@bendyline/squisq-react 2.2.0 → 2.3.0

package/dist/player/index.d.ts

@@ -0,0 +1,410 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Block, Doc, Theme, SurfaceScheme, Transition, CaptionTrack, ViewportConfig as ViewportConfig$1, ScheduledClip } from '@bendyline/squisq/schemas';
+import { ViewportConfig } from '@bendyline/squisq/doc';
+import { a as AudioController } from '../AudioController-DwMsPe38.js';
+
+/**
+ * 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.
+ * - `'narrate'` — Teleprompter/performance surface. DocPlayer does not
+ *   implement this mode; it is owned by the editor package
+ *   (`@bendyline/squisq-editor-react`), which renders its own
+ *   voice-paced teleprompter view for it.
+ */
+type DisplayMode = 'video' | 'slideshow' | 'linear' | 'page' | 'narrate';
+/**
+ * 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 {
+    isPlaying: boolean;
+    currentTime: number;
+    totalDuration: number;
+    /** Whether the managed cover is the visual currently shown. */
+    isCoverVisible?: boolean;
+    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;
+    /** Optional display label for non-block slides, e.g. the managed cover. */
+    currentSlideLabel?: string;
+    /** Optional human-facing slide number, separate from internal nav index. */
+    currentSlideNumber?: number;
+    /** Optional human-facing slide total, separate from internal nav total. */
+    totalSlideNumber?: number;
+}
+/** Playback actions exposed to external control components */
+interface PlaybackActions {
+    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;
+}
+/**
+ * Instance-scoped API created in render mode and debug mode.
+ * React hosts receive it via `DocPlayer.onRenderAPIReady`; standalone hosts
+ * receive it from their mount handle.
+ *
+ * @example
+ * ```ts
+ * const handle = SquisqPlayer.getHandle(rootElement);
+ * const api = await handle?.renderAPI;
+ * await api?.seekTo(5.0);
+ * ```
+ */
+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;
+}
+/** Format time in seconds to MM:SS string */
+declare function formatTime(seconds: number): string;
+
+interface DocPlayerProps {
+    /** The Doc to play. Wins over `markdown` when both are provided. */
+    doc?: Doc;
+    /** Markdown source to convert when `doc` is absent. */
+    markdown?: string;
+    /** Base path for resolving media URLs (default: `'.'`). */
+    basePath?: string;
+    /** Render mode for deterministic video capture. */
+    renderMode?: boolean;
+    /** Render slide transitions and per-layer animations (default: true). */
+    animationsEnabled?: boolean;
+    /** Receives the instance-scoped render API, and `null` on cleanup. */
+    onRenderAPIReady?: (api: SquisqRenderAPI | null) => void;
+    autoPlay?: boolean;
+    onEnded?: () => void;
+    onTimeUpdate?: (time: number) => void;
+    /** Optional host-owned audio controller. */
+    audioController?: AudioController;
+    /** Explicit synthetic clock for timed documents that intentionally have no audio asset. */
+    audioMode?: 'media' | 'synthetic';
+    showControls?: boolean;
+    showScrubber?: boolean;
+    muted?: boolean;
+    captionsEnabled?: boolean;
+    onCaptionsToggle?: (enabled: boolean) => void;
+    onPlaybackStateChange?: (state: PlaybackState) => void;
+    onControlsReady?: (controls: PlaybackActions & {
+        play: () => void;
+        pause: () => void;
+    }) => void;
+    isFullscreen?: boolean;
+    onFullscreenToggle?: () => void;
+    onBlockMarkers?: (markers: BlockMarker[]) => void;
+    forceViewport?: ViewportConfig;
+    theme?: Theme;
+    surface?: SurfaceScheme | 'auto';
+    /** Video, manual slideshow, or long-scrolling linear rendition. */
+    displayMode?: DisplayMode;
+    showCoverSlide?: boolean;
+    coverVisible?: boolean;
+    captionStyle?: CaptionStyle;
+    enableSwipe?: boolean;
+    globalKeyboardShortcuts?: boolean;
+}
+
+/**
+ * Front-door component: resolves the `doc` / `markdown` props into a Doc
+ * and renders a themed empty state when neither is provided. The playback
+ * machinery lives in `DocPlayerContent` so its hook order never changes
+ * when a doc appears or disappears.
+ */
+declare function DocPlayer(props: DocPlayerProps): react_jsx_runtime.JSX.Element;
+
+/** 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;
+    /** Transition to apply. Defaults to block.transition. */
+    transition?: Transition;
+    /** Viewport dimensions (defaults to 1920x1080 landscape) */
+    viewport?: ViewportDimensions;
+    /** Whether the doc is currently playing (controls video playback) */
+    isPlaying?: boolean;
+    /**
+     * Whether to render block transitions and layer animations (default: true).
+     * Disabling this only removes authored/render-style motion; timed video
+     * layers continue to advance normally.
+     */
+    animationsEnabled?: boolean;
+    /** Resolved theme inherited by rich-media renderers such as Mermaid. */
+    theme?: Theme;
+}
+declare function BlockRenderer({ block, blockTime, basePath, isEntering, isExiting, transition, viewport, isPlaying, animationsEnabled, theme, }: 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;
+    actions: PlaybackActions;
+    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;
+    actions: PlaybackActions;
+    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;
+    actions: PlaybackActions;
+}
+declare function DocControlsSidebar({ state, actions }: DocControlsSidebarProps): react_jsx_runtime.JSX.Element;
+
+interface SlideshowPickerItem {
+    /** Stable identifier for the slide/block. */
+    id: string;
+    /** Human-facing slide number, or a special label such as "Cover". */
+    label: string;
+    /** Short description shown in the slide picker. */
+    summary: string;
+}
+interface DocControlsSlideshowProps {
+    state: PlaybackState;
+    slideNav: SlideNavActions;
+    /** Slides available for direct navigation from the counter popover. */
+    slides?: readonly SlideshowPickerItem[];
+    /** Controlled open state for hosts that expose their own picker shortcut. */
+    pickerOpen?: boolean;
+    /** Called whenever the slide picker should open or close. */
+    onPickerOpenChange?: (open: boolean) => void;
+}
+declare function DocControlsSlideshow({ state, slideNav, slides, pickerOpen, onPickerOpenChange, }: DocControlsSlideshowProps): react_jsx_runtime.JSX.Element;
+
+interface DocPlayerWithSidebarProps {
+    /** The Doc to play */
+    doc: Doc;
+    /** Base path for resolving media URLs (default: `'.'`) */
+    basePath?: string;
+    autoPlay?: boolean;
+    onEnded?: () => void;
+    onTimeUpdate?: (time: number) => void;
+    /** Optional audio controller (if not provided, uses default HTML5 audio) */
+    audioController?: AudioController;
+    /** Whether to render slide transitions and per-layer animations (default: true). */
+    animationsEnabled?: boolean;
+    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;
+    /**
+     * Theme for rendering. Forwarded to the inner DocPlayer so the sidebar
+     * (portrait) layout matches the default (landscape) layout — without it the
+     * inner player falls back to DEFAULT_THEME, whose dark text is unreadable
+     * over a hero cover image.
+     */
+    theme?: Theme;
+}
+declare function DocPlayerWithSidebar({ doc, basePath, autoPlay, onEnded, onTimeUpdate, audioController, animationsEnabled, muted, captionsEnabled, isFullscreen, onFullscreenToggle, forceViewport, onPlayingChange, theme, }: DocPlayerWithSidebarProps): react_jsx_runtime.JSX.Element;
+
+interface DocProgressBarProps {
+    state: PlaybackState;
+    actions: PlaybackActions;
+    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 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 MediaClipLayerProps {
+    schedule: ScheduledClip[];
+    currentTime: number;
+    isPlaying: boolean;
+    basePath: string;
+    renderMode?: boolean;
+    /** Silence every scheduled clip during live playback. */
+    muted?: boolean;
+}
+declare function MediaClipLayer({ schedule, currentTime, isPlaying, basePath, renderMode, muted, }: MediaClipLayerProps): react_jsx_runtime.JSX.Element | null;
+
+export { type BlockMarker, BlockRenderer, type CaptionMode, CaptionOverlay, type CaptionStyle, type ControlsLayout, type DisplayMode, DocControlsBottom, DocControlsOverlay, DocControlsSidebar, DocControlsSlideshow, DocPlayer, type DocPlayerProps, DocPlayerWithSidebar, DocProgressBar, InlineAudioPlayer, type InlineAudioPlayerProps, InlineVideoPlayer, type InlineVideoPlayerProps, MediaClipLayer, type MediaClipLayerProps, type PlaybackActions, type PlaybackState, type RenderAudioSegmentInfo, type RenderBlockInfo, type RenderCaptionInfo, type RenderChapterInfo, type SlideNavActions, SocialCaptionOverlay, type SquisqRenderAPI, formatTime };

package/dist/player/index.js

@@ -0,0 +1,41 @@
+import {
+  CaptionOverlay,
+  DocControlsBottom,
+  DocControlsOverlay,
+  DocControlsSidebar,
+  DocControlsSlideshow,
+  DocPlayer,
+  DocPlayerWithSidebar,
+  DocProgressBar,
+  MediaClipLayer,
+  SocialCaptionOverlay,
+  formatTime
+} from "../chunk-7FVQ7T3I.js";
+import {
+  BlockRenderer
+} from "../chunk-TQH6RTTV.js";
+import "../chunk-XYS7HMP4.js";
+import "../chunk-NWZQGZIJ.js";
+import "../chunk-TT6ENR6T.js";
+import {
+  InlineAudioPlayer,
+  InlineVideoPlayer
+} from "../chunk-D7KN4CRG.js";
+import "../chunk-WLUZTUNZ.js";
+import "../chunk-LR3AIGDD.js";
+export {
+  BlockRenderer,
+  CaptionOverlay,
+  DocControlsBottom,
+  DocControlsOverlay,
+  DocControlsSidebar,
+  DocControlsSlideshow,
+  DocPlayer,
+  DocPlayerWithSidebar,
+  DocProgressBar,
+  InlineAudioPlayer,
+  InlineVideoPlayer,
+  MediaClipLayer,
+  SocialCaptionOverlay,
+  formatTime
+};