react-helios 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanish Manandhar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,261 @@
+# @sanishmdhr/react-video-player
+
+Production-grade React video player with HLS streaming, adaptive quality selection, live stream support, subtitle tracks, thumbnail preview, Picture-in-Picture, and full keyboard control.
+
+## Installation
+
+```bash
+npm install @sanishmdhr/react-video-player
+```
+
+**Peer dependencies** — install if not already in your project:
+
+```bash
+npm install react react-dom
+```
+
+## Quick Start
+
+```tsx
+import { VideoPlayer } from "@sanishmdhr/react-video-player";
+import "@sanishmdhr/react-video-player/styles";
+
+export default function App() {
+  return (
+    <VideoPlayer
+      src="https://example.com/video.mp4"
+      controls
+      autoplay={false}
+    />
+  );
+}
+```
+
+> **Next.js** — import the styles in your root `layout.tsx` and mark the component as `"use client"` or wrap it in a client component.
+
+## HLS Streaming
+
+Pass any `.m3u8` URL — HLS.js is initialised automatically:
+
+```tsx
+<VideoPlayer
+  src="https://example.com/stream.m3u8"
+  controls
+  enableHLS        // default: true
+/>
+```
+
+On Safari the browser's native HLS engine is used. A **LIVE** badge and **GO LIVE** button appear automatically for live streams.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | — | Video URL (MP4, WebM, HLS `.m3u8`, …) |
+| `poster` | `string` | — | Poster image shown before playback |
+| `controls` | `boolean` | `true` | Show the built-in control bar |
+| `autoplay` | `boolean` | `false` | Start playback on mount |
+| `muted` | `boolean` | `false` | Start muted |
+| `loop` | `boolean` | `false` | Loop the video |
+| `preload` | `"none" \| "metadata" \| "auto"` | `"metadata"` | Native `preload` attribute |
+| `playbackRates` | `PlaybackRate[]` | `[0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]` | Available speed options |
+| `enableHLS` | `boolean` | `true` | Enable HLS.js for `.m3u8` sources |
+| `enablePreview` | `boolean` | `true` | Show thumbnail preview on progress bar hover (disabled automatically for HLS) |
+| `hlsConfig` | `Partial<HlsConfig>` | — | Override any [hls.js configuration](https://github.com/video-dev/hls.js/blob/master/docs/API.md#fine-tuning) option |
+| `subtitles` | `SubtitleTrack[]` | — | Subtitle / caption tracks |
+| `crossOrigin` | `"anonymous" \| "use-credentials"` | — | CORS attribute for the video element |
+| `className` | `string` | — | CSS class on the player container |
+| `onPlay` | `() => void` | — | Fired when playback starts |
+| `onPause` | `() => void` | — | Fired when playback pauses |
+| `onEnded` | `() => void` | — | Fired when playback ends |
+| `onError` | `(error: VideoError) => void` | — | Fired on playback or stream errors |
+| `onTimeUpdate` | `(time: number) => void` | — | Fired every ~250 ms during playback |
+| `onDurationChange` | `(duration: number) => void` | — | Fired when video duration becomes known |
+| `onBuffering` | `(isBuffering: boolean) => void` | — | Fired when buffering starts / stops |
+
+## Imperative API (Ref)
+
+Use a `ref` to control the player programmatically:
+
+```tsx
+import { useRef } from "react";
+import { VideoPlayer, VideoPlayerRef } from "@sanishmdhr/react-video-player";
+
+export default function App() {
+  const playerRef = useRef<VideoPlayerRef>(null);
+
+  return (
+    <>
+      <VideoPlayer ref={playerRef} src="..." controls />
+      <button onClick={() => playerRef.current?.play()}>Play</button>
+      <button onClick={() => playerRef.current?.pause()}>Pause</button>
+      <button onClick={() => playerRef.current?.seek(30)}>Jump to 30s</button>
+      <button onClick={() => playerRef.current?.setVolume(0.5)}>50% volume</button>
+      <button onClick={() => playerRef.current?.setPlaybackRate(1.5)}>1.5× speed</button>
+    </>
+  );
+}
+```
+
+### `VideoPlayerRef` methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `play` | `() => Promise<void>` | Start playback |
+| `pause` | `() => void` | Pause playback |
+| `seek` | `(time: number) => void` | Seek to a time in seconds |
+| `setVolume` | `(volume: number) => void` | Set volume `0–1` |
+| `toggleMute` | `() => void` | Toggle mute, restoring the pre-mute volume |
+| `setPlaybackRate` | `(rate: PlaybackRate) => void` | Set playback speed |
+| `setQualityLevel` | `(level: number) => void` | Set HLS quality level; `-1` = auto ABR |
+| `seekToLive` | `() => void` | Jump to the live edge (HLS live streams) |
+| `toggleFullscreen` | `() => Promise<void>` | Toggle fullscreen |
+| `togglePictureInPicture` | `() => Promise<void>` | Toggle Picture-in-Picture |
+| `getState` | `() => PlayerState` | Snapshot of current player state |
+| `getVideoElement` | `() => HTMLVideoElement \| null` | Access the underlying `<video>` element |
+
+## Subtitles
+
+```tsx
+<VideoPlayer
+  src="https://example.com/video.mp4"
+  subtitles={[
+    { id: "en", src: "/subs/en.vtt", label: "English", srclang: "en", default: true },
+    { id: "es", src: "/subs/es.vtt", label: "Español", srclang: "es" },
+  ]}
+/>
+```
+
+## Keyboard Shortcuts
+
+Shortcuts activate when the player has focus (click the player or tab to it).
+
+| Key | Action |
+|-----|--------|
+| `Space` / `K` | Play / Pause |
+| `←` / `→` | Seek −5 s / +5 s |
+| `↑` / `↓` | Volume +10% / −10% |
+| `M` | Toggle mute (restores previous volume) |
+| `F` | Toggle fullscreen |
+| `P` | Toggle Picture-in-Picture |
+| `L` | Seek to live edge (live streams only) |
+| `0`–`9` | Jump to 0%–90% of duration |
+
+Progress bar keyboard (when the progress bar has focus):
+
+| Key | Action |
+|-----|--------|
+| `←` / `→` | Seek −5 s / +5 s |
+| `Shift + ←` / `Shift + →` | Seek −10 s / +10 s |
+| `Home` | Jump to start |
+| `End` | Jump to end |
+
+## TypeScript
+
+All types are exported from the package:
+
+```ts
+import type {
+  VideoPlayerProps,
+  VideoPlayerRef,
+  PlayerState,
+  PlaybackRate,
+  HLSQualityLevel,
+  SubtitleTrack,
+  BufferedRange,
+  VideoError,
+  VideoErrorCode,
+} from "@sanishmdhr/react-video-player";
+```
+
+### `PlayerState`
+
+```ts
+interface PlayerState {
+  isPlaying: boolean;
+  currentTime: number;
+  duration: number;
+  volume: number;
+  isMuted: boolean;
+  playbackRate: number;
+  bufferedRanges: BufferedRange[];
+  isBuffering: boolean;
+  error: VideoError | null;
+  isFullscreen: boolean;
+  isPictureInPicture: boolean;
+  isLive: boolean;
+  qualityLevels: HLSQualityLevel[];
+  currentQualityLevel: number; // -1 = ABR auto
+}
+```
+
+### `VideoError`
+
+```ts
+type VideoErrorCode =
+  | "MEDIA_ERR_ABORTED"
+  | "MEDIA_ERR_NETWORK"
+  | "MEDIA_ERR_DECODE"
+  | "MEDIA_ERR_SRC_NOT_SUPPORTED"
+  | "HLS_NETWORK_ERROR"
+  | "HLS_FATAL_ERROR"
+  | "UNKNOWN";
+
+interface VideoError {
+  code: VideoErrorCode;
+  message: string;
+}
+```
+
+## Project Structure
+
+```
+react-video-player/
+├── src/                    # Library source
+│   ├── components/         # VideoPlayer, Controls, control elements
+│   ├── hooks/              # useVideoPlayer (state + HLS init)
+│   ├── lib/                # Types, HLS utilities, format helpers
+│   └── styles/             # CSS
+├── examples/
+│   └── nextjs-demo/        # Standalone Next.js demo app
+├── dist/                   # Build output (ESM + CJS + DTS)
+├── package.json
+├── tsconfig.json
+└── tsup.config.ts
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the library
+npm run build
+
+# Watch mode (rebuild on changes)
+npm run dev
+
+# Type-check only
+npm run typecheck
+```
+
+To run the demo app against your local build:
+
+```bash
+cd examples/nextjs-demo
+npm install
+npm run dev
+```
+
+## Publishing
+
+`prepublishOnly` runs the build automatically:
+
+```bash
+npm publish
+```
+
+## License
+
+MIT

package/dist/index.css

@@ -0,0 +1,2 @@
+.controlButton{background:none;border:none;color:#fff;cursor:pointer;padding:10px;min-width:40px;min-height:40px;display:flex;align-items:center;justify-content:center;border-radius:4px;transition:opacity .15s,background-color .15s,transform .1s;flex-shrink:0}.controlButton:hover{background-color:#ffffff1f;opacity:1}.controlButton:active{transform:scale(.92)}.controlButton svg{width:20px;height:20px;pointer-events:none}@media(max-width:480px){.controlButton{padding:8px;min-width:36px;min-height:36px}}.volumeContainer{position:relative;display:flex;align-items:center}.volumeSlider{width:80px;cursor:pointer;-webkit-appearance:none;appearance:none;background:#ffffff4d;border-radius:2px;height:4px;outline:none;transition:width .15s;flex-shrink:0}.volumeSlider::-webkit-slider-thumb{-webkit-appearance:none;appearance:none;width:12px;height:12px;background:#fff;border-radius:50%;cursor:pointer;box-shadow:0 1px 4px #0006}.volumeSlider::-moz-range-thumb{width:12px;height:12px;background:#fff;border-radius:50%;cursor:pointer;border:none;box-shadow:0 1px 4px #0006}.timeDisplay{color:#fff;font-size:13px;font-weight:500;user-select:none;white-space:nowrap;padding:0 4px;letter-spacing:.01em}.settingsContainer{position:relative}.settingsDropdown{position:absolute;bottom:calc(100% + 8px);right:0;background-color:#0f0f0ff2;border-radius:6px;padding:6px;min-width:150px;z-index:30;box-shadow:0 4px 24px #0009;backdrop-filter:blur(8px)}.settingsTabs{display:flex;border-bottom:1px solid rgba(255,255,255,.12);margin-bottom:4px}.settingsTab{flex:1;background:none;border:none;color:#fff9;cursor:pointer;font-size:12px;font-weight:600;padding:6px 0;letter-spacing:.04em;border-bottom:2px solid transparent;transition:color .15s,border-color .15s;text-transform:uppercase}.settingsTab.active{color:#fff;border-bottom-color:#3b82f6}.settingsTab:hover:not(.active){color:#ffffffe6}.settingsPanelLabel{color:#ffffff80;font-size:10px;font-weight:700;letter-spacing:.08em;text-transform:uppercase;padding:4px 8px 2px}.settingsOption{display:flex;align-items:center;justify-content:space-between;width:100%;padding:7px 10px;background:none;border:none;color:#ffffffd9;cursor:pointer;text-align:left;border-radius:4px;font-size:13px;transition:background-color .15s}.settingsOption:hover{background-color:#ffffff1a;color:#fff}.settingsOption.active{color:#60a5fa;font-weight:600}.settingsOptionBadge{font-size:10px;color:#fff6;margin-left:8px;flex-shrink:0}.progressContainer{position:relative;width:100%;padding:10px 0;cursor:pointer;box-sizing:content-box}.progressContainer:focus{outline:none}.progressContainer:focus-visible{outline:2px solid #60a5fa;outline-offset:2px;border-radius:2px}.previewVideo{display:none}.previewTooltip{position:absolute;bottom:calc(100% + 6px);transform:translate(-50%);pointer-events:none;z-index:20;background-color:#000;border-radius:4px;overflow:hidden;box-shadow:0 4px 16px #00000080}.previewCanvas{display:block;width:160px;height:90px}.previewTime{padding:3px 8px;font-size:11px;font-weight:600;color:#fff;text-align:center;background-color:#000000b3}.progressBackground{position:relative;width:100%;height:4px;background-color:#ffffff40;border-radius:2px;overflow:hidden;transition:height .15s;will-change:height}.progressContainer:hover .progressBackground{height:6px}.bufferedSegment{position:absolute;top:0;height:100%;background-color:#ffffff73;border-radius:2px}.progressFilled{position:absolute;top:0;left:0;height:100%;background-color:#3b82f6;border-radius:2px;will-change:width}.hoverIndicator{position:absolute;top:50%;transform:translate(-50%,-50%);width:2px;height:100%;background-color:#fffc;pointer-events:none}.scrubHandle{position:absolute;top:50%;transform:translate(-50%,-50%);width:14px;height:14px;background-color:#fff;border-radius:50%;box-shadow:0 1px 6px #00000080;pointer-events:none;transition:transform .12s,opacity .12s;opacity:0;z-index:2;will-change:transform,opacity}.progressContainer:hover .scrubHandle,.scrubHandle.dragging{opacity:1}.scrubHandle.dragging{transform:translate(-50%,-50%) scale(1.25);transition:none}
+/*# sourceMappingURL=index.css.map */

package/dist/index.css.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/styles/ControlElements.css","../src/styles/ProgressBar.css"],"sourcesContent":["/* ─── Control button base ────────────────────────────────────────────────── */\n.controlButton {\n  background: none;\n  border: none;\n  color: #fff;\n  cursor: pointer;\n  padding: 10px;\n  min-width: 40px;\n  min-height: 40px;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  border-radius: 4px;\n  transition: opacity 0.15s, background-color 0.15s, transform 0.1s;\n  flex-shrink: 0;\n}\n\n.controlButton:hover {\n  background-color: rgba(255, 255, 255, 0.12);\n  opacity: 1;\n}\n\n.controlButton:active {\n  transform: scale(0.92);\n}\n\n.controlButton svg {\n  width: 20px;\n  height: 20px;\n  pointer-events: none;\n}\n\n@media (max-width: 480px) {\n  .controlButton {\n    padding: 8px;\n    min-width: 36px;\n    min-height: 36px;\n  }\n}\n\n/* ─── Volume control ─────────────────────────────────────────────────────── */\n.volumeContainer {\n  position: relative;\n  display: flex;\n  align-items: center;\n}\n\n.volumeSlider {\n  width: 80px;\n  cursor: pointer;\n  -webkit-appearance: none;\n  appearance: none;\n  background: rgba(255, 255, 255, 0.3);\n  border-radius: 2px;\n  height: 4px;\n  outline: none;\n  transition: width 0.15s;\n  flex-shrink: 0;\n}\n\n.volumeSlider::-webkit-slider-thumb {\n  -webkit-appearance: none;\n  appearance: none;\n  width: 12px;\n  height: 12px;\n  background: #fff;\n  border-radius: 50%;\n  cursor: pointer;\n  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.4);\n}\n\n.volumeSlider::-moz-range-thumb {\n  width: 12px;\n  height: 12px;\n  background: #fff;\n  border-radius: 50%;\n  cursor: pointer;\n  border: none;\n  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.4);\n}\n\n/* ─── Time display ───────────────────────────────────────────────────────── */\n.timeDisplay {\n  color: #fff;\n  font-size: 13px;\n  font-weight: 500;\n  user-select: none;\n  white-space: nowrap;\n  padding: 0 4px;\n  letter-spacing: 0.01em;\n}\n\n/* ─── Settings menu ──────────────────────────────────────────────────────── */\n.settingsContainer {\n  position: relative;\n}\n\n.settingsDropdown {\n  position: absolute;\n  bottom: calc(100% + 8px);\n  right: 0;\n  background-color: rgba(15, 15, 15, 0.95);\n  border-radius: 6px;\n  padding: 6px;\n  min-width: 150px;\n  z-index: 30;\n  box-shadow: 0 4px 24px rgba(0, 0, 0, 0.6);\n  backdrop-filter: blur(8px);\n}\n\n/* Tabs (Speed / Quality) */\n.settingsTabs {\n  display: flex;\n  border-bottom: 1px solid rgba(255, 255, 255, 0.12);\n  margin-bottom: 4px;\n}\n\n.settingsTab {\n  flex: 1;\n  background: none;\n  border: none;\n  color: rgba(255, 255, 255, 0.6);\n  cursor: pointer;\n  font-size: 12px;\n  font-weight: 600;\n  padding: 6px 0;\n  letter-spacing: 0.04em;\n  border-bottom: 2px solid transparent;\n  transition: color 0.15s, border-color 0.15s;\n  text-transform: uppercase;\n}\n\n.settingsTab.active {\n  color: #fff;\n  border-bottom-color: #3b82f6;\n}\n\n.settingsTab:hover:not(.active) {\n  color: rgba(255, 255, 255, 0.9);\n}\n\n/* Panel section label */\n.settingsPanelLabel {\n  color: rgba(255, 255, 255, 0.5);\n  font-size: 10px;\n  font-weight: 700;\n  letter-spacing: 0.08em;\n  text-transform: uppercase;\n  padding: 4px 8px 2px;\n}\n\n/* Option rows */\n.settingsOption {\n  display: flex;\n  align-items: center;\n  justify-content: space-between;\n  width: 100%;\n  padding: 7px 10px;\n  background: none;\n  border: none;\n  color: rgba(255, 255, 255, 0.85);\n  cursor: pointer;\n  text-align: left;\n  border-radius: 4px;\n  font-size: 13px;\n  transition: background-color 0.15s;\n}\n\n.settingsOption:hover {\n  background-color: rgba(255, 255, 255, 0.1);\n  color: #fff;\n}\n\n.settingsOption.active {\n  color: #60a5fa;\n  font-weight: 600;\n}\n\n.settingsOptionBadge {\n  font-size: 10px;\n  color: rgba(255, 255, 255, 0.4);\n  margin-left: 8px;\n  flex-shrink: 0;\n}\n","/* ─── Progress bar container ─────────────────────────────────────────────── */\n.progressContainer {\n  position: relative;\n  width: 100%;\n  /* Tall hit area so scrub feels easy to grab on touch and mouse */\n  padding: 10px 0;\n  cursor: pointer;\n  /* Expand the clickable zone without affecting layout neighbours */\n  box-sizing: content-box;\n}\n\n.progressContainer:focus {\n  outline: none;\n}\n\n.progressContainer:focus-visible {\n  outline: 2px solid #60a5fa;\n  outline-offset: 2px;\n  border-radius: 2px;\n}\n\n/* ─── Hidden preview video ───────────────────────────────────────────────── */\n.previewVideo {\n  display: none;\n}\n\n/* ─── Thumbnail tooltip ──────────────────────────────────────────────────── */\n.previewTooltip {\n  position: absolute;\n  /* Sits above the container; bottom 100% + a small gap */\n  bottom: calc(100% + 6px);\n  transform: translateX(-50%);\n  pointer-events: none;\n  z-index: 20;\n  background-color: #000;\n  border-radius: 4px;\n  overflow: hidden;\n  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.5);\n}\n\n.previewCanvas {\n  display: block;\n  width: 160px;\n  height: 90px;\n}\n\n.previewTime {\n  padding: 3px 8px;\n  font-size: 11px;\n  font-weight: 600;\n  color: #fff;\n  text-align: center;\n  background-color: rgba(0, 0, 0, 0.7);\n}\n\n/* ─── Track background ───────────────────────────────────────────────────── */\n.progressBackground {\n  position: relative;\n  width: 100%;\n  height: 4px;\n  background-color: rgba(255, 255, 255, 0.25);\n  border-radius: 2px;\n  /* Keep overflow:hidden for buffered / filled bars ONLY.\n     The scrub handle must live OUTSIDE this element. */\n  overflow: hidden;\n  transition: height 0.15s;\n  will-change: height;\n}\n\n/* Grow the track on hover for a \"YouTube-style\" feel */\n.progressContainer:hover .progressBackground {\n  height: 6px;\n}\n\n/* ─── Buffered range indicator ───────────────────────────────────────────── */\n.bufferedSegment {\n  position: absolute;\n  top: 0;\n  height: 100%;\n  background-color: rgba(255, 255, 255, 0.45);\n  border-radius: 2px;\n}\n\n/* ─── Played progress fill ───────────────────────────────────────────────── */\n.progressFilled {\n  position: absolute;\n  top: 0;\n  left: 0;\n  height: 100%;\n  background-color: #3b82f6;\n  border-radius: 2px;\n  will-change: width;\n}\n\n/* ─── Hover position indicator (thin white line) ────────────────────────── */\n.hoverIndicator {\n  position: absolute;\n  top: 50%;\n  transform: translate(-50%, -50%);\n  width: 2px;\n  height: 100%;\n  background-color: rgba(255, 255, 255, 0.8);\n  pointer-events: none;\n}\n\n/* ─── Scrub handle ───────────────────────────────────────────────────────── */\n/*\n * The handle is a SIBLING of .progressBackground (outside overflow:hidden).\n * It is positioned absolutely within .progressContainer, which provides\n * the full padded height. `top: 50%` centers it on the container mid-line,\n * which aligns with the track regardless of the container's padding.\n *\n * Fix: previously the handle was inside overflow:hidden and only a tiny\n * sliver was visible on the 4px-tall track.\n */\n.scrubHandle {\n  position: absolute;\n  top: 50%;\n  transform: translate(-50%, -50%);\n  width: 14px;\n  height: 14px;\n  background-color: #fff;\n  border-radius: 50%;\n  box-shadow: 0 1px 6px rgba(0, 0, 0, 0.5);\n  pointer-events: none;\n  transition: transform 0.12s, opacity 0.12s;\n  /* Hidden by default; shown on container hover */\n  opacity: 0;\n  z-index: 2;\n  will-change: transform, opacity;\n}\n\n.progressContainer:hover .scrubHandle,\n.scrubHandle.dragging {\n  opacity: 1;\n}\n\n.scrubHandle.dragging {\n  transform: translate(-50%, -50%) scale(1.25);\n  transition: none;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.mts

@@ -0,0 +1,244 @@
+import * as react from 'react';
+import react__default from 'react';
+import { HlsConfig } from 'hls.js';
+
+interface BufferedRange {
+    start: number;
+    end: number;
+}
+type VideoErrorCode = "MEDIA_ERR_ABORTED" | "MEDIA_ERR_NETWORK" | "MEDIA_ERR_DECODE" | "MEDIA_ERR_SRC_NOT_SUPPORTED" | "HLS_NETWORK_ERROR" | "HLS_FATAL_ERROR" | "UNKNOWN";
+interface VideoError {
+    code: VideoErrorCode;
+    message: string;
+}
+interface HLSQualityLevel {
+    id: number;
+    height: number;
+    width: number;
+    bitrate: number;
+    /** Display name e.g. "1080p", "720p", "Auto" */
+    name: string;
+}
+interface SubtitleTrack {
+    id: string;
+    src: string;
+    label: string;
+    srclang: string;
+    default?: boolean;
+}
+interface PlayerState {
+    isPlaying: boolean;
+    currentTime: number;
+    duration: number;
+    volume: number;
+    isMuted: boolean;
+    playbackRate: number;
+    bufferedRanges: BufferedRange[];
+    isBuffering: boolean;
+    error: VideoError | null;
+    isFullscreen: boolean;
+    isPictureInPicture: boolean;
+    /** True when the stream is a live HLS stream (Infinity duration) */
+    isLive: boolean;
+    /** Available HLS quality levels; empty for non-HLS sources */
+    qualityLevels: HLSQualityLevel[];
+    /** Currently active quality level id; -1 = ABR auto */
+    currentQualityLevel: number;
+}
+type PlaybackRate = 0.25 | 0.5 | 0.75 | 1 | 1.25 | 1.5 | 1.75 | 2;
+interface VideoPlayerRef {
+    play: () => Promise<void>;
+    pause: () => void;
+    seek: (time: number) => void;
+    setVolume: (volume: number) => void;
+    /** Toggle mute while remembering the pre-mute volume */
+    toggleMute: () => void;
+    setPlaybackRate: (rate: PlaybackRate) => void;
+    /** Set HLS quality level; pass -1 for automatic ABR */
+    setQualityLevel: (level: number) => void;
+    /** Jump to the live edge of an HLS live stream */
+    seekToLive: () => void;
+    toggleFullscreen: () => Promise<void>;
+    togglePictureInPicture: () => Promise<void>;
+    getState: () => PlayerState;
+    getVideoElement: () => HTMLVideoElement | null;
+}
+interface VideoPlayerProps {
+    src: string;
+    poster?: string;
+    autoplay?: boolean;
+    muted?: boolean;
+    loop?: boolean;
+    controls?: boolean;
+    preload?: "none" | "metadata" | "auto";
+    playbackRates?: PlaybackRate[];
+    className?: string;
+    enableHLS?: boolean;
+    enablePreview?: boolean;
+    /** Additional hls.js configuration options */
+    hlsConfig?: Partial<HlsConfig>;
+    /** Subtitle / caption tracks */
+    subtitles?: SubtitleTrack[];
+    /** crossorigin attribute for CORS-enabled preview thumbnails */
+    crossOrigin?: "anonymous" | "use-credentials";
+    onPlay?: () => void;
+    onPause?: () => void;
+    onEnded?: () => void;
+    onError?: (error: VideoError) => void;
+    onTimeUpdate?: (time: number) => void;
+    onDurationChange?: (duration: number) => void;
+    onBuffering?: (isBuffering: boolean) => void;
+}
+
+declare const VideoPlayer: react__default.ForwardRefExoticComponent<VideoPlayerProps & react__default.RefAttributes<VideoPlayerRef>>;
+
+interface ControlsProps {
+    playerRef: VideoPlayerRef;
+    /** Ref to the outer player container; used to scope keyboard shortcuts to the focused player */
+    playerContainerRef: react__default.RefObject<HTMLElement | null>;
+    playbackRates: PlaybackRate[];
+    enablePreview: boolean;
+    isPlaying: boolean;
+    currentTime: number;
+    duration: number;
+    volume: number;
+    isMuted: boolean;
+    playbackRate: number;
+    isFullscreen: boolean;
+    isPictureInPicture: boolean;
+    isLive: boolean;
+    qualityLevels: HLSQualityLevel[];
+    currentQualityLevel: number;
+    bufferedRanges: BufferedRange[];
+}
+/**
+ * Controls is intentionally NOT wrapped in React.memo here – it receives
+ * currentTime which changes every tick, so memo wouldn't help at this level.
+ * Instead, all its CHILDREN are memoized so they skip renders when their
+ * specific props haven't changed.
+ */
+declare const Controls: react__default.FC<ControlsProps>;
+
+interface TimeDisplayProps {
+    currentTime: number;
+    duration: number;
+    isLive?: boolean;
+}
+/**
+ * TimeDisplay re-renders every timeupdate tick (currentTime changes).
+ * Wrapped in memo anyway so that if its specific props haven't changed
+ * (e.g. when only volume changes) it skips the render.
+ */
+declare const TimeDisplay: react.NamedExoticComponent<TimeDisplayProps>;
+
+interface SettingsMenuProps {
+    currentRate: number;
+    playbackRates: PlaybackRate[];
+    onRateChange: (rate: PlaybackRate) => void;
+    qualityLevels?: HLSQualityLevel[];
+    currentQualityLevel?: number;
+    onQualityChange?: (level: number) => void;
+}
+/**
+ * SettingsMenu wrapped in React.memo.
+ * playbackRate and qualityLevel rarely change → this component skips
+ * almost all re-renders during normal playback.
+ *
+ * sortedLevels is memoized so the .sort() only runs when qualityLevels
+ * actually changes (usually once after manifest is parsed).
+ */
+declare const SettingsMenu: react.NamedExoticComponent<SettingsMenuProps>;
+
+interface ProgressBarProps {
+    playerRef: VideoPlayerRef;
+    currentTime: number;
+    duration: number;
+    bufferedRanges: BufferedRange[];
+    enablePreview?: boolean;
+}
+declare const ProgressBar: react__default.FC<ProgressBarProps>;
+
+interface VolumeControlProps {
+    volume: number;
+    isMuted: boolean;
+    onVolumeChange: (volume: number) => void;
+    onToggleMute: () => void;
+}
+/**
+ * VolumeControl wrapped in React.memo.
+ * volume and isMuted don't change during timeupdate → 0 re-renders during
+ * normal playback when the user isn't touching volume controls.
+ */
+declare const VolumeControl: react.NamedExoticComponent<VolumeControlProps>;
+
+interface PlayButtonProps {
+    onClick: () => void;
+}
+interface PauseButtonProps {
+    onClick: () => void;
+}
+interface FullscreenButtonProps {
+    onClick: () => void;
+    isFullscreen?: boolean;
+}
+interface PiPButtonProps {
+    onClick: () => void;
+    isPiP?: boolean;
+}
+/**
+ * All button components are wrapped in React.memo.
+ * They receive stable callback refs (useCallback in Controls), so they
+ * only re-render when their specific props (isFullscreen, isPiP, etc.)
+ * actually change – not on every timeupdate tick.
+ */
+declare const PlayButton: react.NamedExoticComponent<PlayButtonProps>;
+declare const PauseButton: react.NamedExoticComponent<PauseButtonProps>;
+declare const FullscreenButton: react.NamedExoticComponent<FullscreenButtonProps>;
+declare const PiPButton: react.NamedExoticComponent<PiPButtonProps>;
+
+declare const ControlElements: {
+    PlayButton: react.NamedExoticComponent<PlayButtonProps>;
+    PauseButton: react.NamedExoticComponent<PauseButtonProps>;
+    FullscreenButton: react.NamedExoticComponent<FullscreenButtonProps>;
+    PiPButton: react.NamedExoticComponent<PiPButtonProps>;
+    VolumeControl: react.NamedExoticComponent<VolumeControlProps>;
+    ProgressBar: react.FC<ProgressBarProps>;
+    SettingsMenu: react.NamedExoticComponent<SettingsMenuProps>;
+    TimeDisplay: react.NamedExoticComponent<TimeDisplayProps>;
+};
+
+declare const index_ControlElements: typeof ControlElements;
+declare const index_FullscreenButton: typeof FullscreenButton;
+type index_FullscreenButtonProps = FullscreenButtonProps;
+declare const index_PauseButton: typeof PauseButton;
+type index_PauseButtonProps = PauseButtonProps;
+declare const index_PiPButton: typeof PiPButton;
+type index_PiPButtonProps = PiPButtonProps;
+declare const index_PlayButton: typeof PlayButton;
+type index_PlayButtonProps = PlayButtonProps;
+declare const index_ProgressBar: typeof ProgressBar;
+type index_ProgressBarProps = ProgressBarProps;
+declare const index_SettingsMenu: typeof SettingsMenu;
+type index_SettingsMenuProps = SettingsMenuProps;
+declare const index_TimeDisplay: typeof TimeDisplay;
+type index_TimeDisplayProps = TimeDisplayProps;
+declare const index_VolumeControl: typeof VolumeControl;
+type index_VolumeControlProps = VolumeControlProps;
+declare namespace index {
+  export { index_ControlElements as ControlElements, index_FullscreenButton as FullscreenButton, type index_FullscreenButtonProps as FullscreenButtonProps, index_PauseButton as PauseButton, type index_PauseButtonProps as PauseButtonProps, index_PiPButton as PiPButton, type index_PiPButtonProps as PiPButtonProps, index_PlayButton as PlayButton, type index_PlayButtonProps as PlayButtonProps, index_ProgressBar as ProgressBar, type index_ProgressBarProps as ProgressBarProps, index_SettingsMenu as SettingsMenu, type index_SettingsMenuProps as SettingsMenuProps, index_TimeDisplay as TimeDisplay, type index_TimeDisplayProps as TimeDisplayProps, index_VolumeControl as VolumeControl, type index_VolumeControlProps as VolumeControlProps };
+}
+
+/**
+ * Format seconds → MM:SS or HH:MM:SS
+ */
+declare function formatTime(seconds: number): string;
+/**
+ * Detect an HLS stream URL regardless of query-string parameters.
+ */
+declare function isHLSUrl(url: string): boolean;
+/**
+ * Return the MIME type for a given video URL.
+ */
+declare function getMimeType(url: string): string;
+
+export { type BufferedRange, index as ControlElements, Controls, type HLSQualityLevel, type PlaybackRate, type PlayerState, type SubtitleTrack, type VideoError, type VideoErrorCode, VideoPlayer, type VideoPlayerProps, type VideoPlayerRef, formatTime, getMimeType, isHLSUrl };