Files
hyperframes/packages/core/src/runtime
Miguel Ángel 8661e8c965 perf(studio): move the live tweens in place after a timeline drop (#5042)
* perf(studio): move the live tweens in place after a timeline move instead of re-running the script

* fix(studio): pair a live retime with the script's own tweens, not the nested composition timelines

* fix(studio): leave the runtime's filler tweens out of a live retime's pairing

* refactor(studio): move the live tweens in their own step of the timing sync

* perf(studio): read nested files only when a timing edit re-runs the script

* fix(studio): move live tweens only when the live timeline is exactly what the script parser read

* fix(core): a rebound timeline is padded and timed like a fresh load

* refactor(studio): decide unknown tween lengths in the plan and check order swaps only on a move

* fix(studio): re-run the script whenever moving the live tweens could differ from a fresh load

* fix(studio): keep trims and reformatted scripts on the fast path, re-run for delays and hosts

* fix(studio): re-run for tweens inside a sub-composition host or that change order on an element

* fix(studio): ignore layout inside raw script values when matching a reformatted preview script

* refactor(studio): check each moved element once and scan nested timelines only for moved targets

* docs(studio): keep the live-retime comments within the merge hook's rules
2026-10-05 08:14:35 +00:00
..
…
…
…

Hyperframe Runtime Engine

This folder owns the runtime that powers preview and producer parity.

Current Direction

  • Runtime source of truth is converging on hyperframe.ts.
  • Build produces:
    • dist/hyperframe.runtime.iife.js (browser bootstrap)
    • dist/hyperframe.runtime.mjs (tooling/tests)
    • dist/hyperframe.manifest.json (version + sha256 + artifact map)
  • FE owns iframe runtime injection.
  • BE persists raw generated HTML without injecting runtime scripts.
  • Producer validates pinned runtime checksum from manifest before render.

Runtime Contract (Stable Surface)

Globals:

  • window.__player
  • window.__playerReady
  • window.__renderReady
  • window.__timelines
  • window.__clipManifest

postMessage:

  • parent -> runtime control:
    • source: "hf-parent"
    • type: "control"
    • actions: play, pause, seek, set-muted, set-playback-rate, enable-pick-mode, disable-pick-mode
  • runtime -> parent events:
    • source: "hf-preview"
    • type: "state" carries the whole frame, the exact currentTime in seconds and ended, true once the clock has reached the film's end; a parent ends the film on ended rather than comparing times, and a pause on the last frame stays a pause
    • type: "timeline" carries assetsReady (whether the composition's media, images and fonts have settled) and the runtime then posts type: "assets-ready" once, so a parent that cannot read the iframe can gate playback
    • type: "ready" — emitted once when installRuntimeControlBridge registers the control-message listener. The parent uses it to replay current playback state (set-muted, set-volume, set-playback-rate) so any control message sent before the listener was installed isn't lost. Emitted again on every iframe reload because the new runtime instance starts with no state.

Determinism baseline:

  • renderSeek is the producer-canonical seek path.
  • 30fps quantization and readiness gates are correctness requirements.

Build

bun run --filter @hyperframes/core build:hyperframes-runtime

Security Expectations

  • Runtime bootstrap URL must be version-pinned and host-allowlisted.
  • Iframe bridge payloads must be schema-validated.
  • Unsafe URL schemes (javascript: and unapproved data:) are rejected.
  • Fail closed if runtime bootstrap/handshake is not healthy.

Product Editing Model

  • Primary mode: prompt + element picking.
  • Secondary mode: manual precision controls.
  • Avoid timeline-first manual workflows as default product path.