Files
hyperframes/packages/core
Ice colaandClaude Fable 5.1 95e4e7f880 fix(producer): probe sub-composition media defaults (#7550)
* fix(producer): probe sub-composition media defaults

Sub-composition defaults declared on <html> disappear from the DOM
during inlining. The browser-probe gate then misses data-var-src
bindings, causing renders to use the authored placeholder source.

Pass the inliner's variablesByComp table through CompiledComposition
and consult the nearest composition scope when checking media bindings.

Give anonymous mounts distinct runtime scopes and reserve IDs as
nested mounts are processed, preserving each instance's variable values.

Add regression coverage for declared defaults, repeated mounts,
nested scopes, and named/anonymous mount collisions.

Fixes #7505

* fix(core): keep anonymous hosts unnamed, key their variables by the authored id

The previous commit made an anonymous mount claim its sub-composition's id on
the host element, which changed the DOM contract the runtime mount path and
the `missing-host-comp-id` regression golden pin: the compile paths put the
host's start/duration on the composition while the mount path kept them on an
unnamed timed element, so the producer parity test and the regression shard
failed on the first CI run.

Restore the contract: an anonymous host carries no composition id and its
flattened wrapper keeps the authored one. For #7505 that wrapper is already
the scope the probe gate (and `variableScope.ts`) resolves through, so the
inliner now keys an anonymous mount's merged defaults by the authored id
instead of skipping them. A named mount of the same file shares that scope;
its explicit instance values win regardless of inlining order, which the
replacement unit test pins in both orders. The id-reservation machinery for
claimed ids goes with the claim.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-11-16 18:58:41 +00:00
..
2026-11-16 15:15:30 +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