lumina-slides 8.9.4 → 9.0.0

package/src/core/types.ts

@@ -0,0 +1,1611 @@
+/**
+ * LUMINA ENGINE TYPES
+ * Centralized type definitions for strict contract enforcement.
+ */
+
+// --- Slide & Deck Definitions ---
+
+/**
+ * Supported slide layout types.
+ * Each type corresponds to a registered Vue component (e.g. 'statement' -> LayoutStatement).
+ */
+export type SlideType = 'statement' | 'half' | 'features' | 'timeline' | 'steps' | 'flex' | 'chart' | 'diagram' | 'free' | (string & {});
+
+/**
+ * Structure for items in the 'timeline' layout.
+ */
+export interface TimelineItem {
+    /** Optional id for element control (engine.element(id)). */
+    id?: string;
+    date: string;
+    title: string;
+    t?: string;        // Alias for title
+    description: string;
+    desc?: string;     // Alias for description
+    icon?: string;
+}
+
+/**
+ * Structure for items in the 'steps' layout.
+ */
+export interface StepItem {
+    /** Optional id for element control (engine.element(id)). */
+    id?: string;
+    step: string; // e.g., "01"
+    title: string;
+    description?: string;
+    icon?: string;
+}
+
+// --- Chart Layout Types ---
+
+/**
+ * Supported chart types.
+ */
+export type ChartType = 'bar' | 'line' | 'pie' | 'doughnut';
+
+/**
+ * A single dataset for chart visualization.
+ */
+export interface ChartDataset {
+    /** Label for this dataset (appears in legend). */
+    label: string;
+    /** Numeric values corresponding to each label. */
+    values: number[];
+    /** 
+     * Color for this dataset. Supports Lumina tokens:
+     * - 'c:p' → primary color
+     * - 'c:s' → secondary color  
+     * - 'c:m' → muted color
+     * - Or any valid CSS color (hex, rgb, etc.)
+     */
+    color?: string;
+}
+
+/**
+ * Data structure for chart visualization.
+ */
+export interface ChartData {
+    /** Labels for the x-axis or pie segments. */
+    labels: string[];
+    /** Array of datasets to display. */
+    datasets: ChartDataset[];
+}
+
+// --- Flex Layout Types ---
+
+/**
+ * Size tokens for flex element sizing.
+ * Determines how much horizontal/vertical space an element occupies.
+ */
+export type FlexSize = 'auto' | 'quarter' | 'third' | 'half' | 'two-thirds' | 'three-quarters' | 'full';
+
+/**
+ * Spacing tokens used for gaps and padding.
+ */
+export type SpacingToken = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+
+/**
+ * Vertical alignment options.
+ */
+export type VAlign = 'top' | 'center' | 'bottom';
+
+/**
+ * Horizontal alignment options.
+ */
+export type HAlign = 'left' | 'center' | 'right';
+
+/**
+ * Text alignment options.
+ */
+export type TextAlign = 'left' | 'center' | 'right';
+
+/**
+ * Title element - Large heading text.
+ */
+export interface FlexElementTitle {
+    type: 'title';
+    /** Optional id for element control (engine.element(id)). */
+    id?: string;
+    text: string;
+    /** Heading size. Default: 'xl' */
+    size?: 'lg' | 'xl' | '2xl' | '3xl';
+    /** Text alignment. Default: 'left' */
+    align?: TextAlign;
+}
+
+/**
+ * Text element - Body paragraph text.
+ */
+export interface FlexElementText {
+    type: 'text';
+    /** Optional id for element control (engine.element(id)). */
+    id?: string;
+    text: string;
+    /** Text alignment. Default: 'left' */
+    align?: TextAlign;
+    /** Muted/subtle appearance. Default: false */
+    muted?: boolean;
+}
+
+/**
+ * Bullets element - Unordered list.
+ */
+export interface FlexElementBullets {
+    type: 'bullets';
+    /** Optional id for element control (engine.element(id)). */
+    id?: string;
+    items: string[];
+}
+
+/**
+ * Ordered element - Numbered list.
+ */
+export interface FlexElementOrdered {
+    type: 'ordered';
+    /** Optional id for element control (engine.element(id)). */
+    id?: string;
+    items: string[];
+}
+
+/**
+ * Image element - Visual media.
+ */
+export interface FlexElementImage {
+    type: 'image';
+    /** Optional id for element control (engine.element(id)). */
+    id?: string;
+    src: string;
+    alt?: string;
+    /** Fill entire container edge-to-edge. Default: true */
+    fill?: boolean;
+    /** Object-fit mode when fill is true. Default: 'cover' */
+    fit?: 'cover' | 'contain';
+    /** Border radius. Default: 'none' when fill, 'lg' otherwise */
+    rounded?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
+    /** Link URL when image is clicked. */
+    href?: string;
+    /** Link target. Default: '_blank' */
+    target?: '_blank' | '_self';
+    /** Custom CSS class */
+    class?: string;
+}
+
+/**
+ * Video element - Visual media.
+ */
+export interface FlexElementVideo extends VideoProperties {
+    type: 'video';
+    /** Optional id for element control (engine.element(id)). */
+    id?: string;
+    /** Fill entire container edge-to-edge. Default: true */
+    fill?: boolean;
+    /** Object-fit mode when fill is true. Default: 'cover' */
+    fit?: 'cover' | 'contain';
+    /** Border radius. Default: 'none' when fill, 'lg' otherwise */
+    rounded?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
+    /** Custom CSS class */
+    class?: string;
+}
+
+/**
+ * Button element - Call-to-action button.
+ */
+export interface FlexElementButton {
+    type: 'button';
+    /** Optional id for element control (engine.element(id)). */
+    id?: string;
+    label: string;
+    /** Action identifier emitted on click (for custom event handling). */
+    action?: string;
+    /** Type of action to perform. Default: 'event' */
+    actionType?: 'event' | 'url' | 'slide' | 'download';
+    /** URL to navigate to when actionType is 'url'. */
+    href?: string;
+    /** Slide index to navigate to when actionType is 'slide'. */
+    gotoSlide?: number;
+    /** Link target for URL actions. Default: '_blank' */
+    target?: '_blank' | '_self';
+    /** Visual variant. Default: 'primary' */
+    variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
+    /** Full width button. Default: false */
+    fullWidth?: boolean;
+}
+
+/**
+ * Timeline element - Embedded timeline with events.
+ */
+export interface FlexElementTimeline {
+    type: 'timeline';
+    /** Optional id for element control (engine.element(id)). */
+    id?: string;
+    items: TimelineItem[];
+    /** Compact display mode. Default: false */
+    compact?: boolean;
+}
+
+/**
+ * Stepper element - Embedded step-by-step process.
+ */
+export interface FlexElementStepper {
+    type: 'stepper';
+    /** Optional id for element control (engine.element(id)). */
+    id?: string;
+    items: StepItem[];
+    /** Compact display mode. Default: false */
+    compact?: boolean;
+}
+
+/**
+ * Spacer element - Adds visual spacing.
+ */
+export interface FlexElementSpacer {
+    type: 'spacer';
+    /** Optional id for element control (engine.element(id)). */
+    id?: string;
+    /** Size of the space. Default: 'md' */
+    size?: SpacingToken;
+}
+
+/**
+ * Content container - Groups child elements vertically with alignment control.
+ */
+export interface FlexElementContent {
+    type: 'content';
+    /** Optional id for element control (engine.element(id)). */
+    id?: string;
+    elements: FlexChildElement[];
+    /** Vertical alignment of content. Default: 'center' */
+    valign?: VAlign;
+    /** Horizontal alignment of content. Default: 'left' */
+    halign?: HAlign;
+    /** Gap between child elements. Default: 'md' */
+    gap?: SpacingToken;
+    /** Internal padding. Default: 'lg' */
+    padding?: SpacingToken;
+}
+
+/**
+ * Child elements that can appear inside a content container.
+ */
+export type FlexChildElement =
+    | FlexElementTitle
+    | FlexElementText
+    | FlexElementBullets
+    | FlexElementOrdered
+    | FlexElementButton
+    | FlexElementTimeline
+    | FlexElementStepper
+    | FlexElementSpacer;
+
+/**
+ * Top-level flex elements that can have size.
+ */
+export type FlexElement =
+    | (FlexElementImage & { size?: FlexSize })
+    | (FlexElementVideo & { size?: FlexSize })
+    | (FlexElementContent & { size?: FlexSize })
+    | (FlexElementTitle & { size?: FlexSize })
+    | (FlexElementText & { size?: FlexSize })
+    | (FlexElementBullets & { size?: FlexSize })
+    | (FlexElementOrdered & { size?: FlexSize })
+    | (FlexElementButton & { size?: FlexSize })
+    | (FlexElementTimeline & { size?: FlexSize })
+    | (FlexElementStepper & { size?: FlexSize });
+
+/**
+ * Metadata for individual slides.
+ * Can contain arbitrary data used by custom layouts.
+ */
+export interface SlideMeta {
+    orbColor?: string;
+    orbPos?: { top: string; left: string };
+    [key: string]: any;
+}
+
+/**
+ * State for a single controllable element (visibility, opacity, transform, etc.).
+ * Applied by LuminaElement / useElementState; written by `engine.element(id).show()`, `.hide()`, `.opacity()`, etc.
+ *
+ * Use `meta.initialElementState` in the deck to start with elements hidden and reveal them
+ * programmatically (e.g. presentation starts "empty", then `engine.element('s0-title').show()`).
+ *
+ * @example
+ * // In deck JSON: start slide 0 title and subtitle hidden; reveal via API.
+ * { "meta": { "title": "Demo", "initialElementState": { "s0-title": { "visible": false }, "s0-subtitle": { "visible": false } } }, "slides": [...] }
+ *
+ * @see ElementController
+ * @see DeckMeta.initialElementState
+ */
+export interface ElementState {
+    /** If false, the element is hidden (v-show). Omit or true = visible. */
+    visible?: boolean;
+    /** Opacity from 0 to 1. Applied as inline style. */
+    opacity?: number;
+    /** CSS transform (e.g. "scale(1.2)", "translateX(10px)"). */
+    transform?: string;
+    /** Extra CSS class names (space-separated). Merged with component classes. */
+    class?: string;
+    /** Inline style overrides. Merged with opacity/transform when those are set. */
+    style?: Record<string, string | number>;
+}
+
+/**
+ * Options for `ElementController.animate()` and `animateAsync()`. GSAP-compatible property names and values.
+ *
+ * @description
+ * `to` is required; `from` optional (animates from current state if omitted). `duration` and `ease` default
+ * to options.animation.elementDuration and elementEase (or resolveTransitionConfig). Element must be mounted (on the active slide).
+ *
+ * @example
+ * engine.element('s0-title').animate({ to: { opacity: 1, y: 0 }, duration: 0.6, ease: 'power2.out' });
+ * engine.element('s1-features-0').animate({ from: { scale: 0 }, to: { scale: 1 }, duration: 0.5 });
+ * await engine.element('s0-tag').animateAsync({ to: { opacity: 1 }, onComplete: () => console.log('done') });
+ *
+ * @see ElementController.animate
+ * @see ElementController.animateAsync
+ */
+export interface AnimateOptions {
+    /** Preset name (fadeUp, scaleIn, slideLeft, etc.). Expands to from/to/ease; explicit from/to/ease override. */
+    preset?: string;
+    /** Motion name from meta.motions (future). Ignored if preset is set. */
+    motion?: string;
+    /** Starting values (GSAP from). If omitted, animates from current state or from preset. */
+    from?: Record<string, string | number>;
+    /** Target values (GSAP to). Optional when preset is set; preset provides to. */
+    to?: Record<string, string | number>;
+    /** Duration in seconds. Default from config or 0.5. */
+    duration?: number;
+    /** GSAP easing. Default from config or 'power2.out'. Preset provides default. */
+    ease?: string;
+    /** Callback when the animation completes. Also used by animateAsync. */
+    onComplete?: () => void;
+}
+
+/**
+ * Options for `Lumina.revealInSequence`. Controls staggered reveal of slide elements.
+ *
+ * @description
+ * When a value is omitted, it falls back to resolveTransitionConfig (revealDelayMs, revealDuration, revealEase).
+ * hideFirst: true (default) hides all elements before the sequence. only/exclude filter which ids are revealed.
+ *
+ * @example
+ * engine.revealInSequence(0, { delayMs: 500, animate: true });
+ * await engine.revealInSequence(undefined, { only: ['s1-title', 's1-subtitle'], hideFirst: true });
+ * engine.on('slideChange', e => engine.revealInSequence(e.index, { delayMs: 400, duration: 0.5 }));
+ *
+ * @see Lumina.revealInSequence
+ * @see resolveTransitionConfig
+ */
+export interface RevealInSequenceOptions {
+    /** Delay in ms between each element. Default: 400 */
+    delayMs?: number;
+    /** Stagger mode: sequential, center-out, ends-in, wave, random. Default: sequential. */
+    staggerMode?: 'sequential' | 'center-out' | 'ends-in' | 'wave' | 'random';
+    /** For staggerMode 'random', seed for deterministic order. Omit for arbitrary. */
+    randomSeed?: number;
+    /** Preset for each element's animation (fadeUp, scaleIn, etc.). Overridden by from/to/ease. */
+    preset?: string;
+    /** Motion from meta.motions (future). */
+    motion?: string;
+    /** Whether to animate each element on reveal. Default: true */
+    animate?: boolean;
+    /** GSAP from vars. Default: `{ opacity: 0, y: 16 }` or from preset. */
+    from?: Record<string, string | number>;
+    /** GSAP to vars. Default: `{ opacity: 1, y: 0 }` or from preset. */
+    to?: Record<string, string | number>;
+    /** Animation duration in seconds. Default: 0.45 */
+    duration?: number;
+    /** GSAP ease. Default: `'power2.out'` */
+    ease?: string;
+    /** If true, hide all elements before starting the sequence. Default: true */
+    hideFirst?: boolean;
+    /** Only reveal these element ids (subset). Order follows slide elements. */
+    only?: string[];
+    /** Exclude these element ids from the sequence. */
+    exclude?: string[];
+}
+
+/**
+ * State at a keyframe for timeline-driven animation. Used in `slide.timelineTracks[id]` and
+ * `element(id).animateToProgress(progress, keyframes)`. Keys are progress strings 0–1 (e.g. "0", "0.25", "1").
+ *
+ * @description
+ * Remotion-style: progress 0–1 drives element state. Interpolation is linear between keyframes.
+ * `x`, `y`, `scale` are mapped to a CSS transform. `visible: false` hides the element.
+ *
+ * @example
+ * { "0": { opacity: 0, y: 20 }, "0.3": { opacity: 1, y: 0 }, "1": { opacity: 1 } }
+ *
+ * @see TimelineTracks
+ * @see Lumina.seekTo
+ * @see ElementController.animateToProgress
+ */
+export type TimelineKeyframeState = Partial<{
+  opacity: number;
+  x: number;
+  y: number;
+  scale: number;
+  rotate: number;
+  visible: boolean;
+}>;
+
+/** Keyframes for one element: progress string -> state. */
+export type TimelineKeyframes = Record<string, TimelineKeyframeState>;
+
+/** Per-element timeline tracks. Keys = element ids. Use in `slide.timelineTracks`. */
+export type TimelineTracks = Record<string, TimelineKeyframes>;
+
+/**
+ * Fluent API to control one slide element in real time. Returned by `engine.element(id)`
+ * and `engine.element(slideIndex, path)`. All methods return `this` for chaining.
+ *
+ * Use for: starting with an empty slide and revealing items in order, hiding highlights,
+ * animating entrances on demand, or syncing with voice/agent.
+ *
+ * @example
+ * // Reveal sequence (after loading a deck with initialElementState hiding s0-tag, s0-title, s0-subtitle)
+ * engine.element(0, 'tag').show();
+ * await delay(500);
+ * engine.element(0, 'title').show().animate({ from: { y: 20, opacity: 0 }, to: { y: 0, opacity: 1 }, duration: 0.5 });
+ * engine.element(0, 'subtitle').show();
+ *
+ * @see Lumina.element
+ * @see Lumina.elements
+ * @see ElementState
+ * @see AnimateOptions
+ */
+export interface ElementController {
+    /** Set visible = true. Use after starting with `initialElementState` { visible: false }. */
+    show(): ElementController;
+    /** Set visible = false. Element stays in DOM but is not displayed. */
+    hide(): ElementController;
+    /** Toggle visible. If `force` is given (true/false), set to that value. */
+    toggle(force?: boolean): ElementController;
+    /** Set opacity 0–1. Updates store; LuminaElement applies it. */
+    opacity(value: number): ElementController;
+    /** Set CSS transform string. */
+    transform(value: string): ElementController;
+    /** Merge props into element's style. Merged with existing style in the store. */
+    css(style: Record<string, string | number>): ElementController;
+    /** Append a CSS class to the element's state. */
+    addClass(className: string): ElementController;
+    /** Remove a CSS class from the element's state. */
+    removeClass(className: string): ElementController;
+    /** Run a GSAP animation on the DOM node. Element must be mounted (e.g. on that slide). */
+    animate(options: AnimateOptions): ElementController;
+    /** Like animate but returns a Promise that resolves when the animation completes. */
+    animateAsync(options: AnimateOptions): Promise<void>;
+    /**
+     * Set element state from a progress 0–1 by interpolating between keyframes. Remotion-style scrub.
+     * Use with `engine.seekTo(progress)` when the slide has `slide.timeline`.
+     *
+     * @param progress - 0–1. Interpolates between keyframes; keys are parseable numbers (e.g. "0", "0.3", "1").
+     * @param keyframes - Record of "progress" -> { opacity?, x?, y?, scale?, visible? }.
+     */
+    animateToProgress(progress: number, keyframes: TimelineKeyframes): ElementController;
+}
+
+/**
+ * Base properties shared by all slides.
+ */
+interface SlideBase {
+    /** Unique ID for keying loop optimization (optional). */
+    id?: string;
+    /**
+     * Map of path keys to element ids. Use dot-notation for nested paths.
+     * Examples: { tag: "intro-tag" }, { "features.0": "hero-feature" }, { "elements.0.elements.1": "cta-btn" }.
+     * Overrides the default s{N}-{path} id when the target object has no explicit `id`.
+     */
+    ids?: Record<string, string>;
+    /** Slide-specific metadata. */
+    meta?: SlideMeta;
+    /** Sizing mode: 'viewport' (100vh) or 'container' (100%). Default: 'viewport' */
+    sizing?: 'viewport' | 'container';
+    /**
+     * Timeline tracks per element (Remotion-style): id -> { "0": { opacity, y, ... }, "0.3": { ... }, "1": { ... } }.
+     * Use with `engine.seekTo(progress)` and `engine.playTimeline()`. Do not confuse with the "timeline" layout's `timeline: TimelineItem[]`.
+     */
+    timelineTracks?: TimelineTracks;
+    /** Speaker notes for this slide (supports basic markdown). */
+    notes?: string;
+    /** Background image or video. */
+    background?: string | VideoProperties;
+    /** Opacity of the background (0-1). Default: 1 (or 0.2 for default dark overlay) */
+    backgroundOpacity?: number;
+    /** Optional custom CSS class for the slide content container. */
+    class?: string;
+}
+
+/**
+ * Common properties for video elements.
+ */
+export interface VideoProperties {
+    type: 'video';
+    src: string;
+    poster?: string;
+    /** Default: true for backgrounds, false for elements */
+    autoplay?: boolean;
+    /** Default: true for backgrounds, false for elements */
+    loop?: boolean;
+    /** Default: true for backgrounds, false for elements */
+    muted?: boolean;
+    /** Default: false */
+    controls?: boolean;
+    /** Custom CSS class */
+    className?: string;
+}
+
+/**
+ * Slide: Statement Layout
+ * A simple, high-impact text layout.
+ * @example
+ * ```json
+ * {
+ *   "type": "statement",
+ *   "meta": { "orbColor": "#3b82f6" },
+ *   "tag": "Declarative Engine",
+ *   "title": "Lumina V8",
+ *   "subtitle": "A highly modular, performance-first presentation engine."
+ * }
+ * ```
+ */
+export interface SlideStatement extends SlideBase {
+    type: 'statement';
+    tag?: string;
+    title: string;
+    subtitle?: string;
+}
+
+/**
+ * Feature Item structure for Features Layout.
+ */
+export interface FeatureItem {
+    /** Optional id for element control (engine.element(id)). */
+    id?: string;
+    class: string;
+    title: string;
+    desc: string;
+    description?: string;  // Alias for desc (backwards compatibility)
+    icon: string;
+}
+
+/**
+ * Slide: Features Layout
+ * A grid of feature cards.
+ * @example
+ * ```json
+ * {
+ *   "type": "features",
+ *   "title": "Core Capabilities",
+ *   "description": "Built to scale.",
+ *   "features": [
+ *     { "title": "Reactive", "desc": "State management", "icon": "fa-database" },
+ *     { "title": "Modular", "desc": "Tree-shakable", "icon": "fa-cube" }
+ *   ]
+ * }
+ * ```
+ */
+export interface SlideFeatures extends SlideBase {
+    type: 'features';
+    title: string;
+    description?: string;
+    /** List of feature cards to display. */
+    features: FeatureItem[];
+}
+
+/**
+ * Slide: Split/Half Layout
+ * Text on one side, image on the other.
+ * @example
+ * ```json
+ * {
+ *   "type": "half",
+ *   "imageSide": "left",
+ *   "image": "https://example.com/photo.jpg",
+ *   "title": "Smart Split Layouts",
+ *   "paragraphs": ["Lumina adapts to viewport size.", "Content is King."],
+ *   "cta": "Read Documentation"
+ * }
+ * ```
+ */
+export interface SlideHalf extends SlideBase {
+    imageClass: string;
+    type: 'half';
+    /** Which side the image appears on. */
+    imageSide: 'left' | 'right';
+    /** Image URL (optional if video is provided). */
+    image?: string;
+    /** Video properties (optional). */
+    video?: VideoProperties;
+    tag?: string;
+    title: string;
+    paragraphs: string[];
+    cta?: string;
+}
+
+/**
+ * Slide: Timeline Layout
+ * Chronological list of events.
+ */
+export interface SlideTimeline extends SlideBase {
+    type: 'timeline';
+    title: string;
+    subtitle?: string;
+    timeline: TimelineItem[];
+}
+
+/**
+ * Slide: Steps / Process Layout
+ * Numbered steps with descriptions.
+ */
+export interface SlideSteps extends SlideBase {
+    type: 'steps';
+    title: string;
+    subtitle?: string;
+    steps: StepItem[];
+}
+
+/**
+ * Slide: Flex Layout
+ * Flow-based layout for composing slides using semantic sizing.
+ * Elements flow in order with size tokens (half, third, etc.) instead of coordinates.
+ * @example
+ * ```json
+ * {
+ *   "type": "flex",
+ *   "direction": "horizontal",
+ *   "elements": [
+ *     { "type": "image", "src": "photo.jpg", "size": "half", "fill": true },
+ *     { "type": "content", "size": "half", "valign": "center", "elements": [
+ *       { "type": "title", "text": "Hello World" },
+ *       { "type": "bullets", "items": ["Point A", "Point B"] }
+ *     ]}
+ *   ]
+ * }
+ * ```
+ */
+export interface SlideFlex extends SlideBase {
+    type: 'flex';
+    /** Main flow direction. Default: 'horizontal' */
+    direction?: 'horizontal' | 'vertical';
+    /** Gap between top-level elements. Default: 'none' */
+    gap?: SpacingToken;
+    /** Padding around the entire container. Default: 'none' */
+    padding?: SpacingToken;
+    /** Horizontal alignment of the flex group within the slide. Default: 'left' */
+    halign?: HAlign;
+    /** Vertical alignment of the flex group within the slide. Default: 'top' */
+    valign?: VAlign;
+    /** Array of flex elements to render. */
+    elements: FlexElement[];
+}
+
+/**
+ * Slide: Custom HTML
+ * Renders arbitrary HTML content fullscreen.
+ * Use with caution - HTML is injected directly.
+ * @example
+ * ```json
+ * {
+ *   "type": "custom",
+ *   "html": "<div class='my-custom-slide'>Custom Content</div>",
+ *   "css": ".my-custom-slide { color: white; }"
+ * }
+ * ```
+ */
+export interface SlideCustom extends SlideBase {
+    type: 'custom';
+    /** Raw HTML content to render */
+    html: string;
+    /** Optional scoped CSS styles */
+    css?: string;
+}
+
+/**
+ * Slide: Chart Layout
+ * Renders data visualizations using Chart.js.
+ * @example
+ * ```json
+ * {
+ *   "type": "chart",
+ *   "chartType": "bar",
+ *   "title": "Revenue by Quarter",
+ *   "data": {
+ *     "labels": ["Q1", "Q2", "Q3", "Q4"],
+ *     "datasets": [{ "label": "2024", "values": [120, 150, 180, 220], "color": "c:p" }]
+ *   }
+ * }
+ * ```
+ */
+export interface SlideChart extends SlideBase {
+    chartClass: string;
+    type: 'chart';
+    /** The type of chart to render. */
+    chartType: ChartType;
+    /** Chart title displayed above the chart. */
+    title?: string;
+    /** Subtitle or description. */
+    subtitle?: string;
+    /** The chart data configuration. */
+    data: ChartData;
+}
+
+/**
+ * Slide: Diagram Layout
+ * Renders an interactive node-based diagram.
+ */
+export interface SlideDiagram extends SlideBase {
+    type: 'diagram';
+    title?: string;
+    /** Diagram nodes (compatible with Vue Flow) */
+    nodes: any[];
+    /** Diagram edges (compatible with Vue Flow) */
+    edges: any[];
+    /** Optional configuration for the diagram engine */
+    config?: {
+        fitView?: boolean;
+        [key: string]: any;
+    };
+}
+
+/**
+ * Element in a free/composition layout. Absolutely positioned; position is driven by
+ * slide.timelineTracks (x, y as translate). Use for Remotion-style storytelling.
+ */
+export interface FreeElement {
+  id?: string;
+  type: 'text' | 'image' | 'box';
+  text?: string;
+  src?: string;
+  width?: number | string;
+  height?: number | string;
+  fontSize?: string | number;
+  color?: string;
+  fontWeight?: string;
+  backgroundColor?: string;
+}
+
+/**
+ * Slide: Free / Composition (Remotion-style)
+ * Absolutely positioned elements (text, image, box) animated via timelineTracks.
+ * x, y in keyframes = translate; use for storytelling, motion, and layout freedom.
+ */
+export interface SlideFree extends SlideBase {
+  type: 'free';
+  elements: FreeElement[];
+}
+
+/**
+ * Slide: Generic / Custom
+ * Fallback for custom layouts or unknown types.
+ */
+export interface SlideGeneric extends SlideBase {
+    type: string & {};
+    [key: string]: any;
+}
+
+/**
+ * Slide: Video Layout
+ * Full screen video player.
+ */
+export interface SlideVideo extends SlideBase {
+    type: 'video';
+    video: VideoProperties;
+    /** Optional caption or title overlay */
+    title?: string;
+}
+
+/**
+ * The main Slide Data structure.
+ * A discriminated union of all supported slide types.
+ */
+export type BaseSlideData =
+    | SlideStatement
+    | SlideFeatures
+    | SlideHalf
+    | SlideTimeline
+    | SlideSteps
+    | SlideFlex
+    | SlideChart
+    | SlideDiagram
+    | SlideCustom
+    | SlideVideo
+    | SlideFree
+    | SlideGeneric;
+
+/**
+ * Map of element id → partial ElementState. Used in `DeckMeta.initialElementState`
+ * to define initial visibility/opacity/transform when the deck loads. Enables
+ * "start empty, reveal on demand" presentations.
+ */
+export type InitialElementState = Record<string, Partial<ElementState>>;
+
+/**
+ * Global metadata for the entire presentation deck.
+ */
+export interface DeckMeta {
+    id?: string; // Firestore document ID
+    title: string;
+    author?: string;
+    authorId?: string; // ID of the user who owns this deck
+    authorName?: string; // Display name of the author
+    isPublic?: boolean; // Visibility flag
+    date?: string;
+    deletedAt?: string; // Soft delete timestamp
+    /**
+     * Initial state for controllable elements when the deck is loaded. Keys are element ids
+     * (e.g. "s0-tag", "s0-title", "s1-features-0" or custom ids). Use { visible: false } to
+     * start hidden; then call engine.element(id).show() to reveal. Also supports opacity,
+     * transform, class, style. Overwritten on load; patchDeck does not reset it.
+     *
+     * @example
+     * "initialElementState": { "s0-tag": { "visible": false }, "s0-title": { "visible": false }, "s0-subtitle": { "visible": false } }
+     *
+     * @see ElementState
+     * @see Lumina.element
+     * @see getElementIds
+     */
+    initialElementState?: InitialElementState;
+    /**
+     * Element control defaults. Can be set in deck JSON so the deck is self-contained.
+     * defaultVisible: false = start all elements hidden; override per-id via initialElementState.
+     */
+    elementControl?: { defaultVisible?: boolean };
+    [key: string]: any;
+}
+
+/**
+ * Complete deck object. Primary input to `engine.load(deck)`.
+ *
+ * @description
+ * Must have `meta.title` and `slides` (array of slide objects). meta.initialElementState and
+ * meta.elementControl enable reveal-on-demand. meta.effects overrides animation (see LuminaAnimationOptions).
+ *
+ * @example
+ * { meta: { title: "Demo", initialElementState: { "s0-title": { visible: false } } }, slides: [{ type: "statement", title: "Hi" }] }
+ *
+ * @see Lumina.load
+ * @see DeckMeta
+ * @see BaseSlideData
+ */
+export interface Deck {
+    meta: DeckMeta;
+    slides: BaseSlideData[];
+    /** Theme preset name or custom ThemeConfig object. */
+    theme?: string | ThemeConfig;
+}
+
+// --- Configuration ---
+
+// ============================================================================
+// THEME CONFIGURATION TYPES
+// Comprehensive design token system for full customization
+// ============================================================================
+
+/**
+ * Color palette configuration.
+ * All values should be Hex codes (e.g. '#EF4444') or valid CSS colors.
+ */
+export interface ThemeColors {
+    // --- Core Colors ---
+    /** Main brand/accent color. Used for highlights, buttons, links. */
+    primary?: string;
+    /** Secondary brand color. Used for complementary elements. */
+    secondary?: string;
+    /** Tertiary/accent color. Used for special highlights. */
+    accent?: string;
+    /** Main background color. */
+    background?: string;
+    /** Elevated surface color (cards, panels, modals). */
+    surface?: string;
+    /** Primary text color. */
+    text?: string;
+    /** Secondary/subdued text color. */
+    textSecondary?: string;
+    /** Muted/disabled text color. */
+    muted?: string;
+
+    // --- Semantic Colors ---
+    /** Success state color (green tones). */
+    success?: string;
+    /** Warning state color (yellow/amber tones). */
+    warning?: string;
+    /** Danger/error state color (red tones). */
+    danger?: string;
+    /** Informational state color (blue tones). */
+    info?: string;
+
+    // --- UI Element Colors ---
+    /** Border color for containers, cards, inputs. */
+    border?: string;
+    /** Subtle border color for dividers. */
+    borderSubtle?: string;
+    /** Shadow color (used with rgba). */
+    shadow?: string;
+    /** Overlay color for modals, backdrops. */
+    overlay?: string;
+    /** Highlight/selection color. */
+    highlight?: string;
+
+    // --- Interactive Element Colors ---
+    /** Primary button background. */
+    buttonPrimary?: string;
+    /** Primary button text. */
+    buttonPrimaryText?: string;
+    /** Secondary button background. */
+    buttonSecondary?: string;
+    /** Secondary button text. */
+    buttonSecondaryText?: string;
+    /** Link color. */
+    link?: string;
+    /** Link hover color. */
+    linkHover?: string;
+
+    // --- Gradient Colors ---
+    /** Gradient start color. */
+    gradientFrom?: string;
+    /** Gradient middle color (optional). */
+    gradientVia?: string;
+    /** Gradient end color. */
+    gradientTo?: string;
+}
+
+/**
+ * Typography configuration.
+ */
+export interface ThemeTypography {
+    /** Font family definitions. */
+    fontFamily?: {
+        /** Font for headings (h1-h6, titles). */
+        heading?: string;
+        /** Font for body text, paragraphs. */
+        body?: string;
+        /** Font for code, monospace text. */
+        mono?: string;
+    };
+    /** Font size scale. Values should be CSS size values (rem, px, etc.). */
+    fontSize?: {
+        /** Extra small: 0.75rem / 12px */
+        xs?: string;
+        /** Small: 0.875rem / 14px */
+        sm?: string;
+        /** Base: 1rem / 16px */
+        base?: string;
+        /** Large: 1.125rem / 18px */
+        lg?: string;
+        /** Extra large: 1.25rem / 20px */
+        xl?: string;
+        /** 2XL: 1.5rem / 24px */
+        '2xl'?: string;
+        /** 3XL: 1.875rem / 30px */
+        '3xl'?: string;
+        /** 4XL: 2.25rem / 36px */
+        '4xl'?: string;
+        /** 5XL: 3rem / 48px */
+        '5xl'?: string;
+        /** 6XL: 3.75rem / 60px */
+        '6xl'?: string;
+        /** 7XL: 4.5rem / 72px */
+        '7xl'?: string;
+    };
+    /** Font weight scale. Values should be numeric (100-900). */
+    fontWeight?: {
+        /** Light weight: 300 */
+        light?: number;
+        /** Normal weight: 400 */
+        normal?: number;
+        /** Medium weight: 500 */
+        medium?: number;
+        /** Semibold weight: 600 */
+        semibold?: number;
+        /** Bold weight: 700 */
+        bold?: number;
+        /** Extra bold weight: 800 */
+        extrabold?: number;
+    };
+    /** Line height scale. Values should be unitless or CSS values. */
+    lineHeight?: {
+        /** Tight: 1.1 */
+        tight?: string;
+        /** Snug: 1.25 */
+        snug?: string;
+        /** Normal: 1.5 */
+        normal?: string;
+        /** Relaxed: 1.625 */
+        relaxed?: string;
+        /** Loose: 2 */
+        loose?: string;
+    };
+    /** Letter spacing scale. Values should be CSS values (em, px). */
+    letterSpacing?: {
+        /** Tighter: -0.05em */
+        tighter?: string;
+        /** Tight: -0.025em */
+        tight?: string;
+        /** Normal: 0 */
+        normal?: string;
+        /** Wide: 0.025em */
+        wide?: string;
+        /** Wider: 0.05em */
+        wider?: string;
+        /** Widest: 0.1em (tracking-widest for labels) */
+        widest?: string;
+    };
+}
+
+/**
+ * Spacing scale configuration.
+ * Values should be CSS size values (rem, px, etc.).
+ */
+export interface ThemeSpacing {
+    /** 0 */
+    none?: string;
+    /** 0.25rem / 4px */
+    xs?: string;
+    /** 0.5rem / 8px */
+    sm?: string;
+    /** 1rem / 16px */
+    md?: string;
+    /** 1.5rem / 24px */
+    lg?: string;
+    /** 2rem / 32px */
+    xl?: string;
+    /** 3rem / 48px */
+    '2xl'?: string;
+    /** 4rem / 64px */
+    '3xl'?: string;
+    /** 6rem / 96px */
+    '4xl'?: string;
+}
+
+/**
+ * Border radius scale configuration.
+ * Values should be CSS size values (rem, px, etc.).
+ */
+export interface ThemeBorderRadius {
+    /** No rounding: 0 */
+    none?: string;
+    /** Small: 0.25rem / 4px */
+    sm?: string;
+    /** Medium: 0.5rem / 8px */
+    md?: string;
+    /** Large: 0.75rem / 12px */
+    lg?: string;
+    /** Extra large: 1rem / 16px */
+    xl?: string;
+    /** 2XL: 1.5rem / 24px */
+    '2xl'?: string;
+    /** 3XL: 2rem / 32px */
+    '3xl'?: string;
+    /** Full circle/pill: 9999px */
+    full?: string;
+}
+
+/**
+ * Visual effects configuration.
+ */
+export interface ThemeEffects {
+    // --- Gradients ---
+    /** Enable/disable gradient effects globally. */
+    useGradients?: boolean;
+    /** Gradient direction. */
+    gradientDirection?: 'to-t' | 'to-b' | 'to-l' | 'to-r' | 'to-tl' | 'to-tr' | 'to-bl' | 'to-br';
+    /** Override gradient start color (uses colors.gradientFrom if not set). */
+    gradientFrom?: string;
+    /** Override gradient via/middle color. */
+    gradientVia?: string;
+    /** Override gradient end color (uses colors.gradientTo if not set). */
+    gradientTo?: string;
+
+    // --- Shadows ---
+    /** Enable/disable shadow effects globally. */
+    useShadows?: boolean;
+    /** Shadow intensity level. */
+    shadowIntensity?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+    /** Shadow color (supports CSS color). */
+    shadowColor?: string;
+
+    // --- Glass/Blur Effect ---
+    /** Enable/disable glassmorphism effect on panels. */
+    useGlass?: boolean;
+    /** Glass panel opacity (0-1). */
+    glassOpacity?: number;
+    /** Glass blur amount (e.g., "20px"). */
+    glassBlur?: string;
+    /** Glass border opacity (0-1). */
+    glassBorderOpacity?: number;
+
+    // --- Ambient Orb/Glow ---
+    /** Enable/disable ambient orb effect. */
+    useOrb?: boolean;
+    /** Orb opacity (0-1). */
+    orbOpacity?: number;
+    /** Orb blur amount (e.g., "120px"). */
+    orbBlur?: string;
+    /** Orb size (e.g., "60vw"). */
+    orbSize?: string;
+
+    // --- Animations ---
+    /** Enable/disable animations globally. */
+    animationsEnabled?: boolean;
+    /** Default transition duration (e.g., "0.3s"). */
+    transitionDuration?: string;
+    /** Default transition easing (e.g., "ease-out", CSS cubic-bezier). */
+    transitionEasing?: string;
+    /** Hover scale factor (e.g., 1.05 for 5% scale up). */
+    hoverScale?: number;
+}
+
+/**
+ * Component-specific theming configuration.
+ */
+export interface ThemeComponents {
+    // --- Buttons ---
+    /** Button border radius token or CSS value. */
+    buttonRadius?: string;
+    /** Button padding (e.g., "0.75rem 1.5rem"). */
+    buttonPadding?: string;
+    /** Button font weight. */
+    buttonFontWeight?: number;
+    /** Button text transform (uppercase, capitalize, none). */
+    buttonTextTransform?: 'none' | 'uppercase' | 'capitalize';
+
+    // --- Cards/Panels ---
+    /** Card border radius token or CSS value. */
+    cardRadius?: string;
+    /** Card padding. */
+    cardPadding?: string;
+    /** Card border width (e.g., "1px"). */
+    cardBorderWidth?: string;
+    /** Card background (can override surface color). */
+    cardBackground?: string;
+
+    // --- Timeline ---
+    /** Timeline node/dot size (e.g., "1rem"). */
+    timelineNodeSize?: string;
+    /** Timeline connector line width (e.g., "2px"). */
+    timelineLineWidth?: string;
+    /** Timeline node color (uses primary if not set). */
+    timelineNodeColor?: string;
+    /** Timeline line color (uses border if not set). */
+    timelineLineColor?: string;
+
+    // --- Steps ---
+    /** Step number badge size. */
+    stepBadgeSize?: string;
+    /** Step number font size. */
+    stepFontSize?: string;
+
+    // --- Progress Bar ---
+    /** Progress bar height. */
+    progressHeight?: string;
+    /** Progress bar border radius. */
+    progressRadius?: string;
+    /** Progress bar background (track). */
+    progressBackground?: string;
+    /** Progress bar fill color. */
+    progressFill?: string;
+
+    // --- Tags/Badges ---
+    /** Tag padding. */
+    tagPadding?: string;
+    /** Tag border radius. */
+    tagRadius?: string;
+    /** Tag font size. */
+    tagFontSize?: string;
+
+    // --- Input/Form Elements ---
+    /** Input border radius. */
+    inputRadius?: string;
+    /** Input padding. */
+    inputPadding?: string;
+    /** Input border color. */
+    inputBorder?: string;
+    /** Input focus border color. */
+    inputFocusBorder?: string;
+}
+
+/**
+ * Configuration for the visual theme.
+ * Comprehensive design token system for full slide customization.
+ * 
+ * @example
+ * ```typescript
+ * const theme: ThemeConfig = {
+ *   colors: {
+ *     primary: '#8b5cf6',
+ *     background: '#0a0a0a',
+ *     text: '#ffffff'
+ *   },
+ *   effects: {
+ *     useGradients: true,
+ *     useGlass: true,
+ *     glassBlur: '20px'
+ *   }
+ * };
+ * ```
+ */
+export interface ThemeConfig {
+    /**
+     * Color palette configuration.
+     * Defines all colors used throughout the presentation.
+     */
+    colors?: ThemeColors;
+
+    /**
+     * Typography configuration.
+     * Controls fonts, sizes, weights, and text styling.
+     */
+    typography?: ThemeTypography;
+
+    /**
+     * Spacing scale configuration.
+     * Defines consistent spacing values for gaps, padding, margins.
+     */
+    spacing?: ThemeSpacing;
+
+    /**
+     * Border radius configuration.
+     * Defines rounded corner values for UI elements.
+     */
+    borderRadius?: ThemeBorderRadius;
+
+    /**
+     * Visual effects configuration.
+     * Controls gradients, shadows, glass effects, animations.
+     */
+    effects?: ThemeEffects;
+
+    /**
+     * Component-specific theming.
+     * Fine-grained control over individual component styles.
+     */
+    components?: ThemeComponents;
+
+    // Legacy support (mapped to new structure internally)
+    /** @deprecated Use typography.fontFamily instead */
+    fonts?: {
+        heading?: string;
+        body?: string;
+        mono?: string;
+    };
+}
+
+/**
+ * Custom keyboard shortcuts.
+ */
+export interface LuminaKeyBindings {
+    next: string[];
+    prev: string[];
+}
+
+/**
+ * UI Visibility toggles.
+ */
+export interface LuminaUIOptions {
+    visible?: boolean;        // Global UI visibility
+    showProgressBar?: boolean;
+    showSlideCount?: boolean;
+    showControls?: boolean;   // Next/Prev buttons
+}
+
+/**
+ * Animation configuration. All properties optional. Overrides apply in: options.animation, deck.meta.effects, slide.meta.effects.
+ * Same keys are supported in meta.effects; legacy names (animationDuration→durationIn, etc.) are mapped. See resolveTransitionConfig.
+ *
+ * @description
+ * Use when creating the engine: `new Lumina("#app", { animation: { durationIn: 1.2, revealDelayMs: 500 } })`.
+ * Or in deck/slide JSON: `meta: { effects: { durationIn: 1, revealDelayMs: 400 } }`.
+ *
+ * @example
+ * new Lumina("#app", { animation: { enabled: true, type: "cascade", durationIn: 1, revealDelayMs: 500, elementDuration: 0.6 } });
+ *
+ * @see resolveTransitionConfig
+ * @see ANIMATION_DEFAULTS
+ * @see ResolvedTransitionConfig
+ */
+export interface LuminaAnimationOptions {
+    /** Global toggle for animations. */
+    enabled?: boolean;
+    /** The style of entry animation for slide elements. */
+    type?: 'fade' | 'slide' | 'zoom' | 'cascade'; // Default: 'cascade'
+    /** Duration of entry animations in seconds. */
+    durationIn?: number;
+    /** Duration of exit animations in seconds. */
+    durationOut?: number;
+    /** Stagger delay between sequential elements in seconds. */
+    stagger?: number;
+    /** GSAP easing string (e.g. 'power3.out'). */
+    ease?: string;
+    /**
+     * If true, run the built-in GSAP reveal entrance on elements with .reveal-* classes.
+     * Default: false. Also settable via meta.effects.entranceReveal.
+     */
+    entranceReveal?: boolean;
+
+    // --- revealInSequence (engine.revealInSequence) ---
+    /** Delay in ms between each element. Default: 400. */
+    revealDelayMs?: number;
+    /** Duration in seconds for each element's reveal. Default: 0.45. */
+    revealDuration?: number;
+    /** GSAP ease for reveal. Default: 'power2.out'. */
+    revealEase?: string;
+
+    // --- element().animate() ---
+    /** Default duration in seconds. Default: 0.5. */
+    elementDuration?: number;
+    /** Default GSAP ease. Default: 'power2.out'. */
+    elementEase?: string;
+
+    // --- Exit / deck leave ---
+    /** Ease for exit and slide leave. Default: 'power2.in'. */
+    easeOut?: string;
+
+    // --- useTransition: entrance (granular) ---
+    /** Image duration = durationIn * this. Default: 1.5. */
+    imageDurationMultiplier?: number;
+    /** Image reveal ease. Default: 'expo.out'. */
+    imageEase?: string;
+    /** Stagger between character spans (split text). Default: 0.015. */
+    characterStagger?: number;
+    /** Character duration = durationIn * this. Default: 0.8. */
+    characterDurationFactor?: number;
+    /** Character ease. Default: 'back.out(2)'. */
+    characterEase?: string;
+    /** Stagger between .reveal-child. Default: 0.05. */
+    childRevealStagger?: number;
+    /** Child duration = durationIn * this. Default: 0.6. */
+    childRevealDurationFactor?: number;
+    /** Timeline start offset for child reveal. Default: 0.2. */
+    childRevealStart?: number;
+    /** Child reveal ease. Default: 'power2.out'. */
+    childRevealEase?: string;
+    /** Fallback duration when type is not elastic. Default: 0.7. */
+    durationInStandard?: number;
+    /** Duration for elastic-up type. Default: 1.2. */
+    durationInElastic?: number;
+    /** Ease for elastic-up. Default: 'elastic.out(1, 0.5)'. */
+    easeElastic?: string;
+    /** Ease for spring type. Default: 'back.out(1.5)'. */
+    easeSpring?: string;
+
+    // --- useTransition: exit ---
+    /** Stagger between chars on exit. Default: 0.005. */
+    exitCharStagger?: number;
+    /** Exit element stagger = stagger * this. Default: 0.5. */
+    exitStaggerFactor?: number;
+    /** Exit image duration = durationOut * this. Default: 1.2. */
+    exitImageDurationFactor?: number;
+    /** Exit child duration = durationOut * this. Default: 0.8. */
+    exitChildDurationFactor?: number;
+
+    // --- LuminaElement opacity transition ---
+    /** CSS transition value for opacity (e.g. '0.35s ease-out'). Used via --lumina-element-opacity-transition. */
+    elementOpacityTransition?: string;
+}
+
+/**
+ * Options for `new Lumina(selector, options)`. All properties optional.
+ *
+ * @description
+ * Controls theme (preset or ThemeConfig), loop, navigation, keyboard, touch, UI toggles, animation,
+ * and elementControl (defaultVisible for reveal-on-demand). For animation overrides see LuminaAnimationOptions.
+ *
+ * @example
+ * new Lumina("#app", { theme: "midnight", loop: true, animation: { durationIn: 1.2 } });
+ * new Lumina("#app", { elementControl: { defaultVisible: false } });
+ *
+ * @see Lumina
+ * @see LuminaAnimationOptions
+ */
+export interface LuminaOptions {
+    /** CSS Selector for the container to mount into (default: '#app' or internal). */
+    selector?: string;
+    /** Whether to loop back to the start after the last slide. */
+    loop?: boolean;
+    /** Enable/Disable keyboard navigation. */
+    navigation?: boolean;
+    /** Enable/Disable keyboard shortcuts. */
+    keyboard?: boolean;
+    /** Enable/Disable touch swipe gestures. */
+    touch?: boolean;
+    /** Enable debug logs. */
+    debug?: boolean;
+    /** Theme configuration object or preset name string. */
+    theme?: ThemeConfig | string;
+    /** UI element toggles. */
+    ui?: LuminaUIOptions;
+    /** Custom key bindings. */
+    keys?: LuminaKeyBindings;
+    /** Animation settings. */
+    animation?: LuminaAnimationOptions;
+    /**
+     * Element control defaults. Use for reveal-on-demand: set defaultVisible to false so all
+     * elements start hidden; override per-id via meta.initialElementState. Then reveal with
+     * engine.element(id).show().
+     */
+    elementControl?: {
+        /** If false, all elements start hidden unless listed in meta.initialElementState. Default: true. */
+        defaultVisible?: boolean;
+    };
+    /** Enable Studio (Page Builder) mode. */
+    studio?: boolean;
+}
+
+// --- Events ---
+
+/**
+ * Supported event names emitted by the engine.
+ */
+export type LuminaEventType =
+    | 'ready'
+    | 'slideChange'
+    | 'action'
+    | 'error'
+    | 'patch'
+    | 'destroy'
+    | 'navigate'
+    | 'themeChange'
+    | 'speakerNotesOpen'
+    | 'speakerNotesClose'
+    | 'timelineSeek'
+    | 'timelineComplete'
+    | 'revealStart'
+    | 'revealComplete'
+    | 'revealElement'
+    | 'diagram-node-update'
+    | 'studio:update';
+
+/**
+ * Payload for the 'slideChange' event.
+ */
+export interface SlideChangePayload {
+    index: number;
+    previousIndex: number;
+    slide: BaseSlideData;
+}
+
+/**
+ * Payload for the 'action' event (e.g. button clicks).
+ */
+export interface ActionPayload {
+    type: string;
+    label?: string;
+    value?: any;
+    origin?: string; // Component ID
+    /** Slide index for slide-update actions */
+    slideIndex?: number;
+    /** Patch object for slide-update actions (e.g., { nodes, edges }) */
+    patch?: Record<string, any>;
+}
+
+/** Payload for the 'patch' event. Fired when engine.patch(diff) is called. */
+export interface PatchPayload {
+    diff: any;
+}
+
+/** Payload for the 'navigate' event. Fired when next(), prev(), or goTo() changes the slide. */
+export interface NavigatePayload {
+    direction: 'next' | 'prev' | 'goto';
+    fromIndex: number;
+    toIndex: number;
+}
+
+/** Payload for the 'themeChange' event. Fired when theme or meta (colors, etc.) is applied. */
+export interface ThemeChangePayload {
+    theme: string;
+}
+
+/** Payload for 'timelineSeek'. Fired when seekTo(progress) is called. */
+export interface TimelineSeekPayload {
+    progress: number;
+    slideIndex: number;
+}
+
+/** Payload for 'timelineComplete'. Fired when playTimeline finishes. */
+export interface TimelineCompletePayload {
+    slideIndex: number;
+}
+
+/** Payload for 'revealStart'. Fired when revealInSequence starts. */
+export interface RevealStartPayload {
+    slideIndex: number;
+    elementIds: string[];
+}
+
+/** Payload for 'revealComplete'. Fired when revealInSequence finishes. */
+export interface RevealCompletePayload {
+    slideIndex: number;
+}
+
+/** Payload for 'revealElement'. Fired for each element as it is revealed in a sequence. */
+export interface RevealElementPayload {
+    slideIndex: number;
+    elementId: string;
+    index: number;
+}
+
+/**
+ * Event name → payload type map. Use with `engine.on(k, (payload) => ...)` for type-safe handlers.
+ * - `ready`: deck loaded. - `slideChange`: active slide changed. - `action`: user action (e.g. button). - `error`: engine error.
+ * - `patch`: deck patched (streaming). - `destroy`: engine destroyed. - `navigate`: next/prev/goTo changed slide.
+ * - `themeChange`: theme or meta applied. - `speakerNotesOpen` / `speakerNotesClose`: speaker window.
+ * - `timelineSeek` / `timelineComplete`: Remotion-style timeline. - `revealStart` / `revealComplete` / `revealElement`: revealInSequence.
+ */
+export interface LuminaEventMap {
+    /** Fired when a deck is successfully loaded. */
+    ready: Deck;
+    /** Fired when the active slide changes. */
+    slideChange: SlideChangePayload;
+    /** Fired when a user interaction occurs. */
+    action: ActionPayload;
+    /** Fired when an internal or forwarded error occurs. Use engine.emitError(err) to forward. */
+    error: Error;
+    /** Fired when engine.patch(diff) is called. Useful for streaming or analytics. */
+    patch: PatchPayload;
+    /** Fired when engine.destroy() is called. Use for cleanup. */
+    destroy: Record<string, never>;
+    /** Fired when next(), prev(), or goTo() changes the slide. */
+    navigate: NavigatePayload;
+    /** Fired when theme or meta (colors, typography, etc.) is applied. */
+    themeChange: ThemeChangePayload;
+    /** Fired when the speaker notes window is opened. */
+    speakerNotesOpen: Record<string, never>;
+    /** Fired when the speaker notes window is closed. */
+    speakerNotesClose: Record<string, never>;
+    /** Fired when seekTo(progress) is called. */
+    timelineSeek: TimelineSeekPayload;
+    /** Fired when playTimeline(duration) finishes. */
+    timelineComplete: TimelineCompletePayload;
+    /** Fired when revealInSequence starts. */
+    revealStart: RevealStartPayload;
+    /** Fired when revealInSequence finishes. */
+    revealComplete: RevealCompletePayload;
+    /** Fired for each element as it is revealed in revealInSequence. */
+    revealElement: RevealElementPayload;
+    /** Fired to update a diagram node directly (bypasses store -> watch cycle). Internal. */
+    'diagram-node-update': { slideIndex: number; nodeId: string; key: string; value: any };
+    /** Fired when Studio updates a node (path, value). Internal. */
+    'studio:update': { path: string; value: any };
+}
+
+/**
+ * Key-value store exposed as `engine.data`. Persists across deck loads; not serialized.
+ * Use for preferences, flags, or any app-specific state accessible from the engine or
+ * from components via the injected store (getUserData/setUserData).
+ */
+export interface LuminaDataStore {
+    get(key: string): unknown;
+    set(key: string, value: unknown): LuminaDataStore;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    keys(): string[];
+}
+
+// --- Speaker Notes ---
+
+/**
+ * Message payload for Speaker Notes cross-window synchronization.
+ * Used by BroadcastChannel for bidirectional communication.
+ */
+export interface SpeakerSyncPayload {
+    /** Action type for the sync message. */
+    action: 'goto' | 'next' | 'prev' | 'state' | 'ping' | 'pong' | 'close';
+    /** Current slide index (for 'goto' and 'state'). */
+    index?: number;
+    /** Total number of slides in the deck. */
+    totalSlides?: number;
+    /** Notes content for current slide. */
+    currentNotes?: string;
+    /** Preview info for the next slide. */
+    nextSlidePreview?: {
+        title?: string;
+        type?: string;
+    };
+    /** Timestamp to prevent echo loops. */
+    timestamp?: number;
+    /** Channel ID for multi-instance support. */
+    channelId?: string;
+}