mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-16 06:19:21 +00:00
## Summary Two independent initiatives that improve agent DX and expand HyperFrames' reach. ### Initiative 1: Fix the Clip Animation Footgun - `gsap_animates_clip_element` lint rule now uses smart detection — only errors when GSAP animates `visibility` or `display` on a clip element - All other properties (opacity, transform, x, y, scale, etc.) are allowed silently - This was the #1 agent failure in QA (10/10 agents hit it on v0.2.1) ### Initiative 2: `<hyperframes-player>` Web Component - New `@hyperframes/player` package — zero dependencies, 3.3KB gzipped - Iframe-based web component with Shadow DOM for perfect isolation - Video-like API: `play()`, `pause()`, `seek()`, `currentTime`, `duration`, events - Controls overlay with play/pause, scrubber (mouse + touch), time display, auto-hide - Full docs page at `docs/packages/player.mdx` ## Before / After ### Clip animation lint **Before (10/10 agents hit this):** ``` ✗ gsap_animates_clip_element: GSAP animation targets a clip element. Selector "#title" resolves to element <div id="title" class="clip">. The framework manages clip visibility — animate an inner wrapper instead. Fix: Wrap content in a child <div> and target that with GSAP. ``` **After (only errors on actual conflicts):** ``` # This passes lint — no error: tl.from("#title", { opacity: 0, y: -50, scale: 0.8 }, 0); # This still errors — actual conflict with runtime: tl.to("#title", { visibility: "hidden" }, 3); ✗ gsap_animates_clip_element: GSAP animation sets visibility on a clip element. Fix: Remove the visibility/display tween. Use opacity for fade effects. ``` ### Embeddable player **Before:** No way to embed a composition in a web page. **After:** ```html <script src="https://cdn.jsdelivr.net/npm/@hyperframes/player"></script> <hyperframes-player src="./composition/index.html" controls></hyperframes-player> ``` ```js const player = document.querySelector('hyperframes-player'); player.play(); player.pause(); player.seek(2.5); player.addEventListener('ready', (e) => console.log('Duration:', e.detail.duration)); ``` ## Test plan - [x] 427 core tests pass (20 GSAP lint tests with smart detection) - [x] 7 player tests pass (formatTime + element registration) - [x] TypeScript compiles cleanly (core + player) - [x] Lint: GSAP animating clip with safe props → 0 errors - [x] Lint: GSAP animating clip with `visibility` → 1 error (correct) - [x] Player builds to 3.3KB gzipped ESM - [x] Lockfile updated for CI - [x] Docs page added at `docs/packages/player.mdx`
396 lines
12 KiB
TypeScript
396 lines
12 KiB
TypeScript
import { createControls, type ControlsCallbacks } from "./controls.js";
|
|
import { PLAYER_STYLES } from "./styles.js";
|
|
|
|
const DEFAULT_FPS = 30;
|
|
const RUNTIME_CDN_URL =
|
|
"https://cdn.jsdelivr.net/npm/@hyperframes/core/dist/hyperframe.runtime.iife.js";
|
|
|
|
class HyperframesPlayer extends HTMLElement {
|
|
static get observedAttributes() {
|
|
return ["src", "width", "height", "controls", "muted", "poster", "playback-rate"];
|
|
}
|
|
|
|
private shadow: ShadowRoot;
|
|
private container: HTMLDivElement;
|
|
private iframe: HTMLIFrameElement;
|
|
private posterEl: HTMLImageElement | null = null;
|
|
private controlsApi: ReturnType<typeof createControls> | null = null;
|
|
private resizeObserver: ResizeObserver;
|
|
|
|
private _ready = false;
|
|
private _duration = 0;
|
|
private _currentTime = 0;
|
|
private _paused = true;
|
|
private _compositionWidth = 1920;
|
|
private _compositionHeight = 1080;
|
|
private _probeInterval: ReturnType<typeof setInterval> | null = null;
|
|
private _lastUpdateMs = 0;
|
|
|
|
constructor() {
|
|
super();
|
|
this.shadow = this.attachShadow({ mode: "open" });
|
|
|
|
const style = document.createElement("style");
|
|
style.textContent = PLAYER_STYLES;
|
|
this.shadow.appendChild(style);
|
|
|
|
this.container = document.createElement("div");
|
|
this.container.className = "hfp-container";
|
|
|
|
this.iframe = document.createElement("iframe");
|
|
this.iframe.className = "hfp-iframe";
|
|
this.iframe.sandbox.add("allow-scripts", "allow-same-origin");
|
|
this.iframe.allow = "autoplay; fullscreen";
|
|
this.iframe.referrerPolicy = "no-referrer";
|
|
this.iframe.title = "HyperFrames Composition";
|
|
|
|
this.container.appendChild(this.iframe);
|
|
this.shadow.appendChild(this.container);
|
|
|
|
// Clicking the bare player surface toggles play/pause.
|
|
// Ignore shadow-DOM control interactions so overlay clicks don't double-handle.
|
|
this.addEventListener("click", (event) => {
|
|
if (this._isControlsClick(event)) return;
|
|
if (this._paused) this.play();
|
|
else this.pause();
|
|
});
|
|
|
|
this.resizeObserver = new ResizeObserver(() => this._updateScale());
|
|
|
|
this._onMessage = this._onMessage.bind(this);
|
|
this._onIframeLoad = this._onIframeLoad.bind(this);
|
|
}
|
|
|
|
connectedCallback() {
|
|
this.resizeObserver.observe(this);
|
|
window.addEventListener("message", this._onMessage);
|
|
this.iframe.addEventListener("load", this._onIframeLoad);
|
|
|
|
if (this.hasAttribute("controls")) this._setupControls();
|
|
if (this.hasAttribute("poster")) this._setupPoster();
|
|
if (this.hasAttribute("src")) this.iframe.src = this.getAttribute("src")!;
|
|
}
|
|
|
|
disconnectedCallback() {
|
|
this.resizeObserver.disconnect();
|
|
window.removeEventListener("message", this._onMessage);
|
|
this.iframe.removeEventListener("load", this._onIframeLoad);
|
|
if (this._probeInterval) clearInterval(this._probeInterval);
|
|
this.controlsApi?.destroy();
|
|
}
|
|
|
|
attributeChangedCallback(name: string, _old: string | null, val: string | null) {
|
|
switch (name) {
|
|
case "src":
|
|
if (val) {
|
|
this._ready = false;
|
|
this.iframe.src = val;
|
|
}
|
|
break;
|
|
case "width":
|
|
this._compositionWidth = parseInt(val || "1920", 10);
|
|
this._updateScale();
|
|
break;
|
|
case "height":
|
|
this._compositionHeight = parseInt(val || "1080", 10);
|
|
this._updateScale();
|
|
break;
|
|
case "controls":
|
|
if (val !== null) this._setupControls();
|
|
else {
|
|
this.controlsApi?.destroy();
|
|
this.controlsApi = null;
|
|
}
|
|
break;
|
|
case "poster":
|
|
this._setupPoster();
|
|
break;
|
|
case "playback-rate":
|
|
this._sendControl("set-playback-rate", { playbackRate: parseFloat(val || "1") });
|
|
break;
|
|
case "muted":
|
|
this._sendControl("set-muted", { muted: val !== null });
|
|
break;
|
|
}
|
|
}
|
|
|
|
// ── Public API ──
|
|
|
|
play() {
|
|
this._hidePoster();
|
|
this._sendControl("play");
|
|
this._paused = false;
|
|
this.controlsApi?.updatePlaying(true);
|
|
this.dispatchEvent(new Event("play"));
|
|
}
|
|
|
|
pause() {
|
|
this._sendControl("pause");
|
|
this._paused = true;
|
|
this.controlsApi?.updatePlaying(false);
|
|
this.dispatchEvent(new Event("pause"));
|
|
}
|
|
|
|
seek(timeInSeconds: number) {
|
|
const frame = Math.round(timeInSeconds * DEFAULT_FPS);
|
|
this._sendControl("seek", { frame });
|
|
this._currentTime = timeInSeconds;
|
|
this._paused = true;
|
|
this.controlsApi?.updatePlaying(false);
|
|
this.controlsApi?.updateTime(this._currentTime, this._duration);
|
|
}
|
|
|
|
get currentTime() {
|
|
return this._currentTime;
|
|
}
|
|
set currentTime(t: number) {
|
|
this.seek(t);
|
|
}
|
|
|
|
get duration() {
|
|
return this._duration;
|
|
}
|
|
get paused() {
|
|
return this._paused;
|
|
}
|
|
get ready() {
|
|
return this._ready;
|
|
}
|
|
|
|
get playbackRate() {
|
|
return parseFloat(this.getAttribute("playback-rate") || "1");
|
|
}
|
|
set playbackRate(r: number) {
|
|
this.setAttribute("playback-rate", String(r));
|
|
}
|
|
|
|
get muted() {
|
|
return this.hasAttribute("muted");
|
|
}
|
|
set muted(m: boolean) {
|
|
if (m) this.setAttribute("muted", "");
|
|
else this.removeAttribute("muted");
|
|
}
|
|
|
|
get loop() {
|
|
return this.hasAttribute("loop");
|
|
}
|
|
set loop(l: boolean) {
|
|
if (l) this.setAttribute("loop", "");
|
|
else this.removeAttribute("loop");
|
|
}
|
|
|
|
// ── Private ──
|
|
|
|
private _sendControl(action: string, extra: Record<string, unknown> = {}) {
|
|
try {
|
|
this.iframe.contentWindow?.postMessage(
|
|
{ source: "hf-parent", type: "control", action, ...extra },
|
|
"*",
|
|
);
|
|
} catch {
|
|
/* cross-origin */
|
|
}
|
|
}
|
|
|
|
private _isControlsClick(event: Event) {
|
|
return event
|
|
.composedPath()
|
|
.some((target) => target instanceof HTMLElement && target.classList.contains("hfp-controls"));
|
|
}
|
|
|
|
private _onMessage(e: MessageEvent) {
|
|
if (e.source !== this.iframe.contentWindow) return;
|
|
const data = e.data;
|
|
if (!data || data.source !== "hf-preview") return;
|
|
|
|
if (data.type === "state") {
|
|
this._currentTime = (data.frame ?? 0) / DEFAULT_FPS;
|
|
const wasPlaying = !this._paused;
|
|
this._paused = !data.isPlaying;
|
|
|
|
// Throttle UI updates and event dispatch to ~10fps to avoid excessive re-renders
|
|
const now = performance.now();
|
|
if (now - this._lastUpdateMs > 100 || this._paused !== wasPlaying) {
|
|
this._lastUpdateMs = now;
|
|
this.controlsApi?.updateTime(this._currentTime, this._duration);
|
|
this.controlsApi?.updatePlaying(!this._paused);
|
|
this.dispatchEvent(
|
|
new CustomEvent("timeupdate", { detail: { currentTime: this._currentTime } }),
|
|
);
|
|
}
|
|
|
|
if (this._currentTime >= this._duration && !this._paused) {
|
|
if (this.loop) {
|
|
this.seek(0);
|
|
this.play();
|
|
} else {
|
|
this._paused = true;
|
|
this.controlsApi?.updatePlaying(false);
|
|
this.dispatchEvent(new Event("ended"));
|
|
}
|
|
}
|
|
}
|
|
|
|
if (data.type === "timeline" && data.durationInFrames > 0) {
|
|
this._duration = data.durationInFrames / DEFAULT_FPS;
|
|
this.controlsApi?.updateTime(this._currentTime, this._duration);
|
|
}
|
|
|
|
if (data.type === "stage-size" && data.width > 0 && data.height > 0) {
|
|
this._compositionWidth = data.width;
|
|
this._compositionHeight = data.height;
|
|
this._updateScale();
|
|
}
|
|
}
|
|
|
|
private _runtimeInjected = false;
|
|
|
|
private _onIframeLoad() {
|
|
let attempts = 0;
|
|
this._runtimeInjected = false;
|
|
if (this._probeInterval) clearInterval(this._probeInterval);
|
|
|
|
this._probeInterval = setInterval(() => {
|
|
attempts++;
|
|
try {
|
|
const win = this.iframe.contentWindow as Window & {
|
|
__player?: { getDuration: () => number };
|
|
__timelines?: Record<string, { duration: () => number }>;
|
|
__hf?: unknown;
|
|
};
|
|
if (!win) return;
|
|
|
|
// Check if the runtime bridge is active (__hf or __player from the runtime)
|
|
const hasRuntime = !!(win.__hf || win.__player);
|
|
const hasTimelines = !!(win.__timelines && Object.keys(win.__timelines).length > 0);
|
|
|
|
// Auto-inject runtime if GSAP timelines exist but no runtime bridge
|
|
if (!hasRuntime && hasTimelines && !this._runtimeInjected && attempts >= 5) {
|
|
this._injectRuntime();
|
|
return; // Wait for runtime to load and initialize
|
|
}
|
|
|
|
const getAdapter = () => {
|
|
if (win.__player && typeof win.__player.getDuration === "function") return win.__player;
|
|
if (win.__timelines) {
|
|
const keys = Object.keys(win.__timelines);
|
|
if (keys.length > 0) {
|
|
const tl = win.__timelines[keys[keys.length - 1]];
|
|
return { getDuration: () => tl.duration() };
|
|
}
|
|
}
|
|
return null;
|
|
};
|
|
|
|
const adapter = getAdapter();
|
|
if (adapter && adapter.getDuration() > 0) {
|
|
clearInterval(this._probeInterval!);
|
|
this._duration = adapter.getDuration();
|
|
this._ready = true;
|
|
this.controlsApi?.updateTime(0, this._duration);
|
|
this.dispatchEvent(new CustomEvent("ready", { detail: { duration: this._duration } }));
|
|
|
|
// Auto-detect dimensions from composition
|
|
const doc = this.iframe.contentDocument;
|
|
const root = doc?.querySelector("[data-composition-id]");
|
|
if (root) {
|
|
const w = parseInt(root.getAttribute("data-width") || "0", 10);
|
|
const h = parseInt(root.getAttribute("data-height") || "0", 10);
|
|
if (w > 0 && h > 0) {
|
|
this._compositionWidth = w;
|
|
this._compositionHeight = h;
|
|
this._updateScale();
|
|
}
|
|
}
|
|
|
|
if (this.hasAttribute("autoplay")) {
|
|
this.play();
|
|
}
|
|
return;
|
|
}
|
|
} catch {
|
|
/* cross-origin */
|
|
}
|
|
|
|
if (attempts >= 40) {
|
|
clearInterval(this._probeInterval!);
|
|
this.dispatchEvent(
|
|
new CustomEvent("error", {
|
|
detail: { message: "Composition timeline not found after 8s" },
|
|
}),
|
|
);
|
|
}
|
|
}, 200);
|
|
}
|
|
|
|
/** Inject the HyperFrames runtime into the iframe if not already present. */
|
|
private _injectRuntime() {
|
|
this._runtimeInjected = true;
|
|
try {
|
|
const doc = this.iframe.contentDocument;
|
|
if (!doc) return;
|
|
const script = doc.createElement("script");
|
|
script.src = RUNTIME_CDN_URL;
|
|
script.onload = () => {
|
|
// Runtime loaded — the probe interval will pick up __hf on next tick
|
|
};
|
|
script.onerror = () => {
|
|
// CDN failed — the probe will continue and eventually timeout
|
|
};
|
|
(doc.head || doc.documentElement).appendChild(script);
|
|
} catch {
|
|
/* cross-origin — can't inject */
|
|
}
|
|
}
|
|
|
|
private _updateScale() {
|
|
const rect = this.getBoundingClientRect();
|
|
if (rect.width === 0 || rect.height === 0) return;
|
|
const scale = Math.min(
|
|
rect.width / this._compositionWidth,
|
|
rect.height / this._compositionHeight,
|
|
);
|
|
this.iframe.style.width = `${this._compositionWidth}px`;
|
|
this.iframe.style.height = `${this._compositionHeight}px`;
|
|
this.iframe.style.transform = `translate(-50%, -50%) scale(${scale})`;
|
|
}
|
|
|
|
private _setupControls() {
|
|
if (this.controlsApi) return;
|
|
const callbacks: ControlsCallbacks = {
|
|
onPlay: () => this.play(),
|
|
onPause: () => this.pause(),
|
|
onSeek: (fraction) => this.seek(fraction * this._duration),
|
|
};
|
|
this.controlsApi = createControls(this.shadow, callbacks);
|
|
}
|
|
|
|
private _setupPoster() {
|
|
const url = this.getAttribute("poster");
|
|
if (!url) {
|
|
this.posterEl?.remove();
|
|
this.posterEl = null;
|
|
return;
|
|
}
|
|
if (!this.posterEl) {
|
|
this.posterEl = document.createElement("img");
|
|
this.posterEl.className = "hfp-poster";
|
|
this.shadow.appendChild(this.posterEl);
|
|
}
|
|
this.posterEl.src = url;
|
|
}
|
|
|
|
private _hidePoster() {
|
|
this.posterEl?.remove();
|
|
this.posterEl = null;
|
|
}
|
|
}
|
|
|
|
if (!customElements.get("hyperframes-player")) {
|
|
customElements.define("hyperframes-player", HyperframesPlayer);
|
|
}
|
|
|
|
export { HyperframesPlayer };
|
|
export { formatTime } from "./controls.js";
|