@hyperframes/core

@hyperframes/core contains the shared composition model and browser runtime used across HyperFrames. Most people should use the CLI, Studio, or SDK. Install Core directly when you are generating composition HTML, compiling projects, building tooling around the shared types, or embedding the runtime.

npm install @hyperframes/core

Main surfaces

Need	Import
Types, generators, and common utilities	`@hyperframes/core`
Timing compilation and project bundling	`@hyperframes/core/compiler`
Variable declarations and validation	`@hyperframes/core/variables`
Composition contract helpers	`@hyperframes/core/composition-contract`
Prebuilt browser runtime	`@hyperframes/core/runtime`

The standalone Parsers and Linter packages own those concerns for new integrations. Core retains compatibility re-exports for some older imports.

Types

import type {
  CanvasResolution,
  CompositionSpec,
  CompositionVariable,
  TimelineCompositionElement,
  TimelineElement,
  TimelineMediaElement,
  TimelineTextElement,
} from "@hyperframes/core";

Composition variables support string, number, color, boolean, enum, font, and image values.

Parse or generate HTML

Core re-exports the common parsing helpers:

import { extractCompositionMetadata, parseHtml } from "@hyperframes/core";

const parsed = parseHtml(html);
const metadata = extractCompositionMetadata(html);

console.log(metadata.compositionId, metadata.compositionDuration, metadata.variables);

Generate a complete composition from TimelineElement data:

import { generateHyperframesHtml } from "@hyperframes/core";

const html = generateHyperframesHtml(elements, 6, {
  compositionId: "product-intro",
  resolution: "landscape",
  animations,
  styles,
});

The second argument is the requested duration in seconds. Pass a stable compositionId when output must be reproducible. 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.

Read and validate variables

Inside a composition script, getVariables() reads declared defaults plus the values supplied for the current preview or render:

import { getVariables } from "@hyperframes/core";

const { title } = getVariables<{ title: string }>();

In Node tooling, validate a values object against declarations parsed from the composition:

import { formatVariableValidationIssue, validateVariables } from "@hyperframes/core";

const issues = validateVariables({ title: "Launch day" }, metadata.variables);

for (const issue of issues) {
  console.warn(formatVariableValidationIssue(issue));
}

Compile a project

Use the compiler entry when your integration needs resolved media timing or a single bundled document.

import { bundleToSingleHtml, compileHtml } from "@hyperframes/core/compiler";

const compiled = await compileHtml(rawHtml, "./project", async (mediaPath) =>
  probeDuration(mediaPath),
);

const bundled = await bundleToSingleHtml("./project", {
  entryFile: "index.html",
});

The compiler also exposes lower-level timing helpers such as compileTimingAttrs(), injectDurations(), and extractResolvedMedia().

Check the static contract

import { validateHyperframeHtmlContract } from "@hyperframes/core/compiler";

const result = await validateHyperframeHtmlContract(html);

if (!result.isValid) {
  console.error(result.missingKeys);
}

For the full composition lint result, use @hyperframes/lint or run npx hyperframes lint.

Build a frame adapter

Frame adapters make an animation runtime seekable by frame. Core includes the GSAP adapter:

import { createGSAPFrameAdapter } from "@hyperframes/core";

const adapter = createGSAPFrameAdapter({
  id: "product-intro",
  fps: 30,
  timeline,
});

await adapter.init?.({
  compositionId: "product-intro",
  fps: 30,
  width: 1920,
  height: 1080,
});

await adapter.seekFrame(42);

Composition schema

Learn the HTML contract that Core reads and writes.

@hyperframes/parsers

Work directly with HTML and GSAP parsing.

@hyperframes/lint

Validate composition HTML in your own tooling.

@hyperframes/producer

Turn a project into a finished video from Node.js.

Start here

Command line

SDK guides

SDK reference

Composition, design & animation

Composition reference

Rendering paths

Cloud infrastructure

Advanced rendering

Packages

Agent setup

Contributing & community

Main surfaces

Types

Parse or generate HTML

Read and validate variables

Compile a project

Check the static contract

Build a frame adapter

Composition schema

@hyperframes/parsers

@hyperframes/lint

@hyperframes/producer

​Main surfaces

​Types

​Parse or generate HTML

​Read and validate variables

​Compile a project

​Check the static contract

​Build a frame adapter

​Related topics

Composition schema

@hyperframes/parsers

@hyperframes/lint

@hyperframes/producer

Main surfaces

Types

Parse or generate HTML

Read and validate variables

Compile a project

Check the static contract

Build a frame adapter

Related topics