waygraph 0.12.21 → 0.12.23

package/bin/waygraph

@@ -1,13 +1,48 @@
-#!/bin/sh
-# Two cwd/symlink pitfalls this resolves, both real, both hit in practice:
-#  - `--import tsx/esm` is a bare specifier - Node resolves it as if from an
-#    unnamed module at the CALLER's cwd, not this script's install
-#    directory, so it broke when invoked from anywhere else.
-#  - `npm link` makes this script reachable via a SYMLINK (e.g.
-#    ~/.nvm/.../bin/waygraph) - `dirname "$0"` alone follows argv[0], not the
-#    symlink target, so it resolved to the nvm bin dir instead of this
-#    package. `readlink -f` follows the symlink to the real file first.
-SOURCE="$(readlink -f "$0")"
-DIR="$(cd "$(dirname "$SOURCE")/.." && pwd)"
-TSX_ESM="$(cd "$DIR" && node -e "console.log(require.resolve('tsx/esm'))")"
-exec node --import "$TSX_ESM" "$DIR/dist/cli.js" "$@"
+#!/usr/bin/env node
+/**
+ * Cross-platform CLI launcher.
+ *
+ * Why Node (not #!/bin/sh + readlink -f):
+ *   - macOS BSD `readlink` has no `-f` (GNU) -> "illegal option -- f" / broken bin
+ *   - Windows npm expects a Node shebang for `.cmd` shims
+ *
+ * Still registers `tsx/esm` before `dist/cli.js` so consumer `.block.ts` /
+ * `.flow.ts` dynamic imports resolve the same as the old shell wrapper.
+ */
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const require = createRequire(join(pkgRoot, "package.json"));
+let tsxEsm;
+try {
+  tsxEsm = require.resolve("tsx/esm");
+} catch (err) {
+  console.error(
+    "waygraph: cannot resolve dependency \"tsx\" (required to load .ts Blocks).\n" +
+      "  Reinstall: npm install waygraph\n" +
+      `  Detail: ${err instanceof Error ? err.message : String(err)}`,
+  );
+  process.exit(1);
+}
+
+const cli = join(pkgRoot, "dist", "cli.js");
+const child = spawn(
+  process.execPath,
+  ["--import", tsxEsm, cli, ...process.argv.slice(2)],
+  { stdio: "inherit", env: process.env, windowsHide: true },
+);
+
+child.on("error", (err) => {
+  console.error(`waygraph: failed to start CLI: ${err.message}`);
+  process.exit(1);
+});
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 1);
+});

package/dist/auto-explore-run.js

@@ -468,22 +468,16 @@ function printCliMenu(menu, library) {
     console.log("  [q] quit");
     console.log("");
 }
-async function cliPick(menu) {
-    const rl = createInterface({ input, output });
-    try {
-        while (true) {
-            const ans = (await rl.question("Choose: ")).trim().toLowerCase();
-            if (ans === "q" || ans === "quit")
-                return { type: "quit" };
-            const n = Number(ans);
-            if (Number.isInteger(n) && n >= 1 && n <= menu.flat.length) {
-                return { type: "pick", index: n - 1 };
-            }
-            console.log("Enter a number from the list, or q to quit.");
+async function cliPick(menu, rl) {
+    while (true) {
+        const ans = (await rl.question("Choose: ")).trim().toLowerCase();
+        if (ans === "q" || ans === "quit")
+            return { type: "quit" };
+        const n = Number(ans);
+        if (Number.isInteger(n) && n >= 1 && n <= menu.flat.length) {
+            return { type: "pick", index: n - 1 };
         }
-    }
-    finally {
-        rl.close();
+        console.log("Enter a number from the list, or q to quit.");
     }
 }
 /**
@@ -544,6 +538,7 @@ export async function runAutoExplore(projectDir, options = {}) {
         wiredPage = target;
     }
     let here = null;
+    const cliRl = cli ? createInterface({ input, output }) : null;
     try {
         for (;;) {
             page = await ensureLivePage(context, page, startUrl);
@@ -572,9 +567,9 @@ export async function runAutoExplore(projectDir, options = {}) {
                     break;
             }
             let pick;
-            if (cli) {
+            if (cli && cliRl) {
                 printCliMenu(menu, library.byName);
-                pick = await cliPick(menu);
+                pick = await cliPick(menu, cliRl);
             }
             else {
                 pick = await headfulPick(page, menu, library.byName, mem, () => pickWait.promise);
@@ -614,6 +609,7 @@ export async function runAutoExplore(projectDir, options = {}) {
         }
     }
     finally {
+        cliRl?.close();
         await context.close();
         await browser.close();
     }

package/dist/cli.js

@@ -224,6 +224,7 @@ import {
   demoPaceIsSlow,
   formatDemoPaceBadge,
   formatDemoPaceLabel,
+  normalizeTodos,
 } from "waygraph";
 
 function walkDir(dir, pattern) {
@@ -507,6 +508,14 @@ const RING_CSS =
   "#wg-panel .wg-pace[data-pace-kind=blitz] .wg-pace-badge{background:#22C55E;color:#052e16;}" +
   "#wg-panel .wg-pace[data-pace-kind=ms] .wg-pace-badge{background:#3B82F6;color:#fff;}" +
   "#wg-panel .wg-narration{margin:0 0 12px;font:italic 14px/1.4 system-ui,sans-serif;color:#f0e8ff;}" +
+  "#wg-todos{list-style:none;margin:0 0 12px;padding:8px 10px;background:#0f0620;border-radius:8px;" +
+  "border:1px solid #3a2a60;}" +
+  "#wg-todos li{display:flex;gap:8px;align-items:flex-start;margin:0 0 6px;font:600 12.5px/1.35 system-ui,sans-serif;}" +
+  "#wg-todos li:last-child{margin-bottom:0;}" +
+  "#wg-todos .wg-todo-mark{flex:0 0 auto;width:1.1em;text-align:center;}" +
+  "#wg-todos .wg-todo-done{color:#6ee7b7;text-decoration:line-through;opacity:.85;}" +
+  "#wg-todos .wg-todo-current{color:#fff;}" +
+  "#wg-todos .wg-todo-pending{color:#9a7ad1;}" +
   "#wg-progress{height:4px;background:#2a1650;border-radius:2px;margin:0 0 12px;overflow:hidden;}" +
   "#wg-progress-bar{height:100%;background:#7C3AED;border-radius:2px;transition:width .3s ease;}" +
   // A real tab bar for episodes - the currently-active episode reads as
@@ -767,6 +776,31 @@ async function installOverlay(page, title) {
           const ringLabel = document.getElementById("wg-ring-label");
           if (ring) ring.style.opacity = "0";
           if (ringLabel) ringLabel.style.opacity = "0";
+          if (window.__wgClearZoom) window.__wgClearZoom();
+        };
+        window.__wgClearZoom = () => {
+          document.querySelectorAll("[data-wg-zoomed=\\"1\\"]").forEach((el) => {
+            el.style.removeProperty("transform");
+            el.style.removeProperty("transform-origin");
+            el.style.removeProperty("transition");
+            el.style.removeProperty("z-index");
+            el.style.removeProperty("position");
+            delete el.dataset.wgZoomed;
+          });
+        };
+        window.__wgApplyZoom = (sel, scale) => {
+          if (window.__wgClearZoom) window.__wgClearZoom();
+          const n = Number(scale);
+          if (!Number.isFinite(n) || n <= 1.001) return;
+          const el = document.querySelector(sel);
+          if (!el) return;
+          const st = getComputedStyle(el);
+          if (st.position === "static") el.style.position = "relative";
+          el.style.zIndex = "2147483645";
+          el.style.transition = "transform .35s ease";
+          el.style.transformOrigin = "center center";
+          el.style.transform = "scale(" + n + ")";
+          el.dataset.wgZoomed = "1";
         };
         const POSITIONS = ["left", "center", "right"];
         const applyPos = (el, pos) => {
@@ -988,7 +1022,8 @@ async function renderBeforeStep(page, info) {
         paceHtml +
         "<div id=\\"wg-modules\\" class=\\"" + modulesClass + "\\">" + modulesHtml + "</div>" +
         "<h3>Step " + (info.index + 1) + " / " + info.total + " - " + info.blockName + "</h3>" +
-        narrationHtml;
+        narrationHtml +
+        todosHtmlFromInfo(info, esc);
       if (info.keys.length === 0) {
         html += "<div class=\\"wg-key\\">(no MemKeys required)</div>";
       }
@@ -1021,12 +1056,7 @@ async function renderBeforeStep(page, info) {
       }
       if (window.__wgWirePanelChrome) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
-          stepLabel:
-            (info.index + 1) +
-            " / " +
-            info.total +
-            (info.blockName ? " · " + info.blockName : "") +
-            (info.paceBadge ? " · " + info.paceBadge : ""),
+          stepLabel: miniStepLabel(info),
           forceCollapsed: info.forceCollapsed === true ? true : info.forceCollapsed === false ? false : undefined,
         });
       }
@@ -1103,6 +1133,102 @@ async function renderBeforeStep(page, info) {
     .catch(() => {});
 }
 
+async function ensureSelectorInView(page, selector) {
+  try {
+    const loc = page.locator(selector).first();
+    await loc.scrollIntoViewIfNeeded().catch(() => {});
+    await page
+      .evaluate((sel) => {
+        const el = document.querySelector(sel);
+        if (!el) return;
+        try {
+          el.scrollIntoView({ block: "center", inline: "center", behavior: "instant" });
+        } catch {
+          try {
+            el.scrollIntoView(true);
+          } catch {
+            /* ignore */
+          }
+        }
+        let p = el.parentElement;
+        while (p && p !== document.documentElement && p !== document.body) {
+          const st = getComputedStyle(p);
+          const ox = st.overflowX;
+          const oy = st.overflowY;
+          if (/(auto|scroll|overlay)/.test(ox) || /(auto|scroll|overlay)/.test(oy)) {
+            const er = el.getBoundingClientRect();
+            const pr = p.getBoundingClientRect();
+            if (er.left < pr.left || er.right > pr.right || er.top < pr.top || er.bottom > pr.bottom) {
+              p.scrollLeft += er.left + er.width / 2 - (pr.left + pr.width / 2);
+              p.scrollTop += er.top + er.height / 2 - (pr.top + pr.height / 2);
+            }
+          }
+          p = p.parentElement;
+        }
+      }, selector)
+      .catch(() => {});
+  } catch {
+    /* best-effort */
+  }
+}
+
+async function applyHighlightZoom(page, selector, zoom) {
+  const z = Number(zoom);
+  if (!Number.isFinite(z) || z <= 1.001) {
+    await page.evaluate(() => {
+      if (window.__wgClearZoom) window.__wgClearZoom();
+    }).catch(() => {});
+    return;
+  }
+  await page
+    .evaluate(
+      ({ sel, scale }) => {
+        if (window.__wgApplyZoom) window.__wgApplyZoom(sel, scale);
+      },
+      { sel: selector, scale: z },
+    )
+    .catch(() => {});
+}
+
+function todosHtmlFromInfo(info, escFn) {
+  const list = info.todos || [];
+  if (!list.length) return "";
+  return (
+    "<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>" +
+          escFn(t.text || "") +
+          "</span></li>"
+        );
+      })
+      .join("") +
+    "</ul>"
+  );
+}
+
+function miniStepLabel(info) {
+  const ep =
+    info.episodeNumber !== undefined && info.episodeNumber !== null
+      ? "Ep " + info.episodeNumber + " \\u00b7 "
+      : "";
+  return (
+    ep +
+    (info.index + 1) +
+    " / " +
+    info.total +
+    (info.blockName ? " \\u00b7 " + info.blockName : "") +
+    (info.paceBadge ? " \\u00b7 " + info.paceBadge : "")
+  );
+}
+
 async function cycleHighlightRings(page, highlights, gatesFast, opts) {
   const list = highlights || [];
   // defaultHoldMs: when set (fail path), use instead of legacy 900/200 so BUG
@@ -1112,12 +1238,47 @@ async function cycleHighlightRings(page, highlights, gatesFast, opts) {
   for (let i = 0; i < list.length; i++) {
     const h = list[i];
     try {
+      await ensureSelectorInView(page, h.selector);
+      await applyHighlightZoom(page, h.selector, h.zoom);
       const box = await page.locator(h.selector).first().boundingBox();
       if (box) {
         await showRing(page, box, h.label, h.tone || "planned", {
           size: h.size,
           weight: h.weight,
         });
+        if (h.todos && h.todos.length) {
+          const rows = normalizeTodos(h.todos, h.todoIndex);
+          await page
+            .evaluate((todos) => {
+              const ul = document.getElementById("wg-todos");
+              if (!ul) return;
+              ul.innerHTML = todos
+                .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";
+                  const esc = (s) =>
+                    String(s)
+                      .replace(/&/g, "&amp;")
+                      .replace(/</g, "&lt;")
+                      .replace(/>/g, "&gt;");
+                  return (
+                    "<li class=\\"" +
+                    cls +
+                    "\\"><span class=\\"wg-todo-mark\\">" +
+                    mark +
+                    "</span><span>" +
+                    esc(t.text || "") +
+                    "</span></li>"
+                  );
+                })
+                .join("");
+            }, rows)
+            .catch(() => {});
+        }
         const authored = resolveFixtureDwellMs(h, { gatesFast, pace });
         const legacyMs = i === list.length - 1 ? 200 : 900;
         const holdMs =
@@ -1261,6 +1422,7 @@ async function renderAfterStep(page, info) {
         paceHtml +
         "<div id=\\"wg-modules\\" class=\\"" + modulesClass + "\\">" + modulesHtml + "</div>" +
         "<h3>" + heading + "</h3>" +
+        todosHtmlFromInfo(info, escA) +
         resultHtml +
         gateHtml;
       if (isNewPanel) {
@@ -1269,12 +1431,7 @@ async function renderAfterStep(page, info) {
       }
       if (window.__wgWirePanelChrome) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
-          stepLabel:
-            (info.index + 1) +
-            " / " +
-            info.total +
-            (info.blockName ? " · " + info.blockName : "") +
-            (info.paceBadge ? " · " + info.paceBadge : ""),
+          stepLabel: miniStepLabel(info),
           forceCollapsed: info.forceCollapsed === true ? true : info.forceCollapsed === false ? false : undefined,
         });
       }
@@ -1376,12 +1533,7 @@ async function renderStepError(page, info) {
       }
       if (window.__wgWirePanelChrome) {
         window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
-          stepLabel:
-            (info.index + 1) +
-            " / " +
-            info.total +
-            (info.blockName ? " · " + info.blockName : "") +
-            (info.paceBadge ? " · " + info.paceBadge : ""),
+          stepLabel: miniStepLabel(info),
           forceCollapsed: info.forceCollapsed === true ? true : info.forceCollapsed === false ? false : undefined,
         });
       }
@@ -1609,6 +1761,8 @@ async function presentSlides(page, slides, _gate, opts) {
     await installOverlay(page, title);
     if (s.selector) {
       try {
+        await ensureSelectorInView(page, s.selector);
+        await applyHighlightZoom(page, s.selector, s.zoom);
         const box = await page.locator(s.selector).first().boundingBox();
         if (box) await showRing(page, box, caption, slideTone, slideStyle);
       } catch {
@@ -1696,11 +1850,14 @@ async function presentSlides(page, slides, _gate, opts) {
         if (window.__wgWirePanelChrome) {
           window.__wgWirePanelChrome(panel, "wg-panel-hidden", "waygraph demo", {
             stepLabel:
+              (info.episodeNumber !== undefined && info.episodeNumber !== null
+                ? "Ep " + info.episodeNumber + " \\u00b7 "
+                : "") +
               "Slide " +
               (info.index + 1) +
               " / " +
               info.total +
-              (info.blockName ? " · " + info.blockName : ""),
+              (info.blockName ? " \\u00b7 " + info.blockName : ""),
             forceCollapsed: false,
           });
         }
@@ -2416,6 +2573,12 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       episodeTitle: r.episodeTitle,
       stepperMode,
       forceCollapsed,
+      todos: (() => {
+        for (const h of stubBeforeRef.current || []) {
+          if (h.todos && h.todos.length) return normalizeTodos(h.todos, h.todoIndex);
+        }
+        return [];
+      })(),
       ...paceSpeak,
     });
     const edits = await gate();
@@ -2487,6 +2650,9 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
             tone: styled.tone,
             size: styled.size,
             weight: styled.weight,
+            todos: styled.todos,
+            todoIndex: styled.todoIndex,
+            zoom: styled.zoom,
           };
         });
         await cycleHighlightRings(page, errHighlights, !!pacing.gatesFast, {
@@ -2569,6 +2735,9 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
             tone: styled.tone,
             size: styled.size,
             weight: styled.weight,
+            todos: styled.todos,
+            todoIndex: styled.todoIndex,
+            zoom: styled.zoom,
           };
         },
       );
@@ -2596,6 +2765,12 @@ async function runStepMode(engine, start, end, context, page, mem, resolved, slo
       episodeNumber: r.episodeNumber,
       episodeTitle: r.episodeTitle,
       stepperMode,
+      todos: (() => {
+        for (const h of highlights || []) {
+          if (h.todos && h.todos.length) return normalizeTodos(h.todos, h.todoIndex);
+        }
+        return [];
+      })(),
       // After a nav under auto-next, stay compact until the next action block expands.
       forceCollapsed: !!process.env.WAYGRAPH_VIDEO || ((await currentAutoplay()) && isNavBlock),
     });
@@ -2690,7 +2865,7 @@ async function runChainedFlows(chainFlow, chainFlows, context, mem, page) {
 /** Parses WAYGRAPH_VIDEO_VIEWPORT / --video-viewport: "1920x1080" or "1920,1080". */
 function parseVideoViewport(raw) {
   if (!raw || !raw.trim()) return null;
-  const m = raw.trim().match(/^(\d{3,5})[xX,](\d{3,5})$/);
+  const m = raw.trim().match(/^(\\d{3,5})[xX,](\\d{3,5})$/);
   if (!m) return null;
   const width = Number(m[1]);
   const height = Number(m[2]);
@@ -2981,7 +3156,13 @@ async function main() {
       ...(executablePath ? { executablePath } : {}),
     });
     const contextOpts = fixedVideoViewport
-      ? { baseURL, viewport: fixedVideoViewport }
+      ? {
+          baseURL,
+          viewport: fixedVideoViewport,
+          // Lock DPR so --video-viewport 800x450 stays 800x450 in the .webm
+          // (HiDPI hosts otherwise scale recordVideo to e.g. 1920x1080).
+          deviceScaleFactor: 1,
+        }
       : step
         ? { baseURL, viewport: null }
         : { baseURL, viewport: { width: 1280, height: 720 } };

package/dist/highlights.d.ts

@@ -24,6 +24,18 @@ export type FixtureDurationFields = {
      */
     fastMode?: number;
 };
+/**
+ * One checklist row for episode planning (demo panel).
+ * Prefer {@link WaygraphHighlightStub.todoIndex} for sequential done/current.
+ */
+export type WaygraphTodoItem = {
+    text: 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;
 /** One named highlight slot on a block (selector + caption). */
 export interface WaygraphHighlightStub extends FixtureDurationFields {
     selector: string;
@@ -50,9 +62,25 @@ export interface WaygraphHighlightStub extends FixtureDurationFields {
      * Aliases: regular, strong.
      */
     weight?: HighlightWeight;
+    /**
+     * Simple episode checklist (demo panel). Same lifecycle as this stub
+     * (stubBefore / stubAfter / stubOnError). Strings or `{ text, done?, current? }`.
+     */
+    todos?: readonly WaygraphTodoInput[];
+    /**
+     * Which todo is current (0-based). Rows before = done, after = pending.
+     * Authored `done`/`current` on an item still win when set.
+     * Bump in a stub phase function for sequential plans.
+     */
+    todoIndex?: number;
+    /**
+     * Magnify the target element while this ring is shown (e.g. `1.35`).
+     * Cleared when the ring hides / next highlight starts. `1` or omit = off.
+     */
+    zoom?: number;
 }
 /** Flow fixture patch: label required; selector optional (inherits from stub). */
-export type WaygraphHighlightFixture = Partial<Pick<WaygraphHighlightStub, "selector">> & Required<Pick<WaygraphHighlightStub, "label">> & Pick<WaygraphHighlightStub, "detail" | "tag" | "tone" | "size" | "weight"> & FixtureDurationFields;
+export type WaygraphHighlightFixture = Partial<Pick<WaygraphHighlightStub, "selector">> & Required<Pick<WaygraphHighlightStub, "label">> & Pick<WaygraphHighlightStub, "detail" | "tag" | "tone" | "size" | "weight" | "todos" | "todoIndex" | "zoom"> & FixtureDurationFields;
 export type HighlightStubPhase = Record<string, WaygraphHighlightStub>;
 export type HighlightStubPhaseOrFn<Out extends Checkpoint<string>> = HighlightStubPhase | ((out: Out) => HighlightStubPhase);
 /**
@@ -69,6 +97,8 @@ export interface WaygraphSlide extends FixtureDurationFields {
     tone?: HighlightTone;
     size?: HighlightSize;
     weight?: HighlightWeight;
+    /** Magnify selector target while this slide is showing (same as stub zoom). */
+    zoom?: number;
 }
 /**
  * Demo ring tones (iconified).
@@ -188,6 +218,10 @@ export interface WaygraphHighlight {
     tone?: HighlightTone;
 }
 export type ResolvedHighlight = WaygraphHighlightStub;
+/**
+ * Normalize checklist rows; apply todoIndex for sequential done/current.
+ */
+export declare function normalizeTodos(todos: readonly WaygraphTodoInput[] | undefined, todoIndex?: number): WaygraphTodoItem[];
 /**
  * Resolve ordered highlight slots for a phase, merging flow fixtures over block stubs.
  * Shim: empty stubAfter + legacy `instruction.highlights` -> auto-keyed stubAfter.

package/dist/highlights.js

@@ -289,11 +289,50 @@ 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 pickTodoFields(base, patch) {
+    const out = {};
+    const todos = patch?.todos !== undefined ? patch.todos : base?.todos;
+    const todoIndex = patch?.todoIndex !== undefined ? patch.todoIndex : base?.todoIndex;
+    const zoom = patch?.zoom !== undefined ? patch.zoom : base?.zoom;
+    if (todos !== undefined)
+        out.todos = todos;
+    if (todoIndex !== undefined)
+        out.todoIndex = todoIndex;
+    if (zoom !== undefined && Number.isFinite(zoom) && zoom > 0)
+        out.zoom = zoom;
+    return out;
+}
 function mergeSlot(base, patch) {
     if (!base && !patch)
         return null;
     const dwell = pickDurationFields(base, patch);
     const style = pickStyleFields(base, patch);
+    const todos = pickTodoFields(base, patch);
     if (!base && patch) {
         if (!patch.selector)
             return null;
@@ -304,6 +343,7 @@ function mergeSlot(base, patch) {
             ...(patch.tag ? { tag: patch.tag } : {}),
             ...style,
             ...dwell,
+            ...todos,
         };
     }
     if (base && !patch) {
@@ -312,6 +352,7 @@ function mergeSlot(base, patch) {
             ...(base.tone ? { tone: normalizeHighlightTone(base.tone) } : {}),
             ...(base.size ? { size: normalizeHighlightSize(base.size) } : {}),
             ...(base.weight ? { weight: normalizeHighlightWeight(base.weight) } : {}),
+            ...pickTodoFields(base, undefined),
         };
     }
     return {
@@ -325,6 +366,7 @@ function mergeSlot(base, patch) {
         ...(patch.tag !== undefined ? { tag: patch.tag } : base.tag ? { tag: base.tag } : {}),
         ...style,
         ...dwell,
+        ...todos,
     };
 }
 function phaseFromLegacyHighlights(highlights) {

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, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, 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, FixtureDurationFields, HighlightStubPhase, HighlightStubPhaseName, HighlightFixtureMap, ResolvedHighlight, WaygraphHighlight, HighlightTone, HighlightSize, HighlightWeight, HighlightStyleDefaults, DemoPace, DemoPaceName, } from "./highlights.js";
+export { resolveHighlightSlots, resolveSlides, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, 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, } 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, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, 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, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, 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/package.json

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