@bendyline/squisq-react 1.3.2 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq-react",
-  "version": "1.3.2",
+  "version": "1.4.1",
   "description": "React component library for doc playback, block rendering, and media layers",
   "license": "MIT",
   "author": "Bendyline",
@@ -34,7 +34,7 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./styles": "./src/styles/index.css",
+    "./styles": "./dist/styles/index.css",
     "./standalone": "./dist/squisq-player.global.js",
     "./standalone-source": {
       "types": "./src/standalone-source.d.ts",
@@ -42,7 +42,7 @@
     }
   },
   "scripts": {
-    "build": "tsup && tsup --config tsup.standalone.config.ts && node scripts/generate-standalone-source.mjs",
+    "build": "tsup && tsup --config tsup.standalone.config.ts && node scripts/generate-standalone-source.mjs && node ../../scripts/build-styles.mjs",
     "build:esm": "tsup",
     "build:standalone": "tsup --config tsup.standalone.config.ts && node scripts/generate-standalone-source.mjs",
     "dev": "npm run build:standalone && concurrently -n js,dts -c blue,gray -r \"tsup --watch --no-dts --no-clean\" \"tsup --watch --dts-only --no-clean\"",
@@ -53,17 +53,21 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@bendyline/squisq": "1.4.1"
+    "@bendyline/squisq": "1.5.1"
   },
   "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",
     "tsup": "8.5.1",
     "typescript": "5.9.3"
-  }
+  },
+  "sideEffects": [
+    "**/*.css"
+  ]
 }

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

@@ -11,7 +11,7 @@
  * - Playback controls (play/pause, seek, next/prev)
  * - Progress display
  * - Render mode for video capture (via window.seekTo)
- * - Pluggable audio provider for different environments (browser, EFB)
+ * - Pluggable audio controller for different environments (browser, EFB)
  * - Multiple control layouts: overlay (default), sidebar, bottom
  *
  * Related Files:
@@ -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';
@@ -33,14 +39,17 @@ import { useAutoSurface } from './hooks/useAutoSurface';
 import { useAudioSync } from './hooks/useAudioSync';
 import { useDocPlayback } from './hooks/useDocPlayback';
 import { useViewportOrientation } from './hooks/useViewportOrientation';
-import type { AudioProvider } from './hooks/AudioProvider';
+import { useSlideSwipe } from './hooks/useSlideSwipe';
+import type { AudioController } from './hooks/AudioController';
 import {
   expandCoverBlock,
   createTemplateContext,
+  markdownToDoc,
   DEFAULT_THEME,
   VIEWPORT_PRESETS,
   type ViewportConfig,
 } from '@bendyline/squisq/doc';
+import { parseMarkdown } from '@bendyline/squisq/markdown';
 import { DocControlsOverlay } from './DocControlsOverlay';
 import { DocControlsSlideshow } from './DocControlsSlideshow';
 import { DocProgressBar } from './DocProgressBar';
@@ -79,11 +88,11 @@ const SMALL_WORDS = new Set([
  * Uses sectionHeader blocks to find real titles, with fallbacks
  * for "intro" and slug-based names.
  */
-function buildSegmentTitleMap(script: Doc): Map<number, string> {
+function buildSegmentTitleMap(doc: Doc): Map<number, string> {
   const map = new Map<number, string>();
 
   // Scan blocks for sectionHeader templates which carry the real title
-  for (const block of script.blocks as DocBlock[]) {
+  for (const block of doc.blocks as DocBlock[]) {
     if (isTemplateBlock(block) && block.template === 'sectionHeader' && 'title' in block) {
       const segIdx = block.audioSegment;
       if (!map.has(segIdx)) {
@@ -93,9 +102,9 @@ function buildSegmentTitleMap(script: Doc): Map<number, string> {
   }
 
   // Fill in any segments that weren't covered by sectionHeader blocks
-  for (let i = 0; i < script.audio.segments.length; i++) {
+  for (let i = 0; i < doc.audio.segments.length; i++) {
     if (!map.has(i)) {
-      const name = script.audio.segments[i].name;
+      const name = doc.audio.segments[i].name;
       if (name === 'intro' || name.includes('intro')) {
         map.set(i, 'Introduction');
       } else if (name === 'flight-context' || name.includes('flight-context')) {
@@ -117,10 +126,20 @@ function buildSegmentTitleMap(script: Doc): Map<number, string> {
 }
 
 interface DocPlayerProps {
-  /** Doc script to play */
-  script: Doc;
-  /** Base path for resolving media URLs */
-  basePath: string;
+  /**
+   * The Doc to play. Wins over `markdown` when both are provided.
+   * When neither `doc` nor `markdown` is given, the player renders a
+   * minimal themed empty state instead of crashing.
+   */
+  doc?: Doc;
+  /**
+   * Markdown source to play. When `doc` is absent, the markdown is parsed
+   * and converted to a Doc via `markdownToDoc(parseMarkdown(markdown))`.
+   * Ignored when `doc` is provided.
+   */
+  markdown?: string;
+  /** Base path for resolving media URLs (default: `'.'`) */
+  basePath?: string;
   /** Render mode for video capture (hides controls, exposes seekTo) */
   renderMode?: boolean;
   /** Auto-play when loaded */
@@ -129,8 +148,8 @@ interface DocPlayerProps {
   onEnded?: () => void;
   /** Callback for time updates */
   onTimeUpdate?: (time: number) => void;
-  /** Optional audio provider (if not provided, uses default HTML5 audio) */
-  audioProvider?: AudioProvider;
+  /** Optional audio controller (if not provided, uses default HTML5 audio) */
+  audioController?: AudioController;
   /** Show built-in controls (default: true). Set to false for custom controls. */
   showControls?: boolean;
   /** Show only the progress bar/scrubber at bottom (no other controls).
@@ -183,16 +202,66 @@ interface DocPlayerProps {
   /** Caption display style (default: 'standard').
    *  'social' shows large centered words with the active word highlighted. */
   captionStyle?: CaptionStyle;
+  /**
+   * Enable drag-to-swipe slide navigation in slideshow mode (default: true).
+   * When enabled, press-and-drag on a slide advances/rewinds on release past a
+   * threshold (or a quick flick), and snaps back otherwise. Only applies when
+   * `displayMode === 'slideshow'` and not in render/headless mode.
+   */
+  enableSwipe?: boolean;
+}
+
+// Dev-only, browser-safe environment probe. Bundlers substitute the
+// `process.env.NODE_ENV` expression; bare browsers without a bundler have
+// no `process` at all and are treated as production (no warning noise).
+function isDevEnvironment(): boolean {
+  try {
+    return typeof process !== 'undefined' && process.env.NODE_ENV !== 'production';
+  } catch {
+    return false;
+  }
 }
 
-export function DocPlayer({
-  script,
-  basePath,
+// One-shot flag for the missing-stylesheet warning (module-level so the
+// warning fires at most once per page, not once per player instance).
+let warnedMissingStyles = false;
+
+/**
+ * Front-door component: resolves the `doc` / `markdown` props into a Doc
+ * and renders a themed empty state when neither is provided. The playback
+ * machinery lives in `DocPlayerContent` so its hook order never changes
+ * when a doc appears or disappears.
+ */
+export function DocPlayer(props: DocPlayerProps) {
+  const { doc, markdown } = props;
+
+  // Parse markdown into a Doc only when no explicit doc is supplied.
+  const markdownDoc = useMemo(
+    () => (!doc && markdown !== undefined ? markdownToDoc(parseMarkdown(markdown)) : undefined),
+    [doc, markdown],
+  );
+
+  const resolvedDoc = doc ?? markdownDoc;
+
+  if (!resolvedDoc) {
+    return <div className="doc-player doc-player--empty" />;
+  }
+
+  return <DocPlayerContent {...props} doc={resolvedDoc} />;
+}
+
+interface DocPlayerContentProps extends DocPlayerProps {
+  doc: Doc;
+}
+
+function DocPlayerContent({
+  doc,
+  basePath = '.',
   renderMode = false,
   autoPlay = false,
   onEnded,
   onTimeUpdate,
-  audioProvider: externalAudioProvider,
+  audioController: externalAudioController,
   showControls = true,
   showScrubber = false,
   muted = false,
@@ -208,7 +277,8 @@ export function DocPlayer({
   theme,
   surface,
   captionStyle = 'standard',
-}: DocPlayerProps) {
+  enableSwipe = true,
+}: DocPlayerContentProps) {
   const isSlideshowMode = displayMode === 'slideshow';
   const isLinearMode = displayMode === 'linear';
   const audioRef = useRef<HTMLAudioElement>(null);
@@ -231,11 +301,27 @@ export function DocPlayer({
     return params.get('debug') === 'true';
   }, []);
 
-  // Use internal HTML5 audio sync if no external provider is given
-  const internalAudio = useAudioSync(audioRef, script.audio, basePath);
+  // Use internal HTML5 audio sync if no external controller is given
+  const internalAudio = useAudioSync(audioRef, doc.audio, basePath);
 
-  // Use external provider if provided, otherwise fall back to internal
-  const audio = externalAudioProvider || internalAudio;
+  // Use external controller if provided, otherwise fall back to internal
+  const audio = externalAudioController || internalAudio;
+
+  // Dev-only sentinel: warn once when the package stylesheet isn't loaded.
+  // The stylesheet sets `--squisq-styles-loaded: 1` on `.doc-player`; if the
+  // mounted container computes an empty value, the CSS never made it in.
+  useEffect(() => {
+    if (warnedMissingStyles || !isDevEnvironment()) return;
+    const el = containerRef.current;
+    if (!el || typeof getComputedStyle !== 'function') return;
+    const value = getComputedStyle(el).getPropertyValue('--squisq-styles-loaded');
+    if (!value.trim()) {
+      warnedMissingStyles = true;
+      console.warn(
+        '[squisq] @bendyline/squisq-react/styles is not loaded — import "@bendyline/squisq-react/styles"',
+      );
+    }
+  }, []);
 
   // Destructure for convenience
   const {
@@ -255,6 +341,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(doc), [doc]);
+
   // 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);
@@ -307,11 +398,11 @@ export function DocPlayer({
     nextBlock: _nextBlock,
     prevBlock: _prevBlock,
     blocks: expandedBlocks,
-  } = useDocPlayback(script, currentTime, activeViewport, renderMode, effectiveTheme);
+  } = useDocPlayback(doc, currentTime, activeViewport, renderMode, effectiveTheme);
 
   // Expand cover block (startBlock) if present - uses active viewport
   const coverBlock = useMemo((): Block | null => {
-    const startBlockConfig = script.startBlock as StartBlockConfig | undefined;
+    const startBlockConfig = doc.startBlock as StartBlockConfig | undefined;
     if (!startBlockConfig) return null;
 
     const context = createTemplateContext(effectiveTheme, 0, 1, activeViewport);
@@ -324,7 +415,7 @@ export function DocPlayer({
       audioSegment: -1,
       layers,
     };
-  }, [script.startBlock, activeViewport, effectiveTheme]);
+  }, [doc.startBlock, activeViewport, effectiveTheme]);
 
   // Render-mode cover block control: allows Playwright to force-show the cover block
   const [coverForced, setCoverForced] = useState(false);
@@ -450,7 +541,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 +565,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 +597,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(doc);
+        if (totalDuration > 0) return Math.max(totalDuration, mediaDuration);
+        return mediaDuration;
       };
       // Expose block metadata for testing -- allows tests to find specific templates
       w.getBlocks = () =>
@@ -495,7 +614,7 @@ export function DocPlayer({
         }));
       // Audio segment info for video production -- returns the actual files in composition order
       w.getAudioSegments = () =>
-        script.audio.segments.map((seg) => ({
+        doc.audio.segments.map((seg) => ({
           src: seg.src,
           name: seg.name,
           duration: seg.duration,
@@ -503,15 +622,15 @@ export function DocPlayer({
         }));
       // Caption phrases for SRT/subtitle export
       w.getCaptions = () =>
-        script.captions?.phrases?.map((p) => ({
+        doc.captions?.phrases?.map((p) => ({
           text: p.text,
           startTime: p.startTime,
           endTime: p.endTime,
         })) || [];
       // Chapter markers for YouTube timestamps -- uses segment titles from sectionHeader blocks
       w.getChapters = () => {
-        const titleMap = buildSegmentTitleMap(script);
-        return script.audio.segments.map((seg, i) => ({
+        const titleMap = buildSegmentTitleMap(doc);
+        return doc.audio.segments.map((seg, i) => ({
           title: titleMap.get(i) || seg.name,
           startTime: seg.startTime,
           duration: seg.duration,
@@ -542,7 +661,7 @@ export function DocPlayer({
         delete w.hasCoverBlock;
       }
     };
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- script is a stable prop; re-registering on every script change is unnecessary
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- doc is a stable prop; re-registering on every doc change is unnecessary
   }, [renderMode, isDebugMode, seekTo, totalDuration, expandedBlocks, coverBlock]);
 
   // Caption mode state: cycles through off → standard → social → off
@@ -552,6 +671,15 @@ export function DocPlayer({
     captionsEnabledProp === false ? 'off' : captionStyle || 'standard';
   const [captionMode, setCaptionMode] = useState<CaptionMode>(defaultMode);
 
+  // Keep the internal caption mode in sync when the controlling props change
+  // — e.g. the editor's preview toolbar drives caption style / on-off. Keyed
+  // on the derived `defaultMode` string, so it only fires on a real prop
+  // change and never disturbs the in-player CC toggle for consumers (the
+  // standalone player, video export) that set these props once at mount.
+  useEffect(() => {
+    setCaptionMode(defaultMode);
+  }, [defaultMode]);
+
   // Derive captionsEnabled and active style from the mode
   const captionsEnabled = captionMode !== 'off';
   const activeCaptionStyle: CaptionStyle = captionMode === 'social' ? 'social' : 'standard';
@@ -575,10 +703,10 @@ export function DocPlayer({
     });
   }, [onCaptionsToggle]);
 
-  const hasCaptions = script.captions && script.captions.phrases.length > 0;
+  const hasCaptions = doc.captions && doc.captions.phrases.length > 0;
 
   // Map segment indices to human-readable titles (from sectionHeader blocks)
-  const segmentTitleMap = useMemo(() => buildSegmentTitleMap(script), [script]);
+  const segmentTitleMap = useMemo(() => buildSegmentTitleMap(doc), [doc]);
 
   // Build shared playback state for extracted controls
   const playbackState: PlaybackState = useMemo(
@@ -595,10 +723,10 @@ export function DocPlayer({
       isFullscreen,
       currentSegmentIndex: currentSegment,
       currentSegmentName:
-        segmentTitleMap.get(currentSegment) ?? script.audio.segments[currentSegment]?.name ?? null,
+        segmentTitleMap.get(currentSegment) ?? doc.audio.segments[currentSegment]?.name ?? null,
       currentBlock: currentBlock ?? null,
     }),
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- script.audio.segments is stable within a given script
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- doc.audio.segments is stable within a given doc
     [
       isPlaying,
       currentTime,
@@ -664,6 +792,18 @@ export function DocPlayer({
     [currentBlockIndex, expandedBlocks, seekTo, pause],
   );
 
+  // Drag-to-swipe navigation for slideshow mode. Inert unless in slideshow mode,
+  // interactive (not headless), and not overridden off via `enableSwipe`.
+  const swipeEnabled = isSlideshowMode && !isLinearMode && !renderMode && enableSwipe;
+  const swipe = useSlideSwipe({
+    enabled: swipeEnabled,
+    containerRef,
+    canGoNext: currentBlockIndex < expandedBlocks.length - 1,
+    canGoPrev: currentBlockIndex > 0,
+    onNext: slideNavActions.nextSlide,
+    onPrev: slideNavActions.prevSlide,
+  });
+
   // Callback for playback state changes (for external controls)
   useEffect(() => {
     onPlaybackStateChange?.(playbackState);
@@ -816,7 +956,7 @@ export function DocPlayer({
         }}
       >
         <LinearDocView
-          doc={script}
+          doc={doc}
           basePath={basePath}
           viewport={activeViewport}
           theme={theme}
@@ -829,20 +969,35 @@ export function DocPlayer({
   return (
     <div
       ref={containerRef}
-      className="doc-player"
+      className={`doc-player${swipeEnabled ? ' doc-player--swipe' : ''}${
+        swipe.phase === 'dragging' ? ' doc-player--grabbing' : ''
+      }`}
       onClick={handleContainerClick}
+      onPointerDown={swipe.onPointerDown}
       style={{
         position: 'relative',
         width: '100%',
         aspectRatio: `${activeViewport.width} / ${activeViewport.height}`,
         margin: '0 auto',
         overflow: 'hidden',
-        cursor: renderMode ? undefined : 'pointer',
+        // Swipe uses the grab/grabbing cursor via CSS classes; let vertical page
+        // scroll through on touch while we own horizontal drags.
+        cursor: renderMode || swipeEnabled ? undefined : 'pointer',
+        touchAction: swipeEnabled ? 'pan-y' : undefined,
       }}
     >
       {/* 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 +1015,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 +1033,15 @@ 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${
+              swipe.phase !== 'idle' ? ` doc-player__block--${swipe.phase}` : ''
+            }`}
+            style={
+              swipe.phase !== 'idle' ? { transform: `translateX(${swipe.offsetPx}px)` } : undefined
+            }
+          >
             <BlockRenderer
               block={currentBlock}
               blockTime={blockTime}
@@ -888,7 +1056,7 @@ export function DocPlayer({
         {/* Caption overlay -- shown during playback and in render mode when captions are enabled */}
         {hasCaptions && (renderMode ? captionsEnabled : true) && (
           <CaptionOverlay
-            captions={script.captions}
+            captions={doc.captions}
             currentTime={currentTime}
             enabled={captionsEnabled && (renderMode || isPlaying || currentTime > 0)}
             fontSize={16}
@@ -937,8 +1105,7 @@ export function DocPlayer({
               <span style={{ color: '#888' }}>time:</span> {currentTime.toFixed(2)}s /{' '}
               {totalDuration.toFixed(1)}s{' '}
               <span style={{ color: '#666' }}>
-                (progress: {(docProgress * 100).toFixed(1)}%, scriptDur:{' '}
-                {script.duration.toFixed(1)})
+                (progress: {(docProgress * 100).toFixed(1)}%, scriptDur: {doc.duration.toFixed(1)})
               </span>
             </div>
             <div>
@@ -947,9 +1114,9 @@ export function DocPlayer({
             </div>
             <div>
               <span style={{ color: '#888' }}>segment:</span> {currentSegment}/
-              {script.audio.segments.length - 1}{' '}
+              {doc.audio.segments.length - 1}{' '}
               <span style={{ color: '#666' }}>
-                ({script.audio.segments[currentSegment]?.name || 'none'})
+                ({doc.audio.segments[currentSegment]?.name || 'none'})
               </span>
             </div>
             <div>
@@ -966,13 +1133,13 @@ export function DocPlayer({
             </div>
             {hasCaptions &&
               (() => {
-                const debugPhrase = getCaptionAtTime(script.captions!, currentTime);
+                const debugPhrase = getCaptionAtTime(doc.captions!, currentTime);
                 const debugEnabled = captionsEnabled && (isPlaying || currentTime > 0);
                 return (
                   <Fragment>
                     <div>
                       <span style={{ color: '#888' }}>captions:</span>{' '}
-                      {script.captions?.phrases.length || 0} phrases{' '}
+                      {doc.captions?.phrases.length || 0} phrases{' '}
                       <span style={{ color: captionsEnabled ? '#4ade80' : '#666' }}>
                         ({captionsEnabled ? 'on' : 'off'})
                       </span>