@bendyline/squisq-react 1.0.2 → 1.1.0

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/__tests__/TableLayer.test.tsx

@@ -0,0 +1,142 @@
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { TableLayer } from '../layers/TableLayer';
+import type { TableLayer as TableLayerType } from '@bendyline/squisq/schemas';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeTableLayer(overrides: Partial<TableLayerType> = {}): TableLayerType {
+  return {
+    type: 'table',
+    id: 'test-table',
+    content: {
+      headers: ['Name', 'Age', 'City'],
+      rows: [
+        ['Alice', '30', 'Seattle'],
+        ['Bob', '25', 'Portland'],
+      ],
+      style: {
+        headerBackground: '#1e3a5f',
+        headerColor: '#ffffff',
+        cellBackground: 'rgba(255,255,255,0.05)',
+        cellColor: '#e0e0e0',
+        borderColor: 'rgba(255,255,255,0.12)',
+        fontSize: 28,
+        fontFamily: 'system-ui',
+        headerFontFamily: 'Georgia',
+        borderRadius: 8,
+      },
+    },
+    position: { x: '10%', y: '10%', width: '80%', height: '80%' },
+    ...overrides,
+  } as TableLayerType;
+}
+
+const viewport = { width: 1920, height: 1080 };
+
+function renderTableLayer(layer?: TableLayerType) {
+  return render(
+    <svg>
+      <TableLayer layer={layer ?? makeTableLayer()} viewport={viewport} blockTime={0} />
+    </svg>,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('TableLayer', () => {
+  it('renders a foreignObject element', () => {
+    const { container } = renderTableLayer();
+    const fo = container.querySelector('foreignObject');
+    expect(fo).toBeTruthy();
+  });
+
+  it('renders a table element', () => {
+    const { container } = renderTableLayer();
+    const table = container.querySelector('table');
+    expect(table).toBeTruthy();
+  });
+
+  it('renders the correct number of header cells', () => {
+    const { container } = renderTableLayer();
+    const headers = container.querySelectorAll('th');
+    expect(headers.length).toBe(3);
+  });
+
+  it('renders header text content', () => {
+    const { container } = renderTableLayer();
+    const headers = container.querySelectorAll('th');
+    expect(headers[0].textContent).toBe('Name');
+    expect(headers[1].textContent).toBe('Age');
+    expect(headers[2].textContent).toBe('City');
+  });
+
+  it('renders the correct number of data rows', () => {
+    const { container } = renderTableLayer();
+    const rows = container.querySelectorAll('tbody tr');
+    expect(rows.length).toBe(2);
+  });
+
+  it('renders cell text content', () => {
+    const { container } = renderTableLayer();
+    const cells = container.querySelectorAll('td');
+    expect(cells[0].textContent).toBe('Alice');
+    expect(cells[1].textContent).toBe('30');
+    expect(cells[2].textContent).toBe('Seattle');
+    expect(cells[3].textContent).toBe('Bob');
+  });
+
+  it('applies header background color', () => {
+    const { container } = renderTableLayer();
+    const th = container.querySelector('th');
+    expect(th?.style.background).toBe('rgb(30, 58, 95)');
+  });
+
+  it('applies font size from style', () => {
+    const { container } = renderTableLayer();
+    const table = container.querySelector('table');
+    expect(table?.style.fontSize).toBe('28px');
+  });
+
+  it('applies column alignment when provided', () => {
+    const layer = makeTableLayer();
+    layer.content.align = ['left', 'center', 'right'];
+    const { container } = renderTableLayer(layer);
+
+    const headers = container.querySelectorAll('th');
+    expect(headers[0].style.textAlign).toBe('left');
+    expect(headers[1].style.textAlign).toBe('center');
+    expect(headers[2].style.textAlign).toBe('right');
+  });
+
+  it('handles empty headers gracefully', () => {
+    const layer = makeTableLayer();
+    layer.content.headers = [];
+    const { container } = renderTableLayer(layer);
+    const thead = container.querySelector('thead');
+    // No thead or empty thead
+    expect(thead).toBeFalsy();
+  });
+
+  it('handles empty rows gracefully', () => {
+    const layer = makeTableLayer();
+    layer.content.rows = [];
+    const { container } = renderTableLayer(layer);
+    const tbody = container.querySelector('tbody');
+    // No tbody or empty tbody
+    expect(tbody).toBeFalsy();
+  });
+
+  it('sets foreignObject dimensions based on viewport percentage', () => {
+    const { container } = renderTableLayer();
+    const fo = container.querySelector('foreignObject');
+    // 80% of 1920 = 1536
+    expect(fo?.getAttribute('width')).toBe('1536');
+    // 80% of 1080 = 864
+    expect(fo?.getAttribute('height')).toBe('864');
+  });
+});

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';
@@ -16,6 +17,7 @@ export { ImageLayer } from './layers/ImageLayer.js';
 export { TextLayer } from './layers/TextLayer.js';
 export { ShapeLayer } from './layers/ShapeLayer.js';
 export { VideoLayer } from './layers/VideoLayer.js';
+export { TableLayer } from './layers/TableLayer.js';
 export { MapLayer } from './layers/MapLayer.js';
 
 // Hooks
@@ -32,6 +34,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/TableLayer.tsx

@@ -0,0 +1,129 @@
+/**
+ * TableLayer Component
+ *
+ * Renders a data table within an SVG block using a <foreignObject> to embed
+ * an HTML table. This gives us native table layout inside SVG viewports.
+ *
+ * The table is styled inline using the TableLayerStyle properties, which are
+ * typically derived from the active theme by the dataTable template.
+ */
+
+import type { TableLayer as TableLayerType } from '@bendyline/squisq/schemas';
+import { resolveValue, getAnchorOffset } from '../utils/layerUtils';
+import { getAnimationStyle } from '../utils/animationUtils';
+
+interface TableLayerProps {
+  layer: TableLayerType;
+  /** Viewport dimensions for percentage calculations */
+  viewport: { width: number; height: number };
+  /** Current time relative to block start (for animation) */
+  blockTime: number;
+}
+
+export function TableLayer({ layer, viewport, blockTime }: TableLayerProps) {
+  const { content, position, animation } = layer;
+  const { headers, rows, align, style } = content;
+
+  // 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;
+
+  // Build animation style
+  const animStyle = animation ? getAnimationStyle(animation, blockTime) : {};
+
+  const cellAlign = (ci: number): React.CSSProperties | undefined => {
+    const a = align?.[ci];
+    return a ? { textAlign: a } : undefined;
+  };
+
+  const borderRadius = style.borderRadius ?? 8;
+
+  return (
+    <foreignObject x={finalX} y={finalY} 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)}
+        style={{
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          padding: '16px',
+          boxSizing: 'border-box',
+        }}
+      >
+        <table
+          style={{
+            width: '100%',
+            borderCollapse: 'separate',
+            borderSpacing: 0,
+            fontSize: `${style.fontSize}px`,
+            fontFamily: style.fontFamily ?? 'system-ui, sans-serif',
+            overflow: 'hidden',
+            borderRadius: `${borderRadius}px`,
+            border: `1px solid ${style.borderColor}`,
+          }}
+        >
+          {headers.length > 0 && (
+            <thead>
+              <tr>
+                {headers.map((header, ci) => (
+                  <th
+                    key={ci}
+                    style={{
+                      background: style.headerBackground,
+                      color: style.headerColor,
+                      fontFamily:
+                        style.headerFontFamily ?? style.fontFamily ?? 'system-ui, sans-serif',
+                      fontWeight: 600,
+                      padding: '12px 16px',
+                      borderBottom: `2px solid ${style.borderColor}`,
+                      borderRight:
+                        ci < headers.length - 1 ? `1px solid ${style.borderColor}` : undefined,
+                      ...cellAlign(ci),
+                    }}
+                  >
+                    {header}
+                  </th>
+                ))}
+              </tr>
+            </thead>
+          )}
+          {rows.length > 0 && (
+            <tbody>
+              {rows.map((row, ri) => (
+                <tr key={ri}>
+                  {row.map((cell, ci) => (
+                    <td
+                      key={ci}
+                      style={{
+                        background: style.cellBackground,
+                        color: style.cellColor,
+                        padding: '10px 16px',
+                        borderBottom:
+                          ri < rows.length - 1 ? `1px solid ${style.borderColor}` : undefined,
+                        borderRight:
+                          ci < row.length - 1 ? `1px solid ${style.borderColor}` : undefined,
+                        ...cellAlign(ci),
+                      }}
+                    >
+                      {cell}
+                    </td>
+                  ))}
+                </tr>
+              ))}
+            </tbody>
+          )}
+        </table>
+      </div>
+    </foreignObject>
+  );
+}

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)),