@bendyline/squisq-react 2.0.1 → 2.2.0

package/src/layers/TreeLayer.tsx

@@ -1,167 +0,0 @@
-/**
- * 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

@@ -1,171 +0,0 @@
-/**
- * VideoLayer Component
- *
- * Renders a video clip layer within an SVG block. Uses an HTML5 <video> element
- * inside a <foreignObject> (same pattern as ImageLayer for cover-mode images).
- * Videos are always muted — narration audio is the only sound track.
- *
- * Two modes of operation:
- * 1. Normal playback: Video auto-plays from clipStart to clipEnd on mount,
- *    pausing when the clip ends or when the block is no longer active.
- * 2. Render/seekTo mode (Playwright frame capture): Video is paused and seeked
- *    programmatically via data attributes read by DocPlayer's seekTo handler.
- *
- * The <video> element carries data-clip-start and data-clip-end attributes so
- * the seekTo handler can calculate the correct video time for any doc time.
- *
- * Related Files:
- * - schemas/Doc.ts — VideoLayer type definition
- * - shared/doc/templates/videoWithCaption.ts — template producing VideoLayers
- * - site/src/components/doc/DocPlayer.tsx — seekTo handler for video sync
- * - site/src/components/doc/layers/ImageLayer.tsx — similar foreignObject pattern
- */
-
-import { useRef, useEffect } from 'react';
-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 */
-  basePath: string;
-  /** Viewport dimensions for percentage calculations */
-  viewport: { width: number; height: number };
-  /** Current time relative to block start (for playback sync) */
-  blockTime: number;
-  /** Whether the doc is currently playing */
-  isPlaying?: boolean;
-}
-
-export function VideoLayer({ layer, basePath, viewport, blockTime, isPlaying }: VideoLayerProps) {
-  const { content, position } = layer;
-  const videoRef = useRef<HTMLVideoElement>(null);
-  const hasStartedRef = useRef(false);
-
-  // Seconds into the block before this clip begins. Until then the video is
-  // held (paused) at its in-point so a `startAt` offset reads as a delay.
-  const startAt = content.startAt ?? 0;
-  const gated = blockTime < startAt;
-
-  // Resolve position values to pixels
-  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;
-
-  // Apply anchor offset
-  const offset = getAnchorOffset(position.anchor, width, height);
-  const finalX = x + offset.x;
-  const finalY = y + offset.y;
-
-  // Resolve video URL via MediaProvider (if available), falling back to basePath
-  const src = useMediaUrl(content.src, basePath);
-
-  // Always call the hook (Rules of Hooks), but pass empty string when no poster
-  const resolvedPoster = useMediaUrl(content.posterSrc || '', basePath);
-  const posterSrc = content.posterSrc ? resolvedPoster : undefined;
-
-  // On mount: seek to clipStart and set up clipEnd boundary.
-  // The video will be muted and play silently alongside the narration.
-  useEffect(() => {
-    const video = videoRef.current;
-    if (!video) return;
-
-    // Set initial time to clipStart
-    video.currentTime = content.clipStart;
-    hasStartedRef.current = true;
-
-    // Start playing if doc is already playing
-    if (isPlaying) {
-      const playPromise = video.play();
-      if (playPromise) {
-        playPromise.catch(() => {
-          // Autoplay blocked — fine for Playwright seekTo mode
-        });
-      }
-    }
-
-    // Monitor timeupdate to pause at clipEnd
-    const handleTimeUpdate = () => {
-      if (video.currentTime >= content.clipEnd) {
-        video.pause();
-        video.currentTime = content.clipEnd;
-      }
-    };
-
-    video.addEventListener('timeupdate', handleTimeUpdate);
-    return () => {
-      video.removeEventListener('timeupdate', handleTimeUpdate);
-      video.pause();
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- isPlaying is handled by the separate sync effect below
-  }, [src, content.clipStart, content.clipEnd]);
-
-  // 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();
-      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();
-      if (playPromise) {
-        playPromise.catch(() => {});
-      }
-    } else {
-      video.pause();
-    }
-  }, [isPlaying, gated, blockTime, startAt, src, content.clipStart, content.clipEnd]);
-
-  return (
-    <g className="block-layer block-layer--video" data-layer-id={layer.id}>
-      <foreignObject x={finalX} y={finalY} width={width} height={height}>
-        <video
-          ref={videoRef}
-          src={src}
-          poster={posterSrc}
-          muted
-          playsInline
-          preload="auto"
-          data-clip-start={content.clipStart}
-          data-clip-end={content.clipEnd}
-          data-start-at={startAt}
-          style={{
-            width: `${width}px`,
-            height: `${height}px`,
-            objectFit: content.fit || 'cover',
-            objectPosition: 'center',
-            display: 'block',
-            pointerEvents: 'none',
-          }}
-        />
-      </foreignObject>
-    </g>
-  );
-}
-
-export default VideoLayer;

package/src/layers/index.ts

@@ -1,6 +0,0 @@
-export { ImageLayer } from './ImageLayer';
-export { TextLayer } from './TextLayer';
-export { ShapeLayer } from './ShapeLayer';
-export { PathLayer } from './PathLayer';
-export { VideoLayer } from './VideoLayer';
-export { MapLayer } from './MapLayer';

package/src/standalone-entry.tsx

@@ -1,337 +0,0 @@
-/**
- * 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>
- */
-
-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';
-
-// CSS is loaded as text via esbuild's text loader (configured in tsup.standalone.config.ts)
-// @ts-expect-error — .css import returns a string when esbuild uses 'text' loader (standalone build only)
-import animationCss from './styles/doc-animations.css';
-
-// ── Types ──────────────────────────────────────────────────────────
-
-export 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}. */
-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;
-
-function injectCss(): void {
-  if (cssInjected || typeof document === 'undefined') return;
-  const style = document.createElement('style');
-  style.setAttribute('data-squisq-player', 'animations');
-  style.textContent = animationCss;
-  document.head.appendChild(style);
-  cssInjected = true;
-}
-
-// ── Inline Media Provider ──────────────────────────────────────────
-
-/**
- * Creates a MediaProvider that resolves URLs from an inline image map.
- * Falls back to basePath-based resolution for unknown paths.
- */
-function createInlineMediaProvider(
-  images: Record<string, string>,
-  basePath: string,
-): MediaProvider {
-  // Doc image references may not exactly match image map keys
-  // (e.g., "images/hero.jpg" vs "hero.jpg"). Build a filename-keyed
-  // lookup so resolution can fall back to basename matching.
-  const byFilename: Record<string, string> = {};
-  for (const key of Object.keys(images)) {
-    const filename = key.split('/').pop()!;
-    byFilename[filename] = images[key];
-  }
-
-  return {
-    async resolveUrl(relativePath: string): Promise<string> {
-      if (relativePath in images) return images[relativePath];
-      const stripped = relativePath.replace(/^\.\//, '');
-      if (stripped !== relativePath && stripped in images) return images[stripped];
-      const filename = relativePath.split('/').pop()!;
-      if (filename in byFilename) return byFilename[filename];
-      if (
-        relativePath.startsWith('http') ||
-        relativePath.startsWith('data:') ||
-        relativePath.startsWith('blob:')
-      ) {
-        return relativePath;
-      }
-      return `${basePath}/${relativePath}`;
-    },
-    async listMedia() {
-      return Object.keys(images).map((name) => ({
-        name,
-        mimeType: inferMimeType(name),
-        size: 0,
-      }));
-    },
-    async addMedia() {
-      throw new Error('Standalone player is read-only');
-    },
-    async removeMedia() {
-      throw new Error('Standalone player is read-only');
-    },
-    dispose() {
-      // no-op
-    },
-  };
-}
-
-function inferMimeType(filename: string): string {
-  const ext = filename.split('.').pop()?.toLowerCase() ?? '';
-  const map: Record<string, string> = {
-    jpg: 'image/jpeg',
-    jpeg: 'image/jpeg',
-    png: 'image/png',
-    gif: 'image/gif',
-    webp: 'image/webp',
-    svg: 'image/svg+xml',
-    mp3: 'audio/mpeg',
-    mp4: 'video/mp4',
-    webm: 'video/webm',
-  };
-  return map[ext] ?? 'application/octet-stream';
-}
-
-// ── Audio Rewriting ────────────────────────────────────────────────
-
-/**
- * Rewrite audio segment URLs in a Doc if an audio map is provided.
- * Returns a shallow-modified copy — does not mutate the original.
- */
-function rewriteAudioUrls(doc: Doc, audioMap: Record<string, string>): Doc {
-  if (!doc.audio?.segments?.length) return doc;
-
-  const segments = doc.audio.segments.map((seg) => {
-    const resolved = audioMap[seg.name] ?? audioMap[seg.src] ?? seg.src;
-    return { ...seg, src: resolved };
-  });
-
-  return { ...doc, audio: { ...doc.audio, segments } };
-}
-
-// ── Root Tracking ──────────────────────────────────────────────────
-
-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 ─────────────────────────────────────────────────────
-
-/**
- * Mount a SquisqPlayer into a DOM element.
- *
- * @param element - The DOM element to render into
- * @param doc - A Doc object (parsed JSON)
- * @param options - Rendering options
- */
-export function mount(element: Element, doc: Doc, options: MountOptions = {}): SquisqPlayerHandle {
-  injectCss();
-
-  const {
-    mode = 'slideshow',
-    basePath = '.',
-    images,
-    audio,
-    autoPlay = false,
-    theme,
-    renderMode = false,
-    animationsEnabled = true,
-    captionStyle,
-    globalKeyboardShortcuts = true,
-  } = options;
-
-  // Rewrite audio URLs if map provided
-  const finalDoc = audio ? rewriteAudioUrls(doc, audio) : doc;
-
-  // 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>;
-
-  if (mode === 'static') {
-    content = createElement(LinearDocView, {
-      doc: finalDoc,
-      basePath,
-      theme,
-      animationsEnabled,
-      globalKeyboardShortcuts,
-    });
-  } else {
-    content = createElement(DocPlayer, {
-      doc: finalDoc,
-      basePath,
-      displayMode: 'slideshow',
-      autoPlay: renderMode ? false : autoPlay,
-      showControls: !renderMode,
-      renderMode,
-      animationsEnabled,
-      theme,
-      captionsEnabled: !!captionStyle,
-      captionStyle: captionStyle ?? 'standard',
-      globalKeyboardShortcuts,
-      onRenderAPIReady: (api: SquisqRenderAPI | null) => handle.setRenderAPI(api),
-    });
-  }
-
-  // Wrap in MediaContext if provider is available
-  if (mediaProvider) {
-    content = createElement(MediaContext.Provider, { value: mediaProvider }, content);
-  }
-
-  // Create or reuse React root
-  let root = roots.get(element);
-  if (!root) {
-    root = createRoot(element);
-    roots.set(element, root);
-  }
-  root.render(content);
-  return handle;
-}
-
-/** 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();
-    roots.delete(element);
-  }
-}
-
-/** Package version — injected at build time via esbuild define */
-declare const __SQUISQ_VERSION__: string;
-export const version: string =
-  typeof __SQUISQ_VERSION__ !== 'undefined' ? __SQUISQ_VERSION__ : '0.0.0';

package/src/standalone-source.d.ts

@@ -1,10 +0,0 @@
-/**
- * Type declaration for the `@bendyline/squisq-react/standalone-source`
- * subpath export. The runtime JS file is generated by
- * `scripts/generate-standalone-source.mjs` after the IIFE build emits
- * `dist/squisq-player.global.js`, but the type surface is constant —
- * it always exposes the same single `string` constant — so the
- * declaration lives in source so consumers can typecheck without
- * having had to build this package first.
- */
-export declare const PLAYER_BUNDLE: string;