@hyperframes/核心

核心包提供了所有其他 Hyperframes 包构建的基础类型、HTML 解析/生成、运行时和组合 linter。如果您正在构建工具、编写自定义集成或扩展 Hyperframes 本身，那么这就是您需要的包。

npm install @hyperframes/core

何时使用

大多数用户不需要直接安装 @hyperframes/core。 CLI、生产者和 studio 包都内部依赖于 core。仅当您执行下列操作之一时才需要它。

当您需要时使用 @hyperframes/core：

以编程方式进行 Lint 组合（CI 管道、编辑器插件）
将 HTML 组合解析为结构化 TypeScript 对象
从数据（例如，从 API 或 AI 代理）生成合成 HTML
访问用于您自己的工具的 Hyperframes 类型系统
将 Hyperframes 运行时嵌入自定义播放器

如果您愿意，请使用不同的包：

在浏览器中预览合成 — 使用 CLI (npx hyperframes preview) 或 studio
将合成渲染为 MP4 — 使用 CLI (npx hyperframes render) 或生产者
从无头浏览器捕获帧 - 使用 engine

包裹出口

核心包有四个入口点：

进口	描述
`@hyperframes/core`	类型、解析器、生成器、适配器、运行时实用程序
`@hyperframes/core/lint`	组合短绒
`@hyperframes/core/compiler`	时序编译器、HTML 编译器、捆绑器、静态防护
`@hyperframes/core/runtime`	用于浏览器注入的预构建 IIFE 运行时

类型

核心类型系统对组合、时间线元素和变量进行建模：

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,
  isStringVariable,
  isNumberVariable,
  isColorVariable,
  isBooleanVariable,
  isEnumVariable,
} from '@hyperframes/core';

// Constants
import {
  CANVAS_DIMENSIONS,        // { landscape: { width, height }, portrait: { width, height } }
  TIMELINE_COLORS,
  DEFAULT_DURATIONS,
} from '@hyperframes/core';

变量类型

组合可以公开动态内容的类型化变量：

import type {
  CompositionVariableType,   // "string" | "number" | "color" | "boolean" | "enum"
  StringVariable,
  NumberVariable,
  ColorVariable,
  BooleanVariable,
  EnumVariable,
} from '@hyperframes/core';

关键帧类型

import type {
  Keyframe,
  KeyframeProperties,
  ElementKeyframes,
  StageZoom,
  StageZoomKeyframe,
} from '@hyperframes/core';

import { getDefaultStageZoom } from '@hyperframes/core';

解析和生成 HTML

HTML 和结构化数据之间的往返：

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',
});

修改 HTML

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脚本解析

import {
  parseGsapScript,
  serializeGsapAnimations,
  updateAnimationInScript,
  addAnimationToScript,
  removeAnimationFromScript,
  getAnimationsForElement,
  validateCompositionGsap,
  keyframesToGsapAnimations,
  gsapAnimationsToKeyframes,
  SUPPORTED_PROPS,            // animatable properties
  SUPPORTED_EASES,            // available easing functions
} from '@hyperframes/core';
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 生成

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
);

模板实用程序

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');

短绒

组合检查会检查可能导致渲染失败或意外行为的结构问题。您可以使用 npx hyperframes lint 从 CLI 运行它，或以编程方式调用它：

import { lintHyperframeHtml, lintMediaUrls } from '@hyperframes/core/lint';
import type {
  HyperframeLintResult,
  HyperframeLintFinding,
  HyperframeLintSeverity,     // "error" | "warning"
  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);

检测到的问题包括：

缺少时间表注册 (window.__timelines)
未静音的视频元素（导致自动播放失败）
定时可见元素上缺少 class="clip"
已弃用的属性名称
缺少组合维度（data-width、data-height）
对不存在的剪辑 ID 的无效 data-start 引用

有关 linter 捕获的内容以及如何解决每个问题的完整列表，请参阅常见错误和故障排除。

编译器

编译器子包处理时序解析、HTML 编译和捆绑：

// 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);

// 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);

// 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 });

// 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"

运行时

Hyperframes 运行时管理浏览器中的播放、搜索和剪辑生命周期。核心包提供了用于构建和加载运行时的实用程序：

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);

预构建的运行时 IIFE 可直接导入：

import runtime from '@hyperframes/core/runtime';

框架适配器

核心包定义了Frame Adapter接口并提供了内置的GSAP适配器：

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?.();

媒体实用程序

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);

选取器API

对于编辑器 UI 中的元素选择：

import type {
  HyperframePickerApi,
  HyperframePickerBoundingBox,
  HyperframePickerElementInfo,
} from '@hyperframes/core';

命令行界面

创建、预览、检查和渲染合成的最简单方法。

引擎

使用核心类型和运行时的低级帧捕获管道。

制片人

完整的渲染管道构建在核心和引擎之上。

工作室

嵌入核心运行时进行预览的可视化合成编辑器。

Packages

何时使用

包裹出口

类型

变量类型

关键帧类型

解析和生成 HTML

修改 HTML

GSAP脚本解析

HTML 生成

模板实用程序

短绒

编译器

运行时

框架适配器

媒体实用程序

选取器API

相关套餐

命令行界面

引擎

制片人

工作室

​何时使用

​包裹出口

​类型

​变量类型

​关键帧类型

​解析和生成 HTML

​修改 HTML

​GSAP脚本解析

​HTML 生成

​模板实用程序

​短绒

​编译器

​运行时

​框架适配器

​媒体实用程序

​选取器API

​相关套餐

命令行界面

引擎

制片人

工作室

何时使用

包裹出口

类型

变量类型

关键帧类型

解析和生成 HTML

修改 HTML

GSAP脚本解析

HTML 生成

模板实用程序

短绒

编译器

运行时

框架适配器

媒体实用程序

选取器API

相关套餐