fix(player+core): correctly render and pause nested compositions

[jrusso1020]

Two related fixes for nested-composition playback in <hyperframes-player>. Both surface when a composition uses data-composition-src to lazy-load child scenes (e.g. registry/examples/product-promo) and is served through the async/non-bundled path — i.e. raw static files or a custom server that doesn't run the composition through bundleToSingleHtml.

The studio preview (hyperframes preview) already bundles compositions via bundleToSingleHtml before serving, so it masks both bugs. They're latent for studio users but visible to anyone embedding the player against raw composition HTML (static hosts, CDN embeds, the upcoming HyperFrames Vercel template, etc.).

1. fix(player): inject runtime immediately for nested compositions

Problem

<hyperframes-player> renders an empty black iframe when loading any composition that uses data-composition-src on child elements. The composition is structured correctly and renders perfectly via hyperframes render server-side — but the browser preview is blank.

Root cause

The probe loop in hyperframes-player.ts has two paths to "ready":

1. Inject the runtime if hasTimelines && !hasRuntime && attempts >= 5
2. Use an adapter built from whatever's at window.__timelines or window.__player if adapter.getDuration() > 0

For nested compositions in the async path, path (2) wins the race. The composition registers inline pre-runtime GSAP timelines at window.__timelines[\"main\"] while the iframe document is loading (typically covering only a partial duration — 14s of a 20s master, for product-promo). On the very first probe tick — long before attempts reaches 5 — the adapter check finds that timeline, treats it as source of truth, and locks the player into a broken "ready" state. The runtime never gets injected, so scenes declared via data-composition-src never load. The iframe stays blank.

Fix

Split the injection decision into a pure helper (shouldInjectRuntime(state)) and treat compositions with data-composition-src children as "inject immediately, skip the attempts gate." Self-contained GSAP-only compositions retain the 5-tick grace period so the adapter path keeps first shot for them (no regression).

2. fix(core): propagate play/pause to all sibling timelines

Problem

Even after the runtime loads, clicking pause on the player only freezes the master timeline (which, for product-promo, is the partial inline mainTl plus captions). The per-scene timelines keep playing, and after a few seconds the composition ends up in an empty gray end-state while the player UI still shows the paused time.

Root cause

packages/core/src/runtime/player.ts:67-78 — player.pause() only calls .pause() on the single adapter-selected timeline (state.capturedTimeline). In the async scene-loading path, each scene's timeline is registered as a sibling in window.__timelines (e.g. scene1-logo-intro, scene2-4-canvas, scene5-logo-outro), driven independently off GSAP's ticker. Pausing master leaves them free-running. Same issue symmetrically on play().

Bundled compositions happen to avoid this because the bundled pipeline nests everything synchronously, and nested children inherit their parent's paused state.

Fix

Wire window.__timelines into the runtime player via a new optional getTimelineRegistry dep, iterate the registry on play/pause, and forward timeScale to siblings on play so a changed playback-rate applies uniformly. Identity-equality check ensures the master isn't double-invoked; a try/catch isolates one broken sibling from breaking the whole pause. The change is a no-op on the bundled path (siblings there are already paused as nested children).

Files

• packages/player/src/shouldInjectRuntime.ts — new pure decision helper
• packages/player/src/shouldInjectRuntime.test.ts — 8 unit tests
• packages/player/src/hyperframes-player.ts — compute hasNestedCompositions, call the helper
• packages/core/src/runtime/player.ts — add getTimelineRegistry to PlayerDeps, iterate on play/pause
• packages/core/src/runtime/player.test.ts — 7 new unit tests covering propagation, playbackRate, identity, errors, back-compat, undefined entries
• packages/core/src/runtime/init.ts — wire window.__timelines into the dep

Testing

• cd packages/player && bunx vitest run — 35/35 pass (8 new + 27 existing)
• cd packages/core && bunx vitest run — 488/488 pass (7 new + 481 existing)
• bunx oxlint clean across all changed files
• bunx oxfmt --check clean
• bun run typecheck clean in both packages
• End-to-end verified via Playwright against a live Vercel deploy of a Next.js template using the unmodified product-promo composition: preview at t=0 matches rendered MP4 frame 0, preview at t=3s matches frame 3. Pause freezes the full composition, not just the master timeline.
• Manually verified the bug in the release: running npx hyperframes@latest preview registry/examples/product-promo (which goes through the bundled path) pauses correctly — consistent with this being a bug in the async-scene-loading path only.