feat: cap-rendition-to-player-size

[cjpillsbury]

Exposes hls.js's capRenditionToPlayerSize option with a Mux-optimized default.

Closes #1238 (based off of initial effort from @spuppo-mux in #1251)

Behavior

Value	Behavior
undefined (default)	Caps to player size, 720p minimum floor
true	Standard hls.js capping (may go below 720p)
false	No capping

Test plan

• npm run dev → http://localhost:3000/MuxPlayer
• Toggle "Cap Level To Player Size" between None/true/false
• Verify no console errors
• Verify config: document.querySelector('mux-player').media.nativeEl._hls.config.capLevelToPlayerSize
• Trigger a rendition switch/re-selection via ABR - e.g. open Chrome Dev Tools, resize player size, seek backwards during playback to prompt segment reloading, and confirm that rendition does(n't) get capped under different permutations

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[vercel]

@cjpillsbury is attempting to deploy a commit to the Mux Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
elements-demo-astro	Ready	Preview, Comment	Jan 15, 2026 8:37pm
elements-demo-nextjs	Ready	Preview, Comment	Jan 15, 2026 8:37pm
elements-demo-svelte-kit	Ready	Preview, Comment	Jan 15, 2026 8:37pm
elements-demo-vanilla	Ready	Preview, Comment	Jan 15, 2026 8:37pm
elements-demo-vue	Ready	Preview, Comment	Jan 15, 2026 8:37pm

[heff]

A few problems I see with the API:

We're pulling in the word "level" from HLS.js, but it's a vague term that we don't use anywhere else in the player settings docs. We use "resolution" otherwise.

We're explicitly calling out HLS.js, while otherwise we've only ever mentioned it as "(currently hls.js)". So this hardens the tie to HLS.js to some degree.

There's also not quite enough detail in the docs on the interaction between this, maxAutoResolution, maxResolution (not quite sure how this differs from the auto version), minResolution. Some quick notes in each setting about the interaction could solve this one.

Considering the future of MuxPlayer there's a world where we call this a "quick and advanced" feature and lean harder into that with the messaging: Say "ADVANCED" in the setting description, name it "capHlsLevel..." to be explicit abou the tie in the name.

But I think we should just polish it up.

• Change Level to Resolution
• Get clear on the interaction beteween related settings and make them clear in the docs.

[luwes]

Code looks good to me but yes def agree with Steve about the naming.

[heff]

API updates look good, thanks 👍