* fix(core): a clip the preview lets go of stays unloaded in Firefox
Releasing a clip dropped its src, called load() and set the src again.
Firefox treats preload="none" as "metadata" while an explicit load() is
pending, so every release fetched the clip's metadata and first frame. The
runtime then saw a far clip loading and released it again, in a loop: about
20,700 media requests over one 2:16 film, with 2-4 s stalls at cuts.
Setting src already runs the media load algorithm, which ends the fetch, so
the release now sets it again without load(). Chrome and Safari behave as
before: Blink clears its ignore-preload-none flag when src is set, and
WebKit's src set cancels the prepareToPlay that load() queued.
To reproduce: in Firefox, give a <video> with a src preload="none", then call
removeAttribute("src"), load() and setAttribute("src", src) in one task. It
loads to readyState 4; with the src set in a later task it stays at 0.
* fix(player): a film cut from one long recording plays through in Chrome and Firefox
A film whose clips are cut from one or two long recordings froze a few
seconds in, in Chrome and Firefox. Both keep a paused clip's request open
with its unread bytes, and every request to one host shares one HTTP/2 or
HTTP/3 connection window. With every clip of the file loading at parse, those
idle streams fill the window, and the request for the clip coming up is never
answered.
The player's frame now holds clips back on every engine, as it already did on
WebKit: each file keeps the clip on screen and the next one loading, and
frees the rest. The player also names its frame, because a composition in an
opaque sandbox cannot read frameElement to find the player's mark.
To reproduce: play a film of 37 clips cut from a 363 MB and a 180 MB .mov
served over HTTP/3 in <hyperframes-player>. On main it stops at 0:17 in
Chrome and at 0:09 in Firefox and never recovers.
* chore(player): raise the packed size budget for the frame name
Naming the player's frame adds 44 bytes to the packed player (158,706 to
158,750 bytes with pnpm 10.17.1). main was already 10 bytes under the 1%
tolerance of its 157,145-byte budget, so any growth fails the check. The
budget moves to 5% above the new measured size, as the check suggests.
* fix(core): seeking in the player stays as it was in Chrome and Firefox
Holding clips back in every player frame also moved Chrome and Firefox
player frames onto Studio's paused-seek path, which keeps the old picture
until every clip on screen has its new frame. In the player's scrub
benchmark the inline p95 rose from about 1.0 s on main to 1.9 s in CI,
and a seek could miss the benchmark's 1 s limit. In Firefox a paused seek
to a clip the player had let go showed no frame for about 5 s, because the
clip was released again each time it loaded.
Chrome and Firefox player frames now hold clips back and seek as they did
on main. Studio and Safari player frames keep the path they already had.
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.
- Preview automation uses
?hf-capture=1,hyperframes snapshot, or runtime readiness (window.__renderReadyand the seek contract), never a wait on all ofdocument.images. Interactive preview leaves images in hidden future clips unloaded until they are needed.
Runtime-loaded compositions finalize IDs already used by native SVG references before scene
scripts run. IDs used only by JavaScript keep their authored values. If an initial script
introduces an ID's first native url() or href reference, that ID can be renamed after
initial scripts finish. A string captured before that first native use is not guaranteed
stable; read the target element's current id after runtime readiness for deferred writes.
Attribute selectors with a declared namespace prefix (@namespace xl url(...) plus
[xl|href="#id"]) follow renamed references through the live CSSOM before scene scripts run,
in runtime and compiled output alike. Compiled CSS text leaves them as authored, so these
selectors need JavaScript; with scripts disabled they match only unrenamed values.
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.