waygraph 0.15.7 → 0.15.9

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/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;
         }
@@ -6727,8 +6915,9 @@ function applyRunFlags(flags, opts) {
             process.env.WAYGRAPH_HEADED = "0";
         }
     }
-    if ((flags.fast || flags.fullStepper || flags.miniStepper || flags.todoPos) && !opts?.allowDemoUi) {
-        console.error("waygraph: --fast / --full / --mini / --todo-left|--todo-right are demo-only flags");
+    if ((flags.fast || flags.fullStepper || flags.miniStepper || flags.todoPos || flags.todoUiFull || flags.todoUiSmart) &&
+        !opts?.allowDemoUi) {
+        console.error("waygraph: --fast / --full / --mini / --todo-left|--todo-right / --todo-full|--todo-smart are demo-only flags");
         process.exit(1);
     }
     if (flags.step === true) {
@@ -6782,6 +6971,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 +7225,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, type DevicePreset, type DeviceState } 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
@@ -97,6 +97,11 @@ export type PilotHighlightFixtures = {
     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 `30000` (30s) unless specified.

package/dist/pilot-overlay.js

@@ -1,4 +1,4 @@
-import { WAYGRAPH_RING_CSS, normalizeHighlightTone, normalizeHighlightSize, normalizeHighlightWeight, formatHighlightCaption, resolveDeviceState, } 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,11 +88,13 @@ 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;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;}
@@ -100,6 +102,9 @@ const OVERLAY_CSS = `
 #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);
@@ -318,6 +323,7 @@ export async function showPilotFixtures(page, fixtures) {
     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
@@ -368,7 +374,7 @@ export async function showPilotFixtures(page, fixtures) {
                 ? fixtures.device
                 : fixtures.device.preset || "device";
     return page
-        .evaluate(({ rings, todos, todoIndex, todoTitle, todoPos, holdMs, zoom, zoomSelector, zoomOut, clearAll, deviceLabel, }) => {
+        .evaluate(({ rings, todos, todoIndex, todoTitle, todoPos, holdMs, zoom, zoomSelector, zoomOut, clearAll, deviceLabel, todoUi, }) => {
         const w = window;
         if (w.__wgPilotFxHideTimer)
             clearTimeout(w.__wgPilotFxHideTimer);
@@ -511,6 +517,17 @@ export async function showPilotFixtures(page, fixtures) {
             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");
@@ -519,13 +536,38 @@ 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 (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) {
@@ -567,6 +609,7 @@ export async function showPilotFixtures(page, fixtures) {
         zoomOut,
         clearAll: fixtures.clear === true,
         deviceLabel,
+        todoUi,
     })
         .catch(() => ({ painted: 0, missing: rings.map((r) => r.selector) }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.7",
+  "version": "0.15.9",
   "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

@@ -39,6 +39,7 @@ 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)