@bendyline/squisq-react 0.1.2

package/src/layers/TextLayer.tsx

@@ -0,0 +1,197 @@
+/**
+ * TextLayer Component
+ *
+ * Renders a text layer within an SVG block. Supports multi-line text,
+ * styling options (font, color, shadow), and animations like fadeIn
+ * and typewriter effects.
+ *
+ * Text is rendered using SVG <text> elements with <tspan> for line breaks.
+ */
+
+import type { TextLayer as TextLayerType } from '@bendyline/squisq/schemas';
+import { DEFAULT_DOC_FONT } from '@bendyline/squisq/schemas';
+import { getAnimationStyle } from '../utils/animationUtils';
+import { resolveValue } from '../utils/layerUtils';
+
+interface TextLayerProps {
+  layer: TextLayerType;
+  /** Viewport dimensions for percentage calculations */
+  viewport: { width: number; height: number };
+  /** Current time relative to block start */
+  blockTime: number;
+}
+
+export function TextLayer({ layer, viewport, blockTime }: TextLayerProps) {
+  const { content, position, animation } = layer;
+  const { text, style } = content;
+
+  // Resolve position values to pixels
+  const x = resolveValue(position.x, viewport.width);
+  const y = resolveValue(position.y, viewport.height);
+  const maxWidth = position.width ? resolveValue(position.width, viewport.width) : undefined;
+
+  // Apply anchor offset for text alignment
+  const textAnchor = getTextAnchor(style.textAlign, position.anchor);
+  const dominantBaseline = getDominantBaseline(position.anchor);
+
+  // Get animation styles
+  const animStyle = getAnimationStyle(animation, blockTime);
+
+  // Split text into lines, and wrap if maxWidth is specified
+  const rawLines = text.split('\n');
+  let lines = maxWidth
+    ? rawLines.reduce<string[]>(
+        (acc, line) => acc.concat(wrapText(line, style.fontSize, maxWidth)),
+        [],
+      )
+    : rawLines;
+
+  // Truncate to maxLines if specified
+  if (style.maxLines && lines.length > style.maxLines) {
+    lines = lines.slice(0, style.maxLines);
+    // Add ellipsis to last visible line
+    const last = lines[lines.length - 1];
+    lines[lines.length - 1] = last.replace(/\s*$/, '') + '...';
+  }
+  const lineHeight = style.lineHeight || 1.4;
+  const lineHeightPx = style.fontSize * lineHeight;
+
+  // Build text styles
+  const textStyles: Record<string, string | number> = {
+    fontSize: `${style.fontSize}px`,
+    fontFamily: style.fontFamily || DEFAULT_DOC_FONT,
+    fontWeight: style.fontWeight || 'normal',
+    fill: style.color,
+    ...animStyle.style,
+  };
+
+  // Add shadow filter if requested
+  const filterId = style.shadow ? `shadow-${layer.id}` : undefined;
+
+  return (
+    <g className={`block-layer block-layer--text ${animStyle.className}`} data-layer-id={layer.id}>
+      {/* Shadow filter definition */}
+      {style.shadow && (
+        <defs>
+          <filter id={filterId} x="-20%" y="-20%" width="140%" height="140%">
+            <feDropShadow dx="0" dy="2" stdDeviation="3" floodColor="rgba(0,0,0,0.7)" />
+          </filter>
+        </defs>
+      )}
+
+      {/* Background box if specified */}
+      {style.background && (
+        <rect
+          x={x - (style.padding || 16)}
+          y={y - style.fontSize - (style.padding || 16)}
+          width={getTextBoxWidth(lines, style) + (style.padding || 16) * 2}
+          height={lines.length * lineHeightPx + (style.padding || 16) * 2}
+          fill={style.background}
+          rx={4}
+          ry={4}
+        />
+      )}
+
+      {/* Text element with tspans for each line */}
+      <text
+        x={x}
+        y={y}
+        textAnchor={textAnchor as 'start' | 'middle' | 'end'}
+        dominantBaseline={dominantBaseline as 'text-before-edge' | 'middle' | 'text-after-edge'}
+        style={textStyles}
+        filter={filterId ? `url(#${filterId})` : undefined}
+      >
+        {lines.map((line, i) => (
+          <tspan key={i} x={x} dy={i === 0 ? 0 : lineHeightPx}>
+            {line || '\u00A0'} {/* Non-breaking space for empty lines */}
+          </tspan>
+        ))}
+      </text>
+    </g>
+  );
+}
+
+/**
+ * Map text alignment to SVG text-anchor.
+ */
+function getTextAnchor(align?: 'left' | 'center' | 'right', anchor?: string): string {
+  // Explicit alignment takes precedence
+  if (align === 'center') return 'middle';
+  if (align === 'right') return 'end';
+  if (align === 'left') return 'start';
+
+  // Otherwise infer from position anchor
+  if (anchor?.includes('right')) return 'end';
+  if (anchor === 'center') return 'middle';
+  return 'start';
+}
+
+/**
+ * Map position anchor to SVG dominant-baseline.
+ */
+function getDominantBaseline(anchor?: string): string {
+  if (anchor?.includes('bottom')) return 'text-after-edge';
+  if (anchor === 'center') return 'middle';
+  return 'text-before-edge';
+}
+
+/**
+ * Estimate text box width based on content (rough approximation).
+ */
+function getTextBoxWidth(lines: string[], style: { fontSize: number }): number {
+  const maxLineLength = Math.max(...lines.map((l) => l.length));
+  // Rough estimate: average character width is ~0.5 * fontSize
+  return maxLineLength * style.fontSize * 0.55;
+}
+
+/**
+ * Wrap text to fit within a maximum width.
+ * Uses character-based estimation for line breaking.
+ */
+function wrapText(text: string, fontSize: number, maxWidth: number): string[] {
+  if (!text.trim()) return [''];
+
+  // Estimate characters per line (average char width ~0.5 * fontSize for most fonts)
+  const avgCharWidth = fontSize * 0.5;
+  const charsPerLine = Math.floor(maxWidth / avgCharWidth);
+
+  if (charsPerLine <= 0) return [text];
+
+  const words = text.split(/\s+/);
+  const lines: string[] = [];
+  let currentLine = '';
+
+  for (const word of words) {
+    const testLine = currentLine ? `${currentLine} ${word}` : word;
+
+    if (testLine.length <= charsPerLine) {
+      currentLine = testLine;
+    } else {
+      // Current line is full, start new line
+      if (currentLine) {
+        lines.push(currentLine);
+      }
+      // Handle words longer than a line
+      if (word.length > charsPerLine) {
+        // Break long word
+        let remaining = word;
+        while (remaining.length > charsPerLine) {
+          lines.push(remaining.slice(0, charsPerLine));
+          remaining = remaining.slice(charsPerLine);
+        }
+        currentLine = remaining;
+      } else {
+        currentLine = word;
+      }
+    }
+  }
+
+  // Add remaining text
+  if (currentLine) {
+    lines.push(currentLine);
+  }
+
+  return lines.length > 0 ? lines : [''];
+}
+
+export default TextLayer;

package/src/layers/VideoLayer.tsx

@@ -0,0 +1,150 @@
+/**
+ * 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';
+
+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: _blockTime,
+  isPlaying,
+}: VideoLayerProps) {
+  const { content, position } = layer;
+  const videoRef = useRef<HTMLVideoElement>(null);
+  const hasStartedRef = useRef(false);
+
+  // 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
+  }, [content.src, content.clipStart, content.clipEnd]);
+
+  // Sync video play/pause with doc playback state
+  useEffect(() => {
+    const video = videoRef.current;
+    if (!video || !hasStartedRef.current) return;
+
+    // Don't resume if clip has already reached its end
+    if (video.currentTime >= content.clipEnd) return;
+
+    if (isPlaying) {
+      const playPromise = video.play();
+      if (playPromise) {
+        playPromise.catch(() => {});
+      }
+    } else {
+      video.pause();
+    }
+  }, [isPlaying, 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}
+          style={{
+            width: '100%',
+            height: '100%',
+            objectFit: content.fit || 'cover',
+            objectPosition: 'center',
+            display: 'block',
+            pointerEvents: 'none',
+          }}
+        />
+      </foreignObject>
+    </g>
+  );
+}
+
+export default VideoLayer;

package/src/layers/index.ts

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

package/src/standalone-entry.tsx

@@ -0,0 +1,228 @@
+/**
+ * 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>
+ *     SquisqPlayer.mount(document.getElementById('root'), docJson, {
+ *       mode: 'slideshow',
+ *       images: { 'hero.jpg': 'data:image/jpeg;base64,...' }
+ *     });
+ *   </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 { 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;
+}
+
+// ── 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 {
+  return {
+    async resolveUrl(relativePath: string): Promise<string> {
+      if (relativePath in images) return images[relativePath];
+      // Fallback to basePath
+      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>();
+
+// ── 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 = {}): void {
+  injectCss();
+
+  const { mode = 'slideshow', basePath = '.', images, audio, autoPlay = false, theme } = 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;
+
+  let content: ReturnType<typeof createElement>;
+
+  if (mode === 'static') {
+    content = createElement(LinearDocView, {
+      doc: finalDoc,
+      basePath,
+      theme,
+    });
+  } else {
+    content = createElement(DocPlayer, {
+      script: finalDoc,
+      basePath,
+      displayMode: 'slideshow',
+      autoPlay,
+      showControls: true,
+      theme,
+    });
+  }
+
+  // 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);
+}
+
+/**
+ * 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' });
+}
+
+/**
+ * Unmount a previously mounted SquisqPlayer from an element.
+ */
+export function unmount(element: Element): void {
+  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';