feat(player): add customizable branding to the preview player (#7718)

A page that embeds <hyperframes-player> can now give it its own play,
pause and volume icons and its own loading logo, by putting elements with
a slot attribute inside the player. Anything the page leaves out keeps
today's HyperFrames look.

Co-authored-by: robinebers <16515780+robinebers@users.noreply.github.com>
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
Robin Ebers
2026-11-18 04:10:18 +00:00
committed by GitHub
co-authored by robinebers capy-ai[bot]
parent ebddc42486
commit a9b4745f1f
7 changed files with 287 additions and 18 deletions
+35
View File
@@ -141,6 +141,41 @@ player.addEventListener("timeupdate", (event) => {
| `error` | `{ message }` | Load or runtime error; a video adds its `MediaError` `code` |
| `playbackerror` | `{ source, error }` | The browser blocked playback, for example unmuted autoplay |
## Custom icons and loading mark
Put an element with a `slot` attribute inside the player to replace a control glyph or the loading mark. Anything you leave out keeps the default.
| Slot | Shown when | Default size |
| ------------------- | ----------------------------------------------------------- | ------------ |
| `play-icon` | Paused | 24 px |
| `pause-icon` | Playing | 24 px |
| `volume-high-icon` | Unmuted, volume 0.5 or higher | 20 px |
| `volume-low-icon` | Unmuted, volume below 0.5 | 20 px |
| `volume-muted-icon` | Muted | 20 px |
| `loading-mark` | Preparing shader transitions, loading assets, and buffering | 78 px |
```html title="index.html"
<hyperframes-player src="/compositions/intro.html" controls>
<svg slot="play-icon" width="24" height="24" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
<path d="M8 5v14l11-7z" />
</svg>
<svg slot="pause-icon" width="24" height="24" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
<path d="M6 5h4v14H6zM14 5h4v14h-4z" />
</svg>
<img slot="loading-mark" src="/brand-mark.svg" width="78" height="78" alt="" />
</hyperframes-player>
```
Glyphs take the control bar's color through `currentColor`, and you set their size. Put `slot` on the `<svg>` or `<img>` itself, as a direct child of the player; a wrapper element needs `display: contents` to keep the glyph centered. A custom mark replaces the HyperFrames light sweep and glow, so add your own CSS animation if you want motion.
Until the element is defined, its children show as plain content. Hide them:
```css title="styles.css"
hyperframes-player:not(:defined) > [slot] {
display: none;
}
```
## Advanced: iframe access
The composition runs inside an `<iframe>` in the player's Shadow DOM. For most
+49
View File
@@ -280,6 +280,55 @@ player.addEventListener("ended", () => {
});
```
## Custom icons and loading mark
Put an element with a `slot` attribute inside the player to replace a control glyph or the loading mark. Anything you leave out keeps the default.
| Slot | Shown when | Default size |
| ------------------- | ----------------------------------------------------------- | ------------ |
| `play-icon` | Paused | 24 px |
| `pause-icon` | Playing | 24 px |
| `volume-high-icon` | Unmuted, volume 0.5 or higher | 20 px |
| `volume-low-icon` | Unmuted, volume below 0.5 | 20 px |
| `volume-muted-icon` | Muted | 20 px |
| `loading-mark` | Preparing shader transitions, loading assets, and buffering | 78 px |
```html
<hyperframes-player src="./my-composition/index.html" controls>
<svg
slot="play-icon"
width="24"
height="24"
viewBox="0 0 24 24"
fill="currentColor"
aria-hidden="true"
>
<path d="M8 5v14l11-7z" />
</svg>
<svg
slot="pause-icon"
width="24"
height="24"
viewBox="0 0 24 24"
fill="currentColor"
aria-hidden="true"
>
<path d="M6 5h4v14H6zM14 5h4v14h-4z" />
</svg>
<img slot="loading-mark" src="./brand-mark.svg" width="78" height="78" alt="" />
</hyperframes-player>
```
Glyphs take the control bar's color through `currentColor`, and you set their size. Put `slot` on the `<svg>` or `<img>` itself, as a direct child of the player; a wrapper element needs `display: contents` to keep the glyph centered. A custom mark replaces the HyperFrames light sweep and glow, so add your own CSS animation if you want motion.
Until the element is defined, its children show as plain content. Hide them:
```css
hyperframes-player:not(:defined) > [slot] {
display: none;
}
```
## Sizing
The player fills its container and scales the composition to fit while preserving aspect ratio. Set a size on the element or its parent:
+120 -1
View File
@@ -1,6 +1,14 @@
import { describe, it, expect, vi, afterEach } from "vitest";
import { type ControlsCallbacks, createControls } from "./controls";
import { FULLSCREEN_ENTER_ICON, FULLSCREEN_EXIT_ICON } from "./styles";
import {
FULLSCREEN_ENTER_ICON,
FULLSCREEN_EXIT_ICON,
PAUSE_ICON,
PLAY_ICON,
VOLUME_HIGH_ICON,
VOLUME_LOW_ICON,
VOLUME_MUTED_ICON,
} from "./styles";
function noopCallbacks(): ControlsCallbacks {
return {
@@ -167,6 +175,117 @@ describe("createControls idle hide", () => {
});
});
describe("createControls page glyph slots", () => {
function setup(...glyphSlots: string[]) {
const host = document.createElement("div");
const glyphs = glyphSlots.map((name) => {
const glyph = document.createElement("span");
glyph.slot = name;
host.appendChild(glyph);
return glyph;
});
document.body.appendChild(host);
const shadow = host.attachShadow({ mode: "open" });
const api = createControls(shadow, noopCallbacks());
const cleanup = () => {
api.destroy();
host.remove();
};
return { shadow, api, glyphs, cleanup };
}
function slotAt(root: ParentNode, selector: string): HTMLSlotElement {
const slot = root.querySelector(selector);
if (!(slot instanceof HTMLSlotElement)) throw new Error(`no slot at ${selector}`);
return slot;
}
function onlyAssigned(slot: HTMLSlotElement): Element | undefined {
const assigned = slot.assignedElements();
return assigned.length === 1 ? assigned[0] : undefined;
}
function markup(html: string): string {
const parsed = document.createElement("div");
parsed.innerHTML = html;
return parsed.innerHTML;
}
it("shows today's glyphs in every named control slot when the page supplies none", () => {
const { shadow, api, cleanup } = setup();
const seen = new Map<string, HTMLSlotElement>();
const record = (selector: string) => {
const slot = slotAt(shadow, selector);
seen.set(slot.name, slot);
};
record(".hfp-ico-play slot");
record(".hfp-ico-pause slot");
record(".hfp-mute-btn slot");
api.updateVolume(0.2);
record(".hfp-mute-btn slot");
api.updateMuted(true);
record(".hfp-mute-btn slot");
const expected: Record<string, string> = {
"play-icon": PLAY_ICON,
"pause-icon": PAUSE_ICON,
"volume-high-icon": VOLUME_HIGH_ICON,
"volume-low-icon": VOLUME_LOW_ICON,
"volume-muted-icon": VOLUME_MUTED_ICON,
};
expect([...seen.keys()].sort()).toEqual(Object.keys(expected).sort());
for (const [name, icon] of Object.entries(expected)) {
const slot = seen.get(name);
expect(slot?.assignedElements()).toEqual([]);
expect(slot?.innerHTML).toBe(markup(icon));
}
cleanup();
});
it("puts the page's play and pause glyphs in the play button and still marks it playing", () => {
const {
shadow,
api,
glyphs: [play, pause],
cleanup,
} = setup("play-icon", "pause-icon");
const playSlot = slotAt(shadow, ".hfp-ico-play slot");
expect(onlyAssigned(playSlot)).toBe(play);
expect(onlyAssigned(slotAt(shadow, ".hfp-ico-pause slot"))).toBe(pause);
api.updatePlaying(true);
expect(playSlot.closest(".hfp-play-btn")?.classList.contains("hfp-playing")).toBe(true);
cleanup();
});
it("keeps the default volume glyphs the page left out and shows its own muted glyph", () => {
const {
shadow,
api,
glyphs: [muted],
cleanup,
} = setup("volume-muted-icon");
const muteSlot = () => slotAt(shadow, ".hfp-mute-btn slot");
expect(muteSlot().name).toBe("volume-high-icon");
expect(muteSlot().assignedElements()).toEqual([]);
api.updateVolume(0.2);
expect(muteSlot().name).toBe("volume-low-icon");
expect(muteSlot().assignedElements()).toEqual([]);
api.updateVolume(0);
expect(muteSlot().name).toBe("volume-low-icon");
expect(muteSlot().assignedElements()).toEqual([]);
api.updateMuted(true);
expect(muteSlot().name).toBe("volume-muted-icon");
expect(onlyAssigned(muteSlot())).toBe(muted);
cleanup();
});
});
describe("createControls fullscreen", () => {
const mounted: { host: HTMLElement; api: ReturnType<typeof createControls> }[] = [];
+22 -13
View File
@@ -52,6 +52,13 @@ export function formatTime(seconds: number): string {
return `${m}:${sec.toString().padStart(2, "0")}`;
}
function iconSlot(name: string, fallbackSvg: string): HTMLSlotElement {
const slot = document.createElement("slot");
slot.name = name;
slot.innerHTML = fallbackSvg;
return slot;
}
function createFullscreenButton(
host: HTMLElement,
): { button: HTMLButtonElement; destroy: () => void } | null {
@@ -107,7 +114,7 @@ export function createControls(
// Both glyphs stay in the DOM, stacked; toggling `hfp-playing` crossfade-morphs
// between them (see styles.ts) instead of swapping innerHTML, which would kill
// the transition.
playBtn.innerHTML = `<span class="hfp-ico hfp-ico-play">${PLAY_ICON}</span><span class="hfp-ico hfp-ico-pause">${PAUSE_ICON}</span>`;
playBtn.innerHTML = `<span class="hfp-ico hfp-ico-play"><slot name="play-icon">${PLAY_ICON}</slot></span><span class="hfp-ico hfp-ico-pause"><slot name="pause-icon">${PAUSE_ICON}</slot></span>`;
playBtn.setAttribute("aria-label", "Play");
const scrubber = document.createElement("div");
@@ -153,8 +160,17 @@ export function createControls(
const muteBtn = document.createElement("button");
muteBtn.className = "hfp-mute-btn";
muteBtn.type = "button";
muteBtn.innerHTML = VOLUME_HIGH_ICON;
muteBtn.setAttribute("aria-label", "Mute");
const volumeIcons = {
high: iconSlot("volume-high-icon", VOLUME_HIGH_ICON),
low: iconSlot("volume-low-icon", VOLUME_LOW_ICON),
muted: iconSlot("volume-muted-icon", VOLUME_MUTED_ICON),
};
const showVolumeIcon = (muted: boolean, volume: number) => {
const icon = muted ? volumeIcons.muted : volume < 0.5 ? volumeIcons.low : volumeIcons.high;
if (muteBtn.firstChild !== icon) muteBtn.replaceChildren(icon);
};
showVolumeIcon(false, 1);
const volumeSliderWrap = document.createElement("div");
volumeSliderWrap.className = "hfp-volume-slider-wrap";
@@ -195,13 +211,6 @@ export function createControls(
let speedIndex = presets.indexOf(1); // start at 1x
if (speedIndex === -1) speedIndex = 0;
const getVolumeIcon = (muted: boolean, volume: number): string => {
if (muted) return VOLUME_MUTED_ICON;
if (volume === 0) return VOLUME_LOW_ICON;
if (volume < 0.5) return VOLUME_LOW_ICON;
return VOLUME_HIGH_ICON;
};
playBtn.addEventListener("click", (e) => {
e.stopPropagation();
if (isPlaying) callbacks.onPause();
@@ -222,7 +231,7 @@ export function createControls(
volumeFill.style.width = `${fraction * 100}%`;
volumeSlider.setAttribute("aria-valuenow", String(Math.round(fraction * 100)));
if (isMuted && fraction > 0) callbacks.onMuteToggle();
muteBtn.innerHTML = getVolumeIcon(isMuted, fraction);
showVolumeIcon(isMuted, fraction);
callbacks.onVolumeChange(fraction);
};
@@ -277,7 +286,7 @@ export function createControls(
volumeFill.style.width = `${newVol * 100}%`;
volumeSlider.setAttribute("aria-valuenow", String(Math.round(newVol * 100)));
if (isMuted && newVol > 0) callbacks.onMuteToggle();
muteBtn.innerHTML = getVolumeIcon(isMuted, newVol);
showVolumeIcon(isMuted, newVol);
callbacks.onVolumeChange(newVol);
});
@@ -415,14 +424,14 @@ export function createControls(
},
updateMuted(muted: boolean) {
isMuted = muted;
muteBtn.innerHTML = getVolumeIcon(muted, currentVolume);
showVolumeIcon(muted, currentVolume);
muteBtn.setAttribute("aria-label", muted ? "Unmute" : "Mute");
},
updateVolume(volume: number) {
currentVolume = volume;
volumeFill.style.width = `${volume * 100}%`;
volumeSlider.setAttribute("aria-valuenow", String(Math.round(volume * 100)));
muteBtn.innerHTML = getVolumeIcon(isMuted, volume);
showVolumeIcon(isMuted, volume);
},
setVolumeControlsHidden(hidden: boolean) {
volumeWrap.style.display = hidden ? "none" : "";
@@ -696,6 +696,60 @@ describe("HyperframesPlayer adoptedStyleSheets", () => {
});
});
describe("HyperframesPlayer page glyph slots", () => {
function slotAt(root: ParentNode | null, selector: string): HTMLSlotElement {
const slot = root?.querySelector(selector);
if (!(slot instanceof HTMLSlotElement)) throw new Error(`no slot at ${selector}`);
return slot;
}
function onlyAssigned(slot: HTMLSlotElement): Element | undefined {
const assigned = slot.assignedElements();
return assigned.length === 1 ? assigned[0] : undefined;
}
beforeEach(async () => {
await import("./hyperframes-player.js");
});
afterEach(() => {
document.body.innerHTML = "";
});
it("keeps the page's play glyph in the controls after they are rebuilt or the player moves", () => {
const player = document.createElement("hyperframes-player");
player.setAttribute("controls", "");
const glyph = document.createElement("span");
glyph.slot = "play-icon";
player.appendChild(glyph);
document.body.appendChild(player);
const expectGlyphShown = () => {
expect(glyph.parentElement).toBe(player);
expect(onlyAssigned(slotAt(player.shadowRoot, ".hfp-ico-play slot"))).toBe(glyph);
};
expectGlyphShown();
player.removeAttribute("controls");
player.setAttribute("controls", "");
expectGlyphShown();
player.remove();
document.body.appendChild(player);
expectGlyphShown();
});
it("shows the page's loading mark in the loader card", () => {
const player = document.createElement("hyperframes-player");
const mark = document.createElement("img");
mark.slot = "loading-mark";
player.appendChild(mark);
document.body.appendChild(player);
expect(onlyAssigned(slotAt(player.shadowRoot, ".hfp-shader-loader-mark slot"))).toBe(mark);
});
});
// ── Media MutationObserver scoping ──
//
// The observer that catches late-attached `<audio data-start>` from
+5 -2
View File
@@ -62,7 +62,9 @@ export function createShaderLoader(): ShaderLoaderElements {
const markFrame = document.createElement("div");
markFrame.className = "hfp-shader-loader-mark";
markFrame.draggable = false;
markFrame.innerHTML = [
const markSlot = document.createElement("slot");
markSlot.name = "loading-mark";
markSlot.innerHTML = [
'<svg width="78" height="78" viewBox="0 0 100 100" fill="none" aria-hidden="true" draggable="false">',
`<path d="${MARK_LEFT}" fill="url(#hfp-shader-loader-grad-left)"/>`,
`<path d="${MARK_RIGHT}" fill="url(#hfp-shader-loader-grad-right)"/>`,
@@ -83,7 +85,8 @@ export function createShaderLoader(): ShaderLoaderElements {
sheen.className = "hfp-shader-loader-sheen";
sheen.style.setProperty("mask-image", MARK_SHAPE_MASK);
sheen.style.setProperty("-webkit-mask-image", MARK_SHAPE_MASK);
markFrame.appendChild(sheen);
markSlot.appendChild(sheen);
markFrame.appendChild(markSlot);
const titleContainer = document.createElement("div");
titleContainer.className = "hfp-shader-loader-title";
+2 -2
View File
@@ -32,8 +32,8 @@
"unpacked": 915000
},
"@hyperframes/player": {
"packed": 160300,
"unpacked": 549900
"packed": 162000,
"unpacked": 554000
},
"@hyperframes/producer": {
"packed": 936000,