@bendyline/squisq-react 0.1.3 → 1.0.2

package/dist/hooks/useAudioSync.js

@@ -0,0 +1,338 @@
+/**
+ * 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 AudioProvider interface.
+ * For EFB/MSFS environments, use useCompanionAudioSync instead.
+ */
+import { useState, useEffect, useRef, useCallback } from 'react';
+export function useAudioSync(audioRef, audioTrack, basePath = '') {
+    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([]);
+    // Pending seek time (used when switching segments)
+    const pendingSeekTime = useRef(null);
+    const shouldPlayAfterLoad = useRef(false);
+    // Preloaded audio blob URLs (for seeking without range request support)
+    const blobUrls = useRef(new Map());
+    const loadingPromises = useRef(new Map());
+    // 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) {
+            return;
+        }
+        let time = 0;
+        segmentStarts.current = audioTrack.segments.map((seg) => {
+            const start = time;
+            time += seg.duration;
+            return start;
+        });
+        setTotalDuration(time);
+    }, [audioTrack]);
+    // Preload audio file as blob (enables seeking without range request support)
+    const preloadAudio = useCallback(async (src) => {
+        const audioUrl = basePath ? `${basePath}/${src}` : src;
+        // 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 loadPromise = (async () => {
+            try {
+                const response = await fetch(audioUrl);
+                if (!response.ok)
+                    throw new Error(`HTTP ${response.status}`);
+                const blob = await response.blob();
+                const blobUrl = URL.createObjectURL(blob);
+                blobUrls.current.set(src, blobUrl);
+                return blobUrl;
+            }
+            catch {
+                // Fall back to direct URL if blob loading fails
+                return audioUrl;
+            }
+            finally {
+                loadingPromises.current.delete(src);
+            }
+        })();
+        loadingPromises.current.set(src, loadPromise);
+        return loadPromise;
+    }, [basePath]);
+    // Preload all audio segments on mount
+    useEffect(() => {
+        if (!audioTrack?.segments)
+            return;
+        // Preload all segments in parallel
+        audioTrack.segments.forEach((segment) => {
+            preloadAudio(segment.src);
+        });
+        // Cleanup blob URLs on unmount
+        const currentBlobUrls = blobUrls.current;
+        return () => {
+            currentBlobUrls.forEach((url) => {
+                URL.revokeObjectURL(url);
+            });
+            currentBlobUrls.clear();
+        };
+    }, [audioTrack, preloadAudio]);
+    // Handle audio time updates
+    useEffect(() => {
+        const audio = audioRef.current;
+        if (!audio)
+            return;
+        const handleTimeUpdate = () => {
+            // Calculate overall timeline position
+            const segmentStart = segmentStarts.current[currentSegment] || 0;
+            const overallTime = segmentStart + audio.currentTime;
+            setCurrentTime(overallTime);
+        };
+        const handlePlay = () => {
+            fallbackMode.current = false;
+            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]);
+    // Load new segment when currentSegment changes
+    useEffect(() => {
+        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));
+        if (!isSameSource) {
+            // Need to load new source - use preloaded blob URL
+            const loadAndPlay = async () => {
+                const blobUrl = await preloadAudio(segment.src);
+                const handleCanPlay = () => {
+                    setIsAudioReady(true);
+                    applyPendingSeek();
+                    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) {
+                    audio.removeEventListener('canplay', handleCanPlay);
+                    setIsAudioReady(true);
+                    applyPendingSeek();
+                }
+            };
+            loadAndPlay();
+        }
+        else {
+            // Same source - apply seek directly
+            applyPendingSeek();
+        }
+    }, [audioRef, currentSegment, audioTrack, preloadAudio]);
+    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) => {
+        const audio = audioRef.current;
+        if (!audio || !audioTrack?.segments)
+            return;
+        // Clamp time to valid range
+        const clampedTime = Math.max(0, Math.min(time, totalDuration));
+        // 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) => {
+        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;
+        const tick = (now) => {
+            // 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) => seekTo(time),
+        skipToSegment: async (index) => skipToSegment(index),
+        restart,
+    };
+}
+export default useAudioSync;
+//# sourceMappingURL=useAudioSync.js.map

package/dist/hooks/useAudioSync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAudioSync.js","sourceRoot":"","sources":["../../src/hooks/useAudioSync.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useDocPlayback.d.ts

@@ -0,0 +1,47 @@
+/**
+ * useDocPlayback Hook
+ *
+ * Manages the playback state for a visual doc, including which block
+ * is currently active, transition states, and synchronization with audio.
+ *
+ * This hook provides:
+ * - Current block determination based on time
+ * - Transition tracking (entering/exiting blocks)
+ * - Manual navigation (next/prev block)
+ * - Time-based seeking
+ * - Automatic expansion of template blocks
+ */
+import type { Doc, Block } from '@bendyline/squisq/schemas';
+import type { Theme } from '@bendyline/squisq/schemas';
+import { type ViewportConfig } from '@bendyline/squisq/doc';
+interface PlaybackState {
+    /** Currently visible block */
+    currentBlock: Block | null;
+    /** Index of current block */
+    currentBlockIndex: number;
+    /** Previous block (for transitions) */
+    previousBlock: Block | null;
+    /** Whether current block is entering */
+    isEntering: boolean;
+    /** Whether previous block is exiting */
+    isExiting: boolean;
+    /** Time relative to current block start */
+    blockTime: number;
+    /** Progress through current block (0-1) */
+    blockProgress: number;
+    /** Overall progress through doc (0-1) */
+    docProgress: number;
+    /** Expanded blocks (templates converted to full blocks with layers) */
+    blocks: Block[];
+}
+interface PlaybackActions {
+    /** Go to next block */
+    nextBlock: () => void;
+    /** Go to previous block */
+    prevBlock: () => void;
+    /** Go to specific block by index */
+    goToBlock: (index: number) => void;
+}
+export declare function useDocPlayback(script: Doc | null, currentTime: number, viewport?: ViewportConfig, renderMode?: boolean, theme?: Theme): PlaybackState & PlaybackActions;
+export default useDocPlayback;
+//# sourceMappingURL=useDocPlayback.d.ts.map

package/dist/hooks/useDocPlayback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDocPlayback.d.ts","sourceRoot":"","sources":["../../src/hooks/useDocPlayback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAY,MAAM,2BAA2B,CAAC;AACtE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AAEvD,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AAE/B,UAAU,aAAa;IACrB,8BAA8B;IAC9B,YAAY,EAAE,KAAK,GAAG,IAAI,CAAC;IAC3B,6BAA6B;IAC7B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uCAAuC;IACvC,aAAa,EAAE,KAAK,GAAG,IAAI,CAAC;IAC5B,wCAAwC;IACxC,UAAU,EAAE,OAAO,CAAC;IACpB,wCAAwC;IACxC,SAAS,EAAE,OAAO,CAAC;IACnB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,aAAa,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,MAAM,EAAE,KAAK,EAAE,CAAC;CACjB;AAED,UAAU,eAAe;IACvB,uBAAuB;IACvB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,oCAAoC;IACpC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED,wBAAgB,cAAc,CAC5B,MAAM,EAAE,GAAG,GAAG,IAAI,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,GAAE,cAA2C,EACrD,UAAU,GAAE,OAAe,EAC3B,KAAK,CAAC,EAAE,KAAK,GACZ,aAAa,GAAG,eAAe,CA2LjC;AAED,eAAe,cAAc,CAAC"}

package/dist/hooks/useDocPlayback.js

@@ -0,0 +1,176 @@
+/**
+ * useDocPlayback Hook
+ *
+ * Manages the playback state for a visual doc, including which block
+ * is currently active, transition states, and synchronization with audio.
+ *
+ * This hook provides:
+ * - Current block determination based on time
+ * - Transition tracking (entering/exiting blocks)
+ * - Manual navigation (next/prev block)
+ * - Time-based seeking
+ * - Automatic expansion of template blocks
+ */
+import { useState, useEffect, useMemo, useCallback, useRef } from 'react';
+import { getBlockAtTime } from '@bendyline/squisq/schemas';
+import { expandDocBlocks, isTemplateBlock, VIEWPORT_PRESETS, } from '@bendyline/squisq/doc';
+export function useDocPlayback(script, currentTime, viewport = VIEWPORT_PRESETS.landscape, renderMode = false, theme) {
+    const [transitionState, setTransitionState] = useState({
+        entering: false,
+        exiting: false,
+        previousBlock: null,
+    });
+    // Expand any template blocks into full blocks
+    const blocks = useMemo(() => {
+        if (!script?.blocks) {
+            return [];
+        }
+        // Check if any blocks are templates
+        const hasTemplates = script.blocks.some(isTemplateBlock);
+        if (hasTemplates) {
+            // Extract audio segment timing for proper block synchronization
+            const audioSegments = script.audio?.segments?.map((seg) => ({
+                startTime: seg.startTime,
+                duration: seg.duration,
+            }));
+            // Expand template blocks with audio segment timing, viewport, and persistent layers
+            const expanded = expandDocBlocks(script.blocks, {
+                audioSegments,
+                viewport,
+                persistentLayers: script.persistentLayers,
+                theme,
+            });
+            return expanded;
+        }
+        // All raw blocks, use as-is
+        return script.blocks;
+    }, [script?.blocks, script?.audio?.segments, script?.persistentLayers, viewport, theme]);
+    // Find current block based on time
+    const currentBlock = useMemo(() => getBlockAtTime(blocks, currentTime), [blocks, currentTime]);
+    const currentBlockIndex = useMemo(() => (currentBlock ? blocks.indexOf(currentBlock) : -1), [blocks, currentBlock]);
+    // Calculate block-relative time
+    const blockTime = useMemo(() => {
+        if (!currentBlock)
+            return 0;
+        return Math.max(0, currentTime - currentBlock.startTime);
+    }, [currentBlock, currentTime]);
+    // Calculate progress values
+    const blockProgress = useMemo(() => {
+        if (!currentBlock || currentBlock.duration === 0)
+            return 0;
+        return Math.min(1, blockTime / currentBlock.duration);
+    }, [currentBlock, blockTime]);
+    const docProgress = useMemo(() => {
+        if (!script || script.duration === 0)
+            return 0;
+        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(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;
+    // Manual navigation
+    const goToBlock = useCallback((index) => {
+        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;
+        }
+    }, [script, blocks]);
+    const nextBlock = useCallback(() => {
+        if (currentBlockIndex < blocks.length - 1) {
+            return goToBlock(currentBlockIndex + 1);
+        }
+    }, [currentBlockIndex, blocks.length, goToBlock]);
+    const prevBlock = useCallback(() => {
+        if (currentBlockIndex > 0) {
+            return goToBlock(currentBlockIndex - 1);
+        }
+    }, [currentBlockIndex, goToBlock]);
+    return {
+        currentBlock,
+        currentBlockIndex,
+        previousBlock: renderMode
+            ? renderIsExiting
+                ? renderPrevBlockRef.current
+                : null
+            : transitionState.exiting
+                ? transitionState.previousBlock
+                : null,
+        isEntering: renderMode ? renderIsEntering : transitionState.entering,
+        isExiting: renderMode ? renderIsExiting : transitionState.exiting,
+        blockTime,
+        blockProgress,
+        docProgress,
+        nextBlock,
+        prevBlock,
+        goToBlock,
+        /** Expanded blocks (templates converted to full blocks with layers) */
+        blocks,
+    };
+}
+export default useDocPlayback;
+//# sourceMappingURL=useDocPlayback.js.map

package/dist/hooks/useDocPlayback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDocPlayback.js","sourceRoot":"","sources":["../../src/hooks/useDocPlayback.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useViewportOrientation.d.ts

@@ -0,0 +1,31 @@
+/**
+ * useViewportOrientation Hook
+ *
+ * Detects the current viewport orientation and returns the appropriate
+ * VIEWPORT_PRESET for rendering docs. Automatically updates when
+ * the window is resized.
+ *
+ * Thresholds:
+ * - Portrait: height > width * 1.2 (significantly taller than wide)
+ * - Square: width and height within 20% of each other
+ * - Landscape: width > height * 1.2 (significantly wider than tall)
+ */
+import { type ViewportConfig, type ViewportOrientation } from '@bendyline/squisq/doc';
+interface UseViewportOrientationResult {
+    /** Current viewport preset configuration */
+    viewport: ViewportConfig;
+    /** Current orientation name */
+    orientation: ViewportOrientation;
+    /** Current window dimensions */
+    windowSize: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Hook to detect viewport orientation and return appropriate preset.
+ * Updates automatically when window is resized.
+ */
+export declare function useViewportOrientation(): UseViewportOrientationResult;
+export default useViewportOrientation;
+//# sourceMappingURL=useViewportOrientation.d.ts.map

package/dist/hooks/useViewportOrientation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useViewportOrientation.d.ts","sourceRoot":"","sources":["../../src/hooks/useViewportOrientation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACzB,MAAM,uBAAuB,CAAC;AAE/B,UAAU,4BAA4B;IACpC,4CAA4C;IAC5C,QAAQ,EAAE,cAAc,CAAC;IACzB,+BAA+B;IAC/B,WAAW,EAAE,mBAAmB,CAAC;IACjC,gCAAgC;IAChC,UAAU,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAsCD;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,4BAA4B,CA6CrE;AAED,eAAe,sBAAsB,CAAC"}