Files
hyperframes/packages/core
Miguel Ángel c5a69727ff fix(core): bundling and rendering keep print-only, titled and non-CSS styles conditional (#4664)
* fix(core): keep print-only and non-CSS head styles apart when bundling

* fix(core): inline each linked stylesheet where its link was, keeping its media

* fix(core): merge a titled head style only with styles of the same title

A style with a non-empty title belongs to a style sheet set; the browser
enables only the preferred set, so merging it into an untitled
(persistent) style or one with another title changes what applies.
An empty title is persistent, like no title; titles compare
case-sensitively. An inlined linked sheet carries its link's title.
The merge key returns undefined for a non-CSS type (never merged or
inlined) and treats media="all" as no media, as the browser does.

* fix(core): leave a disabled stylesheet link as a link instead of inlining it

* fix(producer): render keeps conditional head styles apart, as the preview does

* test(core): pin case and padding in head style merge keys, drop a subsumed case

* fix(core): keep a composition style's media, and leave its non-CSS styles out of CSS

* fix(core): emit a conditional composition style as its own element, keeping media and title

* test(core): make the non-CSS composition style fixture able to fail

* fix(core): a composition's link keeps its own media and title when another links the same file

Hoisted composition links are deduped on href, rel, condition, type and disabled
rather than href alone, in the bundle, the render and the live mount, and keep
their type and disabled state.

* fix(core): the bundle keeps a font's only applied copy when an alternate style repeats it

The font dedupe asks cssStyleMergeKey whether a style always applies, so a titled
style no longer counts as always applied.

* fix(core): the bundle inlines a linked sheet whose type names a charset

Chrome applies <link type="text/css; charset=utf-8">, so a link's type is read by
its MIME essence; a style's type still has to be exactly text/css. Adds a test for a
template with no matching root and a non-CSS style.

* style(core): drop a comment the constant's name already says

* fix(core): hoisted links dedupe on CORS mode, integrity and referrer policy, not noscript copies

One helper, hasSameLink, decides whether a hoisted link duplicates a live one, for the
bundle, the render and the mount. inlineSubCompositions no longer dedupes its result on
its own. Tests cover rel, disabled, non-CSS type, CORS, integrity, referrer policy and a
root noscript link.

* fix(core): a root link and a composition's same link differing only in fetch attributes ship once

The link key goes back to href, rel, condition and disabled; crossorigin, integrity and
referrerpolicy are not compared, so a root snippet repeated in a composition is emitted
once and the root's override styles keep their order.
2026-09-29 07:27:33 +00:00
..
2026-09-29 06:33:17 +00:00

@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