perf(player): share PLAYER_STYLES via adoptedStyleSheets

[vanceingalls]

Summary

Replace per-instance <style> injection in <hyperframes-player> with a lazily constructed CSSStyleSheet adopted via shadowRoot.adoptedStyleSheets. One parsed stylesheet, many adopters — the studio thumbnail grid renders dozens of players concurrently and was paying for N parses of the same CSS.

Why

Step P1-1 of the player perf proposal. The previous implementation appended a <style> element to every shadow root, which means:

• N shadow roots → N copies of the same CSS string parsed into N independent style sheets.
• Each <style> lives in the DOM and contributes to layout/style invalidation work when its shadow root churns.
• The studio's project grid mounts ~30 players on initial load — that's 30 redundant parses of the same ~1 KB stylesheet on the critical path.

adoptedStyleSheets flips this: parse once at module load, hand the same CSSStyleSheet reference to every shadow root.

What changed

• New getSharedPlayerStyleSheet() in packages/player/src/styles.ts — module-scoped and memoized; the sheet is built once per process and returned to every adopter.
• New applyPlayerStyles(shadow) is the single integration point. 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.
• SSR-safe via a typeof CSSStyleSheet guard. Failures (e.g. replaceSync throw, no constructor) are cached as null so we don't retry constructor failures forever.
• Defensive fallback path creates a per-instance <style> element when adoptedStyleSheets is unavailable (older runtimes, hostile environments). Behavior on those paths is unchanged from before.
• PLAYER_STYLES, PLAY_ICON, and PAUSE_ICON exports preserved — no public API change.

Test plan

• Unit tests in styles.test.ts 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.
• Integration test in hyperframes-player.test.ts confirms two real <hyperframes-player> elements adopt the same CSSStyleSheet instance and inject zero <style> elements.
• Build size delta is negligible (utility code replaces container.appendChild calls).

Stack

Step P1-1 of the player perf proposal. Followed by P1-2 (scoping the media MutationObserver) and P1-4 (coalescing parent media-time mirror writes) — all three target the studio multi-player render path.

[vanceingalls]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• perf(player): p0-1c live-playback parity test via SSIM #401
• perf(player): p0-1b perf tests for fps, scrub latency, and media sync drift #400
• perf(player): p0-1a perf test infra + composition-load smoke test #399
• perf(player): srcdoc composition switching for studio #398
• feat(player): synchronous seek() API with same-origin detection #397
• perf(player): coalesce _mirrorParentMediaTime writes #396
• perf(player): scope MutationObserver to composition hosts #395
• perf(player): share PLAYER_STYLES via adoptedStyleSheets #394 👈 (View in Graphite)
• feat(core): add emitPerformanceMetric bridge for runtime telemetry #393
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[jrusso1020]

Good perf win. Constructable stylesheet shared across every shadow root, memoized, with a proper <style> fallback when CSSStyleSheet is missing, replaceSync throws, or adoptedStyleSheets returns non-array. Test matrix covers each fallback path individually — exactly the right way to exercise this.

Idempotency test (applyPlayerStyles called three times → one adopted sheet, zero <style> elements) is what pinned my confidence here. The preservation of pre-existing adoptedStyleSheets is a nice touch for hosts that stack their own sheets on top.

Two non-blocking observations:

1. The test "falls back to a <style> element when adoptedStyleSheets is unsupported" uses Object.defineProperty to make the setter throw, but the production code (if (sheet && Array.isArray(adopted))) only reads the getter. In the tested scenario the getter returns undefined, so Array.isArray(undefined) === false, which takes the fallback path. That's fine — but an environment where the getter returns an array and the setter throws would skip the guard. Probably not real-world, just noting.

2. sharedSheet memoization key is process-scoped. In a multi-document test environment (some test runners reuse modules across multiple documents), a stale CSSStyleSheet from a prior document could be handed to a new one. _resetSharedPlayerStyleSheet is the escape hatch — good that it's exported.

Approved.

— Rames Jusso