feat(packages): add poster placeholder blur-up pattern

[ronald-urbina]

Add the poster placeholder blur-up pattern. Displays a low-resolution image behind the poster with a blur effect while the full poster loads matching the API established by Media Chrome (placeholdersrc) and Mux Player (placeholder).

both default and minimal skins render the placeholder via ::before with filter: blur(). The React variant fades in via an opacity transition keyed on data-visible; the HTML variant applies blur directly on media-poster::before.

Accepts a URL or data URI (inline blurhash output).

resolve 1438

---

Note

Low Risk
Additive UI/CSS API with optional props; poster visibility timing changes are localized to placeholder usage and load-state attributes.

Overview
Adds poster placeholder blur-up support so a low-res image can show behind the poster while the full asset loads (aligned with Media Chrome placeholdersrc and Mux Player placeholder).

React: New optional placeholder on video skin props; skins set --media-poster-placeholder on the container. Poster tracks load state via data-loaded and keeps the full poster hidden until loaded so the blurred ::before layer shows first, then crossfades in.

HTML: placeholdersrc on SkinElement, PosterElement, and skin tags maps to the same CSS variable via attributeChangedCallback.

Skins: Default and minimal CSS and Tailwind paths add blurred ::before layers and :has() rules for the React load sequence; poster opacity rules now account for data-loaded.

Sandbox: getPlaceholderSrc (Mux thumbnail at width=20), usePlaceholder, and mux-video HTML/React demos wire placeholders through.

Design notes live in internal/design/ui/poster-placeholder.md.

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

[netlify]

👷 Deploy request for vjs10-site pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	709b83c

[vercel]

@ronald-urbina 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	Actions	Updated (UTC)
v10-sandbox	Ready	Preview, Comment	Jun 11, 2026 4:51pm

[sampotts]

I checked out the preview and used network simulation as Slow 4G but it looks like it's just waiting and pulling down the full size image?

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 1075f3d. Configure here.}

[sampotts]

Nice one, Cheers!