waygraph 0.15.36 → 0.15.38

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

@@ -72,6 +72,8 @@ export declare class AutoSession {
      * fallback when a Block's own `resolve()` doesn't set `__state` - same
      * behavior `applyPick` always had, just factored out, not changed.
      */
+    /** Paint + log a Block's authored waygraph overlay fixtures (same as demo does), best-effort. */
+    private paintStubPhase;
     private runNamedBlock;
     /** Applies exactly one pick: runs at most one Block, returns the resulting state. */
     applyPick(raw: string): Promise<ApplyPickResult>;

package/dist/auto-session/session.js

@@ -1,12 +1,13 @@
 // Split out of the former 1,078-line auto-session.ts (see src/ARCHITECTURE.md). Behavior unchanged.
 import { CONSOLE_LOG_MAX_ENTRIES, FULL_MODE_DEFAULT_DEPTH, FULL_MODE_MAX_NODES, FULL_MODE_MAX_TEXT_LENGTH, TRACE_MAX_STEPS, buildSessionSnapshot, parsePick, stubFilePath, stubPhaseHasContent, walkFullDom } from "./helpers.js";
-import { instrumentPilotActions, installPersistentPilotOverlay, showPilotActivity, showPilotFixtures, showPilotVision, updatePilotOverlay } from "../pilot-overlay.js";
+import { instrumentPilotActions, installPersistentPilotOverlay, showPilotActivity, showPilotFixtures, showPilotVision, phaseToOverlayFixtures, describeOverlayFixtures, updatePilotOverlay } from "../pilot-overlay.js";
 import { buildExploreContext, buildExploreMenu } from "../auto-explore.js";
 import { MemPage } from "../mem-page.js";
 import { Engine } from "../engine.js";
 import { detectHere, ensureLivePage, ensureMem, resolveBaseUrl, runOneBlock, seedDefaultMem } from "../auto-explore-run.js";
 import { collectKnownInteractionSelectors, unmappedInteractionsPageScript } from "../coverage-gap.js";
 import { runStubPhase } from "../highlights.js";
+import { verboseLog } from "../verbose-log.js";
 import { findBlockPathDetailed } from "../graph.js";
 /**
  * Non-interactive explore session: same graph/library/mem/browser setup
@@ -328,9 +329,19 @@ export class AutoSession {
      * fallback when a Block's own `resolve()` doesn't set `__state` - same
      * behavior `applyPick` always had, just factored out, not changed.
      */
+    /** Paint + log a Block's authored waygraph overlay fixtures (same as demo does), best-effort. */
+    async paintStubPhase(tag, phase, holdMs) {
+        if (!this.page || !stubPhaseHasContent(phase))
+            return;
+        const fixtures = phaseToOverlayFixtures(phase, holdMs);
+        for (const line of describeOverlayFixtures(tag, fixtures))
+            verboseLog("pilot", line);
+        await showPilotFixtures(this.page, fixtures).catch(() => { });
+    }
     async runNamedBlock(entry, expectedTo, instanceOption) {
         const from = this.here;
         const stubBeforeResult = await runStubPhase(entry.block, "stubBefore");
+        await this.paintStubPhase("stub.before", stubBeforeResult, 6000);
         const stepBase = {
             block: entry.block.name,
             from,
@@ -348,6 +359,7 @@ export class AutoSession {
             this.here = result.__state ?? expectedTo;
             this.lastRunNote = `${entry.block.name} -> ${this.here}`;
             const stubAfterResult = await runStubPhase(entry.block, "stubAfter", { out: result });
+            await this.paintStubPhase("stub.after", stubAfterResult, 6000);
             this.pushTrace({
                 ...stepBase,
                 to: this.here,
@@ -358,6 +370,7 @@ export class AutoSession {
             this.lastRunNote = `${entry.block.name} failed`;
             const message = err instanceof Error ? err.message : String(err);
             const stubOnErrorResult = await runStubPhase(entry.block, "stubOnError", { error: err });
+            await this.paintStubPhase("stub.error", stubOnErrorResult, 8000);
             this.pushTrace({
                 ...stepBase,
                 error: message,
@@ -588,6 +601,8 @@ export class AutoSession {
         // Same bottom-left activity toast as Running (Dom)/(Block) - agent narration.
         await showPilotActivity(this.page, `Highlighting: ${detail}`);
         try {
+            for (const line of describeOverlayFixtures("highlight", fixtures))
+                verboseLog("pilot", line);
             const { painted, missing } = await showPilotFixtures(this.page, fixtures);
             const menu = await this.currentMenu();
             this.lastRunNote = fixtures.clear

package/dist/engine/branch-regression.d.ts

@@ -1,6 +1,7 @@
 import type { Checkpoint } from "../types.js";
 import type { Flow } from "./flow.js";
 import type { RunGraphOptions } from "./run-graph.js";
+import { MemPage } from "../mem-page.js";
 import type { BrowserContext } from "@playwright/test";
 /** One branch reachable from `flow`, possibly several `.branch()` levels deep. */
 export interface BranchEntry {
@@ -13,27 +14,33 @@ export declare function branchRoutes(flow: Flow<any>): ReadonlyMap<string, Flow<
 /**
  * Every branch Flow reachable from `flow`, at any depth, deduped by object identity (the same
  * route Flow reused under two tags is only listed once). Doesn't include `flow` itself - only its
- * `.branch()` continuations.
+ * `.branch()` continuations. Static - doesn't run anything.
  */
 export declare function collectBranchFlows(flow: Flow<any>): BranchEntry[];
-/** Why a branch was skipped instead of run. */
-export type BranchSkipReason = "first Block is not nav/page - this branch needs page state a live run would have reached through its prefix, not its own blocks";
 export interface BranchRunResult {
     path: string;
-    status: "ok" | "failed" | "skipped";
+    status: "ok" | "failed";
     result?: Checkpoint<string>;
     error?: string;
-    reason?: BranchSkipReason;
+}
+export interface RunBranchRegressionOptions extends RunGraphOptions {
+    /**
+     * Default `true`: clone the real session (storageState + current URL) at every branch point, so
+     * every route runs from a genuine copy of the live state, not a fresh page. `false` runs the
+     * whole tree exactly once, through whichever single path the live state actually takes (same as
+     * calling `flow.run()` directly) - can't explore siblings, since the one real page has moved on
+     * once a branch's Blocks run.
+     */
+    cloneSession?: boolean;
 }
 /**
- * Runs every independently-enterable branch of `flow` (one whose own first Block navigates), each
- * with a fresh `MemPage` seeded via {@link seedMemStub} and a fresh page. Branches that assume
- * prior page state (first Block isn't nav/page) are reported as `"skipped"`, not silently run into
- * a confusing failure - see this file's own header for why that's a real, unavoidable limit, not a
- * gap to code around.
+ * Runs every path through `flow`'s `.branch()` tree - by default in a CLONED session per branch
+ * point (see this file's own header), so one branch finishing doesn't consume another's chance to
+ * run. Each explored branch gets its own `MemPage` (via {@link MemPage.clone}, seeded further with
+ * {@link seedMemStub} for anything a route alone requires that the shared prefix didn't already set).
  * @example
  * for (const r of await runBranchRegression(loginFlow, context)) {
- *   console.log(r.path, r.status, r.error ?? r.reason ?? "");
+ *   console.log(r.path, r.status, r.error ?? "");
  * }
  */
-export declare function runBranchRegression(flow: Flow<any>, context: BrowserContext, options?: RunGraphOptions): Promise<BranchRunResult[]>;
+export declare function runBranchRegression(flow: Flow<any>, context: BrowserContext, mem?: MemPage, options?: RunBranchRegressionOptions): Promise<BranchRunResult[]>;

package/dist/engine/branch-regression.js

@@ -1,14 +1,17 @@
 import { MemPage } from "../mem-page.js";
 import { seedMemStub } from "../mem-stub.js";
+function branchInfo(flow) {
+    return flow.__wgBranch;
+}
 /** This Flow's own immediate `.branch()` routes, or `undefined` if it wasn't built by `.branch()`. */
 export function branchRoutes(flow) {
-    const routes = flow.__wgBranchRoutes;
-    return routes ? new Map(Object.entries(routes)) : undefined;
+    const info = branchInfo(flow);
+    return info ? new Map(Object.entries(info.routes)) : undefined;
 }
 /**
  * Every branch Flow reachable from `flow`, at any depth, deduped by object identity (the same
  * route Flow reused under two tags is only listed once). Doesn't include `flow` itself - only its
- * `.branch()` continuations.
+ * `.branch()` continuations. Static - doesn't run anything.
  */
 export function collectBranchFlows(flow) {
     const out = [];
@@ -30,43 +33,85 @@ export function collectBranchFlows(flow) {
     return out;
 }
 /**
- * Runs every independently-enterable branch of `flow` (one whose own first Block navigates), each
- * with a fresh `MemPage` seeded via {@link seedMemStub} and a fresh page. Branches that assume
- * prior page state (first Block isn't nav/page) are reported as `"skipped"`, not silently run into
- * a confusing failure - see this file's own header for why that's a real, unavoidable limit, not a
- * gap to code around.
+ * Runs every path through `flow`'s `.branch()` tree - by default in a CLONED session per branch
+ * point (see this file's own header), so one branch finishing doesn't consume another's chance to
+ * run. Each explored branch gets its own `MemPage` (via {@link MemPage.clone}, seeded further with
+ * {@link seedMemStub} for anything a route alone requires that the shared prefix didn't already set).
  * @example
  * for (const r of await runBranchRegression(loginFlow, context)) {
- *   console.log(r.path, r.status, r.error ?? r.reason ?? "");
+ *   console.log(r.path, r.status, r.error ?? "");
  * }
  */
-export async function runBranchRegression(flow, context, options) {
-    const entries = collectBranchFlows(flow);
+export async function runBranchRegression(flow, context, mem = new MemPage(), options) {
+    const cloneSession = options?.cloneSession ?? true;
     const results = [];
-    for (const entry of entries) {
-        const first = entry.flow.blocks()[0]?.block;
-        const kind = first?.__waygraphKind;
-        if (kind !== "nav" && kind !== "page") {
-            results.push({
-                path: entry.path,
-                status: "skipped",
-                reason: "first Block is not nav/page - this branch needs page state a live run would have reached through its prefix, not its own blocks",
-            });
-            continue;
+    const browser = cloneSession ? context.browser() : null;
+    if (cloneSession && !browser) {
+        throw new Error("Waygraph runBranchRegression: cloneSession needs context.browser() (a persistent context " +
+            "has none) - pass { cloneSession: false } to run the single live path in this context instead.");
+    }
+    /** `entryPage`, when given, is already positioned (cloned session + navigated) - reused as-is,
+     *  never replaced by a fresh `ctx.newPage()` (that would throw away the whole point of cloning). */
+    async function walk(f, ctx, m, path, entryPage) {
+        const info = branchInfo(f);
+        if (!info) {
+            // Leaf: whatever Blocks this route itself adds - run them to completion from the (possibly
+            // cloned, already-positioned) session already in place.
+            seedMemStub(m, f);
+            const page = entryPage ?? (await ctx.newPage());
+            try {
+                const result = await f.run(ctx, m, { ...options, page, closeOnFinish: true });
+                results.push({ path, status: "ok", result: result });
+            }
+            catch (err) {
+                results.push({ path, status: "failed", error: err instanceof Error ? err.message : String(err) });
+            }
+            return;
         }
-        const mem = new MemPage();
-        seedMemStub(mem, entry.flow);
+        seedMemStub(m, info.before);
+        const page = entryPage ?? (await ctx.newPage());
+        let first;
         try {
-            const result = await entry.flow.run(context, mem, { ...options, closeOnFinish: true });
-            results.push({ path: entry.path, status: "ok", result: result });
+            first = (await info.before.run(ctx, m, { ...options, page, closeOnFinish: false }));
         }
         catch (err) {
-            results.push({
-                path: entry.path,
-                status: "failed",
-                error: err instanceof Error ? err.message : String(err),
-            });
+            results.push({ path, status: "failed", error: err instanceof Error ? err.message : String(err) });
+            return;
+        }
+        if (!cloneSession) {
+            // Shared-session mode: only the ONE route the live state actually resolved to is reachable -
+            // the page has already moved past every other tag.
+            const route = info.routes[first.result.__state];
+            const tagPath = path ? `${path} > ${first.result.__state}` : first.result.__state;
+            if (!route) {
+                results.push({ path: tagPath, status: "ok", result: first.result });
+                return;
+            }
+            await walk(route, ctx, m, tagPath, first.page);
+            return;
+        }
+        const url = first.page.url();
+        const storageState = await ctx.storageState();
+        await first.page.close();
+        for (const [tag, route] of Object.entries(info.routes)) {
+            const branchPath = path ? `${path} > ${tag}` : tag;
+            if (!route) {
+                results.push({ path: branchPath, status: "ok", result: { __state: tag } });
+                continue;
+            }
+            const branchContext = await browser.newContext({ storageState });
+            try {
+                const branchPage = await branchContext.newPage();
+                // Best-effort: land back on the same page the prefix ended on before this route's own
+                // Blocks run - restores cookies/localStorage AND which page was loaded, not just auth state.
+                await branchPage.goto(url).catch(() => { });
+                await walk(route, branchContext, m.clone(), branchPath, branchPage);
+            }
+            finally {
+                await branchContext.close();
+            }
         }
     }
+    await walk(flow, context, mem, "");
     return results;
 }

package/dist/engine/engine-class.js

@@ -134,7 +134,7 @@ function buildBranchedFlow(before, routes) {
         }
         return branchFlow.run(context, mem, { ...options, page: first.page, closeOnFinish });
     });
-    const flow = {
+    return {
         resetSession: before.resetSession,
         ...(before.title !== undefined ? { title: before.title } : {}),
         ...(before.expectedFailureReason !== undefined ? { expectedFailureReason: before.expectedFailureReason } : {}),
@@ -142,6 +142,11 @@ function buildBranchedFlow(before, routes) {
         ...(before.demoPace !== undefined ? { demoPace: before.demoPace } : {}),
         ...(before.highlightStyle !== undefined ? { highlightStyle: before.highlightStyle } : {}),
         ...(before.memStub !== undefined ? { memStub: before.memStub } : {}),
+        // Read by branchRoutes()/branchInfo() (branch-regression.ts) - real, ORDINARY (enumerable)
+        // properties, not hidden ones, specifically so a `with*` wrapper's `{ ...flow, ... }` spread
+        // (withSessionReset, withTitle, etc.) carries them through instead of silently dropping them -
+        // the same class of bug branch()'s missing copyWaygraphRuntime call already was.
+        __wgBranch: { before, routes },
         // 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.
@@ -157,10 +162,6 @@ function buildBranchedFlow(before, routes) {
             return buildBranchedFlow(before.modBlockVerify(block, nameOrIndex, newCheck), routes);
         },
     };
-    // Non-enumerable so it doesn't show up on a spread/JSON.stringify of the Flow - read by
-    // branchRoutes()/collectBranchFlows() (branch-regression.ts), not part of the public Flow shape.
-    Object.defineProperty(flow, "__wgBranchRoutes", { value: routes, enumerable: false, configurable: true });
-    return flow;
 }
 /**
  * Fluent builder over {@link Engine.defineFlow} - see `map()`'s own doc

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 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, branchRoutes, collectBranchFlows, runBranchRegression, } from "./engine.js";
-export type { BranchEntry, BranchRunResult, BranchSkipReason } from "./engine/branch-regression.js";
+export type { BranchEntry, BranchRunResult, RunBranchRegressionOptions } from "./engine/branch-regression.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, 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";

package/dist/mem-page.d.ts

@@ -67,4 +67,12 @@ export declare class MemPage {
     setAll<A, B, C, D>(p1: readonly [MemKey<A>, A], p2: readonly [MemKey<B>, B], p3: readonly [MemKey<C>, C], p4: readonly [MemKey<D>, D]): void;
     setAll<A, B, C, D, E>(p1: readonly [MemKey<A>, A], p2: readonly [MemKey<B>, B], p3: readonly [MemKey<C>, C], p4: readonly [MemKey<D>, D], p5: readonly [MemKey<E>, E]): void;
     setAll<A, B, C, D, E, F>(p1: readonly [MemKey<A>, A], p2: readonly [MemKey<B>, B], p3: readonly [MemKey<C>, C], p4: readonly [MemKey<D>, D], p5: readonly [MemKey<E>, E], p6: readonly [MemKey<F>, F]): void;
+    /**
+     * An independent copy of every key currently set - a later `.set()` on either the original or the
+     * clone never touches the other. For branch-session cloning (`runBranchRegression`): each explored
+     * branch gets its own mem, so one branch's writes can't bleed into a sibling that also gets tried
+     * from the same snapshot point. Shallow per value (same as `set()` always was - MemPage never
+     * owned deep-copying the values themselves, only which keys point to which).
+     */
+    clone(): MemPage;
 }

package/dist/mem-page.js

@@ -68,4 +68,18 @@ export class MemPage {
             this.set(k, v);
         }
     }
+    /**
+     * An independent copy of every key currently set - a later `.set()` on either the original or the
+     * clone never touches the other. For branch-session cloning (`runBranchRegression`): each explored
+     * branch gets its own mem, so one branch's writes can't bleed into a sibling that also gets tried
+     * from the same snapshot point. Shallow per value (same as `set()` always was - MemPage never
+     * owned deep-copying the values themselves, only which keys point to which).
+     */
+    clone() {
+        const copy = new MemPage();
+        for (const [k, v] of this.store) {
+            copy.store.set(k, v);
+        }
+        return copy;
+    }
 }

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

@@ -7,3 +7,12 @@ import type { PilotHighlightFixtures } from "./fixtures.js";
  * Not Playwright test fixtures - these describe what the waygraph overlay paints on the page under test.
  */
 export declare function overlayFixturesToPhase(f: PilotHighlightFixtures): Promise<StubPhaseResult>;
+/**
+ * The reverse: a resolved stub phase (what `runStubPhase` returns for a Block's stubBefore/After/OnError)
+ * -> what the Pilot painter takes. Lets `auto/browser/pilot send` paint a Block's authored waygraph overlay
+ * fixtures (rings, todos, device, zoom, title/banner) the way `waygraph demo` does, instead of only recording
+ * them in the trace.
+ */
+export declare function phaseToOverlayFixtures(phase: StubPhaseResult, holdMs?: number): PilotHighlightFixtures;
+/** One verbose line per authored overlay fixture - same wording on every surface so a log reader (or an AI with no eyes) can tell what was painted. */
+export declare function describeOverlayFixtures(tag: string, f: PilotHighlightFixtures): string[];

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

@@ -43,3 +43,63 @@ export async function overlayFixturesToPhase(f) {
     };
     return runStubPhase({ name: "overlay-fixtures", stubBefore: lifecycle }, "stubBefore");
 }
+/**
+ * The reverse: a resolved stub phase (what `runStubPhase` returns for a Block's stubBefore/After/OnError)
+ * -> what the Pilot painter takes. Lets `auto/browser/pilot send` paint a Block's authored waygraph overlay
+ * fixtures (rings, todos, device, zoom, title/banner) the way `waygraph demo` does, instead of only recording
+ * them in the trace.
+ */
+export function phaseToOverlayFixtures(phase, holdMs = 6000) {
+    const items = phase.todoDock?.groups[0]?.items ?? phase.todos;
+    const idx = items.findIndex((t) => t.current) >= 0 ? items.findIndex((t) => t.current) : items.findIndex((t) => !t.done);
+    return {
+        rings: phase.highlights.map((h) => ({
+            selector: h.selector,
+            label: h.label ?? "",
+            ...(h.detail ? { detail: h.detail } : {}),
+            ...(h.tag ? { tag: h.tag } : {}),
+            ...(h.tone ? { tone: h.tone } : {}),
+            ...(h.size ? { size: h.size } : {}),
+            ...(h.weight ? { weight: h.weight } : {}),
+            ...(h.color ? { color: h.color } : {}),
+            ...(h.zoom !== undefined ? { zoom: h.zoom } : {}),
+            ...(h.zoomOut !== undefined ? { zoomOut: h.zoomOut } : {}),
+            ...(h.focus ? { focus: true } : {}),
+        })),
+        ...(phase.todoSync === "set" && items.length
+            ? {
+                todos: items.map((t) => t.text),
+                todoIndex: idx < 0 ? items.length : idx,
+                ...(phase.todoDock?.groups[0]?.title ? { todoTitle: phase.todoDock.groups[0].title } : {}),
+                ...(phase.todoPos ? { todoPos: phase.todoPos } : {}),
+            }
+            : {}),
+        ...(phase.todoDockUi ? { todoDockUi: phase.todoDockUi } : {}),
+        ...(phase.deviceSync === "set" && phase.device ? { device: phase.device } : {}),
+        ...(phase.zoom !== undefined ? { zoom: phase.zoom } : {}),
+        ...(phase.zoomOut !== undefined ? { zoomOut: phase.zoomOut } : {}),
+        ...(phase.title ? { title: phase.title } : {}),
+        ...(phase.titlePos ? { titlePos: phase.titlePos } : {}),
+        ...(phase.bannerUi ? { bannerUi: phase.bannerUi } : {}),
+        holdMs,
+    };
+}
+/** One verbose line per authored overlay fixture - same wording on every surface so a log reader (or an AI with no eyes) can tell what was painted. */
+export function describeOverlayFixtures(tag, f) {
+    const out = [];
+    if (f.title)
+        out.push(`${tag} ctx.title(${JSON.stringify(f.title)})${f.titlePos ? ` pos=${f.titlePos}` : ""}`);
+    if (f.bannerUi)
+        out.push(`${tag} ctx.bannerUi(${JSON.stringify(f.bannerUi)})`);
+    if (f.todos?.length)
+        out.push(`${tag} ctx.todos n=${f.todos.length} index=${f.todoIndex ?? 0}${f.todoPos ? ` pos=${f.todoPos}` : ""}`);
+    if (f.todoDockUi ?? f.todoUi)
+        out.push(`${tag} ctx.todoDockUi(${JSON.stringify(f.todoDockUi ?? f.todoUi)})`);
+    if (f.device)
+        out.push(`${tag} ctx.device(${typeof f.device === "string" ? f.device : f.device.preset ?? "custom"})`);
+    if (f.zoom)
+        out.push(`${tag} ctx.zoom(${f.zoom})`);
+    for (const r of f.rings ?? [])
+        out.push(`${tag} ring ${r.selector} tone=${r.tone ?? "planned"} label=${JSON.stringify(r.label)}`);
+    return out;
+}

package/examples/saucedemo/.waygraph-auto/2b831907.log

@@ -0,0 +1,6 @@
+[21:45:47.529] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[21:45:47.529] waygraph pilot: stub.before ctx.todos n=6 index=0
+[21:45:47.529] waygraph pilot: stub.before ctx.device(mobile)
+[21:45:47.529] waygraph pilot: stub.before ctx.zoom(1.35)
+[21:45:47.529] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[21:45:47.633] waygraph pilot: stub.after ctx.todos n=6 index=1

package/examples/saucedemo/.waygraph-auto/3c1e5fe0.log

@@ -0,0 +1,22 @@
+[21:46:29.741] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[21:46:29.741] waygraph pilot: stub.before ctx.todos n=6 index=0
+[21:46:29.741] waygraph pilot: stub.before ctx.device(mobile)
+[21:46:29.741] waygraph pilot: stub.before ctx.zoom(1.35)
+[21:46:29.741] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[21:46:29.866] waygraph pilot: stub.after ctx.todos n=6 index=1
+[21:46:31.935] waygraph pilot: stub.before ring #password tone=planned label="Password"
+[21:46:31.998] waygraph pilot: stub.after ctx.todos n=6 index=2
+[21:46:33.773] waygraph pilot: stub.before ring #login-button tone=warning label="Login"
+[21:46:33.961] waygraph pilot: stub.after ctx.title("Inventory · landscape")
+[21:46:33.961] waygraph pilot: stub.after ctx.todos n=6 index=3
+[21:46:33.961] waygraph pilot: stub.after ctx.device(mobile)
+[21:46:33.961] waygraph pilot: stub.after ring .inventory_list tone=success label="Product shelf"
+[21:46:37.277] waygraph pilot: stub.before ctx.title("Pick a product · tablet")
+[21:46:37.277] waygraph pilot: stub.before ctx.todos n=6 index=3
+[21:46:37.277] waygraph pilot: stub.before ctx.device(tablet)
+[21:46:37.277] waygraph pilot: stub.before ctx.zoom(1.35)
+[21:46:37.277] waygraph pilot: stub.before ring div.inventory_item:has(button[data-test="add-to-cart-sauce-labs-backpack"], button[data-test="remove-sauce-labs-backpack"]) .inventory_item_name tone=info label="Sauce Labs Backpack"
+[21:46:37.277] waygraph pilot: stub.before ring [data-test="add-to-cart-sauce-labs-backpack"] tone=success label="Add to cart"
+[21:46:37.375] waygraph pilot: stub.after ctx.title("In the cart")
+[21:46:37.376] waygraph pilot: stub.after ctx.todos n=6 index=4
+[21:46:37.376] waygraph pilot: stub.after ring .shopping_cart_badge tone=success label="Cart badge"

package/examples/saucedemo/.waygraph-auto/7b226350.log

@@ -0,0 +1,5 @@
+[21:46:10.717] waygraph pilot: highlight ctx.todos n=3 index=0
+[21:46:10.717] waygraph pilot: highlight ring #user-name tone=planned label="Username"
+[21:46:10.717] waygraph pilot: highlight ring #password tone=info label="Password"
+[21:46:12.774] waygraph pilot: highlight ring #no-such-element-waygraph tone=danger label="Gone"
+[21:46:14.903] waygraph pilot: highlight ring #login-button tone=success label="Login"

package/examples/saucedemo/.waygraph-auto/7effd5b2.log

@@ -0,0 +1,20 @@
+[21:46:24.561] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[21:46:24.562] waygraph pilot: stub.before ctx.todos n=6 index=0
+[21:46:24.562] waygraph pilot: stub.before ctx.device(mobile)
+[21:46:24.562] waygraph pilot: stub.before ctx.zoom(1.35)
+[21:46:24.562] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[21:46:24.751] waygraph pilot: stub.after ctx.todos n=6 index=1
+[21:46:25.895] waygraph pilot: stub.before ring #password tone=planned label="Password"
+[21:46:25.977] waygraph pilot: stub.after ctx.todos n=6 index=2
+[21:46:27.278] waygraph pilot: stub.before ring #login-button tone=warning label="Login"
+[21:46:27.476] waygraph pilot: stub.after ctx.title("Inventory · landscape")
+[21:46:27.476] waygraph pilot: stub.after ctx.todos n=6 index=3
+[21:46:27.476] waygraph pilot: stub.after ctx.device(mobile)
+[21:46:27.476] waygraph pilot: stub.after ring .inventory_list tone=success label="Product shelf"
+[21:46:28.988] waygraph pilot: stub.before ctx.title("Open cart · landscape")
+[21:46:28.988] waygraph pilot: stub.before ctx.todos n=6 index=5
+[21:46:28.988] waygraph pilot: stub.before ctx.device(mobile)
+[21:46:28.988] waygraph pilot: stub.before ctx.zoom(1.4)
+[21:46:28.988] waygraph pilot: stub.before ring .shopping_cart_link tone=planned label="Cart"
+[21:46:29.115] waygraph pilot: stub.after ctx.title("Your cart · desktop")
+[21:46:29.116] waygraph pilot: stub.after ring .cart_item tone=success label="Cart items"

package/examples/saucedemo/.waygraph-auto/9761c4c4.log

@@ -0,0 +1,6 @@
+[21:46:28.846] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[21:46:28.846] waygraph pilot: stub.before ctx.todos n=6 index=0
+[21:46:28.846] waygraph pilot: stub.before ctx.device(mobile)
+[21:46:28.847] waygraph pilot: stub.before ctx.zoom(1.35)
+[21:46:28.847] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[21:46:29.003] waygraph pilot: stub.after ctx.todos n=6 index=1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.36",
+  "version": "0.15.38",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",