@sphynxoid/stepwise 0.1.0 → 0.3.0

package/dist/index.js

@@ -59,15 +59,30 @@ function useSteps(items, opts) {
 
 // src/use-step-player.ts
 import { useCallback as useCallback2, useEffect as useEffect2, useMemo as useMemo2, useRef as useRef2, useState as useState2 } from "react";
-function useStepPlayer({ total, baseDelayMs = 900, autoPlay = false, engine, syncHash, onEnd }) {
+function useStepPlayer({
+  total,
+  baseDelayMs = 900,
+  autoPlay = false,
+  engine,
+  syncHash,
+  onEnd,
+  respectReducedMotion = true,
+  holdAt,
+  follow = false
+}) {
   const core = useSteps(total);
+  const { go, next: coreNext, prev: corePrev, first } = core;
   const [started, setStarted] = useState2(autoPlay && total > 0);
-  const [playing, setPlaying] = useState2(autoPlay && total > 0);
+  const [playing, setPlaying] = useState2(autoPlay && (total > 0 || follow));
   const [speed, setSpeed] = useState2(1);
   const [ended, setEnded] = useState2(false);
   const endedRef = useRef2(false);
   const onEndRef = useRef2(onEnd);
   onEndRef.current = onEnd;
+  const holdAtRef = useRef2(holdAt);
+  holdAtRef.current = holdAt;
+  const [held, setHeld] = useState2(null);
+  const releasedRef = useRef2(/* @__PURE__ */ new Set());
   const markEnded = useCallback2(() => {
     if (endedRef.current) return;
     endedRef.current = true;
@@ -81,10 +96,21 @@ function useStepPlayer({ total, baseDelayMs = 900, autoPlay = false, engine, syn
   }, []);
   const index = started && core.index >= 0 ? core.index : -1;
   const atEnd = total > 0 && index >= 0 && index >= total - 1;
-  const engineRef = useRef2(engine);
-  engineRef.current = engine;
+  const live = follow && held === null && (started ? playing || atEnd : playing);
   const totalRef = useRef2(total);
   totalRef.current = total;
+  const cursorRef = useRef2(core.index);
+  cursorRef.current = core.index;
+  const playingRef = useRef2(playing);
+  playingRef.current = playing;
+  const atEndRef = useRef2(atEnd);
+  atEndRef.current = atEnd;
+  const heldRef = useRef2(held);
+  heldRef.current = held;
+  const startedRef = useRef2(started);
+  startedRef.current = started;
+  const engineRef = useRef2(engine);
+  engineRef.current = engine;
   const engineApiRef = useRef2({});
   useEffect2(() => {
     if (!engine) return;
@@ -92,7 +118,7 @@ function useStepPlayer({ total, baseDelayMs = 900, autoPlay = false, engine, syn
       get total() {
         return totalRef.current;
       },
-      onFrame: (f) => core.go(f),
+      onFrame: (f) => go(f),
       onEnd: () => {
         markEnded();
         setPlaying(false);
@@ -108,90 +134,135 @@ function useStepPlayer({ total, baseDelayMs = 900, autoPlay = false, engine, syn
       engineApiRef.current = {};
       handle.disconnect();
     };
-  }, [engine]);
+  }, [engine, go, markEnded]);
+  useEffect2(() => {
+    if (!respectReducedMotion || !autoPlay) return;
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
+    if (!window.matchMedia("(prefers-reduced-motion: reduce)").matches) return;
+    setPlaying(false);
+    engineApiRef.current.pause?.();
+  }, []);
   const start = useCallback2(() => {
     setStarted(true);
     setPlaying(true);
     clearEnded();
-    core.first();
+    setHeld(null);
+    releasedRef.current = /* @__PURE__ */ new Set();
+    first();
     if (engineRef.current) {
       engineApiRef.current.seek?.(0);
       engineApiRef.current.play?.();
     }
-  }, [core]);
+  }, [first, clearEnded]);
   const reset = useCallback2(() => {
     setStarted(false);
     setPlaying(false);
     clearEnded();
+    setHeld(null);
+    releasedRef.current = /* @__PURE__ */ new Set();
     if (engineRef.current) engineApiRef.current.pause?.();
   }, [clearEnded]);
   const seek = useCallback2(
     (f) => {
-      if (total === 0) return;
+      const t = totalRef.current;
+      if (t === 0) return;
       setStarted(true);
       setPlaying(false);
       clearEnded();
-      core.go(Math.max(0, Math.min(f, total - 1)));
+      setHeld(null);
+      go(Math.max(0, Math.min(f, t - 1)));
       if (engineRef.current) {
         engineApiRef.current.pause?.();
         engineApiRef.current.seek?.(f);
       }
     },
-    [total, core, clearEnded]
+    [go, clearEnded]
   );
   const next = useCallback2(
     (onEmpty) => {
       setPlaying(false);
-      if (total === 0) {
+      const t = totalRef.current;
+      if (t === 0) {
         onEmpty?.();
         return;
       }
       setStarted(true);
       clearEnded();
-      core.next();
+      setHeld(null);
+      const target = Math.min(cursorRef.current + 1, t - 1);
+      coreNext();
       if (engineRef.current) {
         engineApiRef.current.pause?.();
-        engineApiRef.current.seek?.(Math.min(core.index + 1, total - 1));
+        engineApiRef.current.seek?.(target);
       }
     },
-    [total, core, clearEnded]
+    [coreNext, clearEnded]
   );
   const prev = useCallback2(() => {
     setPlaying(false);
     clearEnded();
-    core.prev();
+    setHeld(null);
+    const target = Math.max(0, cursorRef.current - 1);
+    corePrev();
     if (engineRef.current) {
       engineApiRef.current.pause?.();
-      engineApiRef.current.seek?.(Math.max(0, core.index - 1));
+      engineApiRef.current.seek?.(target);
     }
-  }, [core, clearEnded]);
+  }, [corePrev, clearEnded]);
   const toggle = useCallback2(
     (onEmpty) => {
-      if (total === 0) {
+      if (totalRef.current === 0) {
         onEmpty?.();
         return;
       }
-      if (!playing && atEnd) {
-        setStarted(true);
-        setPlaying(true);
-        clearEnded();
-        core.first();
-        if (engineRef.current) {
-          engineApiRef.current.seek?.(0);
-          engineApiRef.current.play?.();
-        }
+      if (!playingRef.current && atEndRef.current) {
+        start();
         return;
       }
-      const nextPlaying = !playing;
+      const nextPlaying = !playingRef.current;
       setPlaying(nextPlaying);
       setStarted(true);
+      if (nextPlaying) {
+        releasedRef.current.add(cursorRef.current);
+        setHeld(null);
+      }
       if (engineRef.current) {
         if (nextPlaying) engineApiRef.current.play?.();
         else engineApiRef.current.pause?.();
       }
     },
-    [total, playing, atEnd, core, clearEnded]
+    [start]
   );
+  const release = useCallback2(() => {
+    const h = heldRef.current;
+    if (h === null) return;
+    releasedRef.current.add(h);
+    setHeld(null);
+    setPlaying(true);
+  }, []);
+  const jump = useCallback2(
+    (f) => {
+      const t = totalRef.current;
+      if (t === 0) return;
+      setStarted(true);
+      go(Math.max(0, Math.min(f, t - 1)));
+      if (engineRef.current) engineApiRef.current.seek?.(f);
+    },
+    [go]
+  );
+  const goLive = useCallback2(() => {
+    const t = totalRef.current;
+    if (t === 0) return;
+    setStarted(true);
+    setPlaying(false);
+    clearEnded();
+    setHeld(null);
+    go(t - 1);
+    if (engineRef.current) {
+      engineApiRef.current.pause?.();
+      engineApiRef.current.seek?.(t - 1);
+    }
+  }, [go, clearEnded]);
   const changeSpeed = useCallback2((s) => {
     setSpeed(s);
     if (engineRef.current) engineApiRef.current.rate?.(s);
@@ -199,6 +270,21 @@ function useStepPlayer({ total, baseDelayMs = 900, autoPlay = false, engine, syn
   useEffect2(() => {
     clearEnded();
   }, [total, clearEnded]);
+  const prevTotal = useRef2(total);
+  useEffect2(() => {
+    const before = prevTotal.current;
+    prevTotal.current = total;
+    if (!follow || engineRef.current || total <= before) return;
+    if (heldRef.current !== null) return;
+    if (!startedRef.current) {
+      if (playingRef.current) setStarted(true);
+      return;
+    }
+    if (playingRef.current || cursorRef.current >= before - 1) setPlaying(true);
+  }, [total, follow]);
+  useEffect2(() => {
+    if (held !== null && held !== core.index) setHeld(null);
+  }, [held, core.index]);
   useEffect2(() => {
     if (engineRef.current) return;
     if (!playing || !started || total === 0) return;
@@ -207,34 +293,49 @@ function useStepPlayer({ total, baseDelayMs = 900, autoPlay = false, engine, syn
       setPlaying(false);
       return;
     }
-    const id = setTimeout(() => core.next(), baseDelayMs / speed);
+    if (holdAtRef.current?.(core.index) && !releasedRef.current.has(core.index)) {
+      setHeld(core.index);
+      setPlaying(false);
+      return;
+    }
+    const id = setTimeout(() => coreNext(), baseDelayMs / speed);
     return () => clearTimeout(id);
-  }, [playing, started, core, total, speed, baseDelayMs, markEnded]);
-  const hashKey = syncHash;
-  const coreGoRef = useRef2(core.go);
-  coreGoRef.current = core.go;
+  }, [playing, started, core.index, coreNext, total, speed, baseDelayMs, markEnded]);
   const lastWrittenHash = useRef2("");
+  const pendingRead = useRef2(null);
   const readHash = useCallback2(() => {
-    if (!hashKey || typeof window === "undefined" || total === 0) return;
+    const t = totalRef.current;
+    if (!syncHash || typeof window === "undefined" || t === 0) return;
     const hash = window.location.hash;
     if (hash === lastWrittenHash.current) return;
-    const match = hash.match(new RegExp(`[#&]${hashKey}=(\\d+)`));
-    if (!match) return;
-    const f = Number(match[1]);
-    if (Number.isFinite(f) && f >= 0 && f < total) {
+    const value = readHashParam(hash, syncHash);
+    if (value === null || !/^\d+$/.test(value)) return;
+    const f = Number(value);
+    if (f < t) {
+      pendingRead.current = f;
       setStarted(true);
-      coreGoRef.current(f);
+      go(f);
     }
-  }, [hashKey, total]);
+  }, [syncHash, go]);
+  const linkedRead = useRef2(false);
   useEffect2(() => {
     readHash();
+    linkedRead.current = totalRef.current > 0;
     const onHashChange = () => readHash();
     window.addEventListener("hashchange", onHashChange);
     return () => window.removeEventListener("hashchange", onHashChange);
   }, [readHash]);
+  useEffect2(() => {
+    if (linkedRead.current || total === 0) return;
+    linkedRead.current = true;
+    readHash();
+  }, [total, readHash]);
   useEffect2(() => {
     if (!syncHash || index < 0 || typeof window === "undefined") return;
-    const next2 = `#${syncHash}=${index}`;
+    const pending2 = pendingRead.current;
+    pendingRead.current = null;
+    if (pending2 !== null && pending2 !== index) return;
+    const next2 = writeHashParam(window.location.hash, syncHash, String(index));
     if (window.location.hash !== next2) {
       lastWrittenHash.current = next2;
       window.history.replaceState(null, "", next2);
@@ -249,6 +350,11 @@ function useStepPlayer({ total, baseDelayMs = 900, autoPlay = false, engine, syn
       speed,
       atEnd,
       ended,
+      held,
+      release,
+      jump,
+      live,
+      goLive,
       start,
       reset,
       seek,
@@ -258,28 +364,598 @@ function useStepPlayer({ total, baseDelayMs = 900, autoPlay = false, engine, syn
       setPlaying,
       setSpeed: changeSpeed
     }),
-    [total, index, playing, speed, atEnd, ended, start, reset, seek, next, prev, toggle, changeSpeed]
+    [total, index, playing, speed, atEnd, ended, held, release, jump, live, goLive, start, reset, seek, next, prev, toggle, changeSpeed]
+  );
+}
+function hashParts(hash) {
+  const body = hash.startsWith("#") ? hash.slice(1) : hash;
+  return body ? body.split("&") : [];
+}
+function readHashParam(hash, key) {
+  for (const part of hashParts(hash)) {
+    const eq = part.indexOf("=");
+    if (eq > 0 && part.slice(0, eq) === key) return part.slice(eq + 1);
+  }
+  return null;
+}
+function writeHashParam(hash, key, value) {
+  const parts = hashParts(hash);
+  const pair = `${key}=${value}`;
+  const i = parts.findIndex((p) => p.startsWith(`${key}=`));
+  if (i >= 0) parts[i] = pair;
+  else parts.push(pair);
+  return `#${parts.join("&")}`;
+}
+
+// src/use-trace.ts
+import { useCallback as useCallback3, useEffect as useEffect3, useLayoutEffect, useMemo as useMemo3, useReducer, useRef as useRef3 } from "react";
+
+// src/reanchor.ts
+function reanchor(oldSteps, oldIndex, newSteps, keyOf) {
+  if (newSteps.length === 0) return -1;
+  if (oldIndex < 0 || oldSteps.length === 0) return 0;
+  const positions = /* @__PURE__ */ new Map();
+  newSteps.forEach((s, i) => {
+    const k = keyOf(s, i);
+    if (k !== void 0 && !positions.has(k)) positions.set(k, i);
+  });
+  for (let i = Math.min(oldIndex, oldSteps.length - 1); i >= 0; i--) {
+    const k = keyOf(oldSteps[i], i);
+    if (k === void 0) continue;
+    const j = positions.get(k);
+    if (j !== void 0) return j;
+  }
+  return 0;
+}
+var stepKey = (step) => step !== null && typeof step === "object" && typeof step.key === "string" ? step.key : void 0;
+
+// src/use-trace.ts
+var useIsomorphicLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect3;
+function useTrace(steps, opts) {
+  const { keyOf, holdAt, ...playerOpts } = opts ?? {};
+  const stepsRef = useRef3(steps);
+  const player = useStepPlayer({
+    ...playerOpts,
+    total: steps.length,
+    holdAt: holdAt ? (f) => holdAt(f, stepsRef.current[f]) : void 0
+  });
+  stepsRef.current = steps;
+  const keyFn = keyOf ?? stepKey;
+  const shownRef = useRef3({ steps, index: player.index });
+  const shown = shownRef.current;
+  let anchored = null;
+  if (shown.steps !== steps && shown.index >= 0) {
+    const i = shown.index;
+    const k = i < shown.steps.length ? keyFn(shown.steps[i], i) : void 0;
+    if (k !== void 0 && i < steps.length && keyFn(steps[i], i) === k) anchored = i;
+    else if (steps.some((s, j) => keyFn(s, j) !== void 0)) anchored = reanchor(shown.steps, i, steps, keyFn);
+  }
+  const index = anchored ?? player.index;
+  const { jump } = player;
+  const [, rerender] = useReducer((n) => n + 1, 0);
+  useIsomorphicLayoutEffect(() => {
+    shownRef.current = { steps, index };
+    if (anchored === null) return;
+    if (anchored >= 0 && anchored !== player.index) jump(anchored);
+    rerender();
+  });
+  const frame = steps.length === 0 ? -1 : Math.max(0, Math.min(index, steps.length - 1));
+  const step = frame >= 0 ? steps[frame] : void 0;
+  const toneAt = useCallback3((i) => stepsRef.current[i]?.tone ?? "neutral", []);
+  const titleAt = useCallback3((i) => stepsRef.current[i]?.label ?? `step ${i + 1}`, []);
+  return useMemo3(() => ({ player, step, frame, toneAt, titleAt }), [player, step, frame, toneAt, titleAt]);
+}
+
+// src/use-simulation.ts
+import { useMemo as useMemo4 } from "react";
+
+// src/simulation.ts
+function hashSeed(seed) {
+  let h = 2166136261;
+  for (let i = 0; i < seed.length; i++) {
+    h ^= seed.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+function createRng(seed = 0) {
+  const base = typeof seed === "string" ? hashSeed(seed) : seed >>> 0;
+  let state = base;
+  const next = () => {
+    state = state + 1831565813 >>> 0;
+    let t = state;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+  const int = (min, max) => min + Math.floor(next() * (max - min + 1));
+  return {
+    seed: base,
+    next,
+    int,
+    pick(items) {
+      if (items.length === 0) throw new RangeError("rng.pick: empty array");
+      return items[int(0, items.length - 1)];
+    },
+    shuffle(items) {
+      const out = items.slice();
+      for (let i = out.length - 1; i > 0; i--) {
+        const j = int(0, i);
+        [out[i], out[j]] = [out[j], out[i]];
+      }
+      return out;
+    }
+  };
+}
+function runSimulation(simulation, input, opts) {
+  const maxSteps = opts?.maxSteps ?? 1e4;
+  const rng = createRng(opts?.seed ?? 0);
+  const steps = [];
+  let truncated = false;
+  let error = null;
+  try {
+    for (const step of simulation(input, { rng })) {
+      if (steps.length >= maxSteps) {
+        truncated = true;
+        break;
+      }
+      steps.push(step);
+    }
+  } catch (e) {
+    error = e;
+  }
+  return { steps, truncated, error, seed: rng.seed };
+}
+
+// src/use-simulation.ts
+function useSimulation(simulation, input, opts) {
+  const { seed, maxSteps, ...traceOpts } = opts ?? {};
+  const result = useMemo4(
+    () => runSimulation(simulation, input, { seed, maxSteps }),
+    [simulation, input, seed, maxSteps]
+  );
+  const trace = useTrace(result.steps, traceOpts);
+  return useMemo4(
+    () => ({ ...trace, steps: result.steps, truncated: result.truncated, error: result.error, seed: result.seed }),
+    [trace, result]
+  );
+}
+
+// src/create-trace.ts
+function createTrace() {
+  const frames = [];
+  const builder = {
+    step(step) {
+      frames.push(step);
+      return builder;
+    },
+    get length() {
+      return frames.length;
+    },
+    last() {
+      return frames[frames.length - 1];
+    },
+    build() {
+      return frames.slice();
+    }
+  };
+  return builder;
+}
+
+// src/use-synced-tracks.ts
+import { useCallback as useCallback4, useMemo as useMemo5, useRef as useRef4 } from "react";
+function alignTracks(tracks, key) {
+  const names = Object.keys(tracks);
+  const lens = names.map((n) => tracks[n].length);
+  const rows = [];
+  const holdCell = (len, at) => ({ index: len === 0 ? -1 : Math.min(at, len - 1), held: true });
+  if (!key) {
+    const length = Math.max(0, ...lens);
+    for (let i = 0; i < length; i++) {
+      const row = {};
+      names.forEach((n, t) => {
+        row[n] = i < lens[t] ? { index: i, held: false } : holdCell(lens[t], i);
+      });
+      rows.push(row);
+    }
+    return rows;
+  }
+  const keyed = names.map(
+    (n) => tracks[n].map((step, i) => {
+      const k = key(step, i, n);
+      return k == null ? null : k;
+    })
+  );
+  const qualified = keyed.map((ks) => {
+    const seen = /* @__PURE__ */ new Map();
+    return ks.map((k) => {
+      if (k === null) return null;
+      const n = seen.get(k) ?? 0;
+      seen.set(k, n + 1);
+      return `${k}\0${n}`;
+    });
+  });
+  const where = /* @__PURE__ */ new Map();
+  qualified.forEach(
+    (ks, t) => ks.forEach((k, i) => {
+      if (k === null) return;
+      let m = where.get(k);
+      if (!m) where.set(k, m = /* @__PURE__ */ new Map());
+      m.set(t, i);
+    })
+  );
+  for (const [k, m] of where) if (m.size < 2) where.delete(k);
+  const pos = names.map(() => 0);
+  while (pos.some((p, t) => p < lens[t])) {
+    const live = names.map((_, t) => pos[t] < lens[t]);
+    const blocked = names.map((_, t) => {
+      if (!live[t]) return false;
+      const k = qualified[t][pos[t]];
+      const m = k === null ? void 0 : where.get(k);
+      if (!m) return false;
+      for (const [u, at] of m) if (u !== t && at > pos[u]) return true;
+      return false;
+    });
+    const anyFree = live.some((l, t) => l && !blocked[t]);
+    const row = {};
+    names.forEach((n, t) => {
+      if (live[t] && (!blocked[t] || !anyFree)) {
+        row[n] = { index: pos[t], held: false };
+        pos[t]++;
+      } else {
+        row[n] = holdCell(lens[t], Math.max(0, pos[t] - 1));
+      }
+    });
+    rows.push(row);
+  }
+  return rows;
+}
+var TONE_RANK = ["bad", "good", "write", "accent", "neutral", "idle"];
+function useSyncedTracks(tracks, opts) {
+  const { key, ...playerOpts } = opts ?? {};
+  const keyRef = useRef4(key);
+  keyRef.current = key;
+  const cache = useRef4(null);
+  const names = Object.keys(tracks);
+  const arrays = names.map((n) => tracks[n]);
+  const c = cache.current;
+  if (!c || c.keyed !== !!key || c.names.length !== names.length || names.some((n, i) => c.names[i] !== n || c.arrays[i] !== arrays[i])) {
+    cache.current = { names, arrays, keyed: !!key, rows: alignTracks(tracks, keyRef.current) };
+  }
+  const rows = cache.current.rows;
+  const player = useStepPlayer({ ...playerOpts, total: rows.length });
+  const tracksRef = useRef4(tracks);
+  tracksRef.current = tracks;
+  const rowsRef = useRef4(rows);
+  rowsRef.current = rows;
+  const frame = rows.length === 0 ? -1 : Math.max(0, Math.min(player.index, rows.length - 1));
+  const row = frame >= 0 ? rows[frame] : void 0;
+  const aligned = cache.current;
+  const view = useMemo5(() => {
+    const out = {};
+    aligned.names.forEach((n, t) => {
+      const list = aligned.arrays[t];
+      const cell = row?.[n];
+      const index = cell ? cell.index : list.length === 0 ? -1 : 0;
+      out[n] = {
+        step: index >= 0 ? list[index] : void 0,
+        index,
+        held: cell?.held ?? false,
+        done: list.length > 0 && index === list.length - 1,
+        length: list.length
+      };
+    });
+    return out;
+  }, [aligned, row]);
+  const moved = useCallback4((i) => {
+    const r = rowsRef.current[i];
+    if (!r) return [];
+    return Object.keys(r).filter((n) => !r[n].held).map((n) => ({ name: n, step: tracksRef.current[n]?.[r[n].index] })).filter((m) => !!m.step);
+  }, []);
+  const toneAt = useCallback4(
+    (i) => {
+      const tones = moved(i).map((m) => m.step.tone);
+      return TONE_RANK.find((t) => tones.includes(t)) ?? "neutral";
+    },
+    [moved]
+  );
+  const titleAt = useCallback4(
+    (i) => {
+      const parts = moved(i).map((m) => `${m.name}: ${m.step.label}`);
+      return parts.length ? parts.join(" \xB7 ") : `frame ${i + 1}`;
+    },
+    [moved]
+  );
+  return useMemo5(
+    () => ({ player, frame, total: rows.length, tracks: view, rows, toneAt, titleAt }),
+    [player, frame, rows, view, toneAt, titleAt]
+  );
+}
+
+// src/use-lesson-stream.ts
+import { useCallback as useCallback5, useEffect as useEffect5, useLayoutEffect as useLayoutEffect2, useMemo as useMemo6, useRef as useRef5, useState as useState4 } from "react";
+
+// src/use-prefers-reduced-motion.ts
+import { useEffect as useEffect4, useState as useState3 } from "react";
+function usePrefersReducedMotion() {
+  const [reduced, setReduced] = useState3(false);
+  useEffect4(() => {
+    const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
+    setReduced(mq.matches);
+    const onChange = (e) => setReduced(e.matches);
+    mq.addEventListener("change", onChange);
+    return () => mq.removeEventListener("change", onChange);
+  }, []);
+  return reduced;
+}
+
+// src/use-lesson-stream.ts
+var useIsoLayoutEffect = typeof window !== "undefined" ? useLayoutEffect2 : useEffect5;
+function useLessonStream(count, opts = {}) {
+  const { radius = 1, approachBelow = 600, approachAbove = 300, scrollToSeed = true } = opts;
+  const last = count - 1;
+  const seed = count === 0 ? -1 : Math.max(0, Math.min(opts.seed ?? 0, last));
+  const reducedMotion = usePrefersReducedMotion();
+  const core = useSteps(count, { initialIndex: Math.max(0, seed) });
+  const coreGoRef = useRef5(core.go);
+  coreGoRef.current = core.go;
+  const activeRef = useRef5(core.index);
+  activeRef.current = core.index;
+  const [range, setRange] = useState4(() => ({
+    first: Math.max(0, seed - radius),
+    last: Math.min(last, seed + radius)
+  }));
+  const first = Math.max(0, Math.min(range.first, last));
+  const lastMounted = Math.min(range.last, last);
+  const rangeRef = useRef5({ first, last: lastMounted });
+  rangeRef.current = { first, last: lastMounted };
+  const countRef = useRef5(count);
+  countRef.current = count;
+  const reducedRef = useRef5(reducedMotion);
+  reducedRef.current = reducedMotion;
+  const onActiveRef = useRef5(opts.onActiveChange);
+  onActiveRef.current = opts.onActiveChange;
+  const optsRef = useRef5({ approachBelow, approachAbove });
+  optsRef.current = { approachBelow, approachAbove };
+  const blocks = useRef5(/* @__PURE__ */ new Map());
+  const refCache = useRef5(/* @__PURE__ */ new Map());
+  const refFor = useCallback5((i) => {
+    let fn = refCache.current.get(i);
+    if (!fn) {
+      fn = (el) => {
+        if (el) blocks.current.set(i, el);
+        else blocks.current.delete(i);
+      };
+      refCache.current.set(i, fn);
+    }
+    return fn;
+  }, []);
+  const causeRef = useRef5("scroll");
+  const expandTo = useCallback5((i, cause) => {
+    const r = rangeRef.current;
+    if (i >= r.first && i <= r.last) return;
+    causeRef.current = cause;
+    const grown = { first: Math.min(r.first, i), last: Math.max(r.last, i) };
+    rangeRef.current = grown;
+    setRange(grown);
+  }, []);
+  const scheduleRef = useRef5(null);
+  useEffect5(() => {
+    if (count === 0) return;
+    let raf = 0;
+    const update = () => {
+      raf = 0;
+      if (blocks.current.size === 0) return;
+      const mid = window.innerHeight / 2;
+      let best = -1;
+      for (const [i, el] of blocks.current) {
+        const rect = el.getBoundingClientRect();
+        if (rect.top <= mid && rect.bottom >= mid) best = Math.max(best, i);
+      }
+      if (best === -1) best = Math.min(...blocks.current.keys());
+      if (best !== activeRef.current) {
+        activeRef.current = best;
+        coreGoRef.current(best);
+        onActiveRef.current?.(best);
+      }
+      const { first: f, last: l } = rangeRef.current;
+      const { approachBelow: below, approachAbove: above } = optsRef.current;
+      const lastEl = blocks.current.get(l);
+      if (lastEl && l < countRef.current - 1 && lastEl.getBoundingClientRect().bottom - window.innerHeight < below) {
+        expandTo(l + 1, "scroll");
+      }
+      const firstEl = blocks.current.get(f);
+      if (firstEl && f > 0 && firstEl.getBoundingClientRect().top > -above) {
+        expandTo(f - 1, "scroll");
+      }
+    };
+    const onScroll = () => {
+      if (!raf) raf = requestAnimationFrame(update);
+    };
+    scheduleRef.current = onScroll;
+    update();
+    window.addEventListener("scroll", onScroll, { passive: true });
+    window.addEventListener("resize", onScroll);
+    return () => {
+      scheduleRef.current = null;
+      window.removeEventListener("scroll", onScroll);
+      window.removeEventListener("resize", onScroll);
+      if (raf) cancelAnimationFrame(raf);
+    };
+  }, [count, expandTo]);
+  useEffect5(() => {
+    scheduleRef.current?.();
+  }, [first, lastMounted]);
+  const firstRef = useRef5(first);
+  useIsoLayoutEffect(() => {
+    if (first < firstRef.current && causeRef.current === "scroll") {
+      let height = 0;
+      for (let i = first; i < firstRef.current; i++) {
+        height += blocks.current.get(i)?.getBoundingClientRect().height ?? 0;
+      }
+      if (height) window.scrollBy({ top: height, behavior: "auto" });
+    }
+    causeRef.current = "scroll";
+    firstRef.current = first;
+  }, [first]);
+  useIsoLayoutEffect(() => {
+    if (!scrollToSeed || seed <= 0) return;
+    blocks.current.get(seed)?.scrollIntoView({ block: "start", behavior: "auto" });
+  }, []);
+  const [nav, setNav] = useState4(null);
+  useEffect5(() => {
+    if (!nav) return;
+    const raf = requestAnimationFrame(
+      () => blocks.current.get(nav.target)?.scrollIntoView({ behavior: reducedRef.current ? "auto" : "smooth", block: "start" })
+    );
+    return () => cancelAnimationFrame(raf);
+  }, [nav]);
+  const goTo = useCallback5(
+    (i) => {
+      const c = countRef.current;
+      if (c === 0) return;
+      const target = Math.max(0, Math.min(i, c - 1));
+      expandTo(target, "nav");
+      setNav({ target });
+    },
+    [expandTo]
+  );
+  const next = useCallback5(() => goTo(activeRef.current + 1), [goTo]);
+  const prev = useCallback5(() => goTo(activeRef.current - 1), [goTo]);
+  const mounted = useMemo6(() => {
+    const out = [];
+    for (let i = first; i <= lastMounted; i++) out.push(i);
+    return out;
+  }, [first, lastMounted]);
+  return useMemo6(
+    () => ({
+      active: core.index,
+      seed,
+      mounted,
+      complete: count > 0 && lastMounted === last,
+      refFor,
+      goTo,
+      next,
+      prev,
+      reducedMotion
+    }),
+    [core.index, seed, mounted, count, lastMounted, last, refFor, goTo, next, prev, reducedMotion]
+  );
+}
+function useFadeIn(initiallyVisible = false) {
+  const reduced = usePrefersReducedMotion();
+  const [shown, setShown] = useState4(initiallyVisible);
+  useEffect5(() => {
+    if (shown) return;
+    if (reduced) {
+      setShown(true);
+      return;
+    }
+    const raf = requestAnimationFrame(() => setShown(true));
+    return () => cancelAnimationFrame(raf);
+  }, [shown, reduced]);
+  return shown;
+}
+
+// src/use-evaluator.ts
+import { useCallback as useCallback6, useEffect as useEffect6, useMemo as useMemo7, useRef as useRef6, useState as useState5 } from "react";
+
+// src/evaluate.ts
+function toVerdict(result) {
+  return typeof result === "boolean" ? { status: result ? "pass" : "fail" } : result;
+}
+var pass = (feedback) => ({ status: "pass", feedback });
+var fail = (feedback) => ({ status: "fail", feedback });
+var pending = (feedback) => ({ status: "pending", feedback });
+
+// src/use-evaluator.ts
+var IDLE = { status: "idle", feedback: void 0, error: null };
+function useEvaluator(evaluator, ctx, opts) {
+  const mode = opts?.mode ?? "auto";
+  const [state, setState] = useState5(IDLE);
+  const [attempts, setAttempts] = useState5(0);
+  const evaluatorRef = useRef6(evaluator);
+  evaluatorRef.current = evaluator;
+  const ctxRef = useRef6(ctx);
+  ctxRef.current = ctx;
+  const runRef = useRef6(null);
+  useEffect6(() => () => runRef.current?.abort(), []);
+  const run = useCallback6(async () => {
+    runRef.current?.abort();
+    const controller = new AbortController();
+    runRef.current = controller;
+    let result;
+    try {
+      result = evaluatorRef.current(ctxRef.current, controller.signal);
+    } catch (error) {
+      setState({ status: "fail", feedback: void 0, error });
+      return { status: "fail" };
+    }
+    if (!(result instanceof Promise)) {
+      const verdict = toVerdict(result);
+      setState({ status: verdict.status, feedback: verdict.feedback, error: null });
+      return verdict;
+    }
+    setState((s) => ({ status: "pending", feedback: s.feedback, error: null }));
+    try {
+      const verdict = toVerdict(await result);
+      if (controller.signal.aborted) return null;
+      setState({ status: verdict.status, feedback: verdict.feedback, error: null });
+      return verdict;
+    } catch (error) {
+      if (controller.signal.aborted) return null;
+      setState({ status: "fail", feedback: void 0, error });
+      return { status: "fail" };
+    }
+  }, []);
+  const check = useCallback6(() => {
+    setAttempts((n) => n + 1);
+    return run();
+  }, [run]);
+  const reset = useCallback6(() => {
+    runRef.current?.abort();
+    runRef.current = null;
+    setState(IDLE);
+    setAttempts(0);
+  }, []);
+  useEffect6(() => {
+    if (mode === "auto") {
+      void run();
+    } else {
+      runRef.current?.abort();
+      setState(IDLE);
+    }
+  }, [ctx, mode, run]);
+  return useMemo7(
+    () => ({ ...state, passed: state.status === "pass", attempts, check, reset }),
+    [state, attempts, check, reset]
   );
 }
 
 // src/use-guided-tour.ts
-import { useCallback as useCallback3, useEffect as useEffect3, useRef as useRef3, useState as useState3 } from "react";
+import { useCallback as useCallback7, useEffect as useEffect7, useMemo as useMemo8, useRef as useRef7, useState as useState6 } from "react";
+function gateVerdict(step) {
+  const r = step?.gate?.();
+  return r === void 0 ? { status: "pass", feedback: void 0 } : toVerdict(r);
+}
 function useGuidedTour(steps, opts) {
-  const [running, setRunning] = useState3(false);
-  const runningRef = useRef3(running);
+  const [running, setRunning] = useState6(false);
+  const runningRef = useRef7(running);
   runningRef.current = running;
   const core = useSteps(steps.length);
-  const stepsRef = useRef3(steps);
+  const stepsRef = useRef7(steps);
   stepsRef.current = steps;
-  const driverRef = useRef3(opts?.driver);
+  const driverRef = useRef7(opts?.driver);
   driverRef.current = opts?.driver;
-  const coreGoRef = useRef3(core.go);
+  const coreGoRef = useRef7(core.go);
   coreGoRef.current = core.go;
-  const isSkipped = useCallback3(
+  const cursorRef = useRef7(core.index);
+  cursorRef.current = core.index;
+  const isSkipped = useCallback7(
     (i) => stepsRef.current[i]?.when?.() === false,
     []
   );
-  const settle = useCallback3(
+  const settle = useCallback7(
     (start2, dir) => {
       const len = stepsRef.current.length;
       let i = start2;
@@ -291,7 +967,7 @@ function useGuidedTour(steps, opts) {
     },
     [isSkipped]
   );
-  const arrive = useCallback3(
+  const arrive = useCallback7(
     (i, dir) => {
       const target = settle(i, dir);
       if (target === null) {
@@ -303,14 +979,14 @@ function useGuidedTour(steps, opts) {
     },
     [settle]
   );
-  const goTo = useCallback3(
+  const goTo = useCallback7(
     (i) => {
       if (stepsRef.current.length === 0) return;
       arrive(Math.max(0, Math.min(i, stepsRef.current.length - 1)), 1);
     },
     [arrive]
   );
-  const goToId = useCallback3(
+  const goToId = useCallback7(
     (id) => {
       const i = stepsRef.current.findIndex((s) => s.id === id);
       if (i >= 0) goTo(i);
@@ -318,11 +994,11 @@ function useGuidedTour(steps, opts) {
     [goTo]
   );
   const index = running ? core.index : null;
-  useEffect3(() => {
+  useEffect7(() => {
     if (!running) return;
     stepsRef.current[core.index]?.onEnter?.();
   }, [running, core.index]);
-  useEffect3(() => {
+  useEffect7(() => {
     const driver = driverRef.current;
     if (!driver) return;
     if (!running) {
@@ -341,14 +1017,14 @@ function useGuidedTour(steps, opts) {
       back: () => goTo(core.index - 1),
       end: () => setRunning(false)
     });
-  }, [running, core.index, goTo, core]);
-  useEffect3(() => () => driverRef.current?.hide(), []);
-  const start = useCallback3(() => {
+  }, [running, core.index, goTo]);
+  useEffect7(() => () => driverRef.current?.hide(), []);
+  const start = useCallback7(() => {
     if (stepsRef.current.length === 0) return;
     arrive(0, 1);
   }, [arrive]);
-  const end = useCallback3(() => setRunning(false), []);
-  const resolveNext = useCallback3((i) => {
+  const end = useCallback7(() => setRunning(false), []);
+  const resolveNext = useCallback7((i) => {
     const list = stepsRef.current;
     const edge = list[i]?.next?.();
     if (edge != null) {
@@ -357,30 +1033,35 @@ function useGuidedTour(steps, opts) {
     }
     return i + 1;
   }, []);
-  const next = useCallback3(() => {
+  const next = useCallback7(() => {
     if (!runningRef.current) return;
-    const i = core.index;
-    if (stepsRef.current[i]?.gate?.() === false) return;
+    const i = cursorRef.current;
+    if (gateVerdict(stepsRef.current[i]).status !== "pass") return;
     const target = resolveNext(i);
     if (target > stepsRef.current.length - 1) {
       setRunning(false);
       return;
     }
     arrive(target, 1);
-  }, [core, arrive, resolveNext]);
-  const back = useCallback3(() => {
+  }, [arrive, resolveNext]);
+  const back = useCallback7(() => {
     if (!runningRef.current) return;
-    const i = core.index;
+    const i = cursorRef.current;
     if (i <= 0) return;
     arrive(i - 1, -1);
-  }, [core, arrive]);
+  }, [arrive]);
   const current = running ? stepsRef.current[core.index] ?? null : null;
-  const blocked = current?.gate?.() === false;
-  return { index, current, active: running, blocked, start, end, next, back, goto: goTo, gotoId: goToId };
+  const verdict = current ? gateVerdict(current) : null;
+  const blocked = verdict !== null && verdict.status !== "pass";
+  const feedback = verdict?.feedback;
+  return useMemo8(
+    () => ({ index, current, active: running, blocked, feedback, start, end, next, back, goto: goTo, gotoId: goToId }),
+    [index, current, running, blocked, feedback, start, end, next, back, goTo, goToId]
+  );
 }
 
 // src/use-chapters.ts
-import { useCallback as useCallback4, useEffect as useEffect4, useMemo as useMemo3, useRef as useRef4, useState as useState4 } from "react";
+import { useCallback as useCallback8, useEffect as useEffect8, useMemo as useMemo9, useRef as useRef8, useState as useState7 } from "react";
 
 // src/flatten.ts
 function flattenChapters(chapters, depth = 0) {
@@ -399,17 +1080,17 @@ function flattenChapters(chapters, depth = 0) {
 
 // src/use-chapters.ts
 function useChapters(chapters) {
-  const [mounted, setMounted] = useState4(false);
-  const flat = useMemo3(() => flattenChapters(chapters), [chapters]);
-  const flatRef = useRef4(flat);
+  const [mounted, setMounted] = useState7(false);
+  const flat = useMemo9(() => flattenChapters(chapters), [chapters]);
+  const flatRef = useRef8(flat);
   flatRef.current = flat;
-  const [active, setActive] = useState4(0);
-  const activeRef = useRef4(0);
+  const [active, setActive] = useState7(0);
+  const activeRef = useRef8(0);
   activeRef.current = active;
   const core = useSteps(flat.length, { initialIndex: 0 });
-  const coreGoRef = useRef4(core.go);
+  const coreGoRef = useRef8(core.go);
   coreGoRef.current = core.go;
-  useEffect4(() => {
+  useEffect8(() => {
     if (!mounted) return;
     let raf = 0;
     const update = () => {
@@ -447,8 +1128,8 @@ function useChapters(chapters) {
       if (raf) cancelAnimationFrame(raf);
     };
   }, [mounted, flat.length]);
-  useEffect4(() => setMounted(true), []);
-  const goTo = useCallback4((i) => {
+  useEffect8(() => setMounted(true), []);
+  const goTo = useCallback8((i) => {
     const entry = flatRef.current[i];
     if (!entry) return;
     setActive(i);
@@ -457,25 +1138,25 @@ function useChapters(chapters) {
     if (!el) return;
     el.scrollIntoView({ behavior: "smooth", block: "start" });
   }, []);
-  const next = useCallback4(() => {
+  const next = useCallback8(() => {
     if (activeRef.current < flatRef.current.length - 1) goTo(activeRef.current + 1);
   }, [goTo]);
-  const prev = useCallback4(() => {
+  const prev = useCallback8(() => {
     if (activeRef.current > 0) goTo(activeRef.current - 1);
   }, [goTo]);
-  return { active: core.index, goTo, next, prev };
+  return useMemo9(() => ({ active: core.index, goTo, next, prev }), [core.index, goTo, next, prev]);
 }
 
 // src/use-global-keys.ts
-import { useEffect as useEffect5, useRef as useRef5 } from "react";
+import { useEffect as useEffect9, useRef as useRef9 } from "react";
 var DEFAULT_IGNORED_TAGS = ["INPUT", "TEXTAREA", "SELECT", "BUTTON"];
 function useGlobalKeys(map, opts) {
-  const mapRef = useRef5(map);
+  const mapRef = useRef9(map);
   mapRef.current = map;
-  const ignoreRef = useRef5(new Set(opts?.ignoreTags ?? DEFAULT_IGNORED_TAGS));
-  const enabledRef = useRef5(opts?.enabled ?? true);
+  const ignoreRef = useRef9(new Set(opts?.ignoreTags ?? DEFAULT_IGNORED_TAGS));
+  const enabledRef = useRef9(opts?.enabled ?? true);
   enabledRef.current = opts?.enabled ?? true;
-  useEffect5(() => {
+  useEffect9(() => {
     const onKey = (e) => {
       const gate = enabledRef.current;
       const enabled = typeof gate === "function" ? gate() : gate;
@@ -493,7 +1174,7 @@ function useGlobalKeys(map, opts) {
 }
 
 // src/use-discoveries.ts
-import { useCallback as useCallback5, useEffect as useEffect6, useMemo as useMemo4, useRef as useRef6, useState as useState5 } from "react";
+import { useCallback as useCallback9, useEffect as useEffect10, useMemo as useMemo10, useRef as useRef10, useState as useState8 } from "react";
 function localStorageStore(key = "stepwise.discoveries") {
   return {
     read() {
@@ -544,23 +1225,23 @@ function memoryStore(seed = []) {
   };
 }
 function useDiscoveries(opts) {
-  const defaultStoreRef = useRef6(null);
-  const storeRef = useRef6(null);
+  const defaultStoreRef = useRef10(null);
+  const storeRef = useRef10(null);
   if (opts?.store) {
     storeRef.current = opts.store;
   } else {
     if (!defaultStoreRef.current) defaultStoreRef.current = localStorageStore(opts?.key);
     storeRef.current = defaultStoreRef.current;
   }
-  const [ids, setIds] = useState5(() => /* @__PURE__ */ new Set());
-  const [ready, setReady] = useState5(false);
-  const idsRef = useRef6(ids);
+  const [ids, setIds] = useState8(() => /* @__PURE__ */ new Set());
+  const [ready, setReady] = useState8(false);
+  const idsRef = useRef10(ids);
   idsRef.current = ids;
-  useEffect6(() => {
+  useEffect10(() => {
     setIds(new Set(storeRef.current.read()));
     setReady(true);
   }, []);
-  const markDiscovered = useCallback5((id) => {
+  const markDiscovered = useCallback9((id) => {
     const additions = Array.isArray(id) ? id : [id];
     const merged = new Set(idsRef.current);
     let changed = false;
@@ -575,24 +1256,24 @@ function useDiscoveries(opts) {
     setIds(merged);
     storeRef.current.write([...merged]);
   }, []);
-  const reset = useCallback5(() => {
+  const reset = useCallback9(() => {
     const empty = /* @__PURE__ */ new Set();
     idsRef.current = empty;
     setIds(empty);
     storeRef.current.write([]);
   }, []);
-  const isDiscovered = useCallback5((id) => idsRef.current.has(id), []);
-  return useMemo4(
+  const isDiscovered = useCallback9((id) => idsRef.current.has(id), []);
+  return useMemo10(
     () => ({ discovered: ids, ready, isDiscovered, markDiscovered, reset }),
     [ids, ready, isDiscovered, markDiscovered, reset]
   );
 }
 
 // src/use-focus-trap.ts
-import { useEffect as useEffect7, useRef as useRef7 } from "react";
+import { useEffect as useEffect11, useRef as useRef11 } from "react";
 function useFocusTrap(active) {
-  const ref = useRef7(null);
-  useEffect7(() => {
+  const ref = useRef11(null);
+  useEffect11(() => {
     if (!active) return;
     const container = ref.current;
     if (!container) return;
@@ -626,31 +1307,17 @@ function useFocusTrap(active) {
   return ref;
 }
 
-// src/use-prefers-reduced-motion.ts
-import { useEffect as useEffect8, useState as useState6 } from "react";
-function usePrefersReducedMotion() {
-  const [reduced, setReduced] = useState6(false);
-  useEffect8(() => {
-    const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
-    setReduced(mq.matches);
-    const onChange = (e) => setReduced(e.matches);
-    mq.addEventListener("change", onChange);
-    return () => mq.removeEventListener("change", onChange);
-  }, []);
-  return reduced;
-}
-
 // src/glossary.tsx
 import {
   createContext,
-  useCallback as useCallback6,
+  useCallback as useCallback10,
   useContext,
-  useEffect as useEffect9,
+  useEffect as useEffect12,
   useId,
-  useLayoutEffect,
-  useMemo as useMemo5,
-  useRef as useRef8,
-  useState as useState7
+  useLayoutEffect as useLayoutEffect3,
+  useMemo as useMemo11,
+  useRef as useRef12,
+  useState as useState9
 } from "react";
 import { createPortal } from "react-dom";
 
@@ -708,7 +1375,7 @@ function GlossaryProvider({
   theme = defaultTheme,
   children
 }) {
-  const value = useMemo5(
+  const value = useMemo11(
     () => ({ byId: new Map(entries.map((e) => [e.id, e])), entries, theme }),
     [entries, theme]
   );
@@ -718,23 +1385,23 @@ function Term({ id, children, className }) {
   const ctx = useContext(GlossaryContext);
   const depth = useContext(DepthContext);
   const entry = ctx?.byId.get(id);
-  const [open, setOpen] = useState7(false);
-  const [pos, setPos] = useState7(null);
-  const openRef = useRef8(false);
-  const wrapperRef = useRef8(null);
-  const triggerRef = useRef8(null);
-  const cardRef = useRef8(null);
-  const openTimer = useRef8(0);
-  const closeTimer = useRef8(0);
+  const [open, setOpen] = useState9(false);
+  const [pos, setPos] = useState9(null);
+  const openRef = useRef12(false);
+  const wrapperRef = useRef12(null);
+  const triggerRef = useRef12(null);
+  const cardRef = useRef12(null);
+  const openTimer = useRef12(0);
+  const closeTimer = useRef12(0);
   const tipId = useId();
   const display = children ?? entry?.term ?? id;
-  const closeNow = useCallback6(() => {
+  const closeNow = useCallback10(() => {
     window.clearTimeout(openTimer.current);
     window.clearTimeout(closeTimer.current);
     openRef.current = false;
     setOpen(false);
   }, []);
-  const openNow = useCallback6((focusCard = false) => {
+  const openNow = useCallback10((focusCard = false) => {
     window.clearTimeout(closeTimer.current);
     window.clearTimeout(openTimer.current);
     openRef.current = true;
@@ -743,18 +1410,18 @@ function Term({ id, children, className }) {
       requestAnimationFrame(() => cardRef.current?.focus({ preventScroll: true }));
     }
   }, []);
-  const scheduleOpen = useCallback6(() => {
+  const scheduleOpen = useCallback10(() => {
     window.clearTimeout(closeTimer.current);
     if (openRef.current) return;
     window.clearTimeout(openTimer.current);
     openTimer.current = window.setTimeout(() => openNow(), OPEN_DELAY_MS);
   }, [openNow]);
-  const scheduleClose = useCallback6(() => {
+  const scheduleClose = useCallback10(() => {
     window.clearTimeout(openTimer.current);
     window.clearTimeout(closeTimer.current);
     closeTimer.current = window.setTimeout(closeNow, CLOSE_GRACE_MS);
   }, [closeNow]);
-  useLayoutEffect(() => {
+  useLayoutEffect3(() => {
     if (!open) {
       setPos(null);
       return;
@@ -791,7 +1458,7 @@ function Term({ id, children, className }) {
       if (raf) cancelAnimationFrame(raf);
     };
   }, [open]);
-  useEffect9(() => {
+  useEffect12(() => {
     if (!open) return;
     const onPointerDown = (e) => {
       const target = e.target;
@@ -802,7 +1469,7 @@ function Term({ id, children, className }) {
     document.addEventListener("pointerdown", onPointerDown);
     return () => document.removeEventListener("pointerdown", onPointerDown);
   }, [open, closeNow]);
-  useEffect9(() => () => {
+  useEffect12(() => () => {
     window.clearTimeout(openTimer.current);
     window.clearTimeout(closeTimer.current);
   }, []);
@@ -854,6 +1521,7 @@ function Term({ id, children, className }) {
     "span",
     {
       ref: wrapperRef,
+      "data-stepwise": "",
       className: "relative inline",
       onMouseEnter: interactive ? scheduleOpen : void 0,
       onMouseLeave: interactive ? scheduleClose : void 0,
@@ -876,6 +1544,7 @@ function Term({ id, children, className }) {
             "span",
             {
               ref: cardRef,
+              "data-stepwise": "",
               role: "tooltip",
               id: tipId,
               tabIndex: -1,
@@ -946,14 +1615,14 @@ function GlossaryAppendix({
   if (bare) {
     return /* @__PURE__ */ jsx(AppendixContext.Provider, { value: true, children: body });
   }
-  return /* @__PURE__ */ jsx(AppendixContext.Provider, { value: true, children: /* @__PURE__ */ jsxs("section", { "aria-label": title, className: cn("mt-16 border-t border-white/10 pt-10", className), children: [
+  return /* @__PURE__ */ jsx(AppendixContext.Provider, { value: true, children: /* @__PURE__ */ jsxs("section", { "data-stepwise": "", "aria-label": title, className: cn("mt-16 border-t border-white/10 pt-10", className), children: [
     /* @__PURE__ */ jsx("p", { className: cn("text-[11px] font-mono uppercase tracking-widest mb-6", theme.muted), children: title }),
     body
   ] }) });
 }
 
 // src/components.tsx
-import { useEffect as useEffect10, useState as useState8 } from "react";
+import { useEffect as useEffect13, useState as useState10 } from "react";
 import { createPortal as createPortal2 } from "react-dom";
 import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
 var TONE_SEGMENT_CLASS = defaultTheme.toneSegment;
@@ -975,7 +1644,7 @@ function CodeBlock({
   theme = defaultTheme,
   className
 }) {
-  return /* @__PURE__ */ jsx2("div", { className: cn(theme.codeBlock, className), children: lines.map((line, i) => {
+  return /* @__PURE__ */ jsx2("div", { "data-stepwise": "", className: cn(theme.codeBlock, className), children: lines.map((line, i) => {
     const commentStart = line.indexOf("//");
     if (commentStart === 0) {
       return /* @__PURE__ */ jsx2("div", { className: cn("whitespace-pre", theme.codeMuted), children: line }, i);
@@ -1022,7 +1691,7 @@ function StepScrubber({
     }
   };
   if (count === 0) {
-    return /* @__PURE__ */ jsx2("div", { className: cn("flex-1 flex items-center min-w-0", className), children: emptyHint && /* @__PURE__ */ jsx2("span", { className: cn("text-xs font-mono px-2", theme.muted), children: emptyHint }) });
+    return /* @__PURE__ */ jsx2("div", { "data-stepwise": "", className: cn("flex-1 flex items-center min-w-0", className), children: emptyHint && /* @__PURE__ */ jsx2("span", { className: cn("text-xs font-mono px-2", theme.muted), children: emptyHint }) });
   }
   const valueText = labels?.frame ? labels.frame(index) : titleAt?.(index) ?? `frame ${index + 1} of ${count}`;
   const segment = (i) => /* @__PURE__ */ jsx2(
@@ -1064,6 +1733,7 @@ function StepScrubber({
   return /* @__PURE__ */ jsx2(
     "div",
     {
+      "data-stepwise": "",
       role: "slider",
       tabIndex: 0,
       "aria-label": labels?.scrubber ?? "Frames",
@@ -1091,17 +1761,21 @@ function PlayerBar({
   className,
   theme = defaultTheme,
   groupOf,
-  labels
+  labels,
+  live
 }) {
   const L = {
     previous: labels?.previous ?? "Previous step",
     play: labels?.play ?? "Play",
     pause: labels?.pause ?? "Pause",
     replay: labels?.replay ?? "Replay",
-    next: labels?.next ?? "Next step"
+    next: labels?.next ?? "Next step",
+    live: labels?.live ?? "Live",
+    goLive: labels?.goLive ?? "Go live"
   };
+  const behind = Math.max(0, player.total - 1 - Math.max(player.index, 0));
   const playLabel = player.playing ? L.pause : player.total > 0 && player.atEnd ? L.replay : L.play;
-  return /* @__PURE__ */ jsxs2("div", { className: cn("flex items-center gap-2 p-2", className), children: [
+  return /* @__PURE__ */ jsxs2("div", { "data-stepwise": "", className: cn("flex items-center gap-2 p-2", className), children: [
     leading,
     /* @__PURE__ */ jsx2(StepButton, { variant: "ghost", onClick: () => player.prev(), className: "h-7 px-2 text-xs", "aria-label": L.previous, children: "\u2190" }),
     /* @__PURE__ */ jsx2(StepButton, { variant: "outline", onClick: () => player.toggle(onEmpty), className: "h-7 px-3.5 text-[11px]", children: playLabel }),
@@ -1119,7 +1793,15 @@ function PlayerBar({
         groupOf
       }
     ),
-    /* @__PURE__ */ jsx2("span", { className: cn("text-[10px] font-mono w-11 text-right shrink-0", theme.muted), children: player.total > 0 ? `${player.index + 1}/${player.total}` : "\u2014" })
+    /* @__PURE__ */ jsx2("span", { className: cn("text-[10px] font-mono w-11 text-right shrink-0", theme.muted), children: player.total > 0 ? `${player.index + 1}/${player.total}` : "\u2014" }),
+    live && (player.live || behind === 0 ? /* @__PURE__ */ jsxs2("span", { role: "status", className: "flex items-center gap-1 text-[10px] font-mono uppercase text-primary shrink-0", children: [
+      /* @__PURE__ */ jsx2("span", { "aria-hidden": "true", className: cn("h-1.5 w-1.5 rounded-full bg-primary", player.playing && "motion-safe:animate-pulse") }),
+      L.live
+    ] }) : /* @__PURE__ */ jsxs2(StepButton, { variant: "ghost", onClick: () => player.goLive?.(), className: "h-7 px-2 text-[10px] font-mono shrink-0", children: [
+      L.goLive,
+      " +",
+      behind
+    ] }))
   ] });
 }
 function ChapterNav({
@@ -1163,6 +1845,7 @@ function ChapterNav({
   return /* @__PURE__ */ jsx2(
     "nav",
     {
+      "data-stepwise": "",
       "aria-label": "Chapters",
       className: cn(
         "sticky top-20 md:top-24 z-30 rounded-sm shadow-[0_8px_24px_rgba(0,0,0,0.35)]",
@@ -1186,7 +1869,7 @@ function LessonPager({
   className,
   labels
 }) {
-  return /* @__PURE__ */ jsxs2("div", { className: cn("flex items-center gap-2", className), children: [
+  return /* @__PURE__ */ jsxs2("div", { "data-stepwise": "", className: cn("flex items-center gap-2", className), children: [
     /* @__PURE__ */ jsxs2(
       StepButton,
       {
@@ -1223,8 +1906,8 @@ function TourSpotlight({
   target,
   theme = defaultTheme
 }) {
-  const [rect, setRect] = useState8(null);
-  useEffect10(() => {
+  const [rect, setRect] = useState10(null);
+  useEffect13(() => {
     if (!target) {
       setRect(null);
       return;
@@ -1256,7 +1939,7 @@ function TourSpotlight({
   }, [target]);
   if (!rect) return null;
   const pad = 6;
-  return /* @__PURE__ */ jsx2("div", { className: "fixed inset-0 z-40 pointer-events-none", children: /* @__PURE__ */ jsx2(
+  return /* @__PURE__ */ jsx2("div", { "data-stepwise": "", className: "fixed inset-0 z-40 pointer-events-none", children: /* @__PURE__ */ jsx2(
     "div",
     {
       className: cn("absolute", theme.spotlight),
@@ -1280,7 +1963,8 @@ function TourCard({
   labels,
   className,
   theme = defaultTheme,
-  nextDisabled = false
+  nextDisabled = false,
+  feedback
 }) {
   const L = {
     title: labels?.title ?? "Guided tour",
@@ -1294,6 +1978,7 @@ function TourCard({
     "div",
     {
       ref: trapRef,
+      "data-stepwise": "",
       role: "dialog",
       "aria-modal": "true",
       "aria-label": `${L.title} \xB7 ${index + 1}/${total}`,
@@ -1327,6 +2012,7 @@ function TourCard({
         /* @__PURE__ */ jsx2("p", { className: "text-sm font-bold text-foreground/95 mb-1.5", children: step.title }),
         /* @__PURE__ */ jsx2("div", { className: "text-[12px] font-mono text-foreground/70 leading-relaxed", children: step.body }),
         step.waitHint && /* @__PURE__ */ jsx2("p", { className: "text-[11px] font-mono text-accent mt-2 animate-pulse", children: step.waitHint }),
+        /* @__PURE__ */ jsx2("div", { "aria-live": "polite", children: feedback != null && feedback !== false && /* @__PURE__ */ jsx2("p", { className: "text-[11px] font-mono text-foreground/70 mt-2", children: feedback }) }),
         /* @__PURE__ */ jsxs2("div", { className: "flex items-center gap-2 mt-3 pt-3 border-t border-white/10", children: [
           /* @__PURE__ */ jsx2(StepButton, { variant: "outline", onClick: onBack, disabled: index === 0, className: "h-7 px-3 text-[11px]", children: L.back }),
           /* @__PURE__ */ jsx2(
@@ -1352,10 +2038,10 @@ function ShortcutsDialog({
   className,
   theme = defaultTheme
 }) {
-  const [mounted, setMounted] = useState8(false);
+  const [mounted, setMounted] = useState10(false);
   const trapRef = useFocusTrap(open);
-  useEffect10(() => setMounted(true), []);
-  useEffect10(() => {
+  useEffect13(() => setMounted(true), []);
+  useEffect13(() => {
     if (!open) return;
     const onKey = (e) => {
       if (e.key === "Escape") onClose();
@@ -1368,6 +2054,7 @@ function ShortcutsDialog({
     /* @__PURE__ */ jsx2(
       "div",
       {
+        "data-stepwise": "",
         className: cn("fixed inset-0 z-50 flex items-center justify-center p-4", theme.overlay, className),
         onClick: onClose,
         children: /* @__PURE__ */ jsxs2(
@@ -1424,18 +2111,35 @@ export {
   Term,
   TourCard,
   TourSpotlight,
+  alignTracks,
   cookieStore,
+  createRng,
+  createTrace,
   defaultTheme,
+  fail,
   flattenChapters,
   localStorageStore,
   memoryStore,
+  pass,
+  pending,
+  readHashParam,
+  reanchor,
+  runSimulation,
+  toVerdict,
   useChapters,
   useDiscoveries,
+  useEvaluator,
+  useFadeIn,
   useFocusTrap,
   useGlobalKeys,
   useGuidedTour,
+  useLessonStream,
   usePrefersReducedMotion,
+  useSimulation,
   useStepPlayer,
-  useSteps
+  useSteps,
+  useSyncedTracks,
+  useTrace,
+  writeHashParam
 };
 //# sourceMappingURL=index.js.map