From 317424beaa2ebcdd27bb7f0f675884817cb74347 Mon Sep 17 00:00:00 2001
From: Vance Ingalls <vance@heygen.com>
Date: Tue, 21 Apr 2026 00:44:50 -0700
Subject: [PATCH] perf(player): share PLAYER_STYLES via adoptedStyleSheets
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replaces per-instance `<style>` injection in HyperframesPlayer with a
lazily constructed CSSStyleSheet adopted into every shadow root via
`shadowRoot.adoptedStyleSheets`. The studio thumbnail grid renders
dozens of players concurrently — sharing one parsed stylesheet across
N players (one rule tree, one parse, N adopters) cuts per-instance
style work that the old <style>-per-shadow-root path imposed.

Key behavior:

- `getSharedPlayerStyleSheet()` is module-scoped and memoized; the
  sheet is built once per process and returned to every adopter. SSR-
  safe via a `typeof CSSStyleSheet` guard, with failures cached as
  `null` to avoid retrying constructor failures forever.
- `applyPlayerStyles(shadow)` is the single integration point for the
  player. It appends (never replaces) the shared sheet so any pre-
  adopted sheets — host themes, scoped overrides, future caller-side
  injections — survive intact, and is idempotent so repeated calls
  don't multiply adoptions.
- A defensive fallback path creates a per-instance `<style>` element
  when adoptedStyleSheets is unavailable (older runtimes, hostile
  environments, or replaceSync failure). Behavior on those paths is
  unchanged from the previous implementation.

Tests cover sharing across instances, fallback when CSSStyleSheet is
undefined or `replaceSync` throws, fallback when adoptedStyleSheets is
unsupported on the shadow root, idempotency, and preservation of pre-
existing adopted sheets. Includes an integration test in the player
spec confirming two real `<hyperframes-player>` elements adopt the
same CSSStyleSheet instance and inject no `<style>` element.

No public API change. PLAYER_STYLES, PLAY_ICON, and PAUSE_ICON exports
are preserved. Build size delta is negligible (utility code replaces
container.appendChild calls).
---
 .../player/src/hyperframes-player.test.ts     |  40 +++++
 packages/player/src/hyperframes-player.ts     |  26 ++-
 packages/player/src/styles.test.ts            | 154 ++++++++++++++++++
 packages/player/src/styles.ts                 |  77 +++++++++
 4 files changed, 294 insertions(+), 3 deletions(-)
 create mode 100644 packages/player/src/styles.test.ts

diff --git a/packages/player/src/hyperframes-player.test.ts b/packages/player/src/hyperframes-player.test.ts
index 766b0a7d1..3d86de851 100644
--- a/packages/player/src/hyperframes-player.test.ts
+++ b/packages/player/src/hyperframes-player.test.ts
@@ -322,3 +322,43 @@ describe("HyperframesPlayer parent-frame media", () => {
     expect(mockAudio.muted).toBe(false);
   });
 });
+
+// ── Shared stylesheet (adoptedStyleSheets) ──
+//
+// Every player constructed in the same document should adopt the *same*
+// CSSStyleSheet instance instead of getting its own <style> element. This is
+// the studio thumbnail-grid win — N players, one parsed sheet.
+
+describe("HyperframesPlayer adoptedStyleSheets", () => {
+  type AdoptingShadowRoot = ShadowRoot & { adoptedStyleSheets: CSSStyleSheet[] };
+  type PlayerWithShadow = HTMLElement & { shadowRoot: AdoptingShadowRoot | null };
+
+  beforeEach(async () => {
+    await import("./hyperframes-player.js");
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("shares a single CSSStyleSheet across multiple player instances", () => {
+    const a = document.createElement("hyperframes-player") as PlayerWithShadow;
+    const b = document.createElement("hyperframes-player") as PlayerWithShadow;
+    document.body.appendChild(a);
+    document.body.appendChild(b);
+
+    const sheetsA = a.shadowRoot?.adoptedStyleSheets ?? [];
+    const sheetsB = b.shadowRoot?.adoptedStyleSheets ?? [];
+
+    expect(sheetsA.length).toBeGreaterThan(0);
+    expect(sheetsB.length).toBeGreaterThan(0);
+    expect(sheetsA.at(-1)).toBe(sheetsB.at(-1));
+  });
+
+  it("does not inject a per-instance <style> when adoption succeeds", () => {
+    const player = document.createElement("hyperframes-player") as PlayerWithShadow;
+    document.body.appendChild(player);
+
+    expect(player.shadowRoot?.querySelector("style")).toBeNull();
+  });
+});
diff --git a/packages/player/src/hyperframes-player.ts b/packages/player/src/hyperframes-player.ts
index 2f0314afc..e51e23f89 100644
--- a/packages/player/src/hyperframes-player.ts
+++ b/packages/player/src/hyperframes-player.ts
@@ -2,6 +2,21 @@ import { createControls, SPEED_PRESETS, type ControlsCallbacks } from "./control
 import { shouldInjectRuntime } from "./shouldInjectRuntime.js";
 import { PLAYER_STYLES } from "./styles.js";
 
+let sharedSheet: CSSStyleSheet | null = null;
+
+function getSharedSheet(): CSSStyleSheet | null {
+  if (sharedSheet) return sharedSheet;
+  if (typeof CSSStyleSheet === "undefined") return null;
+  try {
+    const sheet = new CSSStyleSheet();
+    sheet.replaceSync(PLAYER_STYLES);
+    sharedSheet = sheet;
+    return sheet;
+  } catch {
+    return null;
+  }
+}
+
 const DEFAULT_FPS = 30;
 const RUNTIME_CDN_URL =
   "https://cdn.jsdelivr.net/npm/@hyperframes/core/dist/hyperframe.runtime.iife.js";
@@ -85,9 +100,14 @@ class HyperframesPlayer extends HTMLElement {
     super();
     this.shadow = this.attachShadow({ mode: "open" });
 
-    const style = document.createElement("style");
-    style.textContent = PLAYER_STYLES;
-    this.shadow.appendChild(style);
+    const sheet = getSharedSheet();
+    if (sheet) {
+      this.shadow.adoptedStyleSheets = [sheet];
+    } else {
+      const style = document.createElement("style");
+      style.textContent = PLAYER_STYLES;
+      this.shadow.appendChild(style);
+    }
 
     this.container = document.createElement("div");
     this.container.className = "hfp-container";
diff --git a/packages/player/src/styles.test.ts b/packages/player/src/styles.test.ts
new file mode 100644
index 000000000..6cfe05d1f
--- /dev/null
+++ b/packages/player/src/styles.test.ts
@@ -0,0 +1,154 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  _resetSharedPlayerStyleSheet,
+  applyPlayerStyles,
+  getSharedPlayerStyleSheet,
+  PLAYER_STYLES,
+} from "./styles.js";
+
+type AdoptingShadowRoot = ShadowRoot & {
+  adoptedStyleSheets: CSSStyleSheet[];
+};
+
+function createShadowHost(): AdoptingShadowRoot {
+  const host = document.createElement("div");
+  document.body.appendChild(host);
+  return host.attachShadow({ mode: "open" }) as AdoptingShadowRoot;
+}
+
+describe("getSharedPlayerStyleSheet", () => {
+  beforeEach(() => {
+    _resetSharedPlayerStyleSheet();
+  });
+
+  it("returns the same CSSStyleSheet instance across calls", () => {
+    const a = getSharedPlayerStyleSheet();
+    const b = getSharedPlayerStyleSheet();
+
+    expect(a).not.toBeNull();
+    expect(a).toBe(b);
+  });
+
+  it("returns null and memoizes the failure when CSSStyleSheet is unavailable", () => {
+    const original = globalThis.CSSStyleSheet;
+    (globalThis as { CSSStyleSheet?: unknown }).CSSStyleSheet = undefined;
+
+    try {
+      expect(getSharedPlayerStyleSheet()).toBeNull();
+      expect(getSharedPlayerStyleSheet()).toBeNull();
+    } finally {
+      globalThis.CSSStyleSheet = original;
+    }
+  });
+});
+
+describe("applyPlayerStyles", () => {
+  beforeEach(() => {
+    _resetSharedPlayerStyleSheet();
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("adopts the shared sheet on a fresh shadow root and adds no <style> element", () => {
+    const shadow = createShadowHost();
+
+    applyPlayerStyles(shadow);
+
+    const sheet = getSharedPlayerStyleSheet();
+    expect(sheet).not.toBeNull();
+    expect(shadow.adoptedStyleSheets).toContain(sheet);
+    expect(shadow.querySelector("style")).toBeNull();
+  });
+
+  it("shares one CSSStyleSheet across multiple shadow roots", () => {
+    const shadowA = createShadowHost();
+    const shadowB = createShadowHost();
+
+    applyPlayerStyles(shadowA);
+    applyPlayerStyles(shadowB);
+
+    const adoptedA = shadowA.adoptedStyleSheets.at(-1);
+    const adoptedB = shadowB.adoptedStyleSheets.at(-1);
+
+    expect(adoptedA).toBeDefined();
+    expect(adoptedA).toBe(adoptedB);
+  });
+
+  it("preserves any pre-existing adopted stylesheets", () => {
+    const shadow = createShadowHost();
+    const existing = new CSSStyleSheet();
+    existing.replaceSync(":host { --pre: 1; }");
+    shadow.adoptedStyleSheets = [existing];
+
+    applyPlayerStyles(shadow);
+
+    expect(shadow.adoptedStyleSheets[0]).toBe(existing);
+    expect(shadow.adoptedStyleSheets).toContain(getSharedPlayerStyleSheet());
+    expect(shadow.adoptedStyleSheets).toHaveLength(2);
+  });
+
+  it("is idempotent when called repeatedly on the same shadow root", () => {
+    const shadow = createShadowHost();
+
+    applyPlayerStyles(shadow);
+    applyPlayerStyles(shadow);
+    applyPlayerStyles(shadow);
+
+    expect(shadow.adoptedStyleSheets).toHaveLength(1);
+    expect(shadow.querySelectorAll("style")).toHaveLength(0);
+  });
+
+  it("falls back to a <style> element when adoptedStyleSheets is unsupported", () => {
+    const shadow = createShadowHost();
+    Object.defineProperty(shadow, "adoptedStyleSheets", {
+      configurable: true,
+      get() {
+        return undefined;
+      },
+      set() {
+        throw new Error("adoptedStyleSheets is not supported in this environment");
+      },
+    });
+
+    applyPlayerStyles(shadow);
+
+    const styleEl = shadow.querySelector("style");
+    expect(styleEl).not.toBeNull();
+    expect(styleEl?.textContent).toBe(PLAYER_STYLES);
+  });
+
+  it("falls back to a <style> element when CSSStyleSheet is unavailable", () => {
+    const original = globalThis.CSSStyleSheet;
+    (globalThis as { CSSStyleSheet?: unknown }).CSSStyleSheet = undefined;
+
+    try {
+      const shadow = createShadowHost();
+      applyPlayerStyles(shadow);
+
+      const styleEl = shadow.querySelector("style");
+      expect(styleEl).not.toBeNull();
+      expect(styleEl?.textContent).toBe(PLAYER_STYLES);
+    } finally {
+      globalThis.CSSStyleSheet = original;
+    }
+  });
+
+  it("falls back to a <style> element when replaceSync throws", () => {
+    const replaceSyncSpy = vi
+      .spyOn(CSSStyleSheet.prototype, "replaceSync")
+      .mockImplementation(() => {
+        throw new Error("simulated replaceSync failure");
+      });
+
+    try {
+      const shadow = createShadowHost();
+      applyPlayerStyles(shadow);
+
+      expect(shadow.querySelector("style")?.textContent).toBe(PLAYER_STYLES);
+    } finally {
+      replaceSyncSpy.mockRestore();
+    }
+  });
+});
diff --git a/packages/player/src/styles.ts b/packages/player/src/styles.ts
index 2ae4e650a..35a565b42 100644
--- a/packages/player/src/styles.ts
+++ b/packages/player/src/styles.ts
@@ -199,3 +199,80 @@ export const PLAYER_STYLES = /* css */ `
 
 export const PLAY_ICON = `<svg width="24" height="24" viewBox="0 0 18 18" fill="currentColor"><polygon points="4,2 16,9 4,16"/></svg>`;
 export const PAUSE_ICON = `<svg width="24" height="24" viewBox="0 0 18 18" fill="currentColor"><rect x="3" y="2" width="4" height="14"/><rect x="11" y="2" width="4" height="14"/></svg>`;
+
+/**
+ * Process-wide cache for the constructed PLAYER_STYLES sheet. Lazy so the
+ * module stays SSR-safe (CSSStyleSheet is window-scoped) and so a single
+ * sheet can be shared across every shadow root via `adoptedStyleSheets` —
+ * the studio thumbnail grid renders dozens of players, and avoiding N
+ * duplicate `<style>` parses + style-recalc invalidations is the win here.
+ *
+ * `null` after a failed construction attempt = "fall back forever in this
+ * process" (the usual cause is a missing constructor in older runtimes;
+ * retrying every call would just throw the same way).
+ */
+let sharedSheet: CSSStyleSheet | null | undefined;
+
+/**
+ * Returns the shared player stylesheet, or `null` if constructable
+ * stylesheets aren't available in this environment.
+ *
+ * The result is memoized for the life of the module — every shadow root
+ * adopts the same `CSSStyleSheet` instance.
+ */
+export function getSharedPlayerStyleSheet(): CSSStyleSheet | null {
+  if (sharedSheet !== undefined) return sharedSheet;
+
+  if (typeof CSSStyleSheet === "undefined") {
+    sharedSheet = null;
+    return null;
+  }
+
+  try {
+    const sheet = new CSSStyleSheet();
+    sheet.replaceSync(PLAYER_STYLES);
+    sharedSheet = sheet;
+    return sheet;
+  } catch {
+    sharedSheet = null;
+    return null;
+  }
+}
+
+/**
+ * Internal hook for tests to clear the memoized sheet. Not part of the
+ * public API.
+ */
+export function _resetSharedPlayerStyleSheet(): void {
+  sharedSheet = undefined;
+}
+
+/**
+ * Install PLAYER_STYLES into a player shadow root. Prefers the shared
+ * constructable stylesheet (one parse, one rule tree, N adopters) and
+ * falls back to a per-instance `<style>` element when the host runtime
+ * lacks `adoptedStyleSheets` support.
+ *
+ * Idempotent: re-applying to a root that already adopts the shared sheet
+ * is a no-op. Pre-existing adopted sheets are preserved (we append, never
+ * replace), so callers further up the chain can keep their styles.
+ */
+export function applyPlayerStyles(shadow: ShadowRoot): void {
+  const sheet = getSharedPlayerStyleSheet();
+  const adopted = (shadow as ShadowRoot & { adoptedStyleSheets?: CSSStyleSheet[] })
+    .adoptedStyleSheets;
+
+  if (sheet && Array.isArray(adopted)) {
+    if (!adopted.includes(sheet)) {
+      (shadow as ShadowRoot & { adoptedStyleSheets: CSSStyleSheet[] }).adoptedStyleSheets = [
+        ...adopted,
+        sheet,
+      ];
+    }
+    return;
+  }
+
+  const style = document.createElement("style");
+  style.textContent = PLAYER_STYLES;
+  shadow.appendChild(style);
+}