[robinebers]

Why

Teams that put the HyperFrames player inside their own product get the HyperFrames play button, volume icons and green HyperFrames logo on the loading screen, and there is no supported way to change them. The player looks like someone else's product sitting inside yours. The only workaround today is reaching into the player's internals, which can break with any release.

What changes

A page can now give the player its own artwork. You put an icon inside the <hyperframes-player> tag and label which part it replaces: the play icon, the pause icon, the three volume icons (loud, quiet, muted) or the loading logo. The player shows it in place of its own.

• Anything you don't replace keeps today's HyperFrames look, so existing players look exactly as they did.
• Your icons take on the control bar's color, so they match the rest of the bar.
• A custom loading logo replaces the HyperFrames logo together with its light sweep and green glow. You can animate your own logo with ordinary CSS.
• The package README and the docs page have a short guide with a copy-paste example.

Before

The page supplies its own icons and logo, and the player ignores them.

After

The same page: the player shows the page's icons in the control bar and its logo on the loading screen.

Test plan

Checked in Chrome 157 against a build of main on the same pages:

• Default look unchanged: when the page supplies nothing, screenshots of six player states (paused, playing, quiet volume, muted, loading assets, shader prep) are byte-for-byte identical to main.
• The page's artwork shows in all six states, and the player still shows it with sandbox-origin="opaque".
• Clicking a custom play icon plays once, clicking again pauses once, the Space key still works, and the play and pause icons still swap.
• A custom play icon sits centered in its button and follows the bar's color (--hfp-color).
• Custom icons come back after controls is turned off and on and after the player is moved in the page, and stay hidden while controls is off.
• A custom loading logo hides the HyperFrames logo, sweep and glow. Without one, the HyperFrames logo keeps them.
• bun run --cwd packages/player test (584 tests, 5 new), typecheck, oxlint, oxfmt, fallow, the comment checks and bun run verify:packed-manifests pass.

How

• Each replaceable glyph now sits in a named <slot> in the player's shadow DOM, with today's SVG as the fallback: play-icon, pause-icon, volume-high-icon, volume-low-icon, volume-muted-icon and loading-mark. No new attributes, CSS variables, parts or styles.
• The volume button holds one of three slots. Each is created once and swapped in only when the state changes, with the same thresholds as before: muted, volume below 0.5, otherwise high.
• The HyperFrames sweep and glow now live inside the loading-mark fallback, so a custom logo never gets them.
• Raises the player's package size budget (packed 157,145 → 159,700, unpacked 541,601 → 547,900). With CI's pnpm 10.17.1, main packs to 158,705 bytes, 11 under the old limit. This change adds about 380 bytes of code and 600 bytes of README (packed 159,691).

Related work

No earlier issue or PR covers player icons or branding. #241 added the speed menu and the control bar's CSS theming, whose color these icons pick up.

[mintlify]

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit 49a260d.

Approve preview