= ({
}}
/>
)}
+ {previousBgVideoUrl && (isFadingIn || (isSwitching && !isNewBgReady)) && (
+
+ )}
{/* Background video - z-1 keeps it below backdrop blur layer (z-5) */}
{backgroundVideoUrl && (
diff --git a/frontend/src/components/Constructor/TransitionPreviewOverlay.tsx b/frontend/src/components/Constructor/TransitionPreviewOverlay.tsx
index e10d3cf..424a834 100644
--- a/frontend/src/components/Constructor/TransitionPreviewOverlay.tsx
+++ b/frontend/src/components/Constructor/TransitionPreviewOverlay.tsx
@@ -4,6 +4,9 @@
* Full-screen overlay for transition video preview.
* Designed to work with useTransitionPlayback hook which manages
* video src and playback externally via the videoRef.
+ *
+ * Supports letterbox mode to constrain transitions within canvas bounds,
+ * matching the behavior of background images and UI elements.
*/
import React from 'react';
@@ -15,26 +18,53 @@ interface TransitionPreviewOverlayProps {
isActive: boolean;
/** Whether the video is currently buffering (used to hide video during load) */
isBuffering?: boolean;
+ /** Letterbox styles from useCanvasScale - positions overlay within canvas bounds */
+ letterboxStyles?: React.CSSProperties;
+ /** Video object-fit mode (default: 'contain' to match backgrounds) */
+ videoFit?: 'contain' | 'cover';
+ /** Additional opacity value for fade-out effects (0-1) */
+ opacity?: number;
}
const TransitionPreviewOverlay: React.FC = ({
videoRef,
isActive,
isBuffering = false,
+ letterboxStyles,
+ videoFit = 'contain',
+ opacity,
}) => {
if (!isActive) return null;
+ // Video opacity: 0 while buffering, 1 otherwise
+ const videoOpacity = isBuffering ? 0 : 1;
+ // Container opacity: controlled by parent for fade-out effects
+ const containerOpacity = opacity ?? 1;
+
return (
-
-
+ // Outer: full viewport with black background (letterbox bars)
+ // No fade transition - transition video itself is the effect
+
- {/* Background image element - z-1 keeps it below backdrop blur (z-5).
- CSS backgroundImage provides instant display.
- Use native img for blob URLs to prevent repeated fetch requests from Next.js Image. */}
- {backgroundImageUrl && !backgroundVideoUrl && (
-
+ {/* Inner: respects letterbox dimensions when provided */}
+
);
};
diff --git a/frontend/src/components/RuntimePresentation.tsx b/frontend/src/components/RuntimePresentation.tsx
index 4bdfe53..e0c84a0 100644
--- a/frontend/src/components/RuntimePresentation.tsx
+++ b/frontend/src/components/RuntimePresentation.tsx
@@ -22,6 +22,7 @@ import BaseButton from './BaseButton';
import CardBox from './CardBox';
import { OfflineToggle } from './Offline/OfflineToggle';
import RuntimeElement from './RuntimeElement';
+import TransitionPreviewOverlay from './Constructor/TransitionPreviewOverlay';
import GalleryCarouselOverlay from './UiElements/GalleryCarouselOverlay';
import { BackdropPortalProvider } from './BackdropPortal';
import { RotatePrompt } from './RotatePrompt';
@@ -226,12 +227,12 @@ export default function RuntimePresentation({
},
});
- // Use shared background transition hook for fade-out and fade-in effects
+ // Use shared background transition hook for crossfade effects
const {
isOverlayFadingOut,
resetFadeOut,
isFadingIn,
- elementsOpacity,
+ onFadeInAnimationEnd,
resetFadeIn,
} = useBackgroundTransition({
pageSwitch,
@@ -349,10 +350,10 @@ export default function RuntimePresentation({
isReverse: isBack,
});
} else {
- // Direct navigation - use shared hook for smooth transition
- // Reset fade-in state to start fresh
- resetFadeIn();
- // Previous background stays visible until new one is ready
+ // Direct navigation with crossfade effect:
+ // useBackgroundTransition detects switching and applies animation classes
+ // - New page gets animate-crossfade-in (0 → 1)
+ // - Previous background gets animate-crossfade-out (1 → 0)
setIsBackgroundReady(false);
// Mark this page as initialized to prevent redundant effect calls
lastInitializedPageIdRef.current = targetPageId;
@@ -534,65 +535,17 @@ export default function RuntimePresentation({
style={{
...cssVars,
...letterboxStyles,
- backgroundImage: backgroundImageUrl
- ? `url("${backgroundImageUrl}")`
- : undefined,
- backgroundSize: 'contain',
- backgroundPosition: 'center',
- backgroundRepeat: 'no-repeat',
}}
>
+
+
- {backgroundImageUrl.startsWith('blob:') ? (
- // eslint-disable-next-line @next/next/no-img-element
- 
{
- setIsBackgroundReady(true);
- pageSwitch.markBackgroundReady();
- }}
- onError={() => {
- setIsBackgroundReady(true);
- pageSwitch.markBackgroundReady();
- }}
- />
- ) : (
- {
- setIsBackgroundReady(true);
- pageSwitch.markBackgroundReady();
- }}
- onError={() => {
- setIsBackgroundReady(true);
- pageSwitch.markBackgroundReady();
- }}
- />
- )}
-
- )}
-
- {/* Previous background overlay - shows during direct navigation until new bg is ready */}
+ {/* Previous background overlays - show during loading AND crossfade.
+ Uses CSS animation for fade-out effect.
+ Cleared by useBackgroundTransition after fade completes. */}
{pageSwitch.previousBgImageUrl &&
- pageSwitch.isSwitching &&
- !pageSwitch.isNewBgReady && (
+ (isFadingIn ||
+ (pageSwitch.isSwitching && !pageSwitch.isNewBgReady)) && (
)}
-
- {/* Background video - z-1 keeps it below backdrop blur (z-5) */}
- {backgroundVideoUrl && (
-
- )}
-
- {/* Page elements - z-40 ensures they appear above carousel background (z-10) and carousel controls (z-30) */}
-
- {pageElements.map((element: CanvasElement) => (
- handleElementClick(element)}
- resolveUrl={resolveUrlWithBlob}
- onGalleryCardClick={(cardIndex) =>
- handleGalleryCardClick(element, cardIndex)
- }
+ {pageSwitch.previousBgVideoUrl &&
+ (isFadingIn ||
+ (pageSwitch.isSwitching && !pageSwitch.isNewBgReady)) && (
+
- ))}
+ )}
+
+ {/* New page content wrapper - fades in for non-transition navigation.
+ z-1 ensures it's above previous backgrounds (z-0) during fade.
+ onAnimationEnd resets isFadingIn when CSS animation completes. */}
+
+ {/* Background image element - z-1 keeps it below backdrop blur (z-5).
+ CSS backgroundImage provides instant display.
+ Use native img for blob URLs to prevent repeated fetch requests from Next.js Image. */}
+ {backgroundImageUrl && !backgroundVideoUrl && (
+
+ {/* End new page content wrapper */}
{/* Controls: Offline toggle and Fullscreen button */}
+ {backgroundImageUrl.startsWith('blob:') ? (
+ // eslint-disable-next-line @next/next/no-img-element
+ {
+ setIsBackgroundReady(true);
+ pageSwitch.markBackgroundReady();
+ }}
+ onError={() => {
+ setIsBackgroundReady(true);
+ pageSwitch.markBackgroundReady();
+ }}
+ />
+ ) : (
+ {
+ setIsBackgroundReady(true);
+ pageSwitch.markBackgroundReady();
+ }}
+ onError={() => {
+ setIsBackgroundReady(true);
+ pageSwitch.markBackgroundReady();
+ }}
+ />
+ )}
+
+ )}
+
+ {/* Background video - z-1 keeps it below backdrop blur (z-5) */}
+ {backgroundVideoUrl && (
+
+ )}
+
+ {/* Page elements - z-40 ensures they appear above carousel background (z-10) and carousel controls (z-30) */}
+
+ {pageElements.map((element: CanvasElement) => (
+ handleElementClick(element)}
+ resolveUrl={resolveUrlWithBlob}
+ onGalleryCardClick={(cardIndex) =>
+ handleGalleryCardClick(element, cardIndex)
+ }
+ />
+ ))}
+
@@ -661,24 +672,13 @@ export default function RuntimePresentation({
{/* Opacity is 0 during 'preparing' phase to show old page while video loads */}
{/* Also fades to 0 when isOverlayFadingOut to reveal the new page underneath */}
{transitionPreview && (
-
-
-
+
+ *
* @example
* // Simple mode - direct navigation only (constructor)
* useBackgroundTransition({ pageSwitch });
@@ -109,15 +115,10 @@ export function useBackgroundTransition({
fadeIn,
}: UseBackgroundTransitionOptions): UseBackgroundTransitionResult {
const [isOverlayFadingOut, setIsOverlayFadingOut] = useState(false);
-
- // Fade-in state
const [isFadingIn, setIsFadingIn] = useState(false);
- const [elementsOpacity, setElementsOpacity] = useState(1);
// Track previous isSwitching state to detect transition start
const wasSwitchingRef = useRef(false);
- // Track timer for cleanup
- const fadeInTimerRef = useRef | null>(null);
/**
* Reset fade-out state before starting a new transition.
@@ -128,16 +129,18 @@ export function useBackgroundTransition({
}, []);
/**
- * Reset fade-in state before starting new navigation.
- * Clears any in-progress fade animation.
+ * Reset fade-in state (for cleanup or cancellation).
*/
const resetFadeIn = useCallback(() => {
- if (fadeInTimerRef.current) {
- clearTimeout(fadeInTimerRef.current);
- fadeInTimerRef.current = null;
- }
setIsFadingIn(false);
- setElementsOpacity(1);
+ }, []);
+
+ /**
+ * Handler for onAnimationEnd event.
+ * Called when CSS animation completes - CSS is the source of truth for duration.
+ */
+ const onFadeInAnimationEnd = useCallback(() => {
+ setIsFadingIn(false);
}, []);
/**
@@ -187,92 +190,55 @@ export function useBackgroundTransition({
}, [fadeOut, isOverlayFadingOut, pageSwitch]);
/**
- * Effect: Clear previous background overlay when new background is ready (direct navigation).
+ * Effect: Clear previous background overlay after fade completes (direct navigation).
*
- * This handles the case when navigating without a transition video.
- * The previous background stays visible until the new one is ready to paint.
+ * The previous background stays visible during the entire fade animation,
+ * providing a smooth crossfade effect. Only cleared after fade ends.
*/
useEffect(() => {
- if (
- pageSwitch.isSwitching &&
- pageSwitch.isNewBgReady &&
- pageSwitch.previousBgImageUrl
- ) {
- // New background is ready - clear the previous background overlay
+ if (pageSwitch.isSwitching && pageSwitch.isNewBgReady && !isFadingIn) {
+ // Fade is complete - clear the previous background overlay
+ // This also resets isSwitching state so next navigation triggers fade-in
pageSwitch.clearPreviousBackground();
}
}, [
pageSwitch.isSwitching,
pageSwitch.isNewBgReady,
- pageSwitch.previousBgImageUrl,
pageSwitch.clearPreviousBackground,
+ isFadingIn,
]);
/**
- * Effect: Fade-in page content on non-transition navigation.
+ * Layout effect: Set up crossfade BEFORE browser paints when switching starts.
+ * useLayoutEffect runs synchronously after DOM mutations but before paint,
+ * preventing any flash of new content at full opacity.
*
- * Trigger: pageSwitch.isSwitching becomes true AND no active transition
- *
- * Sequence:
- * 1. Navigation starts (isSwitching: false → true)
- * 2. No transition video active
- * 3. Set elementsOpacity = 0
- * 4. Use double RAF to ensure paint before animation
- * 5. Set elementsOpacity = 1 (CSS animates)
- * 6. After duration, set isFadingIn = false
+ * IMPORTANT: Skip this for transitions - transition video IS the effect.
*/
- useEffect(() => {
+ useLayoutEffect(() => {
if (!fadeIn) {
wasSwitchingRef.current = pageSwitch.isSwitching;
return;
}
- const { hasActiveTransition, durationMs = FADE_IN_DURATION_MS } = fadeIn;
+ const { hasActiveTransition } = fadeIn;
const justStartedSwitching =
pageSwitch.isSwitching && !wasSwitchingRef.current;
+
wasSwitchingRef.current = pageSwitch.isSwitching;
- // Start fade-in when:
- // - Just started switching (transition from false to true)
- // - No active transition video
+ // Only start crossfade for NON-transition navigation
+ // Transitions use video overlay - no fade needed
if (justStartedSwitching && !hasActiveTransition) {
setIsFadingIn(true);
- setElementsOpacity(0);
-
- // Double RAF ensures opacity:0 is painted before transition starts
- // (Same pattern as usePageSwitch.ts:396-397)
- requestAnimationFrame(() => {
- requestAnimationFrame(() => {
- setElementsOpacity(1);
- });
- });
-
- // Clear any existing timer
- if (fadeInTimerRef.current) {
- clearTimeout(fadeInTimerRef.current);
- }
-
- // Mark fade as complete after duration
- fadeInTimerRef.current = setTimeout(() => {
- setIsFadingIn(false);
- fadeInTimerRef.current = null;
- }, durationMs);
}
-
- // Cleanup on unmount
- return () => {
- if (fadeInTimerRef.current) {
- clearTimeout(fadeInTimerRef.current);
- fadeInTimerRef.current = null;
- }
- };
}, [pageSwitch.isSwitching, fadeIn]);
return {
isOverlayFadingOut,
resetFadeOut,
isFadingIn,
- elementsOpacity,
+ onFadeInAnimationEnd,
resetFadeIn,
};
}
diff --git a/frontend/src/hooks/usePageSwitch.ts b/frontend/src/hooks/usePageSwitch.ts
index 762fb0c..242ee64 100644
--- a/frontend/src/hooks/usePageSwitch.ts
+++ b/frontend/src/hooks/usePageSwitch.ts
@@ -63,6 +63,8 @@ export interface UsePageSwitchResult {
currentBgAudioUrl: string;
/** Previous background image URL (for overlay) */
previousBgImageUrl: string;
+ /** Previous background video URL (for overlay during fade) */
+ previousBgVideoUrl: string;
/** Whether we're in the middle of a page switch */
isSwitching: boolean;
/** Whether the new background is ready to display */
@@ -198,6 +200,10 @@ export function usePageSwitch(
const previousBgImageUrlRef = useRef('');
previousBgImageUrlRef.current = previousBgImageUrl;
+ const [previousBgVideoUrl, setPreviousBgVideoUrl] = useState('');
+ const previousBgVideoUrlRef = useRef('');
+ previousBgVideoUrlRef.current = previousBgVideoUrl;
+
// Transition state
const [isSwitching, setIsSwitching] = useState(false);
const [isNewBgReady, setIsNewBgReady] = useState(true);
@@ -362,16 +368,20 @@ export function usePageSwitch(
setCurrentBgVideoUrl('');
setCurrentBgAudioUrl('');
setPreviousBgImageUrl('');
+ setPreviousBgVideoUrl('');
setIsSwitching(false);
setIsNewBgReady(true);
onSwitched?.();
return;
}
- // Save current image as previous for overlay (use ref to avoid dependency)
+ // Save current backgrounds as previous for overlay (use refs to avoid dependencies)
if (currentBgImageUrlRef.current) {
setPreviousBgImageUrl(currentBgImageUrlRef.current);
}
+ if (currentBgVideoUrlRef.current) {
+ setPreviousBgVideoUrl(currentBgVideoUrlRef.current);
+ }
setIsSwitching(true);
setIsNewBgReady(false);
@@ -433,16 +443,21 @@ export function usePageSwitch(
}, []);
/**
- * Clear the previous background overlay
+ * Clear the previous background overlay (both image and video)
*/
const clearPreviousBackground = useCallback(() => {
- const prevUrl = previousBgImageUrlRef.current;
+ const prevImageUrl = previousBgImageUrlRef.current;
+ const prevVideoUrl = previousBgVideoUrlRef.current;
setPreviousBgImageUrl('');
+ setPreviousBgVideoUrl('');
setIsSwitching(false);
- // Revoke the previous blob URL after clearing
- if (prevUrl) {
- revokeBlobUrl(prevUrl);
+ // Revoke the previous blob URLs after clearing
+ if (prevImageUrl) {
+ revokeBlobUrl(prevImageUrl);
+ }
+ if (prevVideoUrl) {
+ revokeBlobUrl(prevVideoUrl);
}
}, [revokeBlobUrl]);
@@ -451,6 +466,7 @@ export function usePageSwitch(
currentBgVideoUrl,
currentBgAudioUrl,
previousBgImageUrl,
+ previousBgVideoUrl,
isSwitching,
isNewBgReady,
switchToPage,
diff --git a/frontend/src/pages/constructor.tsx b/frontend/src/pages/constructor.tsx
index 08a0897..50cad67 100644
--- a/frontend/src/pages/constructor.tsx
+++ b/frontend/src/pages/constructor.tsx
@@ -358,10 +358,9 @@ const ConstructorPage = ({ mode = 'constructor' }: ConstructorPageProps) => {
// Destructure stable callback reference to avoid infinite loops in useEffect deps
const pageSwitchToPage = pageSwitch.switchToPage;
- // Use shared background transition hook for direct navigation clearing and fade-in
- // (No fade-out needed in constructor - transitions complete immediately)
- // NOTE: Must be defined before switchToPage callback which uses resetFadeIn
- const { isFadingIn, elementsOpacity, resetFadeIn } = useBackgroundTransition({
+ // Use shared background transition hook for direct navigation clearing and crossfade
+ // Crossfade starts automatically when new background is ready
+ const { isFadingIn } = useBackgroundTransition({
pageSwitch,
fadeIn: {
hasActiveTransition: Boolean(transitionPreview),
@@ -374,9 +373,6 @@ const ConstructorPage = ({ mode = 'constructor' }: ConstructorPageProps) => {
// isBack parameter indicates this is a back navigation (pops history instead of pushing)
const switchToPage = useCallback(
async (page: TourPage | null, isBack = false) => {
- // Reset fade-in state to start fresh
- resetFadeIn();
-
// Mark this page as initialized to prevent redundant effect calls
if (page) {
lastInitializedPageIdRef.current = page.id;
@@ -386,6 +382,7 @@ const ConstructorPage = ({ mode = 'constructor' }: ConstructorPageProps) => {
updateBackgroundFromPage(page);
// Use hook to resolve and set blob URLs for display
+ // Fade starts automatically when new background is ready (crossfade effect)
await pageSwitchToPage(
page
? {
@@ -403,12 +400,7 @@ const ConstructorPage = ({ mode = 'constructor' }: ConstructorPageProps) => {
},
);
},
- [
- pageSwitchToPage,
- updateBackgroundFromPage,
- applyPageSelection,
- resetFadeIn,
- ],
+ [pageSwitchToPage, updateBackgroundFromPage, applyPageSelection],
);
const { isBuffering: isReverseBuffering } = useTransitionPlayback({
@@ -1466,8 +1458,10 @@ const ConstructorPage = ({ mode = 'constructor' }: ConstructorPageProps) => {
backgroundVideoUrl={backgroundVideoSrc}
backgroundAudioUrl={backgroundAudioSrc}
previousBgImageUrl={pageSwitch.previousBgImageUrl}
+ previousBgVideoUrl={pageSwitch.previousBgVideoUrl}
isSwitching={pageSwitch.isSwitching}
isNewBgReady={pageSwitch.isNewBgReady}
+ isFadingIn={isFadingIn}
onBackgroundReady={() => pageSwitch.markBackgroundReady()}
videoAutoplay={backgroundVideoAutoplay}
videoLoop={backgroundVideoLoop}
@@ -1478,13 +1472,7 @@ const ConstructorPage = ({ mode = 'constructor' }: ConstructorPageProps) => {
{/* Elements container - z-10 ensures they appear above backdrop layer */}
{isLoading ? (
@@ -1590,6 +1578,7 @@ const ConstructorPage = ({ mode = 'constructor' }: ConstructorPageProps) => {
videoRef={transitionVideoRef}
isActive={Boolean(transitionPreview)}
isBuffering={isReverseBuffering}
+ letterboxStyles={letterboxStyles}
/>
{/* Gallery Carousel Overlay */}