@bendyline/squisq-react 1.4.2 → 2.0.1

package/src/layers/MapLayer.tsx

@@ -12,7 +12,7 @@
  * Playwright screenshot contexts.
  */
 
-import { useState, useEffect } from 'react';
+import { useId, useState, useEffect } from 'react';
 import type { MapLayer as MapLayerType } from '@bendyline/squisq/schemas';
 import { getAnimationStyle } from '../utils/animationUtils';
 import { resolveValue, getAnchorOffset } from '../utils/layerUtils';
@@ -30,6 +30,7 @@ interface MapLayerProps {
 
 export function MapLayer({ layer, basePath, viewport, blockTime }: MapLayerProps) {
   const { content, position, animation } = layer;
+  const clipId = `map-clip-${useId().replace(/:/g, '')}-${layer.id}`;
   const [mapImageUrl, setMapImageUrl] = useState<string | null>(null);
   const [isLoading, setIsLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
@@ -89,13 +90,13 @@ export function MapLayer({ layer, basePath, viewport, blockTime }: MapLayerProps
     return () => {
       cancelled = true;
     };
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- content properties are destructured below; center/markers/showAttribution are stable per-render
   }, [
-    content.center.lat,
-    content.center.lng,
+    content.center,
     content.zoom,
     content.style,
     content.staticSrc,
+    content.markers,
+    content.showAttribution,
     width,
     height,
     basePath,
@@ -160,13 +161,13 @@ export function MapLayer({ layer, basePath, viewport, blockTime }: MapLayerProps
     >
       {/* Clip path for overflow handling */}
       <defs>
-        <clipPath id={`clip-${layer.id}`}>
+        <clipPath id={clipId}>
           <rect x={finalX} y={finalY} width={width} height={height} />
         </clipPath>
       </defs>
 
       {/* Map image */}
-      <g clipPath={`url(#clip-${layer.id})`}>
+      <g clipPath={`url(#${clipId})`}>
         <image
           href={mapImageUrl}
           x={finalX}

package/src/layers/PathLayer.tsx

@@ -17,11 +17,11 @@
  * rect/circle/line `ShapeLayer` behaves — rather than pinned to a baked
  * absolute path.
  *
- * End markers are configured via `startMarker`/`endMarker` (with the legacy
- * `arrow` flag mapping to a filled triangle). Marker geometry comes from
- * `markerPath` in core so the SSR renderer and the editor agree.
+ * End markers are configured via `startMarker`/`endMarker`. Marker geometry
+ * comes from `markerPath` in core so the SSR renderer and the editor agree.
  */
 
+import { useId } from 'react';
 import type { PathLayer as PathLayerType, MarkerStyle } from '@bendyline/squisq/schemas';
 import { markerPath, shapePath } from '@bendyline/squisq/doc';
 import { getAnimationStyle } from '../utils/animationUtils';
@@ -54,33 +54,42 @@ function effectivePath(layer: PathLayerType, viewport: { width: number; height:
   return derived ?? content.d;
 }
 
-/** Resolve the effective marker for an endpoint (explicit field, else `arrow`). */
+type LegacyArrow = 'none' | 'end' | 'start' | 'both';
+
+/** Tolerant-reader support for documents authored before endpoint markers. */
+function readLegacyArrow(content: PathLayerType['content']): LegacyArrow | undefined {
+  return (content as PathLayerType['content'] & { arrow?: LegacyArrow }).arrow;
+}
+
+/** Resolve the effective marker for an endpoint. */
 function effectiveMarker(
   explicit: MarkerStyle | undefined,
-  arrow: PathLayerType['content']['arrow'],
+  legacyArrow: LegacyArrow | undefined,
   end: 'start' | 'end',
 ): MarkerStyle {
   if (explicit) return explicit;
-  const wants = arrow === 'both' || arrow === end;
+  const wants = legacyArrow === 'both' || legacyArrow === end;
   return wants ? 'arrow' : 'none';
 }
 
 export function PathLayer({ layer, viewport, blockTime }: PathLayerProps) {
   const { content, animation, id } = layer;
+  const defsId = `${useId().replace(/:/g, '')}-${id}`;
   const d = effectivePath(layer, viewport);
   const stroke = content.stroke ?? '#1e293b';
   const strokeWidth = content.strokeWidth ?? 2;
-  const { fill, def: fillDef } = resolveFill(id, content.fill ?? 'none', content.gradient);
+  const { fill, def: fillDef } = resolveFill(defsId, content.fill ?? 'none', content.gradient);
   // `borderStyle` (named shapes) takes precedence over a raw `dasharray`.
   const dash = content.borderStyle
     ? borderDashArray(content.borderStyle, strokeWidth)
     : content.dasharray;
   const animStyle = getAnimationStyle(animation, blockTime);
 
-  const startId = `marker-start-${id}`;
-  const endId = `marker-end-${id}`;
-  const start = markerPath(effectiveMarker(content.startMarker, content.arrow, 'start'), 'start');
-  const end = markerPath(effectiveMarker(content.endMarker, content.arrow, 'end'), 'end');
+  const startId = `marker-start-${defsId}`;
+  const endId = `marker-end-${defsId}`;
+  const legacyArrow = readLegacyArrow(content);
+  const start = markerPath(effectiveMarker(content.startMarker, legacyArrow, 'start'), 'start');
+  const end = markerPath(effectiveMarker(content.endMarker, legacyArrow, 'end'), 'end');
 
   return (
     <g

package/src/layers/ShapeLayer.tsx

@@ -5,6 +5,7 @@
  * Useful for visual accents, dividers, and background elements.
  */
 
+import { useId } from 'react';
 import type { ShapeLayer as ShapeLayerType } from '@bendyline/squisq/schemas';
 import { getAnimationStyle } from '../utils/animationUtils';
 import { resolveValue, getAnchorOffset } from '../utils/layerUtils';
@@ -18,8 +19,17 @@ interface ShapeLayerProps {
   blockTime: number;
 }
 
+/**
+ * Full-bleed HTML and SVG layers can be rasterized on slightly different
+ * subpixel boundaries. Extend unbordered background rectangles beyond the
+ * viewport so an image cannot peek through at the outermost pixel; the block
+ * renderer clips the combined layer stack back to the viewBox.
+ */
+const FULL_BLEED_OVERSCAN = 1;
+
 export function ShapeLayer({ layer, viewport, blockTime }: ShapeLayerProps) {
   const { content, position, animation } = layer;
+  const defsId = `${useId().replace(/:/g, '')}-${layer.id}`;
 
   // Resolve position values to pixels
   const rawX = resolveValue(position.x, viewport.width);
@@ -32,6 +42,20 @@ export function ShapeLayer({ layer, viewport, blockTime }: ShapeLayerProps) {
   const x = rawX + anchorOffset.x;
   const y = rawY + anchorOffset.y;
 
+  const isUnborderedFullBleedRect =
+    content.shape === 'rect' &&
+    x === 0 &&
+    y === 0 &&
+    width === viewport.width &&
+    height === viewport.height &&
+    !content.stroke &&
+    !content.borderRadius;
+  const overscan = isUnborderedFullBleedRect ? FULL_BLEED_OVERSCAN : 0;
+  const paintX = x - overscan;
+  const paintY = y - overscan;
+  const paintWidth = width + overscan * 2;
+  const paintHeight = height + overscan * 2;
+
   // Get animation styles
   const animStyle = getAnimationStyle(animation, blockTime);
 
@@ -49,11 +73,11 @@ export function ShapeLayer({ layer, viewport, blockTime }: ShapeLayerProps) {
         style={animStyle.style}
         data-layer-id={layer.id}
       >
-        <foreignObject x={x} y={y} width={width} height={height}>
+        <foreignObject x={paintX} y={paintY} width={paintWidth} height={paintHeight}>
           <div
             style={{
-              width: `${width}px`,
-              height: `${height}px`,
+              width: `${paintWidth}px`,
+              height: `${paintHeight}px`,
               background: fill,
               borderRadius: content.borderRadius ? `${content.borderRadius}px` : undefined,
               pointerEvents: 'none',
@@ -65,12 +89,12 @@ export function ShapeLayer({ layer, viewport, blockTime }: ShapeLayerProps) {
   }
 
   const { fill: fillValue, def: fillDef } = resolveFill(
-    layer.id,
+    defsId,
     fill,
     content.gradient,
     content.pattern,
   );
-  const { filterAttr, def: filterDef } = resolveShapeFilter(layer.id, content.filter);
+  const { filterAttr, def: filterDef } = resolveShapeFilter(defsId, content.filter);
   const dash = borderDashArray(content.borderStyle, content.strokeWidth);
 
   // Common style props for native SVG shapes. `line` is stroke-only.
@@ -97,10 +121,10 @@ export function ShapeLayer({ layer, viewport, blockTime }: ShapeLayerProps) {
       )}
       {content.shape === 'rect' && (
         <rect
-          x={x}
-          y={y}
-          width={width}
-          height={height}
+          x={paintX}
+          y={paintY}
+          width={paintWidth}
+          height={paintHeight}
           rx={content.borderRadius}
           ry={content.borderRadius}
           {...shapeProps}

package/src/layers/TextLayer.tsx

@@ -16,7 +16,7 @@
  *    PDF bypasses SVG) and already used by Video/Table layers.
  */
 
-import { useMemo, type CSSProperties } from 'react';
+import { useId, useMemo, type CSSProperties } from 'react';
 import type { TextLayer as TextLayerType } from '@bendyline/squisq/schemas';
 import { DEFAULT_DOC_FONT } from '@bendyline/squisq/schemas';
 import {
@@ -165,6 +165,7 @@ function IconTextLayer({ layer, viewport, blockTime }: TextLayerProps) {
 }
 
 function PlainTextLayer({ layer, viewport, blockTime }: TextLayerProps) {
+  const defsId = `${useId().replace(/:/g, '')}-${layer.id}`;
   const { content, position, animation } = layer;
   const { text, style } = content;
 
@@ -225,7 +226,7 @@ function PlainTextLayer({ layer, viewport, blockTime }: TextLayerProps) {
   };
 
   // Add shadow filter if requested
-  const filterId = style.shadow ? `shadow-${layer.id}` : undefined;
+  const filterId = style.shadow ? `shadow-${defsId}` : undefined;
 
   return (
     <g className={`block-layer block-layer--text ${animStyle.className}`} data-layer-id={layer.id}>
@@ -244,7 +245,7 @@ function PlainTextLayer({ layer, viewport, blockTime }: TextLayerProps) {
           rectangle. Without a box we fall back to a snug rect hugging the
           text (legacy behavior for point-anchored text). */}
       <TextBox
-        layerId={layer.id}
+        layerId={defsId}
         style={style}
         box={
           boxWidth != null && boxHeight != null

package/src/layers/TreeLayer.tsx

@@ -0,0 +1,167 @@
+/**
+ * TreeLayer Component
+ *
+ * Renders a hierarchical treeview inside an SVG block via a <foreignObject>
+ * (same technique as TableLayer) — a filesystem-style outline with
+ * folder/file icons, indentation guide rails, and collapse chevrons.
+ *
+ * Interactive in the live React player: clicking a folder chevron
+ * collapses/expands it (local component state, default fully expanded).
+ * Headless frame / PDF capture renders the default expanded DOM statically,
+ * so exports are deterministic.
+ */
+
+import { useState } from 'react';
+import type { TreeLayer as TreeLayerType, TreeLayerItem } from '@bendyline/squisq/schemas';
+import { resolveValue, getAnchorOffset } from '../utils/layerUtils';
+import { getAnimationStyle } from '../utils/animationUtils';
+
+interface TreeLayerProps {
+  layer: TreeLayerType;
+  viewport: { width: number; height: number };
+  blockTime: number;
+}
+
+/** FontAwesome class from a bare name (`folder`) or qualified (`fa-solid:folder`). */
+function faClass(token: string | undefined, fallback: string): string {
+  const name = token && token.trim() ? token.trim() : fallback;
+  const colon = name.indexOf(':');
+  if (colon > 0) {
+    const family = name.slice(0, colon).replace(/^fa-/, '');
+    return `fa-${family} fa-${name.slice(colon + 1)}`;
+  }
+  return `fa-solid fa-${name}`;
+}
+
+export function TreeLayer({ layer, viewport, blockTime }: TreeLayerProps) {
+  const { content, position, animation } = layer;
+  const { items, style } = content;
+
+  const x = resolveValue(position.x, viewport.width);
+  const y = resolveValue(position.y, viewport.height);
+  const width = position.width ? resolveValue(position.width, viewport.width) : viewport.width;
+  const height = position.height ? resolveValue(position.height, viewport.height) : viewport.height;
+  const offset = getAnchorOffset(position.anchor, width, height);
+  const animStyle = animation ? getAnimationStyle(animation, blockTime) : {};
+
+  return (
+    <foreignObject
+      x={x + offset.x}
+      y={y + offset.y}
+      width={width}
+      height={height}
+      style={animStyle}
+    >
+      <div
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        {...({ xmlns: 'http://www.w3.org/1999/xhtml' } as any)}
+        className="squisq-treelayer"
+        style={{
+          width: `${width}px`,
+          height: `${height}px`,
+          display: 'flex',
+          flexDirection: 'column',
+          justifyContent: 'center',
+          padding: '24px 32px',
+          boxSizing: 'border-box',
+          fontFamily: style.fontFamily ?? 'system-ui, sans-serif',
+          fontSize: `${style.fontSize}px`,
+          lineHeight: 1.7,
+          overflow: 'hidden',
+        }}
+      >
+        <TreeList items={items} depth={0} style={style} />
+      </div>
+    </foreignObject>
+  );
+}
+
+function TreeList({
+  items,
+  depth,
+  style,
+}: {
+  items: TreeLayerItem[];
+  depth: number;
+  style: TreeLayerType['content']['style'];
+}) {
+  return (
+    <ul
+      style={{
+        listStyle: 'none',
+        margin: 0,
+        padding: 0,
+        paddingLeft: depth === 0 ? 0 : `${style.indentPx}px`,
+        borderLeft: depth === 0 ? 'none' : `1px solid ${style.connectorColor}`,
+      }}
+    >
+      {items.map((item) => (
+        <TreeRow key={item.id} item={item} style={style} />
+      ))}
+    </ul>
+  );
+}
+
+function TreeRow({
+  item,
+  style,
+}: {
+  item: TreeLayerItem;
+  style: TreeLayerType['content']['style'];
+}) {
+  const hasChildren = item.children.length > 0;
+  const [collapsed, setCollapsed] = useState(false);
+  const isDir = item.isDir || hasChildren;
+  const iconCls = isDir
+    ? faClass(style.folderIcon, collapsed ? 'folder' : 'folder-open')
+    : faClass(style.fileIcon, 'file');
+
+  return (
+    <li style={{ position: 'relative' }}>
+      <div style={{ display: 'flex', alignItems: 'baseline', gap: '8px', padding: '1px 0' }}>
+        {hasChildren ? (
+          <button
+            type="button"
+            aria-label={collapsed ? 'Expand' : 'Collapse'}
+            onClick={() => setCollapsed((c) => !c)}
+            style={{
+              flex: '0 0 auto',
+              width: '1em',
+              border: 'none',
+              background: 'transparent',
+              cursor: 'pointer',
+              color: style.connectorColor,
+              padding: 0,
+              fontSize: '0.8em',
+            }}
+          >
+            <i
+              className={`fa-solid ${collapsed ? 'fa-chevron-right' : 'fa-chevron-down'}`}
+              aria-hidden="true"
+            />
+          </button>
+        ) : (
+          <span style={{ flex: '0 0 auto', width: '1em' }} />
+        )}
+        <i
+          className={iconCls}
+          aria-hidden="true"
+          style={{ flex: '0 0 auto', color: style.iconColor, width: '1.2em', textAlign: 'center' }}
+        />
+        <span
+          style={{ color: isDir ? style.dirColor : style.rowColor, fontWeight: isDir ? 600 : 400 }}
+        >
+          {item.label}
+        </span>
+        {item.comment ? (
+          <span style={{ color: style.commentColor, fontSize: '0.85em', fontStyle: 'italic' }}>
+            {item.comment}
+          </span>
+        ) : null}
+      </div>
+      {hasChildren && !collapsed ? (
+        <TreeList items={item.children} depth={1} style={style} />
+      ) : null}
+    </li>
+  );
+}

package/src/layers/VideoLayer.tsx

@@ -26,6 +26,8 @@ import type { VideoLayer as VideoLayerType } from '@bendyline/squisq/schemas';
 import { useMediaUrl } from '../hooks/MediaContext';
 import { resolveValue, getAnchorOffset } from '../utils/layerUtils';
 
+const VIDEO_SYNC_DRIFT_SECONDS = 0.2;
+
 interface VideoLayerProps {
   layer: VideoLayerType;
   /** Base path for resolving relative video URLs */
@@ -100,22 +102,34 @@ export function VideoLayer({ layer, basePath, viewport, blockTime, isPlaying }:
       video.pause();
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps -- isPlaying is handled by the separate sync effect below
-  }, [content.src, content.clipStart, content.clipEnd]);
+  }, [src, content.clipStart, content.clipEnd]);
 
-  // Sync video play/pause with doc playback state, honoring the startAt gate.
+  // Sync video time + play/pause with the doc clock, honoring the startAt
+  // gate. The time correction matters when a synchronized audience player is
+  // opened partway through a block: its video must join at the main player's
+  // current frame rather than restarting from clipStart.
   useEffect(() => {
     const video = videoRef.current;
     if (!video || !hasStartedRef.current) return;
 
+    const targetTime = gated
+      ? content.clipStart
+      : Math.min(content.clipEnd, content.clipStart + Math.max(0, blockTime - startAt));
+    if (Math.abs(video.currentTime - targetTime) > VIDEO_SYNC_DRIFT_SECONDS) {
+      video.currentTime = targetTime;
+    }
+
     // Before the clip's startAt offset, hold at the in-point.
     if (gated) {
       video.pause();
-      video.currentTime = content.clipStart;
       return;
     }
 
-    // Don't resume if clip has already reached its end
-    if (video.currentTime >= content.clipEnd) return;
+    // Don't resume if the document clock has already reached the clip end.
+    if (targetTime >= content.clipEnd) {
+      video.pause();
+      return;
+    }
 
     if (isPlaying) {
       const playPromise = video.play();
@@ -125,7 +139,7 @@ export function VideoLayer({ layer, basePath, viewport, blockTime, isPlaying }:
     } else {
       video.pause();
     }
-  }, [isPlaying, gated, content.clipStart, content.clipEnd]);
+  }, [isPlaying, gated, blockTime, startAt, src, content.clipStart, content.clipEnd]);
 
   return (
     <g className="block-layer block-layer--video" data-layer-id={layer.id}>

package/src/standalone-entry.tsx

@@ -12,10 +12,12 @@
  *   <script src="squisq-player.iife.js"></script>
  *   <div id="root"></div>
  *   <script>
- *     SquisqPlayer.mount(document.getElementById('root'), docJson, {
+ *     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>
  */
 
@@ -23,6 +25,7 @@ import { createElement } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import type { Doc, MediaProvider } from '@bendyline/squisq/schemas';
 import type { Theme } from '@bendyline/squisq/schemas';
+import type { SquisqRenderAPI } from './types';
 import { DocPlayer } from './DocPlayer';
 import { LinearDocView } from './LinearDocView';
 import { MediaContext } from './hooks/MediaContext';
@@ -54,15 +57,37 @@ export interface MountOptions {
   /** Auto-play on mount (only for slideshow mode, default: false) */
   autoPlay?: boolean;
   /**
-   * Enable render mode for headless frame capture.
-   * Exposes window.seekTo(), getDuration(), getCaptions(), etc.
-   * Disables controls and auto-play. Used by Playwright video export.
+   * 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}. */
+export 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;
+}
+
 // ── CSS Injection ──────────────────────────────────────────────────
 
 let cssInjected = false;
@@ -167,6 +192,50 @@ function rewriteAudioUrls(doc: Doc, audioMap: Record<string, string>): Doc {
 
 const roots = new WeakMap<Element, Root>();
 
+interface InternalPlayerHandle extends SquisqPlayerHandle {
+  setRenderAPI(api: SquisqRenderAPI | null): void;
+  cancel(): void;
+}
+
+const handles = new WeakMap<Element, InternalPlayerHandle>();
+
+function createPlayerHandle(element: Element, expectsRenderAPI: boolean): InternalPlayerHandle {
+  let currentAPI: SquisqRenderAPI | null = null;
+  let active = true;
+  let settled = false;
+  let resolveRenderAPI!: (api: SquisqRenderAPI | null) => void;
+  const renderAPI = new Promise<SquisqRenderAPI | null>((resolve) => {
+    resolveRenderAPI = resolve;
+  });
+
+  const settle = (api: SquisqRenderAPI | null) => {
+    if (settled) return;
+    settled = true;
+    resolveRenderAPI(api);
+  };
+  if (!expectsRenderAPI) settle(null);
+
+  const handle: InternalPlayerHandle = {
+    element,
+    renderAPI,
+    getRenderAPI: () => currentAPI,
+    unmount: () => {
+      if (handles.get(element) === handle) unmount(element);
+    },
+    setRenderAPI(api) {
+      if (!active) return;
+      currentAPI = api;
+      if (api) settle(api);
+    },
+    cancel() {
+      active = false;
+      currentAPI = null;
+      settle(null);
+    },
+  };
+  return handle;
+}
+
 // ── Public API ─────────────────────────────────────────────────────
 
 /**
@@ -176,7 +245,7 @@ const roots = new WeakMap<Element, Root>();
  * @param doc - A Doc object (parsed JSON)
  * @param options - Rendering options
  */
-export function mount(element: Element, doc: Doc, options: MountOptions = {}): void {
+export function mount(element: Element, doc: Doc, options: MountOptions = {}): SquisqPlayerHandle {
   injectCss();
 
   const {
@@ -187,7 +256,9 @@ export function mount(element: Element, doc: Doc, options: MountOptions = {}): v
     autoPlay = false,
     theme,
     renderMode = false,
+    animationsEnabled = true,
     captionStyle,
+    globalKeyboardShortcuts = true,
   } = options;
 
   // Rewrite audio URLs if map provided
@@ -195,6 +266,9 @@ export function mount(element: Element, doc: Doc, options: MountOptions = {}): v
 
   // Build the media provider if images are provided
   const mediaProvider = images ? createInlineMediaProvider(images, basePath) : null;
+  handles.get(element)?.cancel();
+  const handle = createPlayerHandle(element, mode === 'slideshow' && renderMode);
+  handles.set(element, handle);
 
   let content: ReturnType<typeof createElement>;
 
@@ -203,6 +277,8 @@ export function mount(element: Element, doc: Doc, options: MountOptions = {}): v
       doc: finalDoc,
       basePath,
       theme,
+      animationsEnabled,
+      globalKeyboardShortcuts,
     });
   } else {
     content = createElement(DocPlayer, {
@@ -212,9 +288,12 @@ export function mount(element: Element, doc: Doc, options: MountOptions = {}): v
       autoPlay: renderMode ? false : autoPlay,
       showControls: !renderMode,
       renderMode,
+      animationsEnabled,
       theme,
       captionsEnabled: !!captionStyle,
       captionStyle: captionStyle ?? 'standard',
+      globalKeyboardShortcuts,
+      onRenderAPIReady: (api: SquisqRenderAPI | null) => handle.setRenderAPI(api),
     });
   }
 
@@ -230,23 +309,21 @@ export function mount(element: Element, doc: Doc, options: MountOptions = {}): v
     roots.set(element, root);
   }
   root.render(content);
+  return handle;
 }
 
-/**
- * Mount a static scrollable document view (alias for mount with mode='static').
- */
-export function mountStatic(
-  element: Element,
-  doc: Doc,
-  options: Omit<MountOptions, 'mode'> = {},
-): void {
-  mount(element, doc, { ...options, mode: 'static' });
+/** Return the handle for the player mounted into `element`, if any. */
+export function getHandle(element: Element): SquisqPlayerHandle | undefined {
+  return handles.get(element);
 }
 
 /**
  * Unmount a previously mounted SquisqPlayer from an element.
  */
 export function unmount(element: Element): void {
+  const handle = handles.get(element);
+  handle?.cancel();
+  handles.delete(element);
   const root = roots.get(element);
   if (root) {
     root.unmount();