waygraph 0.12.44 → 0.12.46

package/dist/cli.js

@@ -226,6 +226,10 @@ import {
   formatDemoPaceBadge,
   formatDemoPaceLabel,
   normalizeTodos,
+  buildTodoDock,
+  applyTodoPhase,
+  advanceTodoDock,
+  completeSequentialTodoDock,
 } from "waygraph";
 
 function walkDir(dir, pattern) {
@@ -1082,20 +1086,53 @@ async function installOverlay(page, title) {
         // Floating todo dock - lives outside #wg-panel so --mini / Hide never
         // hide the checklist. Click cycles left <-> right with CSS transform.
         // Authors set side via ctx.todoPos("left"|"right"); env / --todo-* fallback.
-        window.__wgSyncTodos = (list, pos) => {
-          list = Array.isArray(list) ? list : [];
-          const POS = ["left", "right"];
+        // Payload:
+        //   { sync: "clear" }                         -> remove dock
+        //   { sync: "keep" }                          -> leave dock alone (no wipe)
+        //   { sync: "set", dock } / { sync:"set", list } -> render / recreate
+        // Compat: bare array = set list (empty array = clear - legacy only).
+        window.__wgSyncTodos = (payload, pos) => {
+          let sync = "set";
+          let list = [];
+          let dockState = null;
+          let wantPos =
+            pos === "left" || pos === "right" ? pos : null;
+          if (Array.isArray(payload)) {
+            list = payload;
+            sync = list.length ? "set" : "clear";
+          } else if (payload && typeof payload === "object") {
+            sync = payload.sync === "clear" || payload.sync === "keep" ? payload.sync : "set";
+            dockState = payload.dock || null;
+            if (payload.pos === "left" || payload.pos === "right") wantPos = payload.pos;
+            if (Array.isArray(payload.list)) list = payload.list;
+            else if (dockState && Array.isArray(dockState.groups)) {
+              // Flatten for legacy callers; full dock rendered below when present.
+              list = [];
+              for (const g of dockState.groups) {
+                if (g && Array.isArray(g.items)) list = list.concat(g.items);
+              }
+            }
+          } else {
+            list = [];
+            sync = "clear";
+          }
+
           let dock = document.getElementById("wg-todo-dock");
           // Drop any in-panel leftover (old builds put #wg-todos in .wg-body).
           document.querySelectorAll("#wg-panel #wg-todos").forEach((el) => el.remove());
-          if (!list.length) {
+
+          // keep + no new payload: do not remove an existing dock (PIA #10).
+          if (sync === "keep") {
+            if (!dockState && !list.length) return;
+            // After navigation the DOM may be gone - recreate from carried dock.
+            sync = "set";
+          }
+          if (sync === "clear" || (sync === "set" && !dockState && !list.length)) {
             if (dock) dock.remove();
             return;
           }
-          const wantPos =
-            pos === "left" || pos === "right"
-              ? pos
-              : null;
+
+          const POS = ["left", "right"];
           if (!dock) {
             dock = document.createElement("div");
             dock.id = "wg-todo-dock";
@@ -1133,33 +1170,84 @@ async function installOverlay(page, title) {
               /* ignore */
             }
           }
+
           const esc = (s) =>
             String(s)
               .replace(/&/g, "&amp;")
               .replace(/</g, "&lt;")
-              .replace(/>/g, "&gt;");
-          dock.innerHTML =
-            '<ul id="wg-todos">' +
-            list
-              .map((t) => {
-                const cls = t.current
-                  ? "wg-todo-current"
-                  : t.done
-                    ? "wg-todo-done"
-                    : "wg-todo-pending";
-                const mark = t.done ? "\u2713" : t.current ? "\u2192" : "\u25CB";
-                return (
-                  '<li class="' +
-                  cls +
-                  '"><span class="wg-todo-mark">' +
-                  mark +
-                  "</span><span>" +
-                  esc(t.text || "") +
-                  "</span></li>"
-                );
-              })
-              .join("") +
-            "</ul>";
+              .replace(/>/g, "&gt;")
+              .replace(/"/g, "&quot;");
+          const attrId = (raw) => {
+            const id = raw != null && String(raw).trim() ? String(raw).trim() : "";
+            return id ? ' data-wg-todo-item="' + esc(id) + '"' : "";
+          };
+          const renderItems = (items, style) => {
+            const st = style === "checklist" ? "checklist" : "sequential";
+            return (
+              '<ul id="wg-todos" data-wg-todo-style="' +
+              st +
+              '">' +
+              (items || [])
+                .map((t) => {
+                  const cls = t.current
+                    ? "wg-todo-current"
+                    : t.done
+                      ? "wg-todo-done"
+                      : "wg-todo-pending";
+                  let mark;
+                  if (st === "checklist") {
+                    mark = t.done ? "\u2611" : "\u2610";
+                  } else {
+                    mark = t.done ? "\u2713" : t.current ? "\u2192" : "\u25CB";
+                  }
+                  const rowId = t.id || t.name || "";
+                  return (
+                    '<li class="' +
+                    cls +
+                    '"' +
+                    attrId(rowId) +
+                    '><span class="wg-todo-mark">' +
+                    mark +
+                    "</span><span>" +
+                    esc(t.text || "") +
+                    "</span></li>"
+                  );
+                })
+                .join("") +
+              "</ul>"
+            );
+          };
+
+          const dockId =
+            (dockState && dockState.id) ||
+            (payload && !Array.isArray(payload) && payload.todoId) ||
+            "";
+          if (dockId) dock.setAttribute("data-wg-todo-id", String(dockId));
+          else dock.removeAttribute("data-wg-todo-id");
+
+          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>";
+            }
+            for (const g of dockState.groups) {
+              const gTitle = g.title && String(g.title).trim();
+              const gid = g.id || g.name || "";
+              html +=
+                '<div class="wg-todo-group"' +
+                (gid ? ' data-wg-todo-group="' + esc(gid) + '"' : "") +
+                ">";
+              if (gTitle) {
+                html += '<div class="wg-todo-group-title">' + esc(gTitle) + "</div>";
+              }
+              html += renderItems(g.items, g.style || dockState.style);
+              html += "</div>";
+            }
+          } else {
+            html = renderItems(list, "sequential");
+          }
+          dock.innerHTML = html;
           if (window.__wgStampModal) {
             window.__wgStampModal(dock, "todos", { ready: true });
           }
@@ -1302,7 +1390,16 @@ async function renderBeforeStep(page, info) {
           forceCollapsed: info.forceCollapsed === true ? true : undefined,
         });
       }
-      if (window.__wgSyncTodos) window.__wgSyncTodos(info.todos || [], info.todoPos || null);
+      if (window.__wgSyncTodos) {
+        const sync = info.todoSync || (info.todos && info.todos.length ? "set" : "keep");
+        window.__wgSyncTodos({
+          sync: sync,
+          dock: info.todoDock || null,
+          list: info.todos || [],
+          pos: info.todoPos || null,
+          todoId: info.todoId || (info.todoDock && info.todoDock.id) || null,
+        });
+      }
       if (window.__wgStampModal) {
         window.__wgStampModal(panel, "panel", {
           phase: "before",
@@ -1840,7 +1937,16 @@ async function renderAfterStep(page, info) {
           forceCollapsed: info.forceCollapsed === true ? true : undefined,
         });
       }
-      if (window.__wgSyncTodos) window.__wgSyncTodos(info.todos || [], info.todoPos || null);
+      if (window.__wgSyncTodos) {
+        const sync = info.todoSync || (info.todos && info.todos.length ? "set" : "keep");
+        window.__wgSyncTodos({
+          sync: sync,
+          dock: info.todoDock || null,
+          list: info.todos || [],
+          pos: info.todoPos || null,
+          todoId: info.todoId || (info.todoDock && info.todoDock.id) || null,
+        });
+      }
       if (window.__wgStampModal) {
         window.__wgStampModal(panel, "panel", {
           phase: "after",
@@ -2908,6 +3014,8 @@ 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;
   for (let i = 0; i < resolved.length; i++) {
     const r = resolved[i];
     // The block breadcrumb is scoped to THIS step's own episode, not the
@@ -2993,13 +3101,24 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
     stubBeforeRef.current = stubBeforePhase.highlights.map((h) =>
       applyHighlightStyleDefaults(h, flowStyle),
     );
-    const stubBeforeTodos = stubBeforePhase.todos || [];
+    const appliedBefore = applyTodoPhase(lastTodoDock, {
+      todoSync: stubBeforePhase.todoSync,
+      todoDock: stubBeforePhase.todoDock,
+      todos: stubBeforePhase.todos,
+      todoPos: stubBeforePhase.todoPos,
+    });
+    lastTodoDock = appliedBefore.dock;
+    const stubBeforeTodos =
+      (lastTodoDock && lastTodoDock.groups[0] && lastTodoDock.groups[0].items) ||
+      stubBeforePhase.todos ||
+      [];
     const overlayTitle =
       (stubBeforePhase.title && String(stubBeforePhase.title).trim()) ||
       (r.episodeTitle && String(r.episodeTitle).trim()) ||
       title ||
       "waygraph demo";
-    const overlayTodoPos = stubBeforePhase.todoPos || undefined;
+    const overlayTodoPos =
+      (lastTodoDock && lastTodoDock.pos) || stubBeforePhase.todoPos || undefined;
     const isNavBlock = r.block.__waygraphKind === "nav";
     const autoNow = await currentAutoplay();
     // Video / --mini: compact pill. Never pass false - Hide/localStorage wins.
@@ -3051,6 +3170,9 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       stepperMode,
       forceCollapsed,
       todos: stubBeforeTodos,
+      todoDock: lastTodoDock,
+      todoSync: appliedBefore.sync,
+      todoId: lastTodoDock && lastTodoDock.id,
       ...paceSpeak,
     });
     const edits = await gate();
@@ -3206,16 +3328,28 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
     let stubAfterTodos = [];
     let afterOverlayTitle = overlayTitle;
     let afterTodoPos = overlayTodoPos;
+    let appliedAfter = { dock: lastTodoDock, sync: "keep" };
     if (hasAuthoredStubAfter(r.block, result, fixturesAfter)) {
       const afterPhase = await runStubPhase(r.block, "stubAfter", {
         out: result,
         fixtures: fixturesAfter,
       });
-      stubAfterTodos = afterPhase.todos || [];
+      appliedAfter = applyTodoPhase(lastTodoDock, {
+        todoSync: afterPhase.todoSync,
+        todoDock: afterPhase.todoDock,
+        todos: afterPhase.todos,
+        todoPos: afterPhase.todoPos,
+      });
+      lastTodoDock = appliedAfter.dock;
+      stubAfterTodos =
+        (lastTodoDock && lastTodoDock.groups[0] && lastTodoDock.groups[0].items) ||
+        afterPhase.todos ||
+        [];
       if (afterPhase.title && String(afterPhase.title).trim()) {
         afterOverlayTitle = String(afterPhase.title).trim();
       }
       if (afterPhase.todoPos) afterTodoPos = afterPhase.todoPos;
+      if (lastTodoDock && lastTodoDock.pos) afterTodoPos = lastTodoDock.pos;
       highlights = afterPhase.highlights.map((h) => {
         const styled = applyHighlightStyleDefaults(h, r.highlightStyle);
         return {
@@ -3255,6 +3389,9 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       episodeTitle: r.episodeTitle,
       stepperMode,
       todos: stubAfterTodos,
+      todoDock: lastTodoDock,
+      todoSync: appliedAfter.sync,
+      todoId: lastTodoDock && lastTodoDock.id,
       forceCollapsed:
         !!process.env.WAYGRAPH_VIDEO ||
         process.env.WAYGRAPH_MINI === "1" ||

package/dist/highlights.d.ts

@@ -34,17 +34,75 @@ export type FixtureDurationFields = {
  */
 export type WaygraphTodoItem = {
     text: string;
+    /**
+     * Stable id for external asserts / redirects (Mailhog, deep links).
+     * Stamped as `data-wg-todo-item` on the row.
+     */
+    id?: string;
+    /** Alias for {@link WaygraphTodoItem.id}. */
+    name?: string;
     /** Explicit done. If omitted, derived from todoIndex (index < todoIndex). */
     done?: boolean;
     /** Explicit current. If omitted, derived from todoIndex (index === todoIndex). */
     current?: boolean;
 };
 export type WaygraphTodoInput = string | WaygraphTodoItem;
+/**
+ * Dock list presentation:
+ * - `sequential` - arrow on current, strike done (demo walkthrough)
+ * - `checklist` - checkbox done/pending only (no current arrow; independent checks)
+ */
+export type TodoListStyle = "sequential" | "checklist";
+/** One titled group in the floating todo dock (FR / Scenarios / ACs, etc.). */
+export type WaygraphTodoGroupInput = {
+    /** Stable group id -> `data-wg-todo-group`. */
+    id?: string;
+    /** Alias for {@link WaygraphTodoGroupInput.id}. */
+    name?: string;
+    /** Group heading shown above the items. */
+    title?: string;
+    /** Per-group style; falls back to dock default ({@link StubCtx.todoStyle}). */
+    style?: TodoListStyle;
+    items: readonly WaygraphTodoInput[];
+    /** Sequential only: which item is current (0-based). */
+    todoIndex?: number;
+};
+export type WaygraphTodoGroup = {
+    id?: string;
+    title?: string;
+    style: TodoListStyle;
+    items: WaygraphTodoItem[];
+};
+/** Full floating dock payload passed to the browser. */
+export type TodoDockState = {
+    /**
+     * Stable dock id for external targeting after redirects
+     * (`#wg-todo-dock[data-wg-todo-id="…"]`).
+     */
+    id?: string;
+    /** Default style for groups that omit their own. */
+    style: TodoListStyle;
+    /** Single-list title when using {@link StubCtx.todos} + {@link StubCtx.todoTitle}. */
+    title?: string;
+    groups: WaygraphTodoGroup[];
+    pos?: "left" | "right";
+};
 /** Episode-level fixtures authored inside stubBefore/After/OnError(ctx). */
 export type StubPhaseFixtures = {
     todos?: readonly WaygraphTodoInput[];
     /** Which todo is current (0-based). Rows before = done, after = pending. */
     todoIndex?: number;
+    /** Heading above a single {@link StubCtx.todos} list. */
+    todoTitle?: string;
+    /**
+     * Stable dock id (`data-wg-todo-id`) for external redirect asserts
+     * (e.g. Mailhog -> back to app and still find the checklist).
+     */
+    todoId?: string;
+    /** `sequential` (default) or `checklist`. */
+    todoStyle?: TodoListStyle;
+    /** Multiple titled lists (FR / Scenarios / ACs). Wins over bare todos when set. */
+    todoGroups?: readonly WaygraphTodoGroupInput[];
     /**
      * Camera zoom (Screen Studio style) - scales the page toward the target /
      * cursor. Not element CSS zoom. Typical `1.25` .. `2`.
@@ -152,10 +210,34 @@ export type StubCtx<Out extends Checkpoint<string> = Checkpoint<string>> = {
     highlights(slots: HighlightStubPhase): void;
     /** Set / overwrite one named ring. */
     ring(id: string, stub: WaygraphHighlightStub): void;
-    /** Episode checklist (demo panel). */
+    /** Episode checklist (demo panel). Single list; use {@link StubCtx.todoGroups} for FR/AC packs. */
     todos(items: readonly WaygraphTodoInput[]): void;
     /** Current checklist index (bump for sequential plans). */
     todoIndex(n: number): void;
+    /** Heading above the single {@link StubCtx.todos} list. */
+    todoTitle(text: string): void;
+    /**
+     * Stable dock id for external selectors after redirects
+     * (`#wg-todo-dock[data-wg-todo-id="ep10-coverage"]`).
+     */
+    todoId(id: string): void;
+    /**
+     * Dock presentation: `sequential` (arrow walkthrough) or `checklist`
+     * (independent checkboxes, no current arrow).
+     */
+    todoStyle(style: TodoListStyle): void;
+    /**
+     * Multiple titled lists (e.g. Functional Requirements / Scenarios / ACs).
+     * Replaces a bare {@link StubCtx.todos} list when set.
+     */
+    todoGroups(groups: readonly WaygraphTodoGroupInput[]): void;
+    /**
+     * Hide the floating todo dock. Omit todos on a later block = **keep** the
+     * previous dock (carry forward). Only hideTodos / clearTodos / todos([]) clears it.
+     */
+    hideTodos(): void;
+    /** Alias for {@link StubCtx.hideTodos}. */
+    clearTodos(): void;
     /** Default camera zoom for rings without their own zoom. */
     zoom(n: number): void;
     /**
@@ -187,8 +269,17 @@ export type HighlightStubPhaseOrFn<Out extends Checkpoint<string>> = HighlightSt
 /** Result of running a stub phase (rings + episode fixtures). */
 export type StubPhaseResult = {
     highlights: ResolvedHighlight[];
+    /** Flattened first-group items (compat). Prefer {@link todoDock}. */
     todos: WaygraphTodoItem[];
     todoIndex?: number;
+    todoDock?: TodoDockState;
+    /**
+     * Todo dock intent for this phase:
+     * - `set` - replace dock with {@link todoDock}
+     * - `clear` - hide dock (author called hideTodos / empty todos())
+     * - `keep` - author omitted todos; demo must leave previous dock alone
+     */
+    todoSync?: "set" | "clear" | "keep";
     zoom?: number;
     zoomOut?: boolean;
     title?: string;
@@ -329,12 +420,51 @@ export interface WaygraphHighlight {
     tone?: HighlightTone;
 }
 export type ResolvedHighlight = WaygraphHighlightStub;
+/** Normalize checklist dock side. */
+export declare function normalizeTodoPos(raw: unknown): "left" | "right" | undefined;
+/** Normalize dock list style. */
+export declare function normalizeTodoStyle(raw: unknown): TodoListStyle | undefined;
 /**
  * Normalize checklist rows; apply todoIndex for sequential done/current.
+ * In checklist mode, todoIndex is ignored unless items omit explicit done.
  */
-export declare function normalizeTodos(todos: readonly WaygraphTodoInput[] | undefined, todoIndex?: number): WaygraphTodoItem[];
-/** Normalize checklist dock side. */
-export declare function normalizeTodoPos(raw: unknown): "left" | "right" | undefined;
+export declare function normalizeTodos(todos: readonly WaygraphTodoInput[] | undefined, todoIndex?: number, style?: TodoListStyle): WaygraphTodoItem[];
+/** Build the floating dock from bag / phase fields. */
+export declare function buildTodoDock(opts: {
+    todos?: readonly WaygraphTodoInput[] | undefined;
+    todoIndex?: number | undefined;
+    todoTitle?: string | undefined;
+    todoId?: string | undefined;
+    todoStyle?: TodoListStyle | undefined;
+    todoGroups?: readonly WaygraphTodoGroupInput[] | undefined;
+    todoPos?: "left" | "right" | undefined;
+}): TodoDockState | undefined;
+/**
+ * Carry-forward rules for the floating todo dock across demo steps.
+ * - clear: author called hideTodos / empty todos()
+ * - set: author authored a new dock this phase
+ * - keep: author omitted todos — preserve previous dock (do not wipe)
+ */
+export declare function applyTodoPhase(prev: TodoDockState | undefined, phase: {
+    todoSync?: "set" | "clear" | "keep";
+    todoDock?: TodoDockState;
+    todos?: WaygraphTodoItem[];
+    todoPos?: "left" | "right";
+    todoId?: string;
+}): {
+    dock: TodoDockState | undefined;
+    sync: "set" | "clear" | "keep";
+};
+/**
+ * Advance every sequential group to `index` (capped). Checklist groups unchanged.
+ * Used while cycling rings / fill/click stubs so the walkthrough moves.
+ */
+export declare function advanceTodoDock(dock: TodoDockState | undefined, index: number): TodoDockState | undefined;
+/**
+ * Mark sequential groups complete (all done, none current) - e.g. end of step.
+ * Checklist groups keep explicit done flags.
+ */
+export declare function completeSequentialTodoDock(dock: TodoDockState | undefined): TodoDockState | undefined;
 /**
  * Run an open stub lifecycle (preferred) or resolve a static slot map.
  * Returns rings + episode fixtures (todos / todoIndex / zoom).

package/dist/highlights.js

@@ -293,31 +293,6 @@ function pickStyleFields(base, patch) {
         out.weight = normalizeHighlightWeight(weight);
     return out;
 }
-/**
- * Normalize checklist rows; apply todoIndex for sequential done/current.
- */
-export function normalizeTodos(todos, todoIndex) {
-    if (!todos || todos.length === 0)
-        return [];
-    const idx = todoIndex !== undefined && Number.isFinite(todoIndex) ? Math.floor(todoIndex) : undefined;
-    return todos.map((t, i) => {
-        const text = typeof t === "string" ? t.trim() : String(t?.text ?? "").trim();
-        const item = { text: text || `Item ${i + 1}` };
-        if (typeof t === "object" && t) {
-            if (t.done !== undefined)
-                item.done = !!t.done;
-            if (t.current !== undefined)
-                item.current = !!t.current;
-        }
-        if (idx !== undefined) {
-            if (item.done === undefined)
-                item.done = i < idx;
-            if (item.current === undefined)
-                item.current = i === idx;
-        }
-        return item;
-    });
-}
 function pickZoom(base, patch) {
     const zoom = patch?.zoom !== undefined ? patch.zoom : base?.zoom;
     if (zoom !== undefined && Number.isFinite(zoom) && zoom > 0)
@@ -394,6 +369,180 @@ export function normalizeTodoPos(raw) {
         return "right";
     return undefined;
 }
+/** Normalize dock list style. */
+export function normalizeTodoStyle(raw) {
+    const s = String(raw ?? "")
+        .trim()
+        .toLowerCase();
+    if (s === "sequential" || s === "seq" || s === "steps" || s === "step")
+        return "sequential";
+    if (s === "checklist" || s === "check" || s === "checks" || s === "box")
+        return "checklist";
+    return undefined;
+}
+/**
+ * Normalize checklist rows; apply todoIndex for sequential done/current.
+ * In checklist mode, todoIndex is ignored unless items omit explicit done.
+ */
+export function normalizeTodos(todos, todoIndex, style = "sequential") {
+    if (!todos || todos.length === 0)
+        return [];
+    const idx = todoIndex !== undefined && Number.isFinite(todoIndex) ? Math.floor(todoIndex) : undefined;
+    return todos.map((t, i) => {
+        const text = typeof t === "string" ? t.trim() : String(t?.text ?? "").trim();
+        const item = { text: text || `Item ${i + 1}` };
+        if (typeof t === "object" && t) {
+            if (t.done !== undefined)
+                item.done = !!t.done;
+            if (t.current !== undefined)
+                item.current = !!t.current;
+            const idRaw = t.id ?? t.name;
+            if (idRaw != null && String(idRaw).trim())
+                item.id = String(idRaw).trim();
+        }
+        if (style === "checklist") {
+            if (item.done === undefined)
+                item.done = false;
+            item.current = false;
+            return item;
+        }
+        if (idx !== undefined) {
+            if (item.done === undefined)
+                item.done = i < idx;
+            if (item.current === undefined)
+                item.current = i === idx;
+        }
+        return item;
+    });
+}
+/** Build the floating dock from bag / phase fields. */
+export function buildTodoDock(opts) {
+    const style = normalizeTodoStyle(opts.todoStyle) || "sequential";
+    const pos = normalizeTodoPos(opts.todoPos);
+    const dockId = opts.todoId != null && String(opts.todoId).trim() ? String(opts.todoId).trim() : undefined;
+    if (opts.todoGroups && opts.todoGroups.length) {
+        const groups = opts.todoGroups
+            .map((g) => {
+            const gs = normalizeTodoStyle(g.style) || style;
+            const items = normalizeTodos(g.items, g.todoIndex, gs);
+            if (!items.length)
+                return null;
+            const group = { style: gs, items };
+            if (g.title && String(g.title).trim())
+                group.title = String(g.title).trim();
+            const gid = g.id ?? g.name;
+            if (gid != null && String(gid).trim())
+                group.id = String(gid).trim();
+            return group;
+        })
+            .filter((g) => !!g);
+        if (!groups.length)
+            return undefined;
+        const dock = { style, groups };
+        if (pos)
+            dock.pos = pos;
+        if (dockId)
+            dock.id = dockId;
+        return dock;
+    }
+    const items = normalizeTodos(opts.todos, opts.todoIndex, style);
+    if (!items.length)
+        return undefined;
+    const group = { style, items };
+    if (opts.todoTitle && String(opts.todoTitle).trim()) {
+        group.title = String(opts.todoTitle).trim();
+    }
+    const dock = { style, groups: [group] };
+    if (opts.todoTitle && String(opts.todoTitle).trim()) {
+        dock.title = String(opts.todoTitle).trim();
+    }
+    if (pos)
+        dock.pos = pos;
+    if (dockId)
+        dock.id = dockId;
+    return dock;
+}
+/**
+ * Carry-forward rules for the floating todo dock across demo steps.
+ * - clear: author called hideTodos / empty todos()
+ * - set: author authored a new dock this phase
+ * - keep: author omitted todos — preserve previous dock (do not wipe)
+ */
+export function applyTodoPhase(prev, phase) {
+    const sync = phase.todoSync ||
+        (phase.todoDock ? "set" : phase.todos && phase.todos.length ? "set" : "keep");
+    if (sync === "clear")
+        return { dock: undefined, sync: "clear" };
+    if (sync === "set") {
+        if (phase.todoDock)
+            return { dock: phase.todoDock, sync: "set" };
+        if (phase.todos && phase.todos.length) {
+            const dock = buildTodoDock({
+                todos: phase.todos,
+                ...(phase.todoPos ? { todoPos: phase.todoPos } : {}),
+                ...(phase.todoId ? { todoId: phase.todoId } : {}),
+            });
+            return { dock, sync: "set" };
+        }
+        return { dock: undefined, sync: "clear" };
+    }
+    return { dock: prev, sync: "keep" };
+}
+/**
+ * Advance every sequential group to `index` (capped). Checklist groups unchanged.
+ * Used while cycling rings / fill/click stubs so the walkthrough moves.
+ */
+export function advanceTodoDock(dock, index) {
+    if (!dock || !dock.groups.length)
+        return dock;
+    const i = Number.isFinite(index) ? Math.max(0, Math.floor(index)) : 0;
+    return {
+        ...dock,
+        groups: dock.groups.map((g) => {
+            if (g.style !== "sequential")
+                return g;
+            const capped = Math.min(i, Math.max(0, g.items.length - 1));
+            const raw = g.items.map((it) => {
+                const row = { text: it.text };
+                if (it.id)
+                    row.id = it.id;
+                else if (it.name)
+                    row.id = it.name;
+                return row;
+            });
+            return {
+                ...g,
+                items: normalizeTodos(raw, capped, "sequential"),
+            };
+        }),
+    };
+}
+/**
+ * Mark sequential groups complete (all done, none current) - e.g. end of step.
+ * Checklist groups keep explicit done flags.
+ */
+export function completeSequentialTodoDock(dock) {
+    if (!dock)
+        return dock;
+    return {
+        ...dock,
+        groups: dock.groups.map((g) => {
+            if (g.style !== "sequential")
+                return g;
+            return {
+                ...g,
+                items: g.items.map((it) => {
+                    const row = { text: it.text, done: true, current: false };
+                    if (it.id)
+                        row.id = it.id;
+                    else if (it.name)
+                        row.id = it.name;
+                    return row;
+                }),
+            };
+        }),
+    };
+}
 function createStubCtx(bag, opts) {
     return {
         out: opts.out,
@@ -405,11 +554,52 @@ function createStubCtx(bag, opts) {
             bag.highlights = { ...bag.highlights, [id]: stub };
         },
         todos(items) {
+            bag.todoTouched = true;
+            bag.hideTodos = false;
             bag.todos = items;
+            delete bag.todoGroups;
+            // Empty list = explicit clear (same as hideTodos).
+            if (!items || !items.length)
+                bag.hideTodos = true;
         },
         todoIndex(n) {
             bag.todoIndex = n;
         },
+        todoTitle(text) {
+            bag.todoTitle = String(text ?? "");
+        },
+        todoId(id) {
+            bag.todoTouched = true;
+            const cleaned = String(id ?? "").trim();
+            if (cleaned)
+                bag.todoId = cleaned;
+            else
+                delete bag.todoId;
+        },
+        todoStyle(style) {
+            const s = normalizeTodoStyle(style);
+            if (s)
+                bag.todoStyle = s;
+        },
+        todoGroups(groups) {
+            bag.todoTouched = true;
+            bag.hideTodos = false;
+            bag.todoGroups = groups;
+            if (!groups || !groups.length)
+                bag.hideTodos = true;
+        },
+        hideTodos() {
+            bag.todoTouched = true;
+            bag.hideTodos = true;
+            bag.todos = [];
+            delete bag.todoGroups;
+        },
+        clearTodos() {
+            bag.todoTouched = true;
+            bag.hideTodos = true;
+            bag.todos = [];
+            delete bag.todoGroups;
+        },
         zoom(n) {
             if (Number.isFinite(n) && n > 0)
                 bag.zoom = n;
@@ -431,10 +621,33 @@ function createStubCtx(bag, opts) {
         set(partial) {
             if (partial.highlights)
                 bag.highlights = { ...partial.highlights };
-            if (partial.todos !== undefined)
+            if (partial.todos !== undefined) {
+                bag.todoTouched = true;
+                bag.hideTodos = !partial.todos || !partial.todos.length;
                 bag.todos = partial.todos;
+                if (partial.todoGroups === undefined)
+                    delete bag.todoGroups;
+            }
             if (partial.todoIndex !== undefined)
                 bag.todoIndex = partial.todoIndex;
+            if (partial.todoTitle !== undefined)
+                bag.todoTitle = String(partial.todoTitle ?? "");
+            if (partial.todoId !== undefined) {
+                bag.todoTouched = true;
+                const cleaned = String(partial.todoId ?? "").trim();
+                if (cleaned)
+                    bag.todoId = cleaned;
+                else
+                    delete bag.todoId;
+            }
+            const ts = normalizeTodoStyle(partial.todoStyle);
+            if (ts)
+                bag.todoStyle = ts;
+            if (partial.todoGroups !== undefined) {
+                bag.todoTouched = true;
+                bag.hideTodos = !partial.todoGroups || !partial.todoGroups.length;
+                bag.todoGroups = partial.todoGroups;
+            }
             if (partial.zoom !== undefined && Number.isFinite(partial.zoom) && partial.zoom > 0) {
                 bag.zoom = partial.zoom;
             }
@@ -576,11 +789,35 @@ export async function runStubPhase(block, phase, opts) {
     let highlights = mergePhaseMaps(bag.highlights, fixturePhase);
     highlights = applyDefaultZoom(highlights, bag.zoom);
     highlights = applyDefaultZoomOut(highlights, bag.zoomOut);
-    const todos = normalizeTodos(bag.todos, bag.todoIndex);
+    const todoDock = bag.hideTodos
+        ? undefined
+        : buildTodoDock({
+            todos: bag.todos,
+            todoIndex: bag.todoIndex,
+            todoTitle: bag.todoTitle,
+            todoId: bag.todoId,
+            todoStyle: bag.todoStyle,
+            todoGroups: bag.todoGroups,
+            todoPos: bag.todoPos,
+        });
+    const todos = todoDock?.groups[0]?.items ||
+        (bag.hideTodos
+            ? []
+            : normalizeTodos(bag.todos, bag.todoIndex, normalizeTodoStyle(bag.todoStyle) || "sequential"));
+    // Omit todos entirely => keep previous dock. Explicit empty / hideTodos => clear.
+    const todoSync = bag.hideTodos
+        ? "clear"
+        : bag.todoTouched && todoDock
+            ? "set"
+            : bag.todoTouched && !todoDock
+                ? "clear"
+                : "keep";
     return {
         highlights,
         todos,
+        todoSync,
         ...(bag.todoIndex !== undefined ? { todoIndex: bag.todoIndex } : {}),
+        ...(todoDock ? { todoDock } : {}),
         ...(bag.zoom !== undefined ? { zoom: bag.zoom } : {}),
         ...(bag.zoomOut !== undefined ? { zoomOut: bag.zoomOut } : {}),
         ...(bag.title !== undefined && bag.title !== "" ? { title: bag.title } : {}),

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 } from "./trait.js";
 export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, } 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, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
-export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, WaygraphTodoItem, WaygraphTodoInput, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures, } 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, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } from "./highlights.js";
+export type { WaygraphHighlightStub, WaygraphHighlightFixture, WaygraphSlide, WaygraphTodoItem, WaygraphTodoInput, WaygraphTodoGroup, WaygraphTodoGroupInput, TodoDockState, TodoListStyle, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, StubCtx, StubLifecycleFn, StubPhaseResult, StubPhaseFixtures, } from "./highlights.js";
 export type { Flow, EngineConfig, ComposedBlock, FastForwardComposedBlock, RunGraphOptions, BlockInfo, NavBlock, NavBlockOptions, NavClickBlock, NavClickBlockOptions, MethodBlock, ActionBlock, PageBlock, PageBlockOptions, PageMethodEntry, EffectBlock, MemEffectBlock, MemNavBlock, } 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 } from "./trait.js";
 export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, chainFlow, } 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, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } 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, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, } 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/examples/saucedemo/package-lock.json

@@ -17,7 +17,7 @@
       }
     },
     "../..": {
-      "version": "0.12.43",
+      "version": "0.12.46",
       "license": "MIT",
       "dependencies": {
         "tsx": "^4.0.0"

package/examples/saucedemo/src/blocks/saucedemo-web/cart/nav-cart.block.ts

@@ -17,7 +17,12 @@ export const NavCartBlock = defineNavClickBlock<CartPage>({
   verify: [Trait.url({ pathname: "/cart.html" })],
   stubBefore: (ctx) => {
     ctx.title("Open cart");
-    ctx.todos(["Find the product", "Add to cart", "Open cart"]);
+    ctx.todoId("saucedemo-cart");
+    ctx.todos([
+      { id: "cart-find", text: "Find the product" },
+      { id: "cart-add", text: "Add to cart" },
+      { id: "cart-open", text: "Open cart" },
+    ]);
     ctx.todoIndex(2);
     ctx.zoom(1.4);
     ctx.zoomOut(false);

package/examples/saucedemo/src/blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.ts

@@ -36,7 +36,12 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
     // Demo: zoom product -> add (stay zoomed), then badge after act.
     stubBefore: (ctx) => {
       ctx.title("Pick a product");
-      ctx.todos(["Find the product", "Add to cart", "Open cart"]);
+      ctx.todoId("saucedemo-cart");
+      ctx.todos([
+        { id: "cart-find", text: "Find the product" },
+        { id: "cart-add", text: "Add to cart" },
+        { id: "cart-open", text: "Open cart" },
+      ]);
       ctx.todoIndex(0);
       ctx.zoom(1.35);
       ctx.zoomOut(false);
@@ -63,7 +68,12 @@ export const AddToCartBlock = defineEffectBlock<Checkpoint<string>, ItemInCart>(
     },
     stubAfter: (ctx) => {
       ctx.banner("In the cart");
-      ctx.todos(["Find the product", "Add to cart", "Open cart"]);
+      ctx.todoId("saucedemo-cart");
+      ctx.todos([
+        { id: "cart-find", text: "Find the product" },
+        { id: "cart-add", text: "Add to cart" },
+        { id: "cart-open", text: "Open cart" },
+      ]);
       ctx.todoIndex(1);
       ctx.zoomOut(false);
       ctx.ring("badge", {

package/examples/saucedemo/src/blocks/saucedemo-web/methods/submit-login.method.block.ts

@@ -49,7 +49,12 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
     // sequential highlight queue (appear / dwell / fade), focus + color.
     stubBefore: (ctx) => {
       ctx.title("Signing in");
-      ctx.todos(["Enter username", "Enter password", "Click Login"]);
+      ctx.todoId("saucedemo-login");
+      ctx.todos([
+        { id: "login-user", text: "Enter username" },
+        { id: "login-pass", text: "Enter password" },
+        { id: "login-submit", text: "Click Login" },
+      ]);
       ctx.todoIndex(0);
       ctx.zoom(1.35);
       ctx.highlights({
@@ -82,7 +87,12 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
       // inventory shelf. Success (LoggedIn) hands off to shopFlow.
       if (ctx.out && ctx.out.__state === "LoginPage") {
         ctx.title("Login blocked");
-        ctx.todos(["Enter username", "Enter password", "Click Login"]);
+        ctx.todoId("saucedemo-login");
+        ctx.todos([
+          { id: "login-user", text: "Enter username" },
+          { id: "login-pass", text: "Enter password" },
+          { id: "login-submit", text: "Click Login" },
+        ]);
         ctx.todoIndex(2);
         ctx.ring("error", {
           selector: '[data-test="error"]',
@@ -95,7 +105,12 @@ export const SubmitLoginActionBlock = defineMethodBlock<LoginPage, LoginSubmitOu
         return;
       }
       ctx.banner("Inventory");
-      ctx.todos(["Enter username", "Enter password", "Click Login"]);
+      ctx.todoId("saucedemo-login");
+      ctx.todos([
+        { id: "login-user", text: "Enter username" },
+        { id: "login-pass", text: "Enter password" },
+        { id: "login-submit", text: "Click Login" },
+      ]);
       ctx.todoIndex(2);
       // Landed on inventory - hand off to shopFlow for product -> cart zoom.
       ctx.ring("shelf", {

package/package.json

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