Co-authored-by: Emily Dixon <edixon@mux.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: Emily Dixon <puterbaugh0@gmail.com>
4.4 KiB
status
| status |
|---|
| draft |
React Native Player Public API
STUB — opened to get buy-in on the RN player's public API surface. The owned design (architecture, native construction, decisions) lives in
.agents/plans/react-native/; this RFC exists for the cross-package, user-facing contract that needs alignment.
Problem Statement
The planned @videojs/react-native package needs a public API. The design doc
commits to a parity principle:
the RN player should match @videojs/react as closely as the platform allows —
same component names, prop names, hook signatures, layer split, and feature set.
That principle is a public-API and product-direction commitment across packages, so it needs buy-in rather than being decided unilaterally:
- It constrains the RN API to track the React API (and arguably the reverse — RN needs may push capabilities like external-store ownership back onto web).
- It introduces platform-only surface (a separate
<BackgroundablePlayer.Provider>and a persistentbackgroundSession) that has no web equivalent. - It defines where divergence is allowed (styling, accessibility mapping).
What happens if we do nothing: the RN package gets built with an ad-hoc API that drifts from the React player, and cross-platform users re-learn the player per platform.
Customer Salience
(To be filled in.) Initial read:
- Who: player integrators building on both web and native; teams standardizing on Video.js across platforms.
- How many: a meaningful minority today (RN is unbuilt), growing as RN ships.
- How strongly: parity strongly reduces cross-platform learning cost; API drift would be a persistent friction for anyone targeting both.
Options Considered
(To be filled in. Sketch:)
Option 1: Strict parity — RN mirrors React API 1:1 except where the platform makes it impossible. Lowest cross-platform learning cost; constrains RN to React shapes that may not always fit native idiom.
Option 2: RN-idiomatic API — design RN's API to native conventions, parity as a non-goal. Best native feel; highest divergence and learning cost.
Option 3: Parity-by-default with documented exceptions (design-doc lean) — match React wherever the platform allows; each divergence (styling, a11y mapping, platform-only capabilities) is justified and documented.
Recommendation
(To be filled in.) Design-doc lean is Option 3. RFC exists to confirm that's the right cross-package tradeoff and to align on the divergence list.
Open items to resolve here
- The exact divergence list (styling, accessibility mapping, platform-only capabilities).
- Whether external/hoisted-store ownership (needed for the RN persistent session) is also exposed on the web for true parity.
- Public shape of platform-only surface: the separate
<BackgroundablePlayer.Provider>(vs. abackgroundPlaybackboolean on the shared provider), thebackgroundSessionimperative API, and the persistent-session model. Whether two providers (over a shared core) is the right web-parity tradeoff vs. distinguishing by astoreprop on a single provider. - Playlists / source queue — cross-platform feature or RN-only? v10 is
single-source and the web deliberately left queues out of scope, but native
players make a gapless queue trivial (see
design § Future work: playlists).
Adding it to RN gets ahead of web on feature set (not platform-forced
divergence), so the question is whether
MediaQueueCapability+ aplaylistFeaturebecome the shared cross-platform concept (web adopting aloadSource-backed fallback later) or stay RN-only. Decide the shared state shape here to avoid drift.
Final Decision
(Completed after review)
Decision: Rationale: Date:
See Also
.agents/plans/react-native/index.md— owned design (architecture + API surface)..agents/plans/react-native/decisions.md— debated native-construction decisions..agents/plans/react-native/persistent-session.md— implementation plan for the persistent session.rfc/player-api/— the web player API RFC this aims for parity with.