@sphynxoid/stepwise 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,640 @@
+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';
+
+interface UseStepsOptions {
+    /** Initial focus. Clamped. Defaults to 0. */
+    initialIndex?: number;
+    /** Fired whenever the focus index changes. */
+    onChange?: (index: number) => void;
+}
+interface StepsCore {
+    /** Number of steps in the sequence. */
+    count: number;
+    /** Clamped focus: 0..count-1, or -1 when the sequence is empty. */
+    index: number;
+    atStart: boolean;
+    atEnd: boolean;
+    canNext: boolean;
+    canPrev: boolean;
+    /** Clamped jump. No-op on an empty sequence. */
+    go: (index: number) => void;
+    /** Clamped forward step. */
+    next: () => void;
+    /** Clamped backward step. */
+    prev: () => void;
+    /** Jump to the first step. */
+    first: () => void;
+}
+/**
+ * The core primitive every stepwise machine composes: a clamped cursor over an
+ * ordered sequence. Frames in a trace, chapters in a lesson, lessons in a
+ * notebook, and tour steps are all the same thing at this layer — timers,
+ * effects, and scroll-tracking are policies layered on top by consumers.
+ *
+ * All callbacks are referentially stable; `count` may change dynamically (a
+ * new timeline, a mounted window) and the cursor re-clamps automatically.
+ */
+declare function useSteps<T>(items: readonly T[] | number, opts?: UseStepsOptions): StepsCore;
+
+interface StepPlayerOptions {
+    /** Number of frames in the current timeline (0 = no timeline loaded). */
+    total: number;
+    /** Delay per frame at 1× speed (built-in timer engine). */
+    baseDelayMs?: number;
+    /** Start playing immediately (used when a timeline exists on first render). */
+    autoPlay?: boolean;
+    /**
+     * Alternate frame source (GSAP timeline, scroll progress, …). Replaces the
+     * built-in timer. Memoize the engine per timeline — identity changes
+     * reconnect it.
+     */
+    engine?: PlayerEngine;
+    /**
+     * Deep-link the current frame into the URL hash (`#<key>=<index>`), opt-in.
+     * 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;
+    /**
+     * Fired once when playback runs to the final frame on its own (built-in
+     * timer or engine `onEnd`). Cleared by any cursor movement (seek/step/
+     * 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. */
+    total: number;
+    /** Raw frame counter; -1 means "no timeline / before first frame". */
+    frame: number;
+    /** Frame clamped into [0, total-1]; -1 when there is nothing to show. */
+    index: number;
+    playing: boolean;
+    speed: number;
+    /** Position flag: the cursor is parked on the final frame (seek counts too). */
+    atEnd: boolean;
+    /**
+     * Completion state: playback ran to the final frame on its own and nothing
+     * has moved the cursor since. Unlike `atEnd`, a seek to the last frame does
+     * not set it — `toggle()` at `ended` replays from frame 0.
+     */
+    ended: boolean;
+    /** Jump to frame 0 and play. */
+    start: () => void;
+    /** Clear the player (frame = -1, paused). */
+    reset: () => void;
+    seek: (frame: number) => void;
+    /** Step forward; pauses first. `onEmpty` fires when there is no timeline. */
+    next: (onEmpty?: () => void) => void;
+    /** Step backward; pauses first. */
+    prev: () => void;
+    /** Play/pause; replays from 0 at the end. `onEmpty` fires when there is no timeline. */
+    toggle: (onEmpty?: () => void) => void;
+    setPlaying: (playing: boolean) => void;
+    setSpeed: (speed: number) => void;
+}
+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. */
+    index: number | null;
+    current: TourStepInput | null;
+    active: boolean;
+    /**
+     * True while the active step's `gate` returns false: `next()` is a no-op
+     * until the gate opens. Present the `blocked` state (disable Next, pulse
+     * the waitHint) so the user knows what is being waited on.
+     */
+    blocked: boolean;
+    start: () => void;
+    end: () => void;
+    next: () => void;
+    back: () => void;
+    goto: (index: number) => void;
+    /** Jump to the step with this id. No-op when the id is unknown. */
+    gotoId: (id: string) => void;
+}
+interface GuidedTourOptions {
+    /**
+     * Alternate presenter (driver.js, Shepherd, …). When set, the hook drives it
+     * imperatively — show/hide per step, with transition controls wired — and
+     * the app should not render the built-in TourSpotlight/TourCard. Without a
+     * driver, the app renders the built-in presentation itself.
+     */
+    driver?: TourDriver;
+}
+/**
+ * Tour state whose steps are effects over app state: `onEnter` fires whenever
+ * the active step changes, reading the latest `steps` via ref so closures stay
+ * fresh without re-triggering the effect on every render. Composed on
+ * useSteps — a tour is a step sequence whose `next` past the end exits.
+ *
+ * On top of the linear cursor, steps may declare `when` (skip on arrival),
+ * `gate` (block `next` until true), and `next` (edge override by step id) —
+ * a small state machine where states are steps, edges are `next` functions,
+ * and guards are gates. The cursor itself stays a cursor: skipped steps are
+ * never landed on, and skipped/gated behavior is evaluated at transition
+ * time, not on every render.
+ */
+declare function useGuidedTour(steps: TourStepInput[], opts?: GuidedTourOptions): GuidedTour;
+
+interface FlatChapter {
+    chapter: Chapter;
+    depth: number;
+    /** Index of this entry's top-level ancestor within the flat list (itself at depth 0). */
+    rootIndex: number;
+    /** Index of the immediate parent within the flat list; -1 at depth 0. */
+    parentIndex: number;
+}
+/** Depth-first flattening — reading order for prev/next and scroll tracking. */
+declare function flattenChapters(chapters: Chapter[], depth?: number): FlatChapter[];
+
+interface ChaptersApi {
+    /** Index of the chapter currently in view (flattened order). */
+    active: number;
+    goTo: (index: number) => void;
+    next: () => void;
+    prev: () => void;
+}
+
+/**
+ * Scroll-tracked chapter navigation for multi-section pages. Active = the
+ * section containing the viewport center: a chapter becomes active when it
+ * reaches the middle of the screen, not the moment its top scrolls past an
+ * offset. Sections are resolved by DOM id; give each section CSS scroll-mt
+ * so `goTo`'s scrollIntoView clears any sticky header. Composed on useSteps —
+ * the scroll position is an external input driving the cursor.
+ */
+declare function useChapters(chapters: Chapter[]): ChaptersApi;
+
+type KeyMap = Record<string, (e: KeyboardEvent) => void>;
+interface GlobalKeysOptions {
+    /** Element tags that swallow keys (except Escape). Defaults to form controls and buttons. */
+    ignoreTags?: string[];
+    /** Gate: bindings fire only while enabled. Boolean or function — checked per event. */
+    enabled?: boolean | (() => boolean);
+}
+/**
+ * Bind global keyboard shortcuts. Keys are matched against `event.key`
+ * (exact first, then lowercase). Handlers fire with preventDefault applied;
+ * Escape always fires, even from ignored targets, and is never prevented.
+ */
+declare function useGlobalKeys(map: KeyMap, opts?: GlobalKeysOptions): void;
+
+interface DiscoveryStore {
+    /** All discovered ids (best-effort; corrupted/absent storage reads as empty). */
+    read(): string[];
+    /** Persist the full set (write-through, not a delta). */
+    write(ids: string[]): void;
+}
+/** localStorage-backed store — the default. Survives reloads, per-browser. */
+declare function localStorageStore(key?: string): DiscoveryStore;
+/**
+ * Cookie-backed store — only when the SERVER must know during SSR (e.g. to
+ * render "NEW" badges without a hydration flash). Costs request bytes; prefer
+ * localStorage otherwise. Values are JSON-encoded and URI-escaped.
+ */
+declare function cookieStore(key?: string): DiscoveryStore;
+/** In-memory store — tests, storybook, SSR fallbacks, "always show" previews. */
+declare function memoryStore(seed?: string[]): DiscoveryStore;
+interface DiscoveriesOptions {
+    /**
+     * Storage seam. Defaults to localStorage. Swap in cookieStore when SSR
+     * markup must know, or your own store (backend sync for cross-device).
+     */
+    store?: DiscoveryStore;
+    /** Storage key used by the built-in stores. */
+    key?: string;
+}
+interface Discoveries {
+    /** Discovered ids. Empty until hydration — gate triggers on `ready`. */
+    discovered: Set<string>;
+    /** False during SSR and before the first client hydration pass. */
+    ready: boolean;
+    /** Ref-backed check for event handlers; prefer `discovered.has` in render. */
+    isDiscovered: (id: string) => boolean;
+    /** Record ids as discovered and persist the merged set. */
+    markDiscovered: (id: string | string[]) => void;
+    /** Forget everything (debug / "show me the tour again"). */
+    reset: () => void;
+}
+/**
+ * A persisted set of discovered ids, hydrated after mount (SSR-safe: the
+ * server renders the undiscovered state, the client corrects it in an
+ * effect — same pattern as usePrefersReducedMotion). Compose with
+ * useGuidedTour: `pending = features.filter(f => !discovered.has(f.id))`,
+ * auto-start the first pending tour, `markDiscovered` on completion.
+ */
+declare function useDiscoveries(opts?: DiscoveriesOptions): Discoveries;
+
+/**
+ * Traps Tab focus inside `ref.current` while `active`, focuses the container
+ * on activation, and restores the previously focused element on release.
+ * Returns a ref to attach to the focusable container (tabIndex={-1}).
+ */
+declare function useFocusTrap(active: boolean): react.RefObject<HTMLDivElement | null>;
+
+/**
+ * True when the user asks the OS to reduce motion. Consumers should disable
+ * transitions, smooth scrolls, and entry animations when this is true.
+ * SSR-safe: false on the server, corrected after mount.
+ */
+declare function usePrefersReducedMotion(): boolean;
+
+interface StepwiseTheme {
+    /** Timeline-segment styling per tone. */
+    toneSegment: Record<StepTone, string>;
+    /** Step-kind chip styling per tone. */
+    toneChip: Record<StepTone, string>;
+    /** Shared structural classes for internal buttons. */
+    buttonBase: string;
+    /** Per-variant appearance for internal buttons. */
+    buttonVariants: Record<"ghost" | "outline" | "primary", string>;
+    /**
+     * Panel chrome for nav bars, cards, dialogs, and tooltip popovers.
+     * Components pass their own border/background overrides after this token,
+     * so it stays a base, not a contract.
+     */
+    surface: string;
+    /** Full-screen dimmed backdrop behind modal surfaces. */
+    overlay: string;
+    /** Code block frame — its own background, border, and type scale. */
+    codeBlock: string;
+    /** Comment / dimmed lines inside the code block. */
+    codeMuted: string;
+    /** Keyboard chip (ShortcutsDialog). */
+    kbd: string;
+    /** Ring + rounding around the tour spotlight target. */
+    spotlight: string;
+    /** Dimmed meta text — counters, hints, empty states. */
+    muted: string;
+}
+declare const defaultTheme: StepwiseTheme;
+
+interface GlossaryEntry {
+    id: string;
+    /** Display name, shown as the tooltip's heading. */
+    term: string;
+    /** Body — may embed <Term> references for nested tooltips. */
+    definition: ReactNode;
+}
+declare function GlossaryProvider({ entries, theme, children, }: {
+    entries: GlossaryEntry[];
+    /** Styling for tooltip cards (see StepwiseTheme). */
+    theme?: StepwiseTheme;
+    children: ReactNode;
+}): react.JSX.Element;
+declare function Term({ id, children, className }: {
+    id: string;
+    children?: ReactNode;
+    className?: string;
+}): react.JSX.Element;
+/**
+ * The glossary appendix: every entry rendered as an anchored row, placed
+ * after the last chapter. Entries default to the provider's declarations —
+ * define them once and the appendix follows automatically; pass `entries`
+ * explicitly to override or to render without a provider. Inside it, <Term>
+ * references resolve to in-page anchor links instead of tooltips.
+ *
+ * Customization hooks: `intro`/`footer` render arbitrary nodes around the
+ * grid, `renderEntry` replaces the whole row renderer, `className` and
+ * `entryClassName` style the section and each row. Opt out of the appendix
+ * entirely by not rendering it.
+ */
+declare function GlossaryAppendix({ entries, title, intro, footer, columns, bare, className, entryClassName, renderEntry, }: {
+    /** Override the row list; defaults to the provider's entries. */
+    entries?: GlossaryEntry[];
+    title?: string;
+    /** Rendered between the title and the grid — an introduction, usage notes, scope, … */
+    intro?: ReactNode;
+    /** Rendered after the grid. */
+    footer?: ReactNode;
+    columns?: 1 | 2;
+    /** Omit the section chrome (title/border) — the host provides its own. */
+    bare?: boolean;
+    className?: string;
+    entryClassName?: string;
+    /** Replace the default row renderer entirely. */
+    renderEntry?: (entry: GlossaryEntry) => ReactNode;
+}): react.JSX.Element | null;
+
+declare const TONE_SEGMENT_CLASS: Record<StepTone, string>;
+declare const TONE_CHIP_CLASS: Record<StepTone, string>;
+declare function CodeBlock({ lines, theme, className, }: {
+    lines: string[];
+    theme?: StepwiseTheme;
+    className?: string;
+}): react.JSX.Element;
+interface ScrubberLabels {
+    /** aria-label for the slider. */
+    scrubber?: string;
+    /** aria-valuetext for the current position. Receives the frame index. */
+    frame?: (i: number) => string;
+}
+declare function StepScrubber({ count, index, toneAt, titleAt, onSeek, emptyHint, className, theme, labels, groupOf, }: {
+    count: number;
+    index: number;
+    toneAt?: (i: number) => StepTone;
+    titleAt?: (i: number) => string;
+    onSeek: (i: number) => void;
+    emptyHint?: string;
+    className?: string;
+    theme?: StepwiseTheme;
+    labels?: ScrubberLabels;
+    /**
+     * Groups consecutive segments into one proportional wrapper — a chapter
+     * with sub-chapters spans the width of its whole subtree and only the
+     * active inner segment fills, so a chapter reads as "halfway" while its
+     * children play. Segments must be group-contiguous (flattenChapters order).
+     */
+    groupOf?: (i: number) => number;
+}): react.JSX.Element;
+declare function PlayerBar({ player, toneAt, titleAt, leading, onEmpty, emptyHint, className, theme, groupOf, labels, }: {
+    player: {
+        total: number;
+        index: number;
+        playing: boolean;
+        atEnd: boolean;
+        next: (onEmpty?: () => void) => void;
+        prev: () => void;
+        toggle: (onEmpty?: () => void) => void;
+        seek: (frame: number) => void;
+    };
+    toneAt?: (i: number) => StepTone;
+    titleAt?: (i: number) => string;
+    leading?: ReactNode;
+    /** Fired when the user plays/steps with no timeline loaded. */
+    onEmpty?: () => void;
+    emptyHint?: string;
+    className?: string;
+    theme?: StepwiseTheme;
+    /**
+     * Forwarded to the scrubber — group consecutive segments into one
+     * proportional wrapper (see StepScrubber).
+     */
+    groupOf?: (i: number) => number;
+    labels?: {
+        previous?: string;
+        play?: string;
+        pause?: string;
+        replay?: string;
+        next?: string;
+    };
+}): react.JSX.Element;
+declare function ChapterNav({ chapters, active, onNavigate, hint, className, theme, }: {
+    chapters: Chapter[];
+    active: number;
+    onNavigate: (i: number) => void;
+    hint?: string;
+    className?: string;
+    theme?: StepwiseTheme;
+}): react.JSX.Element;
+declare function LessonPager({ prev, next, onNavigate, className, labels, }: {
+    prev?: {
+        label: string;
+        hint?: string;
+    };
+    next?: {
+        label: string;
+        hint?: string;
+    };
+    onNavigate: (dir: "prev" | "next") => void;
+    className?: string;
+    labels?: {
+        previous?: string;
+        next?: string;
+    };
+}): react.JSX.Element;
+declare function TourSpotlight({ target, theme, }: {
+    target: string | null;
+    theme?: StepwiseTheme;
+}): react.JSX.Element | null;
+declare function TourCard({ step, index, total, onNext, onBack, onEnd, labels, className, theme, nextDisabled, }: {
+    step: TourStepInput;
+    index: number;
+    total: number;
+    onNext: () => void;
+    onBack: () => void;
+    onEnd: () => void;
+    labels?: {
+        title?: string;
+        back?: string;
+        next?: string;
+        finish?: string;
+        end?: string;
+    };
+    className?: string;
+    theme?: StepwiseTheme;
+    /** Disable the primary (Next/Finish) button — pair with tour.blocked. */
+    nextDisabled?: boolean;
+}): react.JSX.Element;
+declare function ShortcutsDialog({ open, onClose, items, title, className, theme, }: {
+    open: boolean;
+    onClose: () => void;
+    items: ShortcutItem[];
+    title?: string;
+    className?: string;
+    theme?: StepwiseTheme;
+}): react.ReactPortal | null;
+
+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 };