waygraph 0.15.32 → 0.15.34

package/dist/engine/core.js

@@ -45,6 +45,11 @@ export function branch(block, routes) {
         },
         routes: routesAsData,
     });
+    // Without this, branch()'s output carried no __waygraphKind/__waygraphSalt at all (defineBlock
+    // never stamps them - factories do, after defineBlock returns), so a branched Block could never
+    // pass MapBuilder's assertMapKind/assertMapSalt checks. Real bug: branching was unusable from the
+    // Waygraph Map, only from a raw runGraph() call.
+    copyWaygraphRuntime(block, routed);
     return routed;
 }
 /**

package/dist/engine/engine-class.d.ts

@@ -269,6 +269,43 @@ export declare class MapBuilder<Out extends Checkpoint<string>> {
     method<NextOut extends Checkpoint<string>>(block: (MethodBlock<Out, NextOut> | EffectBlock<Out, NextOut>) & {
         name: string;
     }): MapBuilder<NextOut>;
+    /**
+     * Branch: run everything added so far, then continue into whichever `routes[tag]` matches the
+     * resolved Checkpoint's tag - same page, same context, same mem. `routes` must cover every tag
+     * of `Out` (a missing one is a compile error, matching {@link branch}'s own exhaustiveness);
+     * `null` means that tag is terminal (the branched Flow just returns that Checkpoint).
+     *
+     * Each non-null route is a function, not a ready-made `Flow` - a fresh Flow always starts at the
+     * special `S` (start) Checkpoint, but a branch's blocks start from the TAG it routes on (e.g.
+     * `LoggedIn`), so the function is handed a brand-new `MapBuilder` already seeded at that exact
+     * Checkpoint to chain `.method()/.gotoPage()/.assert()/.end()` (or another `.branch()`) off of.
+     *
+     * Real gap this fixes: the plain `branch()` helper's `.next` routing is only ever consulted by
+     * `runGraph`'s own graph walk - `defineFlow`/`.end()` compose steps pairwise via `connect()`,
+     * which never looks at `.next` at all, so a Map-built Flow had no way to branch. This method
+     * branches at the Flow level instead: it finalizes the prefix, runs it, and picks the next Flow
+     * itself once the real tag is known - no engine-level routing involved.
+     *
+     * Only the `run(context, mem[, options])` signature is supported - the page must survive across
+     * the branch, and the bare `run(mem, config)` convenience form always closes its own browser
+     * before a tag is even known, so it throws instead of silently reopening a fresh (state-losing) page.
+     *
+     * The route's first Block still sees `input.__state === "__start__"` in `act()`, not the tag that
+     * routed there - `runGraph` seeds every Flow's entry Block that way unconditionally, the same as
+     * any standalone `defineFlow([start, block, end])` already does. Read `page`/`mem`, not `input`,
+     * in `act()` - every real Block in this codebase already follows that convention.
+     *
+     * @example
+     * map({ homeOrigin }).gotoPage(NavCartBlock).branch({
+     *   ItemInCart: (m) => m.method(RemoveFromCartBlock).end(),
+     *   LoggedIn: (m) => m.method(AddToCartBlock).end(),
+     * });
+     */
+    branch<Routes extends {
+        [K in Out["__state"]]: ((m: MapBuilder<Extract<Out, Checkpoint<K>>>) => Flow<any>) | null;
+    }>(routes: Routes): Flow<{
+        [K in keyof Routes & string]: Routes[K] extends (m: any) => Flow<infer R> ? R : Extract<Out, Checkpoint<K>>;
+    }[keyof Routes & string]>;
     /**
      * Finalizes this chain into a real, runnable {@link Flow} - same object
      * `defineFlow` returns, so `withBlockVerify`/`modBlockVerify` and every

package/dist/engine/engine-class.js

@@ -1,5 +1,6 @@
 import { end, start } from "./run-graph.js";
 import { buildFlow } from "./flow.js";
+import { MemPage } from "../mem-page.js";
 import { fastForwardComposeBlock } from "./compose.js";
 /**
  * Holds engine-level configuration shared across every flow defined from it -
@@ -104,6 +105,59 @@ function assertMapOrigin(block, homeOrigin, expect, method) {
             `home origin (${wantOrigin}) - use .gotoPage() for an internal destination.`);
     }
 }
+/**
+ * Builds the `Flow` object `MapBuilder.branch()` returns: run `before`, then dispatch on the
+ * resolved tag into whichever `routes` entry matches (same page/context/mem), or return that
+ * Checkpoint as-is when its route is `null`. Factored out so `withBlockVerify`/`modBlockVerify`
+ * can patch `before` and rebuild the same branched shape, exactly like a plain Flow's own.
+ */
+function buildBranchedFlow(before, routes) {
+    const run = (async (contextOrMem, memOrConfig, options) => {
+        if (contextOrMem instanceof MemPage) {
+            throw new Error("Waygraph map: a .branch()-ed Flow can't run via run(mem, config) - that convenience form " +
+                "always closes its own browser/page before a branch's tag is even known. Call " +
+                "run(context, mem[, options]) instead, keeping the same page across the branch.");
+        }
+        const context = contextOrMem;
+        const mem = memOrConfig;
+        const gotOwnPage = options?.page === undefined;
+        const page = options?.page ?? (await context.newPage());
+        const closeOnFinish = options?.closeOnFinish ?? gotOwnPage;
+        const first = (await before.run(context, mem, { ...options, page, closeOnFinish: false }));
+        const branchFlow = routes[first.result.__state];
+        if (!branchFlow) {
+            if (options?.closeOnFinish === false)
+                return { result: first.result, page: first.page };
+            if (closeOnFinish)
+                await first.page.close();
+            return first.result;
+        }
+        return branchFlow.run(context, mem, { ...options, page: first.page, closeOnFinish });
+    });
+    return {
+        resetSession: before.resetSession,
+        ...(before.title !== undefined ? { title: before.title } : {}),
+        ...(before.expectedFailureReason !== undefined ? { expectedFailureReason: before.expectedFailureReason } : {}),
+        ...(before.highlightFixtures !== undefined ? { highlightFixtures: before.highlightFixtures } : {}),
+        ...(before.demoPace !== undefined ? { demoPace: before.demoPace } : {}),
+        ...(before.highlightStyle !== undefined ? { highlightStyle: before.highlightStyle } : {}),
+        ...(before.memStub !== undefined ? { memStub: before.memStub } : {}),
+        // Static introspection (`waygraph graph`/list): the fixed prefix, plus every branch's own
+        // Blocks prefixed by the tag that leads to them - can't know at analysis time which one a real
+        // run takes, so this shows all of them rather than none.
+        blocks: () => [
+            ...before.blocks(),
+            ...Object.entries(routes).flatMap(([tag, f]) => f ? f.blocks().map((b) => ({ ...b, name: `${tag} -> ${b.name}` })) : []),
+        ],
+        run,
+        withBlockVerify(block, verify) {
+            return buildBranchedFlow(before.withBlockVerify(block, verify), routes);
+        },
+        modBlockVerify(block, nameOrIndex, newCheck) {
+            return buildBranchedFlow(before.modBlockVerify(block, nameOrIndex, newCheck), routes);
+        },
+    };
+}
 /**
  * Fluent builder over {@link Engine.defineFlow} - see `map()`'s own doc
  * comment for why this exists. Each step method is scoped to exactly the
@@ -226,6 +280,50 @@ export class MapBuilder {
         assertMapSalt(block, ["method", "effect"], "method");
         return this.appendStep(block);
     }
+    /**
+     * Branch: run everything added so far, then continue into whichever `routes[tag]` matches the
+     * resolved Checkpoint's tag - same page, same context, same mem. `routes` must cover every tag
+     * of `Out` (a missing one is a compile error, matching {@link branch}'s own exhaustiveness);
+     * `null` means that tag is terminal (the branched Flow just returns that Checkpoint).
+     *
+     * Each non-null route is a function, not a ready-made `Flow` - a fresh Flow always starts at the
+     * special `S` (start) Checkpoint, but a branch's blocks start from the TAG it routes on (e.g.
+     * `LoggedIn`), so the function is handed a brand-new `MapBuilder` already seeded at that exact
+     * Checkpoint to chain `.method()/.gotoPage()/.assert()/.end()` (or another `.branch()`) off of.
+     *
+     * Real gap this fixes: the plain `branch()` helper's `.next` routing is only ever consulted by
+     * `runGraph`'s own graph walk - `defineFlow`/`.end()` compose steps pairwise via `connect()`,
+     * which never looks at `.next` at all, so a Map-built Flow had no way to branch. This method
+     * branches at the Flow level instead: it finalizes the prefix, runs it, and picks the next Flow
+     * itself once the real tag is known - no engine-level routing involved.
+     *
+     * Only the `run(context, mem[, options])` signature is supported - the page must survive across
+     * the branch, and the bare `run(mem, config)` convenience form always closes its own browser
+     * before a tag is even known, so it throws instead of silently reopening a fresh (state-losing) page.
+     *
+     * The route's first Block still sees `input.__state === "__start__"` in `act()`, not the tag that
+     * routed there - `runGraph` seeds every Flow's entry Block that way unconditionally, the same as
+     * any standalone `defineFlow([start, block, end])` already does. Read `page`/`mem`, not `input`,
+     * in `act()` - every real Block in this codebase already follows that convention.
+     *
+     * @example
+     * map({ homeOrigin }).gotoPage(NavCartBlock).branch({
+     *   ItemInCart: (m) => m.method(RemoveFromCartBlock).end(),
+     *   LoggedIn: (m) => m.method(AddToCartBlock).end(),
+     * });
+     */
+    branch(routes) {
+        if (this.steps.length === 0) {
+            throw new Error("Waygraph map: .branch() needs at least one prior step - nothing to branch from. " +
+                "Add .gotoPage()/.gotoExternal()/.method()/.assert() first.");
+        }
+        const before = this.end();
+        const resolvedRoutes = {};
+        for (const [tag, fn] of Object.entries(routes)) {
+            resolvedRoutes[tag] = fn ? fn(new MapBuilder(this.engine, [], this.homeOrigin, null)) : null;
+        }
+        return buildBranchedFlow(before, resolvedRoutes);
+    }
     /**
      * Finalizes this chain into a real, runnable {@link Flow} - same object
      * `defineFlow` returns, so `withBlockVerify`/`modBlockVerify` and every

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,