waygraph 0.15.3 → 0.15.4

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

@@ -1,4 +1,6 @@
 import { AutoSession, type AutoSessionInit, type SessionSnapshot, type InspectDomOptions, type DomSnapshot, type TraceStep, type ApplyPathResult, type ConsoleLogEntry, type StorageSnapshot, type StubFileKind } from "./auto-session.js";
+import type { PilotHighlightFixtures } from "./pilot-overlay.js";
+export type { PilotHighlightFixtures, PilotFixtureRing } from "./pilot-overlay.js";
 export interface SessionMeta {
     sessionId: string;
     socketPath: string;
@@ -43,6 +45,15 @@ export type StorageResponse = ({
     error: string;
 };
 export type ReachResponse = ApplyPathResult;
+export type HighlightResponse = {
+    ok: true;
+    painted: number;
+    missing: string[];
+    snapshot: SessionSnapshot;
+} | {
+    ok: false;
+    error: string;
+};
 /**
  * Client-side: sends one request to a running session and returns its
  * response. Reports a stale/unreachable session as an error within
@@ -94,6 +105,9 @@ export declare function requestSession(projectDir: string, sessionId: string, re
     op: "reach";
     checkpoint: string;
 }, timeoutMs?: number): Promise<ReachResponse>;
+export declare function requestSession(projectDir: string, sessionId: string, request: {
+    op: "highlight";
+} & PilotHighlightFixtures, timeoutMs?: number): Promise<HighlightResponse>;
 /**
  * Server-side: runs `session` behind a unix socket at
  * `.waygraph-auto/<sessionId>.sock`, writing session metadata only once the

package/dist/auto-session-ipc.js

@@ -235,6 +235,10 @@ export async function serveSession(session, projectDir, sessionId, headless = tr
                 else if (request.op === "resync") {
                     response = await session.resync();
                 }
+                else if (request.op === "highlight") {
+                    const { op: _op, ...fixtures } = request;
+                    response = await session.applyHighlight(fixtures);
+                }
                 else {
                     response = { ok: false, error: `unknown op "${request.op}"` };
                 }

package/dist/auto-session.d.ts

@@ -1,6 +1,7 @@
 import { type BlockEntry, type ExploreMenu } from "./auto-explore.js";
 import { type PickResult } from "./auto-explore-run.js";
 import { type StubPhaseResult } from "./highlights.js";
+import type { PilotHighlightFixtures } from "./pilot-overlay.js";
 export interface SessionSnapshotEdge {
     /** 1-based, matching the numbers a human/agent picks by (same as printCliMenu). */
     index: number;
@@ -299,6 +300,20 @@ export declare class AutoSession {
     rawUpload(selector: string, stub: StubFileKind | {
         filePath: string;
     }): Promise<ApplyPickResult>;
+    /**
+     * Agent-sent highlight fixtures (rings + optional todos) on the live page -
+     * the Pilot equivalent of Block `stubBefore` narration in `waygraph demo`.
+     * Does not run a Block; paint-only. Missing selectors are reported, not fatal.
+     */
+    applyHighlight(fixtures: PilotHighlightFixtures): Promise<{
+        ok: true;
+        painted: number;
+        missing: string[];
+        snapshot: SessionSnapshot;
+    } | {
+        ok: false;
+        error: string;
+    }>;
     /**
      * Runs a whole multi-step route to `targetCheckpoint` in one call, instead
      * of an agent hand-picking one index at a time across many separate

package/dist/auto-session.js

@@ -5,7 +5,7 @@ import { buildExploreContext, buildExploreMenu, } from "./auto-explore.js";
 import { ensureLivePage, detectHere, seedDefaultMem, ensureMem, runOneBlock, resolveBaseUrl, } from "./auto-explore-run.js";
 import { runStubPhase } from "./highlights.js";
 import { findBlockPathDetailed } from "./graph.js";
-import { updatePilotOverlay, showPilotActivity, showPilotVision } from "./pilot-overlay.js";
+import { updatePilotOverlay, showPilotActivity, showPilotVision, showPilotFixtures } from "./pilot-overlay.js";
 /** True when a stub-phase result actually carries authored content worth keeping. */
 function stubPhaseHasContent(r) {
     return (Object.keys(r.highlights).length > 0 ||
@@ -670,6 +670,39 @@ export class AutoSession {
             quit: false,
         };
     }
+    /**
+     * Agent-sent highlight fixtures (rings + optional todos) on the live page -
+     * the Pilot equivalent of Block `stubBefore` narration in `waygraph demo`.
+     * Does not run a Block; paint-only. Missing selectors are reported, not fatal.
+     */
+    async applyHighlight(fixtures) {
+        this.page = await ensureLivePage(this.context, this.page, this.startUrl);
+        const label = fixtures.clear === true
+            ? "clear fixtures"
+            : `${fixtures.rings?.length ?? 0} ring(s)` +
+                (fixtures.todos?.length ? `, ${fixtures.todos.length} todo(s)` : "");
+        await showPilotActivity(this.page, `Highlight: ${label}`);
+        try {
+            const { painted, missing } = await showPilotFixtures(this.page, fixtures);
+            const menu = await this.currentMenu();
+            this.lastRunNote = fixtures.clear
+                ? "highlight cleared"
+                : `highlight painted ${painted}` +
+                    (missing.length ? ` (missing: ${missing.join(", ")})` : "");
+            return {
+                ok: true,
+                painted,
+                missing,
+                snapshot: buildSessionSnapshot(menu, this.library.byName, this.here, this.lastRunNote),
+            };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: `highlight failed - ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
     /**
      * Runs a whole multi-step route to `targetCheckpoint` in one call, instead
      * of an agent hand-picking one index at a time across many separate

package/dist/cli.js

@@ -7006,6 +7006,13 @@ Primary (less is more):
                                            --non-headless session someone is co-driving);
                                            send/reach never do this on their own, since they
                                            only re-detect when the position is already unknown
+  waygraph auto highlight <sessionId> '<json>'
+                                           Paint agent highlight fixtures on the live page
+                                           (rings + optional todos). Same visual language as
+                                           Block stubBefore in demo. JSON: rings[{selector,
+                                           label,tone?,size?,weight?}], todos[], todoIndex?,
+                                           todoTitle?, holdMs? (0=until next), clear:true.
+                                           Missing selectors listed in response, not fatal.
   waygraph pilot start                     Bootstrap for an agent: starts a --detach session
                                            (same as auto --cli --detach) AND reads back the
                                            whole project's Block graph (same as waygraph
@@ -7468,7 +7475,8 @@ Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
                     args[1] === "goto" ||
                     args[1] === "reload" ||
                     args[1] === "reach" ||
-                    args[1] === "resync")) {
+                    args[1] === "resync" ||
+                    args[1] === "highlight")) {
                 const sub = args[1];
                 const sessionId = args[2];
                 if (!sessionId) {
@@ -7670,6 +7678,34 @@ Agents shipped: waygraph-planner, waygraph-author, waygraph-healer.
                         process.exitCode = 1;
                     break;
                 }
+                if (sub === "highlight") {
+                    const raw = args[3];
+                    if (raw === undefined) {
+                        console.error('waygraph auto highlight: usage: waygraph auto highlight <sessionId> \'{"rings":[{"selector":"#x","label":"X"}]}\'');
+                        process.exit(1);
+                    }
+                    let fixtures;
+                    try {
+                        fixtures = JSON.parse(raw);
+                    }
+                    catch {
+                        console.error("waygraph auto highlight: body must be valid JSON");
+                        process.exit(1);
+                    }
+                    if (fixtures.op !== undefined && fixtures.op !== "highlight") {
+                        console.error('waygraph auto highlight: do not set "op" (or set it to "highlight")');
+                        process.exit(1);
+                    }
+                    const { op: _ignore, ...rest } = fixtures;
+                    const res = await requestSession(proj, sessionId, {
+                        op: "highlight",
+                        ...rest,
+                    });
+                    console.log(JSON.stringify(res));
+                    if (!res.ok)
+                        process.exitCode = 1;
+                    break;
+                }
                 const res = await requestSession(proj, sessionId, { op: "status" });
                 console.log(JSON.stringify(res));
                 if (!res.ok)

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/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/package.json

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

package/templates/skills/waygraph-blind-pilot.skill.md

@@ -25,7 +25,8 @@ permanent, reusable, typed coverage instead of leaving nothing behind.
    (`(group)/<page-slug>/page.block.ts` + `nav.block.ts` + `methods/*.block.ts` + one `*.sel.ts`)
    so the result becomes part of the Waygraph Map, not a scattered one-off file.
 4. `auto reload <sessionId>` to pick up the newly-written Block(s) without restarting.
-5. Run the new Block for real via `auto send` - prove it works before moving to the next
+5. Optionally narrate for a headful watcher: `auto highlight <sessionId> '{"rings":[...],"todos":[...]}'`
+6. Run the new Block for real via `auto send` - prove it works before moving to the next
    pattern, exactly like any other real Block.
 6. Ask the user a clarifying question only when something genuinely can't be resolved from
    the DOM alone (is this instance local or published? does a downstream integration exist?)

package/templates/skills/waygraph-pilot.skill.md

@@ -16,12 +16,29 @@ waygraph pilot start                      # bootstraps: {sessionId, socketPath,
 waygraph auto status <sessionId>          # re-read the live menu, no side effects
 waygraph auto send <sessionId> "<pick>"   # run exactly one Block (by menu index or name)
 waygraph auto reach <sessionId> <Checkpoint>  # path-find + run a whole route in one call
+waygraph auto highlight <sessionId> '<json>'  # paint rings/todos on the live page (agent fixtures)
 ```
 
 `graph` in `pilot start`'s response is the **whole project's** Block/Checkpoint graph, not
 just what's reachable from here - use it to plan several steps ahead before you start
 sending picks.
 
+## Highlight fixtures (agent-sent narration)
+
+Block `stubBefore` / `withHighlightFixtures` only paint in `waygraph demo`. In Pilot they
+land in `auto trace` as metadata but do **not** draw on the page. When a human is watching
+a headful session (or you want to narrate intent before a send), paint yourself:
+
+```
+waygraph auto highlight <sessionId> '{"rings":[{"selector":"#user-name","label":"Username","tone":"planned"},{"selector":"#password","label":"Password","tone":"info"}],"todos":["Fill username","Fill password","Submit"],"todoIndex":0,"holdMs":0}'
+waygraph auto highlight <sessionId> '{"clear":true}'
+```
+
+- `tone`: `planned` (purple, default) | `auto` | `info` | `warning` | `danger` | `success` (pilot `orange` is for `auto dom` vision only)
+- `holdMs`: ms to keep fixtures; `0` = until the next highlight / clear (default 12000)
+- Missing selectors are listed in the JSON response (`missing`) - not a hard failure
+- Does not replace `auto send` - paint, then run the real Block
+
 ## Rule 1: run real Blocks, not raw primitives
 
 Default action is always `auto send`/`auto reach` (a real Block). `auto dom/click/type/

package/examples/saucedemo/.waygraph-auto/0b1f5b26.json

@@ -1,8 +0,0 @@
-{
-  "sessionId": "0b1f5b26",
-  "socketPath": "/tmp/waygraph-auto/0b1f5b26.sock",
-  "pid": 1136773,
-  "projectDir": "/home/dan/Desktop/Work/zsign/services/waygraph/examples/saucedemo",
-  "startedAt": "2026-09-20T18:04:00.000Z",
-  "headless": false
-}