@hexdn/react 0.1.0

package/dist/player/use-media-video-player-interactions.js

@@ -0,0 +1,163 @@
+"use client";
+import { useCallback, useEffect, useLayoutEffect, useRef, } from "react";
+import { enterPlaybackFullscreen } from "./playback-landscape-presentation.js";
+import { isCoarsePlaybackPointer, isPlayerFullscreen, readPlaybackScreenOrientation, } from "./playback-landscape-presentation.js";
+import { readMediaVideoPlayerKeyboardShortcut, shouldIgnoreMediaVideoPlayerKeyboardShortcut, } from "./media-video-player-keyboard.js";
+import { resolveMediaVideoPlayerSurfaceClickAction } from "./media-video-player-surface-click.js";
+export function useMediaVideoPlayerInteractions(input) {
+    const latest = useRef(input);
+    useLayoutEffect(() => {
+        latest.current = input;
+    });
+    const videoClickTimerRef = useRef(null);
+    const clearVideoClickTimer = useCallback(() => {
+        if (videoClickTimerRef.current !== null)
+            window.clearTimeout(videoClickTimerRef.current);
+        videoClickTimerRef.current = null;
+    }, []);
+    const togglePlayback = useCallback(async () => {
+        const { controllerRef, hasPresentedMediaFrameRef, showControls, showPlaybackFeedback, videoRef, } = latest.current;
+        const controller = controllerRef.current;
+        if (!controller)
+            return;
+        if (!hasPresentedMediaFrameRef.current &&
+            !controller.getSnapshot().errorCode)
+            return;
+        showControls();
+        const action = videoRef.current?.paused || videoRef.current?.ended ? "play" : "pause";
+        await controller.togglePlayback();
+        if (!controller.getSnapshot().errorCode)
+            showPlaybackFeedback(action);
+    }, []);
+    const seekToTime = useCallback((time) => {
+        latest.current.showControls();
+        latest.current.controllerRef.current?.seek(time);
+    }, []);
+    const seekBackward = useCallback(() => {
+        const { videoRef, showPlaybackFeedback } = latest.current;
+        seekToTime((videoRef.current?.currentTime ?? 0) - 10);
+        showPlaybackFeedback("back-10s");
+    }, [seekToTime]);
+    const seekForward = useCallback(() => {
+        const { videoRef, showPlaybackFeedback } = latest.current;
+        seekToTime((videoRef.current?.currentTime ?? 0) + 10);
+        showPlaybackFeedback("fwd-10s");
+    }, [seekToTime]);
+    const toggleCaptions = useCallback(() => {
+        latest.current.showControls();
+        latest.current.controllerRef.current?.toggleCaptions();
+    }, []);
+    const toggleFullscreen = useCallback(async () => {
+        const { playerRef, controllerRef, showControls, onFullscreenError } = latest.current;
+        showControls();
+        try {
+            if (document.fullscreenElement) {
+                await document.exitFullscreen();
+                return;
+            }
+            const player = playerRef.current;
+            if (player?.requestFullscreen) {
+                await enterPlaybackFullscreen({
+                    lockLandscape: isCoarsePlaybackPointer(),
+                    orientation: readPlaybackScreenOrientation(),
+                    requestFullscreen: () => player.requestFullscreen(),
+                });
+                return;
+            }
+            controllerRef.current?.enterNativeFullscreen();
+        }
+        catch {
+            controllerRef.current?.rollbackNativeFullscreen();
+            onFullscreenError();
+        }
+    }, []);
+    const handleVideoClick = useCallback((event) => {
+        if (!latest.current.hasPresentedMediaFrameRef.current) {
+            clearVideoClickTimer();
+            return;
+        }
+        const target = event.currentTarget;
+        const action = resolveMediaVideoPlayerSurfaceClickAction({
+            clickCount: event.detail,
+            controlsVisible: latest.current.isControlsVisible,
+            ended: target.ended,
+            isCoarsePointer: isCoarsePlaybackPointer(),
+            paused: target.paused,
+        });
+        clearVideoClickTimer();
+        if (action === "ignore")
+            return;
+        latest.current.showControls();
+        if (action === "reveal-controls")
+            return;
+        if (action === "play-now") {
+            void togglePlayback();
+            return;
+        }
+        videoClickTimerRef.current = window.setTimeout(() => {
+            videoClickTimerRef.current = null;
+            void togglePlayback();
+        }, 220);
+    }, [clearVideoClickTimer, togglePlayback]);
+    const handleVideoDoubleClick = useCallback((event) => {
+        event.preventDefault();
+        clearVideoClickTimer();
+        if (latest.current.hasPresentedMediaFrameRef.current)
+            void toggleFullscreen();
+    }, [clearVideoClickTimer, toggleFullscreen]);
+    const handleBack = useCallback(async () => {
+        latest.current.showControls();
+        try {
+            if (isPlayerFullscreen({
+                fullscreenElement: document.fullscreenElement,
+                player: latest.current.playerRef.current,
+            }))
+                await document.exitFullscreen();
+        }
+        catch {
+            /* Navigation can continue if browser fullscreen exit fails. */
+        }
+        latest.current.onBack?.();
+    }, []);
+    const handleSeekChange = useCallback((event) => seekToTime(Number(event.currentTarget.value)), [seekToTime]);
+    useEffect(() => {
+        function keydown(event) {
+            const shortcut = readMediaVideoPlayerKeyboardShortcut(event);
+            if (!shortcut || shouldIgnoreMediaVideoPlayerKeyboardShortcut(event))
+                return;
+            const player = latest.current.playerRef.current, active = document.activeElement;
+            if (player &&
+                active instanceof HTMLElement &&
+                active !== document.body &&
+                !player.contains(active))
+                return;
+            event.preventDefault();
+            if (!latest.current.hasPresentedMediaFrameRef.current)
+                return;
+            if (shortcut === "restart")
+                seekToTime(0);
+            else if (shortcut === "seek-backward")
+                seekBackward();
+            else if (shortcut === "seek-forward")
+                seekForward();
+            else
+                void togglePlayback();
+        }
+        document.addEventListener("keydown", keydown);
+        return () => document.removeEventListener("keydown", keydown);
+    }, [seekBackward, seekForward, seekToTime, togglePlayback]);
+    useEffect(() => clearVideoClickTimer, [clearVideoClickTimer]);
+    return {
+        handleBack,
+        handleSeekChange,
+        handleVideoClick,
+        handleVideoDoubleClick,
+        seekBackward,
+        seekForward,
+        seekToTime,
+        toggleCaptions,
+        toggleFullscreen,
+        togglePlayback,
+        clearVideoClickTimer,
+    };
+}

package/dist/player/use-media-video-player-presentation.d.ts

@@ -0,0 +1,50 @@
+type MutableRef<T> = {
+    current: T;
+};
+export type MediaVideoPlayerPlaybackFeedback = {
+    readonly action: "back-10s" | "fwd-10s" | "pause" | "play";
+    readonly id: number;
+};
+export declare function createMediaVideoPlayerFeedbackController(input: {
+    readonly canShow: () => boolean;
+    readonly clearTimeout: (handle: number) => void;
+    readonly onFeedback: (feedback: MediaVideoPlayerPlaybackFeedback | null) => void;
+    readonly setTimeout: (listener: () => void, durationMs: number) => number;
+}): {
+    clearTimer: () => void;
+    dispose: () => void;
+    show: (action: MediaVideoPlayerPlaybackFeedback["action"]) => void;
+};
+export declare function createMediaVideoPlayerChromeEntrySchedule(input: {
+    readonly cancelAnimationFrame: (handle: number) => void;
+    readonly onEnter: () => void;
+    readonly requestAnimationFrame: (listener: () => void) => number;
+    readonly waitForTransitionIdle: () => Promise<void>;
+}): {
+    dispose(): void;
+};
+export declare function useMediaVideoPlayerPresentation(input: {
+    readonly hasPresentedMediaFrameRef: MutableRef<boolean>;
+}): {
+    clearChromeEntryFrame: () => void;
+    clearPlaybackFeedbackTimer: () => void;
+    chromeEntryScheduleRef: import("react").RefObject<{
+        dispose: () => void;
+    } | null>;
+    hasChromeEntered: boolean;
+    playbackFeedback: MediaVideoPlayerPlaybackFeedback | null;
+    setHasChromeEntered: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    setPlaybackFeedback: import("react").Dispatch<import("react").SetStateAction<MediaVideoPlayerPlaybackFeedback | null>>;
+    showPlaybackFeedback: (action: MediaVideoPlayerPlaybackFeedback["action"]) => void;
+};
+export declare function useMediaVideoPlayerChromeEntryLifecycle(input: {
+    readonly chromeEntryScheduleRef: MutableRef<{
+        dispose: () => void;
+    } | null>;
+    readonly hasError: boolean;
+    readonly isAutoplayPending: boolean;
+    readonly isMediaReady: boolean;
+    readonly setHasChromeEntered: (hasEntered: boolean) => void;
+    readonly sourceUrl: string;
+}): void;
+export {};

package/dist/player/use-media-video-player-presentation.js

@@ -0,0 +1,125 @@
+"use client";
+import { usePlayerHost } from "./player-host.js";
+import { useCallback, useEffect, useRef, useState } from "react";
+const playbackFeedbackDurationMs = 720;
+export function createMediaVideoPlayerFeedbackController(input) {
+    let sequence = 0;
+    let timerHandle = null;
+    function clearTimer() {
+        if (timerHandle === null) {
+            return;
+        }
+        input.clearTimeout(timerHandle);
+        timerHandle = null;
+    }
+    function show(action) {
+        if (!input.canShow()) {
+            return;
+        }
+        clearTimer();
+        sequence += 1;
+        input.onFeedback({ action, id: sequence });
+        timerHandle = input.setTimeout(() => {
+            timerHandle = null;
+            input.onFeedback(null);
+        }, playbackFeedbackDurationMs);
+    }
+    return {
+        clearTimer,
+        dispose: clearTimer,
+        show,
+    };
+}
+export function createMediaVideoPlayerChromeEntrySchedule(input) {
+    let cancelled = false;
+    let frameHandle = null;
+    void input.waitForTransitionIdle().then(() => {
+        if (cancelled) {
+            return;
+        }
+        frameHandle = input.requestAnimationFrame(() => {
+            frameHandle = input.requestAnimationFrame(() => {
+                frameHandle = null;
+                if (!cancelled) {
+                    input.onEnter();
+                }
+            });
+        });
+    });
+    return {
+        dispose() {
+            cancelled = true;
+            if (frameHandle !== null) {
+                input.cancelAnimationFrame(frameHandle);
+                frameHandle = null;
+            }
+        },
+    };
+}
+export function useMediaVideoPlayerPresentation(input) {
+    const [hasChromeEntered, setHasChromeEntered] = useState(false);
+    const [playbackFeedback, setPlaybackFeedback] = useState(null);
+    const chromeEntryScheduleRef = useRef(null);
+    const feedbackControllerRef = useRef(null);
+    feedbackControllerRef.current ??= createMediaVideoPlayerFeedbackController({
+        canShow: () => input.hasPresentedMediaFrameRef.current,
+        clearTimeout: (handle) => window.clearTimeout(handle),
+        onFeedback: setPlaybackFeedback,
+        setTimeout: (listener, durationMs) => window.setTimeout(listener, durationMs),
+    });
+    const clearChromeEntryFrame = useCallback(() => {
+        chromeEntryScheduleRef.current?.dispose();
+        chromeEntryScheduleRef.current = null;
+    }, []);
+    const clearPlaybackFeedbackTimer = useCallback(() => {
+        feedbackControllerRef.current?.clearTimer();
+    }, []);
+    const showPlaybackFeedback = useCallback((action) => {
+        feedbackControllerRef.current?.show(action);
+    }, []);
+    useEffect(() => {
+        return () => feedbackControllerRef.current?.dispose();
+    }, []);
+    return {
+        clearChromeEntryFrame,
+        clearPlaybackFeedbackTimer,
+        chromeEntryScheduleRef,
+        hasChromeEntered,
+        playbackFeedback,
+        setHasChromeEntered,
+        setPlaybackFeedback,
+        showPlaybackFeedback,
+    };
+}
+export function useMediaVideoPlayerChromeEntryLifecycle(input) {
+    const { chromeEntryScheduleRef, hasError, isAutoplayPending, isMediaReady, setHasChromeEntered, sourceUrl, } = input;
+    const { transition } = usePlayerHost();
+    const { waitForIdle: waitForPlaybackPowerTransitionIdle } = transition;
+    useEffect(() => {
+        setHasChromeEntered(false);
+        if ((!hasError && !isMediaReady) || isAutoplayPending) {
+            return;
+        }
+        const schedule = createMediaVideoPlayerChromeEntrySchedule({
+            cancelAnimationFrame: (handle) => window.cancelAnimationFrame(handle),
+            onEnter: () => setHasChromeEntered(true),
+            requestAnimationFrame: (listener) => window.requestAnimationFrame(listener),
+            waitForTransitionIdle: waitForPlaybackPowerTransitionIdle,
+        });
+        chromeEntryScheduleRef.current = schedule;
+        return () => {
+            schedule.dispose();
+            if (chromeEntryScheduleRef.current === schedule) {
+                chromeEntryScheduleRef.current = null;
+            }
+        };
+    }, [
+        chromeEntryScheduleRef,
+        hasError,
+        isAutoplayPending,
+        isMediaReady,
+        setHasChromeEntered,
+        sourceUrl,
+        waitForPlaybackPowerTransitionIdle,
+    ]);
+}

package/dist/player/use-media-video-player.d.ts

@@ -0,0 +1,81 @@
+import { type ChangeEvent, type MouseEvent } from "react";
+import { type PlaybackSourceResolver, type PlaybackSource, type PlaybackQualityEvent, type PlaybackRequestAuthorization } from "@hexdn/playback";
+import { type MediaVideoPlayerCopy, type MediaVideoPlayerError, type MediaVideoPlayerDebugSnapshot } from "@hexdn/playback/internal";
+import { type MediaVideoPlayerPlaybackFeedback } from "./use-media-video-player-presentation.js";
+import type { MediaVideoPlayerProgressSnapshot } from "@hexdn/playback/internal";
+export type { MediaVideoPlayerDebugSnapshot, MediaVideoPlayerCopy, MediaVideoPlayerProgressReason, MediaVideoPlayerProgressSnapshot, } from "@hexdn/playback/internal";
+export { formatMediaVideoTime } from "@hexdn/playback/internal";
+export type { MediaVideoPlayerPlaybackFeedback } from "./use-media-video-player-presentation.js";
+export type MediaVideoPlayerQualityEvent = PlaybackQualityEvent;
+export declare function useMediaVideoPlayer(input: {
+    readonly copy?: MediaVideoPlayerCopy | undefined;
+    readonly debugEnabled?: boolean | undefined;
+    readonly initialPositionMs?: number | undefined;
+    readonly onBack?: (() => void) | undefined;
+    readonly onProgress?: ((snapshot: MediaVideoPlayerProgressSnapshot) => void) | undefined;
+    readonly onIntent?: (() => void) | undefined;
+    readonly onQualityEvent?: ((event: PlaybackQualityEvent) => void) | undefined;
+    readonly getSource?: PlaybackSourceResolver | undefined;
+    readonly onProtectedPlaybackRefresh?: (() => Promise<PlaybackSource | null | undefined>) | undefined;
+    readonly playbackIdentity: string | undefined;
+    readonly autoPlay: boolean;
+    readonly requestAuthorization?: PlaybackRequestAuthorization | undefined;
+    readonly previewThumbnails?: import("@hexdn/playback").VideoPreviewThumbnails | undefined;
+    readonly sourceUrl: string;
+    readonly expiresAt?: string | undefined;
+}): {
+    playerRef: import("react").RefObject<HTMLDivElement | null>;
+    videoRef: import("react").RefObject<HTMLVideoElement | null>;
+    debug: MediaVideoPlayerDebugSnapshot | null;
+    source: PlaybackSource | null;
+    derived: {
+        bufferProgress: string;
+        chromeHasEntered: boolean;
+        controlsAreVisible: boolean;
+        effectiveVolume: number;
+        hasSeekableDuration: boolean;
+        seekProgress: string;
+        volumeProgress: string;
+    };
+    state: {
+        captionsAvailable: boolean;
+        captionsEnabled: boolean;
+        captionText: string | null;
+        currentTime: number;
+        duration: number;
+        error: MediaVideoPlayerError | null;
+        isAutoplayPending: boolean;
+        isBuffering: boolean;
+        isFullscreen: boolean;
+        isLoading: boolean;
+        isMuted: boolean;
+        isPlaying: boolean;
+        isPresentationReady: boolean;
+        playbackFeedback: MediaVideoPlayerPlaybackFeedback | null;
+    };
+    handlers: {
+        holdControls: () => void;
+        holdExtensionControls: () => void;
+        holdVolumeControls: () => void;
+        releaseControls: () => void;
+        releaseExtensionControls: () => void;
+        releaseVolumeControls: () => void;
+        showControls: () => void;
+        commitVolumePreference: () => void | undefined;
+        handleVolumeChange: (event: ChangeEvent<HTMLInputElement>) => void;
+        setVolumeFromRatio: (ratio: number) => void;
+        toggleMute: () => void | undefined;
+        retryPlayback: () => Promise<void>;
+        handleBack: () => Promise<void>;
+        handleSeekChange: (event: ChangeEvent<HTMLInputElement>) => void;
+        handleVideoClick: (event: MouseEvent<HTMLVideoElement>) => void;
+        handleVideoDoubleClick: (event: MouseEvent<HTMLVideoElement>) => void;
+        seekBackward: () => void;
+        seekForward: () => void;
+        seekToTime: (time: number) => void;
+        toggleCaptions: () => void;
+        toggleFullscreen: () => Promise<void>;
+        togglePlayback: () => Promise<void>;
+        clearVideoClickTimer: () => void;
+    };
+};

package/dist/player/use-media-video-player.js

@@ -0,0 +1,263 @@
+"use client";
+import { useCallback, useEffect, useLayoutEffect, useRef, useState, } from "react";
+import { createPlaybackController, } from "@hexdn/playback";
+import { resolveMediaVideoPlayerError, } from "@hexdn/playback/internal";
+import { resolveMediaVideoPlayerViewState } from "./media-video-player-view-state.js";
+import { usePlayerHost } from "./player-host.js";
+import { useMediaVideoPlayerControls } from "./use-media-video-player-controls.js";
+import { useMediaVideoPlayerFullscreen, useMediaVideoPlayerFullscreenLifecycle, } from "./use-media-video-player-fullscreen.js";
+import { useMediaVideoPlayerInteractions } from "./use-media-video-player-interactions.js";
+import { useMediaVideoPlayerPresentation, useMediaVideoPlayerChromeEntryLifecycle, } from "./use-media-video-player-presentation.js";
+export { formatMediaVideoTime } from "@hexdn/playback/internal";
+const defaultMediaVideoPlayerCopy = {
+    fullscreenUnavailableError: "Fullscreen is not available.",
+    playbackFailedError: "Video playback failed. Try again.",
+    playbackStartFailedError: "Video playback could not start.",
+    protectedPlaybackUnsupportedError: "Protected playback is not supported in this browser.",
+};
+const initialState = {
+    source: null,
+    currentTime: 0,
+    duration: 0,
+    bufferedEnd: 0,
+    errorCode: null,
+    isPlaying: false,
+    isAutoplayPending: false,
+    isMediaReady: false,
+    isMediaWaiting: true,
+    isPresentationReady: false,
+    captionsAvailable: false,
+    captionsEnabled: false,
+    captionText: null,
+    volume: 1,
+    isMuted: false,
+};
+export function useMediaVideoPlayer(input) {
+    const playerRef = useRef(null), videoRef = useRef(null), controllerRef = useRef(null);
+    const hasPresentedMediaFrameRef = useRef(false);
+    const [snapshot, setSnapshot] = useState(initialState);
+    const { isFullscreen, setIsFullscreen } = useMediaVideoPlayerFullscreen();
+    const controls = useMediaVideoPlayerControls({
+        hasPresentedMediaFrameRef,
+        playerRef,
+        videoRef,
+    });
+    const presentation = useMediaVideoPlayerPresentation({
+        hasPresentedMediaFrameRef,
+    });
+    const [fullscreenError, setFullscreenError] = useState(false), [debug, setDebug] = useState(null);
+    const host = usePlayerHost();
+    const latest = useRef({ input, controls, presentation, host });
+    useLayoutEffect(() => {
+        latest.current = { input, controls, presentation, host };
+    });
+    const canRefresh = Boolean(input.onProtectedPlaybackRefresh);
+    const { clearPlaybackFeedbackTimer, setPlaybackFeedback } = presentation;
+    const { transition, loadHlsEngine, preferences } = host;
+    useEffect(() => {
+        const video = videoRef.current;
+        if (!video)
+            return;
+        const current = latest.current.input;
+        const resolve = current.getSource ??
+            (current.onProtectedPlaybackRefresh
+                ? async () => {
+                    const next = await latest.current.input.onProtectedPlaybackRefresh?.();
+                    if (!next)
+                        throw new Error("Playback refresh returned no source.");
+                    return next;
+                }
+                : undefined);
+        const controller = createPlaybackController(video, {
+            source: current.sourceUrl
+                ? {
+                    sourceUrl: current.sourceUrl,
+                    expiresAt: current.expiresAt,
+                    requestAuthorization: current.requestAuthorization,
+                    previewThumbnails: current.previewThumbnails,
+                }
+                : undefined,
+            getSource: resolve,
+            identity: current.playbackIdentity,
+            autoPlay: current.autoPlay,
+            initialPositionMs: current.initialPositionMs,
+            transition,
+            loadHlsEngine,
+            preferences,
+            onIntent: () => latest.current.input.onIntent?.(),
+            onProgress: (event) => latest.current.input.onProgress?.(event),
+            onQualityEvent: (event) => latest.current.input.onQualityEvent?.(event),
+            onNativeFullscreenChange: setIsFullscreen,
+            onControlsRequest: (persistent) => persistent
+                ? latest.current.controls.showControlsPersistently()
+                : latest.current.controls.showControls(),
+        });
+        controllerRef.current = controller;
+        const sync = () => {
+            hasPresentedMediaFrameRef.current =
+                controller.getSnapshot().isPresentationReady;
+            setSnapshot(controller.getSnapshot());
+        };
+        sync();
+        const unsubscribe = controller.subscribe(sync);
+        return () => {
+            unsubscribe();
+            controller.destroy();
+            if (controllerRef.current === controller)
+                controllerRef.current = null;
+        };
+    }, [
+        transition,
+        loadHlsEngine,
+        preferences,
+        input.getSource,
+        canRefresh,
+        setIsFullscreen,
+    ]);
+    const applied = useRef(null);
+    useEffect(() => {
+        const previous = applied.current;
+        const next = {
+            sourceUrl: input.sourceUrl,
+            expiresAt: input.expiresAt,
+            authorization: input.requestAuthorization,
+            previews: input.previewThumbnails,
+            identity: input.playbackIdentity,
+            initialPositionMs: input.initialPositionMs,
+            autoPlay: input.autoPlay,
+        };
+        applied.current = next;
+        if (!input.sourceUrl ||
+            !previous ||
+            (previous.sourceUrl === next.sourceUrl &&
+                previous.expiresAt === next.expiresAt &&
+                previous.authorization === next.authorization &&
+                previous.previews === next.previews &&
+                previous.identity === next.identity &&
+                previous.initialPositionMs === next.initialPositionMs &&
+                previous.autoPlay === next.autoPlay))
+            return;
+        controllerRef.current?.setSource({
+            sourceUrl: input.sourceUrl,
+            expiresAt: input.expiresAt,
+            requestAuthorization: input.requestAuthorization,
+            previewThumbnails: input.previewThumbnails,
+        }, {
+            identity: input.playbackIdentity,
+            initialPositionMs: (previous.identity ??
+                controllerRef.current?.getSnapshot().source?.playbackId) !==
+                next.identity ||
+                previous.initialPositionMs !== next.initialPositionMs
+                ? input.initialPositionMs
+                : undefined,
+            autoPlay: input.autoPlay,
+        });
+        clearPlaybackFeedbackTimer();
+        setPlaybackFeedback(null);
+    }, [
+        input.sourceUrl,
+        input.expiresAt,
+        input.requestAuthorization,
+        input.previewThumbnails,
+        input.playbackIdentity,
+        input.initialPositionMs,
+        input.autoPlay,
+        clearPlaybackFeedbackTimer,
+        setPlaybackFeedback,
+    ]);
+    const onFullscreenError = useCallback(() => setFullscreenError(true), []);
+    const interactions = useMediaVideoPlayerInteractions({
+        controllerRef,
+        videoRef,
+        playerRef,
+        hasPresentedMediaFrameRef,
+        isControlsVisible: controls.isControlsVisible,
+        onBack: input.onBack,
+        showControls: controls.showControls,
+        showPlaybackFeedback: presentation.showPlaybackFeedback,
+        onFullscreenError,
+    });
+    useMediaVideoPlayerFullscreenLifecycle({ playerRef, setIsFullscreen });
+    useMediaVideoPlayerChromeEntryLifecycle({
+        chromeEntryScheduleRef: presentation.chromeEntryScheduleRef,
+        hasError: Boolean(snapshot.errorCode),
+        isAutoplayPending: snapshot.isAutoplayPending,
+        isMediaReady: snapshot.isMediaReady,
+        setHasChromeEntered: presentation.setHasChromeEntered,
+        sourceUrl: snapshot.source?.sourceUrl ?? input.sourceUrl,
+    });
+    useEffect(() => {
+        if (!input.debugEnabled) {
+            return;
+        }
+        const capture = () => setDebug(controllerRef.current?.getDebugSnapshot() ?? null);
+        // Snapshot browser media state before the first polling interval.
+        capture();
+        const timer = window.setInterval(capture, 500);
+        return () => window.clearInterval(timer);
+    }, [input.debugEnabled]);
+    const error = resolveMediaVideoPlayerError(snapshot.errorCode ?? (fullscreenError ? "fullscreen_unavailable" : null), input.copy ?? defaultMediaVideoPlayerCopy);
+    const viewState = resolveMediaVideoPlayerViewState({
+        ...snapshot,
+        hasError: Boolean(error),
+        isControlsVisible: controls.isControlsVisible,
+    });
+    return {
+        playerRef,
+        videoRef,
+        debug: input.debugEnabled ? debug : null,
+        source: snapshot.source,
+        derived: {
+            bufferProgress: viewState.bufferProgress,
+            chromeHasEntered: presentation.hasChromeEntered,
+            controlsAreVisible: viewState.controlsAreVisible,
+            effectiveVolume: viewState.effectiveVolume,
+            hasSeekableDuration: viewState.hasSeekableDuration,
+            seekProgress: viewState.seekProgress,
+            volumeProgress: viewState.volumeProgress,
+        },
+        state: {
+            captionsAvailable: snapshot.captionsAvailable,
+            captionsEnabled: snapshot.captionsEnabled,
+            captionText: snapshot.captionText,
+            currentTime: snapshot.currentTime,
+            duration: snapshot.duration,
+            error,
+            isAutoplayPending: snapshot.isAutoplayPending,
+            isBuffering: viewState.isBuffering,
+            isFullscreen,
+            isLoading: viewState.isLoading,
+            isMuted: snapshot.isMuted,
+            isPlaying: snapshot.isPlaying,
+            isPresentationReady: snapshot.isPresentationReady,
+            playbackFeedback: presentation.playbackFeedback,
+        },
+        handlers: {
+            ...interactions,
+            holdControls: controls.holdControls,
+            holdExtensionControls: controls.holdExtensionControls,
+            holdVolumeControls: controls.holdVolumeControls,
+            releaseControls: controls.releaseControls,
+            releaseExtensionControls: controls.releaseExtensionControls,
+            releaseVolumeControls: controls.releaseVolumeControls,
+            showControls: controls.showControls,
+            commitVolumePreference: () => controllerRef.current?.commitVolumePreference(),
+            handleVolumeChange: (event) => {
+                controllerRef.current?.setVolume(Number(event.currentTarget.value));
+                controllerRef.current?.commitVolumePreference();
+                controls.showControls();
+            },
+            setVolumeFromRatio: (ratio) => {
+                controllerRef.current?.setVolume(ratio);
+                controls.showControls();
+            },
+            toggleMute: () => controllerRef.current?.toggleMute(),
+            retryPlayback: async () => {
+                setFullscreenError(false);
+                presentation.clearPlaybackFeedbackTimer();
+                presentation.setPlaybackFeedback(null);
+                await controllerRef.current?.retry();
+            },
+        },
+    };
+}