* feat(studio): drag and resize on an opaque preview start from one gesture-start read A gesture on a preview frame Studio cannot script read nothing from the frame as it started. A drag snapped to nothing; a layer GSAP holds moved by a CSS translate that its save then dropped; a resize grew from the overlay rect, the layer's GSAP scale included; and the pointer reached the element only through the canvas zoom. The runtime answers a new `gesture-start` request. For each pressed element it gives the overlay geometry, the transform-free layout size, how far the centre moves per px of translate (probed the way a draft draws it, every transform above it applied), and GSAP's x/y when GSAP owns its position, with whether a tween moves it. It also lists the boxes of the page the gesture can snap to, walked by the rule Studio's own snap collection now takes from core. On an opaque preview every press waits for that one read, on the existing waiting-press path, and the gesture starts from it: the snap targets, the move route and GSAP base (so the save writes GSAP's x plus the drag, not the drag alone), the pointer-to-offset matrix, and the resize's base size. A layer a tween moves is refused with a notice, since saving that move still reads the frame. Same-origin frames do not change: their presses start at once from the element, and their snap collection walks the same elements by the same rule. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(inspector): raise the packed size budget for the gesture-start runtime The inspector bundles core's preview runtime. Main alone packs to 866206 bytes, 420 under the 1% tolerance on the old 858046 budget; the gesture-start request adds 713 bytes (866919), which tipped the merge queue's Build over. Set the budget to 880000 to leave room for the remaining opaque-preview requests. 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