@sphynxoid/stepwise

A clamped cursor over an ordered sequence. Re-clamps when the count shrinks; all callbacks are referentially stable.

Player policy: timer, speed, seek, optional #hash deep link and an engine port for GSAP or scroll. index === -1 means not started.

A player bound to a typed trace. Resolves the frame to render (frame 0 before start) and returns stable scrubber accessors. steps may change: keyed steps re-anchor, so the playhead stays on the same logical step and playback continues.

Comparison mode: several traces of the same input under one player. Shorter tracks hold their last frame, or steps align on shared sync keys. alignTracks is the pure alignment, usable on the server.

Typed trace builder: run your algorithm at module scope and record frames as you go. Pure data - no React, safe on the server.

A live trace: runs a generator on the input and plays the result. Change the input or seed and the trace is recomputed while keyed steps keep the playhead in place. Define the simulation at module scope, and keep object inputs in state or useMemo: an inline { arr, target } is a new object every render, so the trace would be recomputed every render (development builds warn about it).

The pure pieces: run a simulation to completion (safe at module scope and on the server), and a seeded mulberry32 generator - the only randomness a simulation should use, so runs replay exactly.

The re-anchoring rule useTrace applies: walk back from the old position to the latest step whose key both traces share, and land on it. No shared key returns 0; an empty trace returns -1. Pure - use it in custom players.

Tour policy: onEnter effects over your state, conditional steps (when), guards (gate), branching edges (next) and an optional imperative driver.

Scroll-tracked chapters. Active = the section containing the viewport center. Sections are resolved by DOM id; give them scroll-mt to clear sticky headers.

Headless notebook reader: mounts a window of lessons around the seed, loads neighbours on approach, compensates the scroll for content prepended above, and tracks the active lesson by viewport center. Composes with ChapterNav and LessonPager. useFadeIn(initiallyVisible) fades streamed blocks in.

A persisted set of discovered ids, hydrated after mount. Pair with useGuidedTour for show-once feature tutorials.

Global keyboard bindings matched on event.key (exact, then lowercase). Handlers fire with preventDefault; Escape always fires.

Traps Tab inside the ref'd container while active, focuses it on activation and restores focus on release. Attach to a tabIndex={-1} element.

SSR-safe prefers-reduced-motion query (false on the server, corrected after mount).

Keeps an evaluator's verdict as state. Auto re-judges on every context change (gates). Manual judges only on check() (quizzes); when ctx changes identity afterwards the verdict goes back to idle, but attempts are kept (same question), so call reset() when the question itself changes, e.g. in an effect on player.held. Async checks report pending, abort superseded runs and drop late results.

A Verdict is { status: "pass" | "fail" | "pending", feedback? }. pass(), fail() and pending() build one; toVerdict() normalizes a boolean. All are exported from the package root. The signal aborts when the result is no longer wanted. Grading a checkpoint: the truth is usually the next frame (sim.steps[player.held + 1]), so phrase the question so every possible next frame is an answer option.

Transport controls plus a tone-colored scrubber for a StepPlayer.

Keyboard-accessible slider of tone-colored segments, usable with any cursor.

Recursive chapter navigation; sticky by default. Sub-chapters render inline after their parent.

Previous/next buttons for cross-page lesson navigation.

Dims the page around the target, scrolls it into view once and tracks it every frame. Waits for targets that render late.

Focus-trapped dialog narrating the active tour step, fixed to the bottom of the viewport.

Modal list of keyboard shortcuts with kbd chips; closes on Escape or backdrop click.

Monospace lines with // comments dimmed. This site's View source panels use it.

Declares the entries once. Definitions are ReactNode and may contain further Terms. Every Term and GlossaryAppendix must be inside it (in MDX: wrap the rendered article, or put it in the layout). The entry type is type-only: import type { GlossaryEntry } from "@sphynxoid/stepwise".

A focusable inline reference. Hover or Enter opens a tooltip; nested terms stack outward, depth-capped at 4. Inside the appendix it becomes an anchor link.

Renders the provider's entries in declaration order. Every part is overridable.

Depth-first flattening - reading order for prev/next and scroll tracking.

The fragment format syncHash and syncInput use: &-separated parts, key=value parts are params, anything else (a bare #anchor) is kept verbatim. writeHashParam replaces the key in place or appends it, and returns the new hash; apply it with history.replaceState. For a simulation's input, prefer useSimulation's syncInput.

The default theme's per-tone classes as plain records, for your own chips and badges that should match the scrubber. Styled by styles.css or your Tailwind build like the components.

Built-in DiscoveryStore implementations: { read(): string[]; write(ids: string[]): void }.

Every non-CSS-variable class the components use. TONE_SEGMENT_CLASS and TONE_CHIP_CLASS re-export the defaults. Without Tailwind, import "@sphynxoid/stepwise/styles.css" (precompiled, scoped to [data-stepwise], --stepwise-* tokens); or copy the components in via the shadcn registry at /r/*.json.

One frame of a trace, carrying your domain payload. StepTone is exactly "neutral" | "accent" | "good" | "bad" | "write" | "idle". key names the moment ("compare at i=3, j=2") so the playhead keeps its place when the trace is recomputed; give every step of a simulation one.

Ports for alternate frame sources and tour presenters. Adapters ship on subpaths: @sphynxoid/stepwise/adapters/gsap, /driver-js and /scroll.

useSimulation plus choices. A walk is replayed from (input, seed, choices) on every change, so it stays pure. The unanswered choice point at the end of the path holds playback until choose().

A walk simulation is a generator; a step with await: true is a choice point, and that yield returns the reader's choice: const pick = yield { key: "fork", await: true, … }. runWalk replays it purely, stopping at the first unanswered choice point. Linear simulations are walks without choice points.

A declared automaton: nodes, labeled edges, accept states. Throws on an inconsistent graph. A missing edge goes to otherwise (a dead state) or ends the run with an error.

What an edit changed between two runs, to mark the changed steps instead of only saying that something did. useWalk exposes it as lastChange.