@bendyline/squisq-react 1.0.2 → 1.0.3

package/src/SocialCaptionOverlay.tsx

@@ -0,0 +1,254 @@
+/**
+ * SocialCaptionOverlay Component
+ *
+ * Social media-style captions (Instagram/TikTok): large centered words
+ * showing 3-5 words at a time with the currently-spoken word highlighted
+ * in the theme's primary color. Font and colors are pulled from the
+ * active theme.
+ *
+ * Words are gathered across all caption phrases into a continuous stream,
+ * then chunked into uniform groups for smooth, consistent pacing.
+ *
+ * Supports two timing modes:
+ * 1. Precise: uses per-word timestamps from CaptionPhrase.words
+ * 2. Interpolated: distributes timing evenly within each phrase
+ */
+
+import { useMemo } from 'react';
+import type { CaptionTrack, CaptionPhrase, ViewportConfig } from '@bendyline/squisq/schemas';
+import type { Theme } from '@bendyline/squisq/schemas';
+
+/** Target words per visible chunk. */
+const TARGET_CHUNK_SIZE = 4;
+const MIN_CHUNK_SIZE = 2;
+const MAX_CHUNK_SIZE = 6;
+
+/** A timed word derived from phrase data. */
+interface TimedWord {
+  text: string;
+  startTime: number;
+  endTime: number;
+}
+
+/** A chunk of words displayed together. */
+interface WordChunk {
+  words: TimedWord[];
+  startTime: number;
+  endTime: number;
+}
+
+/**
+ * Resolve per-word timing for a single phrase.
+ * Uses precise word timestamps when available, otherwise interpolates.
+ */
+function resolvePhraseTiming(phrase: CaptionPhrase): TimedWord[] {
+  // Use precise timing when available
+  if (phrase.words && phrase.words.length > 0) {
+    return phrase.words.map((w) => ({
+      text: w.text,
+      startTime: w.startTime,
+      endTime: w.endTime,
+    }));
+  }
+
+  // Interpolate: split text into words, distribute evenly
+  const rawWords = phrase.text.split(/\s+/).filter((w) => w.length > 0);
+  if (rawWords.length === 0) return [];
+
+  const duration = phrase.endTime - phrase.startTime;
+  const wordDuration = duration / rawWords.length;
+
+  return rawWords.map((text, i) => ({
+    text,
+    startTime: phrase.startTime + i * wordDuration,
+    endTime: phrase.startTime + (i + 1) * wordDuration,
+  }));
+}
+
+/**
+ * Build a continuous stream of timed words from ALL caption phrases,
+ * then group into uniform display chunks. This eliminates the "pulsy"
+ * feeling caused by per-phrase chunking with variable phrase lengths.
+ */
+function buildWordStream(captions: CaptionTrack): { words: TimedWord[]; chunks: WordChunk[] } {
+  // Gather all words across all phrases
+  const allWords: TimedWord[] = [];
+  for (const phrase of captions.phrases) {
+    allWords.push(...resolvePhraseTiming(phrase));
+  }
+
+  if (allWords.length === 0) return { words: [], chunks: [] };
+
+  // Determine uniform chunk size
+  let chunkSize = TARGET_CHUNK_SIZE;
+  if (allWords.length > chunkSize) {
+    const numChunks = Math.ceil(allWords.length / chunkSize);
+    chunkSize = Math.ceil(allWords.length / numChunks);
+    chunkSize = Math.min(MAX_CHUNK_SIZE, Math.max(MIN_CHUNK_SIZE, chunkSize));
+  } else {
+    chunkSize = Math.max(MIN_CHUNK_SIZE, allWords.length);
+  }
+
+  // Build chunks
+  const chunks: WordChunk[] = [];
+  for (let i = 0; i < allWords.length; i += chunkSize) {
+    const chunkWords = allWords.slice(i, i + chunkSize);
+    chunks.push({
+      words: chunkWords,
+      startTime: chunkWords[0].startTime,
+      endTime: chunkWords[chunkWords.length - 1].endTime,
+    });
+  }
+
+  return { words: allWords, chunks };
+}
+
+interface SocialCaptionOverlayProps {
+  captions: CaptionTrack | undefined;
+  currentTime: number;
+  enabled?: boolean;
+  theme?: Theme;
+  viewport?: ViewportConfig;
+}
+
+export function SocialCaptionOverlay({
+  captions,
+  currentTime,
+  enabled = true,
+  theme,
+  viewport,
+}: SocialCaptionOverlayProps) {
+  // Build the word stream once when captions change (memoized)
+  const { chunks } = useMemo(
+    () => (captions ? buildWordStream(captions) : { words: [], chunks: [] }),
+    [captions],
+  );
+
+  if (!enabled || chunks.length === 0) {
+    return (
+      <div
+        className="social-caption-overlay"
+        style={{
+          position: 'absolute',
+          bottom: '18%',
+          left: 0,
+          right: 0,
+          zIndex: 50,
+          pointerEvents: 'none',
+          opacity: 0,
+          transition: 'opacity 0.15s ease-in-out',
+        }}
+      />
+    );
+  }
+
+  // Find the active chunk and word using binary-style search
+  let activeChunk: WordChunk | null = null;
+  let activeWordIndex = -1;
+
+  for (const chunk of chunks) {
+    if (currentTime >= chunk.startTime && currentTime < chunk.endTime) {
+      activeChunk = chunk;
+      break;
+    }
+  }
+
+  // If between chunks (gap), show the nearest chunk
+  if (!activeChunk) {
+    for (let i = 0; i < chunks.length - 1; i++) {
+      if (currentTime >= chunks[i].endTime && currentTime < chunks[i + 1].startTime) {
+        // In a gap — show the chunk we just left (feels more natural)
+        activeChunk = chunks[i];
+        activeWordIndex = activeChunk.words.length - 1;
+        break;
+      }
+    }
+    // Past all chunks
+    if (!activeChunk && chunks.length > 0 && currentTime >= chunks[chunks.length - 1].startTime) {
+      activeChunk = chunks[chunks.length - 1];
+      activeWordIndex = activeChunk.words.length - 1;
+    }
+  }
+
+  if (!activeChunk) return null;
+
+  // Find active word within chunk (if not already set from gap handling)
+  if (activeWordIndex === -1) {
+    for (let i = 0; i < activeChunk.words.length; i++) {
+      const word = activeChunk.words[i];
+      if (currentTime >= word.startTime && currentTime < word.endTime) {
+        activeWordIndex = i;
+        break;
+      }
+    }
+    // Fallback: last word before currentTime
+    if (activeWordIndex === -1) {
+      for (let i = activeChunk.words.length - 1; i >= 0; i--) {
+        if (currentTime >= activeChunk.words[i].startTime) {
+          activeWordIndex = i;
+          break;
+        }
+      }
+    }
+    // Final fallback
+    if (activeWordIndex === -1) activeWordIndex = 0;
+  }
+
+  // Theme-derived styling
+  const primaryColor = theme?.colors?.primary ?? '#5b9bd5';
+  const fontFamily = theme?.typography?.titleFontFamily
+    ? `"${theme.typography.titleFontFamily}", system-ui, sans-serif`
+    : '"PT Serif", Georgia, serif';
+
+  // Scale font to viewport — aim for ~5.5% of viewport height
+  const viewportHeight = viewport?.height ?? 720;
+  const baseFontSize = Math.round(viewportHeight * 0.055);
+  const fontSize = Math.max(24, Math.min(72, baseFontSize));
+
+  return (
+    <div
+      className="social-caption-overlay"
+      style={{
+        position: 'absolute',
+        bottom: '18%',
+        left: 0,
+        right: 0,
+        zIndex: 50,
+        pointerEvents: 'none',
+        textAlign: 'center',
+        padding: '0 8%',
+        boxSizing: 'border-box',
+        opacity: 1,
+        transition: 'opacity 0.15s ease-in-out',
+      }}
+    >
+      <div
+        style={{
+          display: 'inline-block',
+          lineHeight: 1.3,
+        }}
+      >
+        {activeChunk.words.map((word, i) => {
+          const isActive = i === activeWordIndex;
+          return (
+            <span
+              key={`${word.startTime}-${i}`}
+              style={{
+                fontFamily,
+                fontSize: `${fontSize}px`,
+                fontWeight: isActive ? 800 : 600,
+                color: isActive ? primaryColor : 'rgba(255, 255, 255, 0.9)',
+                textShadow: '0 2px 8px rgba(0,0,0,0.7), 0 0 20px rgba(0,0,0,0.4)',
+                marginRight: i < activeChunk!.words.length - 1 ? '0.3em' : undefined,
+                transition: 'color 0.1s ease, font-weight 0.1s ease',
+                textTransform: 'uppercase',
+              }}
+            >
+              {word.text}
+            </span>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

package/src/__tests__/DocControlsSlideshow.test.tsx

@@ -13,6 +13,7 @@ function makeState(overrides: Partial<PlaybackState> = {}): PlaybackState {
     docProgress: 0.2,
     hasCaptions: false,
     captionsEnabled: false,
+    captionMode: 'off',
     currentSegmentIndex: 0,
     currentSegmentName: null,
     currentBlock: null,

package/src/hooks/useAudioSync.ts

@@ -277,8 +277,11 @@ export function useAudioSync(
       const audio = audioRef.current;
       if (!audio || !audioTrack?.segments) return;
 
-      // Clamp time to valid range
-      const clampedTime = Math.max(0, Math.min(time, totalDuration));
+      // Clamp time to valid range.
+      // When totalDuration is 0 (no audio segments), don't clamp — allow
+      // seeking by block timing alone (used in render mode / preview).
+      const clampedTime =
+        totalDuration > 0 ? Math.max(0, Math.min(time, totalDuration)) : Math.max(0, time);
 
       // Find which segment this time falls into
       let segmentIndex = 0;

package/src/hooks/useDocPlayback.ts

@@ -18,6 +18,7 @@ import type { Theme } from '@bendyline/squisq/schemas';
 import { getBlockAtTime } from '@bendyline/squisq/schemas';
 import {
   expandDocBlocks,
+  flattenBlocks,
   isTemplateBlock,
   VIEWPORT_PRESETS,
   type ViewportConfig,
@@ -76,8 +77,12 @@ export function useDocPlayback(
       return [];
     }
 
+    // Flatten nested block hierarchy (markdown-derived docs have children)
+    const hasChildren = script.blocks.some((b) => b.children && b.children.length > 0);
+    const flatBlocks = hasChildren ? flattenBlocks(script.blocks) : script.blocks;
+
     // Check if any blocks are templates
-    const hasTemplates = script.blocks.some(isTemplateBlock);
+    const hasTemplates = flatBlocks.some(isTemplateBlock);
 
     if (hasTemplates) {
       // Extract audio segment timing for proper block synchronization
@@ -87,7 +92,7 @@ export function useDocPlayback(
       }));
 
       // Expand template blocks with audio segment timing, viewport, and persistent layers
-      const expanded = expandDocBlocks(script.blocks as DocBlock[], {
+      const expanded = expandDocBlocks(flatBlocks as DocBlock[], {
         audioSegments,
         viewport,
         persistentLayers: script.persistentLayers,
@@ -97,7 +102,7 @@ export function useDocPlayback(
     }
 
     // All raw blocks, use as-is
-    return script.blocks;
+    return flatBlocks;
   }, [script?.blocks, script?.audio?.segments, script?.persistentLayers, viewport, theme]);
 
   // Find current block based on time

package/src/index.ts

@@ -2,6 +2,7 @@
 export { DocPlayer } from './DocPlayer.js';
 export { BlockRenderer, VIEWPORT } from './BlockRenderer.js';
 export { CaptionOverlay } from './CaptionOverlay.js';
+export { SocialCaptionOverlay } from './SocialCaptionOverlay.js';
 export { DocControlsOverlay } from './DocControlsOverlay.js';
 export { DocControlsBottom } from './DocControlsBottom.js';
 export { DocControlsSidebar } from './DocControlsSidebar.js';
@@ -32,6 +33,8 @@ export type {
   BlockMarker,
   ControlsLayout,
   DisplayMode,
+  CaptionStyle,
+  CaptionMode,
   SlideNavActions,
   SquisqRenderAPI,
   SquisqWindow,

package/src/layers/ShapeLayer.tsx

@@ -7,7 +7,7 @@
 
 import type { ShapeLayer as ShapeLayerType } from '@bendyline/squisq/schemas';
 import { getAnimationStyle } from '../utils/animationUtils';
-import { resolveValue } from '../utils/layerUtils';
+import { resolveValue, getAnchorOffset } from '../utils/layerUtils';
 
 interface ShapeLayerProps {
   layer: ShapeLayerType;
@@ -21,11 +21,16 @@ export function ShapeLayer({ layer, viewport, blockTime }: ShapeLayerProps) {
   const { content, position, animation } = layer;
 
   // Resolve position values to pixels
-  const x = resolveValue(position.x, viewport.width);
-  const y = resolveValue(position.y, viewport.height);
+  const rawX = resolveValue(position.x, viewport.width);
+  const rawY = resolveValue(position.y, viewport.height);
   const width = position.width ? resolveValue(position.width, viewport.width) : 100;
   const height = position.height ? resolveValue(position.height, viewport.height) : 100;
 
+  // Apply anchor offset (e.g., 'center' shifts x by -width/2 and y by -height/2)
+  const anchorOffset = getAnchorOffset(position.anchor, width, height);
+  const x = rawX + anchorOffset.x;
+  const y = rawY + anchorOffset.y;
+
   // Get animation styles
   const animStyle = getAnimationStyle(animation, blockTime);
 

package/src/layers/TextLayer.tsx

@@ -38,7 +38,7 @@ export function TextLayer({ layer, viewport, blockTime }: TextLayerProps) {
   const animStyle = getAnimationStyle(animation, blockTime);
 
   // Split text into lines, and wrap if maxWidth is specified
-  const rawLines = text.split('\n');
+  const rawLines = (text ?? '').split('\n');
   let lines = maxWidth
     ? rawLines.reduce<string[]>(
         (acc, line) => acc.concat(wrapText(line, style.fontSize, maxWidth)),

package/src/standalone-entry.tsx

@@ -53,6 +53,14 @@ export interface MountOptions {
   theme?: Theme;
   /** 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.
+   */
+  renderMode?: boolean;
+  /** Caption style: 'standard' or 'social'. Omit or set to undefined for no captions. */
+  captionStyle?: 'standard' | 'social';
 }
 
 // ── CSS Injection ──────────────────────────────────────────────────
@@ -159,7 +167,16 @@ const roots = new WeakMap<Element, Root>();
 export function mount(element: Element, doc: Doc, options: MountOptions = {}): void {
   injectCss();
 
-  const { mode = 'slideshow', basePath = '.', images, audio, autoPlay = false, theme } = options;
+  const {
+    mode = 'slideshow',
+    basePath = '.',
+    images,
+    audio,
+    autoPlay = false,
+    theme,
+    renderMode = false,
+    captionStyle,
+  } = options;
 
   // Rewrite audio URLs if map provided
   const finalDoc = audio ? rewriteAudioUrls(doc, audio) : doc;
@@ -180,9 +197,12 @@ export function mount(element: Element, doc: Doc, options: MountOptions = {}): v
       script: finalDoc,
       basePath,
       displayMode: 'slideshow',
-      autoPlay,
-      showControls: true,
+      autoPlay: renderMode ? false : autoPlay,
+      showControls: !renderMode,
+      renderMode,
       theme,
+      captionsEnabled: !!captionStyle,
+      captionStyle: captionStyle ?? 'standard',
     });
   }
 

package/src/types.ts

@@ -32,6 +32,23 @@ export type ControlsLayout = 'overlay' | 'sidebar' | 'bottom';
  */
 export type DisplayMode = 'video' | 'slideshow' | 'linear';
 
+/**
+ * Caption display style.
+ *
+ * - `'standard'` — Traditional broadcast-style captions: small white text
+ *   on a semi-transparent black badge at the top of the player.
+ * - `'social'` — Social media-style (Instagram/TikTok): large centered words
+ *   showing 3-5 words at a time with the active word highlighted in the
+ *   theme's primary color. Font and colors pulled from the active theme.
+ */
+export type CaptionStyle = 'standard' | 'social';
+
+/**
+ * Caption display mode — combines enable/disable with style selection.
+ * The CC button cycles through: off → standard → social → off.
+ */
+export type CaptionMode = 'off' | 'standard' | 'social';
+
 /** Slide navigation actions for slideshow display mode */
 export interface SlideNavActions {
   /** Navigate to the next slide */
@@ -52,6 +69,8 @@ export interface PlaybackState {
   docProgress: number;
   hasCaptions: boolean;
   captionsEnabled: boolean;
+  /** Current caption display mode (off, standard, social). */
+  captionMode: CaptionMode;
   isFullscreen?: boolean;
   /** Current audio segment index (0-based) */
   currentSegmentIndex: number;
@@ -67,6 +86,8 @@ export interface PlaybackActions {
   restart: () => void;
   seekTo: (time: number) => void;
   setCaptionsEnabled: (enabled: boolean) => void;
+  /** Cycle caption mode: off → standard → social → off */
+  cycleCaptionMode: () => void;
   toggleFullscreen?: () => void;
 }