perf(player): srcdoc composition switching for studio

[vanceingalls]

Summary

Adds srcdoc support to <hyperframes-player> and uses it from studio's Player.tsx so composition switches no longer trigger an iframe navigation. Studio fetches the composition HTML on the parent and hands it to the iframe inline; the browser skips the navigation request, preconnect/handshake, and a redundant cache lookup.

Why

Step P3-2 of the player perf proposal. Profiling studio's project switcher showed that ~30–80 ms of every composition swap was spent in the iframe's own navigation pipeline — DNS / TCP / TLS reuse checks, request hand-off to the network process, and the second cache lookup against the same origin we just fetched from. For same-origin previews (/api/projects/.../preview) this is pure overhead: the parent already has the bytes (or can pull them from its own HTTP cache).

srcdoc lets us skip that pipeline entirely. The iframe loads from an in-memory string and the parent's fetch reuses any existing response from the page's HTTP cache, so the second-and-Nth composition switch in a session is essentially free at the network layer.

What changed

<hyperframes-player> (packages/player/src/hyperframes-player.ts)

• Added srcdoc to observedAttributes so runtime swaps actually fire attributeChangedCallback.
• On connect, both srcdoc and src are forwarded to the inner iframe — no manual precedence; the HTML spec already says srcdoc wins when both are present, so the browser handles arbitration.
• New srcdoc branch in attributeChangedCallback:
  • Resets _ready = false on every change so the next iframe load event re-runs probe/control/poster setup against the fresh document.
  • Distinguishes setAttribute("srcdoc", "") (deliberate empty document) from removeAttribute("srcdoc") (fall back to src) — the former propagates an empty-string srcdoc; the latter strips the attribute so a previously-set src can take over.

Studio Player.tsx (packages/studio/src/player/components/Player.tsx)

• Hoisted AbortController and resolved url outside the dynamic-import .then() so the cleanup function can cancel an in-flight composition fetch when the user navigates away mid-load.
• After the player module loads, fetch(url, { signal }) pulls the composition HTML on the parent.
  • Success → player.setAttribute("srcdoc", html).
  • Network error / non-2xx → fall back to player.setAttribute("src", url). Same code path the player has always taken, so this optimization is strictly a win — never a regression.
  • AbortError → bail without touching the DOM (component is unmounting).
• Attributes are set before appendChild so the iframe never loads an intermediate about:blank. That matters because:
  1. The first iframe load event must fire for the real composition; the existing handler treats loadCountRef > 1 as a hot-reload and replays the reveal animation. An extra about:blank load would trigger the reveal on initial mount.
  2. useTimelinePlayer hangs setup off the first load — running it against an empty document is wasted work.

Test plan

• 7 new unit tests in hyperframes-player.test.ts covering:
  • srcdoc is in observedAttributes.
  • Initial srcdoc set before connect forwards to the iframe on connect.
  • Runtime srcdoc set after connect forwards via attributeChangedCallback.
  • _ready resets when srcdoc changes so onIframeLoad replays setup.
  • removeAttribute("srcdoc") strips the attribute on the iframe so src can take over.
  • Empty-string srcdoc is preserved (not treated as removal).
  • Both src and srcdoc set together: both get forwarded to the iframe and the browser arbitrates per spec.
• Studio fallback path verified manually — disabling fetch falls back to the original src flow with no regression.

Stack

Step P3-2 of the player perf proposal. Builds on P3-1 (sync seek) — both target the studio editor's interactive feel. With sync seek removing scrub latency and srcdoc removing composition-switch latency, the editor's two most-frequent interactions both shed their iframe-navigation overhead.

[vanceingalls]

• 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 👈 (View in Graphite)
• feat(player): synchronous seek() API with same-origin detection #397
• perf(player): coalesce _mirrorParentMediaTime writes #396
• perf(player): scope MutationObserver to composition hosts #395 : 1 other dependent PR (#428 )
• perf(player): share PLAYER_STYLES via adoptedStyleSheets #394
• 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 swap. Pre-fetching the composition HTML and handing it to the iframe via srcdoc is the classic "skip the navigation" win, and the AbortController wiring means a studio project-switch mid-fetch doesn't leave an orphan in-flight request firing into an unmounted component. The comments on the ordering (setting srcdoc/src before appendChild so the first load event fires for the real composition, not an intermediate about:blank) are load-bearing enough that I'm glad they're in-code rather than tribal.

Test coverage is thorough — initial attribute, post-connect change, removal distinguished from empty string, both-srcdoc-and-src-present letting the browser arbitrate via spec precedence, _ready reset on swap. The empty-string vs removal distinction is the kind of thing that only matters once a caller actually exercises it, and nice to see it pinned now.

Non-blocking observations:

1. The studio fetch falls back to src on any non-AbortError failure. For consistency, the fallback branch could emit an analytics/perf metric (leveraging #393) so we can spot how often the srcdoc fast path is actually used in the wild. Not a blocker.

2. fetch(url, { signal }) then player.setAttribute("srcdoc", html) copies the HTML text into an attribute; for large compositions (hundreds of KB inline) this adds a ~1 copy plus DOM attribute cost. Probably still a net win vs network navigation, but worth remembering once compositions grow.

Approved.

— Rames Jusso

[miguel-heygen]

I tested the stack locally with agent-browser sanity checks in Studio plus repeated bun run player:perf -- --mode=measure --scenarios=load,fps,scrub,drift,parity --runs=2 runs on both this stack and main artifacts.

The implementation here looks directionally good: srcdoc support in <hyperframes-player> is wired correctly, the AbortController cleanup is correct, and I don’t see a correctness issue with the fetch-then-inline path for same-origin previews.

The important caveat is evidentiary, not correctness: the perf harness that shows the wins is still measuring the standalone /host.html?fixture=... player flow, not the Studio Player.tsx fetch -> srcdoc preview path introduced in this PR. So I buy the optimization, but I would not over-claim measured Studio impact from the current numbers alone. If we want this PR to carry a strong performance claim, we should either add a Studio-specific switch benchmark later or narrow the wording to “expected Studio composition-switch improvement” rather than presenting it as already proven by the current harness.

Not blocking this PR on that, but I wanted it called out explicitly because the distinction matters at review time.

[vanceingalls]

@jrusso1020 @miguel-heygen — thanks for the review. Three observations to address; none are blocking but worth tracking:

1. The Studio fetch-fallback path could emit an analytics event or perf metric when it hits, leveraging feat(core): add emitPerformanceMetric bridge for runtime telemetry #393

Agreed. Not done in this PR to keep the change surgical, but it's the logical next consumer of the emitPerformanceMetric bridge added in #393. Tracked as a follow-up: a srcdoc-prefetch-fallback mark with the failure mode (fetch-failed, cross-origin, non-200) so we can quantify how often production paths actually take the slow road.

2. Large compositions copied as srcdoc will land in the document's HTML cost — for the Carousel case the docs/HTML are small but worth noting for posterity if someone tries to embed a multi-MB asset blob inline.

Right call — the prefetch path has an upper bound that we should make explicit before someone embeds a large composition. Will add a soft size cap (probably ~256KB of HTML) with a console.warn and fall back to the network src path above the threshold; tracking as a follow-up rather than tightening it here.

Miguel: the perf harness measures the standalone host page, not the Studio Player.tsx switch path

Correct, and worth being precise about in the PR description: this PR optimizes <hyperframes-player> itself, but the Studio surface that you care about (Player.tsx) sits on top of an additional React render + state-machine boundary that the host benchmark can't see. The standalone harness gives us the lower bound; quantifying the Studio-switch delta needs a Studio-mode benchmark we haven't built yet. Tracked separately — happy to scope that as its own perf scenario if it'd unblock you.

Nothing else outstanding.

[vanceingalls]

Merge activity

• Apr 23, 12:59 AM UTC: @vanceingalls merged this pull request with Graphite.