@particle-academy/fancy-slides 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, CSSProperties } from 'react';
-import { f as Slide$1, m as Theme, h as SlideElement, D as Deck, c as DeckOp, e as ShapeKind, j as SlideTransition, g as SlideBackground, k as TextElement, I as ImageElement, S as ShapeElement, i as SlideLayout } from './types-B2ecrEAz.cjs';
-export { C as ChartElement, a as CodeElement, b as DeckActivity, E as ElementBase, d as EmbedElement, T as TableElement, l as TextStyle, n as ThemeColors, o as ThemeFonts, p as TransitionKind } from './types-B2ecrEAz.cjs';
+import { h as Slide$1, o as Theme, j as SlideElement, D as Deck, d as DeckOp, g as ShapeKind, l as SlideTransition, i as SlideBackground, E as ElementAnimation, m as TextElement, I as ImageElement, S as ShapeElement, k as SlideLayout } from './types-9BbelJX1.cjs';
+export { A as AnimationEffect, a as AnimationTrigger, C as ChartElement, b as CodeElement, c as DeckActivity, e as ElementBase, f as EmbedElement, T as TableElement, n as TextStyle, p as ThemeColors, q as ThemeFonts, r as TransitionKind } from './types-9BbelJX1.cjs';
 
 interface SlideProps {
     /** The slide to render. */
@@ -14,6 +14,13 @@ interface SlideProps {
     aspectRatio?: number;
     /** Edit mode flag — passed to element renderers + enables drag/resize affordances. */
     editing?: boolean;
+    /**
+     * Current build step (0..totalSteps). `0` = nothing built (only non-animated
+     * elements visible); each step reveals more animated elements. Omit (or pass
+     * a number ≥ total) to show the fully-built slide. Ignored when `editing` —
+     * the editor always shows every element so authors can position them.
+     */
+    buildStep?: number;
     /** Called when a text element's content is edited (only in editing mode). */
     onElementContentChange?: (elementId: string, content: string) => void;
     /** Called when an element is clicked — host-driven selection. */
@@ -47,7 +54,7 @@ interface SlideProps {
  * Both fire through `onElementMove` / `onElementResize` so the host owns
  * the state — Slide stays a pure renderer.
  */
-declare function Slide({ slide, theme, width, aspectRatio, editing, onElementContentChange, onElementSelect, selectedElementId, onElementMove, onElementResize, renderElement, className, style, }: SlideProps): react_jsx_runtime.JSX.Element;
+declare function Slide({ slide, theme, width, aspectRatio, editing, buildStep, onElementContentChange, onElementSelect, selectedElementId, onElementMove, onElementResize, renderElement, className, style, }: SlideProps): react_jsx_runtime.JSX.Element;
 
 /**
  * What the surrounding <Slide> knows about itself. Exposed to children
@@ -293,6 +300,10 @@ interface ElementInspectorProps {
     onSetTransition?: (transition?: SlideTransition) => void;
     /** Set the slide's background. */
     onSetBackground?: (background?: SlideBackground) => void;
+    /** Set or clear the selected element's entrance build animation. */
+    onSetAnimation?: (animation?: ElementAnimation) => void;
+    /** Set a specific element's build animation by id — used by the slide-level build-order list. */
+    onSetElementAnimation?: (elementId: string, animation?: ElementAnimation) => void;
 }
 /**
  * Right-hand inspector. Tabs split position + style + advanced properties.
@@ -300,7 +311,7 @@ interface ElementInspectorProps {
  * react-fancy `Card`, `Tabs`, `Input`, `Select`, `Slider`, `ColorPicker`,
  * `Action`.
  */
-declare function ElementInspector({ element, onPatch, onDelete, onLockToggle, slide, onSetTransition, onSetBackground }: ElementInspectorProps): react_jsx_runtime.JSX.Element;
+declare function ElementInspector({ element, onPatch, onDelete, onLockToggle, slide, onSetTransition, onSetBackground, onSetAnimation, onSetElementAnimation }: ElementInspectorProps): react_jsx_runtime.JSX.Element;
 
 interface SpeakerNotesProps {
     notes?: string;
@@ -314,6 +325,103 @@ interface SpeakerNotesProps {
  */
 declare function SpeakerNotes({ notes, onChange, placeholder }: SpeakerNotesProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Build (entrance-animation) sequencing — the shared model used by both
+ * `SlideViewer` and `PresenterView` so step-through behaves identically.
+ *
+ * A slide's *builds* are the elements that carry an `animation`. They are
+ * stable-sorted by `(order ?? 0)` then original element array index, then
+ * grouped into *click steps*:
+ *
+ *   - The first build, and every build whose trigger is `"on-click"`, starts
+ *     a NEW step.
+ *   - `"with-prev"` plays simultaneously with the current step's lead.
+ *   - `"after-prev"` plays after a delay equal to the current step's lead
+ *     duration (chained onto its `delay`).
+ *
+ * `buildStep` semantics (used by the viewer/presenter):
+ *   - `0`  → nothing built yet; only non-animated elements are visible.
+ *   - `n`  → the first `n` steps have fired; their elements are visible.
+ *   - `totalSteps` → every build is shown (the fully-built slide).
+ */
+
+/** One element participating in a build, paired with its (defaulted) animation. */
+interface Build {
+    element: SlideElement;
+    animation: ElementAnimation;
+    /** Original index of the element in the slide's `elements` array (tie-breaker). */
+    index: number;
+    /**
+     * For a "by paragraph" text build, which paragraph index (0-based) this
+     * build reveals. Undefined for whole-element builds. The renderer uses this
+     * to show "the first K paragraphs of this element".
+     */
+    paraIndex?: number;
+}
+/**
+ * Split a text element's `content` into paragraphs for a "by paragraph" build.
+ * Splits on `"\n"` and drops a single trailing empty line (so content ending in
+ * a newline doesn't manifest a phantom blank build). Empty interior lines are
+ * preserved — they still consume a click, matching PowerPoint's behaviour.
+ */
+declare function splitParagraphs(content: string): string[];
+/**
+ * Whether an element expands into per-paragraph builds: a text element whose
+ * animation has `byParagraph` and that splits into 2+ paragraphs. With 0/1
+ * paragraphs it behaves like a normal single build.
+ */
+declare function isByParagraph(element: SlideElement, animation: ElementAnimation): boolean;
+/** A click step — the set of builds revealed by a single forward advance. */
+interface BuildStep {
+    /** Builds that reveal on this step (lead first, then with-prev / after-prev). */
+    builds: Build[];
+}
+/**
+ * Collect a slide's builds in resolved order: every element with an
+ * `animation`, stable-sorted by `(order ?? 0)` then array index.
+ */
+declare function collectBuilds(slide: Slide$1 | undefined): Build[];
+/**
+ * Group a slide's builds into click steps. The first build always opens a
+ * step; thereafter an `"on-click"` trigger opens a new step while
+ * `"with-prev"` / `"after-prev"` attach to the current one.
+ */
+declare function buildSteps(slide: Slide$1 | undefined): BuildStep[];
+/** Total number of click steps for a slide (0 when the slide has no builds). */
+declare function totalBuildSteps(slide: Slide$1 | undefined): number;
+/**
+ * Given a slide and a `buildStep` (0..totalSteps), return the set of element
+ * ids that should be VISIBLE. Elements with no animation are always visible;
+ * animated elements become visible once their owning step has fired.
+ */
+declare function visibleElementIds(slide: Slide$1 | undefined, buildStep: number): Set<string>;
+/**
+ * Per-element paragraph reveal state for a "by paragraph" text build at a given
+ * `buildStep`. Keyed by element id:
+ *   - `revealed` — how many paragraphs (0..count) should be shown so far.
+ *   - `firingParaIndex` — the paragraph index revealing on the step that just
+ *     fired (so the renderer plays its entrance effect), or `undefined` when no
+ *     paragraph of this element fires on `buildStep`.
+ * Only elements that actually expand by-paragraph appear in the map.
+ */
+interface ParaReveal {
+    revealed: number;
+    firingParaIndex?: number;
+}
+declare function paragraphReveals(slide: Slide$1 | undefined, buildStep: number): Map<string, ParaReveal>;
+/**
+ * The builds that fire when advancing INTO `buildStep` (1-based). Returns the
+ * lead build first; the viewer uses `with-prev` / `after-prev` to compute each
+ * element's effective `delay`. Empty when `buildStep` is out of range.
+ */
+declare function buildsForStep(slide: Slide$1 | undefined, buildStep: number): Build[];
+/**
+ * Compute the effective entrance delay (ms) for each build within a step,
+ * honouring `with-prev` (0 extra) and `after-prev` (lead duration). The lead
+ * build keeps its own `delay`; followers add to it. Keyed by element id.
+ */
+declare function stepDelays(builds: Build[]): Map<string, number>;
+
 interface TextElementRendererProps {
     element: TextElement;
     theme?: Theme;
@@ -331,6 +439,14 @@ interface TextElementRendererProps {
     selected?: boolean;
     /** Called when the user edits the content (only fires when the textarea is focusable). */
     onContentChange?: (content: string) => void;
+    /**
+     * By-paragraph reveal state, set by `<Slide>` in viewer mode when this text
+     * element has a `byParagraph` animation. When present, the renderer splits
+     * `content` on `"\n"` and shows only the first `revealed` paragraphs,
+     * animating the one at `firingParaIndex`. Ignored in editing mode (the full
+     * text always renders so authors can position/edit it).
+     */
+    paraReveal?: ParaReveal;
 }
 /**
  * Renderer for `text` elements. Three formats:
@@ -344,7 +460,7 @@ interface TextElementRendererProps {
  * In editing mode + when the element is selected, the renderer swaps to a
  * textarea showing the raw source. Edits flow back via `onContentChange`.
  */
-declare function TextElementRenderer({ element, theme, slideWidthPx, editing, selected, onContentChange, }: TextElementRendererProps): react_jsx_runtime.JSX.Element;
+declare function TextElementRenderer({ element, theme, slideWidthPx, editing, selected, onContentChange, paraReveal, }: TextElementRendererProps): react_jsx_runtime.JSX.Element;
 
 interface ImageElementRendererProps {
     element: ImageElement;
@@ -375,8 +491,19 @@ interface SlideKeyboardOptions {
     total: number;
     /** Current slide index. */
     index: number;
-    /** Move to a specific slide. */
+    /** Move to a specific slide. Used by Home/End/1-9 (and by arrows when no `onAdvance`/`onRetreat`). */
     goTo: (index: number) => void;
+    /**
+     * Forward step (→ / Space / PageDown). When provided it OWNS forward nav —
+     * e.g. step through builds, then advance the slide. Falls back to
+     * `goTo(index + 1)` when omitted.
+     */
+    onAdvance?: () => void;
+    /**
+     * Backward step (← / PageUp). When provided it OWNS backward nav. Falls back
+     * to `goTo(index - 1)` when omitted.
+     */
+    onRetreat?: () => void;
     /** Called on Esc — typically exits fullscreen. */
     onExit?: () => void;
     /** Called on `B` — typically blacks/whites out the screen. */
@@ -389,8 +516,8 @@ interface SlideKeyboardOptions {
 /**
  * Standard slideshow keyboard plumbing:
  *
- *   ←   / PageUp     — previous slide
- *   →   / PageDown / Space — next slide
+ *   ←   / PageUp     — retreat (onRetreat, else previous slide)
+ *   →   / PageDown / Space — advance (onAdvance, else next slide)
  *   Home              — first slide
  *   End               — last slide
  *   Esc               — onExit
@@ -398,7 +525,7 @@ interface SlideKeyboardOptions {
  *   F                 — onFullscreen
  *   1..9              — jump to slide N
  */
-declare function useSlideKeyboard({ total, index, goTo, onExit, onBlank, onFullscreen, enabled, }: SlideKeyboardOptions): void;
+declare function useSlideKeyboard({ total, index, goTo, onAdvance, onRetreat, onExit, onBlank, onFullscreen, enabled, }: SlideKeyboardOptions): void;
 
 /**
  * Hook that wraps a controlled deck with a typed mutation API. Every helper
@@ -436,6 +563,8 @@ interface DeckStateApi {
     updateElement: (slideId: string, elementId: string, patch: Partial<SlideElement>) => void;
     moveElement: (slideId: string, elementId: string, x: number, y: number) => void;
     resizeElement: (slideId: string, elementId: string, w: number, h: number) => void;
+    /** Set or clear an element's entrance build animation. Pass `undefined` to clear. */
+    setAnimation: (slideId: string, elementId: string, animation?: ElementAnimation) => void;
     /** Convenience lookups. */
     getSlide: (id: string) => Slide$1 | undefined;
     getElement: (slideId: string, elementId: string) => SlideElement | undefined;
@@ -496,4 +625,4 @@ type ChartKind = "bar" | "line" | "pie" | "area" | "scatter";
 type Option = Record<string, unknown>;
 declare function chartStarterOption(kind: ChartKind): Option;
 
-export { type ChartKind$1 as ChartKind, Deck, DeckEditor, type DeckEditorProps, DeckOp, type DeckStateApi, EditorToolbar, type EditorToolbarProps, ElementInspector, type ElementInspectorProps, ImageElement, ImageElementRenderer, type ImageElementRendererProps, PresenterView, type PresenterViewProps, ShapeElement, ShapeElementRenderer, type ShapeElementRendererProps, ShapeKind, Slide, SlideBackground, type SlideContextValue, Slide$1 as SlideData, SlideElement, type SlideKeyboardOptions, SlideLayout, type SlideProps, SlideRail, type SlideRailProps, SlideThumbnail, type SlideThumbnailProps, SlideTransition, SlideViewer, type SlideViewerProps, SpeakerNotes, type SpeakerNotesProps, TextElement, TextElementRenderer, type TextElementRendererProps, Theme, type UseDeckStateOptions, builtinThemes, chartStarterOption, darkTheme, deckId, defaultTheme, defineTheme, elementId, nextId, reduce as reduceDeck, resolveTheme, slideId, useDeckState, useIsDarkSlide, useSlideContext, useSlideKeyboard, useSlideTheme, vividTheme };
+export { type Build, type BuildStep, type ChartKind$1 as ChartKind, Deck, DeckEditor, type DeckEditorProps, DeckOp, type DeckStateApi, EditorToolbar, type EditorToolbarProps, ElementAnimation, ElementInspector, type ElementInspectorProps, ImageElement, ImageElementRenderer, type ImageElementRendererProps, type ParaReveal, PresenterView, type PresenterViewProps, ShapeElement, ShapeElementRenderer, type ShapeElementRendererProps, ShapeKind, Slide, SlideBackground, type SlideContextValue, Slide$1 as SlideData, SlideElement, type SlideKeyboardOptions, SlideLayout, type SlideProps, SlideRail, type SlideRailProps, SlideThumbnail, type SlideThumbnailProps, SlideTransition, SlideViewer, type SlideViewerProps, SpeakerNotes, type SpeakerNotesProps, TextElement, TextElementRenderer, type TextElementRendererProps, Theme, type UseDeckStateOptions, buildSteps, buildsForStep, builtinThemes, chartStarterOption, collectBuilds, darkTheme, deckId, defaultTheme, defineTheme, elementId, isByParagraph, nextId, paragraphReveals, reduce as reduceDeck, resolveTheme, slideId, splitParagraphs, stepDelays, totalBuildSteps, useDeckState, useIsDarkSlide, useSlideContext, useSlideKeyboard, useSlideTheme, visibleElementIds, vividTheme };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, CSSProperties } from 'react';
-import { f as Slide$1, m as Theme, h as SlideElement, D as Deck, c as DeckOp, e as ShapeKind, j as SlideTransition, g as SlideBackground, k as TextElement, I as ImageElement, S as ShapeElement, i as SlideLayout } from './types-B2ecrEAz.js';
-export { C as ChartElement, a as CodeElement, b as DeckActivity, E as ElementBase, d as EmbedElement, T as TableElement, l as TextStyle, n as ThemeColors, o as ThemeFonts, p as TransitionKind } from './types-B2ecrEAz.js';
+import { h as Slide$1, o as Theme, j as SlideElement, D as Deck, d as DeckOp, g as ShapeKind, l as SlideTransition, i as SlideBackground, E as ElementAnimation, m as TextElement, I as ImageElement, S as ShapeElement, k as SlideLayout } from './types-9BbelJX1.js';
+export { A as AnimationEffect, a as AnimationTrigger, C as ChartElement, b as CodeElement, c as DeckActivity, e as ElementBase, f as EmbedElement, T as TableElement, n as TextStyle, p as ThemeColors, q as ThemeFonts, r as TransitionKind } from './types-9BbelJX1.js';
 
 interface SlideProps {
     /** The slide to render. */
@@ -14,6 +14,13 @@ interface SlideProps {
     aspectRatio?: number;
     /** Edit mode flag — passed to element renderers + enables drag/resize affordances. */
     editing?: boolean;
+    /**
+     * Current build step (0..totalSteps). `0` = nothing built (only non-animated
+     * elements visible); each step reveals more animated elements. Omit (or pass
+     * a number ≥ total) to show the fully-built slide. Ignored when `editing` —
+     * the editor always shows every element so authors can position them.
+     */
+    buildStep?: number;
     /** Called when a text element's content is edited (only in editing mode). */
     onElementContentChange?: (elementId: string, content: string) => void;
     /** Called when an element is clicked — host-driven selection. */
@@ -47,7 +54,7 @@ interface SlideProps {
  * Both fire through `onElementMove` / `onElementResize` so the host owns
  * the state — Slide stays a pure renderer.
  */
-declare function Slide({ slide, theme, width, aspectRatio, editing, onElementContentChange, onElementSelect, selectedElementId, onElementMove, onElementResize, renderElement, className, style, }: SlideProps): react_jsx_runtime.JSX.Element;
+declare function Slide({ slide, theme, width, aspectRatio, editing, buildStep, onElementContentChange, onElementSelect, selectedElementId, onElementMove, onElementResize, renderElement, className, style, }: SlideProps): react_jsx_runtime.JSX.Element;
 
 /**
  * What the surrounding <Slide> knows about itself. Exposed to children
@@ -293,6 +300,10 @@ interface ElementInspectorProps {
     onSetTransition?: (transition?: SlideTransition) => void;
     /** Set the slide's background. */
     onSetBackground?: (background?: SlideBackground) => void;
+    /** Set or clear the selected element's entrance build animation. */
+    onSetAnimation?: (animation?: ElementAnimation) => void;
+    /** Set a specific element's build animation by id — used by the slide-level build-order list. */
+    onSetElementAnimation?: (elementId: string, animation?: ElementAnimation) => void;
 }
 /**
  * Right-hand inspector. Tabs split position + style + advanced properties.
@@ -300,7 +311,7 @@ interface ElementInspectorProps {
  * react-fancy `Card`, `Tabs`, `Input`, `Select`, `Slider`, `ColorPicker`,
  * `Action`.
  */
-declare function ElementInspector({ element, onPatch, onDelete, onLockToggle, slide, onSetTransition, onSetBackground }: ElementInspectorProps): react_jsx_runtime.JSX.Element;
+declare function ElementInspector({ element, onPatch, onDelete, onLockToggle, slide, onSetTransition, onSetBackground, onSetAnimation, onSetElementAnimation }: ElementInspectorProps): react_jsx_runtime.JSX.Element;
 
 interface SpeakerNotesProps {
     notes?: string;
@@ -314,6 +325,103 @@ interface SpeakerNotesProps {
  */
 declare function SpeakerNotes({ notes, onChange, placeholder }: SpeakerNotesProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Build (entrance-animation) sequencing — the shared model used by both
+ * `SlideViewer` and `PresenterView` so step-through behaves identically.
+ *
+ * A slide's *builds* are the elements that carry an `animation`. They are
+ * stable-sorted by `(order ?? 0)` then original element array index, then
+ * grouped into *click steps*:
+ *
+ *   - The first build, and every build whose trigger is `"on-click"`, starts
+ *     a NEW step.
+ *   - `"with-prev"` plays simultaneously with the current step's lead.
+ *   - `"after-prev"` plays after a delay equal to the current step's lead
+ *     duration (chained onto its `delay`).
+ *
+ * `buildStep` semantics (used by the viewer/presenter):
+ *   - `0`  → nothing built yet; only non-animated elements are visible.
+ *   - `n`  → the first `n` steps have fired; their elements are visible.
+ *   - `totalSteps` → every build is shown (the fully-built slide).
+ */
+
+/** One element participating in a build, paired with its (defaulted) animation. */
+interface Build {
+    element: SlideElement;
+    animation: ElementAnimation;
+    /** Original index of the element in the slide's `elements` array (tie-breaker). */
+    index: number;
+    /**
+     * For a "by paragraph" text build, which paragraph index (0-based) this
+     * build reveals. Undefined for whole-element builds. The renderer uses this
+     * to show "the first K paragraphs of this element".
+     */
+    paraIndex?: number;
+}
+/**
+ * Split a text element's `content` into paragraphs for a "by paragraph" build.
+ * Splits on `"\n"` and drops a single trailing empty line (so content ending in
+ * a newline doesn't manifest a phantom blank build). Empty interior lines are
+ * preserved — they still consume a click, matching PowerPoint's behaviour.
+ */
+declare function splitParagraphs(content: string): string[];
+/**
+ * Whether an element expands into per-paragraph builds: a text element whose
+ * animation has `byParagraph` and that splits into 2+ paragraphs. With 0/1
+ * paragraphs it behaves like a normal single build.
+ */
+declare function isByParagraph(element: SlideElement, animation: ElementAnimation): boolean;
+/** A click step — the set of builds revealed by a single forward advance. */
+interface BuildStep {
+    /** Builds that reveal on this step (lead first, then with-prev / after-prev). */
+    builds: Build[];
+}
+/**
+ * Collect a slide's builds in resolved order: every element with an
+ * `animation`, stable-sorted by `(order ?? 0)` then array index.
+ */
+declare function collectBuilds(slide: Slide$1 | undefined): Build[];
+/**
+ * Group a slide's builds into click steps. The first build always opens a
+ * step; thereafter an `"on-click"` trigger opens a new step while
+ * `"with-prev"` / `"after-prev"` attach to the current one.
+ */
+declare function buildSteps(slide: Slide$1 | undefined): BuildStep[];
+/** Total number of click steps for a slide (0 when the slide has no builds). */
+declare function totalBuildSteps(slide: Slide$1 | undefined): number;
+/**
+ * Given a slide and a `buildStep` (0..totalSteps), return the set of element
+ * ids that should be VISIBLE. Elements with no animation are always visible;
+ * animated elements become visible once their owning step has fired.
+ */
+declare function visibleElementIds(slide: Slide$1 | undefined, buildStep: number): Set<string>;
+/**
+ * Per-element paragraph reveal state for a "by paragraph" text build at a given
+ * `buildStep`. Keyed by element id:
+ *   - `revealed` — how many paragraphs (0..count) should be shown so far.
+ *   - `firingParaIndex` — the paragraph index revealing on the step that just
+ *     fired (so the renderer plays its entrance effect), or `undefined` when no
+ *     paragraph of this element fires on `buildStep`.
+ * Only elements that actually expand by-paragraph appear in the map.
+ */
+interface ParaReveal {
+    revealed: number;
+    firingParaIndex?: number;
+}
+declare function paragraphReveals(slide: Slide$1 | undefined, buildStep: number): Map<string, ParaReveal>;
+/**
+ * The builds that fire when advancing INTO `buildStep` (1-based). Returns the
+ * lead build first; the viewer uses `with-prev` / `after-prev` to compute each
+ * element's effective `delay`. Empty when `buildStep` is out of range.
+ */
+declare function buildsForStep(slide: Slide$1 | undefined, buildStep: number): Build[];
+/**
+ * Compute the effective entrance delay (ms) for each build within a step,
+ * honouring `with-prev` (0 extra) and `after-prev` (lead duration). The lead
+ * build keeps its own `delay`; followers add to it. Keyed by element id.
+ */
+declare function stepDelays(builds: Build[]): Map<string, number>;
+
 interface TextElementRendererProps {
     element: TextElement;
     theme?: Theme;
@@ -331,6 +439,14 @@ interface TextElementRendererProps {
     selected?: boolean;
     /** Called when the user edits the content (only fires when the textarea is focusable). */
     onContentChange?: (content: string) => void;
+    /**
+     * By-paragraph reveal state, set by `<Slide>` in viewer mode when this text
+     * element has a `byParagraph` animation. When present, the renderer splits
+     * `content` on `"\n"` and shows only the first `revealed` paragraphs,
+     * animating the one at `firingParaIndex`. Ignored in editing mode (the full
+     * text always renders so authors can position/edit it).
+     */
+    paraReveal?: ParaReveal;
 }
 /**
  * Renderer for `text` elements. Three formats:
@@ -344,7 +460,7 @@ interface TextElementRendererProps {
  * In editing mode + when the element is selected, the renderer swaps to a
  * textarea showing the raw source. Edits flow back via `onContentChange`.
  */
-declare function TextElementRenderer({ element, theme, slideWidthPx, editing, selected, onContentChange, }: TextElementRendererProps): react_jsx_runtime.JSX.Element;
+declare function TextElementRenderer({ element, theme, slideWidthPx, editing, selected, onContentChange, paraReveal, }: TextElementRendererProps): react_jsx_runtime.JSX.Element;
 
 interface ImageElementRendererProps {
     element: ImageElement;
@@ -375,8 +491,19 @@ interface SlideKeyboardOptions {
     total: number;
     /** Current slide index. */
     index: number;
-    /** Move to a specific slide. */
+    /** Move to a specific slide. Used by Home/End/1-9 (and by arrows when no `onAdvance`/`onRetreat`). */
     goTo: (index: number) => void;
+    /**
+     * Forward step (→ / Space / PageDown). When provided it OWNS forward nav —
+     * e.g. step through builds, then advance the slide. Falls back to
+     * `goTo(index + 1)` when omitted.
+     */
+    onAdvance?: () => void;
+    /**
+     * Backward step (← / PageUp). When provided it OWNS backward nav. Falls back
+     * to `goTo(index - 1)` when omitted.
+     */
+    onRetreat?: () => void;
     /** Called on Esc — typically exits fullscreen. */
     onExit?: () => void;
     /** Called on `B` — typically blacks/whites out the screen. */
@@ -389,8 +516,8 @@ interface SlideKeyboardOptions {
 /**
  * Standard slideshow keyboard plumbing:
  *
- *   ←   / PageUp     — previous slide
- *   →   / PageDown / Space — next slide
+ *   ←   / PageUp     — retreat (onRetreat, else previous slide)
+ *   →   / PageDown / Space — advance (onAdvance, else next slide)
  *   Home              — first slide
  *   End               — last slide
  *   Esc               — onExit
@@ -398,7 +525,7 @@ interface SlideKeyboardOptions {
  *   F                 — onFullscreen
  *   1..9              — jump to slide N
  */
-declare function useSlideKeyboard({ total, index, goTo, onExit, onBlank, onFullscreen, enabled, }: SlideKeyboardOptions): void;
+declare function useSlideKeyboard({ total, index, goTo, onAdvance, onRetreat, onExit, onBlank, onFullscreen, enabled, }: SlideKeyboardOptions): void;
 
 /**
  * Hook that wraps a controlled deck with a typed mutation API. Every helper
@@ -436,6 +563,8 @@ interface DeckStateApi {
     updateElement: (slideId: string, elementId: string, patch: Partial<SlideElement>) => void;
     moveElement: (slideId: string, elementId: string, x: number, y: number) => void;
     resizeElement: (slideId: string, elementId: string, w: number, h: number) => void;
+    /** Set or clear an element's entrance build animation. Pass `undefined` to clear. */
+    setAnimation: (slideId: string, elementId: string, animation?: ElementAnimation) => void;
     /** Convenience lookups. */
     getSlide: (id: string) => Slide$1 | undefined;
     getElement: (slideId: string, elementId: string) => SlideElement | undefined;
@@ -496,4 +625,4 @@ type ChartKind = "bar" | "line" | "pie" | "area" | "scatter";
 type Option = Record<string, unknown>;
 declare function chartStarterOption(kind: ChartKind): Option;
 
-export { type ChartKind$1 as ChartKind, Deck, DeckEditor, type DeckEditorProps, DeckOp, type DeckStateApi, EditorToolbar, type EditorToolbarProps, ElementInspector, type ElementInspectorProps, ImageElement, ImageElementRenderer, type ImageElementRendererProps, PresenterView, type PresenterViewProps, ShapeElement, ShapeElementRenderer, type ShapeElementRendererProps, ShapeKind, Slide, SlideBackground, type SlideContextValue, Slide$1 as SlideData, SlideElement, type SlideKeyboardOptions, SlideLayout, type SlideProps, SlideRail, type SlideRailProps, SlideThumbnail, type SlideThumbnailProps, SlideTransition, SlideViewer, type SlideViewerProps, SpeakerNotes, type SpeakerNotesProps, TextElement, TextElementRenderer, type TextElementRendererProps, Theme, type UseDeckStateOptions, builtinThemes, chartStarterOption, darkTheme, deckId, defaultTheme, defineTheme, elementId, nextId, reduce as reduceDeck, resolveTheme, slideId, useDeckState, useIsDarkSlide, useSlideContext, useSlideKeyboard, useSlideTheme, vividTheme };
+export { type Build, type BuildStep, type ChartKind$1 as ChartKind, Deck, DeckEditor, type DeckEditorProps, DeckOp, type DeckStateApi, EditorToolbar, type EditorToolbarProps, ElementAnimation, ElementInspector, type ElementInspectorProps, ImageElement, ImageElementRenderer, type ImageElementRendererProps, type ParaReveal, PresenterView, type PresenterViewProps, ShapeElement, ShapeElementRenderer, type ShapeElementRendererProps, ShapeKind, Slide, SlideBackground, type SlideContextValue, Slide$1 as SlideData, SlideElement, type SlideKeyboardOptions, SlideLayout, type SlideProps, SlideRail, type SlideRailProps, SlideThumbnail, type SlideThumbnailProps, SlideTransition, SlideViewer, type SlideViewerProps, SpeakerNotes, type SpeakerNotesProps, TextElement, TextElementRenderer, type TextElementRendererProps, Theme, type UseDeckStateOptions, buildSteps, buildsForStep, builtinThemes, chartStarterOption, collectBuilds, darkTheme, deckId, defaultTheme, defineTheme, elementId, isByParagraph, nextId, paragraphReveals, reduce as reduceDeck, resolveTheme, slideId, splitParagraphs, stepDelays, totalBuildSteps, useDeckState, useIsDarkSlide, useSlideContext, useSlideKeyboard, useSlideTheme, visibleElementIds, vividTheme };