@bendyline/squisq-react 1.3.2 → 1.4.1

package/src/__tests__/transitionStyles.test.ts

@@ -0,0 +1,125 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import type { TransitionDirection, TransitionType } from '@bendyline/squisq/schemas';
+import { TRANSITION_TYPES } from '@bendyline/squisq/schemas';
+import { getTransitionClass } from '../utils/animationUtils';
+
+const transitionCss = readFileSync(
+  resolve(process.cwd(), 'packages/react/src/styles/doc-animations.css'),
+  'utf8',
+);
+
+const directionalTypes: TransitionType[] = [
+  'cover',
+  'pan',
+  'pull',
+  'push',
+  'reveal',
+  'strips',
+  'uncover',
+  'wipe',
+];
+
+const axisTypes: TransitionType[] = ['blinds', 'comb', 'randomBar', 'randomBars', 'split'];
+const cardinalDirections = [
+  'left',
+  'right',
+  'up',
+  'down',
+] as const satisfies readonly TransitionDirection[];
+const axisDirections = ['horizontal', 'vertical'] as const satisfies readonly TransitionDirection[];
+
+function collectGeneratedTransitionClasses(): string[] {
+  const classNames = new Set<string>();
+
+  for (const type of TRANSITION_TYPES) {
+    if (type === 'cut') continue;
+    classNames.add(getTransitionClass(type, true));
+    classNames.add(getTransitionClass(type, false));
+  }
+
+  for (const type of directionalTypes) {
+    for (const direction of cardinalDirections) {
+      classNames.add(getTransitionClass(type, true, direction));
+      classNames.add(getTransitionClass(type, false, direction));
+    }
+  }
+
+  for (const type of axisTypes) {
+    for (const direction of axisDirections) {
+      classNames.add(getTransitionClass(type, true, direction));
+      classNames.add(getTransitionClass(type, false, direction));
+    }
+  }
+
+  return [...classNames].sort();
+}
+
+describe('transition CSS coverage', () => {
+  it('contains enter and exit selectors for every generated transition class', () => {
+    for (const className of collectGeneratedTransitionClasses()) {
+      expect(transitionCss, className).toContain(`.${className}`);
+    }
+  });
+});
+
+/** All `@keyframes <name>` defined in the stylesheet. */
+function definedKeyframes(): Set<string> {
+  const names = new Set<string>();
+  for (const m of transitionCss.matchAll(/@keyframes\s+([A-Za-z0-9_-]+)/g)) {
+    names.add(m[1]);
+  }
+  return names;
+}
+
+/**
+ * Map each `.transition-<x>-(enter|exit)` selector to the keyframe its rule
+ * animates. Parses top-level `selectors { body }` blocks and reads the first
+ * identifier of the `animation:` shorthand. Returns null for a transition rule
+ * with no `animation` property (itself a defect).
+ */
+function transitionRuleKeyframes(): Map<string, string | null> {
+  const map = new Map<string, string | null>();
+  const ruleRe = /([^{}]+)\{([^{}]*)\}/g;
+  let rule: RegExpExecArray | null;
+  while ((rule = ruleRe.exec(transitionCss)) !== null) {
+    const selectors = rule[1].split(',').map((s) => s.trim());
+    const transitionSelectors = selectors.filter((s) =>
+      /\.transition-[A-Za-z0-9-]+-(?:enter|exit)\b/.test(s),
+    );
+    if (transitionSelectors.length === 0) continue;
+    const animMatch = rule[2].match(/animation:\s*([A-Za-z0-9_-]+)/);
+    const keyframe = animMatch ? animMatch[1] : null;
+    for (const selector of transitionSelectors) {
+      const classMatch = selector.match(/\.(transition-[A-Za-z0-9-]+-(?:enter|exit))/);
+      if (classMatch && !map.has(classMatch[1])) map.set(classMatch[1], keyframe);
+    }
+  }
+  return map;
+}
+
+describe('transition keyframe integrity', () => {
+  it('every transition rule animates a defined @keyframes (catches typos)', () => {
+    const keyframes = definedKeyframes();
+    const broken: string[] = [];
+    for (const [selector, keyframe] of transitionRuleKeyframes()) {
+      if (keyframe === null) broken.push(`${selector}: no animation property`);
+      else if (!keyframes.has(keyframe)) broken.push(`${selector}: missing @keyframes ${keyframe}`);
+    }
+    expect(broken, broken.join('\n')).toEqual([]);
+  });
+
+  it('every generated transition class resolves to a defined keyframe', () => {
+    // Ties the function output to the CSS end-to-end: a class the player can
+    // emit must have a rule, and that rule must animate a real keyframe.
+    const keyframes = definedKeyframes();
+    const rules = transitionRuleKeyframes();
+    for (const className of collectGeneratedTransitionClasses()) {
+      const keyframe = rules.get(className);
+      expect(keyframe, `${className} has no transition rule`).toBeDefined();
+      expect(keyframe, `${className} animates undefined keyframe ${keyframe}`).not.toBeNull();
+      if (keyframe) expect(keyframes.has(keyframe), `${className} -> ${keyframe}`).toBe(true);
+    }
+  });
+});

package/src/__tests__/useDocPlayback.transition.test.ts

@@ -0,0 +1,70 @@
+/**
+ * useDocPlayback — block transition state is derived synchronously.
+ *
+ * Regression guard for the between-block "flash": a newly active block must
+ * report `isEntering` (and its outgoing `previousBlock`) on the SAME render it
+ * becomes current — not a frame later via an effect. Otherwise the block paints
+ * fully settled for a frame and then snaps back to the start of its entrance
+ * animation. The distinguishing assertion is `previousBlock` during the next
+ * block's entrance with NO timer/effect advanced (the old effect-based path
+ * only set it after a `setTimeout`).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { VIEWPORT_PRESETS } from '@bendyline/squisq/doc';
+import type { Doc, Block } from '@bendyline/squisq/schemas';
+import { useDocPlayback } from '../hooks/useDocPlayback';
+
+function block(id: string, startTime: number): Block {
+  return {
+    id,
+    startTime,
+    duration: 5,
+    audioSegment: 0,
+    transition: { type: 'fade', duration: 0.5 },
+    layers: [],
+  };
+}
+
+const doc: Doc = {
+  articleId: 'd',
+  duration: 10,
+  blocks: [block('a', 0), block('b', 5)],
+  audio: { segments: [] },
+};
+
+describe('useDocPlayback — synchronous block transitions', () => {
+  it('exposes the entering block + outgoing previousBlock on the same render (no effect flush)', () => {
+    const { result, rerender } = renderHook(
+      ({ t }: { t: number }) => useDocPlayback(doc, t, VIEWPORT_PRESETS.landscape),
+      { initialProps: { t: 0 } },
+    );
+
+    // Establish block A as the current block first.
+    expect(result.current.currentBlockIndex).toBe(0);
+
+    // Cross into block B's entrance window: it is entering AND crossfading from
+    // A immediately — the old code left previousBlock null until a setTimeout.
+    rerender({ t: 5.1 });
+    expect(result.current.currentBlockIndex).toBe(1);
+    expect(result.current.isEntering).toBe(true);
+    expect(result.current.isExiting).toBe(true);
+    expect(result.current.previousBlock?.id).toBe('a');
+
+    // Past the entrance window: settled, no crossfade.
+    rerender({ t: 7 });
+    expect(result.current.isEntering).toBe(false);
+    expect(result.current.isExiting).toBe(false);
+    expect(result.current.previousBlock).toBeNull();
+  });
+
+  it('isEntering is a pure function of blockTime vs the transition duration', () => {
+    const enteringAt = (t: number) =>
+      renderHook(() => useDocPlayback(doc, t, VIEWPORT_PRESETS.landscape)).result.current
+        .isEntering;
+    expect(enteringAt(5.0)).toBe(true); // blockTime 0.0 < 0.5
+    expect(enteringAt(5.4)).toBe(true); // blockTime 0.4 < 0.5
+    expect(enteringAt(5.6)).toBe(false); // blockTime 0.6 >= 0.5
+  });
+});

package/src/__tests__/useJsonViewTokens.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { DARK_SURFACE, LIGHT_SURFACE, DEFAULT_THEME } from '@bendyline/squisq/schemas';
+import { useJsonViewTokens } from '../jsonView/useJsonViewTokens';
+
+type StyleBag = Record<string, string>;
+
+function mockPrefersDark(dark: boolean): void {
+  Object.defineProperty(window, 'matchMedia', {
+    configurable: true,
+    value: (query: string) => ({
+      matches: dark && query.includes('dark'),
+      media: query,
+      onchange: null,
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      dispatchEvent: vi.fn(() => false),
+    }),
+  });
+}
+
+describe('useJsonViewTokens', () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it('emits json-prefixed tokens for a static surface', () => {
+    const { result } = renderHook(() => useJsonViewTokens(DEFAULT_THEME, LIGHT_SURFACE));
+    const style = result.current.style as StyleBag;
+    expect(style['--squisq-json-bg']).toBe(LIGHT_SURFACE.background);
+    expect(style['--squisq-json-text']).toBe(LIGHT_SURFACE.text);
+  });
+
+  it("tracks a dark OS preference under surface='auto'", () => {
+    mockPrefersDark(true);
+    const { result } = renderHook(() => useJsonViewTokens(DEFAULT_THEME, 'auto'));
+    const style = result.current.style as StyleBag;
+    expect(style['--squisq-json-bg']).toBe(DARK_SURFACE.background);
+    expect(result.current.theme.colors.background).toBe(DARK_SURFACE.background);
+  });
+});

package/src/__tests__/useSlideSwipe.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from 'vitest';
+import { decideSwipe, type SwipeDecisionInput } from '../hooks/useSlideSwipe';
+
+/** A slow drag: long duration so velocity stays well under the flick threshold. */
+function slow(overrides: Partial<SwipeDecisionInput>): SwipeDecisionInput {
+  return {
+    dx: 0,
+    width: 1000,
+    elapsedMs: 1000,
+    canNext: true,
+    canPrev: true,
+    ...overrides,
+  };
+}
+
+describe('decideSwipe', () => {
+  describe('distance threshold (30% of width)', () => {
+    it('snaps back when the drag is below the threshold', () => {
+      // 100px of 1000px = 10% < 30%, and slow enough not to be a flick.
+      expect(decideSwipe(slow({ dx: -100 }))).toBe('snap');
+      expect(decideSwipe(slow({ dx: 100 }))).toBe('snap');
+    });
+
+    it('advances to the next slide when dragged left past the threshold', () => {
+      expect(decideSwipe(slow({ dx: -350 }))).toBe('next');
+    });
+
+    it('goes to the previous slide when dragged right past the threshold', () => {
+      expect(decideSwipe(slow({ dx: 350 }))).toBe('prev');
+    });
+
+    it('commits exactly at the threshold', () => {
+      expect(decideSwipe(slow({ dx: -300 }))).toBe('next');
+    });
+  });
+
+  describe('flick (fast, short drag)', () => {
+    it('commits on a quick flick even below the distance threshold', () => {
+      // 100px in 100ms = 1.0 px/ms >= 0.5, distance 100 >= 12.
+      expect(decideSwipe(slow({ dx: -100, elapsedMs: 100 }))).toBe('next');
+      expect(decideSwipe(slow({ dx: 100, elapsedMs: 100 }))).toBe('prev');
+    });
+
+    it('ignores a fast micro-jitter shorter than the minimum flick distance', () => {
+      // 8px in 5ms = 1.6 px/ms (fast) but distance 8 < 12 → treat as a click.
+      expect(decideSwipe(slow({ dx: -8, elapsedMs: 5 }))).toBe('snap');
+    });
+  });
+
+  describe('deck boundaries', () => {
+    it('snaps back instead of advancing when there is no next slide', () => {
+      expect(decideSwipe(slow({ dx: -350, canNext: false }))).toBe('snap');
+      // A flick past the last slide is also refused.
+      expect(decideSwipe(slow({ dx: -100, elapsedMs: 100, canNext: false }))).toBe('snap');
+    });
+
+    it('snaps back instead of rewinding when there is no previous slide', () => {
+      expect(decideSwipe(slow({ dx: 350, canPrev: false }))).toBe('snap');
+      expect(decideSwipe(slow({ dx: 100, elapsedMs: 100, canPrev: false }))).toBe('snap');
+    });
+  });
+
+  describe('degenerate inputs', () => {
+    it('snaps back on a zero-distance release', () => {
+      expect(decideSwipe(slow({ dx: 0 }))).toBe('snap');
+    });
+
+    it('never commits by distance when the container has no measurable width', () => {
+      // width 0 → distance threshold is Infinity; only a flick can commit.
+      // 500px over 2000ms = 0.25 px/ms, safely below the flick velocity.
+      expect(decideSwipe(slow({ dx: -500, width: 0, elapsedMs: 2000 }))).toBe('snap');
+      expect(decideSwipe(slow({ dx: -500, width: 0, elapsedMs: 100 }))).toBe('next');
+    });
+
+    it('does not divide by zero on an instantaneous release', () => {
+      // elapsedMs 0 → velocity treated as 0; falls back to the distance rule.
+      expect(decideSwipe(slow({ dx: -350, elapsedMs: 0 }))).toBe('next');
+      expect(decideSwipe(slow({ dx: -100, elapsedMs: 0 }))).toBe('snap');
+    });
+  });
+});

package/src/hooks/{AudioProvider.ts → AudioController.ts}

@@ -1,5 +1,5 @@
 /**
- * AudioProvider - Abstraction for audio playback in DocPlayer
+ * AudioController - Abstraction for audio playback in DocPlayer
  *
  * This module defines an interface for audio playback operations that can have
  * different implementations depending on the runtime environment:
@@ -47,9 +47,9 @@ export interface AudioActions {
   restart: () => Promise<void>;
 }
 
-export type AudioProvider = AudioState & AudioActions;
+export type AudioController = AudioState & AudioActions;
 
-export interface AudioProviderConfig {
+export interface AudioControllerConfig {
   /** Audio track with segments */
   audioTrack: AudioTrack | undefined;
   /** Base path for resolving audio URLs */

package/src/hooks/index.ts

@@ -1,5 +1,10 @@
-export { calculateSegmentTiming, findSegmentAtTime } from './AudioProvider';
-export type { AudioState, AudioActions, AudioProvider, AudioProviderConfig } from './AudioProvider';
+export { calculateSegmentTiming, findSegmentAtTime } from './AudioController';
+export type {
+  AudioState,
+  AudioActions,
+  AudioController,
+  AudioControllerConfig,
+} from './AudioController';
 
 export { useAudioSync } from './useAudioSync';
 export { useDocPlayback } from './useDocPlayback';

package/src/hooks/useAudioSync.ts

@@ -7,20 +7,21 @@
  * Handles multiple audio segments (MP3 files) by tracking which segment
  * is currently playing and calculating the overall timeline position.
  *
- * This is the HTML5 Audio implementation of the AudioProvider interface.
- * For EFB/MSFS environments, use useCompanionAudioSync instead.
+ * This is the HTML5 Audio implementation of the AudioController interface.
+ * Hosts that drive audio through an external player (e.g. a native shell)
+ * can supply their own AudioController to DocPlayer instead of this hook.
  */
 
 import { useState, useEffect, useRef, useCallback } from 'react';
 import type { RefObject } from 'react';
 import type { AudioTrack } from '@bendyline/squisq/schemas';
-import type { AudioProvider } from './AudioProvider';
+import type { AudioController } from './AudioController';
 
 export function useAudioSync(
   audioRef: RefObject<HTMLAudioElement>,
   audioTrack: AudioTrack | undefined,
   basePath: string = '',
-): AudioProvider {
+): AudioController {
   const [currentTime, setCurrentTime] = useState(0);
   const [isPlaying, setIsPlaying] = useState(false);
   const [currentSegment, setCurrentSegment] = useState(0);
@@ -120,6 +121,13 @@ export function useAudioSync(
     if (!audio) return;
 
     const handleTimeUpdate = () => {
+      // In fallback mode the <audio> element is NOT the clock — there's no real
+      // source (e.g. the editor preview's synthetic, empty-src track), so the
+      // synthetic timer and `seekTo` own `currentTime`. A `timeupdate` fired as
+      // a side effect of programmatically setting `audio.currentTime` (during a
+      // seek) would otherwise clobber the just-seeked position with the empty
+      // element's unreliable `currentTime`, snapping the scrubber back.
+      if (fallbackMode.current) return;
       // Calculate overall timeline position
       const segmentStart = segmentStarts.current[currentSegment] || 0;
       const overallTime = segmentStart + audio.currentTime;
@@ -127,7 +135,13 @@ export function useAudioSync(
     };
 
     const handlePlay = () => {
-      fallbackMode.current = false;
+      // Don't clear `fallbackMode` here. Whether the <audio> element is really
+      // the clock is decided authoritatively by the play() promise: it only
+      // resolves (clearing fallback, see `play`) when a real source actually
+      // plays. The 'play' event, by contrast, can fire spuriously on the
+      // source-less preview element — and clearing fallback there makes the
+      // synthetic timer's tick guard bail on its next frame, freezing the
+      // clock and the scrubber after a seek/resume.
       setIsPlaying(true);
     };
     const handlePause = () => setIsPlaying(false);

package/src/hooks/useDocPlayback.ts

@@ -12,14 +12,20 @@
  * - Automatic expansion of template blocks
  */
 
-import { useState, useEffect, useMemo, useCallback, useRef } from 'react';
+import { useMemo, useCallback, useRef } from 'react';
 import type { Doc, Block, DocBlock } from '@bendyline/squisq/schemas';
 import type { Theme } from '@bendyline/squisq/schemas';
-import { getBlockAtTime } from '@bendyline/squisq/schemas';
+import {
+  DEFAULT_THEME,
+  getBlockAtTime,
+  resolveBlockTransition,
+  resolveTransitionDuration,
+} from '@bendyline/squisq/schemas';
 import {
   expandDocBlocks,
-  flattenBlocks,
+  flattenRenderableBlocks,
   isTemplateBlock,
+  resolvePersistentLayers,
   VIEWPORT_PRESETS,
   type ViewportConfig,
 } from '@bendyline/squisq/doc';
@@ -61,29 +67,34 @@ export function useDocPlayback(
   renderMode: boolean = false,
   theme?: Theme,
 ): PlaybackState & PlaybackActions {
-  const [transitionState, setTransitionState] = useState<{
-    entering: boolean;
-    exiting: boolean;
-    previousBlock: Block | null;
-  }>({
-    entering: false,
-    exiting: false,
-    previousBlock: null,
-  });
-
+  // `renderMode` is retained for API/signature compatibility; block transitions
+  // are now computed identically for real-time and render (export) modes.
+  void renderMode;
   // Expand any template blocks into full blocks
   const blocks = useMemo(() => {
     if (!script?.blocks) {
       return [];
     }
 
-    // Flatten nested block hierarchy (markdown-derived docs have children)
+    // Flatten nested block hierarchy (markdown-derived docs have children).
+    // `flattenRenderableBlocks` skips the children of container templates
+    // (`diagram`, `drawing`) — those are consumed by the parent's render as
+    // nodes/shapes, so they must not also appear as their own slides.
     const hasChildren = script.blocks.some((b) => b.children && b.children.length > 0);
-    const flatBlocks = hasChildren ? flattenBlocks(script.blocks) : script.blocks;
+    const flatBlocks = hasChildren ? flattenRenderableBlocks(script.blocks) : script.blocks;
 
     // Check if any blocks are templates
     const hasTemplates = flatBlocks.some(isTemplateBlock);
 
+    // Doc persistent layers win wholesale; docs without any inherit the
+    // theme's (see resolvePersistentLayers). Passed as a narrow object so
+    // the memo deps stay field-precise.
+    const resolvedTheme = theme ?? DEFAULT_THEME;
+    const persistentLayers = resolvePersistentLayers(
+      { persistentLayers: script.persistentLayers },
+      resolvedTheme,
+    );
+
     if (hasTemplates) {
       // Extract audio segment timing for proper block synchronization
       const audioSegments = script.audio?.segments?.map((seg) => ({
@@ -95,15 +106,31 @@ export function useDocPlayback(
       const expanded = expandDocBlocks(flatBlocks as DocBlock[], {
         audioSegments,
         viewport,
-        persistentLayers: script.persistentLayers,
+        persistentLayers,
         theme,
+        // Custom (user-defined) templates inlined into the doc's
+        // frontmatter — see CustomTemplates.ts. Merged onto the
+        // built-in registry so blocks annotated with `{[myhero]}`
+        // resolve through the user's design.
+        customTemplates: script.customTemplates,
       });
       return expanded;
     }
 
-    // All raw blocks, use as-is
-    return flatBlocks;
-  }, [script?.blocks, script?.audio?.segments, script?.persistentLayers, viewport, theme]);
+    // All raw blocks — used as-is except for the theme's default transition
+    // fallback (copies, never mutations: these blocks are caller-owned).
+    return flatBlocks.map((block, index) => {
+      const transition = resolveBlockTransition(block, resolvedTheme, index);
+      return transition !== block.transition ? { ...block, transition } : block;
+    });
+  }, [
+    script?.blocks,
+    script?.audio?.segments,
+    script?.persistentLayers,
+    script?.customTemplates,
+    viewport,
+    theme,
+  ]);
 
   // Find current block based on time
   const currentBlock = useMemo(() => getBlockAtTime(blocks, currentTime), [blocks, currentTime]);
@@ -130,78 +157,38 @@ export function useDocPlayback(
     return Math.min(1, currentTime / script.duration);
   }, [script, currentTime]);
 
-  // Track block transitions.
-  // In render mode, transitions are computed from blockTime so they stay
-  // synchronized with the seekTo timeline. In normal mode, setTimeout drives
-  // transitions at the browser's real-time clock speed.
-  const _prevBlockRef = useMemo(
-    () => currentBlock,
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- intentionally keyed on index, not block reference
-    [currentBlockIndex],
-  );
-
-  useEffect(() => {
-    if (!currentBlock || renderMode) return;
-
-    // When block changes, trigger transition (real-time mode only)
-    if (transitionState.previousBlock?.id !== currentBlock.id) {
-      const transition = currentBlock.transition;
-      const transitionDuration = transition?.duration || 0;
-
-      if (transitionDuration > 0) {
-        // Start transition
-        setTransitionState({
-          entering: true,
-          exiting: true,
-          previousBlock: transitionState.previousBlock,
-        });
-
-        // End transition after duration
-        const timer = setTimeout(() => {
-          setTransitionState({
-            entering: false,
-            exiting: false,
-            previousBlock: currentBlock,
-          });
-        }, transitionDuration * 1000);
-
-        return () => clearTimeout(timer);
-      } else {
-        // Instant cut
-        setTransitionState({
-          entering: false,
-          exiting: false,
-          previousBlock: currentBlock,
-        });
-      }
-    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- intentionally keyed on currentBlock?.id only; reading transitionState.previousBlock without dep to avoid infinite loop
-  }, [currentBlock?.id, renderMode]);
-
-  // Render mode: track previous block via ref and compute transition from time
-  const renderPrevBlockRef = useRef<Block | null>(null);
-
-  useEffect(() => {
-    if (!renderMode || !currentBlock) return;
-
-    if (transitionState.previousBlock?.id !== currentBlock.id) {
-      // Block changed — remember the old block for crossfade
-      const oldPrev = transitionState.previousBlock;
-      renderPrevBlockRef.current = oldPrev;
-      // Store current block as the "last seen" for next transition
-      setTransitionState((prev) => ({
-        ...prev,
-        previousBlock: currentBlock,
-      }));
-    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- same pattern: keyed on block identity change
-  }, [currentBlock?.id, renderMode]);
-
-  // In render mode, derive entering/exiting from blockTime
-  const renderTransitionDuration = currentBlock?.transition?.duration || 0;
-  const renderIsEntering =
-    renderMode && renderTransitionDuration > 0 && blockTime < renderTransitionDuration;
-  const renderIsExiting = renderIsEntering && renderPrevBlockRef.current !== null;
+  // ─── Transition tracking (synchronous — no effect lag) ──────────────
+  // `isEntering` is simply "we are within the block's entrance window"
+  // (blockTime < the transition's duration). Deriving it during render —
+  // rather than flipping it in an effect a frame AFTER the block changes —
+  // means a newly-active block renders WITH its entrance state on its very
+  // first frame. Otherwise the block paints once fully settled and then, a
+  // frame later, snaps back to the start of its entrance animation: the brief
+  // "flash then re-animate" seen between blocks. This runs identically for
+  // real-time playback and frame-seeked render (export) mode.
+  //
+  // The block we transitioned FROM (for the crossfade) is tracked with refs
+  // updated during render — the standard "previous value" pattern — so the
+  // outgoing block is known on the SAME frame the new block becomes active
+  // (an effect would lag a frame and drop the crossfade's first frames).
+  const outgoingBlockRef = useRef<Block | null>(null);
+  const activeBlockIdRef = useRef<string | null>(null);
+  const lastRenderedBlockRef = useRef<Block | null>(null);
+  if (currentBlock && currentBlock.id !== activeBlockIdRef.current) {
+    outgoingBlockRef.current = lastRenderedBlockRef.current;
+    activeBlockIdRef.current = currentBlock.id;
+  }
+  lastRenderedBlockRef.current = currentBlock;
+
+  const transitionDuration = currentBlock?.transition
+    ? resolveTransitionDuration(currentBlock.transition)
+    : 0;
+  const isEntering = !!currentBlock && transitionDuration > 0 && blockTime < transitionDuration;
+  const outgoingBlock = outgoingBlockRef.current;
+  // Only crossfade a genuinely different outgoing block (guards restarts/seeks
+  // where the "previous" resolves to the same block).
+  const isExiting = isEntering && outgoingBlock != null && outgoingBlock.id !== currentBlock?.id;
+  const previousBlock = isExiting ? outgoingBlock : null;
 
   // Manual navigation
   const goToBlock = useCallback(
@@ -233,15 +220,9 @@ export function useDocPlayback(
   return {
     currentBlock,
     currentBlockIndex,
-    previousBlock: renderMode
-      ? renderIsExiting
-        ? renderPrevBlockRef.current
-        : null
-      : transitionState.exiting
-        ? transitionState.previousBlock
-        : null,
-    isEntering: renderMode ? renderIsEntering : transitionState.entering,
-    isExiting: renderMode ? renderIsExiting : transitionState.exiting,
+    previousBlock,
+    isEntering,
+    isExiting,
     blockTime,
     blockProgress,
     docProgress,