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]

• perf(player): scope MutationObserver to composition hosts #395 : 2 dependent PRs (#396 , #428 )
• 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

[vanceingalls]

@jrusso1020 — thanks for the review. Two non-blocking observations to address:

the test "falls back to a <style> element when adoptedStyleSheets is unsupported" uses Object.defineProperty to make the setter throw, but the production code only reads the getter

You're right — the test exercises the case where the getter returns undefined, which is what production drops on (via Array.isArray(undefined) === false). The "getter returns array, setter throws" branch isn't covered by a test. I left it as-is for now because no real environment exhibits that combination — every browser that supports adoptedStyleSheets enforces both halves of the descriptor together — but happy to add a defensive try/catch around the assignment if you'd prefer the belt-and-braces version.

sharedSheet memoization key is process-scoped. In a multi-document test environment ... _resetSharedPlayerStyleSheet is the escape hatch — good that it's exported.

Right call out. The escape hatch is intentionally exported for exactly this reason; the runtime path doesn't need a per-document keying because every shadow root in a single document shares the same CSSStyleSheet constructor. Adding a WeakMap<Document, CSSStyleSheet> would catch the cross-document case but penalize the common path, so I'd rather keep _resetSharedPlayerStyleSheet as the documented seam and let test infra call it explicitly.

Nothing else outstanding.

[graphite-app]

Merge activity

• Apr 22, 10:09 PM UTC: This pull request can not be added to the Graphite merge queue. Please try rebasing and resubmitting to merge when ready.
• Apr 22, 10:09 PM UTC: Graphite disabled "merge when ready" on this PR due to: a merge conflict with the target branch; resolve the conflict and try again..
• Apr 22, 10:40 PM UTC: @vanceingalls merged this pull request with Graphite.