[RFC] Mux Source & URL DX

[R-Delfino95]

Refs #1432
Refs #1431
Refs #977

Summary

RFC for how <mux-video> takes a source — and signs and refreshes its token — without the surface changing when the playback engine changes. Motivated by signed-token refresh (#1432), under the Mux Media Elements epic (#977). Status: accepted — direction approved in review.

Problem

<mux-video> has no token surface today (it only reads the playback-id out of src for analytics), so signed playback hard-fails mid-session when the JWT lapses — there's nothing to refresh. Two DX goals (convenience vs. lean-on-src) had to be reconciled under one hard constraint: the surface stays engine-agnostic.

Decision

• Surface — source-based. The component takes a src (plus an optional standalone toMuxVideoURL helper to build it); no playback-id / tokens component attributes. Aligns with the Video.js direction: normalize toward source, fewer Mux-specific props than Mux Player — one surface, not two.
• Refresh — player-owned. The integrator supplies one async "get a fresh token" callback; the player decodes the JWT, watches expiry, and refreshes proactively / on 403, re-resolving the master. On hls.js / native this is a controlled media reload (on par with Mux Player today, improvable later); seamless on SPF — the migration target.

Open for the implementation design doc

Exact refresh API shape (callback vs onTokenExpiring event), where the resolver lives, signed-thumbnail tokens, and whether to ship a minimal playback-token pass-through first.

---

Note

Low Risk
Documentation-only RFC; no runtime or API code changes in this PR.

Overview
Adds rfc/mux-source-dx.md as an accepted RFC that locks direction for <mux-video> signed playback and source configuration (motivated by #1432, epic #977).

The doc records a source-based public API: src only on the element, with an optional off-component toMuxVideoURL helper — explicitly not playback-id / tokens attributes. Player-owned token refresh is agreed: the integrator supplies one async callback; the player reads JWT exp, refreshes proactively and/or on 403, and re-resolves the master URL. It states that mid-session refresh is a controlled media reload on hls.js/native (v1 bar, comparable to Mux Player) and can be seamless on SPF later.

It also captures layering (surface vs resolver vs engine), resolved risk (JWT on master only; §6.3.4 not blocking), next steps (implementation design, possible minimal token pass-through first), and remaining open questions (exact refresh API shape, resolver placement, signed thumbnails).

^{Reviewed by Cursor Bugbot for commit 3a9a5c8. Bugbot is set up for automated code reviews on this repo. Configure here.}

[netlify]

✅ Deploy Preview for vjs10-site ready!

Name	Link
🔨 Latest commit	3a9a5c8
🔍 Latest deploy log	https://app.netlify.com/projects/vjs10-site/deploys/6a3c3a75f6739b0008d8d8b5
😎 Deploy Preview	https://deploy-preview-1665--vjs10-site.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[vercel]

@R-Delfino95 is attempting to deploy a commit to the Mux Team on Vercel.

A member of the Team first needs to authorize it.