@bendyline/squisq-react 1.4.2 → 2.0.0

package/README.md

@@ -70,6 +70,7 @@ Blocks are composed of typed layers rendered as SVG:
 | `VideoLayer` | Embedded video with playback sync             |
 | `TableLayer` | HTML table embedded via SVG `<foreignObject>` |
 | `MapLayer`   | Tile-based map rendering                      |
+| `TreeLayer`  | Interactive filesystem/outline tree           |
 
 ## Hooks
 
@@ -82,24 +83,50 @@ Blocks are composed of typed layers rendered as SVG:
 | `useAutoSurface`                   | Live light/dark surface detection via `prefers-color-scheme`       |
 | `useMediaProvider` / `useMediaUrl` | Media URL resolution via `MediaContext`                            |
 
+`useDocPlayback` takes configuration as an options object:
+
+```ts
+useDocPlayback(doc, currentTime, { viewport, theme, onSeek });
+```
+
 ## Standalone Player
 
 A self-contained global build is available for non-React environments. It
-exposes a `SquisqPlayer` global with `mount`, `mountStatic`, `unmount`, and
-`version`:
+exposes a `SquisqPlayer` global with `mount`, `getHandle`, `unmount`, and
+`version`. `mount` returns an instance handle.
+
+The former `mountStatic()` shortcut was removed; pass `mode: 'static'` to
+`mount()`. Render methods are instance-scoped and are no longer copied to
+top-level `window.seekTo` / `window.getDuration` properties.
+
+Interactive mount:
 
 ```html
 <script src="https://unpkg.com/@bendyline/squisq-react/dist/squisq-player.global.js"></script>
 <div id="player"></div>
 <script>
   // docJson is a Doc (e.g. produced by markdownToDoc and serialized)
-  SquisqPlayer.mount(document.getElementById('player'), docJson, {
+  const root = document.getElementById('player');
+  const handle = SquisqPlayer.mount(root, docJson, {
     mode: 'slideshow', // or 'static' for a scrollable document view
     basePath: '/',
   });
+
+  // In render mode: const api = await handle.renderAPI;
+  // The same handle is available later as SquisqPlayer.getHandle(root).
 </script>
 ```
 
+For headless capture, add `renderMode: true`, then await
+`handle.renderAPI` before calling `seekTo()` or reading render metadata.
+TypeScript hosts can import `MountOptions` and `SquisqPlayerHandle` from the
+package root.
+
+Set `animationsEnabled: false` on `DocPlayer`, `BlockRenderer`, or standalone
+`mount()` to render authored layer animations and block transitions as static
+content. Embedded video, timed media, captions, audio, and document timing stay
+active; this makes the option suitable for compact MP4 and animated-GIF export.
+
 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.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-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 { 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, TreeLayer as TreeLayer$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, HtmlPolicy } from '@bendyline/squisq/markdown';
@@ -86,8 +86,12 @@ type ControlsLayout = 'overlay' | 'sidebar' | 'bottom';
  *   `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';
+type DisplayMode = 'video' | 'slideshow' | 'linear' | 'page' | 'narrate';
 /**
  * Caption display style.
  *
@@ -117,6 +121,8 @@ interface PlaybackState$1 {
     isPlaying: boolean;
     currentTime: number;
     totalDuration: number;
+    /** Whether the managed cover is the visual currently shown. */
+    isCoverVisible?: boolean;
     currentBlockIndex: number;
     totalBlocks: number;
     docProgress: number;
@@ -184,15 +190,15 @@ interface RenderChapterInfo {
     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.
+ * 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
- * // In Playwright:
- * const w = window as unknown as SquisqWindow;
- * await w.seekTo!(5.0);
- * const blocks = w.getBlocks!();
+ * const handle = SquisqPlayer.getHandle(rootElement);
+ * const api = await handle?.renderAPI;
+ * await api?.seekTo(5.0);
  * ```
  */
 interface SquisqRenderAPI {
@@ -206,11 +212,6 @@ interface SquisqRenderAPI {
     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;
 
@@ -229,8 +230,19 @@ interface DocPlayerProps {
     markdown?: string;
     /** Base path for resolving media URLs (default: `'.'`) */
     basePath?: string;
-    /** Render mode for video capture (hides controls, exposes seekTo) */
+    /** Render mode for video capture (hides controls and creates a render API). */
     renderMode?: boolean;
+    /**
+     * Whether to render slide transitions and per-layer animations (default: true).
+     * Set to false for static slide changes while preserving timeline and media
+     * playback.
+     */
+    animationsEnabled?: boolean;
+    /**
+     * Receives this player's instance-scoped render API, and `null` on cleanup.
+     * The API is created in render mode and `?debug=true` mode only.
+     */
+    onRenderAPIReady?: (api: SquisqRenderAPI | null) => void;
     /** Auto-play when loaded */
     autoPlay?: boolean;
     /** Callback when playback ends */
@@ -291,6 +303,12 @@ interface DocPlayerProps {
      * `doc.startBlock`. Defaults to true for existing documents.
      */
     showCoverSlide?: boolean;
+    /**
+     * Optional controlled cover visibility. Intended for synchronized audience
+     * mirrors that follow another DocPlayer's visual cursor. When omitted, the
+     * player owns its normal cover lifecycle.
+     */
+    coverVisible?: boolean;
     /** Caption display style (default: 'standard').
      *  'social' shows large centered words with the active word highlighted. */
     captionStyle?: CaptionStyle;
@@ -301,6 +319,12 @@ interface DocPlayerProps {
      * `displayMode === 'slideshow'` and not in render/headless mode.
      */
     enableSwipe?: boolean;
+    /**
+     * Listen for playback/navigation shortcuts at the document level instead of
+     * requiring this player to hold focus. Intended for a primary preview or
+     * standalone presentation; leave disabled when several players share a page.
+     */
+    globalKeyboardShortcuts?: boolean;
 }
 /**
  * Front-door component: resolves the `doc` / `markdown` props into a Doc
@@ -310,11 +334,80 @@ interface DocPlayerProps {
  */
 declare function DocPlayer(props: DocPlayerProps): react_jsx_runtime.JSX.Element;
 
-/** Default viewport dimensions (1080p landscape) - for backwards compatibility */
-declare const VIEWPORT: {
-    width: number;
-    height: number;
-};
+/**
+ * Standalone Entry Point — IIFE bundle for self-contained HTML rendering.
+ *
+ * This file is the entry point for the standalone `squisq-player.iife.js` bundle.
+ * It bundles Preact (via preact/compat), squisq core, and all rendering components
+ * into a single self-contained script that can be loaded in any HTML page.
+ *
+ * The bundle exposes a global `SquisqPlayer` object with methods to mount
+ * interactive or static document views into any DOM element.
+ *
+ * Usage (in HTML):
+ *   <script src="squisq-player.iife.js"></script>
+ *   <div id="root"></div>
+ *   <script>
+ *     const root = document.getElementById('root');
+ *     const handle = SquisqPlayer.mount(root, docJson, {
+ *       mode: 'slideshow',
+ *       images: { 'hero.jpg': 'data:image/jpeg;base64,...' }
+ *     });
+ *     // In render mode: const api = await handle.renderAPI;
+ *   </script>
+ */
+
+interface MountOptions {
+    /** Rendering mode: 'slideshow' (interactive, default) or 'static' (scrollable) */
+    mode?: 'slideshow' | 'static';
+    /** Base path for resolving relative media URLs */
+    basePath?: string;
+    /**
+     * Map of relative image paths to data URIs or blob URLs.
+     * Used in single-HTML exports where images are inlined as base64.
+     * Example: { 'hero.jpg': 'data:image/jpeg;base64,...' }
+     */
+    images?: Record<string, string>;
+    /**
+     * Map of audio segment names/paths to URLs (data URIs, blob URLs, or relative paths).
+     * Used in ZIP exports where audio files are included alongside the HTML.
+     */
+    audio?: Record<string, string>;
+    /** Optional theme override */
+    theme?: Theme;
+    /** Auto-play on mount (only for slideshow mode, default: false) */
+    autoPlay?: boolean;
+    /**
+     * Capture presentation arrow keys without requiring focus (default: true).
+     * Disable when mounting multiple interactive players on the same page.
+     */
+    globalKeyboardShortcuts?: boolean;
+    /**
+     * Enable render mode for headless frame capture. The instance API is
+     * available through the returned mount handle. Disables controls and
+     * auto-play.
+     */
+    renderMode?: boolean;
+    /**
+     * Whether to render slide transitions and per-layer animations (default: true).
+     * Timed media continues to play when disabled.
+     */
+    animationsEnabled?: boolean;
+    /** Caption style: 'standard' or 'social'. Omit or set to undefined for no captions. */
+    captionStyle?: 'standard' | 'social';
+}
+/** Instance handle returned by {@link mount}. */
+interface SquisqPlayerHandle {
+    /** DOM element that owns this player instance. */
+    readonly element: Element;
+    /** Resolves to this instance's render API, or null when render mode is off. */
+    readonly renderAPI: Promise<SquisqRenderAPI | null>;
+    /** Current render API without waiting for effects to run. */
+    getRenderAPI(): SquisqRenderAPI | null;
+    /** Unmount this exact player instance. */
+    unmount(): void;
+}
+
 /** Viewport configuration type */
 interface ViewportDimensions {
     width: number;
@@ -337,8 +430,14 @@ interface BlockRendererProps {
     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;
 }
-declare function BlockRenderer({ block, blockTime, basePath, isEntering, isExiting, transition, viewport, isPlaying, }: BlockRendererProps): react_jsx_runtime.JSX.Element;
+declare function BlockRenderer({ block, blockTime, basePath, isEntering, isExiting, transition, viewport, isPlaying, animationsEnabled, }: BlockRendererProps): react_jsx_runtime.JSX.Element;
 
 interface CaptionOverlayProps {
     /** Caption track with timestamped phrases */
@@ -391,11 +490,25 @@ interface DocControlsSidebarProps {
 }
 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$1;
     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 }: DocControlsSlideshowProps): react_jsx_runtime.JSX.Element;
+declare function DocControlsSlideshow({ state, slideNav, slides, pickerOpen, onPickerOpenChange, }: DocControlsSlideshowProps): react_jsx_runtime.JSX.Element;
 
 interface DocPlayerWithSidebarProps {
     /** The Doc to play */
@@ -407,6 +520,8 @@ interface DocPlayerWithSidebarProps {
     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;
@@ -423,7 +538,7 @@ interface DocPlayerWithSidebarProps {
      */
     theme?: Theme;
 }
-declare function DocPlayerWithSidebar({ doc, basePath, autoPlay, onEnded, onTimeUpdate, audioController, muted, captionsEnabled, isFullscreen, onFullscreenToggle, forceViewport, onPlayingChange, theme, }: DocPlayerWithSidebarProps): react_jsx_runtime.JSX.Element;
+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$1;
@@ -483,6 +598,8 @@ interface LinearDocViewProps {
     className?: string;
     /** Theme to use for rendering (default: DEFAULT_THEME from the theme library) */
     theme?: Theme;
+    /** Whether inline visual cards render their layer animations (default: true). */
+    animationsEnabled?: boolean;
     /**
      * Optional surface scheme (light / dark paper) overlaid on top of the
      * theme's colors. Orthogonal to `theme` — a theme picks editorial
@@ -508,6 +625,11 @@ interface LinearDocViewProps {
      * full-size images would dominate the layout.
      */
     imageDisplayMode?: ImageDisplayMode;
+    /**
+     * Let unmodified Up/Down arrows scroll this view even when it does not
+     * currently hold focus. Intended for a primary document preview.
+     */
+    globalKeyboardShortcuts?: boolean;
 }
 type ImageDisplayMode = 'inline' | 'thumbnail';
 /**
@@ -522,7 +644,7 @@ type ImageDisplayMode = 'inline' | 'thumbnail';
  * <LinearDocView doc={doc} basePath="/media/" />
  * ```
  */
-declare function LinearDocView({ doc, markdown, basePath, viewport, className, theme, surface, thinMargins, imageDisplayMode, }: LinearDocViewProps): react_jsx_runtime.JSX.Element;
+declare function LinearDocView({ doc, markdown, basePath, viewport, className, theme, surface, animationsEnabled, thinMargins, imageDisplayMode, globalKeyboardShortcuts, }: LinearDocViewProps): react_jsx_runtime.JSX.Element;
 
 interface InlineVideoPlayerProps {
     /** Source path — resolved through MediaContext when relative. */
@@ -640,6 +762,16 @@ interface TableLayerProps {
 }
 declare function TableLayer({ layer, viewport, blockTime }: TableLayerProps): react_jsx_runtime.JSX.Element;
 
+interface TreeLayerProps {
+    layer: TreeLayer$1;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    blockTime: number;
+}
+declare function TreeLayer({ layer, viewport, blockTime }: TreeLayerProps): react_jsx_runtime.JSX.Element;
+
 interface MapLayerProps {
     layer: MapLayer$1;
     /** Base path for resolving relative image URLs */
@@ -660,8 +792,10 @@ interface MediaClipLayerProps {
     isPlaying: boolean;
     basePath: string;
     renderMode?: boolean;
+    /** Silence every scheduled clip during live playback. */
+    muted?: boolean;
 }
-declare function MediaClipLayer({ schedule, currentTime, isPlaying, basePath, renderMode, }: MediaClipLayerProps): react_jsx_runtime.JSX.Element | null;
+declare function MediaClipLayer({ schedule, currentTime, isPlaying, basePath, renderMode, muted, }: MediaClipLayerProps): react_jsx_runtime.JSX.Element | null;
 
 /**
  * useAudioSync Hook
@@ -677,7 +811,7 @@ declare function MediaClipLayer({ schedule, currentTime, isPlaying, basePath, re
  * can supply their own AudioController to DocPlayer instead of this hook.
  */
 
-declare function useAudioSync(audioRef: RefObject<HTMLAudioElement>, audioTrack: AudioTrack | undefined, basePath?: string): AudioController;
+declare function useAudioSync(audioRef: RefObject<HTMLAudioElement>, audioTrack: AudioTrack | undefined, basePath?: string, enabled?: boolean): AudioController;
 
 /**
  * useMediaSchedule
@@ -744,8 +878,21 @@ interface PlaybackActions {
     prevBlock: () => void;
     /** Go to specific block by index */
     goToBlock: (index: number) => void;
+    /**
+     * Let the identified block enter without remounting the outgoing block.
+     * Used when another interaction (such as a swipe) already removed it.
+     */
+    suppressOutgoingForNextBlock: (blockId: string) => void;
+}
+interface UseDocPlaybackOptions {
+    /** Target viewport used to materialize template blocks. */
+    viewport?: ViewportConfig;
+    /** Active theme used for materialization and transition defaults. */
+    theme?: Theme;
+    /** Host seek callback used by block navigation actions. */
+    onSeek?: (time: number) => void;
 }
-declare function useDocPlayback(script: Doc | null, currentTime: number, viewport?: ViewportConfig, renderMode?: boolean, theme?: Theme): PlaybackState & PlaybackActions;
+declare function useDocPlayback(script: Doc | null, currentTime: number, options?: UseDocPlaybackOptions): PlaybackState & PlaybackActions;
 
 /**
  * useViewportOrientation Hook
@@ -823,4 +970,4 @@ interface JsonViewProps {
 }
 declare function JsonView(props: JsonViewProps): react_jsx_runtime.JSX.Element;
 
-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 };
+export { type AudioActions, type AudioController, type AudioState, type BlockMarker, BlockRenderer, type CaptionMode, CaptionOverlay, type CaptionStyle, type ControlsLayout, type DisplayMode, DocControlsBottom, DocControlsOverlay, DocControlsSidebar, DocControlsSlideshow, DocPlayer, type DocPlayerProps, 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, type MountOptions, PathLayer, type PlaybackActions$1 as PlaybackActions, type PlaybackState$1 as PlaybackState, type RenderAudioSegmentInfo, type RenderBlockInfo, type RenderCaptionInfo, type RenderChapterInfo, ShapeLayer, type SlideNavActions, SocialCaptionOverlay, type SquisqPlayerHandle, type SquisqRenderAPI, TableLayer, TextLayer, TreeLayer, type UseDocPlaybackOptions, VideoLayer, formatTime, useAudioSync, useAutoSurface, useDocPlayback, useMediaProvider, useMediaSchedule, useMediaUrl, useViewportOrientation };