@sphynxoid/stepwise 0.0.0-stage → 0.2.0

package/dist/index.js

@@ -0,0 +1,1828 @@
+"use client";
+
+// src/use-steps.ts
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+function useSteps(items, opts) {
+  const count = typeof items === "number" ? items : items.length;
+  const countRef = useRef(count);
+  countRef.current = count;
+  const onChangeRef = useRef(opts?.onChange);
+  onChangeRef.current = opts?.onChange;
+  const [cursor, setCursor] = useState(() => {
+    const initial = opts?.initialIndex ?? 0;
+    return count === 0 ? -1 : Math.max(0, Math.min(initial, count - 1));
+  });
+  const index = count === 0 ? -1 : Math.max(0, Math.min(cursor, count - 1));
+  const indexRef = useRef(index);
+  indexRef.current = index;
+  useEffect(() => {
+    if (count === 0) {
+      if (cursor !== -1) setCursor(-1);
+    } else if (cursor < 0 || cursor > count - 1) {
+      setCursor(Math.max(0, Math.min(cursor, count - 1)));
+    }
+  }, [count, cursor]);
+  const go = useCallback((i) => {
+    const c = countRef.current;
+    if (c === 0) return;
+    const clamped = Math.max(0, Math.min(i, c - 1));
+    if (clamped === indexRef.current) return;
+    indexRef.current = clamped;
+    setCursor(clamped);
+    onChangeRef.current?.(clamped);
+  }, []);
+  const next = useCallback(() => {
+    go(indexRef.current + 1);
+  }, [go]);
+  const prev = useCallback(() => {
+    go(indexRef.current - 1);
+  }, [go]);
+  const first = useCallback(() => {
+    go(0);
+  }, [go]);
+  return useMemo(
+    () => ({
+      count,
+      index,
+      atStart: index <= 0,
+      atEnd: count > 0 && index >= count - 1,
+      canNext: count > 0 && index < count - 1,
+      canPrev: count > 0 && index > 0,
+      go,
+      next,
+      prev,
+      first
+    }),
+    [count, index, go, next, prev, first]
+  );
+}
+
+// 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,
+  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);
+  const [ended, setEnded] = useState2(false);
+  const endedRef = useRef2(false);
+  const onEndRef = useRef2(onEnd);
+  onEndRef.current = onEnd;
+  const markEnded = useCallback2(() => {
+    if (endedRef.current) return;
+    endedRef.current = true;
+    setEnded(true);
+    onEndRef.current?.();
+  }, []);
+  const clearEnded = useCallback2(() => {
+    if (!endedRef.current) return;
+    endedRef.current = false;
+    setEnded(false);
+  }, []);
+  const index = started && core.index >= 0 ? core.index : -1;
+  const atEnd = total > 0 && index >= 0 && index >= total - 1;
+  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;
+    const handle = engine.connect({
+      get total() {
+        return totalRef.current;
+      },
+      onFrame: (f) => go(f),
+      onEnd: () => {
+        markEnded();
+        setPlaying(false);
+      }
+    });
+    engineApiRef.current = {
+      play: () => handle.play(),
+      pause: () => handle.pause(),
+      seek: (f) => handle.seek(f),
+      rate: (r) => handle.setRate(r)
+    };
+    return () => {
+      engineApiRef.current = {};
+      handle.disconnect();
+    };
+  }, [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();
+    first();
+    if (engineRef.current) {
+      engineApiRef.current.seek?.(0);
+      engineApiRef.current.play?.();
+    }
+  }, [first, clearEnded]);
+  const reset = useCallback2(() => {
+    setStarted(false);
+    setPlaying(false);
+    clearEnded();
+    if (engineRef.current) engineApiRef.current.pause?.();
+  }, [clearEnded]);
+  const seek = useCallback2(
+    (f) => {
+      const t = totalRef.current;
+      if (t === 0) return;
+      setStarted(true);
+      setPlaying(false);
+      clearEnded();
+      go(Math.max(0, Math.min(f, t - 1)));
+      if (engineRef.current) {
+        engineApiRef.current.pause?.();
+        engineApiRef.current.seek?.(f);
+      }
+    },
+    [go, clearEnded]
+  );
+  const next = useCallback2(
+    (onEmpty) => {
+      setPlaying(false);
+      const t = totalRef.current;
+      if (t === 0) {
+        onEmpty?.();
+        return;
+      }
+      setStarted(true);
+      clearEnded();
+      const target = Math.min(cursorRef.current + 1, t - 1);
+      coreNext();
+      if (engineRef.current) {
+        engineApiRef.current.pause?.();
+        engineApiRef.current.seek?.(target);
+      }
+    },
+    [coreNext, clearEnded]
+  );
+  const prev = useCallback2(() => {
+    setPlaying(false);
+    clearEnded();
+    const target = Math.max(0, cursorRef.current - 1);
+    corePrev();
+    if (engineRef.current) {
+      engineApiRef.current.pause?.();
+      engineApiRef.current.seek?.(target);
+    }
+  }, [corePrev, clearEnded]);
+  const toggle = useCallback2(
+    (onEmpty) => {
+      if (totalRef.current === 0) {
+        onEmpty?.();
+        return;
+      }
+      if (!playingRef.current && atEndRef.current) {
+        start();
+        return;
+      }
+      const nextPlaying = !playingRef.current;
+      setPlaying(nextPlaying);
+      setStarted(true);
+      if (engineRef.current) {
+        if (nextPlaying) engineApiRef.current.play?.();
+        else engineApiRef.current.pause?.();
+      }
+    },
+    [start]
+  );
+  const changeSpeed = useCallback2((s) => {
+    setSpeed(s);
+    if (engineRef.current) engineApiRef.current.rate?.(s);
+  }, []);
+  useEffect2(() => {
+    clearEnded();
+  }, [total, clearEnded]);
+  useEffect2(() => {
+    if (engineRef.current) return;
+    if (!playing || !started || total === 0) return;
+    if (core.index >= total - 1) {
+      markEnded();
+      setPlaying(false);
+      return;
+    }
+    const id = setTimeout(() => coreNext(), baseDelayMs / speed);
+    return () => clearTimeout(id);
+  }, [playing, started, core.index, coreNext, total, speed, baseDelayMs, markEnded]);
+  const lastWrittenHash = useRef2("");
+  const readHash = useCallback2(() => {
+    if (!syncHash || typeof window === "undefined" || total === 0) return;
+    const hash = window.location.hash;
+    if (hash === lastWrittenHash.current) return;
+    const value = readHashParam(hash, syncHash);
+    if (value === null || !/^\d+$/.test(value)) return;
+    const f = Number(value);
+    if (f < total) {
+      setStarted(true);
+      go(f);
+    }
+  }, [syncHash, total, go]);
+  useEffect2(() => {
+    readHash();
+    const onHashChange = () => readHash();
+    window.addEventListener("hashchange", onHashChange);
+    return () => window.removeEventListener("hashchange", onHashChange);
+  }, [readHash]);
+  useEffect2(() => {
+    if (!syncHash || index < 0 || typeof window === "undefined") return;
+    const next2 = writeHashParam(window.location.hash, syncHash, String(index));
+    if (window.location.hash !== next2) {
+      lastWrittenHash.current = next2;
+      window.history.replaceState(null, "", next2);
+    }
+  }, [syncHash, index]);
+  return useMemo2(
+    () => ({
+      total,
+      frame: index,
+      index,
+      playing,
+      speed,
+      atEnd,
+      ended,
+      start,
+      reset,
+      seek,
+      next,
+      prev,
+      toggle,
+      setPlaying,
+      setSpeed: changeSpeed
+    }),
+    [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 useCallback6, useEffect as useEffect5, useMemo as useMemo6, useRef as useRef6, useState as useState5 } from "react";
+function useGuidedTour(steps, opts) {
+  const [running, setRunning] = useState5(false);
+  const runningRef = useRef6(running);
+  runningRef.current = running;
+  const core = useSteps(steps.length);
+  const stepsRef = useRef6(steps);
+  stepsRef.current = steps;
+  const driverRef = useRef6(opts?.driver);
+  driverRef.current = opts?.driver;
+  const coreGoRef = useRef6(core.go);
+  coreGoRef.current = core.go;
+  const cursorRef = useRef6(core.index);
+  cursorRef.current = core.index;
+  const isSkipped = useCallback6(
+    (i) => stepsRef.current[i]?.when?.() === false,
+    []
+  );
+  const settle = useCallback6(
+    (start2, dir) => {
+      const len = stepsRef.current.length;
+      let i = start2;
+      while (i >= 0 && i < len && isSkipped(i)) i += dir;
+      if (i >= 0 && i < len) return i;
+      if (dir === 1) return null;
+      for (let j = 0; j < len; j++) if (!isSkipped(j)) return j;
+      return null;
+    },
+    [isSkipped]
+  );
+  const arrive = useCallback6(
+    (i, dir) => {
+      const target = settle(i, dir);
+      if (target === null) {
+        setRunning(false);
+        return;
+      }
+      setRunning(true);
+      coreGoRef.current(target);
+    },
+    [settle]
+  );
+  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 = useCallback6(
+    (id) => {
+      const i = stepsRef.current.findIndex((s) => s.id === id);
+      if (i >= 0) goTo(i);
+    },
+    [goTo]
+  );
+  const index = running ? core.index : null;
+  useEffect5(() => {
+    if (!running) return;
+    stepsRef.current[core.index]?.onEnter?.();
+  }, [running, core.index]);
+  useEffect5(() => {
+    const driver = driverRef.current;
+    if (!driver) return;
+    if (!running) {
+      driver.hide();
+      return;
+    }
+    const step = stepsRef.current[core.index];
+    if (!step) {
+      driver.hide();
+      return;
+    }
+    driver.show(step, {
+      index: core.index,
+      total: stepsRef.current.length,
+      next: () => goTo(core.index + 1),
+      back: () => goTo(core.index - 1),
+      end: () => setRunning(false)
+    });
+  }, [running, core.index, goTo]);
+  useEffect5(() => () => driverRef.current?.hide(), []);
+  const start = useCallback6(() => {
+    if (stepsRef.current.length === 0) return;
+    arrive(0, 1);
+  }, [arrive]);
+  const end = useCallback6(() => setRunning(false), []);
+  const resolveNext = useCallback6((i) => {
+    const list = stepsRef.current;
+    const edge = list[i]?.next?.();
+    if (edge != null) {
+      const t = list.findIndex((s) => s.id === edge);
+      if (t >= 0) return t;
+    }
+    return i + 1;
+  }, []);
+  const next = useCallback6(() => {
+    if (!runningRef.current) return;
+    const i = cursorRef.current;
+    if (stepsRef.current[i]?.gate?.() === false) return;
+    const target = resolveNext(i);
+    if (target > stepsRef.current.length - 1) {
+      setRunning(false);
+      return;
+    }
+    arrive(target, 1);
+  }, [arrive, resolveNext]);
+  const back = useCallback6(() => {
+    if (!runningRef.current) return;
+    const i = cursorRef.current;
+    if (i <= 0) return;
+    arrive(i - 1, -1);
+  }, [arrive]);
+  const current = running ? stepsRef.current[core.index] ?? null : null;
+  const blocked = current?.gate?.() === false;
+  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 useCallback7, useEffect as useEffect6, useMemo as useMemo7, useRef as useRef7, useState as useState6 } from "react";
+
+// src/flatten.ts
+function flattenChapters(chapters, depth = 0) {
+  const out = [];
+  const walk = (list, depth2, parentIndex, rootIndex) => {
+    for (const chapter of list) {
+      const index = out.length;
+      const effectiveRoot = depth2 === 0 ? index : rootIndex;
+      out.push({ chapter, depth: depth2, rootIndex: effectiveRoot, parentIndex });
+      if (chapter.children?.length) walk(chapter.children, depth2 + 1, index, effectiveRoot);
+    }
+  };
+  walk(chapters, depth, -1, -1);
+  return out;
+}
+
+// src/use-chapters.ts
+function useChapters(chapters) {
+  const [mounted, setMounted] = useState6(false);
+  const flat = useMemo7(() => flattenChapters(chapters), [chapters]);
+  const flatRef = useRef7(flat);
+  flatRef.current = flat;
+  const [active, setActive] = useState6(0);
+  const activeRef = useRef7(0);
+  activeRef.current = active;
+  const core = useSteps(flat.length, { initialIndex: 0 });
+  const coreGoRef = useRef7(core.go);
+  coreGoRef.current = core.go;
+  useEffect6(() => {
+    if (!mounted) return;
+    let raf = 0;
+    const update = () => {
+      raf = 0;
+      const flat2 = flatRef.current;
+      const mid = window.innerHeight / 2;
+      let best = -1;
+      for (let i = 0; i < flat2.length; i++) {
+        const el = document.getElementById(flat2[i].chapter.id);
+        if (!el) continue;
+        const rect = el.getBoundingClientRect();
+        if (rect.top <= mid && rect.bottom >= mid) best = i;
+      }
+      if (best === -1) {
+        for (let i = 0; i < flat2.length; i++) {
+          const el = document.getElementById(flat2[i].chapter.id);
+          if (el && el.getBoundingClientRect().top <= mid) best = i;
+        }
+        if (best === -1) best = 0;
+      }
+      if (best !== activeRef.current) {
+        setActive(best);
+        coreGoRef.current(best);
+      }
+    };
+    const onScroll = () => {
+      if (!raf) raf = requestAnimationFrame(update);
+    };
+    update();
+    window.addEventListener("scroll", onScroll, { passive: true });
+    window.addEventListener("resize", onScroll);
+    return () => {
+      window.removeEventListener("scroll", onScroll);
+      window.removeEventListener("resize", onScroll);
+      if (raf) cancelAnimationFrame(raf);
+    };
+  }, [mounted, flat.length]);
+  useEffect6(() => setMounted(true), []);
+  const goTo = useCallback7((i) => {
+    const entry = flatRef.current[i];
+    if (!entry) return;
+    setActive(i);
+    coreGoRef.current(i);
+    const el = document.getElementById(entry.chapter.id);
+    if (!el) return;
+    el.scrollIntoView({ behavior: "smooth", block: "start" });
+  }, []);
+  const next = useCallback7(() => {
+    if (activeRef.current < flatRef.current.length - 1) goTo(activeRef.current + 1);
+  }, [goTo]);
+  const prev = useCallback7(() => {
+    if (activeRef.current > 0) goTo(activeRef.current - 1);
+  }, [goTo]);
+  return useMemo7(() => ({ active: core.index, goTo, next, prev }), [core.index, goTo, next, prev]);
+}
+
+// src/use-global-keys.ts
+import { useEffect as useEffect7, useRef as useRef8 } from "react";
+var DEFAULT_IGNORED_TAGS = ["INPUT", "TEXTAREA", "SELECT", "BUTTON"];
+function useGlobalKeys(map, opts) {
+  const mapRef = useRef8(map);
+  mapRef.current = map;
+  const ignoreRef = useRef8(new Set(opts?.ignoreTags ?? DEFAULT_IGNORED_TAGS));
+  const enabledRef = useRef8(opts?.enabled ?? true);
+  enabledRef.current = opts?.enabled ?? true;
+  useEffect7(() => {
+    const onKey = (e) => {
+      const gate = enabledRef.current;
+      const enabled = typeof gate === "function" ? gate() : gate;
+      if (!enabled && e.key !== "Escape") return;
+      const tag = e.target?.tagName;
+      if (e.key !== "Escape" && tag && ignoreRef.current.has(tag)) return;
+      const fn = mapRef.current[e.key] ?? mapRef.current[e.key.toLowerCase()];
+      if (!fn) return;
+      if (e.key !== "Escape") e.preventDefault();
+      fn(e);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, []);
+}
+
+// src/use-discoveries.ts
+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() {
+      if (typeof window === "undefined") return [];
+      try {
+        const parsed = JSON.parse(window.localStorage.getItem(key) ?? "[]");
+        return Array.isArray(parsed) ? parsed.filter((x) => typeof x === "string") : [];
+      } catch {
+        return [];
+      }
+    },
+    write(ids) {
+      if (typeof window === "undefined") return;
+      try {
+        window.localStorage.setItem(key, JSON.stringify(ids));
+      } catch {
+      }
+    }
+  };
+}
+function cookieStore(key = "stepwise.discoveries") {
+  const read = () => {
+    if (typeof document === "undefined") return [];
+    const match = document.cookie.match(new RegExp(`(?:^|;\\s*)${key}=([^;]*)`));
+    if (!match) return [];
+    try {
+      const parsed = JSON.parse(decodeURIComponent(match[1]));
+      return Array.isArray(parsed) ? parsed.filter((x) => typeof x === "string") : [];
+    } catch {
+      return [];
+    }
+  };
+  return {
+    read,
+    write(ids) {
+      if (typeof document === "undefined") return;
+      document.cookie = `${key}=${encodeURIComponent(JSON.stringify(ids))}; max-age=31536000; path=/; SameSite=Lax`;
+    }
+  };
+}
+function memoryStore(seed = []) {
+  let ids = [...seed];
+  return {
+    read: () => [...ids],
+    write(next) {
+      ids = [...next];
+    }
+  };
+}
+function useDiscoveries(opts) {
+  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] = useState7(() => /* @__PURE__ */ new Set());
+  const [ready, setReady] = useState7(false);
+  const idsRef = useRef9(ids);
+  idsRef.current = ids;
+  useEffect8(() => {
+    setIds(new Set(storeRef.current.read()));
+    setReady(true);
+  }, []);
+  const markDiscovered = useCallback8((id) => {
+    const additions = Array.isArray(id) ? id : [id];
+    const merged = new Set(idsRef.current);
+    let changed = false;
+    for (const x of additions) {
+      if (!merged.has(x)) {
+        merged.add(x);
+        changed = true;
+      }
+    }
+    if (!changed) return;
+    idsRef.current = merged;
+    setIds(merged);
+    storeRef.current.write([...merged]);
+  }, []);
+  const reset = useCallback8(() => {
+    const empty = /* @__PURE__ */ new Set();
+    idsRef.current = empty;
+    setIds(empty);
+    storeRef.current.write([]);
+  }, []);
+  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 useEffect9, useRef as useRef10 } from "react";
+function useFocusTrap(active) {
+  const ref = useRef10(null);
+  useEffect9(() => {
+    if (!active) return;
+    const container = ref.current;
+    if (!container) return;
+    const previous = document.activeElement;
+    container.focus({ preventScroll: true });
+    const onKey = (e) => {
+      if (e.key !== "Tab") return;
+      const focusables = Array.from(
+        container.querySelectorAll(
+          'a[href], button:not([disabled]), textarea, input, select, [tabindex]:not([tabindex="-1"])'
+        )
+      ).filter((el) => el.offsetParent !== null || el === container);
+      if (focusables.length === 0) return;
+      const first = focusables[0];
+      const last = focusables[focusables.length - 1];
+      const current = document.activeElement;
+      if (e.shiftKey && (current === first || !container.contains(current))) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && (current === last || !container.contains(current))) {
+        e.preventDefault();
+        first.focus();
+      }
+    };
+    document.addEventListener("keydown", onKey, true);
+    return () => {
+      document.removeEventListener("keydown", onKey, true);
+      previous?.focus({ preventScroll: true });
+    };
+  }, [active]);
+  return ref;
+}
+
+// src/glossary.tsx
+import {
+  createContext,
+  useCallback as useCallback9,
+  useContext,
+  useEffect as useEffect10,
+  useId,
+  useLayoutEffect as useLayoutEffect2,
+  useMemo as useMemo9,
+  useRef as useRef11,
+  useState as useState8
+} from "react";
+import { createPortal } from "react-dom";
+
+// src/cn.ts
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+function cn(...inputs) {
+  return twMerge(clsx(inputs));
+}
+
+// src/theme.ts
+var defaultTheme = {
+  toneSegment: {
+    neutral: "bg-white/10",
+    accent: "bg-accent/70",
+    good: "bg-primary",
+    bad: "bg-destructive/70",
+    write: "bg-foreground/30",
+    idle: "bg-white/5"
+  },
+  toneChip: {
+    neutral: "text-foreground/50 border-white/10",
+    accent: "text-accent border-accent/40",
+    good: "text-primary border-primary/40",
+    bad: "text-destructive border-destructive/40",
+    write: "text-foreground/70 border-white/20",
+    idle: "text-foreground/30 border-white/10"
+  },
+  buttonBase: "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-sm font-mono transition-colors duration-200 disabled:pointer-events-none disabled:opacity-50 cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50",
+  buttonVariants: {
+    ghost: "border border-transparent text-foreground/70 hover:bg-white/5 hover:text-foreground",
+    outline: "border border-primary/40 bg-background/40 text-foreground/85 hover:border-primary/70 hover:text-foreground",
+    primary: "border border-primary bg-primary/90 text-primary-foreground hover:bg-primary"
+  },
+  surface: "border border-white/10 bg-background/85 backdrop-blur-md",
+  overlay: "bg-black/70 backdrop-blur-sm",
+  codeBlock: "rounded-sm border border-white/10 bg-black/40 px-2.5 py-2 font-mono text-[11px] leading-5 overflow-x-auto",
+  codeMuted: "text-foreground/35",
+  kbd: "font-mono text-[10px] px-1.5 py-0.5 border border-white/20 bg-white/5 rounded-sm text-foreground/80",
+  spotlight: "rounded-sm ring-2 ring-primary/80 transition-all duration-300",
+  muted: "text-foreground/40"
+};
+
+// src/glossary.tsx
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var MAX_DEPTH = 4;
+var CARD_WIDTH = 288;
+var OPEN_DELAY_MS = 60;
+var CLOSE_GRACE_MS = 120;
+var GlossaryContext = createContext(null);
+var DepthContext = createContext(0);
+var AppendixContext = createContext(false);
+function GlossaryProvider({
+  entries,
+  theme = defaultTheme,
+  children
+}) {
+  const value = useMemo9(
+    () => ({ byId: new Map(entries.map((e) => [e.id, e])), entries, theme }),
+    [entries, theme]
+  );
+  return /* @__PURE__ */ jsx(GlossaryContext.Provider, { value, children });
+}
+function Term({ id, children, className }) {
+  const ctx = useContext(GlossaryContext);
+  const depth = useContext(DepthContext);
+  const entry = ctx?.byId.get(id);
+  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 = useCallback9(() => {
+    window.clearTimeout(openTimer.current);
+    window.clearTimeout(closeTimer.current);
+    openRef.current = false;
+    setOpen(false);
+  }, []);
+  const openNow = useCallback9((focusCard = false) => {
+    window.clearTimeout(closeTimer.current);
+    window.clearTimeout(openTimer.current);
+    openRef.current = true;
+    setOpen(true);
+    if (focusCard) {
+      requestAnimationFrame(() => cardRef.current?.focus({ preventScroll: true }));
+    }
+  }, []);
+  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 = useCallback9(() => {
+    window.clearTimeout(openTimer.current);
+    window.clearTimeout(closeTimer.current);
+    closeTimer.current = window.setTimeout(closeNow, CLOSE_GRACE_MS);
+  }, [closeNow]);
+  useLayoutEffect2(() => {
+    if (!open) {
+      setPos(null);
+      return;
+    }
+    let raf = 0;
+    const update = () => {
+      raf = 0;
+      const trigger = triggerRef.current;
+      const card = cardRef.current;
+      if (!trigger) return;
+      const r = trigger.getBoundingClientRect();
+      const margin = 8;
+      const gap = 8;
+      const cw = card?.offsetWidth ?? CARD_WIDTH;
+      const ch = card?.offsetHeight ?? 160;
+      let top = r.bottom + gap;
+      if (top + ch > window.innerHeight - margin) {
+        top = r.top - gap - ch;
+        if (top < margin) top = margin;
+      }
+      let left = r.left;
+      left = Math.max(margin, Math.min(left, window.innerWidth - cw - margin));
+      setPos({ left, top });
+    };
+    const onMove = () => {
+      if (!raf) raf = requestAnimationFrame(update);
+    };
+    update();
+    window.addEventListener("scroll", onMove, { passive: true });
+    window.addEventListener("resize", onMove);
+    return () => {
+      window.removeEventListener("scroll", onMove);
+      window.removeEventListener("resize", onMove);
+      if (raf) cancelAnimationFrame(raf);
+    };
+  }, [open]);
+  useEffect10(() => {
+    if (!open) return;
+    const onPointerDown = (e) => {
+      const target = e.target;
+      if (wrapperRef.current?.contains(target)) return;
+      if (cardRef.current?.contains(target)) return;
+      closeNow();
+    };
+    document.addEventListener("pointerdown", onPointerDown);
+    return () => document.removeEventListener("pointerdown", onPointerDown);
+  }, [open, closeNow]);
+  useEffect10(() => () => {
+    window.clearTimeout(openTimer.current);
+    window.clearTimeout(closeTimer.current);
+  }, []);
+  const capped = depth >= MAX_DEPTH;
+  const inAppendix = useContext(AppendixContext);
+  const interactive = !capped && !inAppendix;
+  const t = ctx?.theme ?? defaultTheme;
+  if (inAppendix) {
+    const linked = ctx?.byId.get(id);
+    if (!linked) return /* @__PURE__ */ jsx("span", { className, children: display });
+    return /* @__PURE__ */ jsx(
+      "a",
+      {
+        href: `#glossary-${linked.id}`,
+        title: linked.term,
+        className: cn("text-accent underline underline-offset-4 hover:text-primary", className),
+        children: display
+      }
+    );
+  }
+  const triggerProps = interactive ? {
+    role: "button",
+    tabIndex: 0,
+    "aria-expanded": open,
+    "aria-describedby": open ? tipId : void 0,
+    onMouseEnter: scheduleOpen,
+    onMouseLeave: scheduleClose,
+    onFocus: () => openNow(),
+    onBlur: (e) => {
+      const next = e.relatedTarget;
+      if (next && (wrapperRef.current?.contains(next) || cardRef.current?.contains(next))) return;
+      scheduleClose();
+    },
+    onClick: () => openNow(),
+    onKeyDown: (e) => {
+      if (e.key === "Escape") {
+        e.stopPropagation();
+        closeNow();
+      } else if ((e.key === "Enter" || e.key === " ") && !open) {
+        e.preventDefault();
+        openNow(true);
+      }
+    }
+  } : {};
+  if (!ctx || !entry) {
+    return /* @__PURE__ */ jsx("span", { className: cn("text-foreground/85", className), children: display });
+  }
+  return /* @__PURE__ */ jsxs(
+    "span",
+    {
+      ref: wrapperRef,
+      "data-stepwise": "",
+      className: "relative inline",
+      onMouseEnter: interactive ? scheduleOpen : void 0,
+      onMouseLeave: interactive ? scheduleClose : void 0,
+      children: [
+        /* @__PURE__ */ jsx(
+          "span",
+          {
+            ref: triggerRef,
+            ...triggerProps,
+            className: cn(
+              "border-b border-dotted",
+              interactive ? "border-primary/50 text-foreground/85 hover:text-primary focus-visible:text-primary cursor-help" : "text-foreground/70",
+              className
+            ),
+            children: display
+          }
+        ),
+        open && createPortal(
+          /* @__PURE__ */ jsx(DepthContext.Provider, { value: depth + 1, children: /* @__PURE__ */ jsxs(
+            "span",
+            {
+              ref: cardRef,
+              "data-stepwise": "",
+              role: "tooltip",
+              id: tipId,
+              tabIndex: -1,
+              onKeyDown: (e) => {
+                if (e.key === "Escape") {
+                  e.stopPropagation();
+                  closeNow();
+                  triggerRef.current?.focus({ preventScroll: true });
+                }
+              },
+              onMouseEnter: interactive ? () => window.clearTimeout(closeTimer.current) : void 0,
+              onMouseLeave: interactive ? scheduleClose : void 0,
+              className: cn(
+                "fixed z-50 block w-72 max-w-[calc(100vw-1rem)] rounded-sm p-3 shadow-2xl outline-none motion-reduce:transition-none",
+                "transition-opacity duration-150",
+                t.surface,
+                "border-white/15 bg-popover",
+                pos === null && "invisible"
+              ),
+              style: pos ? { left: pos.left, top: pos.top, maxHeight: "min(60vh, 20rem)", overflowY: "auto" } : { visibility: "hidden" },
+              children: [
+                /* @__PURE__ */ jsx("span", { className: "mb-1 block font-mono text-[11px] uppercase tracking-widest text-primary/90", children: entry.term }),
+                /* @__PURE__ */ jsx("span", { className: "block text-[11px] font-mono leading-relaxed text-foreground/70", children: entry.definition })
+              ]
+            }
+          ) }),
+          document.body
+        )
+      ]
+    }
+  );
+}
+function GlossaryAppendix({
+  entries,
+  title = "Glossary",
+  intro,
+  footer,
+  columns = 2,
+  bare = false,
+  className,
+  entryClassName,
+  renderEntry
+}) {
+  const ctxEntries = useContext(GlossaryContext)?.entries;
+  const theme = useContext(GlossaryContext)?.theme ?? defaultTheme;
+  const list = entries ?? ctxEntries;
+  if (!list || list.length === 0) return null;
+  const grid = /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: cn(
+        "grid grid-cols-1 gap-x-10 gap-y-8",
+        columns === 2 ? "xl:grid-cols-2" : "grid-cols-1"
+      ),
+      children: list.map(
+        (entry) => renderEntry ? /* @__PURE__ */ jsx("div", { id: `glossary-${entry.id}`, className: "scroll-mt-40", children: renderEntry(entry) }, entry.id) : /* @__PURE__ */ jsxs("div", { id: `glossary-${entry.id}`, className: cn("scroll-mt-40", entryClassName), children: [
+          /* @__PURE__ */ jsx("h3", { className: "font-mono text-[11px] uppercase tracking-widest text-primary/90 mb-1.5", children: entry.term }),
+          /* @__PURE__ */ jsx("div", { className: "text-[12px] font-mono text-foreground/60 leading-relaxed [&_strong]:text-foreground/80", children: entry.definition })
+        ] }, entry.id)
+      )
+    }
+  );
+  const body = /* @__PURE__ */ jsxs(Fragment, { children: [
+    intro && /* @__PURE__ */ jsx("div", { className: "mb-8 text-[12px] font-mono text-foreground/55 leading-relaxed max-w-3xl [&_a]:text-accent [&_a]:underline [&_a]:underline-offset-4", children: intro }),
+    grid,
+    footer && /* @__PURE__ */ jsx("div", { className: "mt-8", children: footer })
+  ] });
+  if (bare) {
+    return /* @__PURE__ */ jsx(AppendixContext.Provider, { value: true, children: body });
+  }
+  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 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;
+var TONE_CHIP_CLASS = defaultTheme.toneChip;
+var BTN_BASE = defaultTheme.buttonBase;
+var BTN_GHOST = defaultTheme.buttonVariants.ghost;
+var BTN_OUTLINE = defaultTheme.buttonVariants.outline;
+var BTN_PRIMARY = defaultTheme.buttonVariants.primary;
+function StepButton({
+  variant = "ghost",
+  className,
+  ...props
+}) {
+  const variantClass = variant === "outline" ? BTN_OUTLINE : variant === "primary" ? BTN_PRIMARY : BTN_GHOST;
+  return /* @__PURE__ */ jsx2("button", { type: "button", ...props, className: cn(BTN_BASE, variantClass, className) });
+}
+function CodeBlock({
+  lines,
+  theme = defaultTheme,
+  className
+}) {
+  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);
+    }
+    if (commentStart > 0) {
+      return /* @__PURE__ */ jsxs2("div", { className: "whitespace-pre", children: [
+        /* @__PURE__ */ jsx2("span", { className: "text-foreground/85", children: line.slice(0, commentStart) }),
+        /* @__PURE__ */ jsx2("span", { className: theme.codeMuted, children: line.slice(commentStart) })
+      ] }, i);
+    }
+    return /* @__PURE__ */ jsx2("div", { className: "whitespace-pre text-foreground/85", children: line }, i);
+  }) });
+}
+function StepScrubber({
+  count,
+  index,
+  toneAt,
+  titleAt,
+  onSeek,
+  emptyHint,
+  className,
+  theme = defaultTheme,
+  labels,
+  groupOf
+}) {
+  const onKey = (e) => {
+    if (count === 0) return;
+    if (e.key === "ArrowRight" || e.key === "ArrowUp") {
+      e.preventDefault();
+      e.stopPropagation();
+      onSeek(Math.min(count - 1, index + 1));
+    } else if (e.key === "ArrowLeft" || e.key === "ArrowDown") {
+      e.preventDefault();
+      e.stopPropagation();
+      onSeek(Math.max(0, index - 1));
+    } else if (e.key === "Home") {
+      e.preventDefault();
+      e.stopPropagation();
+      onSeek(0);
+    } else if (e.key === "End") {
+      e.preventDefault();
+      e.stopPropagation();
+      onSeek(count - 1);
+    }
+  };
+  if (count === 0) {
+    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(
+    "div",
+    {
+      "aria-hidden": "true",
+      title: titleAt ? titleAt(i) : `frame ${i + 1}`,
+      onClick: () => onSeek(i),
+      className: cn(
+        "h-3.5 flex-1 min-w-[3px] rounded-[2px] transition-all cursor-pointer",
+        theme.toneSegment[toneAt?.(i) ?? "neutral"],
+        i === index && "ring-2 ring-primary scale-y-150"
+      )
+    },
+    i
+  );
+  let rows;
+  if (groupOf) {
+    const groups = [];
+    for (let i = 0; i < count; i++) {
+      const g = groupOf(i);
+      const lastGroup = groups[groups.length - 1];
+      if (lastGroup && groupOf(lastGroup[0]) === g) lastGroup.push(i);
+      else groups.push([i]);
+    }
+    rows = groups.map((units, gi) => /* @__PURE__ */ jsx2(
+      "div",
+      {
+        "aria-hidden": "true",
+        className: "flex-1 min-w-[3px] flex gap-[2px] items-center",
+        style: { flexGrow: units.length },
+        children: units.map(segment)
+      },
+      gi
+    ));
+  } else {
+    rows = Array.from({ length: count }, (_, i) => segment(i));
+  }
+  return /* @__PURE__ */ jsx2(
+    "div",
+    {
+      "data-stepwise": "",
+      role: "slider",
+      tabIndex: 0,
+      "aria-label": labels?.scrubber ?? "Frames",
+      "aria-valuemin": 1,
+      "aria-valuemax": count,
+      "aria-valuenow": index + 1,
+      "aria-valuetext": valueText,
+      "aria-orientation": "horizontal",
+      onKeyDown: onKey,
+      className: cn(
+        "flex-1 flex items-center gap-[3px] min-w-0 cursor-pointer outline-none focus-visible:ring-2 focus-visible:ring-primary/60 rounded-sm",
+        className
+      ),
+      children: rows
+    }
+  );
+}
+function PlayerBar({
+  player,
+  toneAt,
+  titleAt,
+  leading,
+  onEmpty,
+  emptyHint,
+  className,
+  theme = defaultTheme,
+  groupOf,
+  labels
+}) {
+  const L = {
+    previous: labels?.previous ?? "Previous step",
+    play: labels?.play ?? "Play",
+    pause: labels?.pause ?? "Pause",
+    replay: labels?.replay ?? "Replay",
+    next: labels?.next ?? "Next step"
+  };
+  const playLabel = player.playing ? L.pause : player.total > 0 && player.atEnd ? L.replay : L.play;
+  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 }),
+    /* @__PURE__ */ jsx2(StepButton, { variant: "ghost", onClick: () => player.next(onEmpty), className: "h-7 px-2 text-xs", "aria-label": L.next, children: "\u2192" }),
+    /* @__PURE__ */ jsx2(
+      StepScrubber,
+      {
+        count: player.total,
+        index: player.index,
+        toneAt,
+        titleAt,
+        onSeek: (i) => player.seek(i),
+        emptyHint,
+        theme,
+        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" })
+  ] });
+}
+function ChapterNav({
+  chapters,
+  active,
+  onNavigate,
+  hint,
+  className,
+  theme = defaultTheme
+}) {
+  const flat = flattenChapters(chapters);
+  const renderRow = (items, depth) => {
+    const indent = "\u2014 ".repeat(depth);
+    return items.map((chapter) => {
+      const flatIndex = flat.findIndex((f) => f.chapter.id === chapter.id);
+      const isActive = flatIndex === active;
+      return /* @__PURE__ */ jsxs2("div", { className: cn("flex items-center", depth > 0 && "gap-1"), children: [
+        /* @__PURE__ */ jsxs2(
+          StepButton,
+          {
+            type: "button",
+            onClick: () => onNavigate(flatIndex),
+            "aria-current": isActive ? "true" : void 0,
+            title: chapter.hint ?? chapter.label,
+            className: cn(
+              "flex items-center gap-1.5 px-2.5 py-1 rounded-sm text-[11px] font-mono border transition-colors cursor-pointer whitespace-nowrap",
+              depth > 0 && "px-2 text-[10px] border-transparent",
+              isActive ? depth === 0 ? "border-primary/50 text-primary bg-primary/10" : "text-primary bg-primary/5" : depth === 0 ? "border-transparent text-foreground/50 hover:text-foreground hover:border-white/15" : "text-foreground/45 hover:text-foreground"
+            ),
+            children: [
+              depth === 0 && chapter.numbered !== false && /* @__PURE__ */ jsx2("span", { className: cn("text-[9px]", isActive ? "text-primary/80" : "text-foreground/30"), children: String(flatIndex + 1).padStart(2, "0") }),
+              depth > 0 && /* @__PURE__ */ jsx2("span", { className: "text-foreground/25", children: indent }),
+              chapter.label
+            ]
+          }
+        ),
+        chapter.children && chapter.children.length > 0 && /* @__PURE__ */ jsx2("div", { className: "flex flex-wrap items-center gap-1", children: renderRow(chapter.children, depth + 1) })
+      ] }, chapter.id);
+    });
+  };
+  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)]",
+        theme.surface,
+        className
+      ),
+      children: /* @__PURE__ */ jsxs2("div", { className: "p-1.5", children: [
+        /* @__PURE__ */ jsxs2("div", { className: "flex items-center gap-1 overflow-x-auto", children: [
+          /* @__PURE__ */ jsx2("span", { className: cn("shrink-0 px-2 text-[9px] font-mono uppercase tracking-widest", theme.muted), children: "Chapters" }),
+          renderRow(chapters, 0)
+        ] }),
+        hint && /* @__PURE__ */ jsx2("div", { className: "flex justify-end px-2 pt-1.5", children: /* @__PURE__ */ jsx2("span", { className: cn("text-[10px] font-mono hidden md:inline", theme.muted), children: hint }) })
+      ] })
+    }
+  );
+}
+function LessonPager({
+  prev,
+  next,
+  onNavigate,
+  className,
+  labels
+}) {
+  return /* @__PURE__ */ jsxs2("div", { "data-stepwise": "", className: cn("flex items-center gap-2", className), children: [
+    /* @__PURE__ */ jsxs2(
+      StepButton,
+      {
+        variant: "outline",
+        onClick: () => onNavigate("prev"),
+        disabled: !prev,
+        title: prev?.hint ?? prev?.label,
+        className: "h-9 px-3 text-[11px]",
+        "aria-label": prev ? `${labels?.previous ?? "Previous lesson"}: ${prev.label}` : "No previous lesson",
+        children: [
+          "\u2190 ",
+          prev?.label ?? "\u2014"
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsxs2(
+      StepButton,
+      {
+        variant: "outline",
+        onClick: () => onNavigate("next"),
+        disabled: !next,
+        title: next?.hint ?? next?.label,
+        className: "h-9 px-3 text-[11px] ml-auto",
+        "aria-label": next ? `${labels?.next ?? "Next lesson"}: ${next.label}` : "No next lesson",
+        children: [
+          next?.label ?? "\u2014",
+          " \u2192"
+        ]
+      }
+    )
+  ] });
+}
+function TourSpotlight({
+  target,
+  theme = defaultTheme
+}) {
+  const [rect, setRect] = useState9(null);
+  useEffect11(() => {
+    if (!target) {
+      setRect(null);
+      return;
+    }
+    let el = null;
+    let scrolled = false;
+    let raf = 0;
+    let last = "";
+    const tick = () => {
+      if (!el) {
+        el = document.getElementById(target) ?? document.querySelector(`[data-tour="${target}"]`);
+        if (el && !scrolled) {
+          scrolled = true;
+          el.scrollIntoView({ block: "center", behavior: "smooth", inline: "nearest" });
+        }
+      }
+      if (el) {
+        const r = el.getBoundingClientRect();
+        const key = [r.top, r.left, r.width, r.height].map((n) => Math.round(n)).join(",");
+        if (key !== last) {
+          last = key;
+          setRect(r);
+        }
+      }
+      raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, [target]);
+  if (!rect) return null;
+  const pad = 6;
+  return /* @__PURE__ */ jsx2("div", { "data-stepwise": "", className: "fixed inset-0 z-40 pointer-events-none", children: /* @__PURE__ */ jsx2(
+    "div",
+    {
+      className: cn("absolute", theme.spotlight),
+      style: {
+        top: rect.top - pad,
+        left: rect.left - pad,
+        width: rect.width + pad * 2,
+        height: rect.height + pad * 2,
+        boxShadow: "0 0 0 9999px rgba(0,0,0,0.55)"
+      }
+    }
+  ) });
+}
+function TourCard({
+  step,
+  index,
+  total,
+  onNext,
+  onBack,
+  onEnd,
+  labels,
+  className,
+  theme = defaultTheme,
+  nextDisabled = false
+}) {
+  const L = {
+    title: labels?.title ?? "Guided tour",
+    back: labels?.back ?? "Back",
+    next: labels?.next ?? "Next",
+    finish: labels?.finish ?? "Finish",
+    end: labels?.end ?? "End tour"
+  };
+  const trapRef = useFocusTrap(true);
+  return /* @__PURE__ */ jsxs2(
+    "div",
+    {
+      ref: trapRef,
+      "data-stepwise": "",
+      role: "dialog",
+      "aria-modal": "true",
+      "aria-label": `${L.title} \xB7 ${index + 1}/${total}`,
+      tabIndex: -1,
+      className: cn(
+        "fixed bottom-6 left-1/2 -translate-x-1/2 z-50 w-[min(92vw,26rem)] rounded-sm p-4 outline-none",
+        theme.surface,
+        "border-primary/30 bg-background/95 shadow-2xl",
+        className
+      ),
+      children: [
+        /* @__PURE__ */ jsxs2("div", { className: "flex items-center justify-between mb-2", children: [
+          /* @__PURE__ */ jsxs2("span", { className: "text-[10px] font-mono uppercase tracking-widest text-primary/70", children: [
+            L.title,
+            " \xB7 ",
+            index + 1,
+            "/",
+            total
+          ] }),
+          /* @__PURE__ */ jsx2(
+            StepButton,
+            {
+              type: "button",
+              onClick: onEnd,
+              "aria-label": L.end,
+              className: "text-foreground/40 hover:text-foreground cursor-pointer leading-none",
+              children: "\xD7"
+            }
+          )
+        ] }),
+        /* @__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__ */ 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(
+            StepButton,
+            {
+              variant: "primary",
+              onClick: onNext,
+              disabled: nextDisabled,
+              className: "h-7 px-4 text-[11px] ml-auto",
+              children: index === total - 1 ? L.finish : L.next
+            }
+          )
+        ] })
+      ]
+    }
+  );
+}
+function ShortcutsDialog({
+  open,
+  onClose,
+  items,
+  title = "Keyboard shortcuts",
+  className,
+  theme = defaultTheme
+}) {
+  const [mounted, setMounted] = useState9(false);
+  const trapRef = useFocusTrap(open);
+  useEffect11(() => setMounted(true), []);
+  useEffect11(() => {
+    if (!open) return;
+    const onKey = (e) => {
+      if (e.key === "Escape") onClose();
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [open, onClose]);
+  if (!open || !mounted) return null;
+  return createPortal2(
+    /* @__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(
+          "div",
+          {
+            ref: trapRef,
+            role: "dialog",
+            "aria-modal": "true",
+            "aria-label": title,
+            tabIndex: -1,
+            onClick: (e) => e.stopPropagation(),
+            className: cn(
+              "w-full max-w-md rounded-sm p-5 shadow-2xl outline-none",
+              theme.surface,
+              "border-white/15 bg-card"
+            ),
+            children: [
+              /* @__PURE__ */ jsxs2("div", { className: "flex items-center justify-between mb-4", children: [
+                /* @__PURE__ */ jsx2("h3", { className: "text-lg text-primary", children: title }),
+                /* @__PURE__ */ jsx2(
+                  StepButton,
+                  {
+                    type: "button",
+                    onClick: onClose,
+                    "aria-label": "Close shortcuts",
+                    className: "text-foreground/40 hover:text-foreground cursor-pointer leading-none text-lg",
+                    children: "\xD7"
+                  }
+                )
+              ] }),
+              /* @__PURE__ */ jsx2("dl", { className: "space-y-2", children: items.map((s) => /* @__PURE__ */ jsxs2("div", { className: "flex items-center justify-between gap-4", children: [
+                /* @__PURE__ */ jsx2("dt", { children: /* @__PURE__ */ jsx2("kbd", { className: theme.kbd, children: s.keys }) }),
+                /* @__PURE__ */ jsx2("dd", { className: "font-mono text-[11px] text-foreground/60 text-right", children: s.action })
+              ] }, s.keys)) })
+            ]
+          }
+        )
+      }
+    ),
+    document.body
+  );
+}
+export {
+  ChapterNav,
+  CodeBlock,
+  GlossaryAppendix,
+  GlossaryProvider,
+  LessonPager,
+  PlayerBar,
+  ShortcutsDialog,
+  StepScrubber,
+  TONE_CHIP_CLASS,
+  TONE_SEGMENT_CLASS,
+  Term,
+  TourCard,
+  TourSpotlight,
+  alignTracks,
+  cookieStore,
+  createTrace,
+  defaultTheme,
+  flattenChapters,
+  localStorageStore,
+  memoryStore,
+  useChapters,
+  useDiscoveries,
+  useFadeIn,
+  useFocusTrap,
+  useGlobalKeys,
+  useGuidedTour,
+  useLessonStream,
+  usePrefersReducedMotion,
+  useStepPlayer,
+  useSteps,
+  useSyncedTracks,
+  useTrace
+};
+//# sourceMappingURL=index.js.map