@sphynxoid/stepwise 0.2.0 → 0.3.0

package/dist/index.js

@@ -66,17 +66,23 @@ function useStepPlayer({
   engine,
   syncHash,
   onEnd,
-  respectReducedMotion = true
+  respectReducedMotion = true,
+  holdAt,
+  follow = false
 }) {
   const core = useSteps(total);
   const { go, next: coreNext, prev: corePrev, first } = core;
   const [started, setStarted] = useState2(autoPlay && total > 0);
-  const [playing, setPlaying] = useState2(autoPlay && total > 0);
+  const [playing, setPlaying] = useState2(autoPlay && (total > 0 || follow));
   const [speed, setSpeed] = useState2(1);
   const [ended, setEnded] = useState2(false);
   const endedRef = useRef2(false);
   const onEndRef = useRef2(onEnd);
   onEndRef.current = onEnd;
+  const holdAtRef = useRef2(holdAt);
+  holdAtRef.current = holdAt;
+  const [held, setHeld] = useState2(null);
+  const releasedRef = useRef2(/* @__PURE__ */ new Set());
   const markEnded = useCallback2(() => {
     if (endedRef.current) return;
     endedRef.current = true;
@@ -90,6 +96,7 @@ function useStepPlayer({
   }, []);
   const index = started && core.index >= 0 ? core.index : -1;
   const atEnd = total > 0 && index >= 0 && index >= total - 1;
+  const live = follow && held === null && (started ? playing || atEnd : playing);
   const totalRef = useRef2(total);
   totalRef.current = total;
   const cursorRef = useRef2(core.index);
@@ -98,6 +105,10 @@ function useStepPlayer({
   playingRef.current = playing;
   const atEndRef = useRef2(atEnd);
   atEndRef.current = atEnd;
+  const heldRef = useRef2(held);
+  heldRef.current = held;
+  const startedRef = useRef2(started);
+  startedRef.current = started;
   const engineRef = useRef2(engine);
   engineRef.current = engine;
   const engineApiRef = useRef2({});
@@ -135,6 +146,8 @@ function useStepPlayer({
     setStarted(true);
     setPlaying(true);
     clearEnded();
+    setHeld(null);
+    releasedRef.current = /* @__PURE__ */ new Set();
     first();
     if (engineRef.current) {
       engineApiRef.current.seek?.(0);
@@ -145,6 +158,8 @@ function useStepPlayer({
     setStarted(false);
     setPlaying(false);
     clearEnded();
+    setHeld(null);
+    releasedRef.current = /* @__PURE__ */ new Set();
     if (engineRef.current) engineApiRef.current.pause?.();
   }, [clearEnded]);
   const seek = useCallback2(
@@ -154,6 +169,7 @@ function useStepPlayer({
       setStarted(true);
       setPlaying(false);
       clearEnded();
+      setHeld(null);
       go(Math.max(0, Math.min(f, t - 1)));
       if (engineRef.current) {
         engineApiRef.current.pause?.();
@@ -172,6 +188,7 @@ function useStepPlayer({
       }
       setStarted(true);
       clearEnded();
+      setHeld(null);
       const target = Math.min(cursorRef.current + 1, t - 1);
       coreNext();
       if (engineRef.current) {
@@ -184,6 +201,7 @@ function useStepPlayer({
   const prev = useCallback2(() => {
     setPlaying(false);
     clearEnded();
+    setHeld(null);
     const target = Math.max(0, cursorRef.current - 1);
     corePrev();
     if (engineRef.current) {
@@ -204,6 +222,10 @@ function useStepPlayer({
       const nextPlaying = !playingRef.current;
       setPlaying(nextPlaying);
       setStarted(true);
+      if (nextPlaying) {
+        releasedRef.current.add(cursorRef.current);
+        setHeld(null);
+      }
       if (engineRef.current) {
         if (nextPlaying) engineApiRef.current.play?.();
         else engineApiRef.current.pause?.();
@@ -211,6 +233,36 @@ function useStepPlayer({
     },
     [start]
   );
+  const release = useCallback2(() => {
+    const h = heldRef.current;
+    if (h === null) return;
+    releasedRef.current.add(h);
+    setHeld(null);
+    setPlaying(true);
+  }, []);
+  const jump = useCallback2(
+    (f) => {
+      const t = totalRef.current;
+      if (t === 0) return;
+      setStarted(true);
+      go(Math.max(0, Math.min(f, t - 1)));
+      if (engineRef.current) engineApiRef.current.seek?.(f);
+    },
+    [go]
+  );
+  const goLive = useCallback2(() => {
+    const t = totalRef.current;
+    if (t === 0) return;
+    setStarted(true);
+    setPlaying(false);
+    clearEnded();
+    setHeld(null);
+    go(t - 1);
+    if (engineRef.current) {
+      engineApiRef.current.pause?.();
+      engineApiRef.current.seek?.(t - 1);
+    }
+  }, [go, clearEnded]);
   const changeSpeed = useCallback2((s) => {
     setSpeed(s);
     if (engineRef.current) engineApiRef.current.rate?.(s);
@@ -218,6 +270,21 @@ function useStepPlayer({
   useEffect2(() => {
     clearEnded();
   }, [total, clearEnded]);
+  const prevTotal = useRef2(total);
+  useEffect2(() => {
+    const before = prevTotal.current;
+    prevTotal.current = total;
+    if (!follow || engineRef.current || total <= before) return;
+    if (heldRef.current !== null) return;
+    if (!startedRef.current) {
+      if (playingRef.current) setStarted(true);
+      return;
+    }
+    if (playingRef.current || cursorRef.current >= before - 1) setPlaying(true);
+  }, [total, follow]);
+  useEffect2(() => {
+    if (held !== null && held !== core.index) setHeld(null);
+  }, [held, core.index]);
   useEffect2(() => {
     if (engineRef.current) return;
     if (!playing || !started || total === 0) return;
@@ -226,30 +293,48 @@ function useStepPlayer({
       setPlaying(false);
       return;
     }
+    if (holdAtRef.current?.(core.index) && !releasedRef.current.has(core.index)) {
+      setHeld(core.index);
+      setPlaying(false);
+      return;
+    }
     const id = setTimeout(() => coreNext(), baseDelayMs / speed);
     return () => clearTimeout(id);
   }, [playing, started, core.index, coreNext, total, speed, baseDelayMs, markEnded]);
   const lastWrittenHash = useRef2("");
+  const pendingRead = useRef2(null);
   const readHash = useCallback2(() => {
-    if (!syncHash || typeof window === "undefined" || total === 0) return;
+    const t = totalRef.current;
+    if (!syncHash || typeof window === "undefined" || t === 0) return;
     const hash = window.location.hash;
     if (hash === lastWrittenHash.current) return;
     const value = readHashParam(hash, syncHash);
     if (value === null || !/^\d+$/.test(value)) return;
     const f = Number(value);
-    if (f < total) {
+    if (f < t) {
+      pendingRead.current = f;
       setStarted(true);
       go(f);
     }
-  }, [syncHash, total, go]);
+  }, [syncHash, go]);
+  const linkedRead = useRef2(false);
   useEffect2(() => {
     readHash();
+    linkedRead.current = totalRef.current > 0;
     const onHashChange = () => readHash();
     window.addEventListener("hashchange", onHashChange);
     return () => window.removeEventListener("hashchange", onHashChange);
   }, [readHash]);
+  useEffect2(() => {
+    if (linkedRead.current || total === 0) return;
+    linkedRead.current = true;
+    readHash();
+  }, [total, readHash]);
   useEffect2(() => {
     if (!syncHash || index < 0 || typeof window === "undefined") return;
+    const pending2 = pendingRead.current;
+    pendingRead.current = null;
+    if (pending2 !== null && pending2 !== index) return;
     const next2 = writeHashParam(window.location.hash, syncHash, String(index));
     if (window.location.hash !== next2) {
       lastWrittenHash.current = next2;
@@ -265,6 +350,11 @@ function useStepPlayer({
       speed,
       atEnd,
       ended,
+      held,
+      release,
+      jump,
+      live,
+      goLive,
       start,
       reset,
       seek,
@@ -274,7 +364,7 @@ function useStepPlayer({
       setPlaying,
       setSpeed: changeSpeed
     }),
-    [total, index, playing, speed, atEnd, ended, start, reset, seek, next, prev, toggle, changeSpeed]
+    [total, index, playing, speed, atEnd, ended, held, release, jump, live, goLive, start, reset, seek, next, prev, toggle, changeSpeed]
   );
 }
 function hashParts(hash) {
@@ -298,18 +388,139 @@ function writeHashParam(hash, key, value) {
 }
 
 // src/use-trace.ts
-import { useCallback as useCallback3, useMemo as useMemo3, useRef as useRef3 } from "react";
+import { useCallback as useCallback3, useEffect as useEffect3, useLayoutEffect, useMemo as useMemo3, useReducer, useRef as useRef3 } from "react";
+
+// src/reanchor.ts
+function reanchor(oldSteps, oldIndex, newSteps, keyOf) {
+  if (newSteps.length === 0) return -1;
+  if (oldIndex < 0 || oldSteps.length === 0) return 0;
+  const positions = /* @__PURE__ */ new Map();
+  newSteps.forEach((s, i) => {
+    const k = keyOf(s, i);
+    if (k !== void 0 && !positions.has(k)) positions.set(k, i);
+  });
+  for (let i = Math.min(oldIndex, oldSteps.length - 1); i >= 0; i--) {
+    const k = keyOf(oldSteps[i], i);
+    if (k === void 0) continue;
+    const j = positions.get(k);
+    if (j !== void 0) return j;
+  }
+  return 0;
+}
+var stepKey = (step) => step !== null && typeof step === "object" && typeof step.key === "string" ? step.key : void 0;
+
+// src/use-trace.ts
+var useIsomorphicLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect3;
 function useTrace(steps, opts) {
-  const player = useStepPlayer({ ...opts, total: steps.length });
+  const { keyOf, holdAt, ...playerOpts } = opts ?? {};
   const stepsRef = useRef3(steps);
+  const player = useStepPlayer({
+    ...playerOpts,
+    total: steps.length,
+    holdAt: holdAt ? (f) => holdAt(f, stepsRef.current[f]) : void 0
+  });
   stepsRef.current = steps;
-  const frame = steps.length === 0 ? -1 : Math.max(0, Math.min(player.index, steps.length - 1));
+  const keyFn = keyOf ?? stepKey;
+  const shownRef = useRef3({ steps, index: player.index });
+  const shown = shownRef.current;
+  let anchored = null;
+  if (shown.steps !== steps && shown.index >= 0) {
+    const i = shown.index;
+    const k = i < shown.steps.length ? keyFn(shown.steps[i], i) : void 0;
+    if (k !== void 0 && i < steps.length && keyFn(steps[i], i) === k) anchored = i;
+    else if (steps.some((s, j) => keyFn(s, j) !== void 0)) anchored = reanchor(shown.steps, i, steps, keyFn);
+  }
+  const index = anchored ?? player.index;
+  const { jump } = player;
+  const [, rerender] = useReducer((n) => n + 1, 0);
+  useIsomorphicLayoutEffect(() => {
+    shownRef.current = { steps, index };
+    if (anchored === null) return;
+    if (anchored >= 0 && anchored !== player.index) jump(anchored);
+    rerender();
+  });
+  const frame = steps.length === 0 ? -1 : Math.max(0, Math.min(index, steps.length - 1));
   const step = frame >= 0 ? steps[frame] : void 0;
   const toneAt = useCallback3((i) => stepsRef.current[i]?.tone ?? "neutral", []);
   const titleAt = useCallback3((i) => stepsRef.current[i]?.label ?? `step ${i + 1}`, []);
   return useMemo3(() => ({ player, step, frame, toneAt, titleAt }), [player, step, frame, toneAt, titleAt]);
 }
 
+// src/use-simulation.ts
+import { useMemo as useMemo4 } from "react";
+
+// src/simulation.ts
+function hashSeed(seed) {
+  let h = 2166136261;
+  for (let i = 0; i < seed.length; i++) {
+    h ^= seed.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+function createRng(seed = 0) {
+  const base = typeof seed === "string" ? hashSeed(seed) : seed >>> 0;
+  let state = base;
+  const next = () => {
+    state = state + 1831565813 >>> 0;
+    let t = state;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+  const int = (min, max) => min + Math.floor(next() * (max - min + 1));
+  return {
+    seed: base,
+    next,
+    int,
+    pick(items) {
+      if (items.length === 0) throw new RangeError("rng.pick: empty array");
+      return items[int(0, items.length - 1)];
+    },
+    shuffle(items) {
+      const out = items.slice();
+      for (let i = out.length - 1; i > 0; i--) {
+        const j = int(0, i);
+        [out[i], out[j]] = [out[j], out[i]];
+      }
+      return out;
+    }
+  };
+}
+function runSimulation(simulation, input, opts) {
+  const maxSteps = opts?.maxSteps ?? 1e4;
+  const rng = createRng(opts?.seed ?? 0);
+  const steps = [];
+  let truncated = false;
+  let error = null;
+  try {
+    for (const step of simulation(input, { rng })) {
+      if (steps.length >= maxSteps) {
+        truncated = true;
+        break;
+      }
+      steps.push(step);
+    }
+  } catch (e) {
+    error = e;
+  }
+  return { steps, truncated, error, seed: rng.seed };
+}
+
+// src/use-simulation.ts
+function useSimulation(simulation, input, opts) {
+  const { seed, maxSteps, ...traceOpts } = opts ?? {};
+  const result = useMemo4(
+    () => runSimulation(simulation, input, { seed, maxSteps }),
+    [simulation, input, seed, maxSteps]
+  );
+  const trace = useTrace(result.steps, traceOpts);
+  return useMemo4(
+    () => ({ ...trace, steps: result.steps, truncated: result.truncated, error: result.error, seed: result.seed }),
+    [trace, result]
+  );
+}
+
 // src/create-trace.ts
 function createTrace() {
   const frames = [];
@@ -332,7 +543,7 @@ function createTrace() {
 }
 
 // src/use-synced-tracks.ts
-import { useCallback as useCallback4, useMemo as useMemo4, useRef as useRef4 } from "react";
+import { useCallback as useCallback4, useMemo as useMemo5, useRef as useRef4 } from "react";
 function alignTracks(tracks, key) {
   const names = Object.keys(tracks);
   const lens = names.map((n) => tracks[n].length);
@@ -420,7 +631,7 @@ function useSyncedTracks(tracks, opts) {
   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 view = useMemo5(() => {
     const out = {};
     aligned.names.forEach((n, t) => {
       const list = aligned.arrays[t];
@@ -455,20 +666,20 @@ function useSyncedTracks(tracks, opts) {
     },
     [moved]
   );
-  return useMemo4(
+  return useMemo5(
     () => ({ player, frame, total: rows.length, tracks: view, rows, toneAt, titleAt }),
     [player, frame, rows, view, toneAt, titleAt]
   );
 }
 
 // src/use-lesson-stream.ts
-import { useCallback as useCallback5, useEffect as useEffect4, useLayoutEffect, useMemo as useMemo5, useRef as useRef5, useState as useState4 } from "react";
+import { useCallback as useCallback5, useEffect as useEffect5, useLayoutEffect as useLayoutEffect2, useMemo as useMemo6, useRef as useRef5, useState as useState4 } from "react";
 
 // src/use-prefers-reduced-motion.ts
-import { useEffect as useEffect3, useState as useState3 } from "react";
+import { useEffect as useEffect4, useState as useState3 } from "react";
 function usePrefersReducedMotion() {
   const [reduced, setReduced] = useState3(false);
-  useEffect3(() => {
+  useEffect4(() => {
     const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
     setReduced(mq.matches);
     const onChange = (e) => setReduced(e.matches);
@@ -479,7 +690,7 @@ function usePrefersReducedMotion() {
 }
 
 // src/use-lesson-stream.ts
-var useIsoLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect4;
+var useIsoLayoutEffect = typeof window !== "undefined" ? useLayoutEffect2 : useEffect5;
 function useLessonStream(count, opts = {}) {
   const { radius = 1, approachBelow = 600, approachAbove = 300, scrollToSeed = true } = opts;
   const last = count - 1;
@@ -529,7 +740,7 @@ function useLessonStream(count, opts = {}) {
     setRange(grown);
   }, []);
   const scheduleRef = useRef5(null);
-  useEffect4(() => {
+  useEffect5(() => {
     if (count === 0) return;
     let raf = 0;
     const update = () => {
@@ -572,7 +783,7 @@ function useLessonStream(count, opts = {}) {
       if (raf) cancelAnimationFrame(raf);
     };
   }, [count, expandTo]);
-  useEffect4(() => {
+  useEffect5(() => {
     scheduleRef.current?.();
   }, [first, lastMounted]);
   const firstRef = useRef5(first);
@@ -592,7 +803,7 @@ function useLessonStream(count, opts = {}) {
     blocks.current.get(seed)?.scrollIntoView({ block: "start", behavior: "auto" });
   }, []);
   const [nav, setNav] = useState4(null);
-  useEffect4(() => {
+  useEffect5(() => {
     if (!nav) return;
     const raf = requestAnimationFrame(
       () => blocks.current.get(nav.target)?.scrollIntoView({ behavior: reducedRef.current ? "auto" : "smooth", block: "start" })
@@ -611,12 +822,12 @@ function useLessonStream(count, opts = {}) {
   );
   const next = useCallback5(() => goTo(activeRef.current + 1), [goTo]);
   const prev = useCallback5(() => goTo(activeRef.current - 1), [goTo]);
-  const mounted = useMemo5(() => {
+  const mounted = useMemo6(() => {
     const out = [];
     for (let i = first; i <= lastMounted; i++) out.push(i);
     return out;
   }, [first, lastMounted]);
-  return useMemo5(
+  return useMemo6(
     () => ({
       active: core.index,
       seed,
@@ -634,7 +845,7 @@ function useLessonStream(count, opts = {}) {
 function useFadeIn(initiallyVisible = false) {
   const reduced = usePrefersReducedMotion();
   const [shown, setShown] = useState4(initiallyVisible);
-  useEffect4(() => {
+  useEffect5(() => {
     if (shown) return;
     if (reduced) {
       setShown(true);
@@ -646,26 +857,105 @@ function useFadeIn(initiallyVisible = false) {
   return shown;
 }
 
+// src/use-evaluator.ts
+import { useCallback as useCallback6, useEffect as useEffect6, useMemo as useMemo7, useRef as useRef6, useState as useState5 } from "react";
+
+// src/evaluate.ts
+function toVerdict(result) {
+  return typeof result === "boolean" ? { status: result ? "pass" : "fail" } : result;
+}
+var pass = (feedback) => ({ status: "pass", feedback });
+var fail = (feedback) => ({ status: "fail", feedback });
+var pending = (feedback) => ({ status: "pending", feedback });
+
+// src/use-evaluator.ts
+var IDLE = { status: "idle", feedback: void 0, error: null };
+function useEvaluator(evaluator, ctx, opts) {
+  const mode = opts?.mode ?? "auto";
+  const [state, setState] = useState5(IDLE);
+  const [attempts, setAttempts] = useState5(0);
+  const evaluatorRef = useRef6(evaluator);
+  evaluatorRef.current = evaluator;
+  const ctxRef = useRef6(ctx);
+  ctxRef.current = ctx;
+  const runRef = useRef6(null);
+  useEffect6(() => () => runRef.current?.abort(), []);
+  const run = useCallback6(async () => {
+    runRef.current?.abort();
+    const controller = new AbortController();
+    runRef.current = controller;
+    let result;
+    try {
+      result = evaluatorRef.current(ctxRef.current, controller.signal);
+    } catch (error) {
+      setState({ status: "fail", feedback: void 0, error });
+      return { status: "fail" };
+    }
+    if (!(result instanceof Promise)) {
+      const verdict = toVerdict(result);
+      setState({ status: verdict.status, feedback: verdict.feedback, error: null });
+      return verdict;
+    }
+    setState((s) => ({ status: "pending", feedback: s.feedback, error: null }));
+    try {
+      const verdict = toVerdict(await result);
+      if (controller.signal.aborted) return null;
+      setState({ status: verdict.status, feedback: verdict.feedback, error: null });
+      return verdict;
+    } catch (error) {
+      if (controller.signal.aborted) return null;
+      setState({ status: "fail", feedback: void 0, error });
+      return { status: "fail" };
+    }
+  }, []);
+  const check = useCallback6(() => {
+    setAttempts((n) => n + 1);
+    return run();
+  }, [run]);
+  const reset = useCallback6(() => {
+    runRef.current?.abort();
+    runRef.current = null;
+    setState(IDLE);
+    setAttempts(0);
+  }, []);
+  useEffect6(() => {
+    if (mode === "auto") {
+      void run();
+    } else {
+      runRef.current?.abort();
+      setState(IDLE);
+    }
+  }, [ctx, mode, run]);
+  return useMemo7(
+    () => ({ ...state, passed: state.status === "pass", attempts, check, reset }),
+    [state, attempts, check, reset]
+  );
+}
+
 // src/use-guided-tour.ts
-import { useCallback as useCallback6, useEffect as useEffect5, useMemo as useMemo6, useRef as useRef6, useState as useState5 } from "react";
+import { useCallback as useCallback7, useEffect as useEffect7, useMemo as useMemo8, useRef as useRef7, useState as useState6 } from "react";
+function gateVerdict(step) {
+  const r = step?.gate?.();
+  return r === void 0 ? { status: "pass", feedback: void 0 } : toVerdict(r);
+}
 function useGuidedTour(steps, opts) {
-  const [running, setRunning] = useState5(false);
-  const runningRef = useRef6(running);
+  const [running, setRunning] = useState6(false);
+  const runningRef = useRef7(running);
   runningRef.current = running;
   const core = useSteps(steps.length);
-  const stepsRef = useRef6(steps);
+  const stepsRef = useRef7(steps);
   stepsRef.current = steps;
-  const driverRef = useRef6(opts?.driver);
+  const driverRef = useRef7(opts?.driver);
   driverRef.current = opts?.driver;
-  const coreGoRef = useRef6(core.go);
+  const coreGoRef = useRef7(core.go);
   coreGoRef.current = core.go;
-  const cursorRef = useRef6(core.index);
+  const cursorRef = useRef7(core.index);
   cursorRef.current = core.index;
-  const isSkipped = useCallback6(
+  const isSkipped = useCallback7(
     (i) => stepsRef.current[i]?.when?.() === false,
     []
   );
-  const settle = useCallback6(
+  const settle = useCallback7(
     (start2, dir) => {
       const len = stepsRef.current.length;
       let i = start2;
@@ -677,7 +967,7 @@ function useGuidedTour(steps, opts) {
     },
     [isSkipped]
   );
-  const arrive = useCallback6(
+  const arrive = useCallback7(
     (i, dir) => {
       const target = settle(i, dir);
       if (target === null) {
@@ -689,14 +979,14 @@ function useGuidedTour(steps, opts) {
     },
     [settle]
   );
-  const goTo = useCallback6(
+  const goTo = useCallback7(
     (i) => {
       if (stepsRef.current.length === 0) return;
       arrive(Math.max(0, Math.min(i, stepsRef.current.length - 1)), 1);
     },
     [arrive]
   );
-  const goToId = useCallback6(
+  const goToId = useCallback7(
     (id) => {
       const i = stepsRef.current.findIndex((s) => s.id === id);
       if (i >= 0) goTo(i);
@@ -704,11 +994,11 @@ function useGuidedTour(steps, opts) {
     [goTo]
   );
   const index = running ? core.index : null;
-  useEffect5(() => {
+  useEffect7(() => {
     if (!running) return;
     stepsRef.current[core.index]?.onEnter?.();
   }, [running, core.index]);
-  useEffect5(() => {
+  useEffect7(() => {
     const driver = driverRef.current;
     if (!driver) return;
     if (!running) {
@@ -728,13 +1018,13 @@ function useGuidedTour(steps, opts) {
       end: () => setRunning(false)
     });
   }, [running, core.index, goTo]);
-  useEffect5(() => () => driverRef.current?.hide(), []);
-  const start = useCallback6(() => {
+  useEffect7(() => () => driverRef.current?.hide(), []);
+  const start = useCallback7(() => {
     if (stepsRef.current.length === 0) return;
     arrive(0, 1);
   }, [arrive]);
-  const end = useCallback6(() => setRunning(false), []);
-  const resolveNext = useCallback6((i) => {
+  const end = useCallback7(() => setRunning(false), []);
+  const resolveNext = useCallback7((i) => {
     const list = stepsRef.current;
     const edge = list[i]?.next?.();
     if (edge != null) {
@@ -743,10 +1033,10 @@ function useGuidedTour(steps, opts) {
     }
     return i + 1;
   }, []);
-  const next = useCallback6(() => {
+  const next = useCallback7(() => {
     if (!runningRef.current) return;
     const i = cursorRef.current;
-    if (stepsRef.current[i]?.gate?.() === false) return;
+    if (gateVerdict(stepsRef.current[i]).status !== "pass") return;
     const target = resolveNext(i);
     if (target > stepsRef.current.length - 1) {
       setRunning(false);
@@ -754,22 +1044,24 @@ function useGuidedTour(steps, opts) {
     }
     arrive(target, 1);
   }, [arrive, resolveNext]);
-  const back = useCallback6(() => {
+  const back = useCallback7(() => {
     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]
+  const verdict = current ? gateVerdict(current) : null;
+  const blocked = verdict !== null && verdict.status !== "pass";
+  const feedback = verdict?.feedback;
+  return useMemo8(
+    () => ({ index, current, active: running, blocked, feedback, start, end, next, back, goto: goTo, gotoId: goToId }),
+    [index, current, running, blocked, feedback, start, end, next, back, goTo, goToId]
   );
 }
 
 // src/use-chapters.ts
-import { useCallback as useCallback7, useEffect as useEffect6, useMemo as useMemo7, useRef as useRef7, useState as useState6 } from "react";
+import { useCallback as useCallback8, useEffect as useEffect8, useMemo as useMemo9, useRef as useRef8, useState as useState7 } from "react";
 
 // src/flatten.ts
 function flattenChapters(chapters, depth = 0) {
@@ -788,17 +1080,17 @@ function flattenChapters(chapters, depth = 0) {
 
 // src/use-chapters.ts
 function useChapters(chapters) {
-  const [mounted, setMounted] = useState6(false);
-  const flat = useMemo7(() => flattenChapters(chapters), [chapters]);
-  const flatRef = useRef7(flat);
+  const [mounted, setMounted] = useState7(false);
+  const flat = useMemo9(() => flattenChapters(chapters), [chapters]);
+  const flatRef = useRef8(flat);
   flatRef.current = flat;
-  const [active, setActive] = useState6(0);
-  const activeRef = useRef7(0);
+  const [active, setActive] = useState7(0);
+  const activeRef = useRef8(0);
   activeRef.current = active;
   const core = useSteps(flat.length, { initialIndex: 0 });
-  const coreGoRef = useRef7(core.go);
+  const coreGoRef = useRef8(core.go);
   coreGoRef.current = core.go;
-  useEffect6(() => {
+  useEffect8(() => {
     if (!mounted) return;
     let raf = 0;
     const update = () => {
@@ -836,8 +1128,8 @@ function useChapters(chapters) {
       if (raf) cancelAnimationFrame(raf);
     };
   }, [mounted, flat.length]);
-  useEffect6(() => setMounted(true), []);
-  const goTo = useCallback7((i) => {
+  useEffect8(() => setMounted(true), []);
+  const goTo = useCallback8((i) => {
     const entry = flatRef.current[i];
     if (!entry) return;
     setActive(i);
@@ -846,25 +1138,25 @@ function useChapters(chapters) {
     if (!el) return;
     el.scrollIntoView({ behavior: "smooth", block: "start" });
   }, []);
-  const next = useCallback7(() => {
+  const next = useCallback8(() => {
     if (activeRef.current < flatRef.current.length - 1) goTo(activeRef.current + 1);
   }, [goTo]);
-  const prev = useCallback7(() => {
+  const prev = useCallback8(() => {
     if (activeRef.current > 0) goTo(activeRef.current - 1);
   }, [goTo]);
-  return useMemo7(() => ({ active: core.index, goTo, next, prev }), [core.index, goTo, next, prev]);
+  return useMemo9(() => ({ active: core.index, goTo, next, prev }), [core.index, goTo, next, prev]);
 }
 
 // src/use-global-keys.ts
-import { useEffect as useEffect7, useRef as useRef8 } from "react";
+import { useEffect as useEffect9, useRef as useRef9 } from "react";
 var DEFAULT_IGNORED_TAGS = ["INPUT", "TEXTAREA", "SELECT", "BUTTON"];
 function useGlobalKeys(map, opts) {
-  const mapRef = useRef8(map);
+  const mapRef = useRef9(map);
   mapRef.current = map;
-  const ignoreRef = useRef8(new Set(opts?.ignoreTags ?? DEFAULT_IGNORED_TAGS));
-  const enabledRef = useRef8(opts?.enabled ?? true);
+  const ignoreRef = useRef9(new Set(opts?.ignoreTags ?? DEFAULT_IGNORED_TAGS));
+  const enabledRef = useRef9(opts?.enabled ?? true);
   enabledRef.current = opts?.enabled ?? true;
-  useEffect7(() => {
+  useEffect9(() => {
     const onKey = (e) => {
       const gate = enabledRef.current;
       const enabled = typeof gate === "function" ? gate() : gate;
@@ -882,7 +1174,7 @@ function useGlobalKeys(map, opts) {
 }
 
 // src/use-discoveries.ts
-import { useCallback as useCallback8, useEffect as useEffect8, useMemo as useMemo8, useRef as useRef9, useState as useState7 } from "react";
+import { useCallback as useCallback9, useEffect as useEffect10, useMemo as useMemo10, useRef as useRef10, useState as useState8 } from "react";
 function localStorageStore(key = "stepwise.discoveries") {
   return {
     read() {
@@ -933,23 +1225,23 @@ function memoryStore(seed = []) {
   };
 }
 function useDiscoveries(opts) {
-  const defaultStoreRef = useRef9(null);
-  const storeRef = useRef9(null);
+  const defaultStoreRef = useRef10(null);
+  const storeRef = useRef10(null);
   if (opts?.store) {
     storeRef.current = opts.store;
   } else {
     if (!defaultStoreRef.current) defaultStoreRef.current = localStorageStore(opts?.key);
     storeRef.current = defaultStoreRef.current;
   }
-  const [ids, setIds] = useState7(() => /* @__PURE__ */ new Set());
-  const [ready, setReady] = useState7(false);
-  const idsRef = useRef9(ids);
+  const [ids, setIds] = useState8(() => /* @__PURE__ */ new Set());
+  const [ready, setReady] = useState8(false);
+  const idsRef = useRef10(ids);
   idsRef.current = ids;
-  useEffect8(() => {
+  useEffect10(() => {
     setIds(new Set(storeRef.current.read()));
     setReady(true);
   }, []);
-  const markDiscovered = useCallback8((id) => {
+  const markDiscovered = useCallback9((id) => {
     const additions = Array.isArray(id) ? id : [id];
     const merged = new Set(idsRef.current);
     let changed = false;
@@ -964,24 +1256,24 @@ function useDiscoveries(opts) {
     setIds(merged);
     storeRef.current.write([...merged]);
   }, []);
-  const reset = useCallback8(() => {
+  const reset = useCallback9(() => {
     const empty = /* @__PURE__ */ new Set();
     idsRef.current = empty;
     setIds(empty);
     storeRef.current.write([]);
   }, []);
-  const isDiscovered = useCallback8((id) => idsRef.current.has(id), []);
-  return useMemo8(
+  const isDiscovered = useCallback9((id) => idsRef.current.has(id), []);
+  return useMemo10(
     () => ({ discovered: ids, ready, isDiscovered, markDiscovered, reset }),
     [ids, ready, isDiscovered, markDiscovered, reset]
   );
 }
 
 // src/use-focus-trap.ts
-import { useEffect as useEffect9, useRef as useRef10 } from "react";
+import { useEffect as useEffect11, useRef as useRef11 } from "react";
 function useFocusTrap(active) {
-  const ref = useRef10(null);
-  useEffect9(() => {
+  const ref = useRef11(null);
+  useEffect11(() => {
     if (!active) return;
     const container = ref.current;
     if (!container) return;
@@ -1018,14 +1310,14 @@ function useFocusTrap(active) {
 // src/glossary.tsx
 import {
   createContext,
-  useCallback as useCallback9,
+  useCallback as useCallback10,
   useContext,
-  useEffect as useEffect10,
+  useEffect as useEffect12,
   useId,
-  useLayoutEffect as useLayoutEffect2,
-  useMemo as useMemo9,
-  useRef as useRef11,
-  useState as useState8
+  useLayoutEffect as useLayoutEffect3,
+  useMemo as useMemo11,
+  useRef as useRef12,
+  useState as useState9
 } from "react";
 import { createPortal } from "react-dom";
 
@@ -1083,7 +1375,7 @@ function GlossaryProvider({
   theme = defaultTheme,
   children
 }) {
-  const value = useMemo9(
+  const value = useMemo11(
     () => ({ byId: new Map(entries.map((e) => [e.id, e])), entries, theme }),
     [entries, theme]
   );
@@ -1093,23 +1385,23 @@ function Term({ id, children, className }) {
   const ctx = useContext(GlossaryContext);
   const depth = useContext(DepthContext);
   const entry = ctx?.byId.get(id);
-  const [open, setOpen] = 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 [open, setOpen] = useState9(false);
+  const [pos, setPos] = useState9(null);
+  const openRef = useRef12(false);
+  const wrapperRef = useRef12(null);
+  const triggerRef = useRef12(null);
+  const cardRef = useRef12(null);
+  const openTimer = useRef12(0);
+  const closeTimer = useRef12(0);
   const tipId = useId();
   const display = children ?? entry?.term ?? id;
-  const closeNow = useCallback9(() => {
+  const closeNow = useCallback10(() => {
     window.clearTimeout(openTimer.current);
     window.clearTimeout(closeTimer.current);
     openRef.current = false;
     setOpen(false);
   }, []);
-  const openNow = useCallback9((focusCard = false) => {
+  const openNow = useCallback10((focusCard = false) => {
     window.clearTimeout(closeTimer.current);
     window.clearTimeout(openTimer.current);
     openRef.current = true;
@@ -1118,18 +1410,18 @@ function Term({ id, children, className }) {
       requestAnimationFrame(() => cardRef.current?.focus({ preventScroll: true }));
     }
   }, []);
-  const scheduleOpen = useCallback9(() => {
+  const scheduleOpen = useCallback10(() => {
     window.clearTimeout(closeTimer.current);
     if (openRef.current) return;
     window.clearTimeout(openTimer.current);
     openTimer.current = window.setTimeout(() => openNow(), OPEN_DELAY_MS);
   }, [openNow]);
-  const scheduleClose = useCallback9(() => {
+  const scheduleClose = useCallback10(() => {
     window.clearTimeout(openTimer.current);
     window.clearTimeout(closeTimer.current);
     closeTimer.current = window.setTimeout(closeNow, CLOSE_GRACE_MS);
   }, [closeNow]);
-  useLayoutEffect2(() => {
+  useLayoutEffect3(() => {
     if (!open) {
       setPos(null);
       return;
@@ -1166,7 +1458,7 @@ function Term({ id, children, className }) {
       if (raf) cancelAnimationFrame(raf);
     };
   }, [open]);
-  useEffect10(() => {
+  useEffect12(() => {
     if (!open) return;
     const onPointerDown = (e) => {
       const target = e.target;
@@ -1177,7 +1469,7 @@ function Term({ id, children, className }) {
     document.addEventListener("pointerdown", onPointerDown);
     return () => document.removeEventListener("pointerdown", onPointerDown);
   }, [open, closeNow]);
-  useEffect10(() => () => {
+  useEffect12(() => () => {
     window.clearTimeout(openTimer.current);
     window.clearTimeout(closeTimer.current);
   }, []);
@@ -1330,7 +1622,7 @@ function GlossaryAppendix({
 }
 
 // src/components.tsx
-import { useEffect as useEffect11, useState as useState9 } from "react";
+import { useEffect as useEffect13, useState as useState10 } from "react";
 import { createPortal as createPortal2 } from "react-dom";
 import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
 var TONE_SEGMENT_CLASS = defaultTheme.toneSegment;
@@ -1469,15 +1761,19 @@ function PlayerBar({
   className,
   theme = defaultTheme,
   groupOf,
-  labels
+  labels,
+  live
 }) {
   const L = {
     previous: labels?.previous ?? "Previous step",
     play: labels?.play ?? "Play",
     pause: labels?.pause ?? "Pause",
     replay: labels?.replay ?? "Replay",
-    next: labels?.next ?? "Next step"
+    next: labels?.next ?? "Next step",
+    live: labels?.live ?? "Live",
+    goLive: labels?.goLive ?? "Go live"
   };
+  const behind = Math.max(0, player.total - 1 - Math.max(player.index, 0));
   const playLabel = player.playing ? L.pause : player.total > 0 && player.atEnd ? L.replay : L.play;
   return /* @__PURE__ */ jsxs2("div", { "data-stepwise": "", className: cn("flex items-center gap-2 p-2", className), children: [
     leading,
@@ -1497,7 +1793,15 @@ function PlayerBar({
         groupOf
       }
     ),
-    /* @__PURE__ */ jsx2("span", { className: cn("text-[10px] font-mono w-11 text-right shrink-0", theme.muted), children: player.total > 0 ? `${player.index + 1}/${player.total}` : "\u2014" })
+    /* @__PURE__ */ jsx2("span", { className: cn("text-[10px] font-mono w-11 text-right shrink-0", theme.muted), children: player.total > 0 ? `${player.index + 1}/${player.total}` : "\u2014" }),
+    live && (player.live || behind === 0 ? /* @__PURE__ */ jsxs2("span", { role: "status", className: "flex items-center gap-1 text-[10px] font-mono uppercase text-primary shrink-0", children: [
+      /* @__PURE__ */ jsx2("span", { "aria-hidden": "true", className: cn("h-1.5 w-1.5 rounded-full bg-primary", player.playing && "motion-safe:animate-pulse") }),
+      L.live
+    ] }) : /* @__PURE__ */ jsxs2(StepButton, { variant: "ghost", onClick: () => player.goLive?.(), className: "h-7 px-2 text-[10px] font-mono shrink-0", children: [
+      L.goLive,
+      " +",
+      behind
+    ] }))
   ] });
 }
 function ChapterNav({
@@ -1602,8 +1906,8 @@ function TourSpotlight({
   target,
   theme = defaultTheme
 }) {
-  const [rect, setRect] = useState9(null);
-  useEffect11(() => {
+  const [rect, setRect] = useState10(null);
+  useEffect13(() => {
     if (!target) {
       setRect(null);
       return;
@@ -1659,7 +1963,8 @@ function TourCard({
   labels,
   className,
   theme = defaultTheme,
-  nextDisabled = false
+  nextDisabled = false,
+  feedback
 }) {
   const L = {
     title: labels?.title ?? "Guided tour",
@@ -1707,6 +2012,7 @@ function TourCard({
         /* @__PURE__ */ jsx2("p", { className: "text-sm font-bold text-foreground/95 mb-1.5", children: step.title }),
         /* @__PURE__ */ jsx2("div", { className: "text-[12px] font-mono text-foreground/70 leading-relaxed", children: step.body }),
         step.waitHint && /* @__PURE__ */ jsx2("p", { className: "text-[11px] font-mono text-accent mt-2 animate-pulse", children: step.waitHint }),
+        /* @__PURE__ */ jsx2("div", { "aria-live": "polite", children: feedback != null && feedback !== false && /* @__PURE__ */ jsx2("p", { className: "text-[11px] font-mono text-foreground/70 mt-2", children: feedback }) }),
         /* @__PURE__ */ jsxs2("div", { className: "flex items-center gap-2 mt-3 pt-3 border-t border-white/10", children: [
           /* @__PURE__ */ jsx2(StepButton, { variant: "outline", onClick: onBack, disabled: index === 0, className: "h-7 px-3 text-[11px]", children: L.back }),
           /* @__PURE__ */ jsx2(
@@ -1732,10 +2038,10 @@ function ShortcutsDialog({
   className,
   theme = defaultTheme
 }) {
-  const [mounted, setMounted] = useState9(false);
+  const [mounted, setMounted] = useState10(false);
   const trapRef = useFocusTrap(open);
-  useEffect11(() => setMounted(true), []);
-  useEffect11(() => {
+  useEffect13(() => setMounted(true), []);
+  useEffect13(() => {
     if (!open) return;
     const onKey = (e) => {
       if (e.key === "Escape") onClose();
@@ -1807,22 +2113,33 @@ export {
   TourSpotlight,
   alignTracks,
   cookieStore,
+  createRng,
   createTrace,
   defaultTheme,
+  fail,
   flattenChapters,
   localStorageStore,
   memoryStore,
+  pass,
+  pending,
+  readHashParam,
+  reanchor,
+  runSimulation,
+  toVerdict,
   useChapters,
   useDiscoveries,
+  useEvaluator,
   useFadeIn,
   useFocusTrap,
   useGlobalKeys,
   useGuidedTour,
   useLessonStream,
   usePrefersReducedMotion,
+  useSimulation,
   useStepPlayer,
   useSteps,
   useSyncedTracks,
-  useTrace
+  useTrace,
+  writeHashParam
 };
 //# sourceMappingURL=index.js.map