@bendyline/squisq-react 1.3.0 → 1.3.2

package/dist/index.d.ts

@@ -1,35 +1,710 @@
-export { DocPlayer } from './DocPlayer.js';
-export { BlockRenderer, VIEWPORT } from './BlockRenderer.js';
-export { CaptionOverlay } from './CaptionOverlay.js';
-export { SocialCaptionOverlay } from './SocialCaptionOverlay.js';
-export { DocControlsOverlay } from './DocControlsOverlay.js';
-export { DocControlsBottom } from './DocControlsBottom.js';
-export { DocControlsSidebar } from './DocControlsSidebar.js';
-export { DocControlsSlideshow } from './DocControlsSlideshow.js';
-export { DocPlayerWithSidebar } from './DocPlayerWithSidebar.js';
-export { DocProgressBar } from './DocProgressBar.js';
-export { MarkdownRenderer } from './MarkdownRenderer.js';
-export { LinearDocView } from './LinearDocView.js';
-export type { LinearDocViewProps, ImageDisplayMode } from './LinearDocView.js';
-export { InlineVideoPlayer } from './InlineVideoPlayer.js';
-export type { InlineVideoPlayerProps } from './InlineVideoPlayer.js';
-export { InlineAudioPlayer } from './InlineAudioPlayer.js';
-export type { InlineAudioPlayerProps } from './InlineAudioPlayer.js';
-export { ImageLayer } from './layers/ImageLayer.js';
-export { TextLayer } from './layers/TextLayer.js';
-export { ShapeLayer } from './layers/ShapeLayer.js';
-export { VideoLayer } from './layers/VideoLayer.js';
-export { TableLayer } from './layers/TableLayer.js';
-export { MapLayer } from './layers/MapLayer.js';
-export { useAudioSync } from './hooks/useAudioSync.js';
-export { useDocPlayback } from './hooks/useDocPlayback.js';
-export { useViewportOrientation } from './hooks/useViewportOrientation.js';
-export { MediaContext, useMediaProvider, useMediaUrl } from './hooks/MediaContext.js';
-export { useAutoSurface } from './hooks/useAutoSurface.js';
-export type { AudioProvider, AudioState, AudioActions } from './hooks/AudioProvider.js';
-export type { PlaybackState, PlaybackActions, BlockMarker, ControlsLayout, DisplayMode, CaptionStyle, CaptionMode, SlideNavActions, SquisqRenderAPI, SquisqWindow, RenderBlockInfo, RenderAudioSegmentInfo, RenderCaptionInfo, RenderChapterInfo, } from './types.js';
-export { formatTime } from './types.js';
-export { getAnimationStyle, getTransitionClass } from './utils/animationUtils.js';
-export { JsonView } from './jsonView/index.js';
-export type { JsonViewProps } from './jsonView/index.js';
-//# sourceMappingURL=index.d.ts.map
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Block, Doc, Theme, SurfaceScheme, CaptionTrack, ViewportConfig as ViewportConfig$1, ImageLayer as ImageLayer$1, TextLayer as TextLayer$1, ShapeLayer as ShapeLayer$1, VideoLayer as VideoLayer$1, TableLayer as TableLayer$1, MapLayer as MapLayer$1, AudioTrack, MediaProvider } from '@bendyline/squisq/schemas';
+import { ViewportConfig, ViewportOrientation } from '@bendyline/squisq/doc';
+export { getAnimationStyle, getTransitionClass } from '@bendyline/squisq/doc';
+import { MarkdownBlockNode } from '@bendyline/squisq/markdown';
+import * as react from 'react';
+import { RefObject } from 'react';
+import { SquisqAnnotatedSchema } from '@bendyline/squisq/jsonForm';
+
+/**
+ * AudioProvider - Abstraction for audio playback in DocPlayer
+ *
+ * This module defines an interface for audio playback operations that can have
+ * different implementations depending on the runtime environment:
+ *
+ * - Site/Browser: Uses HTML5 Audio element directly
+ * - EFB/MSFS: Routes through CompanionAPI to Electron app
+ *
+ * The DocPlayer uses this abstraction instead of directly manipulating audio,
+ * allowing the same component code to work in both environments.
+ */
+
+interface AudioState {
+    /** Current time in overall timeline (seconds) */
+    currentTime: number;
+    /** Whether audio is currently playing */
+    isPlaying: boolean;
+    /** Index of current audio segment */
+    currentSegment: number;
+    /** Total duration of all segments */
+    totalDuration: number;
+    /** Whether audio has finished */
+    isEnded: boolean;
+    /** Whether audio is loaded and ready to play */
+    isReady: boolean;
+    /** Whether the audio backend is available/connected */
+    isAvailable: boolean;
+    /** Message to show when not available */
+    unavailableMessage?: string;
+}
+interface AudioActions {
+    /** Start or resume playback */
+    play: () => Promise<void>;
+    /** Pause playback */
+    pause: () => Promise<void>;
+    /** Toggle play/pause */
+    toggle: () => Promise<void>;
+    /** Seek to specific time in timeline */
+    seekTo: (time: number) => Promise<void>;
+    /** Skip to specific segment */
+    skipToSegment: (index: number) => Promise<void>;
+    /** Restart from beginning */
+    restart: () => Promise<void>;
+}
+type AudioProvider = AudioState & AudioActions;
+
+/**
+ * Doc Player Control Types
+ *
+ * Shared type definitions for doc player controls across different
+ * layout modes (overlay, sidebar, bottom). These interfaces allow
+ * control components to be decoupled from the core DocPlayer.
+ *
+ * Related Files:
+ * - DocPlayer.tsx — Core player component
+ * - DocProgressBar.tsx — Extracted progress bar
+ * - DocControlsOverlay.tsx — Overlay controls (default)
+ * - DocControlsSidebar.tsx — Vertical sidebar controls
+ * - DocControlsBottom.tsx — Horizontal bottom strip controls
+ */
+
+/** Layout mode for doc player controls */
+type ControlsLayout = 'overlay' | 'sidebar' | 'bottom';
+/**
+ * Display mode for DocPlayer.
+ *
+ * - `'video'` — Traditional video-style playback with play/pause, scrub bar,
+ *   and time-based auto-advance. Default mode.
+ * - `'slideshow'` — PowerPoint-style presentation with prev/next navigation.
+ *   Blocks are treated as static slides that only change on user click.
+ *   No auto-advance, no scrub bar.
+ * - `'linear'` — Long-scrolling document view. Renders the full markdown as
+ *   readable HTML with template-annotated sections shown as inline SVG cards.
+ *   No audio, no timeline, no controls — just a scrollable page.
+ * - `'page'` — Plain semantic HTML preview matching what the
+ *   `markdownDocToPlainHtml` export produces. No SquisqPlayer, no SVG
+ *   cards — just `<h1>`/`<p>`/`<ul>` etc. inside a sandboxed iframe.
+ *   Use when you want a WYSIWYG view of the simple HTML export.
+ */
+type DisplayMode = 'video' | 'slideshow' | 'linear' | 'page';
+/**
+ * Caption display style.
+ *
+ * - `'standard'` — Traditional broadcast-style captions: small white text
+ *   on a semi-transparent black badge at the top of the player.
+ * - `'social'` — Social media-style (Instagram/TikTok): large centered words
+ *   showing 3-5 words at a time with the active word highlighted in the
+ *   theme's primary color. Font and colors pulled from the active theme.
+ */
+type CaptionStyle = 'standard' | 'social';
+/**
+ * Caption display mode — combines enable/disable with style selection.
+ * The CC button cycles through: off → standard → social → off.
+ */
+type CaptionMode = 'off' | 'standard' | 'social';
+/** Slide navigation actions for slideshow display mode */
+interface SlideNavActions {
+    /** Navigate to the next slide */
+    nextSlide: () => void;
+    /** Navigate to the previous slide */
+    prevSlide: () => void;
+    /** Navigate to a specific slide by index (0-based) */
+    goToSlide: (index: number) => void;
+}
+/** Playback state exposed to external control components */
+interface PlaybackState$1 {
+    isPlaying: boolean;
+    currentTime: number;
+    totalDuration: number;
+    currentBlockIndex: number;
+    totalBlocks: number;
+    docProgress: number;
+    hasCaptions: boolean;
+    captionsEnabled: boolean;
+    /** Current caption display mode (off, standard, social). */
+    captionMode: CaptionMode;
+    isFullscreen?: boolean;
+    /** Current audio segment index (0-based) */
+    currentSegmentIndex: number;
+    /** Current audio segment name (e.g., 'intro', 'history') */
+    currentSegmentName: string | null;
+    /** Current block data (for extracting image info, etc.) */
+    currentBlock: Block | null;
+}
+/** Playback actions exposed to external control components */
+interface PlaybackActions$1 {
+    toggle: () => void;
+    restart: () => void;
+    seekTo: (time: number) => void;
+    setCaptionsEnabled: (enabled: boolean) => void;
+    /** Cycle caption mode: off → standard → social → off */
+    cycleCaptionMode: () => void;
+    toggleFullscreen?: () => void;
+}
+/** Block marker data for the progress bar */
+interface BlockMarker {
+    block: Block;
+    index: number;
+    position: number;
+    title: string;
+    /** True if this block is the first in a new audio segment (section boundary) */
+    isSectionStart: boolean;
+}
+/** Block metadata returned by SquisqRenderAPI.getBlocks() */
+interface RenderBlockInfo {
+    id: string;
+    template: string;
+    startTime: number;
+    duration: number;
+}
+/** Audio segment info returned by SquisqRenderAPI.getAudioSegments() */
+interface RenderAudioSegmentInfo {
+    src: string;
+    name: string;
+    duration: number;
+    startTime: number;
+}
+/** Caption phrase info returned by SquisqRenderAPI.getCaptions() */
+interface RenderCaptionInfo {
+    text: string;
+    startTime: number;
+    endTime: number;
+}
+/** Chapter marker returned by SquisqRenderAPI.getChapters() */
+interface RenderChapterInfo {
+    title: string;
+    startTime: number;
+    duration: number;
+}
+/**
+ * API surface exposed on `window` in render mode and debug mode.
+ * Used by Playwright for video export and by ?debug=true for testing.
+ *
+ * @example
+ * ```ts
+ * // In Playwright:
+ * const w = window as unknown as SquisqWindow;
+ * await w.seekTo!(5.0);
+ * const blocks = w.getBlocks!();
+ * ```
+ */
+interface SquisqRenderAPI {
+    seekTo: (time: number) => Promise<void>;
+    getDuration: () => number;
+    getBlocks: () => RenderBlockInfo[];
+    getAudioSegments: () => RenderAudioSegmentInfo[];
+    getCaptions: () => RenderCaptionInfo[];
+    getChapters: () => RenderChapterInfo[];
+    showCover: () => Promise<void>;
+    hideCover: () => Promise<void>;
+    hasCoverBlock: () => boolean;
+}
+/**
+ * Window augmented with optional SquisqRenderAPI properties.
+ * Each property is optional because they're only present in render/debug mode.
+ */
+type SquisqWindow = Window & typeof globalThis & Partial<SquisqRenderAPI>;
+/** Format time in seconds to MM:SS string */
+declare function formatTime(seconds: number): string;
+
+interface DocPlayerProps {
+    /** Doc script to play */
+    script: Doc;
+    /** Base path for resolving media URLs */
+    basePath: string;
+    /** Render mode for video capture (hides controls, exposes seekTo) */
+    renderMode?: boolean;
+    /** Auto-play when loaded */
+    autoPlay?: boolean;
+    /** Callback when playback ends */
+    onEnded?: () => void;
+    /** Callback for time updates */
+    onTimeUpdate?: (time: number) => void;
+    /** Optional audio provider (if not provided, uses default HTML5 audio) */
+    audioProvider?: AudioProvider;
+    /** Show built-in controls (default: true). Set to false for custom controls. */
+    showControls?: boolean;
+    /** Show only the progress bar/scrubber at bottom (no other controls).
+     *  Only takes effect when showControls is false. Allows external controls
+     *  while keeping the scrubber in-video. */
+    showScrubber?: boolean;
+    /** Mute audio (default: false) */
+    muted?: boolean;
+    /** Enable captions (default: true) */
+    captionsEnabled?: boolean;
+    /** Callback when captions enabled state is toggled */
+    onCaptionsToggle?: (enabled: boolean) => void;
+    /** Callback for playback state changes (for external controls) */
+    onPlaybackStateChange?: (state: PlaybackState$1) => void;
+    /** Callback when playback controls are ready (for external controls) */
+    onControlsReady?: (controls: PlaybackActions$1 & {
+        play: () => void;
+        pause: () => void;
+    }) => void;
+    /** Whether the player is currently in fullscreen mode */
+    isFullscreen?: boolean;
+    /** Callback to toggle fullscreen mode */
+    onFullscreenToggle?: () => void;
+    /** Callback when block markers are computed (for external progress bars) */
+    onBlockMarkers?: (markers: BlockMarker[]) => void;
+    /** Force a specific viewport preset, bypassing window-based orientation detection.
+     *  Used when the player is rendered in a constrained container (e.g., map overlay panel)
+     *  whose shape differs from the window's. */
+    forceViewport?: ViewportConfig;
+    /** Theme to use for rendering (default: DEFAULT_THEME from the theme library) */
+    theme?: Theme;
+    /**
+     * Optional surface scheme (light / dark paper) overlaid on top of the
+     * theme's colors. Passed through to the underlying LinearDocView when
+     * `displayMode === 'linear'`; otherwise overlaid onto the theme that
+     * renders the player's SVG blocks.
+     */
+    surface?: SurfaceScheme | 'auto';
+    /**
+     * Display mode for the player.
+     * - `'video'` (default) — Traditional video playback with play/pause, scrub bar, auto-advance.
+     * - `'slideshow'` — PowerPoint-style with prev/next buttons. Blocks are static slides
+     *   that only change on user click. No auto-advance, no scrub bar.
+     * - `'linear'` — Long-scrolling document view. Renders markdown as readable HTML with
+     *   template-annotated sections as inline SVG cards. No audio, no timeline.
+     */
+    displayMode?: DisplayMode;
+    /** Caption display style (default: 'standard').
+     *  'social' shows large centered words with the active word highlighted. */
+    captionStyle?: CaptionStyle;
+}
+declare function DocPlayer({ script, basePath, renderMode, autoPlay, onEnded, onTimeUpdate, audioProvider: externalAudioProvider, showControls, showScrubber, muted, captionsEnabled: captionsEnabledProp, onCaptionsToggle, onPlaybackStateChange, onControlsReady, isFullscreen, onFullscreenToggle, onBlockMarkers, forceViewport, displayMode, theme, surface, captionStyle, }: DocPlayerProps): react_jsx_runtime.JSX.Element;
+
+/** Default viewport dimensions (1080p landscape) - for backwards compatibility */
+declare const VIEWPORT: {
+    width: number;
+    height: number;
+};
+/** Viewport configuration type */
+interface ViewportDimensions {
+    width: number;
+    height: number;
+}
+interface BlockRendererProps {
+    /** The block to render */
+    block: Block;
+    /** Current time relative to block start (seconds) */
+    blockTime: number;
+    /** Base path for resolving media URLs */
+    basePath: string;
+    /** Whether this block is entering (for transition) */
+    isEntering?: boolean;
+    /** Whether this block is exiting (for transition) */
+    isExiting?: boolean;
+    /** Viewport dimensions (defaults to 1920x1080 landscape) */
+    viewport?: ViewportDimensions;
+    /** Whether the doc is currently playing (controls video playback) */
+    isPlaying?: boolean;
+}
+declare function BlockRenderer({ block, blockTime, basePath, isEntering, isExiting, viewport, isPlaying, }: BlockRendererProps): react_jsx_runtime.JSX.Element;
+
+interface CaptionOverlayProps {
+    /** Caption track with timestamped phrases */
+    captions: CaptionTrack | undefined;
+    /** Current playback time in seconds */
+    currentTime: number;
+    /** Whether captions are enabled */
+    enabled?: boolean;
+    /** Font size in pixels for standard style (default: 16) */
+    fontSize?: number;
+    /** Caption display style (default: 'standard') */
+    captionStyle?: CaptionStyle;
+    /** Theme for social-style caption colors and fonts */
+    theme?: Theme;
+    /** Viewport config for social-style font scaling */
+    viewport?: ViewportConfig$1;
+}
+declare function CaptionOverlay({ captions, currentTime, enabled, fontSize, captionStyle, theme, viewport, }: CaptionOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface SocialCaptionOverlayProps {
+    captions: CaptionTrack | undefined;
+    currentTime: number;
+    enabled?: boolean;
+    theme?: Theme;
+    viewport?: ViewportConfig$1;
+}
+declare function SocialCaptionOverlay({ captions, currentTime, enabled, theme, viewport, }: SocialCaptionOverlayProps): react_jsx_runtime.JSX.Element | null;
+
+interface DocControlsOverlayProps {
+    state: PlaybackState$1;
+    actions: PlaybackActions$1;
+    blockMarkers: BlockMarker[];
+    expandedBlocks: Block[];
+    getBlockTitle?: (block: Block) => string;
+}
+declare function DocControlsOverlay({ state, actions, blockMarkers, expandedBlocks, getBlockTitle, }: DocControlsOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface DocControlsBottomProps {
+    state: PlaybackState$1;
+    actions: PlaybackActions$1;
+    blockMarkers: BlockMarker[];
+    expandedBlocks: Block[];
+    getBlockTitle?: (block: Block) => string;
+}
+declare function DocControlsBottom({ state, actions, blockMarkers, expandedBlocks, getBlockTitle, }: DocControlsBottomProps): react_jsx_runtime.JSX.Element;
+
+interface DocControlsSidebarProps {
+    state: PlaybackState$1;
+    actions: PlaybackActions$1;
+}
+declare function DocControlsSidebar({ state, actions }: DocControlsSidebarProps): react_jsx_runtime.JSX.Element;
+
+interface DocControlsSlideshowProps {
+    state: PlaybackState$1;
+    slideNav: SlideNavActions;
+}
+declare function DocControlsSlideshow({ state, slideNav }: DocControlsSlideshowProps): react_jsx_runtime.JSX.Element;
+
+interface DocPlayerWithSidebarProps {
+    script: Doc;
+    basePath: string;
+    autoPlay?: boolean;
+    onEnded?: () => void;
+    onTimeUpdate?: (time: number) => void;
+    audioProvider?: AudioProvider;
+    muted?: boolean;
+    captionsEnabled?: boolean;
+    isFullscreen?: boolean;
+    onFullscreenToggle?: () => void;
+    /** Force a specific viewport preset, bypassing window-based orientation detection. */
+    forceViewport?: ViewportConfig$1;
+    /** Called when playing state changes */
+    onPlayingChange?: (isPlaying: boolean) => void;
+}
+declare function DocPlayerWithSidebar({ script, basePath, autoPlay, onEnded, onTimeUpdate, audioProvider, muted, captionsEnabled, isFullscreen, onFullscreenToggle, forceViewport, onPlayingChange, }: DocPlayerWithSidebarProps): react_jsx_runtime.JSX.Element;
+
+interface DocProgressBarProps {
+    state: PlaybackState$1;
+    actions: PlaybackActions$1;
+    blockMarkers: BlockMarker[];
+    /** All expanded blocks for hover lookup */
+    expandedBlocks: Block[];
+    /** Optional: get block title for hover tooltip */
+    getBlockTitle?: (block: Block) => string;
+}
+declare function DocProgressBar({ state, actions, blockMarkers, expandedBlocks, getBlockTitle, }: DocProgressBarProps): react_jsx_runtime.JSX.Element;
+
+interface MarkdownRendererProps {
+    /** Block-level AST nodes to render */
+    nodes: MarkdownBlockNode[];
+    /** Optional CSS class for the wrapper element */
+    className?: string;
+}
+/**
+ * Renders MarkdownBlockNode[] AST as React HTML elements.
+ *
+ * @example
+ * ```tsx
+ * <MarkdownRenderer nodes={block.contents} />
+ * ```
+ */
+declare function MarkdownRenderer({ nodes, className }: MarkdownRendererProps): react_jsx_runtime.JSX.Element | null;
+
+interface LinearDocViewProps {
+    /** The Doc to render */
+    doc: Doc;
+    /** Base path for resolving media URLs (images, etc.) */
+    basePath?: string;
+    /** Viewport config for SVG card rendering (default: landscape) */
+    viewport?: ViewportConfig$1;
+    /** Optional CSS class for the outer container */
+    className?: string;
+    /** Theme to use for rendering (default: DEFAULT_THEME from the theme library) */
+    theme?: Theme;
+    /**
+     * Optional surface scheme (light / dark paper) overlaid on top of the
+     * theme's colors. Orthogonal to `theme` — a theme picks editorial
+     * identity, a surface picks the paper. Pass `'auto'` to follow the
+     * user's OS `prefers-color-scheme`, a `SurfaceScheme` object to force a
+     * specific surface, or omit to use the theme's built-in colors.
+     */
+    surface?: SurfaceScheme | 'auto';
+    /**
+     * Use tight padding + a wider content column. The default layout is
+     * designed for a reading surface with breathing room (720px column,
+     * 24×16px padding). Short conversational snippets like chat replies
+     * benefit from a much tighter layout. Set to `true` to render with
+     * minimal padding and no max-width cap so the content hugs its
+     * container.
+     */
+    thinMargins?: boolean;
+    /**
+     * How images inside the doc should be sized. `'inline'` (default)
+     * flows them at natural size up to the column width; `'thumbnail'`
+     * constrains each image to a 100×100 box with aspect-preserving
+     * containment — use for chat history and other dense surfaces where
+     * full-size images would dominate the layout.
+     */
+    imageDisplayMode?: ImageDisplayMode;
+}
+type ImageDisplayMode = 'inline' | 'thumbnail';
+/**
+ * Renders a Doc as a long-scrolling, readable document.
+ *
+ * Non-annotated blocks are rendered as HTML text (headings, paragraphs,
+ * lists, etc.) via MarkdownRenderer. Template-annotated blocks are
+ * rendered as inline SVG visual cards via BlockRenderer.
+ *
+ * @example
+ * ```tsx
+ * <LinearDocView doc={doc} basePath="/media/" />
+ * ```
+ */
+declare function LinearDocView({ doc, basePath, viewport, className, theme, surface, thinMargins, imageDisplayMode, }: LinearDocViewProps): react_jsx_runtime.JSX.Element;
+
+interface InlineVideoPlayerProps {
+    /** Source path — resolved through MediaContext when relative. */
+    src: string;
+    /** Base path used when no MediaProvider is in context. */
+    basePath?: string;
+    /** Optional explicit width (pixels or CSS length). */
+    width?: number | string;
+    /** Optional explicit height (pixels or CSS length). */
+    height?: number | string;
+    /** Optional poster image src — also resolved through MediaContext. */
+    poster?: string;
+    /** Whether to show native controls. Defaults to true. */
+    controls?: boolean;
+    /** `preload` attribute passthrough. Defaults to `'metadata'`. */
+    preload?: 'none' | 'metadata' | 'auto';
+    /** Extra className on the wrapper. */
+    className?: string;
+}
+declare function InlineVideoPlayer({ src, basePath, width, height, poster, controls, preload, className, }: InlineVideoPlayerProps): react_jsx_runtime.JSX.Element | null;
+
+interface InlineAudioPlayerProps {
+    /** Source path — resolved through MediaContext when relative. */
+    src: string;
+    /** Base path used when no MediaProvider is in context. */
+    basePath?: string;
+    /** Whether to show native controls. Defaults to true. */
+    controls?: boolean;
+    /** `preload` attribute passthrough. Defaults to `'metadata'`. */
+    preload?: 'none' | 'metadata' | 'auto';
+    /** Extra className on the wrapper. */
+    className?: string;
+}
+declare function InlineAudioPlayer({ src, basePath, controls, preload, className, }: InlineAudioPlayerProps): react_jsx_runtime.JSX.Element | null;
+
+interface ImageLayerProps {
+    layer: ImageLayer$1;
+    /** Base path for resolving relative image URLs */
+    basePath: string;
+    /** Viewport dimensions for percentage calculations */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Current time relative to block start (for animation timing) */
+    blockTime: number;
+}
+declare function ImageLayer({ layer, basePath, viewport, blockTime }: ImageLayerProps): react_jsx_runtime.JSX.Element;
+
+interface TextLayerProps {
+    layer: TextLayer$1;
+    /** Viewport dimensions for percentage calculations */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Current time relative to block start */
+    blockTime: number;
+}
+declare function TextLayer({ layer, viewport, blockTime }: TextLayerProps): react_jsx_runtime.JSX.Element;
+
+interface ShapeLayerProps {
+    layer: ShapeLayer$1;
+    /** Viewport dimensions for percentage calculations */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Current time relative to block start */
+    blockTime: number;
+}
+declare function ShapeLayer({ layer, viewport, blockTime }: ShapeLayerProps): react_jsx_runtime.JSX.Element;
+
+interface VideoLayerProps {
+    layer: VideoLayer$1;
+    /** Base path for resolving relative video URLs */
+    basePath: string;
+    /** Viewport dimensions for percentage calculations */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Current time relative to block start (for playback sync) */
+    blockTime: number;
+    /** Whether the doc is currently playing */
+    isPlaying?: boolean;
+}
+declare function VideoLayer({ layer, basePath, viewport, blockTime: _blockTime, isPlaying, }: VideoLayerProps): react_jsx_runtime.JSX.Element;
+
+interface TableLayerProps {
+    layer: TableLayer$1;
+    /** Viewport dimensions for percentage calculations */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Current time relative to block start (for animation) */
+    blockTime: number;
+}
+declare function TableLayer({ layer, viewport, blockTime }: TableLayerProps): react_jsx_runtime.JSX.Element;
+
+interface MapLayerProps {
+    layer: MapLayer$1;
+    /** Base path for resolving relative image URLs */
+    basePath: string;
+    /** Viewport dimensions for percentage calculations */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Current time relative to block start (for animation timing) */
+    blockTime: number;
+}
+declare function MapLayer({ layer, basePath, viewport, blockTime }: MapLayerProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * useAudioSync Hook
+ *
+ * Synchronizes playback state with an audio element. Provides current
+ * playback time, playing state, and methods to control audio playback.
+ *
+ * Handles multiple audio segments (MP3 files) by tracking which segment
+ * is currently playing and calculating the overall timeline position.
+ *
+ * This is the HTML5 Audio implementation of the AudioProvider interface.
+ * For EFB/MSFS environments, use useCompanionAudioSync instead.
+ */
+
+declare function useAudioSync(audioRef: RefObject<HTMLAudioElement>, audioTrack: AudioTrack | undefined, basePath?: string): AudioProvider;
+
+/**
+ * useDocPlayback Hook
+ *
+ * Manages the playback state for a visual doc, including which block
+ * is currently active, transition states, and synchronization with audio.
+ *
+ * This hook provides:
+ * - Current block determination based on time
+ * - Transition tracking (entering/exiting blocks)
+ * - Manual navigation (next/prev block)
+ * - Time-based seeking
+ * - Automatic expansion of template blocks
+ */
+
+interface PlaybackState {
+    /** Currently visible block */
+    currentBlock: Block | null;
+    /** Index of current block */
+    currentBlockIndex: number;
+    /** Previous block (for transitions) */
+    previousBlock: Block | null;
+    /** Whether current block is entering */
+    isEntering: boolean;
+    /** Whether previous block is exiting */
+    isExiting: boolean;
+    /** Time relative to current block start */
+    blockTime: number;
+    /** Progress through current block (0-1) */
+    blockProgress: number;
+    /** Overall progress through doc (0-1) */
+    docProgress: number;
+    /** Expanded blocks (templates converted to full blocks with layers) */
+    blocks: Block[];
+}
+interface PlaybackActions {
+    /** Go to next block */
+    nextBlock: () => void;
+    /** Go to previous block */
+    prevBlock: () => void;
+    /** Go to specific block by index */
+    goToBlock: (index: number) => void;
+}
+declare function useDocPlayback(script: Doc | null, currentTime: number, viewport?: ViewportConfig, renderMode?: boolean, theme?: Theme): PlaybackState & PlaybackActions;
+
+/**
+ * useViewportOrientation Hook
+ *
+ * Detects the current viewport orientation and returns the appropriate
+ * VIEWPORT_PRESET for rendering docs. Automatically updates when
+ * the window is resized.
+ *
+ * Thresholds:
+ * - Portrait: height > width * 1.2 (significantly taller than wide)
+ * - Square: width and height within 20% of each other
+ * - Landscape: width > height * 1.2 (significantly wider than tall)
+ */
+
+interface UseViewportOrientationResult {
+    /** Current viewport preset configuration */
+    viewport: ViewportConfig;
+    /** Current orientation name */
+    orientation: ViewportOrientation;
+    /** Current window dimensions */
+    windowSize: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Hook to detect viewport orientation and return appropriate preset.
+ * Updates automatically when window is resized.
+ */
+declare function useViewportOrientation(): UseViewportOrientationResult;
+
+/**
+ * React context holding the current MediaProvider (or null if none provided).
+ */
+declare const MediaContext: react.Context<MediaProvider | null>;
+/**
+ * Hook to access the current MediaProvider from context.
+ * Returns null if no provider is set.
+ */
+declare function useMediaProvider(): MediaProvider | null;
+/**
+ * Hook to resolve a media URL via the MediaProvider (if available),
+ * falling back to basePath-based resolution.
+ *
+ * Returns the resolved URL string. Updates when the provider or path changes.
+ *
+ * @param relativePath - Relative media path from the document (e.g., 'hero.jpg')
+ * @param basePath - Fallback base path for URL construction
+ */
+declare function useMediaUrl(relativePath: string, basePath: string): string;
+
+/**
+ * Live-track `prefers-color-scheme` and return a stable SurfaceScheme.
+ * `enabled: false` short-circuits to LIGHT_SURFACE (callers pass `false`
+ * when a static surface was provided so the hook never observes the
+ * media query). The `MediaQueryList` and the `subscribe`/`getSnapshot`
+ * callbacks are memoized so `useSyncExternalStore` doesn't resubscribe on
+ * every parent render.
+ */
+declare function useAutoSurface(enabled: boolean): SurfaceScheme;
+
+interface JsonViewProps {
+    /** Schema describing the value's shape (with optional `squisq` UI hints). */
+    schema: SquisqAnnotatedSchema;
+    /** The value to display. */
+    value: unknown;
+    /** Optional theme. Defaults to `DEFAULT_THEME`. */
+    theme?: Theme;
+    /** Light/dark surface override; `'auto'` follows `prefers-color-scheme`. */
+    surface?: SurfaceScheme | 'auto';
+    /** Padding/gap density. Default: 'comfortable'. */
+    density?: 'comfortable' | 'compact';
+    /** Optional CSS class for the outer container. */
+    className?: string;
+}
+declare function JsonView(props: JsonViewProps): react_jsx_runtime.JSX.Element;
+
+export { type AudioActions, type AudioProvider, type AudioState, type BlockMarker, BlockRenderer, type CaptionMode, CaptionOverlay, type CaptionStyle, type ControlsLayout, type DisplayMode, DocControlsBottom, DocControlsOverlay, DocControlsSidebar, DocControlsSlideshow, DocPlayer, DocPlayerWithSidebar, DocProgressBar, type ImageDisplayMode, ImageLayer, InlineAudioPlayer, type InlineAudioPlayerProps, InlineVideoPlayer, type InlineVideoPlayerProps, JsonView, type JsonViewProps, LinearDocView, type LinearDocViewProps, MapLayer, MarkdownRenderer, MediaContext, type PlaybackActions$1 as PlaybackActions, type PlaybackState$1 as PlaybackState, type RenderAudioSegmentInfo, type RenderBlockInfo, type RenderCaptionInfo, type RenderChapterInfo, ShapeLayer, type SlideNavActions, SocialCaptionOverlay, type SquisqRenderAPI, type SquisqWindow, TableLayer, TextLayer, VIEWPORT, VideoLayer, formatTime, useAudioSync, useAutoSurface, useDocPlayback, useMediaProvider, useMediaUrl, useViewportOrientation };