waygraph 0.15.25 → 0.15.26

package/dist/highlights/stub-ctx.js

@@ -0,0 +1,281 @@
+import { normalizeTodoPos, normalizeTodoStyle } from "./todo-dock.js";
+import { applyOrientation, normalizeDeviceOrientation, resolveDeviceState } from "./device.js";
+export function createStubCtx(bag, opts) {
+    return {
+        mem: opts.mem,
+        out: opts.out,
+        error: opts.error,
+        highlights(slots) {
+            bag.highlights = { ...(slots || {}) };
+        },
+        ring(id, stub) {
+            bag.highlights = { ...bag.highlights, [id]: stub };
+        },
+        todos(a, b, c) {
+            bag.todoTouched = true;
+            bag.hideTodos = false;
+            delete bag.todoGroups;
+            if (typeof a === "string") {
+                const id = String(a).trim();
+                if (id)
+                    bag.todoId = id;
+                else
+                    delete bag.todoId;
+                const items = (Array.isArray(b) ? b : []);
+                bag.todos = items;
+                const opts = (c && typeof c === "object" ? c : {});
+                if (opts.title != null)
+                    bag.todoTitle = String(opts.title);
+                if (opts.index != null)
+                    bag.todoIndex = Number(opts.index);
+                const st = normalizeTodoStyle(opts.style);
+                if (st)
+                    bag.todoStyle = st;
+                const pos = normalizeTodoPos(opts.pos);
+                if (pos)
+                    bag.todoPos = pos;
+                bag.todoParallel = opts.parallel === true;
+                if (!items.length)
+                    bag.hideTodos = true;
+                return;
+            }
+            bag.todos = a;
+            // Legacy list-only form: leave parallel unset (CLI treats as replace).
+            delete bag.todoParallel;
+            if (!a || !a.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;
+        },
+        device(preset) {
+            bag.deviceTouched = true;
+            bag.hideDevice = false;
+            const resolved = resolveDeviceState(preset, bag.touchOverride, bag.orientationOverride);
+            if (resolved) {
+                bag.device = resolved;
+                if (resolved.preset === "desktop" && !resolved.touchMode) {
+                    bag.hideDevice = true;
+                }
+            }
+        },
+        viewport(box) {
+            bag.deviceTouched = true;
+            bag.hideDevice = false;
+            const resolved = resolveDeviceState(box, bag.touchOverride, bag.orientationOverride);
+            if (resolved)
+                bag.device = resolved;
+        },
+        touch(on) {
+            bag.deviceTouched = true;
+            const enabled = on === undefined ? true : !!on;
+            bag.touchOverride = enabled;
+            if (enabled)
+                bag.hideDevice = false;
+            if (bag.device) {
+                bag.device = {
+                    ...bag.device,
+                    touchMode: enabled,
+                    hasTouch: bag.device.hasTouch || enabled,
+                };
+                if (enabled)
+                    bag.hideDevice = false;
+            }
+            else if (enabled) {
+                const base = resolveDeviceState("desktop", true, bag.orientationOverride);
+                if (base)
+                    bag.device = { ...base, touchMode: true, hasTouch: true };
+            }
+        },
+        orientation(o) {
+            const want = normalizeDeviceOrientation(o);
+            if (!want)
+                return;
+            bag.deviceTouched = true;
+            bag.hideDevice = false;
+            bag.orientationOverride = want;
+            const base = bag.device ||
+                resolveDeviceState("mobile", bag.touchOverride) ||
+                resolveDeviceState("mobile");
+            if (base)
+                bag.device = applyOrientation(base, want);
+        },
+        landscape() {
+            this.orientation("landscape");
+        },
+        portrait() {
+            this.orientation("portrait");
+        },
+        hideDevice() {
+            bag.deviceTouched = true;
+            bag.hideDevice = true;
+            bag.device = resolveDeviceState("desktop", false);
+            bag.touchOverride = false;
+            bag.orientationOverride = undefined;
+        },
+        clearDevice() {
+            bag.deviceTouched = true;
+            bag.hideDevice = true;
+            bag.device = resolveDeviceState("desktop", false);
+            bag.touchOverride = false;
+            bag.orientationOverride = undefined;
+        },
+        zoom(n) {
+            if (Number.isFinite(n) && n > 0)
+                bag.zoom = n;
+        },
+        zoomOut(keep) {
+            bag.zoomOut = !!keep;
+        },
+        title(text) {
+            bag.title = String(text ?? "");
+        },
+        banner(text) {
+            bag.title = String(text ?? "");
+        },
+        todoPos(side) {
+            const p = normalizeTodoPos(side);
+            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 };
+            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.touch !== undefined) {
+                bag.deviceTouched = true;
+                bag.touchOverride = !!partial.touch;
+            }
+            if (partial.orientation !== undefined) {
+                const want = normalizeDeviceOrientation(partial.orientation);
+                if (want) {
+                    bag.deviceTouched = true;
+                    bag.hideDevice = false;
+                    bag.orientationOverride = want;
+                    const base = bag.device ||
+                        resolveDeviceState("mobile", bag.touchOverride) ||
+                        resolveDeviceState("mobile");
+                    if (base)
+                        bag.device = applyOrientation(base, want);
+                }
+            }
+            if (partial.device !== undefined) {
+                bag.deviceTouched = true;
+                bag.hideDevice = false;
+                const resolved = resolveDeviceState(partial.device, bag.touchOverride, bag.orientationOverride);
+                if (resolved) {
+                    bag.device = resolved;
+                    if (resolved.preset === "desktop" && !resolved.touchMode)
+                        bag.hideDevice = true;
+                }
+            }
+            if (partial.viewport !== undefined) {
+                bag.deviceTouched = true;
+                bag.hideDevice = false;
+                const resolved = resolveDeviceState(partial.viewport, bag.touchOverride, bag.orientationOverride);
+                if (resolved)
+                    bag.device = resolved;
+            }
+            if (partial.zoom !== undefined && Number.isFinite(partial.zoom) && partial.zoom > 0) {
+                bag.zoom = partial.zoom;
+            }
+            if (partial.zoomOut !== undefined)
+                bag.zoomOut = !!partial.zoomOut;
+            if (partial.title !== undefined)
+                bag.title = String(partial.title ?? "");
+            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 };
+            }
+        },
+    };
+}
+/** Lift legacy per-slot todos (0.12.23) onto the phase bag once. */
+export function liftLegacySlotTodos(bag) {
+    if (bag.todos && bag.todos.length)
+        return;
+    for (const stub of Object.values(bag.highlights)) {
+        const legacy = stub;
+        if (legacy.todos && legacy.todos.length) {
+            bag.todos = legacy.todos;
+            if (legacy.todoIndex !== undefined)
+                bag.todoIndex = legacy.todoIndex;
+            return;
+        }
+    }
+}

package/dist/highlights/style.d.ts

@@ -0,0 +1,27 @@
+import type { HighlightSize, HighlightStyleDefaults, HighlightTone, HighlightWeight } from "./types.js";
+/** Apply Flow defaults under per-slot authored values (slot wins when set). */
+export declare function applyHighlightStyleDefaults<T extends {
+    tone?: HighlightTone | string;
+    size?: HighlightSize | string;
+    weight?: HighlightWeight | string;
+}>(slot: T, defaults?: HighlightStyleDefaults | null): T & {
+    tone: HighlightTone;
+    size: HighlightSize;
+    weight: HighlightWeight;
+};
+/** Map author aliases (`error` -> danger) to a canonical tone. */
+export declare function normalizeHighlightTone(raw: unknown): HighlightTone;
+/** Map size aliases to sm/md/lg. */
+export declare function normalizeHighlightSize(raw: unknown): HighlightSize;
+/** Map weight aliases to normal/bold. */
+export declare function normalizeHighlightWeight(raw: unknown): HighlightWeight;
+/** Prefix label with a short ASCII icon for semantic tones. */
+export declare function toneIconPrefix(tone: HighlightTone): string;
+/** Caption for ring / slide UI (label|caption + optional detail/tag + tone icon). */
+export declare function formatHighlightCaption(h: {
+    label?: string;
+    caption?: string;
+    detail?: string;
+    tag?: string;
+    tone?: HighlightTone | string;
+}): string;

package/dist/highlights/style.js

@@ -0,0 +1,84 @@
+/** Apply Flow defaults under per-slot authored values (slot wins when set). */
+export function applyHighlightStyleDefaults(slot, defaults) {
+    const tone = slot.tone !== undefined && slot.tone !== ""
+        ? normalizeHighlightTone(slot.tone)
+        : defaults?.tone !== undefined
+            ? normalizeHighlightTone(defaults.tone)
+            : "planned";
+    const size = slot.size !== undefined && slot.size !== ""
+        ? normalizeHighlightSize(slot.size)
+        : defaults?.size !== undefined
+            ? normalizeHighlightSize(defaults.size)
+            : "md";
+    const weight = slot.weight !== undefined && slot.weight !== ""
+        ? normalizeHighlightWeight(slot.weight)
+        : defaults?.weight !== undefined
+            ? normalizeHighlightWeight(defaults.weight)
+            : "normal";
+    return { ...slot, tone, size, weight };
+}
+const TONE_ICONS = {
+    planned: "",
+    auto: "",
+    info: "i",
+    warning: "!",
+    danger: "x",
+    success: "+",
+    orange: "",
+};
+/** Map author aliases (`error` -> danger) to a canonical tone. */
+export function normalizeHighlightTone(raw) {
+    if (typeof raw !== "string")
+        return "planned";
+    const t = raw.trim().toLowerCase();
+    if (t === "auto" || t === "automation" || t === "engine")
+        return "auto";
+    if (t === "info" || t === "blue")
+        return "info";
+    if (t === "warning" || t === "warn" || t === "yellow")
+        return "warning";
+    if (t === "danger" || t === "error" || t === "red")
+        return "danger";
+    if (t === "success" || t === "ok" || t === "green")
+        return "success";
+    if (t === "orange" || t === "amber" || t === "dom" || t === "inspect")
+        return "orange";
+    if (t === "planned" || t === "purple" || t === "authored")
+        return "planned";
+    return "planned";
+}
+/** Map size aliases to sm/md/lg. */
+export function normalizeHighlightSize(raw) {
+    if (typeof raw !== "string")
+        return "md";
+    const t = raw.trim().toLowerCase();
+    if (t === "sm" || t === "s" || t === "small" || t === "tiny")
+        return "sm";
+    if (t === "lg" || t === "l" || t === "large" || t === "big" || t === "xl")
+        return "lg";
+    return "md";
+}
+/** Map weight aliases to normal/bold. */
+export function normalizeHighlightWeight(raw) {
+    if (typeof raw !== "string")
+        return "normal";
+    const t = raw.trim().toLowerCase();
+    if (t === "bold" || t === "strong" || t === "heavy" || t === "b")
+        return "bold";
+    return "normal";
+}
+/** Prefix label with a short ASCII icon for semantic tones. */
+export function toneIconPrefix(tone) {
+    const icon = TONE_ICONS[tone];
+    return icon ? `[${icon}] ` : "";
+}
+/** Caption for ring / slide UI (label|caption + optional detail/tag + tone icon). */
+export function formatHighlightCaption(h) {
+    const tone = normalizeHighlightTone(h.tone);
+    const icon = toneIconPrefix(tone);
+    const primary = (h.label ?? h.caption ?? "").trim();
+    const tag = h.tag ? `[${h.tag}] ` : "";
+    if (h.detail)
+        return `${icon}${tag}${primary} - ${h.detail}`;
+    return `${icon}${tag}${primary}`;
+}

package/dist/highlights/todo-dock.d.ts

@@ -0,0 +1,52 @@
+import type { TodoDockState, TodoDockUiOpts, TodoDockUiResolved, TodoListStyle, WaygraphTodoGroupInput, WaygraphTodoInput, WaygraphTodoItem } from "./types.js";
+/**
+ * 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;
+/** 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 / bullets mode, todoIndex is ignored unless items omit explicit done
+ * (bullets never auto-mark current).
+ */
+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 / bullets 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 / bullets groups keep explicit done flags.
+ */
+export declare function completeSequentialTodoDock(dock: TodoDockState | undefined): TodoDockState | undefined;

package/dist/highlights/todo-dock.js

@@ -0,0 +1,248 @@
+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,
+    };
+}
+/** Normalize checklist dock side. */
+export function normalizeTodoPos(raw) {
+    const s = String(raw ?? "")
+        .trim()
+        .toLowerCase();
+    if (s === "left" || s === "l")
+        return "left";
+    if (s === "right" || s === "r")
+        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";
+    if (s === "bullets" ||
+        s === "bullet" ||
+        s === "list" ||
+        s === "ul" ||
+        s === "points" ||
+        s === "plain") {
+        return "bullets";
+    }
+    return undefined;
+}
+/**
+ * Normalize checklist rows; apply todoIndex for sequential done/current.
+ * In checklist / bullets mode, todoIndex is ignored unless items omit explicit done
+ * (bullets never auto-mark current).
+ */
+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 (style === "bullets") {
+            // Flat list: no walkthrough current; keep explicit done if authored.
+            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 };
+    // Title once on the dock - not also on the lone group (avoids duplicate headings).
+    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 / bullets 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 / bullets 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;
+                }),
+            };
+        }),
+    };
+}