@bendyline/squisq-react 1.3.2 → 1.4.1

package/README.md

@@ -22,37 +22,54 @@ import { DocPlayer } from '@bendyline/squisq-react';
 import '@bendyline/squisq-react/styles';
 
 function App() {
-  return <DocPlayer doc={myDoc} />;
+  return <DocPlayer markdown={'# Hello\n\nWelcome to Squisq.'} />;
 }
 ```
 
+`DocPlayer` accepts **either** raw `markdown` (parsed and converted internally)
+**or** a parsed `doc`; if you already have a `Doc`, pass `<DocPlayer doc={doc} />`.
+`basePath` is optional (default `'.'`) and is the base URL for resolving relative
+media paths. With neither `markdown` nor `doc`, the player renders a themed empty
+state rather than crashing.
+
+> **v1.5 breaking changes:** the old `script` prop is now `doc`, and the
+> `audioProvider` prop is now `audioController` (its type `AudioProvider` was
+> renamed to `AudioController`). `LinearDocView` gained the same `markdown` prop.
+
 ## Components
 
-| Component              | Description                                                        |
-| ---------------------- | ------------------------------------------------------------------ |
-| `DocPlayer`            | Main document player with timed playback, audio sync, and controls |
-| `LinearDocView`        | Scroll-based linear rendering of all blocks                        |
-| `BlockRenderer`        | SVG-based renderer for a single block                              |
-| `MarkdownRenderer`     | Renders Squisq markdown as a visual document                       |
-| `DocPlayerWithSidebar` | DocPlayer with a sidebar navigation panel                          |
-| `CaptionOverlay`       | Timed caption/subtitle overlay                                     |
-| `DocProgressBar`       | Playback progress indicator                                        |
-| `DocControlsOverlay`   | Floating playback controls                                         |
-| `DocControlsBottom`    | Bottom-bar playback controls                                       |
-| `DocControlsSidebar`   | Sidebar navigation controls                                        |
-| `DocControlsSlideshow` | Slideshow-style navigation controls                                |
+| Component              | Description                                                         |
+| ---------------------- | ------------------------------------------------------------------- |
+| `DocPlayer`            | Main document player with timed playback, audio sync, and controls  |
+| `LinearDocView`        | Scroll-based linear rendering of all blocks                         |
+| `BlockRenderer`        | SVG-based renderer for a single block                               |
+| `MarkdownRenderer`     | Renders Squisq markdown as a visual document                        |
+| `DocPlayerWithSidebar` | DocPlayer with a sidebar navigation panel                           |
+| `CaptionOverlay`       | Timed caption/subtitle overlay                                      |
+| `DocProgressBar`       | Playback progress indicator                                         |
+| `DocControlsOverlay`   | Floating playback controls                                          |
+| `DocControlsBottom`    | Bottom-bar playback controls                                        |
+| `DocControlsSidebar`   | Sidebar navigation controls                                         |
+| `DocControlsSlideshow` | Slideshow-style navigation controls                                 |
+| `SocialCaptionOverlay` | Large centered word-by-word (TikTok/Reels-style) captions           |
+| `InlineVideoPlayer`    | Native `<video>` wrapper resolving `src`/`poster` via MediaContext  |
+| `InlineAudioPlayer`    | Native `<audio>` wrapper resolving `src` via MediaContext           |
+| `MediaClipLayer`       | Hidden `<audio>`/`<video>` elements for timed media clips           |
+| `JsonView`             | Read-only viewer for JSON values bound to a Squisq-annotated schema |
 
 ## Layers
 
 Blocks are composed of typed layers rendered as SVG:
 
-| Layer        | Description                                |
-| ------------ | ------------------------------------------ |
-| `ImageLayer` | Background and foreground images           |
-| `TextLayer`  | Styled text with positioning and animation |
-| `ShapeLayer` | SVG shapes (rectangles, circles, lines)    |
-| `VideoLayer` | Embedded video with playback sync          |
-| `MapLayer`   | Tile-based map rendering                   |
+| Layer        | Description                                   |
+| ------------ | --------------------------------------------- |
+| `ImageLayer` | Background and foreground images              |
+| `TextLayer`  | Styled text with positioning and animation    |
+| `ShapeLayer` | SVG shapes (rectangles, circles, lines)       |
+| `PathLayer`  | Freeform SVG path drawing                     |
+| `VideoLayer` | Embedded video with playback sync             |
+| `TableLayer` | HTML table embedded via SVG `<foreignObject>` |
+| `MapLayer`   | Tile-based map rendering                      |
 
 ## Hooks
 
@@ -60,21 +77,33 @@ Blocks are composed of typed layers rendered as SVG:
 | ---------------------------------- | ------------------------------------------------------------------ |
 | `useDocPlayback`                   | Core playback state machine — timing, block transitions, scripting |
 | `useAudioSync`                     | Synchronizes audio playback with doc timeline                      |
+| `useMediaSchedule`                 | Resolves which timed media clips are active at the current time    |
 | `useViewportOrientation`           | Tracks viewport orientation for responsive layouts                 |
+| `useAutoSurface`                   | Live light/dark surface detection via `prefers-color-scheme`       |
 | `useMediaProvider` / `useMediaUrl` | Media URL resolution via `MediaContext`                            |
 
 ## Standalone Player
 
-A self-contained global build is available for non-React environments:
+A self-contained global build is available for non-React environments. It
+exposes a `SquisqPlayer` global with `mount`, `mountStatic`, `unmount`, and
+`version`:
 
 ```html
 <script src="https://unpkg.com/@bendyline/squisq-react/dist/squisq-player.global.js"></script>
 <div id="player"></div>
 <script>
-  SquisqPlayer.render(document.getElementById('player'), { markdown: '# Hello' });
+  // docJson is a Doc (e.g. produced by markdownToDoc and serialized)
+  SquisqPlayer.mount(document.getElementById('player'), docJson, {
+    mode: 'slideshow', // or 'static' for a scrollable document view
+    basePath: '/',
+  });
 </script>
 ```
 
+For build-time embedding, `@bendyline/squisq-react/standalone-source` exports
+the same bundle as a string constant (`PLAYER_BUNDLE`) — used by
+`@bendyline/squisq-formats` and the CLI to produce single-file HTML exports.
+
 ## Styles
 
 Import the animation CSS for block transitions:
@@ -83,6 +112,11 @@ Import the animation CSS for block transitions:
 import '@bendyline/squisq-react/styles';
 ```
 
+## Full API Reference
+
+See [docs/API.md](https://github.com/bendyline/squisq/blob/main/docs/API.md)
+for the complete prop tables, hook signatures, and types.
+
 ## Related Packages
 
 | Package                                                                                        | Description                                                    |

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 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 { Block, Doc, Theme, SurfaceScheme, Transition, CaptionTrack, ViewportConfig as ViewportConfig$1, ImageLayer as ImageLayer$1, TextLayer as TextLayer$1, ShapeLayer as ShapeLayer$1, PathLayer as PathLayer$1, VideoLayer as VideoLayer$1, TableLayer as TableLayer$1, MapLayer as MapLayer$1, ScheduledClip, 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 { MarkdownBlockNode, HtmlPolicy } 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
+ * AudioController - 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:
@@ -52,7 +52,7 @@ interface AudioActions {
     /** Restart from beginning */
     restart: () => Promise<void>;
 }
-type AudioProvider = AudioState & AudioActions;
+type AudioController = AudioState & AudioActions;
 
 /**
  * Doc Player Control Types
@@ -209,10 +209,20 @@ type SquisqWindow = Window & typeof globalThis & Partial<SquisqRenderAPI>;
 declare function formatTime(seconds: number): string;
 
 interface DocPlayerProps {
-    /** Doc script to play */
-    script: Doc;
-    /** Base path for resolving media URLs */
-    basePath: string;
+    /**
+     * The Doc to play. Wins over `markdown` when both are provided.
+     * When neither `doc` nor `markdown` is given, the player renders a
+     * minimal themed empty state instead of crashing.
+     */
+    doc?: Doc;
+    /**
+     * Markdown source to play. When `doc` is absent, the markdown is parsed
+     * and converted to a Doc via `markdownToDoc(parseMarkdown(markdown))`.
+     * Ignored when `doc` is provided.
+     */
+    markdown?: string;
+    /** Base path for resolving media URLs (default: `'.'`) */
+    basePath?: string;
     /** Render mode for video capture (hides controls, exposes seekTo) */
     renderMode?: boolean;
     /** Auto-play when loaded */
@@ -221,8 +231,8 @@ interface DocPlayerProps {
     onEnded?: () => void;
     /** Callback for time updates */
     onTimeUpdate?: (time: number) => void;
-    /** Optional audio provider (if not provided, uses default HTML5 audio) */
-    audioProvider?: AudioProvider;
+    /** Optional audio controller (if not provided, uses default HTML5 audio) */
+    audioController?: AudioController;
     /** 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).
@@ -273,8 +283,21 @@ interface DocPlayerProps {
     /** Caption display style (default: 'standard').
      *  'social' shows large centered words with the active word highlighted. */
     captionStyle?: CaptionStyle;
+    /**
+     * Enable drag-to-swipe slide navigation in slideshow mode (default: true).
+     * When enabled, press-and-drag on a slide advances/rewinds on release past a
+     * threshold (or a quick flick), and snaps back otherwise. Only applies when
+     * `displayMode === 'slideshow'` and not in render/headless mode.
+     */
+    enableSwipe?: boolean;
 }
-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;
+/**
+ * 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;
 
 /** Default viewport dimensions (1080p landscape) - for backwards compatibility */
 declare const VIEWPORT: {
@@ -297,12 +320,14 @@ interface BlockRendererProps {
     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;
 }
-declare function BlockRenderer({ block, blockTime, basePath, isEntering, isExiting, viewport, isPlaying, }: BlockRendererProps): react_jsx_runtime.JSX.Element;
+declare function BlockRenderer({ block, blockTime, basePath, isEntering, isExiting, transition, viewport, isPlaying, }: BlockRendererProps): react_jsx_runtime.JSX.Element;
 
 interface CaptionOverlayProps {
     /** Caption track with timestamped phrases */
@@ -362,12 +387,15 @@ interface DocControlsSlideshowProps {
 declare function DocControlsSlideshow({ state, slideNav }: DocControlsSlideshowProps): react_jsx_runtime.JSX.Element;
 
 interface DocPlayerWithSidebarProps {
-    script: Doc;
-    basePath: string;
+    /** The Doc to play */
+    doc: Doc;
+    /** Base path for resolving media URLs (default: `'.'`) */
+    basePath?: string;
     autoPlay?: boolean;
     onEnded?: () => void;
     onTimeUpdate?: (time: number) => void;
-    audioProvider?: AudioProvider;
+    /** Optional audio controller (if not provided, uses default HTML5 audio) */
+    audioController?: AudioController;
     muted?: boolean;
     captionsEnabled?: boolean;
     isFullscreen?: boolean;
@@ -376,8 +404,15 @@ interface DocPlayerWithSidebarProps {
     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({ script, basePath, autoPlay, onEnded, onTimeUpdate, audioProvider, muted, captionsEnabled, isFullscreen, onFullscreenToggle, forceViewport, onPlayingChange, }: DocPlayerWithSidebarProps): react_jsx_runtime.JSX.Element;
+declare function DocPlayerWithSidebar({ doc, basePath, autoPlay, onEnded, onTimeUpdate, audioController, muted, captionsEnabled, isFullscreen, onFullscreenToggle, forceViewport, onPlayingChange, theme, }: DocPlayerWithSidebarProps): react_jsx_runtime.JSX.Element;
 
 interface DocProgressBarProps {
     state: PlaybackState$1;
@@ -395,6 +430,17 @@ interface MarkdownRendererProps {
     nodes: MarkdownBlockNode[];
     /** Optional CSS class for the wrapper element */
     className?: string;
+    /**
+     * Raw HTML policy. Defaults to `sanitize`, which removes unsafe tags,
+     * event handlers, and executable URL schemes before rendering.
+     */
+    htmlPolicy?: HtmlPolicy;
+    /**
+     * Extra URL schemes to allow on links (e.g. a host app's internal
+     * navigation scheme it intercepts on click). Executable schemes are
+     * never allowed regardless. See {@link SanitizeUrlOptions}.
+     */
+    linkSchemes?: readonly string[];
 }
 /**
  * Renders MarkdownBlockNode[] AST as React HTML elements.
@@ -404,11 +450,20 @@ interface MarkdownRendererProps {
  * <MarkdownRenderer nodes={block.contents} />
  * ```
  */
-declare function MarkdownRenderer({ nodes, className }: MarkdownRendererProps): react_jsx_runtime.JSX.Element | null;
+declare function MarkdownRenderer({ nodes, className, htmlPolicy, linkSchemes, }: MarkdownRendererProps): react_jsx_runtime.JSX.Element | null;
 
 interface LinearDocViewProps {
-    /** The Doc to render */
-    doc: Doc;
+    /**
+     * The Doc to render. Wins over `markdown` when both are provided.
+     * When neither `doc` nor `markdown` is given, an empty container renders.
+     */
+    doc?: Doc;
+    /**
+     * Markdown source to render. When `doc` is absent, the markdown is parsed
+     * and converted to a Doc via `markdownToDoc(parseMarkdown(markdown))`.
+     * Ignored when `doc` is provided.
+     */
+    markdown?: string;
     /** Base path for resolving media URLs (images, etc.) */
     basePath?: string;
     /** Viewport config for SVG card rendering (default: landscape) */
@@ -456,7 +511,7 @@ type ImageDisplayMode = 'inline' | 'thumbnail';
  * <LinearDocView doc={doc} basePath="/media/" />
  * ```
  */
-declare function LinearDocView({ doc, basePath, viewport, className, theme, surface, thinMargins, imageDisplayMode, }: LinearDocViewProps): react_jsx_runtime.JSX.Element;
+declare function LinearDocView({ doc, markdown, basePath, viewport, className, theme, surface, thinMargins, imageDisplayMode, }: LinearDocViewProps): react_jsx_runtime.JSX.Element;
 
 interface InlineVideoPlayerProps {
     /** Source path — resolved through MediaContext when relative. */
@@ -516,7 +571,11 @@ interface TextLayerProps {
     /** Current time relative to block start */
     blockTime: number;
 }
-declare function TextLayer({ layer, viewport, blockTime }: TextLayerProps): react_jsx_runtime.JSX.Element;
+/**
+ * Dispatch between the plain SVG-text renderer and the rich HTML renderer
+ * based on whether the layer carries `content.html`.
+ */
+declare function TextLayer(props: TextLayerProps): react_jsx_runtime.JSX.Element;
 
 interface ShapeLayerProps {
     layer: ShapeLayer$1;
@@ -530,6 +589,18 @@ interface ShapeLayerProps {
 }
 declare function ShapeLayer({ layer, viewport, blockTime }: ShapeLayerProps): react_jsx_runtime.JSX.Element;
 
+interface PathLayerProps {
+    layer: PathLayer$1;
+    /** Viewport dimensions — used to resolve `%` positions for named shapes. */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Current time relative to block start. */
+    blockTime: number;
+}
+declare function PathLayer({ layer, viewport, blockTime }: PathLayerProps): react_jsx_runtime.JSX.Element;
+
 interface VideoLayerProps {
     layer: VideoLayer$1;
     /** Base path for resolving relative video URLs */
@@ -544,7 +615,7 @@ interface VideoLayerProps {
     /** Whether the doc is currently playing */
     isPlaying?: boolean;
 }
-declare function VideoLayer({ layer, basePath, viewport, blockTime: _blockTime, isPlaying, }: VideoLayerProps): react_jsx_runtime.JSX.Element;
+declare function VideoLayer({ layer, basePath, viewport, blockTime, isPlaying }: VideoLayerProps): react_jsx_runtime.JSX.Element;
 
 interface TableLayerProps {
     layer: TableLayer$1;
@@ -572,6 +643,15 @@ interface MapLayerProps {
 }
 declare function MapLayer({ layer, basePath, viewport, blockTime }: MapLayerProps): react_jsx_runtime.JSX.Element;
 
+interface MediaClipLayerProps {
+    schedule: ScheduledClip[];
+    currentTime: number;
+    isPlaying: boolean;
+    basePath: string;
+    renderMode?: boolean;
+}
+declare function MediaClipLayer({ schedule, currentTime, isPlaying, basePath, renderMode, }: MediaClipLayerProps): react_jsx_runtime.JSX.Element | null;
+
 /**
  * useAudioSync Hook
  *
@@ -581,11 +661,36 @@ declare function MapLayer({ layer, basePath, viewport, blockTime }: MapLayerProp
  * 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.
+ * This is the HTML5 Audio implementation of the AudioController interface.
+ * Hosts that drive audio through an external player (e.g. a native shell)
+ * can supply their own AudioController to DocPlayer instead of this hook.
+ */
+
+declare function useAudioSync(audioRef: RefObject<HTMLAudioElement>, audioTrack: AudioTrack | undefined, basePath?: string): AudioController;
+
+/**
+ * useMediaSchedule
+ *
+ * Pure follower of the playback clock for the media-clip model. Given the
+ * resolved {@link ScheduledClip}s and the current time, it returns the clips
+ * the player should mount and which of them are active right now.
+ * {@link MediaClipLayer} consumes this to drive one hidden `<audio>` /
+ * full-bleed `<video>` element per clip. (Annotation-authored clips all render
+ * at the player level; template-produced `VideoLayer`s are a separate path and
+ * are not part of the schedule.)
+ *
+ * It owns no clock: `currentTime`/`isPlaying` come from the existing
+ * `useAudioSync` provider via `DocPlayer`. With an empty schedule it returns
+ * empty lists, so documents without the new media model are unaffected.
  */
 
-declare function useAudioSync(audioRef: RefObject<HTMLAudioElement>, audioTrack: AudioTrack | undefined, basePath?: string): AudioProvider;
+interface MediaScheduleController {
+    /** Clips the player mounts (every scheduled clip). */
+    renderClips: ScheduledClip[];
+    /** Ids of clips whose [absoluteStart, absoluteEnd) contains currentTime. */
+    activeIds: Set<string>;
+}
+declare function useMediaSchedule(schedule: ScheduledClip[], currentTime: number): MediaScheduleController;
 
 /**
  * useDocPlayback Hook
@@ -707,4 +812,4 @@ interface JsonViewProps {
 }
 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 };
+export { type AudioActions, type AudioController, 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, MediaClipLayer, type MediaClipLayerProps, MediaContext, type MediaScheduleController, PathLayer, 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, useMediaSchedule, useMediaUrl, useViewportOrientation };