@sphynxoid/stepwise 0.1.0 → 0.2.0

package/dist/index.js

@@ -59,8 +59,17 @@ 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
+}) {
   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 [speed, setSpeed] = useState2(1);
@@ -81,10 +90,16 @@ 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 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 engineRef = useRef2(engine);
+  engineRef.current = engine;
   const engineApiRef = useRef2({});
   useEffect2(() => {
     if (!engine) return;
@@ -92,7 +107,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,17 +123,24 @@ 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();
+    first();
     if (engineRef.current) {
       engineApiRef.current.seek?.(0);
       engineApiRef.current.play?.();
     }
-  }, [core]);
+  }, [first, clearEnded]);
   const reset = useCallback2(() => {
     setStarted(false);
     setPlaying(false);
@@ -127,62 +149,59 @@ function useStepPlayer({ total, baseDelayMs = 900, autoPlay = false, engine, syn
   }, [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)));
+      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();
+      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();
+    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 (engineRef.current) {
@@ -190,7 +209,7 @@ function useStepPlayer({ total, baseDelayMs = 900, autoPlay = false, engine, syn
         else engineApiRef.current.pause?.();
       }
     },
-    [total, playing, atEnd, core, clearEnded]
+    [start]
   );
   const changeSpeed = useCallback2((s) => {
     setSpeed(s);
@@ -207,25 +226,22 @@ function useStepPlayer({ total, baseDelayMs = 900, autoPlay = false, engine, syn
       setPlaying(false);
       return;
     }
-    const id = setTimeout(() => core.next(), baseDelayMs / speed);
+    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 readHash = useCallback2(() => {
-    if (!hashKey || typeof window === "undefined" || total === 0) return;
+    if (!syncHash || typeof window === "undefined" || total === 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 < total) {
       setStarted(true);
-      coreGoRef.current(f);
+      go(f);
     }
-  }, [hashKey, total]);
+  }, [syncHash, total, go]);
   useEffect2(() => {
     readHash();
     const onHashChange = () => readHash();
@@ -234,7 +250,7 @@ function useStepPlayer({ total, baseDelayMs = 900, autoPlay = false, engine, syn
   }, [readHash]);
   useEffect2(() => {
     if (!syncHash || index < 0 || typeof window === "undefined") return;
-    const next2 = `#${syncHash}=${index}`;
+    const next2 = writeHashParam(window.location.hash, syncHash, String(index));
     if (window.location.hash !== next2) {
       lastWrittenHash.current = next2;
       window.history.replaceState(null, "", next2);
@@ -261,25 +277,395 @@ function useStepPlayer({ total, baseDelayMs = 900, autoPlay = false, engine, syn
     [total, index, playing, speed, atEnd, ended, 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, useMemo as useMemo3, useRef as useRef3 } from "react";
+function useTrace(steps, opts) {
+  const player = useStepPlayer({ ...opts, total: steps.length });
+  const stepsRef = useRef3(steps);
+  stepsRef.current = steps;
+  const frame = steps.length === 0 ? -1 : Math.max(0, Math.min(player.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/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 useMemo4, 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 = useMemo4(() => {
+    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 useMemo4(
+    () => ({ 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 useEffect4, useLayoutEffect, useMemo as useMemo5, useRef as useRef5, useState as useState4 } from "react";
+
+// src/use-prefers-reduced-motion.ts
+import { useEffect as useEffect3, useState as useState3 } from "react";
+function usePrefersReducedMotion() {
+  const [reduced, setReduced] = useState3(false);
+  useEffect3(() => {
+    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" ? useLayoutEffect : useEffect4;
+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);
+  useEffect4(() => {
+    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]);
+  useEffect4(() => {
+    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);
+  useEffect4(() => {
+    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 = useMemo5(() => {
+    const out = [];
+    for (let i = first; i <= lastMounted; i++) out.push(i);
+    return out;
+  }, [first, lastMounted]);
+  return useMemo5(
+    () => ({
+      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);
+  useEffect4(() => {
+    if (shown) return;
+    if (reduced) {
+      setShown(true);
+      return;
+    }
+    const raf = requestAnimationFrame(() => setShown(true));
+    return () => cancelAnimationFrame(raf);
+  }, [shown, reduced]);
+  return shown;
+}
 
 // src/use-guided-tour.ts
-import { useCallback as useCallback3, useEffect as useEffect3, useRef as useRef3, useState as useState3 } from "react";
+import { useCallback as useCallback6, useEffect as useEffect5, useMemo as useMemo6, useRef as useRef6, useState as useState5 } from "react";
 function useGuidedTour(steps, opts) {
-  const [running, setRunning] = useState3(false);
-  const runningRef = useRef3(running);
+  const [running, setRunning] = useState5(false);
+  const runningRef = useRef6(running);
   runningRef.current = running;
   const core = useSteps(steps.length);
-  const stepsRef = useRef3(steps);
+  const stepsRef = useRef6(steps);
   stepsRef.current = steps;
-  const driverRef = useRef3(opts?.driver);
+  const driverRef = useRef6(opts?.driver);
   driverRef.current = opts?.driver;
-  const coreGoRef = useRef3(core.go);
+  const coreGoRef = useRef6(core.go);
   coreGoRef.current = core.go;
-  const isSkipped = useCallback3(
+  const cursorRef = useRef6(core.index);
+  cursorRef.current = core.index;
+  const isSkipped = useCallback6(
     (i) => stepsRef.current[i]?.when?.() === false,
     []
   );
-  const settle = useCallback3(
+  const settle = useCallback6(
     (start2, dir) => {
       const len = stepsRef.current.length;
       let i = start2;
@@ -291,7 +677,7 @@ function useGuidedTour(steps, opts) {
     },
     [isSkipped]
   );
-  const arrive = useCallback3(
+  const arrive = useCallback6(
     (i, dir) => {
       const target = settle(i, dir);
       if (target === null) {
@@ -303,14 +689,14 @@ function useGuidedTour(steps, opts) {
     },
     [settle]
   );
-  const goTo = useCallback3(
+  const goTo = useCallback6(
     (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 = useCallback6(
     (id) => {
       const i = stepsRef.current.findIndex((s) => s.id === id);
       if (i >= 0) goTo(i);
@@ -318,11 +704,11 @@ function useGuidedTour(steps, opts) {
     [goTo]
   );
   const index = running ? core.index : null;
-  useEffect3(() => {
+  useEffect5(() => {
     if (!running) return;
     stepsRef.current[core.index]?.onEnter?.();
   }, [running, core.index]);
-  useEffect3(() => {
+  useEffect5(() => {
     const driver = driverRef.current;
     if (!driver) return;
     if (!running) {
@@ -341,14 +727,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]);
+  useEffect5(() => () => driverRef.current?.hide(), []);
+  const start = useCallback6(() => {
     if (stepsRef.current.length === 0) return;
     arrive(0, 1);
   }, [arrive]);
-  const end = useCallback3(() => setRunning(false), []);
-  const resolveNext = useCallback3((i) => {
+  const end = useCallback6(() => setRunning(false), []);
+  const resolveNext = useCallback6((i) => {
     const list = stepsRef.current;
     const edge = list[i]?.next?.();
     if (edge != null) {
@@ -357,9 +743,9 @@ function useGuidedTour(steps, opts) {
     }
     return i + 1;
   }, []);
-  const next = useCallback3(() => {
+  const next = useCallback6(() => {
     if (!runningRef.current) return;
-    const i = core.index;
+    const i = cursorRef.current;
     if (stepsRef.current[i]?.gate?.() === false) return;
     const target = resolveNext(i);
     if (target > stepsRef.current.length - 1) {
@@ -367,20 +753,23 @@ function useGuidedTour(steps, opts) {
       return;
     }
     arrive(target, 1);
-  }, [core, arrive, resolveNext]);
-  const back = useCallback3(() => {
+  }, [arrive, resolveNext]);
+  const back = useCallback6(() => {
     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 };
+  return useMemo6(
+    () => ({ index, current, active: running, blocked, start, end, next, back, goto: goTo, gotoId: goToId }),
+    [index, current, running, blocked, 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 useCallback7, useEffect as useEffect6, useMemo as useMemo7, useRef as useRef7, useState as useState6 } from "react";
 
 // src/flatten.ts
 function flattenChapters(chapters, depth = 0) {
@@ -399,17 +788,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] = useState6(false);
+  const flat = useMemo7(() => flattenChapters(chapters), [chapters]);
+  const flatRef = useRef7(flat);
   flatRef.current = flat;
-  const [active, setActive] = useState4(0);
-  const activeRef = useRef4(0);
+  const [active, setActive] = useState6(0);
+  const activeRef = useRef7(0);
   activeRef.current = active;
   const core = useSteps(flat.length, { initialIndex: 0 });
-  const coreGoRef = useRef4(core.go);
+  const coreGoRef = useRef7(core.go);
   coreGoRef.current = core.go;
-  useEffect4(() => {
+  useEffect6(() => {
     if (!mounted) return;
     let raf = 0;
     const update = () => {
@@ -447,8 +836,8 @@ function useChapters(chapters) {
       if (raf) cancelAnimationFrame(raf);
     };
   }, [mounted, flat.length]);
-  useEffect4(() => setMounted(true), []);
-  const goTo = useCallback4((i) => {
+  useEffect6(() => setMounted(true), []);
+  const goTo = useCallback7((i) => {
     const entry = flatRef.current[i];
     if (!entry) return;
     setActive(i);
@@ -457,25 +846,25 @@ function useChapters(chapters) {
     if (!el) return;
     el.scrollIntoView({ behavior: "smooth", block: "start" });
   }, []);
-  const next = useCallback4(() => {
+  const next = useCallback7(() => {
     if (activeRef.current < flatRef.current.length - 1) goTo(activeRef.current + 1);
   }, [goTo]);
-  const prev = useCallback4(() => {
+  const prev = useCallback7(() => {
     if (activeRef.current > 0) goTo(activeRef.current - 1);
   }, [goTo]);
-  return { active: core.index, goTo, next, prev };
+  return useMemo7(() => ({ 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 useEffect7, useRef as useRef8 } from "react";
 var DEFAULT_IGNORED_TAGS = ["INPUT", "TEXTAREA", "SELECT", "BUTTON"];
 function useGlobalKeys(map, opts) {
-  const mapRef = useRef5(map);
+  const mapRef = useRef8(map);
   mapRef.current = map;
-  const ignoreRef = useRef5(new Set(opts?.ignoreTags ?? DEFAULT_IGNORED_TAGS));
-  const enabledRef = useRef5(opts?.enabled ?? true);
+  const ignoreRef = useRef8(new Set(opts?.ignoreTags ?? DEFAULT_IGNORED_TAGS));
+  const enabledRef = useRef8(opts?.enabled ?? true);
   enabledRef.current = opts?.enabled ?? true;
-  useEffect5(() => {
+  useEffect7(() => {
     const onKey = (e) => {
       const gate = enabledRef.current;
       const enabled = typeof gate === "function" ? gate() : gate;
@@ -493,7 +882,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 useCallback8, useEffect as useEffect8, useMemo as useMemo8, useRef as useRef9, useState as useState7 } from "react";
 function localStorageStore(key = "stepwise.discoveries") {
   return {
     read() {
@@ -544,23 +933,23 @@ function memoryStore(seed = []) {
   };
 }
 function useDiscoveries(opts) {
-  const defaultStoreRef = useRef6(null);
-  const storeRef = useRef6(null);
+  const defaultStoreRef = useRef9(null);
+  const storeRef = useRef9(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] = useState7(() => /* @__PURE__ */ new Set());
+  const [ready, setReady] = useState7(false);
+  const idsRef = useRef9(ids);
   idsRef.current = ids;
-  useEffect6(() => {
+  useEffect8(() => {
     setIds(new Set(storeRef.current.read()));
     setReady(true);
   }, []);
-  const markDiscovered = useCallback5((id) => {
+  const markDiscovered = useCallback8((id) => {
     const additions = Array.isArray(id) ? id : [id];
     const merged = new Set(idsRef.current);
     let changed = false;
@@ -575,24 +964,24 @@ function useDiscoveries(opts) {
     setIds(merged);
     storeRef.current.write([...merged]);
   }, []);
-  const reset = useCallback5(() => {
+  const reset = useCallback8(() => {
     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 = useCallback8((id) => idsRef.current.has(id), []);
+  return useMemo8(
     () => ({ 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 useEffect9, useRef as useRef10 } from "react";
 function useFocusTrap(active) {
-  const ref = useRef7(null);
-  useEffect7(() => {
+  const ref = useRef10(null);
+  useEffect9(() => {
     if (!active) return;
     const container = ref.current;
     if (!container) return;
@@ -626,31 +1015,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 useCallback9,
   useContext,
-  useEffect as useEffect9,
+  useEffect as useEffect10,
   useId,
-  useLayoutEffect,
-  useMemo as useMemo5,
-  useRef as useRef8,
-  useState as useState7
+  useLayoutEffect as useLayoutEffect2,
+  useMemo as useMemo9,
+  useRef as useRef11,
+  useState as useState8
 } from "react";
 import { createPortal } from "react-dom";
 
@@ -708,7 +1083,7 @@ function GlossaryProvider({
   theme = defaultTheme,
   children
 }) {
-  const value = useMemo5(
+  const value = useMemo9(
     () => ({ byId: new Map(entries.map((e) => [e.id, e])), entries, theme }),
     [entries, theme]
   );
@@ -718,23 +1093,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] = useState8(false);
+  const [pos, setPos] = useState8(null);
+  const openRef = useRef11(false);
+  const wrapperRef = useRef11(null);
+  const triggerRef = useRef11(null);
+  const cardRef = useRef11(null);
+  const openTimer = useRef11(0);
+  const closeTimer = useRef11(0);
   const tipId = useId();
   const display = children ?? entry?.term ?? id;
-  const closeNow = useCallback6(() => {
+  const closeNow = useCallback9(() => {
     window.clearTimeout(openTimer.current);
     window.clearTimeout(closeTimer.current);
     openRef.current = false;
     setOpen(false);
   }, []);
-  const openNow = useCallback6((focusCard = false) => {
+  const openNow = useCallback9((focusCard = false) => {
     window.clearTimeout(closeTimer.current);
     window.clearTimeout(openTimer.current);
     openRef.current = true;
@@ -743,18 +1118,18 @@ function Term({ id, children, className }) {
       requestAnimationFrame(() => cardRef.current?.focus({ preventScroll: true }));
     }
   }, []);
-  const scheduleOpen = useCallback6(() => {
+  const scheduleOpen = useCallback9(() => {
     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 = useCallback9(() => {
     window.clearTimeout(openTimer.current);
     window.clearTimeout(closeTimer.current);
     closeTimer.current = window.setTimeout(closeNow, CLOSE_GRACE_MS);
   }, [closeNow]);
-  useLayoutEffect(() => {
+  useLayoutEffect2(() => {
     if (!open) {
       setPos(null);
       return;
@@ -791,7 +1166,7 @@ function Term({ id, children, className }) {
       if (raf) cancelAnimationFrame(raf);
     };
   }, [open]);
-  useEffect9(() => {
+  useEffect10(() => {
     if (!open) return;
     const onPointerDown = (e) => {
       const target = e.target;
@@ -802,7 +1177,7 @@ function Term({ id, children, className }) {
     document.addEventListener("pointerdown", onPointerDown);
     return () => document.removeEventListener("pointerdown", onPointerDown);
   }, [open, closeNow]);
-  useEffect9(() => () => {
+  useEffect10(() => () => {
     window.clearTimeout(openTimer.current);
     window.clearTimeout(closeTimer.current);
   }, []);
@@ -854,6 +1229,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 +1252,7 @@ function Term({ id, children, className }) {
             "span",
             {
               ref: cardRef,
+              "data-stepwise": "",
               role: "tooltip",
               id: tipId,
               tabIndex: -1,
@@ -946,14 +1323,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 useEffect11, useState as useState9 } 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 +1352,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 +1399,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 +1441,7 @@ function StepScrubber({
   return /* @__PURE__ */ jsx2(
     "div",
     {
+      "data-stepwise": "",
       role: "slider",
       tabIndex: 0,
       "aria-label": labels?.scrubber ?? "Frames",
@@ -1101,7 +1479,7 @@ function PlayerBar({
     next: labels?.next ?? "Next step"
   };
   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 }),
@@ -1163,6 +1541,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 +1565,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 +1602,8 @@ function TourSpotlight({
   target,
   theme = defaultTheme
 }) {
-  const [rect, setRect] = useState8(null);
-  useEffect10(() => {
+  const [rect, setRect] = useState9(null);
+  useEffect11(() => {
     if (!target) {
       setRect(null);
       return;
@@ -1256,7 +1635,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),
@@ -1294,6 +1673,7 @@ function TourCard({
     "div",
     {
       ref: trapRef,
+      "data-stepwise": "",
       role: "dialog",
       "aria-modal": "true",
       "aria-label": `${L.title} \xB7 ${index + 1}/${total}`,
@@ -1352,10 +1732,10 @@ function ShortcutsDialog({
   className,
   theme = defaultTheme
 }) {
-  const [mounted, setMounted] = useState8(false);
+  const [mounted, setMounted] = useState9(false);
   const trapRef = useFocusTrap(open);
-  useEffect10(() => setMounted(true), []);
-  useEffect10(() => {
+  useEffect11(() => setMounted(true), []);
+  useEffect11(() => {
     if (!open) return;
     const onKey = (e) => {
       if (e.key === "Escape") onClose();
@@ -1368,6 +1748,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 +1805,24 @@ export {
   Term,
   TourCard,
   TourSpotlight,
+  alignTracks,
   cookieStore,
+  createTrace,
   defaultTheme,
   flattenChapters,
   localStorageStore,
   memoryStore,
   useChapters,
   useDiscoveries,
+  useFadeIn,
   useFocusTrap,
   useGlobalKeys,
   useGuidedTour,
+  useLessonStream,
   usePrefersReducedMotion,
   useStepPlayer,
-  useSteps
+  useSteps,
+  useSyncedTracks,
+  useTrace
 };
 //# sourceMappingURL=index.js.map