@hexdn/react 0.1.0

package/dist/player/ready-player.js

@@ -0,0 +1,293 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { usePlayerAnalytics, } from "./use-player-analytics.js";
+import { createPlayerTranslator } from "./player-labels.js";
+import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
+import { Button } from "./ui-primitives.js";
+import { DsIcon, resolveDsVolumeLevel, } from "./player-icon.js";
+import { EmptyState } from "./ui-primitives.js";
+import { Notice } from "./ui-primitives.js";
+import { cn } from "./utils.js";
+import styles from "./media-video-player.module.css";
+import { areVideoViewportInsetsEqual, buildCaptionViewportStyle, buildVolumeSliderStyle, clampScrubberRatio, emptyVideoViewportInsets, readVideoViewportInsets, } from "./media-video-player-layout.js";
+import { MediaVideoPlayerScrubber } from "./media-video-player-scrubber.js";
+import { PlaybackLoadingIndicator } from "./playback-loading-indicator.js";
+import { PlayerControlPopover } from "./player-control-popover.js";
+import { formatMediaVideoTime, useMediaVideoPlayer, } from "./use-media-video-player.js";
+const playbackFeedbackIconNames = {
+    "back-10s": "back10",
+    "fwd-10s": "fwd10",
+    pause: "pause",
+    play: "play",
+};
+function MediaVideoPlayPauseGlyph({ isPlaying, }) {
+    return (_jsxs("span", { "aria-hidden": "true", className: styles.playPauseGlyph, "data-hexdn-state": isPlaying ? "playing" : "paused", children: [_jsx("span", { className: cn(styles.playPauseGlyphIcon, styles.playPauseGlyphPlay), children: _jsx(DsIcon, { name: "play" }) }), _jsx("span", { className: cn(styles.playPauseGlyphIcon, styles.playPauseGlyphPause), children: _jsx(DsIcon, { name: "pause" }) })] }));
+}
+export function ReadyPlayer({ autoPlay = true, getSource, analytics, style, sourceError, onRetrySource, className, initialPositionMs, onBack, onProgress, onQualityEvent, onProtectedPlaybackRefresh, playbackIdentity, posterUrl, previewThumbnails, requestAuthorization, sourceUrl, expiresAt, subtitle, title = "Video", labels, slots, debugControls = false, loadDebugHud, }) {
+    const t = useMemo(() => createPlayerTranslator(labels), [labels]);
+    const debugControlVisible = debugControls && Boolean(loadDebugHud);
+    const [debugRequested, setDebugRequested] = useState(false);
+    const [DebugHud, setDebugHud] = useState(null);
+    const debugEnabled = debugControlVisible && debugRequested;
+    const toggleDebug = useCallback(() => {
+        if (!debugControlVisible) {
+            return;
+        }
+        if (debugRequested) {
+            setDebugRequested(false);
+            return;
+        }
+        setDebugRequested(true);
+        if (DebugHud) {
+            return;
+        }
+        void loadDebugHud?.()
+            .then((component) => {
+            if (!component) {
+                setDebugRequested(false);
+                return;
+            }
+            setDebugHud(() => component);
+        })
+            .catch(() => {
+            // Diagnostics are optional and must never take down core playback.
+            setDebugRequested(false);
+        });
+    }, [DebugHud, debugControlVisible, debugRequested, loadDebugHud]);
+    const analyticsMonitorRef = useRef(null);
+    const handleIntent = useCallback(() => {
+        analyticsMonitorRef.current?.intent();
+    }, []);
+    const handleQualityEvent = useCallback((event) => {
+        if (event.type === "first-frame")
+            analyticsMonitorRef.current?.recordFirstFrame();
+        if (event.type === "error")
+            analyticsMonitorRef.current?.recordError(event.errorCode, {
+                fatal: event.errorCode !== "fullscreen_unavailable",
+            });
+        onQualityEvent?.(event);
+    }, [onQualityEvent]);
+    const [videoViewportInsets, setVideoViewportInsets] = useState(emptyVideoViewportInsets);
+    const volumePointerIdRef = useRef(null);
+    const playerCopy = useMemo(() => ({
+        fullscreenUnavailableError: t("playback.fullscreenUnavailableError"),
+        playbackFailedError: t("playback.playbackFailedError"),
+        playbackStartFailedError: t("playback.playbackStartFailedError"),
+        protectedPlaybackUnsupportedError: t("playback.protectedPlaybackUnsupportedError"),
+    }), [t]);
+    const { debug, derived, handlers, playerRef, state, videoRef, source: currentSource, } = useMediaVideoPlayer({
+        copy: playerCopy,
+        debugEnabled,
+        initialPositionMs,
+        getSource,
+        onBack,
+        onIntent: handleIntent,
+        onProgress,
+        onQualityEvent: handleQualityEvent,
+        onProtectedPlaybackRefresh,
+        playbackIdentity: playbackIdentity ?? (sourceUrl || undefined),
+        autoPlay,
+        requestAuthorization,
+        previewThumbnails,
+        sourceUrl,
+        expiresAt,
+    });
+    const playbackSourceState = currentSource ?? {
+        sourceUrl,
+        expiresAt,
+        requestAuthorization,
+        previewThumbnails,
+    };
+    usePlayerAnalytics({
+        analytics,
+        autoPlay,
+        monitorRef: analyticsMonitorRef,
+        sourceError,
+        videoRef,
+    });
+    const volumeSliderStyle = buildVolumeSliderStyle(derived.effectiveVolume, derived.volumeProgress);
+    const volumeLevel = resolveDsVolumeLevel(derived.effectiveVolume);
+    const captionViewportStyle = buildCaptionViewportStyle(videoViewportInsets);
+    const captionLines = useMemo(() => {
+        if (!state.captionText) {
+            return [];
+        }
+        const seenLines = new Map();
+        return state.captionText
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => {
+            const occurrence = seenLines.get(line) ?? 0;
+            seenLines.set(line, occurrence + 1);
+            return {
+                id: occurrence === 0 ? line : `${line}:${occurrence}`,
+                text: line,
+            };
+        });
+    }, [state.captionText]);
+    const terminalError = sourceError
+        ? {
+            code: "playback_start_failed",
+            message: sourceError,
+            terminal: true,
+            retryable: true,
+        }
+        : state.error?.terminal
+            ? state.error
+            : null;
+    const retryPlayback = sourceError && onRetrySource ? onRetrySource : handlers.retryPlayback;
+    const controlError = state.error && !state.error.terminal ? state.error : null;
+    useEffect(() => {
+        if (!debugControlVisible) {
+            // Close optional diagnostics when the host removes their capability.
+            // eslint-disable-next-line react-hooks/set-state-in-effect
+            setDebugRequested(false);
+        }
+    }, [debugControlVisible]);
+    useEffect(() => {
+        const video = videoRef.current;
+        if (!video) {
+            setVideoViewportInsets(emptyVideoViewportInsets);
+            return;
+        }
+        const targetVideo = video;
+        let frameId = null;
+        function syncVideoViewportInsets() {
+            frameId = null;
+            setVideoViewportInsets((currentInsets) => {
+                const nextInsets = readVideoViewportInsets(targetVideo);
+                return areVideoViewportInsetsEqual(currentInsets, nextInsets)
+                    ? currentInsets
+                    : nextInsets;
+            });
+        }
+        function scheduleVideoViewportSync() {
+            if (frameId !== null) {
+                return;
+            }
+            frameId = window.requestAnimationFrame(syncVideoViewportInsets);
+        }
+        const resizeObserver = typeof ResizeObserver === "undefined"
+            ? null
+            : new ResizeObserver(scheduleVideoViewportSync);
+        resizeObserver?.observe(targetVideo);
+        targetVideo.addEventListener("emptied", scheduleVideoViewportSync);
+        targetVideo.addEventListener("loadedmetadata", scheduleVideoViewportSync);
+        targetVideo.addEventListener("loadstart", scheduleVideoViewportSync);
+        targetVideo.addEventListener("resize", scheduleVideoViewportSync);
+        window.addEventListener("resize", scheduleVideoViewportSync);
+        scheduleVideoViewportSync();
+        return () => {
+            if (frameId !== null) {
+                window.cancelAnimationFrame(frameId);
+            }
+            resizeObserver?.disconnect();
+            targetVideo.removeEventListener("emptied", scheduleVideoViewportSync);
+            targetVideo.removeEventListener("loadedmetadata", scheduleVideoViewportSync);
+            targetVideo.removeEventListener("loadstart", scheduleVideoViewportSync);
+            targetVideo.removeEventListener("resize", scheduleVideoViewportSync);
+            window.removeEventListener("resize", scheduleVideoViewportSync);
+        };
+    }, [videoRef]);
+    const { setVolumeFromRatio, commitVolumePreference } = handlers;
+    const readVolumeRatio = useCallback((event) => {
+        const rect = event.currentTarget.getBoundingClientRect();
+        if (rect.height <= 0) {
+            return null;
+        }
+        return clampScrubberRatio((rect.bottom - event.clientY) / rect.height);
+    }, []);
+    const setVolumeFromPointer = useCallback((event) => {
+        const ratio = readVolumeRatio(event);
+        if (ratio === null) {
+            return;
+        }
+        setVolumeFromRatio(ratio);
+    }, [setVolumeFromRatio, readVolumeRatio]);
+    const handleVolumePointerDown = useCallback((event) => {
+        if (event.button !== 0) {
+            return;
+        }
+        event.preventDefault();
+        event.currentTarget.setPointerCapture(event.pointerId);
+        volumePointerIdRef.current = event.pointerId;
+        setVolumeFromPointer(event);
+    }, [setVolumeFromPointer]);
+    const handleVolumePointerMove = useCallback((event) => {
+        if (volumePointerIdRef.current !== event.pointerId) {
+            return;
+        }
+        setVolumeFromPointer(event);
+    }, [setVolumeFromPointer]);
+    const releaseVolumePointer = useCallback((event) => {
+        if (volumePointerIdRef.current !== event.pointerId) {
+            return;
+        }
+        setVolumeFromPointer(event);
+        commitVolumePreference();
+        if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+            event.currentTarget.releasePointerCapture(event.pointerId);
+        }
+        volumePointerIdRef.current = null;
+    }, [commitVolumePreference, setVolumeFromPointer]);
+    const cancelVolumePointer = useCallback((event) => {
+        if (volumePointerIdRef.current !== event.pointerId) {
+            return;
+        }
+        if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+            event.currentTarget.releasePointerCapture(event.pointerId);
+        }
+        volumePointerIdRef.current = null;
+    }, []);
+    const slotControls = {
+        showControls: handlers.showControls,
+        holdControls: handlers.holdExtensionControls,
+        releaseControls: handlers.releaseExtensionControls,
+    };
+    return (_jsxs("div", { "aria-busy": state.isLoading ? true : undefined, className: cn(styles.player, className), "data-hexdn-chrome-entered": derived.chromeHasEntered ? "true" : "false", "data-hexdn-controls-visible": derived.controlsAreVisible ? "true" : "false", "data-hexdn-presentation-ready": state.isPresentationReady ? "true" : "false", "data-hexdn-terminal-error": terminalError ? "true" : "false", "data-hexdn-player-control-popover-boundary": "", onPointerEnter: handlers.showControls, ref: playerRef, style: style, tabIndex: -1, children: [_jsx("video", { "aria-label": title, className: styles.video, inert: state.isPresentationReady ? undefined : true, onClick: handlers.handleVideoClick, onDoubleClick: handlers.handleVideoDoubleClick, onPointerDown: () => {
+                    playerRef.current?.focus({ preventScroll: true });
+                    handlers.showControls();
+                }, onPointerMove: handlers.showControls, disablePictureInPicture: true, playsInline: true, poster: posterUrl, preload: autoPlay ? "auto" : "metadata", ref: videoRef }), _jsx("span", { "aria-hidden": "true", className: styles.presentationCurtain }), state.isPresentationReady && state.playbackFeedback ? (_jsx("div", { "aria-hidden": "true", className: styles.playbackFeedback, children: _jsx("span", { className: cn(styles.playbackFeedbackIcon, styles.glassSurface), children: _jsx(DsIcon, { name: playbackFeedbackIconNames[state.playbackFeedback.action] }) }) }, state.playbackFeedback.id)) : null, _jsxs("div", { className: styles.chrome, inert: state.isPresentationReady && !terminalError ? undefined : true, children: [_jsxs("div", { className: styles.top, children: [onBack ? (_jsx("button", { "aria-label": t("playback.backAction"), className: styles.backButton, onFocus: handlers.showControls, onPointerDown: handlers.showControls, onPointerMove: handlers.showControls, onClick: () => {
+                                    void handlers.handleBack();
+                                }, type: "button", children: _jsx(DsIcon, { name: "chevron-l" }) })) : null, onBack ? (_jsxs("button", { "aria-label": t("playback.backAction"), className: cn(styles.titleBlock, styles.titleBackTarget), onFocus: handlers.showControls, onPointerDown: handlers.showControls, onPointerMove: handlers.showControls, onClick: () => {
+                                    void handlers.handleBack();
+                                }, type: "button", children: [_jsx("span", { className: styles.title, children: title }), subtitle ? (_jsx("span", { className: styles.subtitle, children: subtitle })) : null] })) : (_jsxs("div", { className: styles.titleBlock, children: [_jsx("p", { className: styles.title, children: title }), subtitle ? _jsx("p", { className: styles.subtitle, children: subtitle }) : null] })), slots?.headerTrailing?.(slotControls), debugControlVisible ? (_jsx("div", { className: styles.topActions, children: _jsx("button", { "aria-label": debugEnabled
+                                        ? t("playback.hideStatsAction")
+                                        : t("playback.showStatsAction"), "aria-pressed": debugEnabled, className: styles.controlButton, "data-hexdn-active": debugEnabled ? "true" : "false", onFocus: handlers.showControls, onPointerDown: handlers.showControls, onPointerMove: handlers.showControls, onClick: toggleDebug, type: "button", children: _jsx(DsIcon, { name: "info" }) }) })) : null] }), _jsx("div", { className: styles.center, children: _jsx(PlaybackLoadingIndicator, { content: slots?.loading, active: state.isLoading, deferUntilTransitionIdle: !derived.chromeHasEntered, delayMs: state.isPresentationReady ? 0 : undefined }) }), derived.chromeHasEntered &&
+                        state.isPresentationReady &&
+                        captionLines.length > 0 ? (_jsx("div", { "aria-hidden": "true", className: styles.captions, style: captionViewportStyle, children: captionLines.map((line) => (_jsx("span", { className: styles.captionLine, children: line.text }, line.id))) })) : null, _jsxs("div", { className: styles.bottom, onPointerEnter: handlers.holdControls, onPointerLeave: handlers.releaseControls, children: [_jsx("div", { className: styles.meta, children: _jsxs("p", { className: styles.time, children: [_jsx("span", { children: formatMediaVideoTime(state.currentTime) }), _jsx("span", { "aria-hidden": "true", className: styles.timeSeparator, children: "/" }), _jsx("span", { className: styles.timeMuted, children: formatMediaVideoTime(state.duration) })] }) }), _jsx(MediaVideoPlayerScrubber, { bufferProgress: derived.bufferProgress, currentTime: state.currentTime, duration: state.duration, hasSeekableDuration: derived.hasSeekableDuration, onSeekChange: handlers.handleSeekChange, onSeekToTime: handlers.seekToTime, onShowControls: handlers.showControls, previewThumbnails: playbackSourceState.previewThumbnails, requestAuthorization: playbackSourceState.requestAuthorization, seekLabel: t("playback.seekLabel"), seekProgress: derived.seekProgress, seekValueText: t("playback.seekValueText", {
+                                    current: formatMediaVideoTime(state.currentTime),
+                                    duration: formatMediaVideoTime(state.duration),
+                                }) }), _jsxs("div", { className: styles.controls, children: [_jsx("div", { className: styles.controlsLeft, children: slots?.leadingControls?.(slotControls) }), _jsxs("div", { className: styles.controlsCenter, children: [_jsx("button", { "aria-label": t("playback.rewind10Action"), className: styles.controlButton, disabled: !derived.hasSeekableDuration, onFocus: handlers.showControls, onPointerDown: handlers.showControls, onPointerMove: handlers.showControls, onClick: handlers.seekBackward, type: "button", children: _jsx(DsIcon, { name: "back10" }) }), _jsx("button", { "aria-label": t(state.isPlaying
+                                                    ? "playback.pauseVideoAction"
+                                                    : "playback.playVideoAction"), className: cn(styles.controlButton, styles.primaryControlButton), onFocus: handlers.showControls, onPointerDown: handlers.showControls, onPointerMove: handlers.showControls, onClick: () => {
+                                                    void handlers.togglePlayback();
+                                                }, type: "button", children: _jsx(MediaVideoPlayPauseGlyph, { isPlaying: state.isPlaying }) }), _jsx("button", { "aria-label": t("playback.forward10Action"), className: styles.controlButton, disabled: !derived.hasSeekableDuration, onFocus: handlers.showControls, onPointerDown: handlers.showControls, onPointerMove: handlers.showControls, onClick: handlers.seekForward, type: "button", children: _jsx(DsIcon, { name: "fwd10" }) })] }), _jsxs("div", { className: styles.controlsRight, children: [_jsx(PlayerControlPopover, { align: "center", className: styles.volume, content: _jsxs("span", { className: styles.volumeTrack, onPointerCancel: cancelVolumePointer, onPointerDown: handleVolumePointerDown, onPointerMove: handleVolumePointerMove, onPointerUp: releaseVolumePointer, style: volumeSliderStyle, children: [_jsx("span", { className: styles.volumeFill }), _jsx("input", { "aria-label": t("playback.volumeLabel"), className: styles.volumeSlider, max: 1, min: 0, onChange: handlers.handleVolumeChange, onFocus: handlers.showControls, step: 0.01, type: "range", value: derived.effectiveVolume })] }), contentClassName: styles.volumePopover, onInteraction: handlers.holdVolumeControls, onInteractionEnd: handlers.releaseVolumeControls, openDelayMs: 0, children: _jsx("button", { "aria-label": t(state.isMuted
+                                                        ? "playback.unmuteVideoAction"
+                                                        : "playback.muteVideoAction"), className: styles.controlButton, onFocus: handlers.showControls, onPointerDown: handlers.showControls, onPointerMove: handlers.showControls, onClick: handlers.toggleMute, type: "button", children: _jsx(DsIcon, { name: "volume", volumeLevel: volumeLevel }) }) }), state.captionsAvailable ? (_jsx("button", { "aria-label": t(state.captionsEnabled
+                                                    ? "playback.disableCaptionsAction"
+                                                    : "playback.enableCaptionsAction"), "aria-pressed": state.captionsEnabled, className: styles.controlButton, "data-hexdn-active": state.captionsEnabled ? "true" : "false", onFocus: handlers.showControls, onPointerDown: handlers.showControls, onPointerMove: handlers.showControls, onClick: handlers.toggleCaptions, type: "button", children: _jsx(DsIcon, { name: "captions" }) })) : null, _jsx("button", { "aria-label": state.isFullscreen
+                                                    ? t("playback.exitFullscreenAction")
+                                                    : t("playback.enterFullscreenAction"), className: styles.controlButton, onFocus: handlers.showControls, onPointerDown: handlers.showControls, onPointerMove: handlers.showControls, onClick: () => {
+                                                    void handlers.toggleFullscreen();
+                                                }, type: "button", children: _jsx(DsIcon, { name: "fullscreen" }) })] })] })] })] }), terminalError
+                ? (slots?.terminalError?.({
+                    error: terminalError,
+                    retry: retryPlayback,
+                    back: onBack ? handlers.handleBack : undefined,
+                }) ?? (_jsx(EmptyState, { action: terminalError.retryable || onBack ? (_jsxs(_Fragment, { children: [terminalError.retryable ? (_jsx(Button, { onClick: () => {
+                                    void retryPlayback();
+                                }, size: "md", type: "button", children: t("playback.retryAction") })) : null, onBack ? (_jsx(Button, { onClick: () => {
+                                    void handlers.handleBack();
+                                }, size: "md", type: "button", variant: "ghost", children: t("playback.backAction") })) : null] })) : undefined, body: terminalError.code === "protected_playback_unsupported"
+                        ? terminalError.message
+                        : t("playback.sessionUnavailableBody"), className: styles.terminalError, icon: _jsx(DsIcon, { name: "error" }), role: "alert", title: t("playback.sessionUnavailableTitle") })))
+                : null, controlError
+                ? (slots?.controlError?.(controlError.message) ?? (_jsx(Notice, { className: styles.controlError, inline: true, role: "alert", children: controlError.message })))
+                : null, debugEnabled &&
+                DebugHud &&
+                debug &&
+                state.isPresentationReady &&
+                !terminalError ? (_jsx(DebugHud, { debug: debug })) : null] }));
+}

package/dist/player/tooltip-surface.d.ts

@@ -0,0 +1,2 @@
+import { type HTMLAttributes } from "react";
+export declare const TooltipSurface: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLSpanElement> & import("react").RefAttributes<HTMLSpanElement>>;

package/dist/player/tooltip-surface.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { cn } from "./utils.js";
+import styles from "./ui.module.css";
+export const TooltipSurface = forwardRef(function TooltipSurface({ className, ...props }, ref) {
+    return (_jsx("span", { className: cn("hexdn-tooltip-surface", styles.tooltipSurface, className), ref: ref, ...props }));
+});
+TooltipSurface.displayName = "TooltipSurface";

package/dist/player/ui-primitives.d.ts

@@ -0,0 +1,17 @@
+import type { ButtonHTMLAttributes, HTMLAttributes, ReactNode } from "react";
+export declare function Button({ className, variant, size, ...props }: ButtonHTMLAttributes<HTMLButtonElement> & {
+    readonly variant?: "ghost" | undefined;
+    readonly size?: "md" | undefined;
+}): import("react").JSX.Element;
+export declare function EmptyState({ action, body, className, icon, role, title, }: {
+    readonly action?: ReactNode;
+    readonly body: string;
+    readonly className?: string | undefined;
+    readonly icon?: ReactNode;
+    readonly role?: "alert" | undefined;
+    readonly title: string;
+}): import("react").JSX.Element;
+export declare function Notice({ className, inline, ...props }: HTMLAttributes<HTMLDivElement> & {
+    readonly inline?: boolean | undefined;
+}): import("react").JSX.Element;
+export declare function LoadingIndicator(): import("react").JSX.Element;

package/dist/player/ui-primitives.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "./utils.js";
+import styles from "./ui.module.css";
+export function Button({ className, variant, size, ...props }) {
+    return (_jsx("button", { ...props, "data-hexdn-size": size, className: cn(styles.button, variant === "ghost" && styles.ghostButton, className) }));
+}
+export function EmptyState({ action, body, className, icon, role, title, }) {
+    return (_jsxs("div", { className: cn(styles.errorSurface, className), role: role, children: [icon, _jsx("strong", { children: title }), _jsx("p", { children: body }), _jsx("div", { className: styles.errorActions, children: action })] }));
+}
+export function Notice({ className, inline, ...props }) {
+    return (_jsx("div", { ...props, "data-hexdn-inline": inline ? "true" : undefined, className: cn(styles.notice, className) }));
+}
+export function LoadingIndicator() {
+    return _jsx("span", { "aria-hidden": "true", className: styles.spinner });
+}

package/dist/player/ui.module.css

@@ -0,0 +1,113 @@
+.icon {
+  display: block;
+  width: 1.5rem;
+  height: 1.5rem;
+  flex: none;
+}
+
+.button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 44px;
+  padding: 0.6rem 1rem;
+  border: 1px solid transparent;
+  border-radius: 8px;
+  background: #f5f4f1;
+  color: #121212;
+  font: inherit;
+  cursor: pointer;
+}
+
+.button:focus-visible {
+  outline: 2px solid currentColor;
+  outline-offset: 3px;
+}
+
+.ghostButton {
+  color: inherit;
+  background: transparent;
+  border-color: currentColor;
+}
+
+.errorSurface {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 1rem;
+  padding: 2rem;
+  text-align: center;
+}
+
+.errorSurface p {
+  margin: 0;
+  max-width: 30rem;
+}
+
+.errorActions {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.notice {
+  padding: 0.75rem 1rem;
+  border-radius: 8px;
+  background: rgb(20 20 20 / 85%);
+}
+
+.spinner {
+  display: block;
+  width: 2.5rem;
+  height: 2.5rem;
+  border: 3px solid rgb(255 255 255 / 25%);
+  border-top-color: white;
+  border-radius: 50%;
+  animation: spin 850ms linear infinite;
+}
+
+@keyframes spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .spinner {
+    animation: none;
+  }
+}
+
+.tooltipSurface {
+  padding: 0.35rem 0.55rem;
+  border-radius: 6px;
+  background: rgb(20 20 20 / 90%);
+  color: white;
+  font: inherit;
+}
+
+.icon :global(.hexdn-volume-glyph-speaker),
+.icon :global(.hexdn-volume-glyph-wave),
+.icon :global(.hexdn-volume-glyph-mute) {
+  transform-box: fill-box;
+  transform-origin: center;
+  transition:
+    fill-opacity 220ms cubic-bezier(0.2, 0.8, 0.2, 1),
+    opacity 220ms cubic-bezier(0.2, 0.8, 0.2, 1),
+    transform 220ms cubic-bezier(0.2, 0.8, 0.2, 1);
+}
+.icon :global(.hexdn-volume-glyph-wave),
+.icon :global(.hexdn-volume-glyph-mute) {
+  opacity: 0;
+  transform: scale(0.72);
+}
+.icon[data-hexdn-volume-level="muted"] :global(.hexdn-volume-glyph-speaker) {
+  fill-opacity: 0;
+}
+.icon[data-hexdn-volume-level="muted"] :global(.hexdn-volume-glyph-mute),
+.icon[data-hexdn-volume-level="low"] :global(.hexdn-volume-glyph-wave--low),
+.icon[data-hexdn-volume-level="high"] :global(.hexdn-volume-glyph-wave) {
+  opacity: 1;
+  transform: scale(1);
+}

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

@@ -0,0 +1,17 @@
+import { type RefObject } from "react";
+export declare function useMediaVideoPlayerControls({ hasPresentedMediaFrameRef, playerRef, videoRef, }: {
+    readonly hasPresentedMediaFrameRef: RefObject<boolean>;
+    readonly playerRef: RefObject<HTMLDivElement | null>;
+    readonly videoRef: RefObject<HTMLVideoElement | null>;
+}): {
+    clearControlsHideTimer: () => void;
+    holdControls: () => void;
+    holdExtensionControls: () => void;
+    holdVolumeControls: () => void;
+    isControlsVisible: boolean;
+    releaseControls: () => void;
+    releaseExtensionControls: () => void;
+    releaseVolumeControls: () => void;
+    showControls: () => void;
+    showControlsPersistently: () => void;
+};

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

@@ -0,0 +1,87 @@
+"use client";
+import { useCallback, useEffect, useRef, useState, } from "react";
+import { setMediaVideoPlayerControlHold, } from "./media-video-player-control-hold.js";
+import { blurFocusedMediaVideoPlayerControl } from "./media-video-player-keyboard.js";
+const CONTROLS_HIDE_DELAY_MS = 2_800;
+const SHOW_CONTROLS_EVENT_INTERVAL_MS = 120;
+export function useMediaVideoPlayerControls({ hasPresentedMediaFrameRef, playerRef, videoRef, }) {
+    const controlsHideTimerRef = useRef(null);
+    const controlHoldReasonsRef = useRef(new Set());
+    const showControlsLastHandledAtRef = useRef(0);
+    const [isControlsVisible, setIsControlsVisible] = useState(true);
+    const clearControlsHideTimer = useCallback(() => {
+        if (controlsHideTimerRef.current === null) {
+            return;
+        }
+        window.clearTimeout(controlsHideTimerRef.current);
+        controlsHideTimerRef.current = null;
+    }, []);
+    useEffect(() => clearControlsHideTimer, [clearControlsHideTimer]);
+    const showControlsPersistently = useCallback(() => {
+        clearControlsHideTimer();
+        setIsControlsVisible(true);
+    }, [clearControlsHideTimer]);
+    const showControls = useCallback(() => {
+        const nowMs = window.performance.now();
+        const recentlyHandled = nowMs - showControlsLastHandledAtRef.current <
+            SHOW_CONTROLS_EVENT_INTERVAL_MS;
+        if (recentlyHandled && controlsHideTimerRef.current !== null) {
+            return;
+        }
+        showControlsLastHandledAtRef.current = nowMs;
+        clearControlsHideTimer();
+        setIsControlsVisible((current) => (current ? current : true));
+        const video = videoRef.current;
+        if (video &&
+            hasPresentedMediaFrameRef.current &&
+            !video.ended &&
+            controlHoldReasonsRef.current.size === 0) {
+            controlsHideTimerRef.current = window.setTimeout(() => {
+                blurFocusedMediaVideoPlayerControl(playerRef.current);
+                setIsControlsVisible(false);
+                controlsHideTimerRef.current = null;
+            }, CONTROLS_HIDE_DELAY_MS);
+        }
+    }, [clearControlsHideTimer, hasPresentedMediaFrameRef, playerRef, videoRef]);
+    const holdControlsForReason = useCallback((reason) => {
+        setMediaVideoPlayerControlHold(controlHoldReasonsRef.current, reason, true);
+        clearControlsHideTimer();
+        setIsControlsVisible(true);
+    }, [clearControlsHideTimer]);
+    const releaseControlsForReason = useCallback((reason) => {
+        const controlsRemainHeld = setMediaVideoPlayerControlHold(controlHoldReasonsRef.current, reason, false);
+        if (!controlsRemainHeld) {
+            showControls();
+        }
+    }, [showControls]);
+    const holdControls = useCallback(() => {
+        holdControlsForReason("bottom");
+    }, [holdControlsForReason]);
+    const releaseControls = useCallback(() => {
+        releaseControlsForReason("bottom");
+    }, [releaseControlsForReason]);
+    const holdExtensionControls = useCallback(() => {
+        holdControlsForReason("extension");
+    }, [holdControlsForReason]);
+    const releaseExtensionControls = useCallback(() => {
+        releaseControlsForReason("extension");
+    }, [releaseControlsForReason]);
+    const holdVolumeControls = useCallback(() => {
+        holdControlsForReason("volume");
+    }, [holdControlsForReason]);
+    const releaseVolumeControls = useCallback(() => {
+        releaseControlsForReason("volume");
+    }, [releaseControlsForReason]);
+    return {
+        clearControlsHideTimer,
+        holdControls,
+        holdExtensionControls,
+        holdVolumeControls,
+        isControlsVisible,
+        releaseControls,
+        releaseExtensionControls,
+        releaseVolumeControls,
+        showControls,
+        showControlsPersistently,
+    };
+}

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

@@ -0,0 +1,24 @@
+type MutableRef<T> = {
+    current: T;
+};
+type FullscreenDocumentTarget = {
+    readonly fullscreenElement: Element | null;
+    readonly addEventListener: (type: "fullscreenchange", listener: () => void) => void;
+    readonly removeEventListener: (type: "fullscreenchange", listener: () => void) => void;
+};
+export declare function connectMediaVideoPlayerFullscreenListener(input: {
+    readonly documentTarget: FullscreenDocumentTarget;
+    readonly onFullscreenChange: (isFullscreen: boolean) => void;
+    readonly playerRef: MutableRef<HTMLDivElement | null>;
+}): {
+    dispose(): void;
+};
+export declare function useMediaVideoPlayerFullscreen(): {
+    isFullscreen: boolean;
+    setIsFullscreen: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+};
+export declare function useMediaVideoPlayerFullscreenLifecycle(input: {
+    readonly playerRef: MutableRef<HTMLDivElement | null>;
+    readonly setIsFullscreen: (isFullscreen: boolean) => void;
+}): void;
+export {};

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

@@ -0,0 +1,38 @@
+"use client";
+import { useEffect, useState } from "react";
+import { isPlayerFullscreen } from "./playback-landscape-presentation.js";
+export function connectMediaVideoPlayerFullscreenListener(input) {
+    function handleFullscreenChange() {
+        input.onFullscreenChange(isPlayerFullscreen({
+            fullscreenElement: input.documentTarget.fullscreenElement,
+            player: input.playerRef.current,
+        }));
+    }
+    handleFullscreenChange();
+    input.documentTarget.addEventListener("fullscreenchange", handleFullscreenChange);
+    return {
+        dispose() {
+            input.documentTarget.removeEventListener("fullscreenchange", handleFullscreenChange);
+        },
+    };
+}
+export function useMediaVideoPlayerFullscreen() {
+    const [isFullscreen, setIsFullscreen] = useState(false);
+    return { isFullscreen, setIsFullscreen };
+}
+export function useMediaVideoPlayerFullscreenLifecycle(input) {
+    useEffect(() => {
+        const lifecycle = connectMediaVideoPlayerFullscreenListener({
+            documentTarget: {
+                addEventListener: (_type, listener) => document.addEventListener("fullscreenchange", listener),
+                get fullscreenElement() {
+                    return document.fullscreenElement;
+                },
+                removeEventListener: (_type, listener) => document.removeEventListener("fullscreenchange", listener),
+            },
+            onFullscreenChange: input.setIsFullscreen,
+            playerRef: input.playerRef,
+        });
+        return () => lifecycle.dispose();
+    }, [input.playerRef, input.setIsFullscreen]);
+}

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

@@ -0,0 +1,25 @@
+import { type MouseEvent, type ChangeEvent, type RefObject } from "react";
+import type { PlaybackController } from "@hexdn/playback";
+export declare function useMediaVideoPlayerInteractions(input: {
+    readonly controllerRef: RefObject<PlaybackController | null>;
+    readonly videoRef: RefObject<HTMLVideoElement | null>;
+    readonly playerRef: RefObject<HTMLDivElement | null>;
+    readonly hasPresentedMediaFrameRef: RefObject<boolean>;
+    readonly isControlsVisible: boolean;
+    readonly onBack?: (() => void) | undefined;
+    readonly showControls: () => void;
+    readonly showPlaybackFeedback: (action: "back-10s" | "fwd-10s" | "pause" | "play") => void;
+    readonly onFullscreenError: () => 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;
+};