waygraph 0.15.5 → 0.15.8

package/README.md

@@ -1015,6 +1015,7 @@ Flows are files (0.10.5+):
 | Manual watch | `waygraph demo src/flows/shop.flow.ts` |
 | Auto-advance | `waygraph demo --blocks shopFlow --auto-next` (nav auto-hides strip) |
 | Fast / full strip | `waygraph demo ... --fast` (shorter gates; keeps cursor) · `--full` (classic chips; default = carousel) |
+| Todo dock UX | `waygraph demo ... --todo-smart` (default) · `--todo-full` (no compact/collision/behind) |
 | QA watch + record | `waygraph demo --blocks shopFlow --auto-play-video` |
 | Ad-hoc Blocks | `waygraph run --blocks "login then nav-cart" --data '{...}'` |
 | Headed execute | `waygraph run --blocks shopFlow --non-headless --video` |
@@ -1040,6 +1041,20 @@ Flows are files (0.10.5+):
 `--auto-next` (alias `--autoplay`) = panel Auto-advance. `--auto-play-video` is **demo
 only**. `chain` remains a compat alias for `run --blocks` / `auto --blocks`.
 
+### Todo dock UI (demo, 0.15.8+)
+
+Long FR/AC checklists used to bury highlight rings. **Smart defaults are on:**
+
+| Behavior | Default | Opt out |
+|----------|---------|---------|
+| Compact fold (~5 rows around current; hover expands; `+N more`) | on | `ctx.todoDockFull()` / `ctx.todoDockUi({ compact: false })` / `--todo-full` / `WAYGRAPH_TODO_UI=full` |
+| Collision flip (dock L/R when a ring overlaps) | on | `ctx.todoDockUi({ collision: false })` / `WAYGRAPH_TODO_COLLISION=0` |
+| Behind ring (dim + lower z-index while a ring is up) | on | `ctx.todoDockUi({ behindRing: false })` / `WAYGRAPH_TODO_BEHIND=0` |
+
+Per-knob env also: `WAYGRAPH_TODO_COMPACT`, `WAYGRAPH_TODO_CAP` (default 5),
+`WAYGRAPH_TODO_EXPAND_CAP` (default 14). Author API: `ctx.todoDockUi({ ... })`.
+Pilot `auto highlight` accepts the same knobs as `todoUi` on the JSON body.
+
 Run `waygraph --help` (or any subcommand with no args) for the full flag reference kept
 in `src/cli.ts`'s own `usage()` - that's the source of truth for flags, this table is the
 scannable summary.

package/dist/auto-session.js

@@ -682,6 +682,11 @@ export class AutoSession {
             : [
                 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";

package/dist/cli.js

@@ -235,6 +235,7 @@ import {
   completeSequentialTodoDock,
   applyDevicePhase,
   resolveDeviceState,
+  resolveTodoDockUi,
   WAYGRAPH_RING_CSS,
 } from "waygraph";
 
@@ -517,9 +518,22 @@ const RING_CSS =
   "padding:10px 12px;background:rgba(20,10,40,.94);color:#fff;border-radius:12px;" +
   "border:1px solid rgba(124,58,237,.45);box-shadow:0 8px 24px rgba(0,0,0,.35);" +
   "pointer-events:auto;cursor:pointer;" +
-  "transition:transform .4s cubic-bezier(.22,1,.36,1),top .35s ease;transform:translateX(0);}" +
+  "transition:transform .4s cubic-bezier(.22,1,.36,1),top .35s ease,opacity .25s ease,z-index 0s;transform:translateX(0);}" +
   ".wg-todo-dock[data-pos=right],#wg-todo-dock[data-pos=right]{transform:translateX(calc(100vw - 100% - 28px));}" +
   ".wg-todo-dock[data-pos=left],#wg-todo-dock[data-pos=left]{transform:translateX(0);}" +
+  /* While a highlight ring is up: sit under the ring so captions stay readable. */
+  ".wg-todo-dock.wg-todo-behind,#wg-todo-dock.wg-todo-behind{z-index:2147483643;opacity:.42;}" +
+  /* Collision tuck: shrink so a mid-page ring can still breathe. */
+  ".wg-todo-dock[data-tucked=\\"1\\"],#wg-todo-dock[data-tucked=\\"1\\"]{max-height:min(28vh,220px);}" +
+  /* Compact + cap: fold overflow rows; hover / data-expanded reveals more. */
+  ".wg-todo-dock[data-compact=\\"1\\"]:not(:hover):not([data-expanded=\\"1\\"]) li.wg-todo-fold{display:none;}" +
+  ".wg-todo-dock[data-compact=\\"1\\"]:is(:hover,[data-expanded=\\"1\\"]) li.wg-todo-fold-deep{display:none;}" +
+  ".wg-todo-dock .wg-todo-more{display:flex;align-items:center;gap:6px;margin-top:6px;padding:5px 8px;" +
+  "border-radius:8px;background:rgba(124,58,237,.22);border:1px solid rgba(124,58,237,.4);" +
+  "font:700 11px/1.2 system-ui,sans-serif;color:#e8dcff;cursor:pointer;user-select:none;}" +
+  ".wg-todo-dock .wg-todo-more:hover{background:rgba(124,58,237,.35);}" +
+  ".wg-todo-dock .wg-todo-dock-title{font:700 11px/1.2 system-ui,sans-serif;color:#c9a6ff;" +
+  "letter-spacing:.04em;text-transform:uppercase;margin:0 0 8px;}" +
   ".wg-todo-dock .wg-todos-list,#wg-todo-dock #wg-todos,.wg-todo-dock #wg-todos{list-style:none;margin:0;padding:0;background:transparent;border:none;}" +
   // Video device stage: keep recordVideo size fixed; center a device-sized shell.
   "html.wg-video-device-stage{background:#0b1220 !important;}" +
@@ -745,9 +759,17 @@ async function installOverlay(page, title) {
   const envTodoPos = (process.env.WAYGRAPH_TODO_POS || "left").toLowerCase();
   const todoPos = envTodoPos === "right" ? "right" : "left";
   const envAutoplay = process.env.WAYGRAPH_AUTOPLAY === "1";
+  const todoDockUi = resolveTodoDockUi();
   await page
     .evaluate(
-      ({ title, favicon, bannerPos, todoPos, envAutoplay }) => {
+      ({ title, favicon, bannerPos, todoPos, envAutoplay, todoDockUi }) => {
+        window.__wgTodoDockUi = todoDockUi || {
+          compact: true,
+          cap: 5,
+          expandCap: 14,
+          collision: true,
+          behindRing: true,
+        };
         // Seed the live autoplay toggle from the env default on first ever
         // load only - a real navigation re-runs this, and re-stamping here
         // would silently undo a human's mid-run checkbox click.
@@ -851,6 +873,57 @@ async function installOverlay(page, title) {
           if (labelLeft < margin) labelLeft = margin;
           ringLabel.style.left = labelLeft + "px";
           ringLabel.style.top = labelTop + "px";
+          if (window.__wgTodosSetBehind) window.__wgTodosSetBehind(true);
+          if (window.__wgTodosAvoidRingCollision) window.__wgTodosAvoidRingCollision(box);
+        };
+        /** Dim/lower floating todo docks while a ring caption is the focus. */
+        window.__wgTodosSetBehind = (on) => {
+          const ui = window.__wgTodoDockUi || {};
+          if (ui.behindRing === false) {
+            document.querySelectorAll(".wg-todo-dock, #wg-todo-dock").forEach((el) => {
+              el.classList.remove("wg-todo-behind");
+            });
+            return;
+          }
+          document.querySelectorAll(".wg-todo-dock, #wg-todo-dock").forEach((el) => {
+            el.classList.toggle("wg-todo-behind", !!on);
+          });
+        };
+        /**
+         * If the active ring box intersects a todo dock, flip L/R once.
+         * Locked until hideRing so follow-rAF does not thrash.
+         */
+        window.__wgTodosAvoidRingCollision = (box) => {
+          const ui = window.__wgTodoDockUi || {};
+          if (ui.collision === false) return;
+          if (!box || window.__wgTodoCollisionLocked) return;
+          const pad = 10;
+          const rx1 = box.x - pad;
+          const ry1 = box.y - pad;
+          const rx2 = box.x + box.width + pad;
+          const ry2 = box.y + box.height + pad;
+          const overlaps = (el) => {
+            const r = el.getBoundingClientRect();
+            return !(r.right < rx1 || r.left > rx2 || r.bottom < ry1 || r.top > ry2);
+          };
+          const docks = [...document.querySelectorAll(".wg-todo-dock, #wg-todo-dock")].filter(
+            (el, i, arr) => arr.indexOf(el) === i,
+          );
+          for (const dock of docks) {
+            if (!overlaps(dock)) continue;
+            const cur = dock.dataset.pos === "right" ? "right" : "left";
+            dock.dataset.pos = cur === "right" ? "left" : "right";
+            try {
+              localStorage.setItem("wg-todo-pos", dock.dataset.pos);
+            } catch {
+              /* ignore */
+            }
+            // Still colliding after flip - tuck (shorter max-height).
+            if (overlaps(dock)) dock.dataset.tucked = "1";
+            else delete dock.dataset.tucked;
+            window.__wgTodoCollisionLocked = true;
+            break;
+          }
         };
         /** Live-follow a selector with rAF (accurate under device shell scale). */
         window.__wgStopRingFollow = () => {
@@ -907,6 +980,11 @@ async function installOverlay(page, title) {
           if (ring) ring.style.opacity = "0";
           if (ringLabel) ringLabel.style.opacity = "0";
           if (window.__wgClearFocus) window.__wgClearFocus();
+          if (window.__wgTodosSetBehind) window.__wgTodosSetBehind(false);
+          window.__wgTodoCollisionLocked = false;
+          document.querySelectorAll(".wg-todo-dock[data-tucked], #wg-todo-dock[data-tucked]").forEach((el) => {
+            delete el.dataset.tucked;
+          });
           // Honor zoomOut:false - keep camera until next zoom / desktop clear.
           const forceClear = opts && opts.clearZoom === true;
           const skipClear = opts && opts.clearZoom === false;
@@ -1422,6 +1500,7 @@ async function installOverlay(page, title) {
         //   { sync: "set", dock } / { sync:"set", list } -> render / recreate
         // Compat: bare array = set list (empty array = clear - legacy only).
         window.__wgSyncTodos = (payload, pos) => {
+          const syncPayload = payload;
           let sync = "set";
           let list = [];
           let dockState = null;
@@ -1571,7 +1650,35 @@ async function installOverlay(page, title) {
             const id = raw != null && String(raw).trim() ? String(raw).trim() : "";
             return id ? ' data-wg-todo-item="' + esc(id) + '"' : "";
           };
-          const renderItems = (items, style) => {
+          // Compact + cap: >cap rows folds overflow; hover shows up to expandCap; "+N more" pins expand.
+          const ui = (payload && !Array.isArray(payload) && payload.ui) || window.__wgTodoDockUi || {};
+          const COMPACT_AT = Number(ui.cap) > 0 ? Number(ui.cap) : 5;
+          const WINDOW = COMPACT_AT;
+          const EXPAND_MAX = Number(ui.expandCap) > 0 ? Number(ui.expandCap) : 14;
+          const compactEnabled = ui.compact !== false;
+          const flattenItems = () => {
+            if (dockState && Array.isArray(dockState.groups) && dockState.groups.length) {
+              const out = [];
+              for (const g of dockState.groups) {
+                for (const t of g.items || []) out.push({ ...t, __style: g.style || dockState.style });
+              }
+              return out;
+            }
+            return (list || []).map((t) => ({ ...t, __style: "sequential" }));
+          };
+          const windowBounds = (items, cap) => {
+            const n = items.length;
+            if (n <= cap) return { start: 0, end: n };
+            let cur = items.findIndex((t) => t.current);
+            if (cur < 0) cur = items.findIndex((t) => !t.done);
+            if (cur < 0) cur = 0;
+            let start = Math.max(0, cur - Math.floor((cap - 1) / 2));
+            let end = Math.min(n, start + cap);
+            start = Math.max(0, end - cap);
+            return { start, end };
+          };
+          const renderItems = (items, style, foldMeta, indexOffset) => {
+            const offset = indexOffset || 0;
             const rawStyle = String(style || "sequential").toLowerCase();
             const st =
               rawStyle === "checklist"
@@ -1584,13 +1691,18 @@ async function installOverlay(page, title) {
                     rawStyle === "plain"
                   ? "bullets"
                   : "sequential";
+            const foldStart = foldMeta ? foldMeta.foldStart : -1;
+            const foldEnd = foldMeta ? foldMeta.foldEnd : -1;
+            const deepStart = foldMeta ? foldMeta.deepStart : -1;
+            const deepEnd = foldMeta ? foldMeta.deepEnd : -1;
             return (
               '<ul class="wg-todos-list" data-wg-todo-style="' +
               st +
               '">' +
               (items || [])
-                .map((t) => {
-                  const cls =
+                .map((t, idx) => {
+                  const gi = offset + idx;
+                  const clsBase =
                     st === "bullets"
                       ? t.done
                         ? "wg-todo-done"
@@ -1600,6 +1712,9 @@ async function installOverlay(page, title) {
                         : t.done
                           ? "wg-todo-done"
                           : "wg-todo-pending";
+                  let foldCls = "";
+                  if (foldStart >= 0 && (gi < foldStart || gi >= foldEnd)) foldCls += " wg-todo-fold";
+                  if (deepStart >= 0 && (gi < deepStart || gi >= deepEnd)) foldCls += " wg-todo-fold-deep";
                   let mark;
                   if (st === "checklist") {
                     mark = t.done ? "\u2611" : "\u2610";
@@ -1611,7 +1726,8 @@ async function installOverlay(page, title) {
                   const rowId = t.id || t.name || "";
                   return (
                     '<li class="' +
-                    cls +
+                    clsBase +
+                    foldCls +
                     '"' +
                     attrId(rowId) +
                     '><span class="wg-todo-mark">' +
@@ -1629,12 +1745,28 @@ async function installOverlay(page, title) {
           if (dockKey !== "_default") dock.setAttribute("data-wg-todo-id", dockKey);
           else dock.removeAttribute("data-wg-todo-id");
 
+          const flat = flattenItems();
+          const compact = compactEnabled && flat.length > COMPACT_AT;
+          const win = windowBounds(flat, WINDOW);
+          const expand = windowBounds(flat, EXPAND_MAX);
+          const foldMeta = compact
+            ? {
+                foldStart: win.start,
+                foldEnd: win.end,
+                deepStart: expand.start,
+                deepEnd: expand.end,
+              }
+            : null;
+          const hiddenCompact = compact ? flat.length - (win.end - win.start) : 0;
+          const hiddenExpand = compact ? flat.length - (expand.end - expand.start) : 0;
+
           let html = "";
           if (dockState && Array.isArray(dockState.groups) && dockState.groups.length) {
             const dockTitle = dockState.title && String(dockState.title).trim();
             if (dockTitle) {
               html += '<div class="wg-todo-dock-title">' + esc(dockTitle) + "</div>";
             }
+            let globalIdx = 0;
             for (const g of dockState.groups) {
               const gTitle = g.title && String(g.title).trim();
               const gid = g.id || g.name || "";
@@ -1645,13 +1777,42 @@ async function installOverlay(page, title) {
               if (gTitle) {
                 html += '<div class="wg-todo-group-title">' + esc(gTitle) + "</div>";
               }
-              html += renderItems(g.items, g.style || dockState.style);
+              const gItems = g.items || [];
+              html += renderItems(gItems, g.style || dockState.style, foldMeta, globalIdx);
               html += "</div>";
+              globalIdx += gItems.length;
             }
           } else {
-            html = renderItems(list, "sequential");
+            html = renderItems(list, "sequential", foldMeta, 0);
+          }
+          if (compact && hiddenCompact > 0) {
+            const n = dock.dataset.expanded === "1" ? hiddenExpand : hiddenCompact;
+            if (n > 0) {
+              html +=
+                '<div class="wg-todo-more" data-wg-todo-more="1" title="Click to expand / collapse">' +
+                "+" +
+                n +
+                " more</div>";
+            }
+          }
+          if (compact) dock.dataset.compact = "1";
+          else {
+            delete dock.dataset.compact;
+            delete dock.dataset.expanded;
           }
           dock.innerHTML = html;
+          const moreBtn = dock.querySelector("[data-wg-todo-more]");
+          if (moreBtn) {
+            moreBtn.addEventListener("click", (e) => {
+              e.stopPropagation();
+              if (dock.dataset.expanded === "1") delete dock.dataset.expanded;
+              else dock.dataset.expanded = "1";
+              if (window.__wgSyncTodos && dock._wgLastPayload) {
+                window.__wgSyncTodos(dock._wgLastPayload);
+              }
+            });
+          }
+          dock._wgLastPayload = syncPayload;
           relayoutTodoDocks();
           if (window.__wgStampModal) {
             window.__wgStampModal(dock, "todos", { ready: true });
@@ -1864,7 +2025,7 @@ async function installOverlay(page, title) {
           }
         };
       },
-      { title, favicon: WAYGRAPH_FAVICON, bannerPos, todoPos, envAutoplay },
+      { title, favicon: WAYGRAPH_FAVICON, bannerPos, todoPos, envAutoplay, todoDockUi },
     )
     .catch(() => {});
   // Navigations wipe #wg-device-shell - rebuild when video stage + device are live.
@@ -4970,8 +5131,21 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
   let result;
   /** Carry floating todo dock across steps (empty stubBefore must not wipe). */
   let lastTodoDock = undefined;
+  /** Author todoDockUi patches (merged); resolved against env each step. */
+  let lastTodoDockUiPatch = undefined;
   /** Multi-todo: every dock keyed by todoId (or "_default"), survives navigation. */
   const todoDockById = new Map();
+  const pushTodoDockUi = async (patch) => {
+    if (patch && typeof patch === "object") {
+      lastTodoDockUiPatch = { ...(lastTodoDockUiPatch || {}), ...patch };
+    }
+    const ui = resolveTodoDockUi(lastTodoDockUiPatch);
+    await page
+      .evaluate((u) => {
+        window.__wgTodoDockUi = u;
+      }, ui)
+      .catch(() => {});
+  };
   const dockRegistryKey = (dock) =>
     dock && dock.id && String(dock.id).trim() ? String(dock.id).trim() : "_default";
   const rememberTodoDock = (dock, sync, parallel) => {
@@ -5104,6 +5278,11 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
     const fixtures = r.highlightFixtures;
     const flowStyle = r.highlightStyle;
     const stubBeforePhase = await runStubPhase(r.block, "stubBefore", { fixtures, mem });
+    if (stubBeforePhase.todoDockUi) {
+      await pushTodoDockUi(stubBeforePhase.todoDockUi);
+    } else {
+      await pushTodoDockUi(undefined);
+    }
     stubBeforeRef.current = stubBeforePhase.highlights.map((h) =>
       applyHighlightStyleDefaults(h, flowStyle),
     );
@@ -5422,6 +5601,9 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
         fixtures: fixturesAfter,
         mem,
       });
+      if (afterPhase.todoDockUi) {
+        await pushTodoDockUi(afterPhase.todoDockUi);
+      }
       logStubPhaseFixtures("after", {
         ...afterPhase,
         highlights: (afterPhase.highlights || []).map((h) => {
@@ -6604,6 +6786,12 @@ function parseRunFlags(argv) {
         else if (a === "--todo-right") {
             out.todoPos = "right";
         }
+        else if (a === "--todo-full" || a === "--no-todo-smart") {
+            out.todoUiFull = true;
+        }
+        else if (a === "--todo-smart") {
+            out.todoUiSmart = true;
+        }
         else if (a === "--ff-expand") {
             out.ffExpand = true;
         }
@@ -6782,6 +6970,12 @@ function applyRunFlags(flags, opts) {
     if (flags.todoPos === "left" || flags.todoPos === "right") {
         process.env.WAYGRAPH_TODO_POS = flags.todoPos;
     }
+    if (flags.todoUiFull) {
+        process.env.WAYGRAPH_TODO_UI = "full";
+    }
+    else if (flags.todoUiSmart) {
+        process.env.WAYGRAPH_TODO_UI = "smart";
+    }
     if (flags.ffExpand) {
         process.env.WAYGRAPH_FF_EXPAND = "1";
     }
@@ -7030,6 +7224,8 @@ Primary (less is more):
                  --full                    Classic wrap-all block chips (default: carousel)
                  --mini                    Force compact mini panel (Hide pill + Next); alias --stepper-mini
                  --todo-left|--todo-right  Floating checklist dock side (also ctx.todoPos / WAYGRAPH_TODO_POS)
+                 --todo-full               Opt out: full checklist, no compact/collision/behind-ring
+                 --todo-smart              Opt in: compact + collision + behind-ring (default)
                  --ff-expand               Expand fastForwardComposeBlock inners as separate steps
                  --ff-disabled             Dispute: expand FF (alias --no-ff); blitz kept on those inners
                  --auto-play-video         Unattended + recorded: --auto-next + --video (+ step); headless

package/dist/highlights.d.ts

@@ -105,6 +105,41 @@ export type WaygraphTodosOpts = {
      */
     parallel?: boolean;
 };
+/**
+ * Floating todo-dock UX knobs (0.15.8+). Defaults are **smart on** so long
+ * FR/AC checklists do not bury highlight rings. Opt out per phase or globally.
+ *
+ * Defaults: `compact`, `collision`, `behindRing` = true; `cap` = 5; `expandCap` = 14.
+ *
+ * Global: `WAYGRAPH_TODO_UI=full` / `waygraph demo --todo-full` turns smart off.
+ * Per-knob env: `WAYGRAPH_TODO_COMPACT=0`, `WAYGRAPH_TODO_COLLISION=0`,
+ * `WAYGRAPH_TODO_BEHIND=0`, `WAYGRAPH_TODO_CAP`, `WAYGRAPH_TODO_EXPAND_CAP`.
+ */
+export type TodoDockUiOpts = {
+    /** Fold long lists around the current row (+N more / hover). Default true. */
+    compact?: boolean;
+    /** Visible rows when compact. Default 5. */
+    cap?: number;
+    /** Visible rows on hover / pinned expand. Default 14. */
+    expandCap?: number;
+    /** Flip dock L/R when an active ring overlaps it. Default true. */
+    collision?: boolean;
+    /** Dim + lower z-index while a highlight ring is up. Default true. */
+    behindRing?: boolean;
+};
+/** Resolved todo-dock UX (all fields present). */
+export type TodoDockUiResolved = {
+    compact: boolean;
+    cap: number;
+    expandCap: number;
+    collision: boolean;
+    behindRing: boolean;
+};
+/**
+ * Resolve todo-dock UX from env + optional author patch.
+ * `WAYGRAPH_TODO_UI=full|off|legacy` forces compact/collision/behindRing off.
+ */
+export declare function resolveTodoDockUi(patch?: TodoDockUiOpts | null, env?: NodeJS.ProcessEnv): TodoDockUiResolved;
 /** Episode-level fixtures authored inside stubBefore/After/OnError(ctx). */
 export type StubPhaseFixtures = {
     todos?: readonly WaygraphTodoInput[];
@@ -135,6 +170,11 @@ export type StubPhaseFixtures = {
      * Authored control (also click / WAYGRAPH_TODO_POS / --todo-left|right).
      */
     todoPos?: "left" | "right";
+    /**
+     * Todo-dock UX (compact / collision / behind-ring). Merged onto env defaults.
+     * See {@link TodoDockUiOpts}.
+     */
+    todoDockUi?: TodoDockUiOpts;
     /**
      * Viewport preset: `mobile` | `tablet` | `desktop` (default / clear).
      * Omit on later blocks = **keep** (same persist pattern as todos).
@@ -403,6 +443,16 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
      * code; click / env / --todo-left|right are fallbacks.
      */
     todoPos(side: "left" | "right"): void;
+    /**
+     * Todo-dock UX: compact fold, collision flip, dim-behind-ring.
+     * Defaults are smart-on; pass false fields to opt out for this phase.
+     * @example
+     * ctx.todoDockUi({ compact: false }); // always show full list
+     * ctx.todoDockFull(); // shorthand: compact+collision+behindRing off
+     */
+    todoDockUi(opts: TodoDockUiOpts): void;
+    /** Shorthand: full checklist, no compact/collision/behind-ring for this phase. */
+    todoDockFull(): void;
     /** Batch-set rings + episode fixtures. */
     set(partial: {
         highlights?: HighlightStubPhase;
@@ -430,6 +480,8 @@ export type StubPhaseResult = {
      * - `keep` - author omitted todos; demo must leave previous dock alone
      */
     todoSync?: "set" | "clear" | "keep";
+    /** Todo-dock UX for this phase (when author called {@link StubCtx.todoDockUi}). */
+    todoDockUi?: TodoDockUiOpts;
     /** Resolved device after this phase (undefined when keep with no prior). */
     device?: DeviceState;
     /**

package/dist/highlights.js

@@ -12,6 +12,57 @@
  * All fixture shapes share optional {@link FixtureDurationFields} so demo dwell
  * before advancing is authored the same way on stubs, flow fixtures, and slides.
  */
+function envFlagBool(env, key, fallback) {
+    const v = env[key];
+    if (v === undefined || v === "")
+        return fallback;
+    const s = String(v).trim().toLowerCase();
+    if (s === "0" || s === "false" || s === "off" || s === "no")
+        return false;
+    if (s === "1" || s === "true" || s === "on" || s === "yes")
+        return true;
+    return fallback;
+}
+function envFlagInt(env, key, fallback) {
+    const n = Number(env[key]);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
+/**
+ * Resolve todo-dock UX from env + optional author patch.
+ * `WAYGRAPH_TODO_UI=full|off|legacy` forces compact/collision/behindRing off.
+ */
+export function resolveTodoDockUi(patch, env = process.env) {
+    const mode = String(env.WAYGRAPH_TODO_UI || "smart")
+        .trim()
+        .toLowerCase();
+    const full = mode === "full" || mode === "off" || mode === "0" || mode === "legacy" || mode === "classic";
+    const base = {
+        compact: full ? false : envFlagBool(env, "WAYGRAPH_TODO_COMPACT", true),
+        collision: full ? false : envFlagBool(env, "WAYGRAPH_TODO_COLLISION", true),
+        behindRing: full ? false : envFlagBool(env, "WAYGRAPH_TODO_BEHIND", true),
+        cap: envFlagInt(env, "WAYGRAPH_TODO_CAP", 5),
+        expandCap: envFlagInt(env, "WAYGRAPH_TODO_EXPAND_CAP", 14),
+    };
+    if (base.expandCap < base.cap)
+        base.expandCap = base.cap;
+    if (!patch)
+        return base;
+    const cap = patch.cap !== undefined && Number.isFinite(patch.cap)
+        ? Math.max(1, Math.floor(Number(patch.cap)))
+        : base.cap;
+    let expandCap = patch.expandCap !== undefined && Number.isFinite(patch.expandCap)
+        ? Math.max(1, Math.floor(Number(patch.expandCap)))
+        : base.expandCap;
+    if (expandCap < cap)
+        expandCap = cap;
+    return {
+        compact: patch.compact !== undefined ? !!patch.compact : base.compact,
+        collision: patch.collision !== undefined ? !!patch.collision : base.collision,
+        behindRing: patch.behindRing !== undefined ? !!patch.behindRing : base.behindRing,
+        cap,
+        expandCap,
+    };
+}
 /** Built-in preset sizes (CSS pixels) — stored in portrait for mobile/tablet. */
 export const DEVICE_PRESETS = {
     mobile: {
@@ -966,6 +1017,18 @@ function createStubCtx(bag, opts) {
             if (p)
                 bag.todoPos = p;
         },
+        todoDockUi(opts) {
+            if (!opts || typeof opts !== "object")
+                return;
+            bag.todoDockUi = { ...(bag.todoDockUi || {}), ...opts };
+        },
+        todoDockFull() {
+            bag.todoDockUi = {
+                compact: false,
+                collision: false,
+                behindRing: false,
+            };
+        },
         set(partial) {
             if (partial.highlights)
                 bag.highlights = { ...partial.highlights };
@@ -1040,6 +1103,9 @@ function createStubCtx(bag, opts) {
             const tp = normalizeTodoPos(partial.todoPos);
             if (tp)
                 bag.todoPos = tp;
+            if (partial.todoDockUi !== undefined && partial.todoDockUi && typeof partial.todoDockUi === "object") {
+                bag.todoDockUi = { ...(bag.todoDockUi || {}), ...partial.todoDockUi };
+            }
         },
     };
 }
@@ -1237,6 +1303,7 @@ export async function runStubPhase(block, phase, opts) {
         ...(bag.zoomOut !== undefined ? { zoomOut: bag.zoomOut } : {}),
         ...(bag.title !== undefined && bag.title !== "" ? { title: bag.title } : {}),
         ...(bag.todoPos !== undefined ? { todoPos: bag.todoPos } : {}),
+        ...(bag.todoDockUi !== undefined ? { todoDockUi: bag.todoDockUi } : {}),
         ...(bag.todoParallel === true ? { todoParallel: true } : {}),
     };
 }

package/dist/index.d.ts

@@ -3,8 +3,8 @@ 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, 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 { resolveHighlightSlots, resolveSlides, runStubPhase, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS, resolveTodoDockUi, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, WAYGRAPH_RING_CSS, } from "./highlights.js";
+export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, WaygraphTodoItem, WaygraphTodoInput, WaygraphTodoGroup, WaygraphTodoGroupInput, WaygraphTodosOpts, TodoDockUiOpts, TodoDockUiResolved, TodoDockState, TodoListStyle, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures, DevicePreset, DeviceViewport, DeviceState, DeviceOrientation, } from "./highlights.js";
 export type { Flow, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, AssertBlock, AssertBlockOptions, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, Layout, LayoutOptions, MapBuilderOptions, } from "./engine.js";
 export type { ActionPage } from "./types.js";
 export { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";

package/dist/index.js

@@ -2,7 +2,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, 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 { 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 { discoverGraph, toMermaid, findOrphanBlocks, findBlockPath } from "./graph.js";
 export { isFileSelectToken, parseBlocksSelect, matchBlocksSelect, globToRegExp, } from "./blocks-select.js";
 export { EdgeLeaseCoordinator } from "./traverse-lease.js";

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, type TodoDockUiOpts } from "./highlights.js";
 /**
  * Bottom-left transient toast, separate from the persistent bottom-right
  * badge - real, direct user request: something that visibly flags "a
@@ -61,14 +61,30 @@ export declare function showPilotVision(page: Page, selector: string, label: str
 export type PilotFixtureRing = {
     selector: string;
     label: string;
+    /** 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). */
@@ -79,18 +95,41 @@ export type PilotHighlightFixtures = {
     todoIndex?: number;
     /** Optional title above the todo list. */
     todoTitle?: string;
+    /** Todo dock side. Default `right`. */
+    todoPos?: "left" | "right";
+    /**
+     * Todo-dock UX (compact / collision / behind-ring). Defaults smart-on;
+     * pass false fields to opt out. See {@link TodoDockUiOpts}.
+     */
+    todoUi?: TodoDockUiOpts;
     /**
      * 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, normalizeHighlightTone, normalizeHighlightSize, normalizeHighlightWeight, toneIconPrefix } from "./highlights.js";
+import { WAYGRAPH_RING_CSS, normalizeHighlightTone, normalizeHighlightSize, normalizeHighlightWeight, formatHighlightCaption, resolveDeviceState, resolveTodoDockUi, } 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,46 @@ 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;max-height:calc(100vh - 100px);overflow:auto;
   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;
+  box-shadow:0 2px 10px rgba(0,0,0,.3);pointer-events:auto;
+  transition:opacity .25s ease;
 }
+#wg-pilot-fx-todos.wg-todo-behind{z-index:2147483643;opacity:.42;pointer-events:none;}
+#wg-pilot-fx-todos[data-pos=left]{left:14px;right:auto;}
+#wg-pilot-fx-todos[data-pos=right]{right:14px;left:auto;}
 #wg-pilot-fx-todos .wg-pilot-fx-todo-title{font-weight:700;color:#c9a6ff;margin-bottom:6px;}
 #wg-pilot-fx-todos ol{margin:0;padding-left:18px;}
 #wg-pilot-fx-todos li{margin:3px 0;color:#ddd;}
 #wg-pilot-fx-todos li.wg-pilot-fx-todo-done{color:#888;text-decoration:line-through;}
 #wg-pilot-fx-todos li.wg-pilot-fx-todo-now{color:#fff;font-weight:700;}
+#wg-pilot-fx-todos[data-compact="1"]:not(:hover) li.wg-todo-fold{display:none;}
+#wg-pilot-fx-todos .wg-todo-more{margin-top:6px;padding:4px 8px;border-radius:8px;
+  background:rgba(124,58,237,.22);font:700 11px/1.2 system-ui,sans-serif;color:#e8dcff;}
+/* 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 +284,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,38 +293,169 @@ 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 ?? [])).map((r) => {
         const tone = normalizeHighlightTone(r.tone);
         const size = normalizeHighlightSize(r.size);
         const weight = normalizeHighlightWeight(r.weight);
-        const icon = toneIconPrefix(tone);
-        const label = icon && !r.label.startsWith(icon) ? `${icon} ${r.label}` : r.label;
+        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";
+    const todoUi = resolveTodoDockUi(fixtures.todoUi ?? null);
+    // 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, todoUi, }) => {
         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) {
@@ -306,14 +467,11 @@ export async function showPilotFixtures(page, fixtures) {
                 missing.push(ring.selector);
                 continue;
             }
-            const tone = ring.tone;
-            const size = ring.size;
-            const weight = ring.weight;
-            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`;
@@ -321,11 +479,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;
@@ -344,14 +505,29 @@ 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;
             dock.appendChild(title);
+            const WINDOW = todoUi.cap > 0 ? todoUi.cap : 5;
+            const compact = todoUi.compact !== false && todos.length > WINDOW;
+            if (compact)
+                dock.dataset.compact = "1";
+            let start = 0;
+            let end = todos.length;
+            if (compact) {
+                start = Math.max(0, todoIndex - Math.floor((WINDOW - 1) / 2));
+                end = Math.min(todos.length, start + WINDOW);
+                start = Math.max(0, end - WINDOW);
+            }
             const ol = document.createElement("ol");
             todos.forEach((text, i) => {
                 const li = document.createElement("li");
@@ -360,16 +536,81 @@ export async function showPilotFixtures(page, fixtures) {
                     li.className = "wg-pilot-fx-todo-done";
                 else if (i === todoIndex)
                     li.className = "wg-pilot-fx-todo-now";
+                if (compact && (i < start || i >= end))
+                    li.classList.add("wg-todo-fold");
                 ol.appendChild(li);
             });
             dock.appendChild(ol);
+            if (compact && todos.length - (end - start) > 0) {
+                const more = document.createElement("div");
+                more.className = "wg-todo-more";
+                more.textContent = "+" + (todos.length - (end - start)) + " more";
+                dock.appendChild(more);
+            }
             document.documentElement.appendChild(dock);
         }
-        if (holdMs > 0 && (painted > 0 || todos.length > 0)) {
+        if (focusBox)
+            applyFocus(focusBox);
+        // Dim todos under rings / focus so captions stay readable.
+        const dockEl = document.getElementById("wg-pilot-fx-todos");
+        if (dockEl && todoUi.behindRing !== false && (painted > 0 || focusBox)) {
+            dockEl.classList.add("wg-todo-behind");
+        }
+        // Collision flip: if a painted ring intersects the dock, flip side once.
+        if (dockEl && todoUi.collision !== false && painted > 0) {
+            const firstRing = document.querySelector(".wg-pilot-fx-ring");
+            if (firstRing) {
+                const rr = firstRing.getBoundingClientRect();
+                const dr = dockEl.getBoundingClientRect();
+                const hit = !(rr.right < dr.left || rr.left > dr.right || rr.bottom < dr.top || rr.top > dr.bottom);
+                if (hit) {
+                    dockEl.dataset.pos = dockEl.dataset.pos === "right" ? "left" : "right";
+                }
+            }
+        }
+        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,
+        todoUi,
+    })
         .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/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.5",
+  "version": "0.15.8",
   "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}'
 ```
 
+Supported fields (demo parity):
+- `rings[]`: `selector`, `label`, `detail`, `tag`, `tone`, `size`, `weight`, `color`, `zoom`, `zoomOut`, `focus`
+- `todos` / `todoIndex` / `todoTitle` / `todoPos` (`right` default | `left`)
+- `todoUi`: `{ compact?, cap?, expandCap?, collision?, behindRing? }` — same dock UX as demo (defaults smart-on; see README "Todo dock UI")
+- `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)
-- `holdMs`: ms to keep fixtures; `0` = until the next highlight / clear (default 12000)
 - 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