@bendyline/squisq-react 2.0.1 → 2.2.0

package/src/hooks/useAudioSync.ts

@@ -1,456 +0,0 @@
-/**
- * useAudioSync Hook
- *
- * Synchronizes playback state with an audio element. Provides current
- * playback time, playing state, and methods to control audio playback.
- *
- * 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 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 { 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);
-  const [currentSegment, setCurrentSegment] = useState(0);
-  const [isEnded, setIsEnded] = useState(false);
-  const [isAudioReady, setIsAudioReady] = useState(false);
-  const [totalDuration, setTotalDuration] = useState(0);
-
-  // Calculate segment start times
-  const segmentStarts = useRef<number[]>([]);
-
-  // Pending seek time (used when switching segments)
-  const pendingSeekTime = useRef<number | null>(null);
-  const shouldPlayAfterLoad = useRef(false);
-
-  // 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(() => {
-    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;
-    }
-
-    let time = 0;
-    segmentStarts.current = audioTrack.segments.map((seg) => {
-      const start = time;
-      time += seg.duration;
-      return start;
-    });
-    setTotalDuration(time);
-  }, [audioTrack, enabled]);
-
-  // Preload audio file as blob (enables seeking without range request support)
-  const preloadAudio = useCallback(
-    async (src: string): Promise<string> => {
-      const audioUrl = resolveAudioUrl(src, basePath);
-
-      // Return cached blob URL if available
-      if (blobUrls.current.has(src)) {
-        return blobUrls.current.get(src)!;
-      }
-
-      // Return existing loading promise if in progress
-      if (loadingPromises.current.has(src)) {
-        return loadingPromises.current.get(src)!;
-      }
-
-      // Start loading
-      const controller = new AbortController();
-      abortControllers.current.add(controller);
-      const generation = loadGeneration.current;
-      const loadPromise = (async () => {
-        try {
-          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);
-        }
-      })();
-
-      loadingPromises.current.set(src, loadPromise);
-      return loadPromise;
-    },
-    [basePath],
-  );
-
-  // Preload all audio segments on mount
-  useEffect(() => {
-    if (!enabled || !audioTrack?.segments) return;
-
-    // Preload all segments in parallel
-    audioTrack.segments.forEach((segment) => {
-      preloadAudio(segment.src);
-    });
-
-    // 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, enabled]);
-
-  // Handle audio time updates
-  useEffect(() => {
-    if (!enabled) return;
-    const audio = audioRef.current;
-    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;
-      setCurrentTime(overallTime);
-    };
-
-    const handlePlay = () => {
-      // 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);
-    const handleError = () => {
-      // Audio source failed to load (e.g., 404 in CI or missing files).
-      // Set ready so the UI can still render controls and progress.
-      setIsAudioReady(true);
-    };
-    const handleEnded = () => {
-      // Move to next segment or end
-      if (audioTrack && currentSegment < audioTrack.segments.length - 1) {
-        // Auto-advance to next segment
-        // Set shouldPlayAfterLoad so the next segment auto-plays after loading
-        shouldPlayAfterLoad.current = true;
-        setCurrentSegment((prev) => prev + 1);
-      } else {
-        setIsEnded(true);
-        setIsPlaying(false);
-      }
-    };
-
-    audio.addEventListener('timeupdate', handleTimeUpdate);
-    audio.addEventListener('play', handlePlay);
-    audio.addEventListener('pause', handlePause);
-    audio.addEventListener('ended', handleEnded);
-    audio.addEventListener('error', handleError);
-
-    return () => {
-      audio.removeEventListener('timeupdate', handleTimeUpdate);
-      audio.removeEventListener('play', handlePlay);
-      audio.removeEventListener('pause', handlePause);
-      audio.removeEventListener('ended', handleEnded);
-      audio.removeEventListener('error', handleError);
-    };
-  }, [audioRef, currentSegment, audioTrack, enabled]);
-
-  // Load new segment when currentSegment changes
-  useEffect(() => {
-    if (!enabled) return;
-    const audio = audioRef.current;
-    if (!audio || !audioTrack?.segments) return;
-
-    const segment = audioTrack.segments[currentSegment];
-    if (!segment) return;
-
-    // Apply pending seek and play state
-    const applyPendingSeek = () => {
-      if (pendingSeekTime.current !== null) {
-        const segmentStart = segmentStarts.current[currentSegment] || 0;
-        const segmentTime = pendingSeekTime.current - segmentStart;
-        audio.currentTime = Math.max(0, segmentTime);
-        setCurrentTime(pendingSeekTime.current);
-        pendingSeekTime.current = null;
-      }
-
-      if (shouldPlayAfterLoad.current) {
-        audio.play().catch(() => {});
-        shouldPlayAfterLoad.current = false;
-      }
-    };
-
-    // Check if we're already on this source (avoid unnecessary reload)
-    // For blob URLs, check by segment src key
-    const currentSrc = audio.src;
-    const cachedBlobUrl = blobUrls.current.get(segment.src);
-    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;
-
-        handleCanPlay = () => {
-          if (cancelled) return;
-          setIsAudioReady(true);
-          applyPendingSeek();
-          if (handleCanPlay) audio.removeEventListener('canplay', handleCanPlay);
-        };
-
-        audio.addEventListener('canplay', handleCanPlay);
-        audio.src = blobUrl;
-        audio.load();
-
-        // If audio is already ready (blob is instant), canplay might not fire
-        // Check after a microtask to see if it's ready
-        await Promise.resolve();
-        if (audio.readyState >= 3) {
-          if (handleCanPlay) audio.removeEventListener('canplay', handleCanPlay);
-          setIsAudioReady(true);
-          applyPendingSeek();
-        }
-      };
-
-      void loadAndPlay();
-    } else {
-      // Same source - apply seek directly
-      applyPendingSeek();
-    }
-
-    return () => {
-      cancelled = true;
-      if (handleCanPlay) audio.removeEventListener('canplay', handleCanPlay);
-    };
-  }, [audioRef, currentSegment, audioTrack, preloadAudio, enabled]);
-
-  const play = useCallback(() => {
-    const audio = audioRef.current;
-    if (audio) {
-      if (isEnded) {
-        // Restart from beginning
-        setCurrentSegment(0);
-        setIsEnded(false);
-      }
-      audio
-        .play()
-        .then(() => {
-          fallbackMode.current = false;
-        })
-        .catch(() => {
-          // Audio playback failed (e.g., autoplay policy or 404).
-          // Enable fallback timer so blocks progress without audio.
-          fallbackMode.current = true;
-          setIsPlaying(true);
-        });
-    }
-  }, [audioRef, isEnded]);
-
-  const pause = useCallback(() => {
-    const audio = audioRef.current;
-    if (audio) {
-      audio.pause();
-    }
-    // Also set state directly for cases where audio isn't loaded
-    // (pause event won't fire if audio has no valid source)
-    setIsPlaying(false);
-  }, [audioRef]);
-
-  const toggle = useCallback(() => {
-    const audio = audioRef.current;
-    if (!audio) return;
-
-    // Use component state instead of audio.paused to handle cases where
-    // audio source isn't loaded (audio.paused is always true without a source)
-    if (!isPlaying) {
-      play();
-    } else {
-      pause();
-    }
-  }, [audioRef, isPlaying, play, pause]);
-
-  const seekTo = useCallback(
-    (time: number) => {
-      const audio = audioRef.current;
-      if (!audio || !audioTrack?.segments) return;
-
-      // Clamp time to valid range.
-      // When totalDuration is 0 (no audio segments), don't clamp — allow
-      // seeking by block timing alone (used in render mode / preview).
-      const clampedTime =
-        totalDuration > 0 ? Math.max(0, Math.min(time, totalDuration)) : Math.max(0, time);
-
-      // Find which segment this time falls into
-      let segmentIndex = 0;
-      let segmentStart = 0;
-      for (let i = 0; i < audioTrack.segments.length; i++) {
-        const segEnd = segmentStart + audioTrack.segments[i].duration;
-        if (clampedTime < segEnd) {
-          segmentIndex = i;
-          break;
-        }
-        segmentStart = segEnd;
-        // Handle edge case: time exactly at end goes to last segment
-        if (i === audioTrack.segments.length - 1) {
-          segmentIndex = i;
-        }
-      }
-
-      const wasPlaying = !audio.paused;
-      setIsEnded(false);
-
-      // Check if we need to switch segments
-      if (segmentIndex !== currentSegment) {
-        // Store pending seek time - will be applied after segment loads
-        pendingSeekTime.current = clampedTime;
-        shouldPlayAfterLoad.current = wasPlaying;
-        setCurrentSegment(segmentIndex);
-      } else {
-        // Same segment - seek directly
-        const segmentTime = clampedTime - segmentStart;
-        audio.currentTime = Math.max(0, segmentTime);
-        setCurrentTime(clampedTime);
-      }
-    },
-    [audioRef, audioTrack, currentSegment, totalDuration],
-  );
-
-  const skipToSegment = useCallback(
-    (index: number) => {
-      if (!audioTrack?.segments || index < 0 || index >= audioTrack.segments.length) {
-        return;
-      }
-      setCurrentSegment(index);
-      setIsEnded(false);
-    },
-    [audioTrack],
-  );
-
-  // Restart from beginning
-  const restart = useCallback(async () => {
-    seekTo(0);
-    // Small delay to ensure seek completes before playing
-    await new Promise((resolve) => setTimeout(resolve, 50));
-    play();
-  }, [seekTo, play]);
-
-  // Fallback timer: advance currentTime synthetically when audio.play() was blocked
-  // (e.g., autoplay policy or missing audio). Blocks progress at real-time pace
-  // without sound. Stops when audio actually starts playing or playback is paused.
-  useEffect(() => {
-    if (!isPlaying || !fallbackMode.current || !totalDuration) return;
-
-    let lastTime = performance.now();
-    let raf: number;
-
-    const tick = (now: number) => {
-      // Audio started playing for real — stop the fallback
-      if (!fallbackMode.current) return;
-
-      const dt = (now - lastTime) / 1000;
-      lastTime = now;
-
-      setCurrentTime((prev) => {
-        const next = prev + dt;
-        if (next >= totalDuration) {
-          fallbackMode.current = false;
-          setIsEnded(true);
-          setIsPlaying(false);
-          return totalDuration;
-        }
-        return next;
-      });
-
-      raf = requestAnimationFrame(tick);
-    };
-
-    raf = requestAnimationFrame(tick);
-    return () => cancelAnimationFrame(raf);
-  }, [isPlaying, totalDuration]);
-
-  return {
-    // State
-    currentTime,
-    isPlaying,
-    currentSegment,
-    totalDuration,
-    isEnded,
-    isReady: isAudioReady,
-    isAvailable: true, // HTML5 audio is always available in browsers
-    // Actions
-    play: async () => play(),
-    pause: async () => pause(),
-    toggle: async () => toggle(),
-    seekTo: async (time: number) => seekTo(time),
-    skipToSegment: async (index: number) => skipToSegment(index),
-    restart,
-  };
-}
-
-export default useAudioSync;

package/src/hooks/useAutoSurface.ts

@@ -1,33 +0,0 @@
-import { useCallback, useMemo, useSyncExternalStore } from 'react';
-import { DARK_SURFACE, LIGHT_SURFACE, type SurfaceScheme } from '@bendyline/squisq/schemas';
-
-const DARK_QUERY = '(prefers-color-scheme: dark)';
-const getServerSnapshot = () => LIGHT_SURFACE;
-
-/**
- * Live-track `prefers-color-scheme` and return a stable SurfaceScheme.
- * `enabled: false` short-circuits to LIGHT_SURFACE (callers pass `false`
- * when a static surface was provided so the hook never observes the
- * media query). The `MediaQueryList` and the `subscribe`/`getSnapshot`
- * callbacks are memoized so `useSyncExternalStore` doesn't resubscribe on
- * every parent render.
- */
-export function useAutoSurface(enabled: boolean): SurfaceScheme {
-  const mql = useMemo(
-    () => (enabled && typeof window !== 'undefined' ? window.matchMedia(DARK_QUERY) : null),
-    [enabled],
-  );
-
-  const subscribe = useCallback(
-    (cb: () => void) => {
-      if (!mql) return () => {};
-      mql.addEventListener('change', cb);
-      return () => mql.removeEventListener('change', cb);
-    },
-    [mql],
-  );
-
-  const getSnapshot = useCallback(() => (mql?.matches ? DARK_SURFACE : LIGHT_SURFACE), [mql]);
-
-  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
-}