@hyperframes/core

Composition types, generation, compilation, and browser runtime.

@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.

Read and validate variables

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

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

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

getVariables() merges declared defaults with render-time and sub-composition overrides.

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.