(video) feature: unified video player interface with YouTube IFrame API integration

src/frontend/package.json

@@ -103,6 +103,7 @@
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.2",
     "@types/react-syntax-highlighter": "15.5.13",
+    "@types/youtube": "^0.1.2",
     "@vitejs/plugin-react-swc": "4.2.0",
     "canvas-confetti": "1.9.4",
     "eslint": "9.39.1",

src/frontend/src/lib/youtube-api.ts

@@ -0,0 +1,48 @@
+/**
+ * Lazy singleton loader for the YouTube IFrame API.
+ * Script is injected on first use and never unloaded.
+ * Types provided by @types/youtube (YT namespace).
+ */
+
+declare global {
+  interface Window {
+    onYouTubeIframeAPIReady?: () => void;
+  }
+}
+
+let loadPromise: Promise<void> | null = null;
+
+/**
+ * Loads the YouTube IFrame API once. Subsequent calls return the same promise.
+ * Resolves when the API is ready (onYouTubeIframeAPIReady has fired).
+ */
+export function loadYouTubeAPI(): Promise<void> {
+  if (loadPromise) {
+    return loadPromise;
+  }
+
+  if (typeof window === 'undefined') {
+    return Promise.reject(new Error('YouTube API requires window'));
+  }
+
+  if (window.YT?.Player) {
+    loadPromise = Promise.resolve();
+    return loadPromise;
+  }
+
+  loadPromise = new Promise<void>((resolve) => {
+    const previousCallback = window.onYouTubeIframeAPIReady;
+    window.onYouTubeIframeAPIReady = () => {
+      previousCallback?.();
+      resolve();
+    };
+
+    const script = document.createElement('script');
+    script.src = 'https://www.youtube.com/iframe_api';
+    script.async = true;
+    const firstScript = document.getElementsByTagName('script')[0];
+    firstScript?.parentNode?.insertBefore(script, firstScript);
+  });
+
+  return loadPromise;
+}

src/frontend/src/widgets/primitives/index.ts

@@ -18,6 +18,6 @@ export { SpacerWidget } from './SpacerWidget';
 export { LoadingWidget } from './LoadingWidget';
 export { AppHostWidget } from './AppHostWidget';
 export { AudioPlayerWidget } from './AudioPlayerWidget';
-export { VideoPlayerWidget } from './VideoPlayerWidget';
+export { VideoPlayerWidget } from './video';
 export { StepperWidget } from './StepperWidget';
 export { RichTextBlockWidget } from './RichTextBlockWidget';

src/frontend/src/widgets/primitives/video/NativeVideoPlayer.tsx

@@ -0,0 +1,65 @@
+import { useRef, useState } from 'react';
+import { getHeight, getWidth } from '@/lib/styles';
+import { validateImageUrl } from '@/lib/url';
+import { VideoPlayerError } from './VideoPlayerError';
+import type { VideoPlayerProps } from './types';
+
+export const NativeVideoPlayer: React.FC<VideoPlayerProps> = (props: VideoPlayerProps) => {
+  const {
+    id,
+    validatedSrc,
+    poster,
+    width,
+    height,
+    autoplay = false,
+    loop = false,
+    muted = false,
+    preload = 'metadata',
+    controls = true,
+    onError,
+  } = props;
+  const [hasError, setHasError] = useState(false);
+  const videoRef = useRef<HTMLVideoElement>(null);
+  const validatedPoster = poster ? validateImageUrl(poster) : null;
+
+  const handleError = () => {
+    setHasError(true);
+    onError?.();
+  };
+
+  const styles: React.CSSProperties = {
+    ...getWidth(width),
+    ...getHeight(height),
+  };
+
+  if (hasError) {
+    return (
+      <VideoPlayerError
+        id={id}
+        message="Failed to load video file"
+        width={width}
+        height={height}
+      />
+    );
+  }
+
+  return (
+    <video
+      ref={videoRef}
+      id={id}
+      src={validatedSrc}
+      style={styles}
+      autoPlay={autoplay}
+      loop={loop}
+      muted={muted}
+      preload={preload}
+      controls={controls}
+      poster={validatedPoster || undefined}
+      className="w-full rounded"
+      onError={handleError}
+      aria-label="Video player"
+    >
+      Your browser does not support the video element.
+    </video>
+  );
+};

src/frontend/src/widgets/primitives/video/VideoPlayerError.tsx

@@ -0,0 +1,34 @@
+import { getHeight, getWidth } from '@/lib/styles';
+
+export interface VideoPlayerErrorProps {
+  id: string;
+  message: string;
+  width?: string;
+  height?: string;
+}
+
+/**
+ * Shared error state for the video player (invalid URL, load failure, etc.).
+ */
+export const VideoPlayerError: React.FC<VideoPlayerErrorProps> = ({
+  id,
+  message,
+  width,
+  height,
+}) => {
+  const styles: React.CSSProperties = {
+    ...getWidth(width),
+    ...getHeight(height),
+  };
+  return (
+    <div
+      id={id}
+      style={styles}
+      className="flex items-center justify-center bg-destructive/10 text-destructive rounded border-2 border-dashed border-destructive/25 p-4"
+      role="alert"
+      aria-label="Video error"
+    >
+      <span className="text-sm">{message}</span>
+    </div>
+  );
+};