Beats and the story timeline

A story slide pins one visualization to the slide and advances it in beats on the arrow keys. The beat timeline is a function of Slidev’s click count, so stepping backward replays the transition in reverse instead of snapping. Prose sits in a floating card whose copy changes per beat, and a visual can carry over from one slide to the next.

useStage

Everything a stage needs comes from one import:

import { useStage, DUR, stagger, type BeatCopy } from 'slidev-addon-decks/story'

export interface StageOptions<C extends BeatCopy> {
  copy: readonly C[]
  enter?: (tl: gsap.core.Timeline) => void
  beats: (tl: gsap.core.Timeline, beat: (n: number) => void) => void
}
function useStage<C extends BeatCopy>(opts: StageOptions<C>): {
  clicks: Ref<number>
  isActive: Ref<boolean>
  playCount: Ref<number>
  copy: ComputedRef<C>
  beats: number
}

beats comes from opts.copy.length, so a stage’s beat count and its copy array can’t disagree. A guard test, beats.test.ts, checks that value against the clicks: in the deck’s manifest: clicks is the beat count minus one.

Seek or tween

The beat timeline seeks or tweens to the current click on every change. It seeks on first run, on an inactive slide, under reduced motion, or on a jump of more than one beat, and tweens otherwise. An interrupted tween retargets from where it is and catches up within one beat’s duration, so rapid clicks don’t build a backlog.

Entrances

When a stage mounts it builds its entrance timeline, paused. Then:

• Not the real slide view (presenter, overview, print): jump to the end state.
• Slide inactive: hold at zero, so the next entry replays.
• Active but not landing on beat 0, or motion turned down: jump to the end state.
• Otherwise: hold until any view transition lands, then play once.

Durations

Stages use three easings (SETTLE, DRAW, TRACE) and one duration table, DUR, from slidev-addon-decks/story. A guard test fails on a numeric duration literal anywhere else, so timing stays consistent across stages. DUR.card (0.3 s) is the card copy swap; DUR.grow (0.56 s) is a bar or number growing in.