useSequencePlayer

1"use client";
2 
3import { useCallback, useEffect, useRef, useState } from "react";
4 
5import { useReducedMotion } from "@/hooks/use-reduced-motion";
6 
7/**
8 * One scripted sequence: how many beats it plays and how long each beat rests.
9 *
10 * `stepMs` accepts an array when the beats are unequal — a code-entry demo that
11 * types four digits and then holds on a success check needs a long final beat,
12 * and averaging that into one number makes the payoff read as a glitch. The last
13 * entry repeats if the array is shorter than `steps`.
14 */
15export type SequenceScript = {
16  steps: number;
17  stepMs: number | readonly number[];
18};
19 
20export type UseSequencePlayerOptions = {
21  /** One entry per sequence, in spotlight order. */
22  sequences: readonly SequenceScript[];
23  /**
24   * Quiet beat before the first sequence starts, so a page that just scrolled
25   * into view settles before anything moves. Defaults to 500ms.
26   */
27  leadInMs?: number;
28  /** Set false to hold everything at its poster frame. Defaults to true. */
29  enabled?: boolean;
30  /**
31   * Whether `takeOver` keeps replaying its sequence instead of handing off.
32   * Defaults to true — the point of taking over is to watch one thing repeat.
33   */
34  loopTakeOver?: boolean;
35};
36 
37type ContainerProps = {
38  ref: (node: HTMLElement | null) => void;
39  onFocusCapture: () => void;
40  onBlurCapture: (event: { currentTarget: HTMLElement; relatedTarget: EventTarget | null }) => void;
41  onPointerLeave: () => void;
42};
43 
44export type UseSequencePlayerResult = {
45  /**
46   * Spread onto the element that wraps every sequence. Supplies the visibility
47   * observer plus the focus and pointer pauses; without it the player would keep
48   * animating off-screen and would yank the spotlight away from a keyboard user
49   * reading one sequence.
50   */
51  containerProps: ContainerProps;
52  /** Index of the sequence currently holding the spotlight. */
53  activeIndex: number;
54  /** Beats already fired in the active sequence; the last one is still resting. */
55  stepsFired: number;
56  /**
57   * Per-sequence play counter. Feed `runs[i]` to a sequence as a prop (or a
58   * React `key`) and derive its visual state from that number — the player never
59   * needs to know what any sequence actually renders.
60   */
61  runs: readonly number[];
62  /** False while paused: reduced motion, off-screen, background tab, or focused. */
63  isPlaying: boolean;
64  /** Dwell for one beat, for driving a progress indicator. */
65// … truncated