fix: stabilize studio preview and runtime sync

[miguel-heygen]

Summary

Stabilize the Studio preview/runtime path so timeline data, preview rendering, and thumbnails stay in sync.

This PR includes:

• preview hot-refresh without remounting the iframe
• runtime duration/timeline fixes so Studio stops drifting from playback state
• thumbnail and selector-based preview fixes
• local Studio runtime serving and player-resolution fixes so dev/CI do not depend on prebuilt player artifacts
• tests around preview identity and thumbnail/runtime behavior

Why This PR Exists

This is the foundation layer for timeline editing. Without it, the editor was prone to:

• iframe remount flashes after saves
• duration mismatches between preview and timeline
• stale or incorrect thumbnails
• CI/test failures when @hyperframes/player artifacts were not prebuilt

Verification

• bun run --filter @hyperframes/studio test
• bun run --filter @hyperframes/studio typecheck
• bun run --filter @hyperframes/core typecheck
• bunx oxlint packages/cli/src/server/studioServer.ts packages/core/src/runtime/timeline.ts packages/core/src/runtime/timeline.test.ts packages/core/src/studio-api/routes/thumbnail.ts packages/core/src/studio-api/routes/thumbnail.test.ts packages/core/src/studio-api/types.ts packages/studio/src/components/nle/NLELayout.tsx packages/studio/src/components/nle/NLEPreview.tsx packages/studio/src/components/nle/NLEPreview.test.ts packages/studio/src/player/components/CompositionThumbnail.tsx packages/studio/src/player/components/Player.tsx packages/studio/src/player/hooks/useTimelinePlayer.ts packages/studio/src/player/store/playerStore.ts packages/studio/vite.config.ts
• bunx oxfmt --check packages/cli/src/server/studioServer.ts packages/core/src/runtime/timeline.ts packages/core/src/runtime/timeline.test.ts packages/core/src/studio-api/routes/thumbnail.ts packages/core/src/studio-api/routes/thumbnail.test.ts packages/core/src/studio-api/types.ts packages/studio/src/components/nle/NLELayout.tsx packages/studio/src/components/nle/NLEPreview.tsx packages/studio/src/components/nle/NLEPreview.test.ts packages/studio/src/player/components/CompositionThumbnail.tsx packages/studio/src/player/components/Player.tsx packages/studio/src/player/hooks/useTimelinePlayer.ts packages/studio/src/player/store/playerStore.ts packages/studio/vite.config.ts

Stack

• base of stack
• followed by feat: add studio timeline editing
• followed by fix: smooth scrubber end seeking

[miguel-heygen]

• fix: smooth scrubber end seeking #386
• feat: add studio timeline editing #390
• fix: stabilize studio preview and runtime sync #389 👈 (View in Graphite)
• main

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

[jrusso1020]

One additional gap I noticed that I could not attach inline because the file is outside the PR diff: the selector-aware thumbnail path looks only partially wired through. useTimelinePlayer now captures selector metadata and CompositionThumbnail accepts it, but the timeline rendering call sites in packages/studio/src/App.tsx still instantiate CompositionThumbnail without passing el.selector. So the new server-side selector clipping path does not appear to be exercised by the main timeline UI yet.

[miguel-heygen]

Addressed the selector thumbnail gap in 51135377.

What changed:

• packages/studio/src/App.tsx now passes selector={el.selector} through all three CompositionThumbnail timeline render paths
• this wires the selector-aware server thumbnail clipping path into the main timeline UI, not just the data pipeline

Verification:

• bunx oxlint packages/studio/src/App.tsx
• bunx oxfmt --check packages/studio/src/App.tsx
• bun run --filter @hyperframes/studio typecheck

[jrusso1020]

Foundation looks solid. Good test coverage on the new pure helpers (mergeTimelineElementsPreservingDowngrades, getPreviewPlayerKey, thumbnail selector plumbing). The runtime-source fallback making dev/CI independent of a prebuilt @hyperframes/core artifact is a nice ergonomic win.

Two things worth calling out — neither blocking:

1. Soft breaking change in timeline.ts: persistent overlays now require data-timeline-role="overlay" (or "persistent-overlay") to appear in Studio. Existing compositions with auto-showing <div id="grid-overlay"> style decorations will silently disappear from the timeline UI. Playback isn't affected, but the in-Studio tracklist will look different. Worth a one-line mention in the alpha release notes so authors know about the opt-in attribute.

2. Duration no longer "don't-downgrade": previous guard on handleMessage was if (dur > currentDur) setDuration(dur); this PR removes that and accepts any 0 < dur < 7200. Reasoning is clear (stop drifting from runtime), and mergeTimelineElementsPreservingDowngrades handles the element side. Just noting: if an intermediate manifest during generation reports a shorter duration, the timeline controls will now flap with it. Likely fine, but keep an eye on it once timeline editing lands on top.

3. opts.selector → page.evaluate(selector => document.querySelector(selector)): safe functionally (querySelector doesn't execute), but a crafted selector like *:has(*:has(...)) could be arbitrarily expensive to evaluate and the cache-key sanitizer creates distinct keys per input, so every variation bypasses the cache. Post-alpha, worth a selector length/complexity guard on the route handler.

Approved for alpha.

— Rames Jusso

[miguel-heygen]

Merge activity

• Apr 21, 11:42 PM UTC: @miguel-heygen merged this pull request with Graphite.