@bendyline/squisq-react 1.4.1 → 2.0.0

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();

package/src/types.ts

@@ -33,8 +33,12 @@ export 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.
  */
-export type DisplayMode = 'video' | 'slideshow' | 'linear' | 'page';
+export type DisplayMode = 'video' | 'slideshow' | 'linear' | 'page' | 'narrate';
 
 /**
  * Caption display style.
@@ -68,6 +72,8 @@ export 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;
@@ -82,6 +88,12 @@ export interface PlaybackState {
   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 */
@@ -140,15 +152,15 @@ export interface RenderChapterInfo {
 }
 
 /**
- * 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);
  * ```
  */
 export interface SquisqRenderAPI {
@@ -163,12 +175,6 @@ export interface SquisqRenderAPI {
   hasCoverBlock: () => boolean;
 }
 
-/**
- * Window augmented with optional SquisqRenderAPI properties.
- * Each property is optional because they're only present in render/debug mode.
- */
-export type SquisqWindow = Window & typeof globalThis & Partial<SquisqRenderAPI>;
-
 /** Format time in seconds to MM:SS string */
 export function formatTime(seconds: number): string {
   const mins = Math.floor(seconds / 60);