@bendyline/squisq-react 2.0.1 → 2.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bendyline LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,20 @@
+# Third-Party Notices for @bendyline/squisq-react
+
+This notice applies to the `@bendyline/squisq-react` npm package.
+Squisq-authored code is licensed under the MIT license in `LICENSE`.
+Third-party components remain under their respective license terms.
+
+## Runtime, peer, and bundled dependencies
+
+| Package            | Version   | License | Repository                            |
+| ------------------ | --------- | ------- | ------------------------------------- |
+| @bendyline/squisq  | 2.1.0     | MIT     | https://github.com/bendyline/squisq   |
+| mermaid            | 11.16.0   | MIT     | https://github.com/mermaid-js/mermaid |
+| preact             | 10.29.0   | MIT     | https://github.com/preactjs/preact    |
+| react _(peer)_     | ^18 / ^19 | MIT     | https://github.com/facebook/react     |
+| react-dom _(peer)_ | ^18 / ^19 | MIT     | https://github.com/facebook/react     |
+
+Mermaid is Copyright (c) 2014-2022 Knut Sveidqvist and is distributed under
+the MIT License. Preact is used by the standalone browser bundles. Copyright
+and complete license texts for these dependencies are included in their
+respective distributions and source repositories.

package/README.md

@@ -95,6 +95,12 @@ A self-contained global build is available for non-React environments. It
 exposes a `SquisqPlayer` global with `mount`, `getHandle`, `unmount`, and
 `version`. `mount` returns an instance handle.
 
+The default build is the light player and omits Mermaid's multi-megabyte parser
+and layout engines. Documents that contain Mermaid fences should use the full
+variant at `dist/squisq-player.full.global.js` (also exported as
+`@bendyline/squisq-react/standalone/full`). Other diagrams are supported by
+both variants.
+
 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.

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 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, TreeLayer as TreeLayer$1, MapLayer as MapLayer$1, ScheduledClip, AudioTrack, MediaProvider } from '@bendyline/squisq/schemas';
-import { ViewportConfig, ViewportOrientation } from '@bendyline/squisq/doc';
+import { Block, Doc, Theme, SurfaceScheme, Transition, CaptionTrack, ViewportConfig as ViewportConfig$1, ThemePageStyle, 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, MermaidLayer as MermaidLayer$1, ScheduledClip, AudioTrack, MediaProvider } from '@bendyline/squisq/schemas';
+import { ViewportConfig, PageTransformHints, PageSectionMaterialization, PageSection, MaterializeBlockLayersOptions, ViewportOrientation } from '@bendyline/squisq/doc';
 export { getAnimationStyle, getTransitionClass } from '@bendyline/squisq/doc';
-import { MarkdownBlockNode, HtmlPolicy } from '@bendyline/squisq/markdown';
+import { MarkdownBlockNode, HtmlPolicy, ResourcePolicy } from '@bendyline/squisq/markdown';
 import * as react from 'react';
 import { RefObject } from 'react';
 import { SquisqAnnotatedSchema } from '@bendyline/squisq/jsonForm';
@@ -216,116 +216,50 @@ interface SquisqRenderAPI {
 declare function formatTime(seconds: number): string;
 
 interface DocPlayerProps {
-    /**
-     * 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.
-     */
+    /** The Doc to play. Wins over `markdown` when both are provided. */
     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 source to convert when `doc` is absent. */
     markdown?: string;
-    /** Base path for resolving media URLs (default: `'.'`) */
+    /** Base path for resolving media URLs (default: `'.'`). */
     basePath?: string;
-    /** Render mode for video capture (hides controls and creates a render API). */
+    /** Render mode for deterministic video capture. */
     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.
-     */
+    /** Render slide transitions and per-layer animations (default: true). */
     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.
-     */
+    /** Receives the instance-scoped render API, and `null` on cleanup. */
     onRenderAPIReady?: (api: SquisqRenderAPI | null) => void;
-    /** Auto-play when loaded */
     autoPlay?: boolean;
-    /** Callback when playback ends */
     onEnded?: () => void;
-    /** Callback for time updates */
     onTimeUpdate?: (time: number) => void;
-    /** Optional audio controller (if not provided, uses default HTML5 audio) */
+    /** Optional host-owned audio controller. */
     audioController?: AudioController;
-    /** Show built-in controls (default: true). Set to false for custom controls. */
+    /** Explicit synthetic clock for timed documents that intentionally have no audio asset. */
+    audioMode?: 'media' | 'synthetic';
     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.
-     */
+    /** Video, manual slideshow, or long-scrolling linear rendition. */
     displayMode?: DisplayMode;
-    /**
-     * Whether to synthesize and show the managed cover slide from
-     * `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;
-    /**
-     * 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;
-    /**
-     * 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
  * and renders a themed empty state when neither is provided. The playback
@@ -578,6 +512,14 @@ interface MarkdownRendererProps {
  */
 declare function MarkdownRenderer({ nodes, className, htmlPolicy, linkSchemes, }: MarkdownRendererProps): react_jsx_runtime.JSX.Element | null;
 
+interface MermaidDiagramProps {
+    source: string;
+    className?: string;
+    ariaLabel?: string;
+}
+/** Read-only Mermaid rendering for page bodies and slide layers. */
+declare function MermaidDiagram({ source, className, ariaLabel, }: MermaidDiagramProps): react_jsx_runtime.JSX.Element;
+
 interface LinearDocViewProps {
     /**
      * The Doc to render. Wins over `markdown` when both are provided.
@@ -592,13 +534,13 @@ interface LinearDocViewProps {
     markdown?: string;
     /** Base path for resolving media URLs (images, etc.) */
     basePath?: string;
-    /** Viewport config for SVG card rendering (default: landscape) */
+    /** Viewport config for embedded SVG canvas sections (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;
-    /** Whether inline visual cards render their layer animations (default: true). */
+    /** Whether embedded canvas sections render their layer animations (default: true). */
     animationsEnabled?: boolean;
     /**
      * Optional surface scheme (light / dark paper) overlaid on top of the
@@ -609,12 +551,10 @@ interface LinearDocViewProps {
      */
     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.
+     * Use tight padding + a hugging layout. The default layout is a full
+     * page with themed section bands. Short conversational snippets like
+     * chat replies benefit from a much tighter layout. Set to `true` to
+     * render with minimal padding so the content hugs its container.
      */
     thinMargins?: boolean;
     /**
@@ -630,21 +570,54 @@ interface LinearDocViewProps {
      * currently hold focus. Intended for a primary document preview.
      */
     globalKeyboardShortcuts?: boolean;
+    /**
+     * Synthesize a hero section from `doc.startBlock` at the top of the
+     * page (default: true). The editor's Cover toggle maps here.
+     */
+    showCover?: boolean;
+    /**
+     * Page hints from the active transform (Summarize) style — spacing and
+     * emphasis-curve adjustments defined by `TransformStyleConfig.page`.
+     */
+    transformPage?: PageTransformHints;
 }
 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.
+ * Renders a Doc as a scrolling, theme-art-directed page.
  *
  * @example
  * ```tsx
  * <LinearDocView doc={doc} basePath="/media/" />
  * ```
  */
-declare function LinearDocView({ doc, markdown, basePath, viewport, className, theme, surface, animationsEnabled, thinMargins, imageDisplayMode, globalKeyboardShortcuts, }: LinearDocViewProps): react_jsx_runtime.JSX.Element;
+declare function LinearDocView({ doc, markdown, basePath, viewport, className, theme, surface, animationsEnabled, thinMargins, imageDisplayMode, globalKeyboardShortcuts, showCover, transformPage, }: LinearDocViewProps): react_jsx_runtime.JSX.Element;
+
+interface PageSectionViewProps {
+    entry: PageSectionMaterialization;
+    /** Alternation flip for feature-split sections (theme `alternate` hint). */
+    featureFlip?: boolean;
+    /** True when this is the doc's lead prose section (drop-cap target). */
+    isLeadProse?: boolean;
+}
+declare function PageSectionView({ entry, featureFlip, isLeadProse }: PageSectionViewProps): react_jsx_runtime.JSX.Element;
+
+interface CanvasSectionProps {
+    section: PageSection;
+}
+declare function CanvasSection({ section }: CanvasSectionProps): react_jsx_runtime.JSX.Element | null;
+
+interface PageViewContextValue {
+    theme: Theme;
+    pageStyle: ThemePageStyle;
+    basePath: string;
+    viewport: ViewportConfig$1;
+    /** Options for `materializeBlockLayers` inside canvas embeds. */
+    renderContext: MaterializeBlockLayersOptions;
+    animationsEnabled: boolean;
+    imageDisplayMode: ImageDisplayMode;
+}
+declare const PageViewContext: react.Context<PageViewContextValue>;
+declare function usePageView(): PageViewContextValue;
 
 interface InlineVideoPlayerProps {
     /** Source path — resolved through MediaContext when relative. */
@@ -788,6 +761,17 @@ interface MapLayerProps {
 }
 declare function MapLayer({ layer, basePath, viewport, blockTime }: MapLayerProps): react_jsx_runtime.JSX.Element;
 
+interface MermaidLayerProps {
+    layer: MermaidLayer$1;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    blockTime: number;
+}
+/** Mermaid diagram hosted in HTML inside the slide SVG. */
+declare function MermaidLayer({ layer, viewport, blockTime }: MermaidLayerProps): react_jsx_runtime.JSX.Element;
+
 interface MediaClipLayerProps {
     schedule: ScheduledClip[];
     currentTime: number;
@@ -813,7 +797,21 @@ 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, enabled?: boolean): AudioController;
+type AudioSyncMode = 'media' | 'synthetic';
+declare function useAudioSync(audioRef: RefObject<HTMLAudioElement>, audioTrack: AudioTrack | undefined, basePath?: string, enabled?: boolean, mode?: AudioSyncMode): AudioController;
+
+interface ModalDialogOptions {
+    /** The backdrop/portal root. Siblings of this branch are made inert. */
+    rootRef: RefObject<HTMLElement | null>;
+    /** The element with `role="dialog"`; focus is trapped within it. */
+    dialogRef: RefObject<HTMLElement | null>;
+    initialFocusRef?: RefObject<HTMLElement | null>;
+    /** Explicit opener/owner to restore after unmount (important when a child uses autofocus). */
+    returnFocusRef?: RefObject<HTMLElement | null>;
+    onClose: () => void;
+}
+/** Shared focus, keyboard, background-isolation, and restoration behavior for modal dialogs. */
+declare function useModalDialog({ rootRef, dialogRef, initialFocusRef, returnFocusRef, onClose, }: ModalDialogOptions): void;
 
 /**
  * useMediaSchedule
@@ -930,6 +928,13 @@ declare function useViewportOrientation(): UseViewportOrientationResult;
  * React context holding the current MediaProvider (or null if none provided).
  */
 declare const MediaContext: react.Context<MediaProvider | null>;
+/**
+ * Policy for document-controlled media URLs. Hosts rendering untrusted
+ * documents can provide `LOCAL_ONLY_RESOURCE_POLICY` or an explicit host
+ * allow-list without changing their MediaProvider.
+ */
+declare const ResourcePolicyContext: react.Context<ResourcePolicy>;
+declare function useResourcePolicy(): ResourcePolicy;
 /**
  * Hook to access the current MediaProvider from context.
  * Returns null if no provider is set.
@@ -972,4 +977,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, 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 };
+export { type AudioActions, type AudioController, type AudioState, type BlockMarker, BlockRenderer, CanvasSection, type CanvasSectionProps, 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, MermaidDiagram, type MermaidDiagramProps, MermaidLayer, type ModalDialogOptions, type MountOptions, PageSectionView, type PageSectionViewProps, PageViewContext, type PageViewContextValue, PathLayer, type PlaybackActions$1 as PlaybackActions, type PlaybackState$1 as PlaybackState, type RenderAudioSegmentInfo, type RenderBlockInfo, type RenderCaptionInfo, type RenderChapterInfo, ResourcePolicyContext, ShapeLayer, type SlideNavActions, SocialCaptionOverlay, type SquisqPlayerHandle, type SquisqRenderAPI, TableLayer, TextLayer, TreeLayer, type UseDocPlaybackOptions, VideoLayer, formatTime, useAudioSync, useAutoSurface, useDocPlayback, useMediaProvider, useMediaSchedule, useMediaUrl, useModalDialog, usePageView, useResourcePolicy, useViewportOrientation };