> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes-codex-docs-human-first-refactor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# @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](/developers/cli), [Studio](/studio), or
[SDK](/sdk/overview). Install Core directly when you are generating composition
HTML, compiling projects, building tooling around the shared types, or embedding
the runtime.

```bash theme={null}
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](/packages/parsers) and [Linter](/packages/lint)
packages own those concerns for new integrations. Core retains compatibility
re-exports for some older imports.

## Types

```ts theme={null}
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:

```ts theme={null}
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:

```ts theme={null}
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

```ts theme={null}
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.

```ts theme={null}
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

```ts theme={null}
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`](/packages/lint)
or run `npx hyperframes lint`.

## Build a frame adapter

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

```ts theme={null}
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);
```

<CardGroup cols={2}>
  <Card title="Composition schema" icon="code" href="/reference/html-schema">
    Learn the HTML contract that Core reads and writes.
  </Card>

  <Card title="@hyperframes/parsers" icon="brackets-curly" href="/packages/parsers">
    Work directly with HTML and GSAP parsing.
  </Card>

  <Card title="@hyperframes/lint" icon="circle-check" href="/packages/lint">
    Validate composition HTML in your own tooling.
  </Card>

  <Card title="@hyperframes/producer" icon="video" href="/packages/producer">
    Turn a project into a finished video from Node.js.
  </Card>
</CardGroup>