mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-20 20:38:34 +00:00
* 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
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.__playerwindow.__playerReadywindow.__renderReadywindow.__timelineswindow.__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 wholeframe, the exactcurrentTimein seconds andended, true once the clock has reached the film's end; a parent ends the film onendedrather than comparing times, and a pause on the last frame stays a pausetype: "timeline"carriesassetsReady(whether the composition's media, images and fonts have settled) and the runtime then poststype: "assets-ready"once, so a parent that cannot read the iframe can gate playbacktype: "ready"— emitted once wheninstallRuntimeControlBridgeregisters 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:
renderSeekis 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 unapproveddata:) 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.