* fix(core): a later connect from the preview parent gets a fresh editing port A parent that disposes its editing client and creates a new one for the same frame (a remount that keeps the iframe) used to wait forever: the runtime handed its port over once per page load. Each valid connect from the parent now closes the previous port and hands over a new one. Connects from any other sender are still ignored. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(studio): playback and timeline reads go over the preview's message channel Prepares Studio's preview to run on an opaque origin, where the parent cannot read the frame's window. - previewChannel: one editing-port client per frame load, plus the loop start, seek-painted and clip-manifest reads over it. - bridgePlayback: a playback adapter that sends play, pause and seek as control-bridge messages and mirrors the runtime's state and timeline posts. It is used only for a frame Studio cannot script; a same-origin frame keeps the direct adapter. - The loop start and the state-tick manifest recovery now always use the editing port. The shadow reload's seek-painted wait uses it for a frame Studio cannot script. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(core,studio): trim comments back under each file's comment share Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(studio): keep the direct loop-start and manifest reads for frames Studio can script A host can pair this Studio with a runtime older than the editing port. The loop start and the state-tick manifest recovery now read a same-origin frame directly, exactly as before; only a frame Studio cannot script uses the port. previewFrameOpaque replaces previewFrameScriptable and treats a frame with no window as not opaque, so a detached frame keeps its old no-op path too. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(core,studio): keep every editing port the parent receives working on an opaque preview The runtime posts ready before it installs its editing agent, so a client can connect twice and receive two ports. Closing the earlier port on each connect left a client that took the first one with a dead channel for the rest of the frame load. The agent now keeps earlier ports open (a disposed client closes its own end) and closes all of them on teardown. For an opaque preview: - the restore-seek wait gives up after a 1 s probe when no editing port arrives, so a runtime without the agent no longer holds a reload for 15 s; - the bridge playback mirror keeps a seek until the runtime confirms it, so a state posted before the seek cannot undo a quick frame step; - sceneSwapFor returns no swap instead of reading the frame's window, so a reload falls back to a full reload. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(studio): call a frame opaque only when its window refuses a read previewFrameOpaque treated any frame whose contentDocument was null as opaque. A same-origin window can still report a null contentDocument (an iframe that is not in the document), and that sent it down the opaque path. A frame is opaque now only when reading its window's document throws, as it does across origins. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(studio): mirror playback only from preview frames Studio built, at frame precision The bridge playback mirror took a state or timeline post from any window and made a mirror for it. It now takes a post only from a frame Player registered (watchPreviewFrame, called before the frame loads, so the boot-time timeline is not missed), and only when the post's origin is one that frame can have: null for an opaque sandbox or a data: URL, the parent's origin for srcdoc, about: or no src, else the origin of its src. A pending seek now counts as confirmed by the frame the runtime lands it on, the frame at or before it, rather than by a 1 ms match. An off-grid seek used to drop every state post for 500 ms, freezing the playhead and its play state. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(studio): keep the editing-client tests' fake frame detached from the document Main's test harness now attaches its fake iframe, and happy-dom then fires that frame's about:blank load on its own, which ends the editing client's frame load mid-test. These tests build their own detached frame instead. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(studio): share the detached fake frame with the manifest router test The manifest router test had the same race: the attached harness frame's own about:blank load ended the editing client before the port answered, which lost on the slower Windows runner. The harness now exports detachedFakeIframe, which makeFakeIframe builds on, and both opaque-frame test files use it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@hyperframes/core
Types, parsers, generators, compiler, linter, runtime, and frame adapters for the Hyperframes video framework.
Install
npm install @hyperframes/core
Most users don't need to install core directly — the CLI, producer, and studio packages depend on it internally.
What's inside
| Module | Description |
|---|---|
| Types | TimelineElement, CompositionSpec, Asset, canvas dimensions, defaults |
| Parsers | parseHtml — extract timeline elements from HTML; parseGsapScript — parse GSAP animations |
| Generators | generateHyperframesHtml — produce valid Hyperframes HTML from a composition spec |
| Compiler | compileTimingAttrs — resolve data-start / data-duration into absolute times |
| Linter | lintHyperframeHtml — validate Hyperframes HTML (missing attributes, overlapping tracks, etc.) |
| Runtime | IIFE script injected into the browser — manages seek, media playback, and the window.__hf protocol |
| Frame Adapters | Pluggable animation drivers (GSAP, Lottie, CSS, or custom) |
Generated composition trust
Composition generators require trusted authors for code-bearing inputs. styles and
generateHyperframesStyles preserve authored CSS, which can load external resources.
animations may contain __raw: values that are emitted as JavaScript;
includeScripts: true includes executable timeline code. serializeGsapAnimations
also accepts raw preamble, postamble, and a code-bearing timelineVar. Never fill
these inputs with untrusted data. Attribute encoding and closing-tag containment
are not a sandbox; render untrusted compositions in an appropriately isolated
execution environment and never serve them on a privileged origin.
Text content retains the supported inline-formatting sanitizer contract. The clip parser intentionally flattens inner formatting to text, so parse/generate is not a lossless replacement for editing the source HTML.
Frame Adapters
A frame adapter tells the engine how to seek your animation to a specific frame:
import { createGSAPFrameAdapter } from "@hyperframes/core";
const adapter = createGSAPFrameAdapter({
getTimeline: () => gsap.timeline(),
compositionId: "my-video",
});
Implement FrameAdapter for custom animation runtimes:
import type { FrameAdapter } from "@hyperframes/core";
const myAdapter: FrameAdapter = {
id: "my-adapter",
getDurationFrames: () => 300,
seekFrame: (frame) => {
/* seek your animation */
},
};
Parsing and generating HTML
import { parseHtml, generateHyperframesHtml } from "@hyperframes/core";
const { elements, metadata } = parseHtml(htmlString);
const html = generateHyperframesHtml(spec);
Linting
import { lintHyperframeHtml } from "@hyperframes/core/lint";
const result = lintHyperframeHtml(htmlString);
// result.findings: { severity, message, elementId }[]
Documentation
Full documentation: hyperframes.heygen.com/packages/core
Related packages
@hyperframes/engine— rendering engine that drives the browser@hyperframes/producer— full render pipeline (capture + encode)hyperframes— CLI