waygraph 0.15.4 → 0.15.7

package/dist/auto-session.js

@@ -677,11 +677,21 @@ export class AutoSession {
      */
     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}`);
+        const detail = fixtures.clear === true
+            ? "clear"
+            : [
+                fixtures.rings?.length ? `${fixtures.rings.length} ring(s)` : null,
+                fixtures.todos?.length ? `${fixtures.todos.length} todo(s)` : null,
+                fixtures.zoom && fixtures.zoom > 1.001 ? `zoom ${fixtures.zoom}` : null,
+                fixtures.device
+                    ? `device ${typeof fixtures.device === "string" ? fixtures.device : fixtures.device.preset || "custom"}`
+                    : null,
+                fixtures.rings?.some((r) => r.focus) ? "focus" : null,
+            ]
+                .filter(Boolean)
+                .join(", ") || "fixtures";
+        // Same bottom-left activity toast as Running (Dom)/(Block) - agent narration.
+        await showPilotActivity(this.page, `Highlighting: ${detail}`);
         try {
             const { painted, missing } = await showPilotFixtures(this.page, fixtures);
             const menu = await this.currentMenu();

package/dist/pilot-overlay.d.ts

@@ -18,7 +18,7 @@
  */
 import type { Page } from "@playwright/test";
 import type { SessionSnapshot } from "./auto-session.js";
-import { type HighlightTone } from "./highlights.js";
+import { type HighlightTone, type DevicePreset, type DeviceState } from "./highlights.js";
 /**
  * Bottom-left transient toast, separate from the persistent bottom-right
  * badge - real, direct user request: something that visibly flags "a
@@ -61,13 +61,30 @@ export declare function showPilotVision(page: Page, selector: string, label: str
 export type PilotFixtureRing = {
     selector: string;
     label: string;
-    tone?: HighlightTone;
-    size?: "sm" | "md" | "lg";
-    weight?: "normal" | "bold";
+    /** Extra caption line (demo `detail`). */
+    detail?: string;
+    /** Short badge, e.g. AC / BUG / GATE. */
+    tag?: string;
+    /** Any {@link HighlightTone} or alias (`error`/`blue`/…). Normalized on paint. */
+    tone?: HighlightTone | string;
+    size?: "sm" | "md" | "lg" | string;
+    weight?: "normal" | "bold" | string;
+    /** Caption text color (CSS). Overrides tone label color when set. */
+    color?: string;
+    /**
+     * Camera zoom while this ring is up (demo parity: scroll + zoom badge;
+     * does not CSS-scale the page). Typical `1.25`..`2`.
+     */
+    zoom?: number;
+    /** When false, keep zoom after this paint / holdMs. Default true. */
+    zoomOut?: boolean;
+    /** Spotlight: dim the rest of the page around this target. */
+    focus?: boolean;
 };
 /**
  * Agent-sent highlight fixtures for a live Pilot / auto session.
  * Painted by {@link showPilotFixtures}; driven via IPC `op: "highlight"`.
+ * Mirrors demo stub surface: rings, todos, zoom, focus, device.
  */
 export type PilotHighlightFixtures = {
     /** Replace current fixture rings with these (empty + no todos = clear). */
@@ -78,18 +95,36 @@ export type PilotHighlightFixtures = {
     todoIndex?: number;
     /** Optional title above the todo list. */
     todoTitle?: string;
+    /** Todo dock side. Default `right`. */
+    todoPos?: "left" | "right";
     /**
      * How long fixtures stay visible (ms). `0` = until the next highlight /
-     * clear. Default `12000`. Vision rings (`showPilotVision`) stay separate.
+     * clear. Default `30000` (30s) unless specified.
      */
     holdMs?: number;
-    /** Drop every agent fixture ring/todo immediately. */
+    /**
+     * Camera zoom toward a selector (demo parity: scrollIntoView + zoom badge).
+     * Defaults the zoom target to {@link zoomSelector}, else the last ring's
+     * selector (or a ring that sets its own `zoom`). Cleared on `clear: true`
+     * or when holdMs expires (if zoomOut).
+     */
+    zoom?: number;
+    /** Element to zoom toward when {@link zoom} is set (defaults to last ring). */
+    zoomSelector?: string;
+    /** When false, keep zoom after fixtures clear/expire. Default true. */
+    zoomOut?: boolean;
+    /**
+     * Viewport / device fixture (`mobile` | `tablet` | `desktop`, or a full
+     * {@link DeviceState}). Applied via Playwright `setViewportSize`.
+     */
+    device?: DevicePreset | DeviceState;
+    /** Drop every agent fixture ring/todo/focus/zoom 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.
+ * Multi-ring + optional todo strip + zoom/focus/device - the Pilot equivalent
+ * of Block `stubBefore` narration in `waygraph demo`.
  * Does not import `cli.ts` (see file header).
  */
 export declare function showPilotFixtures(page: Page, fixtures: PilotHighlightFixtures): Promise<{

package/dist/pilot-overlay.js

@@ -1,4 +1,4 @@
-import { WAYGRAPH_RING_CSS } from "./highlights.js";
+import { WAYGRAPH_RING_CSS, normalizeHighlightTone, normalizeHighlightSize, normalizeHighlightWeight, formatHighlightCaption, resolveDeviceState, } 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
@@ -88,16 +88,41 @@ const OVERLAY_CSS = `
 .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;
+  position:fixed;z-index:2147483645;top:72px;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[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;}
+/* 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);
+  opacity:0;transition:opacity .3s ease,left .3s ease,top .3s ease,width .3s ease,height .3s ease;}
+#wg-pilot-fx-focus.wg-in{opacity:1;}
+/* Zoom HUD (demo parity - badge only; no CSS scale of the page). */
+#wg-pilot-fx-zoom{position:fixed;z-index:2147483646;bottom:14px;right:14px;
+  display:flex;align-items:center;gap:7px;padding:6px 11px 6px 8px;
+  border-radius:999px;background:rgba(20,10,40,.94);color:#f0e8ff;
+  border:1px solid rgba(250,204,21,.6);box-shadow:0 6px 18px rgba(0,0,0,.4);
+  font:700 12px/1.2 system-ui,sans-serif;pointer-events:none;}
+#wg-pilot-fx-zoom .wg-pilot-fx-zoom-ico{width:18px;height:18px;display:flex;align-items:center;justify-content:center;
+  border-radius:6px;background:rgba(250,204,21,.22);}
+#wg-pilot-fx-zoom .wg-pilot-fx-zoom-ico svg{width:14px;height:14px;display:block;}
+#wg-pilot-fx-zoom .wg-pilot-fx-zoom-val{color:#fde68a;font-variant-numeric:tabular-nums;font-weight:800;min-width:3.2em;}
+#wg-pilot-fx-zoom[data-zoomed="1"]{border-color:#fbbf24;}
+#wg-pilot-fx-device{position:fixed;z-index:2147483646;top:14px;right:14px;
+  padding:8px 12px;border-radius:10px;background:rgba(20,10,40,.94);color:#f0e8ff;
+  border:1px solid rgba(124,58,237,.55);font:700 12px/1.2 system-ui,sans-serif;
+  pointer-events:none;box-shadow:0 6px 18px rgba(0,0,0,.35);}
+#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;
 /** Idempotent - safe to call before every update, matching narrate mode's own precedent. */
 async function ensureInstalled(page) {
@@ -254,8 +279,8 @@ export async function showPilotVision(page, selector, label, tone = "auto") {
 }
 /**
  * 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.
+ * Multi-ring + optional todo strip + zoom/focus/device - the Pilot equivalent
+ * of Block `stubBefore` narration in `waygraph demo`.
  * Does not import `cli.ts` (see file header).
  */
 export async function showPilotFixtures(page, fixtures) {
@@ -263,25 +288,168 @@ export async function showPilotFixtures(page, fixtures) {
     const holdMs = fixtures.clear === true
         ? 0
         : fixtures.holdMs === undefined
-            ? 12_000
+            ? 30_000
             : Math.max(0, fixtures.holdMs);
-    const rings = fixtures.clear ? [] : (fixtures.rings ?? []);
+    const rings = (fixtures.clear ? [] : (fixtures.rings ?? [])).map((r) => {
+        const tone = normalizeHighlightTone(r.tone);
+        const size = normalizeHighlightSize(r.size);
+        const weight = normalizeHighlightWeight(r.weight);
+        const caption = { label: r.label, tone };
+        if (r.detail)
+            caption.detail = r.detail;
+        if (r.tag)
+            caption.tag = r.tag;
+        const label = formatHighlightCaption(caption);
+        return {
+            selector: r.selector,
+            label,
+            tone,
+            size,
+            weight,
+            color: typeof r.color === "string" && r.color.trim() ? r.color.trim() : "",
+            zoom: typeof r.zoom === "number" && Number.isFinite(r.zoom) && r.zoom > 0
+                ? r.zoom
+                : undefined,
+            zoomOut: r.zoomOut,
+            focus: r.focus === true,
+        };
+    });
     const todos = fixtures.clear ? [] : (fixtures.todos ?? []);
     const todoIndex = fixtures.todoIndex ?? 0;
     const todoTitle = fixtures.todoTitle ?? "Plan";
+    const todoPos = fixtures.todoPos === "left" ? "left" : "right";
+    // Effective zoom: phase zoom, else last ring that authored zoom.
+    let zoom = fixtures.clear === true
+        ? 1
+        : typeof fixtures.zoom === "number" && Number.isFinite(fixtures.zoom)
+            ? fixtures.zoom
+            : 1;
+    let zoomSelector = fixtures.zoomSelector ??
+        (rings.length > 0 ? rings[rings.length - 1].selector : undefined);
+    let zoomOut = fixtures.zoomOut !== false;
+    if (!fixtures.clear && zoom <= 1.001) {
+        for (let i = rings.length - 1; i >= 0; i--) {
+            const r = rings[i];
+            if (r.zoom !== undefined && r.zoom > 1.001) {
+                zoom = r.zoom;
+                zoomSelector = r.selector;
+                if (r.zoomOut !== undefined)
+                    zoomOut = r.zoomOut !== false;
+                break;
+            }
+        }
+    }
+    else if (!fixtures.clear) {
+        // Phase zoomOut can still be overridden by the targeted ring.
+        const hit = rings.find((r) => r.selector === zoomSelector);
+        if (hit?.zoomOut !== undefined)
+            zoomOut = hit.zoomOut !== false;
+    }
+    // Device viewport (Node-side) before paint so rings land on the new size.
+    if (fixtures.clear === true) {
+        // Leave viewport alone on clear - only drop overlays.
+    }
+    else if (fixtures.device !== undefined) {
+        const d = resolveDeviceState(fixtures.device);
+        if (d) {
+            await page
+                .setViewportSize({
+                width: Math.max(200, Math.floor(d.viewport.width)),
+                height: Math.max(200, Math.floor(d.viewport.height)),
+            })
+                .catch(() => { });
+        }
+    }
+    const deviceLabel = fixtures.clear === true
+        ? ""
+        : fixtures.device === undefined
+            ? ""
+            : typeof fixtures.device === "string"
+                ? fixtures.device
+                : fixtures.device.preset || "device";
     return page
-        .evaluate(({ rings, todos, todoIndex, todoTitle, holdMs }) => {
+        .evaluate(({ rings, todos, todoIndex, todoTitle, todoPos, holdMs, zoom, zoomSelector, zoomOut, clearAll, deviceLabel, }) => {
         const w = window;
         if (w.__wgPilotFxHideTimer)
             clearTimeout(w.__wgPilotFxHideTimer);
+        const clearFocus = () => {
+            const veil = document.getElementById("wg-pilot-fx-focus");
+            if (!veil)
+                return;
+            veil.classList.remove("wg-in");
+            setTimeout(() => {
+                const v = document.getElementById("wg-pilot-fx-focus");
+                if (v && !v.classList.contains("wg-in"))
+                    v.remove();
+            }, 320);
+        };
+        const applyFocus = (box) => {
+            let veil = document.getElementById("wg-pilot-fx-focus");
+            if (!veil) {
+                veil = document.createElement("div");
+                veil.id = "wg-pilot-fx-focus";
+                document.documentElement.appendChild(veil);
+            }
+            const pad = 10;
+            veil.style.left = `${Math.max(0, box.x - pad)}px`;
+            veil.style.top = `${Math.max(0, box.y - pad)}px`;
+            veil.style.width = `${Math.max(8, box.width + pad * 2)}px`;
+            veil.style.height = `${Math.max(8, box.height + pad * 2)}px`;
+            void veil.offsetWidth;
+            veil.classList.add("wg-in");
+        };
+        const setZoomBadge = (scale) => {
+            const level = Number.isFinite(scale) && scale > 0 ? scale : 1;
+            let badge = document.getElementById("wg-pilot-fx-zoom");
+            if (!badge) {
+                badge = document.createElement("div");
+                badge.id = "wg-pilot-fx-zoom";
+                document.documentElement.appendChild(badge);
+            }
+            const zoomed = level > 1.001 || level < 0.999;
+            badge.dataset.zoomed = zoomed ? "1" : "0";
+            badge.innerHTML =
+                '<span class="wg-pilot-fx-zoom-ico"><svg viewBox="0 0 24 24" fill="none" stroke="#fde68a" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="7"/><path d="M20 20l-3.5-3.5"/></svg></span>' +
+                    `<span class="wg-pilot-fx-zoom-val">${level.toFixed(2)}\u00d7</span>`;
+        };
+        const clearZoom = () => {
+            // Undo any leftover CSS-scale from older Pilot zoom path.
+            const root = document.documentElement;
+            root.style.removeProperty("transform");
+            root.style.removeProperty("transform-origin");
+            root.style.removeProperty("transition");
+            document.getElementById("wg-pilot-fx-zoom")?.remove();
+        };
+        const setDeviceChip = (label) => {
+            document.getElementById("wg-pilot-fx-device")?.remove();
+            if (!label)
+                return;
+            const chip = document.createElement("div");
+            chip.id = "wg-pilot-fx-device";
+            chip.dataset.preset = label;
+            chip.textContent = `device \u00b7 ${label}`;
+            document.documentElement.appendChild(chip);
+        };
+        w.__wgPilotFxZoomOutOnHide = zoomOut;
         const clearFx = () => {
             document.querySelectorAll(".wg-pilot-fx-ring, .wg-pilot-fx-label").forEach((el) => el.remove());
             document.getElementById("wg-pilot-fx-todos")?.remove();
+            clearFocus();
+            if (w.__wgPilotFxZoomOutOnHide !== false || clearAll)
+                clearZoom();
+            if (clearAll) {
+                document.getElementById("wg-pilot-fx-device")?.remove();
+                clearZoom();
+            }
         };
         w.__wgPilotFxClear = clearFx;
         clearFx();
+        if (clearAll) {
+            return { painted: 0, missing: [] };
+        }
         const missing = [];
         let painted = 0;
+        let focusBox = null;
         for (const ring of rings) {
             const el = document.querySelector(ring.selector);
             if (!el) {
@@ -293,14 +461,11 @@ export async function showPilotFixtures(page, fixtures) {
                 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 pad = ring.size === "sm" ? 3 : ring.size === "lg" ? 10 : 6;
             const ringEl = document.createElement("div");
             ringEl.className = "wg-pilot-fx-ring";
-            ringEl.dataset.tone = tone;
-            ringEl.dataset.size = size;
+            ringEl.dataset.tone = ring.tone;
+            ringEl.dataset.size = ring.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`;
@@ -308,11 +473,14 @@ export async function showPilotFixtures(page, fixtures) {
             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.dataset.tone = ring.tone;
+            labelEl.dataset.size = ring.size;
+            labelEl.dataset.weight = ring.weight;
             labelEl.textContent = ring.label;
             labelEl.style.opacity = "1";
+            if (ring.color) {
+                labelEl.style.color = ring.color;
+            }
             document.documentElement.appendChild(ringEl);
             document.documentElement.appendChild(labelEl);
             const lw = labelEl.offsetWidth;
@@ -331,10 +499,14 @@ export async function showPilotFixtures(page, fixtures) {
             labelEl.style.left = `${labelLeft}px`;
             labelEl.style.top = `${labelTop}px`;
             painted += 1;
+            if (ring.focus) {
+                focusBox = { x: rect.left, y: rect.top, width: rect.width, height: rect.height };
+            }
         }
         if (todos.length > 0) {
             const dock = document.createElement("div");
             dock.id = "wg-pilot-fx-todos";
+            dock.dataset.pos = todoPos;
             const title = document.createElement("div");
             title.className = "wg-pilot-fx-todo-title";
             title.textContent = todoTitle;
@@ -352,11 +524,50 @@ export async function showPilotFixtures(page, fixtures) {
             dock.appendChild(ol);
             document.documentElement.appendChild(dock);
         }
-        if (holdMs > 0 && (painted > 0 || todos.length > 0)) {
+        if (focusBox)
+            applyFocus(focusBox);
+        if (zoom > 1.001 && zoomSelector) {
+            const target = document.querySelector(zoomSelector);
+            if (target) {
+                target.scrollIntoView({
+                    block: "center",
+                    inline: "center",
+                    behavior: "instant",
+                });
+                // Re-apply focus after scroll so the cutout tracks the new rect.
+                if (focusBox) {
+                    const r = target.getBoundingClientRect();
+                    applyFocus({ x: r.left, y: r.top, width: r.width, height: r.height });
+                }
+                setZoomBadge(zoom);
+            }
+            else {
+                missing.push(zoomSelector);
+            }
+        }
+        else if (zoom > 1.001) {
+            setZoomBadge(zoom);
+        }
+        if (deviceLabel)
+            setDeviceChip(deviceLabel);
+        if (holdMs > 0 &&
+            (painted > 0 || todos.length > 0 || zoom > 1.001 || !!deviceLabel)) {
             w.__wgPilotFxHideTimer = setTimeout(() => clearFx(), holdMs);
         }
         return { painted, missing };
-    }, { rings, todos, todoIndex, todoTitle, holdMs })
+    }, {
+        rings,
+        todos,
+        todoIndex,
+        todoTitle,
+        todoPos,
+        holdMs,
+        zoom,
+        zoomSelector: zoomSelector ?? "",
+        zoomOut,
+        clearAll: fixtures.clear === true,
+        deviceLabel,
+    })
         .catch(() => ({ painted: 0, missing: rings.map((r) => r.selector) }));
 }
 /**

package/examples/saucedemo/.waygraph-auto/03710cfc.json

@@ -0,0 +1,8 @@
+{
+  "sessionId": "03710cfc",
+  "socketPath": "/tmp/waygraph-auto/03710cfc.sock",
+  "pid": 255515,
+  "projectDir": "/home/dan/Desktop/Work/zsign/services/waygraph/examples/saucedemo",
+  "startedAt": "2026-09-21T09:37:58.750Z",
+  "headless": false
+}

package/examples/saucedemo/.waygraph-auto/39f352c7.log

@@ -0,0 +1,4 @@
+(node:223602) 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:223602) 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/.waygraph-auto/605d965b.json

@@ -0,0 +1,8 @@
+{
+  "sessionId": "605d965b",
+  "socketPath": "/tmp/waygraph-auto/605d965b.sock",
+  "pid": 247729,
+  "projectDir": "/home/dan/Desktop/Work/zsign/services/waygraph/examples/saucedemo",
+  "startedAt": "2026-09-21T09:34:04.318Z",
+  "headless": false
+}

package/examples/saucedemo/.waygraph-auto/6b667734.json

@@ -0,0 +1,8 @@
+{
+  "sessionId": "6b667734",
+  "socketPath": "/tmp/waygraph-auto/6b667734.sock",
+  "pid": 245167,
+  "projectDir": "/home/dan/Desktop/Work/zsign/services/waygraph/examples/saucedemo",
+  "startedAt": "2026-09-21T09:33:13.876Z",
+  "headless": false
+}

package/examples/saucedemo/.waygraph-auto/90141d7e.log

@@ -0,0 +1,4 @@
+(node:254673) 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:254673) 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.4",
+  "version": "0.15.7",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",

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

@@ -27,15 +27,25 @@ sending picks.
 
 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:
+a headful session (or you want to narrate intent before a send), paint yourself with the
+same fixture surface:
 
 ```
-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> '{"rings":[{"selector":"#user-name","label":"Username","tone":"planned","focus":true},{"selector":"#password","label":"Password","tone":"info","detail":"secret"}],"todos":["Fill username","Fill password","Submit"],"todoIndex":0,"zoom":1.5,"holdMs":0}'
+waygraph auto highlight <sessionId> '{"device":"mobile","rings":[{"selector":".inventory_item:last-child","label":"Last item","zoom":1.6,"focus":true}],"holdMs":30000}'
 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)
+Supported fields (demo parity):
+- `rings[]`: `selector`, `label`, `detail`, `tag`, `tone`, `size`, `weight`, `color`, `zoom`, `zoomOut`, `focus`
+- `todos` / `todoIndex` / `todoTitle` / `todoPos` (`right` default | `left`)
+- `zoom` / `zoomSelector` / `zoomOut` - scroll + zoom badge (not CSS page scale)
+- `device`: `mobile` | `tablet` | `desktop` (Playwright viewport)
+- `holdMs`: ms to keep fixtures; `0` = until the next highlight / clear (default 30000)
+- `clear`: true drops rings/todos/focus/zoom badge
+
+- `tone`: all demo tones - `planned` | `auto` | `info` | `warning` | `danger` | `success` | `orange` (aliases like `error`/`blue`/`green` work too)
+- Bottom-left toast shows `Highlighting: …` (same strip as `Running (Dom): …`)
 - Missing selectors are listed in the JSON response (`missing`) - not a hard failure
 - Does not replace `auto send` - paint, then run the real Block