wehub-resource-sync
85453da49f
CodeQL / Analyze (javascript-typescript) (push) Waiting to run
Docs / Validate docs (push) Waiting to run
CodeQL / Analyze (actions) (push) Waiting to run
CodeQL / Analyze (python) (push) Waiting to run
Sync skills to ClawHub / Publish changed skills (push) Waiting to run
regression / regression-shards (style-16-prod style-9-prod style-17-prod iframe-render-compat variables-prod mp4-h265-sdr, shard-4) (push) Has been cancelled
regression / regression-shards (style-4-prod style-11-prod style-2-prod animejs-adapter typegpu-adapter parallel-capture-regression, shard-5) (push) Has been cancelled
regression / regression-shards (style-7-prod style-8-prod style-10-prod css-spinner-render-compat webm-transparency mp4-h264-sdr webm-vp9, shard-3) (push) Has been cancelled
regression / regression-shards (sub-composition-video style-18-prod raf-ball-render-compat font-variant-numeric sub-comp-t0 sub-comp-id-selector, shard-7) (push) Has been cancelled
Windows render verification / Detect changes (push) Has been cancelled
Windows render verification / Preflight (lint + format) (push) Has been cancelled
Windows render verification / Render on windows-latest (push) Has been cancelled
Windows render verification / Tests on windows-latest (push) Has been cancelled
CI / Detect changes (push) Has been cancelled
CI / Build (push) Has been cancelled
CI / Lint (push) Has been cancelled
CI / Fallow audit (push) Has been cancelled
CI / Format (push) Has been cancelled
CI / Typecheck (push) Has been cancelled
CI / Test (push) Has been cancelled
CI / Producer: integration tests (push) Has been cancelled
CI / Producer: unit tests (push) Has been cancelled
CI / File size check (push) Has been cancelled
CI / Test: skills (push) Has been cancelled
CI / Skills: manifest in sync (push) Has been cancelled
CI / CLI: npx shim (macos-latest) (push) Has been cancelled
CI / CLI: npx shim (ubuntu-latest) (push) Has been cancelled
CI / CLI: npx shim (windows-latest) (push) Has been cancelled
CI / SDK: unit + contract + smoke (push) Has been cancelled
CI / Test: runtime contract (push) Has been cancelled
CI / Studio: load smoke (push) Has been cancelled
CI / Smoke: global install (push) Has been cancelled
CI / CLI smoke (required) (push) Has been cancelled
CI / Semantic PR title (push) Has been cancelled
Player perf / Detect changes (push) Has been cancelled
Player perf / Preflight (lint + format) (push) Has been cancelled
Player perf / player-perf (push) Has been cancelled
Player perf / Perf: drift (push) Has been cancelled
Player perf / Perf: fps (push) Has been cancelled
Player perf / Perf: parity (push) Has been cancelled
Player perf / Perf: scrub (push) Has been cancelled
Player perf / Perf: load (push) Has been cancelled
preview-regression / Detect changes (push) Has been cancelled
preview-regression / Preflight (lint + format) (push) Has been cancelled
preview-regression / Preview parity (push) Has been cancelled
preview-regression / preview-regression (push) Has been cancelled
regression / regression (push) Has been cancelled
regression / Detect changes (push) Has been cancelled
regression / Preflight (lint + format) (push) Has been cancelled
regression / regression-shards (hdr-regression style-5-prod style-3-prod mov-prores, shard-1) (push) Has been cancelled
regression / regression-shards (overlay-montage-prod style-12-prod chat missing-host-comp-id png-sequence portrait-edge-bleed, shard-6) (push) Has been cancelled
regression / regression-shards (style-13-prod style-6-prod vignelli-stacking gsap-letters-render-compat audio-mux-parity, shard-8) (push) Has been cancelled
regression / regression-shards (style-15-prod hdr-hlg-regression style-1-prod many-cuts vfr-screen-recording render-symlinked-assets, shard-2) (push) Has been cancelled
454 lines
14 KiB
Plaintext
454 lines
14 KiB
Plaintext
---
|
|
title: "@hyperframes/core"
|
|
description: "Types, HTML generation, runtime, and linter — the foundation every other package depends on."
|
|
---
|
|
|
|
The core package provides the foundational types, HTML parsing/generation, runtime, and composition linter that all other Hyperframes packages build on. If you are building tooling, writing a custom integration, or extending Hyperframes itself, this is the package you need.
|
|
|
|
```bash
|
|
npm install @hyperframes/core
|
|
```
|
|
|
|
## When to Use
|
|
|
|
<Tip>
|
|
**Most users do not need to install `@hyperframes/core` directly.** The [CLI](/packages/cli), [producer](/packages/producer), and [studio](/packages/studio) packages all depend on core internally. You only need it if you are doing one of the things listed below.
|
|
</Tip>
|
|
|
|
**Use `@hyperframes/core` when you need to:**
|
|
- Lint compositions programmatically (CI pipelines, editor plugins)
|
|
- Parse HTML compositions into structured TypeScript objects
|
|
- Generate composition HTML from data (e.g., from an API or AI agent)
|
|
- Access the Hyperframes type system for your own tooling
|
|
- Embed the Hyperframes runtime in a custom player
|
|
|
|
**Use a different package if you want to:**
|
|
- Preview compositions in the browser — use the [CLI](/packages/cli) (`npx hyperframes preview`) or [studio](/packages/studio)
|
|
- Render compositions to MP4 — use the [CLI](/packages/cli) (`npx hyperframes render`) or [producer](/packages/producer)
|
|
- Capture frames from a headless browser — use the [engine](/packages/engine)
|
|
|
|
## Package Exports
|
|
|
|
The core package has four entry points:
|
|
|
|
| Import | Description |
|
|
|--------|-------------|
|
|
| `@hyperframes/core` | Types, parsers, generators, adapters, runtime utilities |
|
|
| `@hyperframes/core/lint` | Composition linter |
|
|
| `@hyperframes/core/compiler` | Timing compiler, HTML compiler, bundler, static guard |
|
|
| `@hyperframes/core/runtime` | Pre-built IIFE runtime for browser injection |
|
|
|
|
## Types
|
|
|
|
The core type system models compositions, timeline elements, and variables:
|
|
|
|
```typescript
|
|
import type {
|
|
TimelineElement,
|
|
TimelineMediaElement,
|
|
TimelineTextElement,
|
|
TimelineCompositionElement,
|
|
TimelineElementType, // "video" | "image" | "text" | "audio" | "composition"
|
|
CompositionSpec,
|
|
CompositionVariable,
|
|
CanvasResolution, // "landscape" | "portrait" | "landscape-4k" | "portrait-4k" | "square" | "square-4k"
|
|
Orientation, // "16:9" | "9:16"
|
|
FrameAdapter,
|
|
FrameAdapterContext,
|
|
} from '@hyperframes/core';
|
|
|
|
// Type guards
|
|
import {
|
|
isTextElement,
|
|
isMediaElement,
|
|
isCompositionElement,
|
|
} from '@hyperframes/core';
|
|
|
|
// Constants
|
|
import {
|
|
CANVAS_DIMENSIONS, // { landscape: { width, height }, portrait: { width, height } }
|
|
TIMELINE_COLORS,
|
|
DEFAULT_DURATIONS,
|
|
} from '@hyperframes/core';
|
|
```
|
|
|
|
### Variable Types
|
|
|
|
Compositions can expose typed variables for dynamic content:
|
|
|
|
```typescript
|
|
import type {
|
|
CompositionVariableType, // "string" | "number" | "color" | "boolean" | "enum"
|
|
StringVariable,
|
|
NumberVariable,
|
|
ColorVariable,
|
|
BooleanVariable,
|
|
EnumVariable,
|
|
} from '@hyperframes/core';
|
|
```
|
|
|
|
### Keyframe Types
|
|
|
|
```typescript
|
|
import type {
|
|
Keyframe,
|
|
KeyframeProperties,
|
|
ElementKeyframes,
|
|
StageZoom,
|
|
StageZoomKeyframe,
|
|
} from '@hyperframes/core';
|
|
|
|
import { getDefaultStageZoom } from '@hyperframes/core';
|
|
```
|
|
|
|
## Parsing and Generating HTML
|
|
|
|
Round-trip between HTML and structured data:
|
|
|
|
```typescript
|
|
import { parseHtml, generateHyperframesHtml } from '@hyperframes/core';
|
|
import type { ParsedHtml, CompositionMetadata } from '@hyperframes/core';
|
|
|
|
// Parse HTML into structured data
|
|
const parsed: ParsedHtml = parseHtml(htmlString);
|
|
// parsed.elements, parsed.gsapScript, parsed.styles, parsed.resolution, parsed.keyframes
|
|
|
|
// Extract composition metadata
|
|
import { extractCompositionMetadata } from '@hyperframes/core';
|
|
const meta: CompositionMetadata = extractCompositionMetadata(htmlString);
|
|
// meta.id, meta.duration, meta.width, meta.height, meta.variables
|
|
//
|
|
// Variable metadata is declared on the document root, for example:
|
|
// <html
|
|
// data-composition-id="card"
|
|
// data-composition-duration="3"
|
|
// data-composition-variables='[{"id":"title","label":"Title","type":"string","default":"Hello"}]'
|
|
// >
|
|
|
|
// Read resolved variables inside a composition (declared defaults +
|
|
// CLI overrides + per-instance host data-variable-values):
|
|
import { getVariables } from '@hyperframes/core';
|
|
const { title } = getVariables<{ title: string }>();
|
|
|
|
// Validate CLI / host overrides against the declared schema:
|
|
import { validateVariables, formatVariableValidationIssue } from '@hyperframes/core';
|
|
const issues = validateVariables({ title: 'Hello', count: 'three' }, meta.variables);
|
|
for (const issue of issues) {
|
|
console.warn(formatVariableValidationIssue(issue));
|
|
}
|
|
|
|
// Generate HTML from structured data
|
|
const html = generateHyperframesHtml(elements, {
|
|
animations,
|
|
styles,
|
|
resolution: 'landscape',
|
|
compositionId: 'my-video',
|
|
});
|
|
```
|
|
|
|
### Modifying HTML
|
|
|
|
```typescript
|
|
import {
|
|
updateElementInHtml,
|
|
addElementToHtml,
|
|
removeElementFromHtml,
|
|
validateCompositionHtml,
|
|
} from '@hyperframes/core';
|
|
|
|
// Update an element's properties
|
|
const updatedHtml = updateElementInHtml(html, 'el-1', { start: 5 });
|
|
|
|
// Add a new element
|
|
const newHtml = addElementToHtml(html, newElement);
|
|
|
|
// Remove an element
|
|
const cleanHtml = removeElementFromHtml(html, 'el-1');
|
|
|
|
// Validate HTML structure
|
|
const result = validateCompositionHtml(html);
|
|
// result.valid, result.errors
|
|
```
|
|
|
|
### GSAP Script Parsing
|
|
|
|
<Info>
|
|
The GSAP + HTML parsing layer now lives in its own standalone package, [`@hyperframes/parsers`](/packages/parsers). Core re-exports the API below for back-compat; import from `@hyperframes/parsers` directly in new code.
|
|
</Info>
|
|
|
|
```typescript
|
|
import {
|
|
serializeGsapAnimations,
|
|
getAnimationsForElementId,
|
|
validateCompositionGsap,
|
|
keyframesToGsapAnimations,
|
|
gsapAnimationsToKeyframes,
|
|
} from '@hyperframes/core';
|
|
|
|
// GSAP parsing, mutation, and constants live in @hyperframes/parsers:
|
|
import { parseGsapScript, SUPPORTED_PROPS, SUPPORTED_EASES } from '@hyperframes/parsers/gsap-parser';
|
|
import { updateAnimationInScript, addAnimationToScript, removeAnimationFromScript } from '@hyperframes/parsers/gsap-writer-acorn';
|
|
import type { GsapAnimation, GsapMethod, ParsedGsap } from '@hyperframes/core';
|
|
|
|
// Parse GSAP script into structured animations
|
|
const parsed: ParsedGsap = parseGsapScript(scriptContent);
|
|
// parsed.animations, parsed.timelineVar, parsed.preamble, parsed.postamble
|
|
|
|
// Serialize back to script
|
|
const script = serializeGsapAnimations(parsed.animations);
|
|
```
|
|
|
|
### HTML Generation
|
|
|
|
```typescript
|
|
import {
|
|
generateHyperframesHtml,
|
|
generateGsapTimelineScript,
|
|
generateHyperframesStyles,
|
|
} from '@hyperframes/core';
|
|
|
|
// Generate a complete HTML composition
|
|
const html = generateHyperframesHtml(elements, options);
|
|
|
|
// Generate just the GSAP script
|
|
const script = generateGsapTimelineScript(animations, options);
|
|
|
|
// Generate CSS styles
|
|
const { coreCss, customCss, googleFontsLink } = generateHyperframesStyles(
|
|
elements, 'landscape', customStyles
|
|
);
|
|
```
|
|
|
|
### Template Utilities
|
|
|
|
```typescript
|
|
import {
|
|
generateBaseHtml,
|
|
getStageStyles,
|
|
GSAP_CDN,
|
|
BASE_STYLES,
|
|
ELEMENT_BASE_STYLES,
|
|
MEDIA_STYLES,
|
|
TEXT_STYLES,
|
|
ZOOM_CONTAINER_STYLES,
|
|
} from '@hyperframes/core';
|
|
|
|
// Generate base HTML structure for a resolution
|
|
const baseHtml = generateBaseHtml('landscape');
|
|
const styles = getStageStyles('portrait');
|
|
```
|
|
|
|
## Linter
|
|
|
|
<Info>
|
|
The composition linter now lives in its own package, [`@hyperframes/lint`](/packages/lint) — install it directly to lint a project or HTML string from Node without the CLI. `@hyperframes/core/lint` remains a back-compat re-export.
|
|
</Info>
|
|
|
|
The composition linter checks for structural issues that would cause rendering failures or unexpected behavior. You can run it from the CLI with `npx hyperframes lint`, or call it programmatically:
|
|
|
|
```typescript
|
|
import { lintHyperframeHtml, lintMediaUrls } from '@hyperframes/core/lint';
|
|
import type {
|
|
HyperframeLintResult,
|
|
HyperframeLintFinding,
|
|
HyperframeLintSeverity, // "error" | "warning" | "info"
|
|
HyperframeLinterOptions,
|
|
} from '@hyperframes/core/lint';
|
|
|
|
const result: HyperframeLintResult = lintHyperframeHtml(html, { filePath: 'index.html' });
|
|
// result.ok, result.errorCount, result.warningCount, result.findings
|
|
|
|
for (const finding of result.findings) {
|
|
console.log(finding.severity, finding.code, finding.message);
|
|
// finding.file, finding.selector, finding.elementId, finding.fixHint, finding.snippet
|
|
}
|
|
|
|
// Additional media URL validation
|
|
const mediaFindings = lintMediaUrls(result.findings);
|
|
```
|
|
|
|
Detected issues include:
|
|
|
|
- Missing timeline registration (`window.__timelines`)
|
|
- Unmuted video elements (causes autoplay failures)
|
|
- Missing `class="clip"` on timed visible elements
|
|
- Deprecated attribute names
|
|
- Missing composition dimensions (`data-width`, `data-height`)
|
|
- Invalid `data-start` references to nonexistent clip IDs
|
|
|
|
<Info>
|
|
For a full list of what the linter catches and how to fix each issue, see [Common Mistakes](/guides/common-mistakes) and [Troubleshooting](/guides/troubleshooting).
|
|
</Info>
|
|
|
|
## Compiler
|
|
|
|
The compiler sub-package handles timing resolution, HTML compilation, and bundling:
|
|
|
|
```typescript
|
|
// Timing compiler (browser-safe — no Node.js dependencies)
|
|
import {
|
|
compileTimingAttrs,
|
|
injectDurations,
|
|
extractResolvedMedia,
|
|
clampDurations,
|
|
} from '@hyperframes/core/compiler';
|
|
import type {
|
|
UnresolvedElement,
|
|
ResolvedDuration,
|
|
ResolvedMediaElement,
|
|
CompilationResult,
|
|
} from '@hyperframes/core/compiler';
|
|
|
|
// Compile timing attributes from HTML
|
|
const compiled: CompilationResult = compileTimingAttrs(html);
|
|
|
|
// Inject resolved durations back into HTML
|
|
const updatedHtml = injectDurations(html, compiled.durations);
|
|
|
|
// Extract resolved media elements
|
|
const media: ResolvedMediaElement[] = extractResolvedMedia(html);
|
|
```
|
|
|
|
```typescript
|
|
// HTML compiler (Node.js — requires media probing)
|
|
import { compileHtml } from '@hyperframes/core/compiler';
|
|
import type { MediaDurationProber } from '@hyperframes/core/compiler';
|
|
|
|
const prober: MediaDurationProber = async (src) => getDuration(src);
|
|
const compiledHtml = await compileHtml(html, prober);
|
|
```
|
|
|
|
```typescript
|
|
// HTML bundler (Node.js — bundles to single file)
|
|
import { bundleToSingleHtml } from '@hyperframes/core/compiler';
|
|
import type { BundleOptions } from '@hyperframes/core/compiler';
|
|
|
|
const bundled = await bundleToSingleHtml({ entryPath: './index.html', inline: true });
|
|
```
|
|
|
|
```typescript
|
|
// Static guard — validate HTML contract
|
|
import { validateHyperframeHtmlContract } from '@hyperframes/core/compiler';
|
|
import type {
|
|
HyperframeStaticGuardResult,
|
|
HyperframeStaticFailureReason,
|
|
} from '@hyperframes/core/compiler';
|
|
|
|
const guard: HyperframeStaticGuardResult = validateHyperframeHtmlContract(html);
|
|
// guard.ok, guard.failures[]
|
|
// Failure reasons: "missing_composition_id" | "missing_composition_dimensions"
|
|
// | "missing_timeline_registry" | "invalid_script_syntax"
|
|
// | "invalid_static_hyperframe_contract"
|
|
```
|
|
|
|
## Runtime
|
|
|
|
The Hyperframes runtime manages playback, seeking, and clip lifecycle in the browser. The core package provides utilities for building and loading the runtime:
|
|
|
|
```typescript
|
|
import {
|
|
loadHyperframeRuntimeSource,
|
|
buildHyperframesRuntimeScript,
|
|
HYPERFRAME_RUNTIME_ARTIFACTS,
|
|
HYPERFRAME_RUNTIME_CONTRACT,
|
|
HYPERFRAME_RUNTIME_GLOBALS,
|
|
HYPERFRAME_BRIDGE_SOURCES,
|
|
HYPERFRAME_CONTROL_ACTIONS,
|
|
} from '@hyperframes/core';
|
|
import type {
|
|
HyperframeControlAction,
|
|
HyperframesRuntimeBuildOptions,
|
|
} from '@hyperframes/core';
|
|
|
|
// Load the pre-built runtime IIFE
|
|
const runtimeSource = loadHyperframeRuntimeSource();
|
|
|
|
// Build a custom runtime script
|
|
const script = buildHyperframesRuntimeScript(options);
|
|
```
|
|
|
|
The pre-built runtime IIFE is available as a direct import:
|
|
|
|
```typescript
|
|
import runtime from '@hyperframes/core/runtime';
|
|
```
|
|
|
|
## Frame Adapters
|
|
|
|
The core package defines the [Frame Adapter](/concepts/frame-adapters) interface and provides the built-in GSAP adapter:
|
|
|
|
```typescript
|
|
import { createGSAPFrameAdapter } from '@hyperframes/core';
|
|
import type {
|
|
FrameAdapter,
|
|
FrameAdapterContext,
|
|
GSAPTimelineLike,
|
|
CreateGSAPFrameAdapterOptions,
|
|
} from '@hyperframes/core';
|
|
|
|
// Create a GSAP frame adapter
|
|
const adapter: FrameAdapter = createGSAPFrameAdapter({
|
|
id: 'my-composition',
|
|
fps: 30,
|
|
timeline: gsapTimeline,
|
|
});
|
|
|
|
// Adapter lifecycle
|
|
await adapter.init?.(context);
|
|
const durationFrames = adapter.getDurationFrames();
|
|
await adapter.seekFrame(42);
|
|
await adapter.destroy?.();
|
|
```
|
|
|
|
## Media Utilities
|
|
|
|
```typescript
|
|
import {
|
|
MEDIA_VISUAL_STYLE_PROPERTIES,
|
|
copyMediaVisualStyles,
|
|
quantizeTimeToFrame,
|
|
} from '@hyperframes/core';
|
|
import type { MediaVisualStyleProperty } from '@hyperframes/core';
|
|
|
|
// Quantize a time value to the nearest frame boundary
|
|
const frameTime = quantizeTimeToFrame(5.033, 30); // → 5.033... snapped to frame
|
|
|
|
// Copy visual styles between media elements
|
|
copyMediaVisualStyles(fromElement, toElement);
|
|
```
|
|
|
|
## Picker API
|
|
|
|
For element selection in editor UIs:
|
|
|
|
```typescript
|
|
import type {
|
|
HyperframePickerApi,
|
|
HyperframePickerBoundingBox,
|
|
HyperframePickerElementInfo,
|
|
} from '@hyperframes/core';
|
|
```
|
|
|
|
## Related Packages
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="@hyperframes/parsers" icon="code" href="/packages/parsers">
|
|
The standalone GSAP + HTML parsing layer extracted from core.
|
|
</Card>
|
|
<Card title="@hyperframes/lint" icon="circle-check" href="/packages/lint">
|
|
The composition linter as a standalone library.
|
|
</Card>
|
|
<Card title="@hyperframes/studio-server" icon="server" href="/packages/studio-server">
|
|
The mountable studio preview/editor backend.
|
|
</Card>
|
|
<Card title="CLI" icon="terminal" href="/packages/cli">
|
|
The easiest way to create, preview, lint, and render compositions.
|
|
</Card>
|
|
<Card title="Engine" icon="gear" href="/packages/engine">
|
|
Low-level frame capture pipeline that uses core types and runtime.
|
|
</Card>
|
|
<Card title="Producer" icon="film" href="/packages/producer">
|
|
Full rendering pipeline built on top of core and engine.
|
|
</Card>
|
|
</CardGroup>
|