feat(player): synchronous seek() API with same-origin detection

[vanceingalls]

Summary

Formalizes the same-origin shortcut Studio has been using privately (iframe.contentWindow.__player.seek in useTimelinePlayer.ts) as a first-class behavior of <hyperframes-player>'s public seek() method. Same-origin seeks now land in the same task as the input event — no postMessage hop, no extra microtask, no perceived scrub lag. Cross-origin embeds fall through to the existing async bridge transparently.

Why

Step P3-1 of the player perf proposal. The current seek() always posts a message to the iframe runtime, which means a single user scrub incurs:

1. JS task: fire postMessage from parent
2. Browser task switch into iframe context
3. Microtask: handler dispatches
4. Frame: runtime calls markExplicitSeek and updates DOM

Same-origin embeds (Studio, preview pane, embedded compositions) can skip all four by calling the runtime's seek directly. Studio was already doing this manually but had to duplicate the local-state bookkeeping (_currentTime, paused, controls UI) — making it a first-class behavior of the player removes the workaround and gives every same-origin consumer the win for free.

What changed

• New _trySyncSeek(time) helper attempts a synchronous call into the iframe's window.__player.seek. Returns true on success, false on cross-origin or pre-bootstrap.
• seek() calls _trySyncSeek first, falls through to the existing _sendControl postMessage path when sync isn't available.
• Detection is a try/catch on contentWindow access (real cross-origin iframes throw SecurityError) plus a typeof guard on __player.seek.
• Local _currentTime, the paused flag, and the controls UI update on both paths so scrubs never leave stale state.
• Runtime-side seek is the same wrapped function the postMessage handler calls — installRuntimeControlBridge routes through player.seek, so markExplicitSeek() and downstream runtime state are identical between the two paths.

Test plan

• 11 new unit tests in hyperframes-player.test.ts covering:
  • Same-origin sync path executes __player.seek synchronously and skips postMessage.
  • Cross-origin (simulated SecurityError on contentWindow) falls back to postMessage.
  • Pre-bootstrap (no __player installed) falls back to postMessage.
  • __player.seek not a function falls back to postMessage.
  • _currentTime, paused, and controls all stay in sync on both paths.
  • Errors thrown from __player.seek propagate without corrupting state.

Stack

Step P3-1 of the player perf proposal. Independent of the P1-* work — this is a pure latency win on the seek/scrub path. Combined with P3-2 (srcdoc composition switching, next in the stack) it removes most of the iframe-bridge overhead from the studio scrubber.

[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 👈 (View in Graphite)
• perf(player): coalesce _mirrorParentMediaTime writes #396
• perf(player): scope MutationObserver to composition hosts #395
• 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]

Formalizes a pattern Studio was already reaching for under the hood (useTimelinePlayer.ts:233). Good: single-task seek on same-origin embeds, transparent postMessage fallback on SecurityError / missing __player / typeof seek !== "function" / runtime panic. Every branch is tested, including the _currentTime cache must update regardless — that catches the easy-to-miss regression where a cross-origin scrub leaves the controls UI showing stale time.

One subtle semantic change worth calling out in the release notes: the sync path passes timeInSeconds through verbatim, while the postMessage path rounds to Math.round(timeInSeconds * DEFAULT_FPS) at the wire boundary. Same-origin embeds will now land sub-frame scrubs at their exact requested time; cross-origin embeds still quantize to frames. Scrub UIs can now drive fractional-frame times on same-origin, which is the improvement — just means a test that does player.seek(7.3333) and asserts exact-equality will only pass same-origin.

Approved.

— Rames Jusso