waygraph 0.15.2 → 0.15.4

package/dist/engine.js

@@ -811,52 +811,108 @@ export class MapBuilder {
     engine;
     steps;
     homeOrigin;
-    constructor(engine, steps, homeOrigin) {
+    ff;
+    constructor(engine, steps, homeOrigin, ff = null) {
         this.engine = engine;
         this.steps = steps;
         this.homeOrigin = homeOrigin;
+        this.ff = ff;
     }
     /** @internal - use `engine.map()` or the standalone `map()` export. */
     static begin(engine, homeOrigin) {
-        return new MapBuilder(engine, [], homeOrigin);
+        return new MapBuilder(engine, [], homeOrigin, null);
     }
     /** Readable chain-opener - mirrors `defineFlow`'s leading `start` sentinel. Returns `this` unchanged; entirely optional. */
     start() {
         return this;
     }
+    /**
+     * Open a fast-forward window - steps until {@link ffEnd} collapse into one
+     * opaque `fastForwardComposeBlock` (blitz theater). Kind/salt checks still
+     * run on each inner step as it is added.
+     */
+    ffStart(name) {
+        if (this.ff) {
+            throw new Error(`Waygraph map: .ffStart() while already inside "${this.ff.name}" - call .ffEnd() first`);
+        }
+        const ffName = typeof name === "string" && name.trim()
+            ? name.trim()
+            : `ff-${this.steps.length + 1}`;
+        return new MapBuilder(this.engine, this.steps, this.homeOrigin, {
+            name: ffName,
+            buffer: [],
+        });
+    }
+    /**
+     * Close the current fast-forward window and append one FFCompose step.
+     * Throws if empty or if {@link ffStart} was never opened.
+     */
+    ffEnd() {
+        if (!this.ff) {
+            throw new Error("Waygraph map: .ffEnd() with no open .ffStart()");
+        }
+        if (this.ff.buffer.length === 0) {
+            throw new Error(`Waygraph map: .ffEnd() for "${this.ff.name}" has no steps - add .gotoPage/.method/… inside the window`);
+        }
+        const composed = fastForwardComposeBlock(this.ff.name, 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.ff.buffer);
+        return new MapBuilder(this.engine, [...this.steps, composed], this.homeOrigin, null);
+    }
+    appendStep(block) {
+        if (this.ff) {
+            return new MapBuilder(this.engine, this.steps, this.homeOrigin, {
+                name: this.ff.name,
+                buffer: [...this.ff.buffer, block],
+            });
+        }
+        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin, null);
+    }
     /**
      * Appends an internal navigation/page-arrival step - requires a Block from
      * `defineNavBlock`/`defineMemNavBlock`/`definePageBlock`. Throws if given
      * anything else, including a `homeOrigin`-mismatched static `url`.
+     * Compile-time: {@link NavBlock} or {@link PageBlock} only (not Assert/Method).
      */
     gotoPage(block) {
         assertMapKind(block, ["nav", "page"], "gotoPage");
         assertMapOrigin(block, this.homeOrigin, "internal", "gotoPage");
-        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin);
+        return this.appendStep(block);
     }
     /**
      * Appends a genuinely cross-origin navigation step (e.g. `(external)/`
      * Blocks in the Waygraph Map convention: mailpit, maildrop.cc) - same
      * kind requirement as {@link gotoPage}, plus the inverse `homeOrigin` check.
+     * Compile-time: {@link NavBlock} or {@link PageBlock} only.
      */
     gotoExternal(block) {
         assertMapKind(block, ["nav", "page"], "gotoExternal");
         assertMapOrigin(block, this.homeOrigin, "external", "gotoExternal");
-        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin);
+        return this.appendStep(block);
     }
-    /** Appends a self-loop verification step - requires a Block from `defineAssertBlock`. */
+    /**
+     * Appends a self-loop verification step - requires a Block from
+     * `defineAssertBlock`. Compile-time: {@link AssertBlock} only (not `.method()`).
+     */
     assert(block) {
         assertMapKind(block, ["assert"], "assert");
-        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin);
+        return this.appendStep(block);
     }
     /**
      * Appends a non-navigating page action (submit, upload, add/remove an
      * instance) - requires a Block from `defineMethodBlock`/`defineActionBlock`/
      * `defineEffectBlock`/`defineMemEffectBlock`.
+     * Compile-time: {@link MethodBlock} or {@link EffectBlock} only - Assert
+     * Blocks must use `.assert()`. Runtime also rejects `__waygraphKind =
+     * "assert"` (those still carry method salt from the factory internals).
      */
     method(block) {
+        if (mapKindOf(block) === "assert") {
+            throw new Error(`Waygraph map: .method("${block.name}") got a defineAssertBlock - use .assert() for ` +
+                "self-loop verify steps (Assert Blocks share method salt internally but are not methods).");
+        }
         assertMapSalt(block, ["method", "effect"], "method");
-        return new MapBuilder(this.engine, [...this.steps, block], this.homeOrigin);
+        return this.appendStep(block);
     }
     /**
      * Finalizes this chain into a real, runnable {@link Flow} - same object
@@ -867,6 +923,9 @@ export class MapBuilder {
      * isn't a flow.
      */
     end() {
+        if (this.ff) {
+            throw new Error(`Waygraph map: .end() while .ffStart("${this.ff.name}") is still open - call .ffEnd() first`);
+        }
         if (this.steps.length === 0) {
             throw new Error("Waygraph map: .end() called with zero steps - add at least one .gotoPage()/.gotoExternal()/" +
                 ".assert()/.method() before .end()");
@@ -937,8 +996,38 @@ function stripMethods(block) {
         ...(block.next ? { next: block.next } : {}),
         ...(block.requires ? { requires: block.requires } : {}),
         ...(block.routes ? { routes: block.routes } : {}),
+        ...(block.instanceOptions ? { instanceOptions: block.instanceOptions } : {}),
     };
 }
+/** Copy non-enumerable waygraph markers so decorate/withVerify keep map() kind checks. */
+function copyWaygraphRuntime(from, to) {
+    for (const key of [
+        "__waygraphKind",
+        "__waygraphSalt",
+        "__waygraphNavUrl",
+        "__waygraphNavClick",
+    ]) {
+        const desc = Object.getOwnPropertyDescriptor(from, key);
+        if (!desc)
+            continue;
+        // Re-define as configurable so later decorate chains can copy again
+        // (factory markers are non-configurable on the original).
+        Object.defineProperty(to, key, {
+            value: desc.value,
+            enumerable: false,
+            writable: false,
+            configurable: true,
+        });
+    }
+    const ff = from.fastForward;
+    if (ff === true) {
+        to.fastForward = true;
+    }
+    const pace = from.demoPace;
+    if (pace !== undefined) {
+        to.demoPace = pace;
+    }
+}
 /**
  * Builds a Block with `withVerify`/`modVerify`/`modVerifyAll` attached as
  * methods - `LoginBlock.withVerify([...])`, discoverable by typing
@@ -958,12 +1047,19 @@ export function defineBlock(base) {
         ...(base.routes ? { routes: base.routes } : {}),
         ...(base.instanceOptions ? { instanceOptions: base.instanceOptions } : {}),
     };
-    return {
+    // Methods must close over `defined` (this object), not `plain` - factories
+    // attach __waygraphKind/__waygraphSalt on the returned object after
+    // defineBlock returns; decorate/withVerify need those markers.
+    const defined = {
         ...plain,
-        withVerify: (verify) => withVerify(plain, verify),
-        modVerify: (nameOrIndex, newCheck) => modVerify(plain, nameOrIndex, newCheck),
-        modVerifyAll: (patches) => modVerifyAll(plain, patches),
+        withVerify: (verify) => withVerify(defined, verify),
+        modVerify: (nameOrIndex, newCheck) => modVerify(defined, nameOrIndex, newCheck),
+        modVerifyAll: (patches) => modVerifyAll(defined, patches),
+        stubBefore: (stub) => withStubBefore(defined, stub),
+        stubAfter: (stub) => withStubAfter(defined, stub),
+        stubOnError: (stub) => withStubOnError(defined, stub),
     };
+    return defined;
 }
 /**
  * Builds a {@link NavBlock}. The generated `act()` is always exactly
@@ -1120,6 +1216,8 @@ export function defineAssertBlock(options) {
         enumerable: false,
         configurable: false,
     });
+    // Brand for map().assert() - distinct from MethodBlock so .method(assert)
+    // is a compile error even though runtime still carries method salt.
     return built;
 }
 function resolvePageMethods(methods) {
@@ -1326,7 +1424,64 @@ export async function locate(page, library, options) {
  */
 export function withVerify(block, verify) {
     const base = stripMethods(block);
-    return defineBlock({ ...base, instruction: { ...base.instruction, verify } });
+    const next = defineBlock({ ...base, instruction: { ...base.instruction, verify } });
+    copyWaygraphRuntime(block, next);
+    return next;
+}
+function isHighlightStubPhase(v) {
+    return !!v && typeof v === "object" && !Array.isArray(v);
+}
+/** Run a prior stub (fn or slot map) into an open ctx so decorate can chain. */
+async function applyStubIntoCtx(raw, ctx) {
+    if (raw === undefined)
+        return;
+    if (typeof raw === "function") {
+        const ret = await raw(ctx);
+        if (isHighlightStubPhase(ret)) {
+            for (const [id, stub] of Object.entries(ret)) {
+                if (stub)
+                    ctx.ring(id, stub);
+            }
+        }
+        return;
+    }
+    if (isHighlightStubPhase(raw)) {
+        for (const [id, stub] of Object.entries(raw)) {
+            if (stub)
+                ctx.ring(id, stub);
+        }
+    }
+}
+function withStubPhase(block, phase, stub) {
+    const base = stripMethods(block);
+    const instr = base.instruction;
+    const prev = instr[phase];
+    const chained = async (ctx) => {
+        await applyStubIntoCtx(prev, ctx);
+        await applyStubIntoCtx(stub, ctx);
+    };
+    const next = defineBlock({
+        ...base,
+        instruction: { ...base.instruction, [phase]: chained },
+    });
+    copyWaygraphRuntime(block, next);
+    return next;
+}
+/**
+ * Attach / chain a stubBefore lifecycle on a Block. Prefer
+ * `(ctx) => { ctx.ring(...); const x = ctx.mem?.get(Key); }`.
+ * @example FillUsernameBlock.stubBefore((ctx) => { ctx.ring("username", { ... }) })
+ */
+export function withStubBefore(block, stub) {
+    return withStubPhase(block, "stubBefore", stub);
+}
+/** @see {@link withStubBefore} */
+export function withStubAfter(block, stub) {
+    return withStubPhase(block, "stubAfter", stub);
+}
+/** @see {@link withStubBefore} */
+export function withStubOnError(block, stub) {
+    return withStubPhase(block, "stubOnError", stub);
 }
 /**
  * Replaces one Trait inside `block`'s verify list, leaving every other check
@@ -1371,5 +1526,7 @@ export function modVerify(block, nameOrIndex, newCheck) {
  * same fail-loud-on-unknown-name behavior holds for every entry.
  */
 export function modVerifyAll(block, patches) {
-    return Object.entries(patches).reduce((current, [name, newCheck]) => modVerify(current, name, newCheck), defineBlock(stripMethods(block)));
+    const seed = defineBlock(stripMethods(block));
+    copyWaygraphRuntime(block, seed);
+    return Object.entries(patches).reduce((current, [name, newCheck]) => modVerify(current, name, newCheck), seed);
 }

package/dist/highlights.d.ts

@@ -13,6 +13,7 @@
  * before advancing is authored the same way on stubs, flow fixtures, and slides.
  */
 import type { Block, Checkpoint } from "./types.js";
+import type { MemPage } from "./mem-page.js";
 /** Shared dwell fields on stubs, fixtures, and yap slides. */
 export type FixtureDurationFields = {
     /**
@@ -313,6 +314,12 @@ export type HighlightStubPhase = Record<string, WaygraphHighlightStub>;
  * }
  */
 export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
+    /**
+     * Live Mem for this run - same store `act`/`observe` read. Prefer this over
+     * closing over outer scope or inventing parallel fixture bags.
+     * Undefined only if the caller ran a stub phase without passing mem (tests).
+     */
+    readonly mem: MemPage | undefined;
     /** Present after resolve (stubAfter). Undefined for stubBefore. */
     readonly out: Out | undefined;
     /** Present on stubOnError when the step threw. */
@@ -636,6 +643,7 @@ export declare function completeSequentialTodoDock(dock: TodoDockState | undefin
 export declare function runStubPhase(block: Block<any, any>, phase: HighlightStubPhaseName, opts?: {
     out?: Checkpoint<string>;
     error?: unknown;
+    mem?: MemPage;
     fixtures?: HighlightFixtureMap;
 }): Promise<StubPhaseResult>;
 /**

package/dist/highlights.js

@@ -795,6 +795,7 @@ export function completeSequentialTodoDock(dock) {
 }
 function createStubCtx(bag, opts) {
     return {
+        mem: opts.mem,
         out: opts.out,
         error: opts.error,
         highlights(slots) {
@@ -1143,6 +1144,7 @@ export async function runStubPhase(block, phase, opts) {
     const ctx = createStubCtx(bag, {
         ...(opts?.out !== undefined ? { out: opts.out } : {}),
         ...(opts?.error !== undefined ? { error: opts.error } : {}),
+        ...(opts?.mem !== undefined ? { mem: opts.mem } : {}),
     });
     const raw = readStubRaw(block, phase);
     if (typeof raw === "function") {

package/dist/index.d.ts

@@ -2,10 +2,10 @@ export type { Checkpoint, Instruction, Block, DefinedBlock, Start, WaygraphInsta
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible, 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, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, defineLayout, map, MapBuilder, } from "./engine.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, 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, 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, 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, AssertBlockOptions, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, Layout, LayoutOptions, MapBuilderOptions, } from "./engine.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";
 export type { WaygraphGraph, WaygraphNode, WaygraphEdge, SkippedBlock, OrphanBlock } from "./graph.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { Trait, urlMatches, textEquals, visible, 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, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, defineLayout, map, MapBuilder, } from "./engine.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, 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, 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 { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";

package/dist/pilot-overlay.d.ts

@@ -52,8 +52,50 @@ export declare function showPilotActivity(page: Page, text: string): Promise<voi
  * raw click/type/upload IS a real Playwright-driven action (`auto` was
  * always documented as meaning exactly that), while a pure `auto dom` read
  * touches nothing, so it gets its own "orange" tone instead.
+ *
+ * For agent-authored multi-ring / todo narration, use {@link showPilotFixtures}
+ * (`auto highlight`) instead - this vision ring is one-shot inspect feedback.
  */
 export declare function showPilotVision(page: Page, selector: string, label: string, tone?: HighlightTone): Promise<void>;
+/** One ring the Pilot agent wants painted (same fields as demo stub rings). */
+export type PilotFixtureRing = {
+    selector: string;
+    label: string;
+    tone?: HighlightTone;
+    size?: "sm" | "md" | "lg";
+    weight?: "normal" | "bold";
+};
+/**
+ * Agent-sent highlight fixtures for a live Pilot / auto session.
+ * Painted by {@link showPilotFixtures}; driven via IPC `op: "highlight"`.
+ */
+export type PilotHighlightFixtures = {
+    /** Replace current fixture rings with these (empty + no todos = clear). */
+    rings?: readonly PilotFixtureRing[];
+    /** Optional floating todo list (demo-dock language, simplified). */
+    todos?: readonly string[];
+    /** 0-based index of the "current" todo row (others before it = done). */
+    todoIndex?: number;
+    /** Optional title above the todo list. */
+    todoTitle?: string;
+    /**
+     * How long fixtures stay visible (ms). `0` = until the next highlight /
+     * clear. Default `12000`. Vision rings (`showPilotVision`) stay separate.
+     */
+    holdMs?: number;
+    /** Drop every agent fixture ring/todo immediately. */
+    clear?: boolean;
+};
+/**
+ * Paint (or clear) agent-authored highlight fixtures on the live page.
+ * Multi-ring + optional todo strip - what Block `stubBefore` does in
+ * `waygraph demo`, available to the Pilot agent without going through demo.
+ * Does not import `cli.ts` (see file header).
+ */
+export declare function showPilotFixtures(page: Page, fixtures: PilotHighlightFixtures): Promise<{
+    painted: number;
+    missing: string[];
+}>;
 /** Minimal shape needed to render the graph tree - matches WaygraphGraph. */
 export interface PilotOverlayGraph {
     nodes: readonly {

package/dist/pilot-overlay.js

@@ -60,6 +60,44 @@ 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 share tone/size CSS with #wg-ring (demo language). */
+.wg-pilot-fx-ring{position:fixed;z-index:2147483645;pointer-events:none;opacity:0;
+  border:3px solid #7C3AED;border-radius:10px;box-sizing:border-box;
+  transition:opacity .12s ease,left .12s,top .12s,width .12s,height .12s;}
+.wg-pilot-fx-ring[data-tone=planned]{border-color:#7C3AED;box-shadow:0 0 0 4px rgba(124,58,237,.16);}
+.wg-pilot-fx-ring[data-tone=auto]{border-color:#9CA3AF;box-shadow:0 0 0 4px rgba(156,163,175,.28);}
+.wg-pilot-fx-ring[data-tone=info]{border-color:#3B82F6;box-shadow:0 0 0 4px rgba(59,130,246,.22);}
+.wg-pilot-fx-ring[data-tone=warning]{border-color:#EAB308;box-shadow:0 0 0 4px rgba(234,179,8,.22);}
+.wg-pilot-fx-ring[data-tone=danger]{border-color:#EF4444;box-shadow:0 0 0 4px rgba(239,68,68,.22);}
+.wg-pilot-fx-ring[data-tone=success]{border-color:#22C55E;box-shadow:0 0 0 4px rgba(34,197,94,.22);}
+.wg-pilot-fx-ring[data-tone=orange]{border-color:#F97316;box-shadow:0 0 0 4px rgba(249,115,22,.22);}
+.wg-pilot-fx-label{position:fixed;z-index:2147483645;pointer-events:none;opacity:0;
+  font:600 12px/1.3 ui-sans-serif,system-ui,sans-serif;padding:5px 9px;border-radius:6px;
+  max-width:min(360px,80vw);box-shadow:0 2px 8px rgba(0,0,0,.25);white-space:nowrap;
+  overflow:hidden;text-overflow:ellipsis;transition:opacity .12s ease;}
+.wg-pilot-fx-label[data-tone=planned]{background:#7C3AED;color:#fff;}
+.wg-pilot-fx-label[data-tone=auto]{background:#6B7280;color:#fff;}
+.wg-pilot-fx-label[data-tone=info]{background:#2563EB;color:#fff;}
+.wg-pilot-fx-label[data-tone=warning]{background:#EAB308;color:#1c1917;}
+.wg-pilot-fx-label[data-tone=danger]{background:#DC2626;color:#fff;}
+.wg-pilot-fx-label[data-tone=success]{background:#16A34A;color:#fff;}
+.wg-pilot-fx-label[data-tone=orange]{background:#EA580C;color:#fff;}
+.wg-pilot-fx-ring[data-size=sm]{border-width:1.5px;border-radius:8px;}
+.wg-pilot-fx-ring[data-size=lg]{border-width:4px;border-radius:12px;}
+.wg-pilot-fx-label[data-size=sm]{font-size:10px;padding:4px 7px;}
+.wg-pilot-fx-label[data-size=lg]{font-size:16px;padding:8px 14px;}
+.wg-pilot-fx-label[data-weight=bold]{font-weight:800;}
+#wg-pilot-fx-todos{
+  position:fixed;z-index:2147483645;top:72px;left:14px;max-width:280px;
+  font:12px/1.4 ui-sans-serif,system-ui,sans-serif;color:#fff;
+  background:rgba(20,10,40,.94);border-radius:10px;padding:10px 12px;
+  box-shadow:0 2px 10px rgba(0,0,0,.3);pointer-events:none;
+}
+#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;}
 ` + WAYGRAPH_RING_CSS;
 /** Idempotent - safe to call before every update, matching narrate mode's own precedent. */
 async function ensureInstalled(page) {
@@ -159,6 +197,9 @@ export async function showPilotActivity(page, text) {
  * raw click/type/upload IS a real Playwright-driven action (`auto` was
  * always documented as meaning exactly that), while a pure `auto dom` read
  * touches nothing, so it gets its own "orange" tone instead.
+ *
+ * For agent-authored multi-ring / todo narration, use {@link showPilotFixtures}
+ * (`auto highlight`) instead - this vision ring is one-shot inspect feedback.
  */
 export async function showPilotVision(page, selector, label, tone = "auto") {
     await ensureInstalled(page);
@@ -211,6 +252,113 @@ export async function showPilotVision(page, selector, label, tone = "auto") {
     }, { selector, label, tone })
         .catch(() => { });
 }
+/**
+ * Paint (or clear) agent-authored highlight fixtures on the live page.
+ * Multi-ring + optional todo strip - what Block `stubBefore` does in
+ * `waygraph demo`, available to the Pilot agent without going through demo.
+ * Does not import `cli.ts` (see file header).
+ */
+export async function showPilotFixtures(page, fixtures) {
+    await ensureInstalled(page);
+    const holdMs = fixtures.clear === true
+        ? 0
+        : fixtures.holdMs === undefined
+            ? 12_000
+            : Math.max(0, fixtures.holdMs);
+    const rings = fixtures.clear ? [] : (fixtures.rings ?? []);
+    const todos = fixtures.clear ? [] : (fixtures.todos ?? []);
+    const todoIndex = fixtures.todoIndex ?? 0;
+    const todoTitle = fixtures.todoTitle ?? "Plan";
+    return page
+        .evaluate(({ rings, todos, todoIndex, todoTitle, holdMs }) => {
+        const w = window;
+        if (w.__wgPilotFxHideTimer)
+            clearTimeout(w.__wgPilotFxHideTimer);
+        const clearFx = () => {
+            document.querySelectorAll(".wg-pilot-fx-ring, .wg-pilot-fx-label").forEach((el) => el.remove());
+            document.getElementById("wg-pilot-fx-todos")?.remove();
+        };
+        w.__wgPilotFxClear = clearFx;
+        clearFx();
+        const missing = [];
+        let painted = 0;
+        for (const ring of rings) {
+            const el = document.querySelector(ring.selector);
+            if (!el) {
+                missing.push(ring.selector);
+                continue;
+            }
+            const rect = el.getBoundingClientRect();
+            if (rect.width === 0 && rect.height === 0) {
+                missing.push(ring.selector);
+                continue;
+            }
+            const tone = ring.tone || "planned";
+            const size = ring.size === "sm" || ring.size === "lg" ? ring.size : "md";
+            const weight = ring.weight === "bold" ? "bold" : "normal";
+            const pad = size === "sm" ? 3 : size === "lg" ? 10 : 6;
+            const ringEl = document.createElement("div");
+            ringEl.className = "wg-pilot-fx-ring";
+            ringEl.dataset.tone = tone;
+            ringEl.dataset.size = size;
+            ringEl.style.left = `${rect.left - pad}px`;
+            ringEl.style.top = `${rect.top - pad}px`;
+            ringEl.style.width = `${Math.max(4, rect.width + pad * 2)}px`;
+            ringEl.style.height = `${Math.max(4, rect.height + pad * 2)}px`;
+            ringEl.style.opacity = "1";
+            const labelEl = document.createElement("div");
+            labelEl.className = "wg-pilot-fx-label";
+            labelEl.dataset.tone = tone;
+            labelEl.dataset.size = size;
+            labelEl.dataset.weight = weight;
+            labelEl.textContent = ring.label;
+            labelEl.style.opacity = "1";
+            document.documentElement.appendChild(ringEl);
+            document.documentElement.appendChild(labelEl);
+            const lw = labelEl.offsetWidth;
+            const lh = labelEl.offsetHeight;
+            let labelLeft = rect.left - pad;
+            let labelTop = rect.top - pad + rect.height + pad * 2 + 8;
+            if (labelTop + lh > window.innerHeight - 6)
+                labelTop = rect.top - pad - lh - 8;
+            if (labelTop < 6)
+                labelTop = 6;
+            if (labelLeft + lw > window.innerWidth - 6) {
+                labelLeft = Math.max(6, window.innerWidth - 6 - lw);
+            }
+            if (labelLeft < 6)
+                labelLeft = 6;
+            labelEl.style.left = `${labelLeft}px`;
+            labelEl.style.top = `${labelTop}px`;
+            painted += 1;
+        }
+        if (todos.length > 0) {
+            const dock = document.createElement("div");
+            dock.id = "wg-pilot-fx-todos";
+            const title = document.createElement("div");
+            title.className = "wg-pilot-fx-todo-title";
+            title.textContent = todoTitle;
+            dock.appendChild(title);
+            const ol = document.createElement("ol");
+            todos.forEach((text, i) => {
+                const li = document.createElement("li");
+                li.textContent = text;
+                if (i < todoIndex)
+                    li.className = "wg-pilot-fx-todo-done";
+                else if (i === todoIndex)
+                    li.className = "wg-pilot-fx-todo-now";
+                ol.appendChild(li);
+            });
+            dock.appendChild(ol);
+            document.documentElement.appendChild(dock);
+        }
+        if (holdMs > 0 && (painted > 0 || todos.length > 0)) {
+            w.__wgPilotFxHideTimer = setTimeout(() => clearFx(), holdMs);
+        }
+        return { painted, missing };
+    }, { rings, todos, todoIndex, todoTitle, holdMs })
+        .catch(() => ({ painted: 0, missing: rings.map((r) => r.selector) }));
+}
 /**
  * Refreshes the badge text and the (possibly-collapsed) panel's two tabs
  * ("Here" - current live menu; "All nodes" - whole project graph as a

package/dist/types.d.ts

@@ -276,6 +276,23 @@ export type DefinedBlock<In extends Checkpoint<string>, Out extends Checkpoint<s
     withVerify(verify: Trait[] | ((out: Out) => Trait[])): DefinedBlock<In, Out>;
     modVerify(nameOrIndex: string | number, newCheck: Trait["check"] | Trait): DefinedBlock<In, Out>;
     modVerifyAll(patches: Record<string, Trait["check"] | Trait>): DefinedBlock<In, Out>;
+    /**
+     * Demo narration before act - prefer `(ctx) => { ctx.ring(...); ctx.mem?.get(...) }`.
+     * Chains after any existing stubBefore on this Block (library then call-site).
+     * Overloads keep `ctx` typed when the author passes a lifecycle function
+     * (a single union parameter would make the callback param `any`).
+     */
+    stubBefore(stub: import("./highlights.js").HighlightStubPhase): DefinedBlock<In, Out>;
+    stubBefore(stub: import("./highlights.js").StubLifecycleFn<Out>): DefinedBlock<In, Out>;
+    stubBefore(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): DefinedBlock<In, Out>;
+    /** Demo narration after resolve. Prefer ctx callbacks over slot-map objects. */
+    stubAfter(stub: import("./highlights.js").HighlightStubPhase): DefinedBlock<In, Out>;
+    stubAfter(stub: import("./highlights.js").StubLifecycleFn<Out>): DefinedBlock<In, Out>;
+    stubAfter(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): DefinedBlock<In, Out>;
+    /** Demo narration when the step fails / expected-failure path. */
+    stubOnError(stub: import("./highlights.js").HighlightStubPhase): DefinedBlock<In, Out>;
+    stubOnError(stub: import("./highlights.js").StubLifecycleFn<Out>): DefinedBlock<In, Out>;
+    stubOnError(stub: (out: Out) => import("./highlights.js").HighlightStubPhase): DefinedBlock<In, Out>;
 };
 /**
  * Structural (not imported) twin of `engine.ts`'s `Layout` - `types.ts` sits

package/examples/saucedemo/.waygraph-auto/49edc885.log

@@ -0,0 +1,4 @@
+(node:218615) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)
+(node:218615) Warning: The 'NO_COLOR' env is ignored due to the 'FORCE_COLOR' env being set.
+(Use `node --trace-warnings ...` to show where the warning was created)

package/examples/saucedemo/src/blocks/saucedemo-web/checkout-step-two/methods/finish-order.method.block.ts

@@ -1,4 +1,4 @@
-import { defineMethodBlock, checkpoint, Trait, narrate } from "waygraph";
+import { defineMethodBlock, checkpoint, Trait, narrate, type StubCtx } from "waygraph";
 import type { CheckoutOverviewPage, OrderComplete } from "../../../../states/checkout.states.js";
 import { CheckoutOverviewSel } from "./checkout-overview.sel.js";
 
@@ -8,6 +8,7 @@ import { CheckoutOverviewSel } from "./checkout-overview.sel.js";
  * Route: saucedemo-web/checkout-step-two/methods/  (= /checkout-step-two.html)
  *
  * Places the order on the overview page - form/finish click, not a NavBlock.
+ * Stubs use open ctx lifecycles (preferred) - not static slot maps.
  */
 export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderComplete>({
   name: "finish-order",
@@ -19,23 +20,23 @@ export const FinishOrderBlock = defineMethodBlock<CheckoutOverviewPage, OrderCom
     },
     resolve: () => checkpoint("OrderComplete"),
     verify: [Trait.text(CheckoutOverviewSel.completeHeader, "Thank you for your order!")],
-    stubBefore: {
-      finish: {
+    stubBefore: (ctx: StubCtx) => {
+      ctx.ring("finish", {
         selector: CheckoutOverviewSel.finishBtn,
         label: "Finish",
         detail: "tone: warning (yellow) - place order",
         tone: "warning",
         weight: "bold",
-      },
+      });
     },
-    stubAfter: {
-      thanks: {
+    stubAfter: (ctx: StubCtx) => {
+      ctx.ring("thanks", {
         selector: CheckoutOverviewSel.completeHeader,
         label: "Order confirmed",
         detail: "tone: success (green) - thank you!",
         tone: "success",
         duration: true,
-      },
+      });
     },
     // Shown AFTER act (order already placed) - selectors must match the
     // completion page, not #finish on the overview.