@sphynxoid/stepwise 0.1.0 → 0.2.0

package/README.md

@@ -1,127 +1,150 @@
-# @sphynxoid/stepwise
-
-A kit for interactive, narrated, step-driven visualizations — one primitive (`useSteps`) at every scale.
-
-Frames in a trace, chapters in a lesson, lessons in a notebook, and tour steps are the same thing at the core: a clamped cursor over an ordered sequence. Timers, tour effects, scroll tracking, and third-party presenters are policies and adapters layered on top.
-
-- **Headless core.** The hooks never render; the styled components are optional and theme-injectable.
-- **One dependency by default.** The root barrel needs only React. GSAP and driver.js integrations are opt-in via adapter subpaths.
-
-## Install
-
-```bash
-npm install @sphynxoid/stepwise
-```
-
-Optional adapters (install only what you use):
-
-```bash
-npm install gsap        # @sphynxoid/stepwise/adapters/gsap
-npm install driver.js   # @sphynxoid/stepwise/adapters/driver-js
-# @sphynxoid/stepwise/adapters/scroll is dependency-free
-```
-
-## Required: Tailwind CSS setup
-
-The styled components ship **className strings**. Tailwind v4's automatic
-content detection skips `node_modules`, so **no library class gets generated**
-unless you register the source. Without this, every library element renders
-completely unstyled.
-
-```css
-@import "tailwindcss";
-@source "../node_modules/@sphynxoid/stepwise/src";
-```
-
-Components are also fully usable without Tailwind if you bring your own
-presentation — the hooks are headless.
-
-## Quick start — a narrated player
-
-```tsx
-"use client";
-import { useStepPlayer, PlayerBar, CodeBlock, type StepTone } from "@sphynxoid/stepwise";
-
-const frames: { tone: StepTone; label: string; code: string[] }[] = [
-  { tone: "write", label: "Initialize", code: ["let i = 0;"] },
-  { tone: "neutral", label: "Loop", code: ["while (i < n) { … }"] },
-  { tone: "good", label: "Done", code: ["return arr;"] },
-];
-
-export function Demo() {
-  const player = useStepPlayer({ total: frames.length, autoPlay: true, syncHash: "frame" });
-  const frame = frames[Math.max(0, player.index)] ?? frames[0];
-
-  return (
-    <>
-      <CodeBlock lines={frame.code} />
-      <PlayerBar player={player} toneAt={(i) => frames[i]?.tone ?? "neutral"} titleAt={(i) => frames[i]?.label ?? ""} />
-    </>
-  );
-}
-```
-
-`useStepPlayer` gives you a timer-driven playhead with play/pause/seek, speed control, and optional `#frame=2` deep links — or hand it an `engine` to drive the playhead from GSAP or scroll instead. Two end-state flavors: `atEnd` (cursor parked on the last frame, seeks included) and `ended` (playback ran to the finish, via the `onEnd` callback option) — clearing on any cursor movement, so a completion summary knows the demo actually finished.
-
-## The three scales
-
-| Scale | Hook | Presentation |
-|---|---|---|
-| **Player** — auto-played frames in a trace | `useStepPlayer` (+ `PlayerEngine` adapters) | `PlayerBar`, `StepScrubber`, `CodeBlock` |
-| **Tour** — steps that mutate app state via `onEnter` | `useGuidedTour` (+ `TourDriver` adapters) | `TourSpotlight`, `TourCard` |
-| **Chapters** — scroll-tracked sections | `useChapters`, `flattenChapters` | `ChapterNav`, `LessonPager` |
-
-All three compose the same `useSteps` cursor, so movement, clamping, and boundary flags behave identically everywhere.
-
-Tours are small state machines: a step may declare `when` (skip on arrival when false), `gate` (block `next()` — and expose `blocked` — until the user actually does the thing), and `next` (edge override to another step's `id`, enabling branches and loops). `gotoId(id)` navigates by identity; programmatic navigation never trips gates.
-
-## Show-once tutorials (led discovery)
-
-Pair `useDiscoveries` with `useGuidedTour` to auto-play a tour the first time a user encounters a feature:
-
-```tsx
-const { discovered, ready, markDiscovered } = useDiscoveries();
-const tour = useGuidedTour(steps);
-
-// when this build carries an undiscovered feature, play its tour once
-useEffect(() => {
-  if (ready && !tour.active && !discovered.has("search:v1")) tour.start();
-}, [ready, tour.active, discovered]);
-
-// mark on completion (or explicit dismiss) — never on mere trigger
-useEffect(() => {
-  if (launched && !tour.active) markDiscovered("search:v1");
-}, [tour.active]);
-```
-
-The ledger is a set of opaque ids behind a `DiscoveryStore` seam: `localStorageStore` (default), `cookieStore` (when SSR markup must know), `memoryStore` (tests), or your own store backed by an API for cross-device discovery.
-
-## Supporting pieces
-
-- `useGlobalKeys` — global keyboard bindings with a form-control guard
-- `useFocusTrap` — dialog/tour focus containment
-- `usePrefersReducedMotion` — motion preference gate
-- `useDiscoveries` (+ `localStorageStore` / `cookieStore` / `memoryStore`) — persisted discovery ledger with a swappable storage seam
-- `GlossaryProvider` / `Term` / `GlossaryAppendix` — recursive, depth-capped term tooltips with an auto-collecting appendix
-- `ShortcutsDialog` — keyboard shortcut reference
-- `defaultTheme` / `StepwiseTheme` — the default styling, overridable per component via a `theme` prop (swap in any design system)
-
-## Adapters
-
-Import adapters from their subpaths — never from the root barrel:
-
-```ts
-import { createGsapPlayerEngine } from "@sphynxoid/stepwise/adapters/gsap";
-import { createDriverJsTourDriver } from "@sphynxoid/stepwise/adapters/driver-js";
-import { createScrollPlayerEngine } from "@sphynxoid/stepwise/adapters/scroll";
-```
-
-An adapter plugs into a tiny port (`PlayerEngine` / `TourDriver`), so you can write your own for Shepherd, Framer Motion, or anything else without touching the kit.
-
-## React
-
-Supports React 18 and 19. All hooks are SSR-safe (`"use client"` modules, no window access at module evaluation) and every public hook returns referentially stable callbacks.
-
-## License
-
-MIT
+# @sphynxoid/stepwise
+
+A kit for interactive, narrated, step-driven visualizations — one primitive (`useSteps`) at every scale.
+
+Frames in a trace, chapters in a lesson, lessons in a notebook, and tour steps are the same thing at the core: a clamped cursor over an ordered sequence. Timers, tour effects, scroll tracking, and third-party presenters are policies and adapters layered on top.
+
+- **Headless core.** The hooks never render; the styled components are optional and theme-injectable.
+- **One dependency by default.** The root barrel needs only React. GSAP and driver.js integrations are opt-in via adapter subpaths.
+
+## Install
+
+```bash
+npm install @sphynxoid/stepwise
+```
+
+Optional adapters (install only what you use):
+
+```bash
+npm install gsap        # @sphynxoid/stepwise/adapters/gsap
+npm install driver.js   # @sphynxoid/stepwise/adapters/driver-js
+# @sphynxoid/stepwise/adapters/scroll is dependency-free
+```
+
+## Styling — pick one
+
+The hooks are headless. The styled components (`PlayerBar`, `TourCard`, `Term`, …) ship Tailwind class strings, and there are three ways to get them styled:
+
+**1. No Tailwind — import the precompiled stylesheet** (once, at your app entry):
+
+```ts
+import "@sphynxoid/stepwise/styles.css";
+```
+
+It contains exactly the CSS the components use, no global reset (a small preflight is scoped to the components' `[data-stepwise]` roots), and light/dark defaults that follow `prefers-color-scheme` or a `.dark` / `[data-theme="dark"]` switch. Re-color it with CSS variables:
+
+```css
+:root {
+  --stepwise-primary: #7c3aed;      /* play button, active segment, rings */
+  --stepwise-accent: #0ea5e9;       /* "accent" tone, links, wait hints */
+}
+```
+
+Tokens: `--stepwise-background`, `-foreground`, `-card`, `-popover`, `-primary`, `-primary-foreground`, `-accent`, `-destructive`, `-ring`, `-shade` (overlay/code-block tint).
+
+**2. Tailwind + shadcn/ui — copy the components in with the shadcn CLI:**
+
+```bash
+npx shadcn@latest add https://stepwise-demo.vercel.app/r/player-bar.json
+```
+
+Items: `player-bar`, `code-block`, `tour`, `glossary`, `chapter-nav`, `lesson-pager`, `shortcuts-dialog` — or `stepwise` for all of them. The presentation source lands in `components/stepwise/` (plus `lib/stepwise-theme.ts`), where Tailwind scans it automatically; hooks and types stay imported from this package. Colors come from your shadcn tokens.
+
+**3. Tailwind, using the components from npm** — register the package so Tailwind generates its classes (v4 skips `node_modules`):
+
+```css
+@import "tailwindcss";
+@source "../node_modules/@sphynxoid/stepwise/dist";
+```
+
+Token contract, Tailwind v3 setup and the "everything renders unstyled" checklist: [TAILWIND-SETUP.md](https://github.com/TheSphynxoid/stepwise/blob/master/docs/TAILWIND-SETUP.md).
+
+## Quick start — a narrated player
+
+```tsx
+"use client";
+import { useTrace, PlayerBar, CodeBlock, type StepwiseStep } from "@sphynxoid/stepwise";
+
+// Your domain payload rides along with the presentation fields.
+const frames: StepwiseStep<{ code: string[] }>[] = [
+  { tone: "write", label: "Initialize", code: ["let i = 0;"] },
+  { tone: "neutral", label: "Loop", code: ["while (i < n) { … }"] },
+  { tone: "good", label: "Done", code: ["return arr;"] },
+];
+
+export function Demo() {
+  const trace = useTrace(frames, { autoPlay: true, syncHash: "frame" });
+
+  return (
+    <>
+      <CodeBlock lines={trace.step!.code} />
+      <PlayerBar player={trace.player} toneAt={trace.toneAt} titleAt={trace.titleAt} />
+    </>
+  );
+}
+```
+
+`useTrace` binds a player to a typed trace: `step` is the frame to render (frame 0 before playback starts), and `toneAt` / `titleAt` feed the scrubber. Under it, `useStepPlayer` gives you a timer-driven playhead with play/pause/seek, speed control, and optional `#frame=2` deep links — or hand it an `engine` to drive the playhead from GSAP or scroll instead. Two end-state flavors: `atEnd` (cursor parked on the last frame, seeks included) and `ended` (playback ran to the finish, via the `onEnd` callback option) — clearing on any cursor movement, so a completion summary knows the demo actually finished. `autoPlay` respects `prefers-reduced-motion` (lands on frame 0, paused; opt out with `respectReducedMotion: false`), and `syncHash` writes only its own key, so it coexists with anchors and other players' keys.
+
+## The three scales
+
+| Scale | Hook | Presentation |
+|---|---|---|
+| **Player** — auto-played frames in a trace | `useStepPlayer` (+ `PlayerEngine` adapters) | `PlayerBar`, `StepScrubber`, `CodeBlock` |
+| **Tour** — steps that mutate app state via `onEnter` | `useGuidedTour` (+ `TourDriver` adapters) | `TourSpotlight`, `TourCard` |
+| **Chapters** — scroll-tracked sections | `useChapters`, `flattenChapters` | `ChapterNav`, `LessonPager` |
+
+All three compose the same `useSteps` cursor, so movement, clamping, and boundary flags behave identically everywhere.
+
+Tours are small state machines: a step may declare `when` (skip on arrival when false), `gate` (block `next()` — and expose `blocked` — until the user actually does the thing), and `next` (edge override to another step's `id`, enabling branches and loops). `gotoId(id)` navigates by identity; programmatic navigation never trips gates.
+
+## Show-once tutorials (led discovery)
+
+Pair `useDiscoveries` with `useGuidedTour` to auto-play a tour the first time a user encounters a feature:
+
+```tsx
+const { discovered, ready, markDiscovered } = useDiscoveries();
+const tour = useGuidedTour(steps);
+
+// when this build carries an undiscovered feature, play its tour once
+useEffect(() => {
+  if (ready && !tour.active && !discovered.has("search:v1")) tour.start();
+}, [ready, tour.active, discovered]);
+
+// mark on completion (or explicit dismiss) — never on mere trigger
+useEffect(() => {
+  if (launched && !tour.active) markDiscovered("search:v1");
+}, [tour.active]);
+```
+
+The ledger is a set of opaque ids behind a `DiscoveryStore` seam: `localStorageStore` (default), `cookieStore` (when SSR markup must know), `memoryStore` (tests), or your own store backed by an API for cross-device discovery.
+
+## Supporting pieces
+
+- `useGlobalKeys` — global keyboard bindings with a form-control guard
+- `useFocusTrap` — dialog/tour focus containment
+- `usePrefersReducedMotion` — motion preference gate
+- `useDiscoveries` (+ `localStorageStore` / `cookieStore` / `memoryStore`) — persisted discovery ledger with a swappable storage seam
+- `GlossaryProvider` / `Term` / `GlossaryAppendix` — recursive, depth-capped term tooltips with an auto-collecting appendix
+- `ShortcutsDialog` — keyboard shortcut reference
+- `defaultTheme` / `StepwiseTheme` — the default styling, overridable per component via a `theme` prop (swap in any design system)
+
+## Adapters
+
+Import adapters from their subpaths — never from the root barrel:
+
+```ts
+import { createGsapPlayerEngine } from "@sphynxoid/stepwise/adapters/gsap";
+import { createDriverJsTourDriver } from "@sphynxoid/stepwise/adapters/driver-js";
+import { createScrollPlayerEngine } from "@sphynxoid/stepwise/adapters/scroll";
+```
+
+An adapter plugs into a tiny port (`PlayerEngine` / `TourDriver`), so you can write your own for Shepherd, Framer Motion, or anything else without touching the kit.
+
+## React
+
+Supports React 18 and 19. All hooks are SSR-safe (`"use client"` modules, no window access at module evaluation) and every public hook returns referentially stable callbacks.
+
+## License
+
+MIT

package/dist/adapters/driver-js.d.ts

@@ -1,4 +1,4 @@
-import { T as TourDriver } from '../types-CPf9ZD_Z.js';
+import { T as TourDriver } from '../types-IT_9L8On.js';
 import 'react';
 
 interface DriverJsTourOptions {

package/dist/adapters/gsap.d.ts

@@ -1,4 +1,4 @@
-import { P as PlayerEngine } from '../types-CPf9ZD_Z.js';
+import { P as PlayerEngine } from '../types-IT_9L8On.js';
 import 'react';
 
 interface GsapEngineOptions {

package/dist/adapters/scroll.d.ts

@@ -1,4 +1,4 @@
-import { P as PlayerEngine } from '../types-CPf9ZD_Z.js';
+import { P as PlayerEngine } from '../types-IT_9L8On.js';
 import 'react';
 
 interface ScrollEngineOptions {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { P as PlayerEngine, a as TourStepInput, T as TourDriver, C as Chapter, S as StepTone, b as ShortcutItem } from './types-CPf9ZD_Z.js';
-export { c as PlayerEngineApi, d as PlayerEngineHandle, e as StepwiseStep, f as TourContext } from './types-CPf9ZD_Z.js';
+import { P as PlayerEngine, S as StepwiseStep, a as StepTone, b as TourStepInput, T as TourDriver, C as Chapter, c as ShortcutItem } from './types-IT_9L8On.js';
+export { d as PlayerEngineApi, e as PlayerEngineHandle, f as TourContext } from './types-IT_9L8On.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
 
@@ -53,7 +53,8 @@ interface StepPlayerOptions {
     engine?: PlayerEngine;
     /**
      * Deep-link the current frame into the URL hash (`#<key>=<index>`), opt-in.
-     * The initial hash is honored once on mount.
+     * The initial hash is honored once on mount. Only this key is written —
+     * other `&`-separated hash parts (anchors, other players' keys) are kept.
      */
     syncHash?: string;
     /**
@@ -62,6 +63,12 @@ interface StepPlayerOptions {
      * reset/new timeline) — the next full playthrough fires it again.
      */
     onEnd?: () => void;
+    /**
+     * Honor `prefers-reduced-motion: reduce` by not auto-advancing: with
+     * `autoPlay`, the player still lands on frame 0 but stays paused until the
+     * user presses play. Default true.
+     */
+    respectReducedMotion?: boolean;
 }
 interface StepPlayer {
     /** Total frames in the current timeline. */
@@ -94,7 +101,199 @@ interface StepPlayer {
     setPlaying: (playing: boolean) => void;
     setSpeed: (speed: number) => void;
 }
-declare function useStepPlayer({ total, baseDelayMs, autoPlay, engine, syncHash, onEnd }: StepPlayerOptions): StepPlayer;
+declare function useStepPlayer({ total, baseDelayMs, autoPlay, engine, syncHash, onEnd, respectReducedMotion, }: StepPlayerOptions): StepPlayer;
+
+interface TracePlayer<S extends StepwiseStep> {
+    /** The underlying player — pass it to PlayerBar. */
+    player: StepPlayer;
+    /**
+     * The frame to render. Never undefined for a non-empty trace: before the
+     * player starts (`player.index === -1`) this is frame 0, not the last one.
+     */
+    step: S | undefined;
+    /** Index of `step` in the trace (0 before start; -1 for an empty trace). */
+    frame: number;
+    /** Stable `toneAt` for PlayerBar / StepScrubber. */
+    toneAt: (i: number) => StepTone;
+    /** Stable `titleAt` for PlayerBar / StepScrubber. */
+    titleAt: (i: number) => string;
+}
+/**
+ * A player bound to a concrete trace: the steps array is the timeline, and
+ * the hook resolves the frame to render (frame 0 before start — invariant
+ * "index -1 means not started"), plus scrubber accessors that read the
+ * latest steps through a ref. Replaces the per-page
+ * `player.index >= 0 ? … : 0` boilerplate.
+ *
+ *   const trace = useTrace(STEPS, { autoPlay: true });
+ *   <Viz arr={trace.step.arr} />
+ *   <PlayerBar player={trace.player} toneAt={trace.toneAt} titleAt={trace.titleAt} />
+ */
+declare function useTrace<S extends StepwiseStep>(steps: readonly S[], opts?: Omit<StepPlayerOptions, "total">): TracePlayer<S>;
+
+interface TraceBuilder<Data extends object> {
+    /** Append one frame. Returns the builder, so calls chain. */
+    step(step: StepwiseStep<Data>): TraceBuilder<Data>;
+    /** Frames appended so far. */
+    readonly length: number;
+    /** The most recently appended frame (handy for "carry the state forward"). */
+    last(): StepwiseStep<Data> | undefined;
+    /** Snapshot the trace. A fresh array each call — the builder stays usable. */
+    build(): StepwiseStep<Data>[];
+}
+/**
+ * Typed trace builder. Authors run their algorithm at module scope and record
+ * frames as they go — no IIFE, no pre-declared `const STEPS = []` that a
+ * component might read before it is filled (invariant 6):
+ *
+ *   const t = createTrace<{ arr: number[] }>();
+ *   for (…) t.step({ tone: "write", label: "swap", arr: [...arr] });
+ *   export const STEPS = t.build();
+ *
+ * Pure data — no React, safe on the server.
+ */
+declare function createTrace<Data extends object = Record<never, never>>(): TraceBuilder<Data>;
+
+/** Named traces to play side by side: `{ bubble: stepsA, insertion: stepsB }`. */
+type Tracks = Record<string, readonly StepwiseStep<object>[]>;
+/**
+ * Sync-point key for a step. Steps with the same key in two or more tracks
+ * land on the same aligned frame; `null`/`undefined` marks a free step. The
+ * n-th occurrence of a key in one track pairs with the n-th in another.
+ */
+type TrackKeyFn<T extends Tracks = Tracks> = (step: T[keyof T][number], index: number, track: keyof T & string) => string | null | undefined;
+/** One track's slot in one aligned frame. */
+interface AlignedCell {
+    /** Index into the track's own steps; -1 only for an empty track. */
+    index: number;
+    /**
+     * The track did not advance on this frame: it is holding its last frame
+     * (finished, or waiting for a sync point), or waiting at frame 0 for its
+     * first sync point.
+     */
+    held: boolean;
+}
+type AlignedRow<K extends string = string> = Record<K, AlignedCell>;
+/**
+ * Align several traces into one timeline. Pure — use it directly for server
+ * rendering or tests; `useSyncedTracks` memoizes it per track identity.
+ *
+ * - No `key` (hold): frame i shows step i of every track; a shorter track
+ *   holds its last frame once it runs out. Length = the longest track.
+ * - With `key`: tracks advance together frame by frame, but a track whose
+ *   next step is a sync point holds until every other track that shares the
+ *   point has reached it, so matching steps share a frame. Keys must occur
+ *   in the same relative order across tracks; where they conflict, that
+ *   frame degrades to lockstep instead of deadlocking.
+ */
+declare function alignTracks<T extends Tracks>(tracks: T, key?: TrackKeyFn<T>): AlignedRow<keyof T & string>[];
+interface TrackView<S> {
+    /** The step to render for this track (undefined only for an empty track). */
+    step: S | undefined;
+    /** Index into the track's own steps; -1 for an empty track. */
+    index: number;
+    /** The track did not advance on this frame (see `AlignedCell.held`). */
+    held: boolean;
+    /** The track is on its final step. */
+    done: boolean;
+    /** Length of the track's own trace. */
+    length: number;
+}
+interface SyncedTracksOptions<T extends Tracks = Tracks> extends Omit<StepPlayerOptions, "total"> {
+    /**
+     * Sync-point alignment (see `alignTracks`). Omit to hold shorter tracks on
+     * their last frame. Read when the tracks change — pass the same tracks to
+     * keep the alignment memoized; an inline function is fine.
+     */
+    key?: TrackKeyFn<T>;
+}
+interface SyncedTracks<T extends Tracks> {
+    /** One player over the aligned timeline — pass it to PlayerBar. */
+    player: StepPlayer;
+    /** Aligned frame to render: 0 before the player starts, -1 when all tracks are empty. */
+    frame: number;
+    /** Number of aligned frames. */
+    total: number;
+    /** Per-track view of `frame`. */
+    tracks: {
+        [K in keyof T]: TrackView<T[K][number]>;
+    };
+    /** The full alignment table (stable while the tracks are). */
+    rows: readonly AlignedRow<keyof T & string>[];
+    /** Stable scrubber accessors: the most severe tone among tracks that moved. */
+    toneAt: (i: number) => StepTone;
+    /** Stable scrubber accessor: `track: label` for every track that moved. */
+    titleAt: (i: number) => string;
+}
+/**
+ * Comparison mode: several traces of the same input (two engines, two
+ * algorithms) under ONE player. The cursor walks the aligned timeline from
+ * `alignTracks`; each track resolves its own step, so payload types stay
+ * per-track. Like `useTrace`, frame 0 renders before playback starts.
+ *
+ *   const cmp = useSyncedTracks({ bubble: BUBBLE, insertion: INSERTION }, { autoPlay: true });
+ *   <Lane step={cmp.tracks.bubble.step} held={cmp.tracks.bubble.held} />
+ *   <PlayerBar player={cmp.player} toneAt={cmp.toneAt} titleAt={cmp.titleAt} />
+ */
+declare function useSyncedTracks<T extends Tracks>(tracks: T, opts?: SyncedTracksOptions<T>): SyncedTracks<T>;
+
+interface LessonStreamOptions {
+    /** Lesson to open on (deep link). Clamped. Default 0. */
+    seed?: number;
+    /** Lessons mounted on each side of the seed initially. Default 1. */
+    radius?: number;
+    /** Load the next lesson when the last mounted one's bottom is within this many px below the viewport. Default 600. */
+    approachBelow?: number;
+    /** Load the previous lesson when the first mounted one's top is below `-approachAbove`. Default 300. */
+    approachAbove?: number;
+    /** Scroll the seed lesson into view before first paint (seed > 0). Default true. */
+    scrollToSeed?: boolean;
+    /**
+     * Fired when the scroll-tracked active lesson changes (not on mount) — sync
+     * the URL / document title here. Read through a ref; inline is fine.
+     */
+    onActiveChange?: (index: number) => void;
+}
+interface LessonStream {
+    /** Lesson containing the viewport center (the seed until the first measure). */
+    active: number;
+    /** The seed lesson — SSR'd visible; every other block should fade in. */
+    seed: number;
+    /** Indices to render, in order (the mounted window). */
+    mounted: number[];
+    /** The window reaches the last lesson — render an end-of-stream footer. */
+    complete: boolean;
+    /** Stable callback ref for lesson `i`'s block element (cached per index). */
+    refFor: (index: number) => (el: HTMLElement | null) => void;
+    /** Mount through lesson `i` (if needed) and scroll to it. */
+    goTo: (index: number) => void;
+    next: () => void;
+    prev: () => void;
+    reducedMotion: boolean;
+}
+/**
+ * Continuous reader for a sequence of lessons (a notebook): renders a growing
+ * window of lessons around the seed instead of all of them, and tracks the
+ * active one by viewport-center containment (invariant 1).
+ *
+ * - The lesson after the window mounts as the reader approaches its place;
+ *   the one before mounts near the top, and a layout effect compensates the
+ *   scroll so prepended content never shoves the reader down.
+ * - Navigation (`goTo`) expansions are NOT compensated — their scrollIntoView
+ *   is absolute, and compensating them displaced the landing.
+ * - The cursor is a useSteps core, so it composes with ChapterNav
+ *   (`active` + `goTo`) and LessonPager (`prev`/`next`).
+ *
+ * Headless: the consumer renders `mounted.map(i => <Block ref={refFor(i)} />)`
+ * and owns the content; pair blocks with `useFadeIn(i === seed)`.
+ */
+declare function useLessonStream(count: number, opts?: LessonStreamOptions): LessonStream;
+/**
+ * Mount fade for streamed blocks: `false` on the first client render, `true`
+ * a frame later (immediately with reduced motion). Pass `initiallyVisible`
+ * for server-rendered blocks (the stream's seed) so they never flash.
+ */
+declare function useFadeIn(initiallyVisible?: boolean): boolean;
 
 interface GuidedTour {
     /** Active step index, or null when the tour is not running. */
@@ -438,4 +637,4 @@ declare function ShortcutsDialog({ open, onClose, items, title, className, theme
     theme?: StepwiseTheme;
 }): react.ReactPortal | null;
 
-export { Chapter, ChapterNav, type ChaptersApi, CodeBlock, type Discoveries, type DiscoveriesOptions, type DiscoveryStore, type FlatChapter, type GlobalKeysOptions, GlossaryAppendix, type GlossaryEntry, GlossaryProvider, type GuidedTour, type GuidedTourOptions, type KeyMap, LessonPager, PlayerBar, PlayerEngine, ShortcutItem, ShortcutsDialog, type StepPlayer, type StepPlayerOptions, StepScrubber, StepTone, type StepsCore, type StepwiseTheme, TONE_CHIP_CLASS, TONE_SEGMENT_CLASS, Term, TourCard, TourDriver, TourSpotlight, TourStepInput, type UseStepsOptions, cookieStore, defaultTheme, flattenChapters, localStorageStore, memoryStore, useChapters, useDiscoveries, useFocusTrap, useGlobalKeys, useGuidedTour, usePrefersReducedMotion, useStepPlayer, useSteps };
+export { type AlignedCell, type AlignedRow, Chapter, ChapterNav, type ChaptersApi, CodeBlock, type Discoveries, type DiscoveriesOptions, type DiscoveryStore, type FlatChapter, type GlobalKeysOptions, GlossaryAppendix, type GlossaryEntry, GlossaryProvider, type GuidedTour, type GuidedTourOptions, type KeyMap, LessonPager, type LessonStream, type LessonStreamOptions, PlayerBar, PlayerEngine, ShortcutItem, ShortcutsDialog, type StepPlayer, type StepPlayerOptions, StepScrubber, StepTone, type StepsCore, StepwiseStep, type StepwiseTheme, type SyncedTracks, type SyncedTracksOptions, TONE_CHIP_CLASS, TONE_SEGMENT_CLASS, Term, TourCard, TourDriver, TourSpotlight, TourStepInput, type TraceBuilder, type TracePlayer, type TrackKeyFn, type TrackView, type Tracks, type UseStepsOptions, alignTracks, cookieStore, createTrace, defaultTheme, flattenChapters, localStorageStore, memoryStore, useChapters, useDiscoveries, useFadeIn, useFocusTrap, useGlobalKeys, useGuidedTour, useLessonStream, usePrefersReducedMotion, useStepPlayer, useSteps, useSyncedTracks, useTrace };