@bendyline/squisq-react 1.3.1 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq-react",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "React component library for doc playback, block rendering, and media layers",
   "license": "MIT",
   "author": "Bendyline",
@@ -53,13 +53,14 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@bendyline/squisq": "1.4.0"
+    "@bendyline/squisq": "1.5.0"
   },
   "devDependencies": {
     "@types/react": "18.3.28",
     "preact": "10.29.0",
     "react": "18.3.1",
     "react-dom": "18.3.1",
+    "@testing-library/dom": "10.4.1",
     "@testing-library/react": "16.3.2",
     "@testing-library/jest-dom": "6.9.1",
     "jsdom": "25.0.1",

package/src/BlockRenderer.tsx

@@ -6,10 +6,12 @@
  * Handles positioning, animations, and transitions.
  */
 
-import type { Block, Layer } from '@bendyline/squisq/schemas';
+import type { Block, Layer, Transition } from '@bendyline/squisq/schemas';
+import { resolveTransitionDuration } from '@bendyline/squisq/schemas';
 import { ImageLayer } from './layers/ImageLayer';
 import { TextLayer } from './layers/TextLayer';
 import { ShapeLayer } from './layers/ShapeLayer';
+import { PathLayer } from './layers/PathLayer';
 import { MapLayer } from './layers/MapLayer';
 import { VideoLayer } from './layers/VideoLayer';
 import { TableLayer } from './layers/TableLayer';
@@ -39,6 +41,8 @@ interface BlockRendererProps {
   isEntering?: boolean;
   /** Whether this block is exiting (for transition) */
   isExiting?: boolean;
+  /** Transition to apply. Defaults to block.transition. */
+  transition?: Transition;
   /** Viewport dimensions (defaults to 1920x1080 landscape) */
   viewport?: ViewportDimensions;
   /** Whether the doc is currently playing (controls video playback) */
@@ -51,18 +55,20 @@ export function BlockRenderer({
   basePath,
   isEntering = false,
   isExiting = false,
+  transition,
   viewport = VIEWPORT,
   isPlaying,
 }: BlockRendererProps) {
   // Build transition class and inline style for dynamic duration
   let transitionClass = '';
   const transitionStyle: Record<string, string> = {};
-  if (block.transition && isEntering) {
-    transitionClass = getTransitionClass(block.transition.type, true);
-    transitionStyle['--transition-duration'] = `${block.transition.duration}s`;
-  } else if (block.transition && isExiting) {
-    transitionClass = getTransitionClass(block.transition.type, false);
-    transitionStyle['--transition-duration'] = `${block.transition.duration}s`;
+  const activeTransition = transition ?? block.transition;
+  if (activeTransition && isEntering) {
+    transitionClass = getTransitionClass(activeTransition.type, true, activeTransition.direction);
+    transitionStyle['--transition-duration'] = `${resolveTransitionDuration(activeTransition)}s`;
+  } else if (activeTransition && isExiting) {
+    transitionClass = getTransitionClass(activeTransition.type, false, activeTransition.direction);
+    transitionStyle['--transition-duration'] = `${resolveTransitionDuration(activeTransition)}s`;
   }
 
   // Unique clip path ID per block to avoid conflicts when multiple blocks render simultaneously
@@ -124,6 +130,8 @@ function LayerRenderer({ layer, basePath, viewport, blockTime, isPlaying }: Laye
       return <TextLayer layer={layer} viewport={viewport} blockTime={blockTime} />;
     case 'shape':
       return <ShapeLayer layer={layer} viewport={viewport} blockTime={blockTime} />;
+    case 'path':
+      return <PathLayer layer={layer} viewport={viewport} blockTime={blockTime} />;
     case 'map':
       return (
         <MapLayer layer={layer} basePath={basePath} viewport={viewport} blockTime={blockTime} />

package/src/DocPlayer.tsx

@@ -24,7 +24,13 @@
 
 import { Fragment, useRef, useState, useEffect, useCallback, useMemo } from 'react';
 import type { Doc, Block, TextLayer, StartBlockConfig, DocBlock } from '@bendyline/squisq/schemas';
-import { isTemplateBlock, getCaptionAtTime } from '@bendyline/squisq/schemas';
+import {
+  isTemplateBlock,
+  getCaptionAtTime,
+  resolveMediaSchedule,
+  getDocPlaybackDuration,
+} from '@bendyline/squisq/schemas';
+import { MediaClipLayer } from './MediaClipLayer';
 import type { SurfaceScheme, Theme } from '@bendyline/squisq/schemas';
 import { applySurface } from '@bendyline/squisq/schemas';
 import { BlockRenderer } from './BlockRenderer';
@@ -255,6 +261,11 @@ export function DocPlayer({
     restart,
   } = audio;
 
+  // Timed media clips (block.media + doc.documentMedia) resolved to absolute
+  // doc-timeline coordinates. Empty for documents without the media model, so
+  // <MediaClipLayer> renders nothing and the legacy audio path is unaffected.
+  const mediaSchedule = useMemo(() => resolveMediaSchedule(script), [script]);
+
   // Refs for frequently-changing values used in the keyboard handler,
   // so the handler callback doesn't need to be recreated every frame.
   const currentTimeRef = useRef(currentTime);
@@ -450,7 +461,13 @@ export function DocPlayer({
                 const video = el as HTMLVideoElement;
                 const clipStart = parseFloat(video.dataset.clipStart || '0');
                 const clipEnd = parseFloat(video.dataset.clipEnd || '0');
-                const targetTime = Math.min(clipStart + Math.max(0, blockElapsed), clipEnd);
+                // Honor the per-clip startAt offset: before it, hold at the
+                // in-point; after, advance by (blockElapsed - startAt).
+                const startAt = parseFloat(video.dataset.startAt || '0');
+                const targetTime = Math.min(
+                  clipStart + Math.max(0, blockElapsed - startAt),
+                  clipEnd,
+                );
 
                 video.pause();
                 video.currentTime = targetTime;
@@ -468,6 +485,30 @@ export function DocPlayer({
               });
             }
 
+            // Seek player-level scheduled videos (document-spanning clips
+            // rendered by MediaClipLayer, outside any single block). Each
+            // carries data-abs-start/data-abs-end/data-source-in.
+            document.querySelectorAll('video[data-clip-id]').forEach((el) => {
+              const video = el as HTMLVideoElement;
+              const absStart = parseFloat(video.dataset.absStart || '0');
+              const absEnd = parseFloat(video.dataset.absEnd || '0');
+              const sourceIn = parseFloat(video.dataset.sourceIn || '0');
+              video.pause();
+              if (time < absStart || time >= absEnd) return;
+              const targetTime = sourceIn + (time - absStart);
+              video.currentTime = targetTime;
+              videoSeekPromises.push(
+                new Promise<void>((r) => {
+                  if (Math.abs(video.currentTime - targetTime) < 0.1) {
+                    r();
+                  } else {
+                    video.addEventListener('seeked', () => r(), { once: true });
+                    setTimeout(r, 200);
+                  }
+                }),
+              );
+            });
+
             // Wait for video seeks + one more frame for the browser to render
             Promise.all(videoSeekPromises).then(() => {
               requestAnimationFrame(() => resolve());
@@ -476,14 +517,12 @@ export function DocPlayer({
         });
       };
       w.getDuration = () => {
-        // When audio is present totalDuration comes from audio segments.
-        // For audio-less docs, compute from block timings instead.
-        if (totalDuration > 0) return totalDuration;
-        if (expandedBlocks.length > 0) {
-          const last = expandedBlocks[expandedBlocks.length - 1];
-          return last.startTime + last.duration;
-        }
-        return 0;
+        // The larger of the audio/block timeline and any media that spills
+        // past the last block (block-clip spillover or document-spanning
+        // media), so frame capture covers the full tail.
+        const mediaDuration = getDocPlaybackDuration(script);
+        if (totalDuration > 0) return Math.max(totalDuration, mediaDuration);
+        return mediaDuration;
       };
       // Expose block metadata for testing -- allows tests to find specific templates
       w.getBlocks = () =>
@@ -843,6 +882,15 @@ export function DocPlayer({
       {/* Hidden audio element */}
       <audio ref={audioRef} preload="auto" muted={muted} />
 
+      {/* Timed media clips (per-block + document-spanning audio/video). */}
+      <MediaClipLayer
+        schedule={mediaSchedule}
+        currentTime={currentTime}
+        isPlaying={isPlaying}
+        basePath={basePath}
+        renderMode={renderMode}
+      />
+
       {/* Block viewport */}
       <div className="doc-player__viewport">
         {/* Cover block (shown at rest before playback) */}
@@ -860,12 +908,17 @@ export function DocPlayer({
 
         {/* Previous block (during transition) */}
         {!showCoverBlock && previousBlock && isExiting && (
-          <div className="doc-player__block doc-player__block--previous">
+          // Keyed by block id so each block is its own DOM subtree: React never
+          // reconciles one block's layers onto another's (templates reuse layer
+          // ids like `title`/`background`), which would otherwise reuse stale
+          // DOM / skip entrance animations mid-transition.
+          <div key={previousBlock.id} className="doc-player__block doc-player__block--previous">
             <BlockRenderer
               block={previousBlock}
               blockTime={blockTime}
               basePath={basePath}
               isExiting={true}
+              transition={currentBlock?.transition}
               viewport={activeViewport}
             />
           </div>
@@ -873,7 +926,7 @@ export function DocPlayer({
 
         {/* Current block */}
         {!showCoverBlock && currentBlock && (
-          <div className="doc-player__block doc-player__block--active">
+          <div key={currentBlock.id} className="doc-player__block doc-player__block--active">
             <BlockRenderer
               block={currentBlock}
               blockTime={blockTime}

package/src/DocProgressBar.tsx

@@ -41,6 +41,15 @@ export function DocProgressBar({
   const progressBarRef = useRef<HTMLDivElement>(null);
   const [hoverPosition, setHoverPosition] = useState<number | null>(null);
 
+  // Fill position tracks the same timeline as the clock readout and the block
+  // marker dots — elapsed playback time over the audio `totalDuration`. (We
+  // deliberately don't use `state.docProgress`, which is keyed to the doc's
+  // estimated `script.duration`; when that diverges from the actual playback
+  // length — e.g. the editor preview's reading-time estimate — the fill would
+  // desync from the clock and the dots.)
+  const playProgress =
+    state.totalDuration > 0 ? Math.max(0, Math.min(1, state.currentTime / state.totalDuration)) : 0;
+
   const handleProgressHover = useCallback((e: React.MouseEvent) => {
     const bar = progressBarRef.current;
     if (!bar) return;
@@ -99,16 +108,25 @@ export function DocProgressBar({
         }}
       />
 
-      {/* Progress fill */}
+      {/* Progress fill.
+          No CSS `width` transition: the fill is driven by frequent JS updates
+          (the synthetic fallback timer runs ~60fps; real audio fires
+          `timeupdate` several times/sec), so it's already smooth. A CSS
+          transition here actively breaks playback — after a discontinuous
+          backward seek, the per-frame inline-width updates on resume keep
+          interrupting the in-flight transition before it advances, so the
+          *rendered* width latches at the seek position even though the inline
+          style (and the clock) keep climbing. The result is a frozen-looking
+          bar while time advances. Update width instantly instead. */}
       <div
+        data-testid="doc-progress-fill"
         style={{
           position: 'absolute',
           left: 0,
-          width: `${state.docProgress * 100}%`,
+          width: `${playProgress * 100}%`,
           height: '6px',
           background: '#5b9bd5',
           borderRadius: '3px',
-          transition: 'width 0.1s',
         }}
       />
 

package/src/LinearDocView.tsx

@@ -28,10 +28,9 @@ import {
   type Theme,
 } from '@bendyline/squisq/schemas';
 import { VIEWPORT_PRESETS } from '@bendyline/squisq/schemas';
-import { getLayers, hasTemplate, DEFAULT_THEME } from '@bendyline/squisq/doc';
+import { getLayers, hasTemplate, DEFAULT_THEME, deriveTemplateInputs } from '@bendyline/squisq/doc';
 import type { RenderContext } from '@bendyline/squisq/doc';
 import { extractPlainText } from '@bendyline/squisq/markdown';
-import type { MarkdownBlockNode, MarkdownList, MarkdownTable } from '@bendyline/squisq/markdown';
 import { BlockRenderer } from './BlockRenderer';
 import { MarkdownRenderer } from './MarkdownRenderer';
 
@@ -126,7 +125,6 @@ function BlockSection({ block, basePath, viewport, renderContext, blockIndex }:
 
     const annotation = block.sourceHeading!.templateAnnotation!;
     const headingText = extractPlainText(block.sourceHeading!);
-    const bodyText = extractBodyPlainText(block.contents);
 
     // Build a TemplateBlock-compatible object
     const templateBlock: Record<string, unknown> = {
@@ -136,12 +134,14 @@ function BlockSection({ block, basePath, viewport, renderContext, blockIndex }:
       duration: 1,
       audioSegment: 0,
       title: headingText,
-      ...getTemplateDefaults(
+      ...(deriveTemplateInputs(
         annotation.template ?? 'sectionHeader',
         headingText,
-        bodyText,
         block.contents,
-      ),
+        {
+          placeholders: true,
+        },
+      ) ?? {}),
       ...annotation.params,
       ...block.templateOverrides,
     };
@@ -223,196 +223,6 @@ function BlockSection({ block, basePath, viewport, renderContext, blockIndex }:
 
 // ── Template Defaults (mirrored from PreviewPanel) ─────────────────
 
-/** Extract plain text from block contents. */
-function extractBodyPlainText(contents?: MarkdownBlockNode[]): string {
-  if (!contents || contents.length === 0) return '';
-  return contents
-    .map((n) => extractPlainText(n))
-    .join('\n')
-    .trim();
-}
-
-/** Extract list items as plain text. */
-function extractListItems(contents?: MarkdownBlockNode[]): string[] {
-  if (!contents) return [];
-  const items: string[] = [];
-  for (const node of contents) {
-    if (node.type === 'list') {
-      for (const item of (node as MarkdownList).children) {
-        const text = extractPlainText(item).trim();
-        if (text) items.push(text);
-      }
-    }
-  }
-  return items;
-}
-
-/** First image discovered in a block's body, with any explicit
- *  dimensions captured (set by `<img width>` / `<img height>` in raw
- *  HTML — markdown shorthand has no syntax for dimensions). */
-interface FirstImage {
-  src: string;
-  alt: string;
-  width?: number;
-  height?: number;
-}
-
-/**
- * Find the first image referenced anywhere in block contents — both
- * markdown shorthand `![alt](url)` (type `image`) and raw HTML `<img>`
- * tags (type `htmlBlock`/`htmlInline`). The WYSIWYG editor emits the
- * HTML form whenever a user resizes an image (markdown shorthand has no
- * width syntax), so missing that path silently breaks every resized
- * image in the linear view.
- */
-function extractFirstImage(contents: MarkdownBlockNode[] | undefined): FirstImage | null {
-  if (!contents || contents.length === 0) return null;
-
-  function fromHtml(nodes: unknown[]): FirstImage | null {
-    for (const node of nodes) {
-      if (!node || typeof node !== 'object') continue;
-      const n = node as Record<string, unknown>;
-      if (n.type === 'htmlElement' && n.tagName === 'img') {
-        const attrs = n.attributes as Record<string, string> | undefined;
-        if (attrs && typeof attrs.src === 'string' && attrs.src) {
-          return {
-            src: attrs.src,
-            alt: typeof attrs.alt === 'string' ? attrs.alt : '',
-            width: parseDim(attrs.width),
-            height: parseDim(attrs.height),
-          };
-        }
-      }
-      if (Array.isArray(n.children)) {
-        const found = fromHtml(n.children);
-        if (found) return found;
-      }
-    }
-    return null;
-  }
-
-  function walk(node: unknown): FirstImage | null {
-    if (!node || typeof node !== 'object') return null;
-    const n = node as Record<string, unknown>;
-    if (n.type === 'image' && typeof n.url === 'string' && n.url) {
-      return { src: n.url, alt: typeof n.alt === 'string' ? n.alt : '' };
-    }
-    if ((n.type === 'htmlBlock' || n.type === 'htmlInline') && Array.isArray(n.htmlChildren)) {
-      const found = fromHtml(n.htmlChildren);
-      if (found) return found;
-    }
-    if (Array.isArray(n.children)) {
-      for (const child of n.children) {
-        const found = walk(child);
-        if (found) return found;
-      }
-    }
-    return null;
-  }
-
-  for (const node of contents) {
-    const found = walk(node);
-    if (found) return found;
-  }
-  return null;
-}
-
-/** Parse a `width`/`height` HTML attribute to a positive number. */
-function parseDim(raw: string | undefined): number | undefined {
-  if (raw === undefined) return undefined;
-  const n = parseFloat(raw);
-  return Number.isFinite(n) && n > 0 ? n : undefined;
-}
-
-/** Extract table data (headers, rows, alignment) from block contents. */
-function extractTableData(contents?: MarkdownBlockNode[]): {
-  headers: string[];
-  rows: string[][];
-  align?: (('left' | 'right' | 'center') | null)[];
-} | null {
-  if (!contents) return null;
-  for (const node of contents) {
-    if (node.type === 'table') {
-      const table = node as MarkdownTable;
-      const [headerRow, ...bodyRows] = table.children;
-      if (!headerRow) return null;
-      const headers = headerRow.children.map((cell) => extractPlainText(cell).trim());
-      const rows = bodyRows.map((row) => row.children.map((cell) => extractPlainText(cell).trim()));
-      return { headers, rows, align: table.align };
-    }
-  }
-  return null;
-}
-
-/**
- * Provide sensible default fields for templates that require more than
- * just a `title`. Prevents crashes from undefined required fields.
- */
-function getTemplateDefaults(
-  templateName: string,
-  headingText: string,
-  bodyText: string,
-  contents?: MarkdownBlockNode[],
-): Record<string, unknown> {
-  switch (templateName) {
-    case 'statHighlight':
-      return { stat: headingText, description: bodyText || headingText };
-    case 'quote':
-    case 'fullBleedQuote':
-    case 'pullQuote':
-      return { quote: bodyText || headingText };
-    case 'factCard':
-      return { fact: headingText, explanation: bodyText || headingText };
-    case 'comparisonBar':
-      return { leftLabel: 'A', leftValue: 60, rightLabel: 'B', rightValue: 40 };
-    case 'list': {
-      const items = extractListItems(contents);
-      return { items: items.length > 0 ? items : ['Item 1', 'Item 2', 'Item 3'] };
-    }
-    case 'definitionCard':
-      return { term: headingText, definition: bodyText || headingText };
-    case 'dateEvent':
-      return { date: headingText, description: bodyText || headingText };
-    case 'dataTable': {
-      const tableData = extractTableData(contents);
-      return tableData ?? { headers: ['Column'], rows: [['Data']] };
-    }
-    case 'imageWithCaption': {
-      // The template requires `imageSrc` — without it the image layer
-      // renders a broken `<img src=undefined>`. Pull the first image
-      // out of the block's body (markdown shorthand or HTML <img>) and
-      // use the heading as a caption fallback so a bare `# Title
-      // [Image with Caption]` block renders something sensible.
-      const img = extractFirstImage(contents);
-      if (!img) return { caption: headingText };
-      return {
-        imageSrc: img.src,
-        imageAlt: img.alt || headingText,
-        caption: headingText,
-      };
-    }
-    case 'leftFeature':
-    case 'rightFeature': {
-      // Feature blocks pair an image with the heading + the first
-      // paragraph of body text. Both inputs come from the section's
-      // contents — the image via the same scan used by imageWithCaption,
-      // the body text via the plain-text extractor that's already in
-      // scope here.
-      const img = extractFirstImage(contents);
-      return {
-        imageSrc: img?.src ?? '',
-        imageAlt: img?.alt || headingText,
-        imageWidth: img?.width,
-        imageHeight: img?.height,
-        title: headingText,
-        body: bodyText,
-      };
-    }
-    default:
-      return {};
-  }
-}
-
 // ── Main Component ─────────────────────────────────────────────────
 
 /**
@@ -444,10 +254,14 @@ export function LinearDocView({
 
   const renderContext: RenderContext = useMemo(() => {
     const baseTheme = theme ?? DEFAULT_THEME;
+    const effectiveTheme = resolvedSurface ? applySurface(baseTheme, resolvedSurface) : baseTheme;
     return {
-      theme: resolvedSurface ? applySurface(baseTheme, resolvedSurface) : baseTheme,
+      theme: effectiveTheme,
       viewport: activeViewport,
       totalBlocks,
+      // Theme atmosphere (vignette/grain/gradient persistent layers) shows
+      // on the inline template cards so they match the player's look.
+      persistentLayers: effectiveTheme.persistentLayers,
     };
   }, [activeViewport, totalBlocks, theme, resolvedSurface]);