Initial Commit

openspec/changes/enterprise-react-video/proposal.md

@@ -0,0 +1,82 @@
+# 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
+
+```ts
+VideoPlayer, VideoControls, VideoPlaylist
+useVideoPlayer (+ UseVideoPlayerReturn)
+formatTime
+
+// Types
+VideoSource, PlaylistItem, PlaylistProps, VideoControlsProps, VideoPlayerProps
+```
+
+---
+
+## New additions for genesis
+
+1. **`VideoError`** — codes: `VIDEO_LOAD_FAILED`, `VIDEO_PLAYBACK_ERROR`.
+2. **Subtitles/captions** — `VideoPlayer` accepts `tracks?: VideoTrack[]` (WebVTT via `<track>` element).
+3. **Fullscreen API** — `useVideoPlayer` exposes `enterFullscreen()` / `exitFullscreen()` / `isFullscreen`.
+4. **Keyboard shortcuts** — Space (play/pause), Left/Right (seek ±5s), Up/Down (volume ±10%), F (fullscreen).
+5. **OTel spans** — `video.play`, `video.pause`, `video.error`.
+6. **Stories** — `VideoPlayer` default, with-playlist, with-subtitles, fullscreen, playground.
+7. **Playwright E2E** — play/pause, seek, playlist navigation.
+
+---
+
+## File layout
+
+```text
+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
+```