@djangocfg/ui-tools 2.1.404 → 2.1.407

package/README.md

@@ -32,7 +32,7 @@ Sixteen tools, each one lazy-loaded so it doesn't ship until used. Bundle size i
 | `LottiePlayer` | ~200KB | Lottie animation player |
 | `Chat` | ~150KB | Streaming chat (SSE + tool calls + attachments). [README](src/tools/Chat/README.md) |
 | `SpeechRecognition` | ~40KB | Mic capture + STT with pluggable engines (Web Speech / HTTP / WS). [README](src/tools/SpeechRecognition/README.md) |
-| `VideoPlayer` | ~150KB | Vidstack-based pro player |
+| `VideoPlayer` | ~12KB core | media-chrome player — YouTube / Vimeo / HLS / MP4 in one composable shell. [README](src/tools/VideoPlayer/README.md) |
 | `MarkdownMessage` | ~120KB | Read-only chat-tuned markdown. **SSR-safe** — use as a Client Component, the result is server-rendered. [README](src/components/markdown/MarkdownMessage/README.md) |
 | `JsonTree` | ~100KB | JSON visualization (full/compact/inline modes) |
 | `AudioPlayer` | ~80KB | WebView-safe waveform player |
@@ -78,6 +78,7 @@ Subpaths come in three flavors:
 | `@djangocfg/ui-tools/markdown-editor` | `LazyMarkdownEditor`, `mentionPresets`, types | TipTap + ProseMirror (~200 KB) only loads via the lazy wrapper. |
 | `@djangocfg/ui-tools/map` | `LazyMapContainer`, `LazyMapView`, plus light primitives (`MapMarker`, `MapPopup`, `MapCluster`, `MapSource`, `MapLayer`, `MapControls`, `MapProvider`, types) | The heavy MapLibre GL chunk (~800 KB) only loads when `LazyMapContainer` actually mounts. Markers and popups are thin `react-map-gl` wrappers — exported synchronously. |
 | `@djangocfg/ui-tools/markdown-message` | `MarkdownMessage`, `ChatMessageRow`, `ActionRow`, `extractTextFromChildren`, types | **SSR-safe.** The component itself is `'use client'`, but rendering produces plain HTML — Next.js will pre-render it on the server when imported from a Client Component. Use this when you want the markdown renderer without dragging in the full chat. |
+| `@djangocfg/ui-tools/video-player` | `VideoPlayer` (+ `LazyVideoPlayer` alias), `parseEmbedUrl`, composable parts (`PlayButton`, `SeekBar`, `Volume`, `ControlsBar`, …), per-engine canvases, types | media-chrome shell — YouTube / Vimeo / HLS / MP4 / iframe behind one API. Provider engines (`youtube-video-element`, `hls-video-element`, …) are imported only by the matching canvas, so unused engines tree-shake. [README](src/tools/VideoPlayer/README.md) |
 | `@djangocfg/ui-tools/<tool-name>` | One tool | `mermaid`, `speech-recognition`, `json-tree`, `pretty-code`, `openapi-viewer`, `json-form`, `lottie-player`, `video-player`, `image-viewer`, `cron-scheduler`, `gallery`, `tour`, `tree`, `file-icon`, `upload` |
 | `@djangocfg/ui-tools/json-form/full` | `JsonSchemaForm`, `ObjectFieldTemplate`, `evaluateDisabledWhen`, all widgets / templates / utils | Eager bundle. Use only for storybook / internal tooling that needs the template + util APIs at module scope. Production code should import `LazyJsonSchemaForm` from `/json-form` instead. |
 | `@djangocfg/ui-tools/styles` | Tailwind source CSS | |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.404",
+  "version": "2.1.407",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -159,8 +159,8 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.404",
-    "@djangocfg/ui-core": "^2.1.404",
+    "@djangocfg/i18n": "^2.1.407",
+    "@djangocfg/ui-core": "^2.1.407",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -183,9 +183,10 @@
     "@tiptap/react": "^3.20.1",
     "@tiptap/starter-kit": "^3.20.1",
     "@tiptap/suggestion": "^3.20.1",
-    "@vidstack/react": "next",
     "@wavesurfer/react": "^1.0.12",
+    "hls-video-element": "^1.5.11",
     "maplibre-gl": "^4.7.1",
+    "media-chrome": "^4.19.0",
     "media-icons": "next",
     "mermaid": "^11.12.0",
     "monaco-editor": "^0.55.1",
@@ -205,8 +206,9 @@
     "remark-emoji": "^5.0.2",
     "remark-gfm": "4.0.1",
     "remark-smartypants": "^3.0.2",
-    "vidstack": "next",
-    "wavesurfer.js": "^7.12.1"
+    "vimeo-video-element": "^1.7.2",
+    "wavesurfer.js": "^7.12.1",
+    "youtube-video-element": "^1.9.0"
   },
   "optionalDependencies": {
     "@mapbox/mapbox-gl-draw": "^1.4.3",
@@ -214,9 +216,9 @@
     "material-file-icons": "^2.4.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.404",
-    "@djangocfg/typescript-config": "^2.1.404",
-    "@djangocfg/ui-core": "^2.1.404",
+    "@djangocfg/i18n": "^2.1.407",
+    "@djangocfg/typescript-config": "^2.1.407",
+    "@djangocfg/ui-core": "^2.1.407",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",

package/src/tools/AudioPlayer/lazy.tsx

@@ -3,39 +3,25 @@
 /**
  * `@djangocfg/ui-tools/audio-player` subpath entrypoint.
  *
- * `LazyPlayer` is the only heavy export — it dynamically imports the full
- * `Player` tree (PlayerShell + Layout + Cover + Waveform + Controls + audio
- * decoding helpers). Everything else listed here is light:
- *   - types are erased,
- *   - the Zustand store, context hooks, and selectors carry no UI,
- *   - the slot components (`Cover`, `Title`, `PlayButton`, `Waveform`, …)
- *     are presentational React components that read from PlayerContext —
- *     they only become meaningful inside a `<PlayerProvider>` (which only
- *     exists inside `LazyPlayer` once loaded).
+ * `LazyPlayer` is exported as a direct (synchronous) alias of `Player`. We
+ * intentionally avoid `React.lazy` + `import('./Player')` here: under bundlers
+ * that pre-bundle subpath entries (Vite optimizeDeps in Next.js/Vite/SB), the
+ * dynamic import creates a second chunk that re-instantiates the React
+ * Contexts (AudioRefCtx/ControlsCtx/MetaCtx/StateCtx/LevelsCtx). The slot
+ * components and selector hooks re-exported below would then read from a
+ * different context instance than `<PlayerProvider>` writes to, which made
+ * `usePlayerAudio` throw "must be used inside <PlayerProvider>".
  *
- * Consumers building a fully custom layout: render `<LazyPlayer>` once to
- * get the provider, then arrange slot components inside via render-children
- * pattern, or use the bare `Player` re-exported from the root barrel.
+ * Heavy audio-decoding work (peaks, AudioContext) already happens lazily at
+ * runtime via effects inside `PlayerProvider`/`PlayerShell` — there is no
+ * benefit to splitting the React shell behind a second chunk.
  */
 
-import { createLazyComponent } from '../../components';
-import type { PlayerProps } from './types';
-
 // ============================================================================
-// Lazy heavy component
+// Player component (synchronous; previously lazy — see note above)
 // ============================================================================
 
-export const LazyPlayer = createLazyComponent<PlayerProps>(
-  () => import('./Player').then((mod) => ({ default: mod.Player })),
-  {
-    displayName: 'LazyAudioPlayer',
-    fallback: (
-      <div className="rounded-lg border border-border/60 bg-card px-4 py-6 text-sm text-muted-foreground">
-        Loading audio player…
-      </div>
-    ),
-  },
-);
+export { Player, Player as LazyPlayer } from './Player';
 
 // ============================================================================
 // Light surface — types, store, context, slot components, hooks

package/src/tools/ImageViewer/components/ImageViewer.tsx

@@ -196,13 +196,21 @@ export function ImageViewer({
           wrapperClass="!w-full !h-full cursor-grab active:cursor-grabbing"
           contentClass="!w-full !h-full flex items-center justify-center"
         >
-          <div className="relative">
+          {/*
+            Fill the TransformComponent content box so the children's
+            `max-w-full / max-h-full` resolve against the actual viewport
+            instead of the image's natural box. Without `w-full h-full`
+            this wrapper shrink-fits the image, which collapses the
+            max-* constraints and renders the image at intrinsic size —
+            visible as cropping / half-height in tall containers.
+          */}
+          <div className="relative w-full h-full flex items-center justify-center">
             {useProgressiveLoading && lqip && !isFullyLoaded && (
               <img
                 src={lqip}
                 alt=""
                 aria-hidden="true"
-                className="absolute inset-0 max-w-full max-h-full object-contain select-none"
+                className="absolute max-w-full max-h-full object-contain select-none"
                 style={{ transform: transformStyle, filter: 'blur(20px)', transition: 'opacity 0.3s ease-out', opacity: isFullyLoaded ? 0 : 1 }}
                 draggable={false}
               />

package/src/tools/VideoPlayer/README.md

@@ -1,264 +1,121 @@
 # VideoPlayer
 
-Unified video player component supporting multiple modes and source types.
-
-## Modes
-
-| Mode | Source Types | Use Case |
-|------|-------------|----------|
-| `vidstack` | YouTube, Vimeo, HLS, DASH | Full-featured player with themes and controls |
-| `native` | URL, data-url | Lightweight HTML5 player |
-| `streaming` | stream, blob | HTTP Range streaming with auth, binary data |
-
-Mode is auto-detected from source type, or can be forced via `mode` prop.
-
-## Installation
+Composable video player built on [media-chrome](https://media-chrome.org)
+(Mux, MIT, ~12 KB). One `<MediaController>` shell drives **YouTube**,
+**Vimeo**, **HLS**, native **MP4/WebM**, and arbitrary **iframe**
+embeds — the source element swaps, the UI stays the same.
 
 ```tsx
-import {
-  VideoPlayer,
-  VideoPlayerProvider,
-  VideoErrorFallback,
-  resolveFileSource
-} from '@djangocfg/ui-nextjs';
-```
+import { VideoPlayer } from '@djangocfg/ui-tools/video-player';
 
-## Basic Usage
+// Structured source
+<VideoPlayer source={{ type: 'youtube', videoId: 'sGbxmsDFVnE' }} />
 
-### YouTube / Vimeo
-
-```tsx
-<VideoPlayer source={{ type: 'youtube', id: 'dQw4w9WgXcQ' }} />
-<VideoPlayer source={{ type: 'vimeo', id: '123456789' }} />
+// Raw URL — auto-classified (YouTube / Vimeo / HLS / MP4 / iframe)
+<VideoPlayer source="https://youtu.be/sGbxmsDFVnE?t=90" />
 ```
 
-### HLS / DASH Streaming
+## Why media-chrome
 
-```tsx
-<VideoPlayer source={{ type: 'hls', url: 'https://example.com/video.m3u8' }} />
-<VideoPlayer source={{ type: 'dash', url: 'https://example.com/video.mpd' }} />
-```
+Native HTML5 `<video>` can't play YouTube. Hand-rolling the YouTube
+IFrame API and keeping it in sync with a custom control bar is fragile.
+media-chrome solves both: its `<media-controller>` speaks one protocol,
+and provider elements (`<youtube-video>`, `<vimeo-video>`,
+`<hls-video>`) plug into the same slot. Our control parts are thin
+React wrappers themed through CSS custom properties.
 
-### Direct URL
+## Sources
 
-```tsx
-<VideoPlayer source={{ type: 'url', url: 'https://example.com/video.mp4' }} />
-```
+`VideoSource` is a discriminated union — pass an object, or a raw URL
+string that `parseEmbedUrl` classifies for you.
 
-### HTTP Range Streaming (with auth)
+| `type` | Shape | Engine |
+|---|---|---|
+| `url` | `{ type:'url', url, mimeType?, poster?, title? }` | native `<video>` |
+| `youtube` | `{ type:'youtube', videoId, startTime?, playlistId?, poster?, title? }` | `youtube-video-element` |
+| `vimeo` | `{ type:'vimeo', videoId, startTime?, poster?, title? }` | `vimeo-video-element` |
+| `hls` | `{ type:'hls', url, poster?, title? }` | `hls-video-element` (native in Safari, `hls.js` elsewhere) |
+| `iframe` | `{ type:'iframe', url, allow?, poster?, title? }` | plain `<iframe>` — control bar auto-hidden |
 
 ```tsx
-// Full source (standalone)
-<VideoPlayer
-  source={{
-    type: 'stream',
-    sessionId: 'abc123',
-    path: '/videos/movie.mp4',
-    getStreamUrl: (id, path) => `/api/stream/${id}?path=${path}&token=${token}`
-  }}
-/>
+import { parseEmbedUrl } from '@djangocfg/ui-tools/video-player';
 
-// Simplified source (with context)
-<VideoPlayerProvider sessionId={sessionId} getStreamUrl={getStreamUrl}>
-  <VideoPlayer source={{ type: 'stream', path: '/videos/movie.mp4' }} />
-</VideoPlayerProvider>
-```
+parseEmbedUrl('https://www.youtube.com/watch?v=ID&t=42s');
+// → { type: 'youtube', videoId: 'ID', startTime: 42 }
 
-### Blob / ArrayBuffer
+parseEmbedUrl('https://vimeo.com/76979871');
+// → { type: 'vimeo', videoId: '76979871' }
 
-```tsx
-<VideoPlayer
-  source={{
-    type: 'blob',
-    data: arrayBuffer,
-    mimeType: 'video/mp4'
-  }}
-/>
+parseEmbedUrl('https://stream.mux.com/abc.m3u8');
+// → { type: 'hls', url: '…' }
 ```
 
 ## Props
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `source` | `VideoSourceUnion` | required | Video source configuration |
-| `mode` | `'auto' \| 'vidstack' \| 'native' \| 'streaming'` | `'auto'` | Force specific player mode |
-| `aspectRatio` | `number \| 'auto' \| 'fill'` | `16/9` | Aspect ratio or fill parent |
-| `autoPlay` | `boolean` | `false` | Auto-play on load |
-| `muted` | `boolean` | `false` | Muted by default |
-| `loop` | `boolean` | `false` | Loop playback |
-| `controls` | `boolean` | `true` | Show player controls |
-| `playsInline` | `boolean` | `true` | Inline playback on mobile |
-| `preload` | `'none' \| 'metadata' \| 'auto'` | `'metadata'` | Preload strategy |
-| `theme` | `'default' \| 'minimal' \| 'modern'` | `'default'` | Vidstack theme |
-| `errorFallback` | `ReactNode \| (props) => ReactNode` | - | Custom error UI |
-| `className` | `string` | - | Container className |
-| `videoClassName` | `string` | - | Video element className |
-
-## Events
-
-| Event | Type | Description |
-|-------|------|-------------|
-| `onPlay` | `() => void` | Playback started |
-| `onPause` | `() => void` | Playback paused |
-| `onEnded` | `() => void` | Playback ended |
-| `onError` | `(error: string) => void` | Error occurred |
-| `onLoadStart` | `() => void` | Loading started |
-| `onCanPlay` | `() => void` | Ready to play |
-| `onTimeUpdate` | `(time: number, duration: number) => void` | Time updated |
-
-## Ref API
-
-```tsx
-const playerRef = useRef<VideoPlayerRef>(null);
-
-<VideoPlayer ref={playerRef} source={source} />
-
-// Control methods
-playerRef.current?.play();
-playerRef.current?.pause();
-playerRef.current?.seek(30);        // Seek to 30 seconds
-playerRef.current?.setVolume(0.5);  // 0-1
-playerRef.current?.setMuted(true);
-playerRef.current?.reload();
-```
-
-## Error Handling
-
-### Custom Error Fallback
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `source` | `VideoSource \| string` | — | Object or raw URL (auto-parsed). |
+| `controls` | `boolean` | `true` | `false` → no built-in control bar. |
+| `aspectRatio` | `number \| 'auto' \| 'fill'` | `16/9` | `'fill'` stretches to parent height; `'auto'` keeps intrinsic. |
+| `autoPlay` | `boolean` | `false` | Browsers require `muted` for autoplay to start. |
+| `muted` / `loop` / `playsInline` | `boolean` | — | Forwarded to the engine. |
+| `preload` | `'none' \| 'metadata' \| 'auto'` | — | Native sources only. |
+| `crossOrigin` | `'' \| 'anonymous' \| 'use-credentials'` | `'anonymous'` | Native sources only. |
+| `className` | `string` | — | On the `<MediaController>` wrapper. |
+| `children` | `ReactNode` | — | Replaces the default control bar entirely. |
 
-```tsx
-<VideoPlayer
-  source={source}
-  errorFallback={(props) => (
-    <div>
-      <p>Error: {props.error}</p>
-      <button onClick={props.retry}>Retry</button>
-    </div>
-  )}
-/>
-```
-
-### Pre-built Error Fallback with Download
-
-```tsx
-import { VideoErrorFallback } from '@djangocfg/ui-nextjs';
-
-<VideoPlayer
-  source={source}
-  errorFallback={(props) => (
-    <VideoErrorFallback
-      {...props}
-      downloadUrl={getDownloadUrl()}
-      downloadFilename="video.mp4"
-      fileSize="125 MB"
-    />
-  )}
-/>
-```
-
-## Fill Mode
-
-Use `aspectRatio="fill"` to fill the parent container:
-
-```tsx
-<div className="absolute inset-0">
-  <VideoPlayer source={source} aspectRatio="fill" />
-</div>
-```
+## Composable layout
 
-## Context Provider
-
-For apps with multiple streaming videos, use the context to avoid repetition:
-
-```tsx
-// In layout or parent component
-<VideoPlayerProvider
-  sessionId={sessionId}
-  getStreamUrl={(id, path) => `/api/stream/${id}?path=${path}`}
->
-  {/* All nested VideoPlayers use this config */}
-  <VideoPlayer source={{ type: 'stream', path: '/video1.mp4' }} />
-  <VideoPlayer source={{ type: 'stream', path: '/video2.mp4' }} />
-</VideoPlayerProvider>
-```
-
-## File Source Helper
-
-For file browser integration:
+Bring your own control bar by passing `children`. Compose any
+media-chrome element or our restyled parts:
 
 ```tsx
-import { resolveFileSource } from '@djangocfg/ui-nextjs';
-
-const source = resolveFileSource({
-  file: { name: 'movie.mp4', path: '/videos/movie.mp4' },
-  sessionId: 'abc123',
-  getStreamUrl: (id, path) => `/api/stream/${id}?path=${path}`,
-});
-
-if (source) {
-  return <VideoPlayer source={source} />;
-}
+import {
+  VideoPlayer, ControlsBar, PlayButton, SeekBar,
+  Volume, PlaybackRate, Pip, Fullscreen,
+} from '@djangocfg/ui-tools/video-player';
+
+<VideoPlayer source={{ type: 'url', url: '/clip.mp4' }}>
+  <ControlsBar>
+    <PlayButton />
+    <SeekBar />
+    <Volume />
+    <PlaybackRate />
+    <Pip />
+    <Fullscreen />
+  </ControlsBar>
+</VideoPlayer>
 ```
 
-## Source Types Reference
+## Parts
 
-```typescript
-type VideoSourceUnion =
-  | { type: 'url'; url: string; title?: string; poster?: string }
-  | { type: 'youtube'; id: string; title?: string; poster?: string }
-  | { type: 'vimeo'; id: string; title?: string; poster?: string }
-  | { type: 'hls'; url: string; title?: string; poster?: string }
-  | { type: 'dash'; url: string; title?: string; poster?: string }
-  | { type: 'stream'; sessionId: string; path: string; getStreamUrl: fn; mimeType?: string }
-  | { type: 'blob'; data: ArrayBuffer | Blob; mimeType?: string }
-  | { type: 'data-url'; data: string; mimeType?: string }
-```
+`PlayButton` · `SeekBar` · `Volume` · `PlaybackRate` · `Pip` ·
+`Fullscreen` · `ControlsBar` · `Poster` — thin wrappers over
+media-chrome components, restyled through semantic tokens. Each accepts
+the props of the media-chrome element it wraps.
 
-## Architecture
+## Theming
 
-```
-VideoPlayer/
-├── index.ts                    # Public API exports
-├── types/
-│   ├── index.ts                # Type re-exports
-│   ├── sources.ts              # Source types (Url, YouTube, HLS, etc.)
-│   ├── player.ts               # Player props, ref, events
-│   └── provider.ts             # Provider & context types
-├── hooks/
-│   ├── index.ts
-│   └── useVideoPositionCache.ts  # Playback position caching
-├── utils/
-│   ├── index.ts
-│   ├── resolvers.ts            # resolvePlayerMode, isSimpleStreamSource
-│   └── fileSource.ts           # resolveFileSource helper
-├── components/
-│   ├── index.ts
-│   ├── VideoPlayer.tsx         # Main orchestrator
-│   ├── VideoControls.tsx       # Standalone Vidstack controls
-│   └── VideoErrorFallback.tsx  # Pre-built error UI
-├── context/
-│   ├── index.ts
-│   └── VideoPlayerContext.tsx  # Streaming config provider
-└── providers/
-    ├── index.ts
-    ├── VidstackProvider.tsx    # YouTube, Vimeo, HLS, DASH
-    ├── NativeProvider.tsx      # HTML5 <video>
-    └── StreamProvider.tsx      # HTTP Range, Blob
-```
+media-chrome reads CSS custom properties; `styles/video-player.css`
+binds them to ui-core semantic tokens (`--primary`, `--popover`, …) via
+`color-mix`, so the player follows light/dark and any active preset.
+The video surface itself stays dark (`bg-black`) by convention.
 
-## Accessibility
+## Notes
 
-Full accessibility support:
-- Keyboard navigation (Space, Arrow keys, F for fullscreen)
-- Screen reader announcements
-- Focus indicators
-- ARIA labels and roles
+- **YouTube/Vimeo branding** — embed providers enforce a minimal logo;
+  `modestbranding` / `rel=0` reduce it but it cannot be fully removed.
+- **PiP over YouTube** — depends on the embed; the button hides itself
+  when the engine reports no support.
+- **HLS** — native in Safari; elsewhere `hls-video-element` lazy-loads
+  `hls.js` (~110 KB) on first HLS mount only.
+- **`LazyVideoPlayer`** — kept as a synchronous alias of `VideoPlayer`
+  for back-compat. No lazy boundary is needed; engines tree-shake per
+  source type.
 
-## Browser Support
+## Storybook
 
-- Chrome 63+
-- Firefox 67+
-- Safari 12+
-- Edge 79+
-- iOS Safari 12+
-- Chrome Android 63+
+`UI Tools / Video Player / Player` — `NativeMp4`, `YouTubeStarWars`,
+`YouTubeStarTrek`, `YouTubeAutoParseUrl`, `YouTubeWithTimestamp`,
+`Vimeo`, `Sintel`, `HlsStream`, `ComposableLayout`, `Fill`,
+`NoControls`, `LazyAlias`.

package/src/tools/VideoPlayer/VideoPlayer.tsx

@@ -0,0 +1,82 @@
+'use client';
+
+/**
+ * VideoPlayer — composable shell over `media-chrome` web components.
+ *
+ * The shell is just a `<MediaController>` wrapper + a `<CanvasDispatcher>`
+ * that mounts the right media element (`<video>`, `<youtube-video>`,
+ * `<vimeo-video>`, `<hls-video>`, `<iframe>`) into the `media` slot.
+ *
+ * Custom layouts: pass `children` to replace the default control bar.
+ * `controls={false}` opts out of any control surface (useful for
+ * iframe sources where the embed renders its own UI).
+ */
+
+import { useMemo, type CSSProperties } from 'react';
+import { MediaController } from 'media-chrome/react';
+import { cn } from '@djangocfg/ui-core/lib';
+import './styles/video-player.css';
+
+import type { VideoPlayerProps, AspectRatioValue } from './types';
+import { parseEmbedUrl } from './utils/parse-embed-url';
+import { CanvasDispatcher } from './canvas/canvas-dispatcher';
+import {
+  ControlsBar,
+  PlayButton,
+  SeekBar,
+  Volume,
+  PlaybackRate,
+  Pip,
+  Fullscreen,
+} from './parts';
+
+function aspectRatioStyle(ar: AspectRatioValue): CSSProperties | undefined {
+  if (ar === 'fill') return { height: '100%' };
+  if (ar === 'auto') return undefined;
+  return { aspectRatio: String(ar) };
+}
+
+export function VideoPlayer({
+  source,
+  controls = true,
+  aspectRatio = 16 / 9,
+  className,
+  children,
+  ...settings
+}: VideoPlayerProps) {
+  const normalized = useMemo(
+    () => (typeof source === 'string' ? parseEmbedUrl(source) : source),
+    [source],
+  );
+
+  const isIframe = normalized.type === 'iframe';
+  // For iframe embeds media-chrome cannot drive the inner player — hide the
+  // control bar to avoid a non-functional UI.
+  const showControls = controls && !isIframe;
+
+  return (
+    <MediaController
+      // Fade controls + scrim after 2.5s of inactivity while playing;
+      // they reappear on mousemove / pause / focus (media-chrome built-in).
+      autohide="2.5"
+      className={cn(
+        'video-player relative block w-full overflow-hidden rounded-lg bg-black',
+        className,
+      )}
+      style={aspectRatioStyle(aspectRatio)}
+    >
+      <CanvasDispatcher source={normalized} {...settings} />
+      {children ??
+        (showControls && (
+          <ControlsBar>
+            <PlayButton />
+            <SeekBar />
+            <Volume iconOnly />
+            <PlaybackRate />
+            <Pip />
+            <Fullscreen />
+          </ControlsBar>
+        ))}
+    </MediaController>
+  );
+}

package/src/tools/VideoPlayer/canvas/canvas-dispatcher.tsx

@@ -0,0 +1,34 @@
+'use client';
+
+/**
+ * Dispatches `source.type` to the right canvas. Single-switch indirection
+ * keeps `<VideoPlayer>` simple and isolates engine-specific imports inside
+ * the canvas files so tree-shakers can drop unused providers.
+ */
+
+import type { VideoSource, VideoPlayerSettings } from '../types';
+import { NativeCanvas } from './native-canvas';
+import { YouTubeCanvas } from './youtube-canvas';
+import { VimeoCanvas } from './vimeo-canvas';
+import { HlsCanvas } from './hls-canvas';
+import { IframeCanvas } from './iframe-canvas';
+
+export interface CanvasDispatcherProps extends VideoPlayerSettings {
+  readonly source: VideoSource;
+}
+
+export function CanvasDispatcher({ source, ...settings }: CanvasDispatcherProps) {
+  switch (source.type) {
+    case 'youtube':
+      return <YouTubeCanvas source={source} {...settings} />;
+    case 'vimeo':
+      return <VimeoCanvas source={source} {...settings} />;
+    case 'hls':
+      return <HlsCanvas source={source} {...settings} />;
+    case 'iframe':
+      return <IframeCanvas source={source} />;
+    case 'url':
+    default:
+      return <NativeCanvas source={source} {...settings} />;
+  }
+}