OpenSpec Change: enterprise-react-video

Change ID: enterprise-react-video
Package: @suaveplan/react-video
Category: react
Target path: react/media/react-video
Status: PROPOSED
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/react-video.md

Summary

Deliver @suaveplan/react-video on genesis from scratch at enterprise quality. Thin React wrapper around the HTML <video> element: VideoPlayer (multi-source, custom controls, keyboard shortcuts), VideoControls (play/pause, scrubber, volume, speed), VideoPlaylist, and useVideoPlayer hook. Genesis adds accessibility improvements (keyboard shortcuts, aria-* on controls), subtitles/captions support, fullscreen API, OTel instrumentation, Storybook stories, and Playwright E2E.

Current-state audit (genesis)

Package does not exist on genesis — fresh build.

Available workspace deps on genesis

Package	Role
`@suaveplan/error` (`workspace:^`)	`VideoError`
`@suaveplan/react-translate` (`workspace:^`)	i18n for control labels
`zod` (`catalog:forms`)	Source/playlist schemas
`@opentelemetry/api` (`catalog:observability`)	`video.play` / `video.error` spans

External: tslib catalog:build. React 18 peer.

Preserved public API surface

VideoPlayer, VideoControls, VideoPlaylist
useVideoPlayer (+ UseVideoPlayerReturn)
formatTime

// Types
VideoSource, PlaylistItem, PlaylistProps, VideoControlsProps, VideoPlayerProps

New additions for genesis

VideoError — codes: VIDEO_LOAD_FAILED, VIDEO_PLAYBACK_ERROR.
Subtitles/captions — VideoPlayer accepts tracks?: VideoTrack[] (WebVTT via <track> element).
Fullscreen API — useVideoPlayer exposes enterFullscreen() / exitFullscreen() / isFullscreen.
Keyboard shortcuts — Space (play/pause), Left/Right (seek ±5s), Up/Down (volume ±10%), F (fullscreen).
OTel spans — video.play, video.pause, video.error.
Stories — VideoPlayer default, with-playlist, with-subtitles, fullscreen, playground.
Playwright E2E — play/pause, seek, playlist navigation.

File layout

react/media/react-video/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    components/
      video-player/ video-controls/ video-playlist/
    hooks/
      use-video-player/
    utils/
      format-time/
    types/
      react-video.types.ts
  e2e/
    video.spec.ts

2.5 KiB Raw Permalink Blame History