@bendyline/squisq-react 1.4.2 → 2.0.1

package/src/__tests__/useAudioSync.test.ts

@@ -0,0 +1,49 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { AudioTrack } from '@bendyline/squisq/schemas';
+import { useAudioSync } from '../hooks/useAudioSync';
+
+const track: AudioTrack = {
+  segments: [{ src: 'https://cdn.example.test/a.mp3', name: 'a', duration: 2, startTime: 0 }],
+};
+
+afterEach(() => vi.restoreAllMocks());
+
+describe('useAudioSync resource loading', () => {
+  it('does not prefix absolute URLs and revokes a blob that resolves after cleanup', async () => {
+    let resolveFetch!: (value: unknown) => void;
+    const fetchPromise = new Promise((resolve) => {
+      resolveFetch = resolve;
+    });
+    const fetchSpy = vi
+      .spyOn(globalThis, 'fetch')
+      .mockReturnValue(fetchPromise as Promise<Response>);
+    const create = vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:late');
+    const revoke = vi.spyOn(URL, 'revokeObjectURL').mockImplementation(() => {});
+    const audioRef = { current: null };
+    const { unmount } = renderHook(() => useAudioSync(audioRef, track, '.'));
+
+    await waitFor(() => expect(fetchSpy).toHaveBeenCalled());
+    expect(fetchSpy.mock.calls[0][0]).toBe('https://cdn.example.test/a.mp3');
+    unmount();
+
+    await act(async () => {
+      resolveFetch({ ok: true, blob: async () => new Blob(['audio']) });
+      await fetchPromise;
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+    expect(create).toHaveBeenCalled();
+    expect(revoke).toHaveBeenCalledWith('blob:late');
+  });
+
+  it('does not preload when an external controller disables the hook', async () => {
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue({
+      ok: true,
+      blob: async () => new Blob(['audio']),
+    } as Response);
+    renderHook(() => useAudioSync({ current: null }, track, '.', false));
+    await act(async () => Promise.resolve());
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});

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

@@ -10,8 +10,8 @@
  * only set it after a `setTimeout`).
  */
 
-import { describe, it, expect } from 'vitest';
-import { renderHook } from '@testing-library/react';
+import { describe, it, expect, vi } from 'vitest';
+import { act, 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';
@@ -37,7 +37,7 @@ const doc: Doc = {
 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),
+      ({ t }: { t: number }) => useDocPlayback(doc, t, { viewport: VIEWPORT_PRESETS.landscape }),
       { initialProps: { t: 0 } },
     );
 
@@ -61,10 +61,53 @@ describe('useDocPlayback — synchronous block transitions', () => {
 
   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;
+      renderHook(() => useDocPlayback(doc, t, { viewport: 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
   });
+
+  it('can enter a swipe destination without restoring the outgoing block', () => {
+    const { result, rerender } = renderHook(
+      ({ t }: { t: number }) => useDocPlayback(doc, t, { viewport: VIEWPORT_PRESETS.landscape }),
+      { initialProps: { t: 0 } },
+    );
+
+    act(() => result.current.suppressOutgoingForNextBlock('b'));
+    rerender({ t: 5 });
+
+    // The destination still gets its own entrance animation, but the slide
+    // already carried away by the swipe is not mounted again as context.
+    expect(result.current.isEntering).toBe(true);
+    expect(result.current.isExiting).toBe(false);
+    expect(result.current.previousBlock).toBeNull();
+  });
+
+  it('clears stale outgoing context when a cover reveals the already-active block', () => {
+    const { result, rerender } = renderHook(
+      ({ t }: { t: number }) => useDocPlayback(doc, t, { viewport: VIEWPORT_PRESETS.landscape }),
+      { initialProps: { t: 0 } },
+    );
+    rerender({ t: 5 });
+    expect(result.current.previousBlock?.id).toBe('a');
+
+    act(() => result.current.suppressOutgoingForNextBlock('b'));
+    rerender({ t: 5 });
+
+    expect(result.current.isEntering).toBe(true);
+    expect(result.current.isExiting).toBe(false);
+    expect(result.current.previousBlock).toBeNull();
+  });
+
+  it('navigation actions seek to the target block', () => {
+    const seek = vi.fn();
+    const { result } = renderHook(() =>
+      useDocPlayback(doc, 0, { viewport: VIEWPORT_PRESETS.landscape, onSeek: seek }),
+    );
+    act(() => result.current.nextBlock());
+    expect(seek).toHaveBeenCalledWith(5);
+    act(() => result.current.goToBlock(0));
+    expect(seek).toHaveBeenLastCalledWith(0);
+  });
 });

package/src/__tests__/useViewportOrientation.test.ts

@@ -0,0 +1,22 @@
+import { renderHook } from '@testing-library/react';
+import { VIEWPORT_PRESETS } from '@bendyline/squisq/doc';
+import { afterEach, describe, expect, it } from 'vitest';
+import { useViewportOrientation } from '../hooks/useViewportOrientation';
+
+const originalWidth = window.innerWidth;
+const originalHeight = window.innerHeight;
+
+afterEach(() => {
+  Object.defineProperty(window, 'innerWidth', { configurable: true, value: originalWidth });
+  Object.defineProperty(window, 'innerHeight', { configurable: true, value: originalHeight });
+});
+
+describe('useViewportOrientation', () => {
+  it('uses the square preset for near-square viewports', () => {
+    Object.defineProperty(window, 'innerWidth', { configurable: true, value: 1000 });
+    Object.defineProperty(window, 'innerHeight', { configurable: true, value: 1000 });
+    const { result } = renderHook(() => useViewportOrientation());
+    expect(result.current.orientation).toBe('square');
+    expect(result.current.viewport).toBe(VIEWPORT_PRESETS.square);
+  });
+});

package/src/hooks/MediaContext.tsx

@@ -73,9 +73,18 @@ export function useMediaUrl(relativePath: string, basePath: string): string {
     }
 
     let cancelled = false;
-    provider!.resolveUrl(safePath).then((resolved) => {
-      if (!cancelled) setUrl(resolved);
-    });
+    // Never show the prior asset while a new provider/path is resolving.
+    setUrl(fallback);
+    provider!.resolveUrl(safePath).then(
+      (resolved) => {
+        if (!cancelled) setUrl(resolved);
+      },
+      () => {
+        // Resolution failures should be non-fatal and must not become
+        // unhandled promise rejections in rendering surfaces.
+        if (!cancelled) setUrl(fallback);
+      },
+    );
 
     return () => {
       cancelled = true;

package/src/hooks/useAudioSync.ts

@@ -17,10 +17,19 @@ import type { RefObject } from 'react';
 import type { AudioTrack } from '@bendyline/squisq/schemas';
 import type { AudioController } from './AudioController';
 
+function resolveAudioUrl(src: string, basePath: string): string {
+  // Preserve absolute/protocol-relative/data/blob URLs. Prefixing an absolute
+  // URL with the common default base path (`.`) produces `./https://...`.
+  if (!src || /^(?:[a-z][a-z0-9+.-]*:|\/\/|\/)/i.test(src)) return src;
+  if (!basePath) return src;
+  return `${basePath.replace(/\/$/, '')}/${src.replace(/^\//, '')}`;
+}
+
 export function useAudioSync(
   audioRef: RefObject<HTMLAudioElement>,
   audioTrack: AudioTrack | undefined,
   basePath: string = '',
+  enabled: boolean = true,
 ): AudioController {
   const [currentTime, setCurrentTime] = useState(0);
   const [isPlaying, setIsPlaying] = useState(false);
@@ -39,13 +48,27 @@ export function useAudioSync(
   // Preloaded audio blob URLs (for seeking without range request support)
   const blobUrls = useRef<Map<string, string>>(new Map());
   const loadingPromises = useRef<Map<string, Promise<string>>>(new Map());
+  const abortControllers = useRef<Set<AbortController>>(new Set());
+  const loadGeneration = useRef(0);
 
   // Fallback timer: when audio.play() is blocked (e.g., autoplay policy),
   // advance currentTime synthetically so blocks still progress without audio.
   const fallbackMode = useRef(false);
 
   useEffect(() => {
-    if (!audioTrack?.segments) {
+    loadGeneration.current += 1;
+    pendingSeekTime.current = null;
+    shouldPlayAfterLoad.current = false;
+    fallbackMode.current = false;
+    setCurrentTime(0);
+    setCurrentSegment(0);
+    setIsPlaying(false);
+    setIsEnded(false);
+    setIsAudioReady(false);
+
+    if (!enabled || !audioTrack?.segments) {
+      segmentStarts.current = [];
+      setTotalDuration(0);
       return;
     }
 
@@ -56,12 +79,12 @@ export function useAudioSync(
       return start;
     });
     setTotalDuration(time);
-  }, [audioTrack]);
+  }, [audioTrack, enabled]);
 
   // Preload audio file as blob (enables seeking without range request support)
   const preloadAudio = useCallback(
     async (src: string): Promise<string> => {
-      const audioUrl = basePath ? `${basePath}/${src}` : src;
+      const audioUrl = resolveAudioUrl(src, basePath);
 
       // Return cached blob URL if available
       if (blobUrls.current.has(src)) {
@@ -74,18 +97,26 @@ export function useAudioSync(
       }
 
       // Start loading
+      const controller = new AbortController();
+      abortControllers.current.add(controller);
+      const generation = loadGeneration.current;
       const loadPromise = (async () => {
         try {
-          const response = await fetch(audioUrl);
+          const response = await fetch(audioUrl, { signal: controller.signal });
           if (!response.ok) throw new Error(`HTTP ${response.status}`);
           const blob = await response.blob();
           const blobUrl = URL.createObjectURL(blob);
+          if (controller.signal.aborted || generation !== loadGeneration.current) {
+            URL.revokeObjectURL(blobUrl);
+            return audioUrl;
+          }
           blobUrls.current.set(src, blobUrl);
           return blobUrl;
         } catch {
           // Fall back to direct URL if blob loading fails
           return audioUrl;
         } finally {
+          abortControllers.current.delete(controller);
           loadingPromises.current.delete(src);
         }
       })();
@@ -98,7 +129,7 @@ export function useAudioSync(
 
   // Preload all audio segments on mount
   useEffect(() => {
-    if (!audioTrack?.segments) return;
+    if (!enabled || !audioTrack?.segments) return;
 
     // Preload all segments in parallel
     audioTrack.segments.forEach((segment) => {
@@ -107,16 +138,23 @@ export function useAudioSync(
 
     // Cleanup blob URLs on unmount
     const currentBlobUrls = blobUrls.current;
+    const currentAbortControllers = abortControllers.current;
+    const currentLoadingPromises = loadingPromises.current;
     return () => {
+      loadGeneration.current += 1;
+      currentAbortControllers.forEach((controller) => controller.abort());
+      currentAbortControllers.clear();
+      currentLoadingPromises.clear();
       currentBlobUrls.forEach((url) => {
         URL.revokeObjectURL(url);
       });
       currentBlobUrls.clear();
     };
-  }, [audioTrack, preloadAudio]);
+  }, [audioTrack, preloadAudio, enabled]);
 
   // Handle audio time updates
   useEffect(() => {
+    if (!enabled) return;
     const audio = audioRef.current;
     if (!audio) return;
 
@@ -176,10 +214,11 @@ export function useAudioSync(
       audio.removeEventListener('ended', handleEnded);
       audio.removeEventListener('error', handleError);
     };
-  }, [audioRef, currentSegment, audioTrack]);
+  }, [audioRef, currentSegment, audioTrack, enabled]);
 
   // Load new segment when currentSegment changes
   useEffect(() => {
+    if (!enabled) return;
     const audio = audioRef.current;
     if (!audio || !audioTrack?.segments) return;
 
@@ -209,15 +248,20 @@ export function useAudioSync(
     const isSameSource =
       currentSrc && (currentSrc === cachedBlobUrl || currentSrc.endsWith(segment.src));
 
+    let cancelled = false;
+    let handleCanPlay: (() => void) | null = null;
+
     if (!isSameSource) {
       // Need to load new source - use preloaded blob URL
       const loadAndPlay = async () => {
         const blobUrl = await preloadAudio(segment.src);
+        if (cancelled) return;
 
-        const handleCanPlay = () => {
+        handleCanPlay = () => {
+          if (cancelled) return;
           setIsAudioReady(true);
           applyPendingSeek();
-          audio.removeEventListener('canplay', handleCanPlay);
+          if (handleCanPlay) audio.removeEventListener('canplay', handleCanPlay);
         };
 
         audio.addEventListener('canplay', handleCanPlay);
@@ -228,18 +272,23 @@ export function useAudioSync(
         // Check after a microtask to see if it's ready
         await Promise.resolve();
         if (audio.readyState >= 3) {
-          audio.removeEventListener('canplay', handleCanPlay);
+          if (handleCanPlay) audio.removeEventListener('canplay', handleCanPlay);
           setIsAudioReady(true);
           applyPendingSeek();
         }
       };
 
-      loadAndPlay();
+      void loadAndPlay();
     } else {
       // Same source - apply seek directly
       applyPendingSeek();
     }
-  }, [audioRef, currentSegment, audioTrack, preloadAudio]);
+
+    return () => {
+      cancelled = true;
+      if (handleCanPlay) audio.removeEventListener('canplay', handleCanPlay);
+    };
+  }, [audioRef, currentSegment, audioTrack, preloadAudio, enabled]);
 
   const play = useCallback(() => {
     const audio = audioRef.current;

package/src/hooks/useDocPlayback.ts

@@ -58,18 +58,28 @@ interface PlaybackActions {
   prevBlock: () => void;
   /** Go to specific block by index */
   goToBlock: (index: number) => void;
+  /**
+   * Let the identified block enter without remounting the outgoing block.
+   * Used when another interaction (such as a swipe) already removed it.
+   */
+  suppressOutgoingForNextBlock: (blockId: string) => void;
+}
+
+export interface UseDocPlaybackOptions {
+  /** Target viewport used to materialize template blocks. */
+  viewport?: ViewportConfig;
+  /** Active theme used for materialization and transition defaults. */
+  theme?: Theme;
+  /** Host seek callback used by block navigation actions. */
+  onSeek?: (time: number) => void;
 }
 
 export function useDocPlayback(
   script: Doc | null,
   currentTime: number,
-  viewport: ViewportConfig = VIEWPORT_PRESETS.landscape,
-  renderMode: boolean = false,
-  theme?: Theme,
+  options: UseDocPlaybackOptions = {},
 ): PlaybackState & PlaybackActions {
-  // `renderMode` is retained for API/signature compatibility; block transitions
-  // are now computed identically for real-time and render (export) modes.
-  void renderMode;
+  const { viewport = VIEWPORT_PRESETS.landscape, theme, onSeek } = options;
   // Expand any template blocks into full blocks
   const blocks = useMemo(() => {
     if (!script?.blocks) {
@@ -174,8 +184,28 @@ export function useDocPlayback(
   const outgoingBlockRef = useRef<Block | null>(null);
   const activeBlockIdRef = useRef<string | null>(null);
   const lastRenderedBlockRef = useRef<Block | null>(null);
+  const suppressOutgoingTargetRef = useRef<string | null>(null);
+  const suppressOutgoingForNextBlock = useCallback((blockId: string) => {
+    // The managed cover is outside the document timeline, so revealing block
+    // one can target the block that is already active underneath it. Clear any
+    // stale outgoing context immediately; the cover visibility update will
+    // provide the render that observes this ref change.
+    if (activeBlockIdRef.current === blockId) {
+      outgoingBlockRef.current = null;
+      suppressOutgoingTargetRef.current = null;
+      return;
+    }
+    suppressOutgoingTargetRef.current = blockId;
+  }, []);
   if (currentBlock && currentBlock.id !== activeBlockIdRef.current) {
-    outgoingBlockRef.current = lastRenderedBlockRef.current;
+    // A swipe has already carried the outgoing slide fully off-screen. Keep
+    // the incoming block's own transition, but do not re-mount the old block
+    // as transition context when the armed destination becomes active.
+    const suppressOutgoing = suppressOutgoingTargetRef.current === currentBlock.id;
+    outgoingBlockRef.current = suppressOutgoing ? null : lastRenderedBlockRef.current;
+    // Consume on the first real block change even if the destination did not
+    // match (for example, a host performed a different seek in between).
+    suppressOutgoingTargetRef.current = null;
     activeBlockIdRef.current = currentBlock.id;
   }
   lastRenderedBlockRef.current = currentBlock;
@@ -194,15 +224,12 @@ export function useDocPlayback(
   const goToBlock = useCallback(
     (index: number) => {
       if (!script || index < 0 || index >= blocks.length) return;
-      // This would need to be coordinated with seekTo from audio sync
-      // For now, just return the target block's start time
       const targetBlock = blocks[index];
       if (targetBlock) {
-        // Caller should use this time with audio seekTo
-        return targetBlock.startTime;
+        onSeek?.(targetBlock.startTime);
       }
     },
-    [script, blocks],
+    [script, blocks, onSeek],
   );
 
   const nextBlock = useCallback(() => {
@@ -229,6 +256,7 @@ export function useDocPlayback(
     nextBlock,
     prevBlock,
     goToBlock,
+    suppressOutgoingForNextBlock,
     /** Expanded blocks (templates converted to full blocks with layers) */
     blocks,
   };

package/src/hooks/useViewportOrientation.ts

@@ -36,15 +36,13 @@ function getOrientationFromWindow(width: number, height: number): ViewportOrient
   // Use thresholds to determine orientation
   // - Ratio > 1.2 = landscape (wider than tall)
   // - Ratio < 0.83 (1/1.2) = portrait (taller than wide)
-  // - Otherwise = square-ish, use landscape for better readability
+  // - Otherwise = square-ish
   if (ratio > 1.2) {
     return 'landscape';
   } else if (ratio < 0.83) {
     return 'portrait';
   } else {
-    // Near-square viewports: use landscape for better text readability
-    // Could also use 'square' preset if available and desired
-    return 'landscape';
+    return 'square';
   }
 }
 

package/src/index.ts

@@ -1,6 +1,8 @@
 // Main components
 export { DocPlayer } from './DocPlayer.js';
-export { BlockRenderer, VIEWPORT } from './BlockRenderer.js';
+export type { DocPlayerProps } from './DocPlayer.js';
+export type { MountOptions, SquisqPlayerHandle } from './standalone-entry.js';
+export { BlockRenderer } from './BlockRenderer.js';
 export { CaptionOverlay } from './CaptionOverlay.js';
 export { SocialCaptionOverlay } from './SocialCaptionOverlay.js';
 export { DocControlsOverlay } from './DocControlsOverlay.js';
@@ -24,6 +26,7 @@ export { ShapeLayer } from './layers/ShapeLayer.js';
 export { PathLayer } from './layers/PathLayer.js';
 export { VideoLayer } from './layers/VideoLayer.js';
 export { TableLayer } from './layers/TableLayer.js';
+export { TreeLayer } from './layers/TreeLayer.js';
 export { MapLayer } from './layers/MapLayer.js';
 
 // Timed media clips (block.media + doc.documentMedia playback)
@@ -35,6 +38,7 @@ export { useAudioSync } from './hooks/useAudioSync.js';
 export { useMediaSchedule } from './hooks/useMediaSchedule.js';
 export type { MediaScheduleController } from './hooks/useMediaSchedule.js';
 export { useDocPlayback } from './hooks/useDocPlayback.js';
+export type { UseDocPlaybackOptions } from './hooks/useDocPlayback.js';
 export { useViewportOrientation } from './hooks/useViewportOrientation.js';
 export { MediaContext, useMediaProvider, useMediaUrl } from './hooks/MediaContext.js';
 export { useAutoSurface } from './hooks/useAutoSurface.js';
@@ -51,7 +55,6 @@ export type {
   CaptionMode,
   SlideNavActions,
   SquisqRenderAPI,
-  SquisqWindow,
   RenderBlockInfo,
   RenderAudioSegmentInfo,
   RenderCaptionInfo,

package/src/layers/ImageLayer.tsx

@@ -20,9 +20,17 @@ interface ImageLayerProps {
   viewport: { width: number; height: number };
   /** Current time relative to block start (for animation timing) */
   blockTime: number;
+  /** Whether authored and responsive image motion should run. */
+  animationsEnabled?: boolean;
 }
 
-export function ImageLayer({ layer, basePath, viewport, blockTime }: ImageLayerProps) {
+export function ImageLayer({
+  layer,
+  basePath,
+  viewport,
+  blockTime,
+  animationsEnabled = true,
+}: ImageLayerProps) {
   const { content, position, animation } = layer;
 
   // Resolve position values to pixels
@@ -55,6 +63,61 @@ export function ImageLayer({ layer, basePath, viewport, blockTime }: ImageLayerP
   // than shifting the entire image container.
   const isSpatialAnim = animation && SPATIAL_ANIMATION_TYPES.has(animation.type);
 
+  // Wide cover photos lose most of their composition when centered inside a
+  // portrait frame. For dominant imagery, scan the cover crop horizontally so
+  // the whole width is revealed over time. `object-position` only moves when
+  // the fitted image actually has horizontal overflow, so portrait sources stay
+  // visually still. This path deliberately avoids the extra Ken Burns scale:
+  // cover already scales the source by the minimum amount needed to fit one
+  // viewport dimension.
+  const usesPortraitPan =
+    isCover && shouldUsePortraitPan(viewport, width, height, animationsEnabled, animation);
+
+  if (usesPortraitPan) {
+    const panClass = getPortraitPanClass(animation);
+    const panStyle = getPortraitPanStyle(isSpatialAnim ? animation : undefined);
+    // Entrance/opacity animations can safely run on the fixed container while
+    // object-position pans the image. Spatial transforms are replaced by the
+    // pan so they cannot zoom an already aggressive portrait crop.
+    const containerAnim = isSpatialAnim ? { className: '', style: {} } : animStyle;
+
+    return (
+      <g
+        className={`block-layer block-layer--image ${containerAnim.className}`}
+        style={containerAnim.style}
+        data-layer-id={layer.id}
+        data-image-framing="portrait-pan"
+      >
+        <foreignObject x={finalX} y={finalY} width={width} height={height}>
+          <div
+            style={{
+              width: `${width}px`,
+              height: `${height}px`,
+              overflow: 'hidden',
+            }}
+          >
+            <img
+              src={src}
+              alt={content.alt || ''}
+              className={panClass}
+              style={{
+                width: `${width}px`,
+                height: `${height}px`,
+                objectFit: 'cover',
+                objectPosition: 'center',
+                display: 'block',
+                pointerEvents: 'none',
+                ...(filter ? { filter } : {}),
+                ...(content.blur && content.blur > 0 ? { transform: 'scale(1.06)' } : {}),
+                ...panStyle,
+              }}
+            />
+          </div>
+        </foreignObject>
+      </g>
+    );
+  }
+
   // Ken Burns mode: cover image with spatial animation.
   // Keep the container static, animate the inner <img> within clipped bounds.
   if (isCover && isSpatialAnim && animation) {
@@ -166,6 +229,48 @@ function getPreserveAspectRatio(fit?: 'cover' | 'contain' | 'fill'): string {
 /** Animation types that use CSS transforms (translate/scale). */
 const SPATIAL_ANIMATION_TYPES = new Set(['panLeft', 'panRight', 'slowZoom', 'zoomIn', 'zoomOut']);
 
+/** Portrait threshold matches useViewportOrientation's 0.83 aspect cutoff. */
+const PORTRAIT_ASPECT_CUTOFF = 0.83;
+
+/**
+ * Only auto-pan images that act as the slide's dominant visual. This keeps
+ * photo-grid tiles, thumbnails, and small authored insets from all moving at
+ * once while covering the full-screen autogenerated layouts.
+ */
+function shouldUsePortraitPan(
+  viewport: { width: number; height: number },
+  layerWidth: number,
+  layerHeight: number,
+  animationsEnabled: boolean,
+  animation: Animation | undefined,
+): boolean {
+  if (!animationsEnabled || animation?.type === 'none') return false;
+  if (viewport.width / viewport.height >= PORTRAIT_ASPECT_CUTOFF) return false;
+
+  return layerWidth >= viewport.width * 0.7 && layerHeight >= viewport.height * 0.7;
+}
+
+/**
+ * `panLeft` means the image moves left (the framing scans toward its right
+ * edge); `panRight` is the reverse. Unspecified motion defaults to revealing
+ * the source from left to right.
+ */
+function getPortraitPanClass(animation: Animation | undefined): string {
+  const pansBack =
+    animation?.type === 'panRight' ||
+    (animation?.type === 'slowZoom' && animation.panDirection === 'right');
+  return pansBack ? 'squisq-image--portrait-pan-left' : 'squisq-image--portrait-pan-right';
+}
+
+/** Use authored spatial timing when present, otherwise a slow ambient scan. */
+function getPortraitPanStyle(animation: Animation | undefined): Record<string, string> {
+  return {
+    '--portrait-pan-duration': `${animation?.duration ?? 12}s`,
+    '--portrait-pan-delay': `${animation?.delay ?? 0}s`,
+    '--portrait-pan-easing': animation?.easing ?? 'ease-in-out',
+  };
+}
+
 /**
  * Remap animation for Ken Burns inner-image rendering.
  *