stepwise — Narrated Step Visualizations for React

Every narrated interactive needs the same machinery: a play/pause cursor over a sequence of frames, a spotlight tour that follows page state, scroll-driven chapters, and terms that explain themselves on hover. Building each by hand means reimplementing timing, keyboard control, focus trapping, reduced-motion handling, and deep links — and every copy drifts.

The tooling behind this site's visualizers had exactly that problem: the Swiss-table probe and the NUMA notebook each carried bespoke player, tour, and scroll logic that could not be reused or tested in isolation.

Reduced the whole space to one primitive: useSteps, a clamped cursor over an ordered sequence with stable callbacks and automatic re-clamping. Frames in a trace, chapters in a lesson, lessons in a notebook, and tour steps are that cursor at different scales.

Layered policies on top — useStepPlayer (timing, speed, deep-link hashing, an engine port so GSAP timelines or scroll progress can drive frames), useGuidedTour (per-step effects over app state, wait gates, and a driver port for third-party presenters like driver.js), useChapters (viewport-center scroll tracking with sub-chapter grouping), and a depth-capped recursive glossary whose appendix collects its own entries.

Shipped it as a package: headless hooks plus injectable themed components (className tokens over CSS variables, so hosts keep their design system), optional peer adapters, an ESM build with clean TypeScript declarations, and a test suite that gates every publish.

Published on npm as @sphynxoid/stepwise — 84 tests run on every publish through a prepublish gate, typed public API, live demo site documenting six usage modes from a bare player to a scroll-told pipeline with sub-chapters.

Powers this site end to end: the Swiss-table probe visualizer, the NUMA playbook's five-lesson stream, and their tours, glossaries, and keyboard controls all run on the same published package that anyone can install.

Wrote the integration guide that documents the sharpest real-world edge — Tailwind v4's content detection silently skipping node_modules — so consumers get one line of CSS instead of a debugging session.