@hyperframes/parsers - HyperFrames

The parsers package is the standalone foundation extracted from core. It owns the GSAP animation parser/writer (recast and acorn implementations), the HTML composition parser, hf-id stamping, and spring-ease generation. It has no @hyperframes/* dependencies, so it’s the base every other package builds on.

npm install @hyperframes/parsers

When to Use

Most users do not need to install @hyperframes/parsers directly. @hyperframes/core re-exports the parser API it needs, and the CLI / studio depend on it transitively. Reach for it directly only when you want the parsing layer without pulling in the rest of core.

Use @hyperframes/parsers when you need to:

Parse HTML compositions into structured TypeScript objects
Parse, edit, and re-serialize GSAP timeline scripts (AST round-trip)
Stamp deterministic hf-id attributes onto a document
Build tooling that touches the parsing layer but doesn’t need core’s runtime, compiler, or generators

Package Exports

Import	Description
`@hyperframes/parsers`	HTML parser, GSAP serialize/validate helpers, hf-ids, shared types
`@hyperframes/parsers/gsap-parser`	GSAP parser exports, `parseGsapScript`, `SUPPORTED_PROPS`, `SUPPORTED_EASES`
`@hyperframes/parsers/gsap-parser-acorn`	Acorn-based GSAP parser (browser-safe, read path)
`@hyperframes/parsers/gsap-writer-acorn`	Acorn-based GSAP writer (mutation helpers)
`@hyperframes/parsers/gsap-parser-recast`	Recast-based GSAP parser/writer (legacy implementation)
`@hyperframes/parsers/gsap-constants`	`SUPPORTED_PROPS`, `SUPPORTED_EASES`, property groups
`@hyperframes/parsers/spring-ease`	Spring-ease curve generation
`@hyperframes/parsers/hf-ids`	Deterministic element id stamping
`@hyperframes/parsers/slideshow`	Slideshow manifest parser (`parseSlideshowManifest`, `resolveSlideshow`)
`@hyperframes/parsers/composition`	Pure, browser-safe composition primitives (data types, font aliases, URL helper)
`@hyperframes/parsers/asset-paths`	Node-only asset-path rewriting helpers (`rewriteAssetPath`, …)
`@hyperframes/parsers/sub-composition-validity`	Sub-composition validation utilities

The package ships subpath entries so consumers tree-shake to what they use — importing @hyperframes/parsers/hf-ids (a couple KB) does not pull in the GSAP AST machinery (recast/babel/acorn).

HTML Parsing

Round-trip between HTML and structured data:

import {
  parseHtml,
  extractCompositionMetadata,
  validateCompositionHtml,
} from '@hyperframes/parsers';
import type { ParsedHtml, CompositionMetadata } from '@hyperframes/parsers';

// Parse HTML into structured data
const parsed: ParsedHtml = parseHtml(htmlString);
// parsed.elements, parsed.gsapScript, parsed.styles, parsed.resolution, parsed.keyframes

// Extract composition metadata (id, duration, dimensions, variables)
const meta: CompositionMetadata = extractCompositionMetadata(htmlString);

// Validate HTML structure
const result = validateCompositionHtml(htmlString);
// result.valid, result.errors

Modifying HTML

import {
  updateElementInHtml,
  addElementToHtml,
  removeElementFromHtml,
} from '@hyperframes/parsers';

const updated = updateElementInHtml(html, 'el-1', { start: 5 });
const added = addElementToHtml(html, newElement);
const cleaned = removeElementFromHtml(html, 'el-1');

GSAP Script Parsing

The acorn parser/writer is the primary path (browser-safe). Parse a timeline script, mutate it, and serialize it back without losing surrounding code:

import { parseGsapScriptAcorn, extractGsapLabels } from '@hyperframes/parsers/gsap-parser-acorn';
import {
  updateAnimationInScript,
  addAnimationToScript,
  removeAnimationFromScript,
  updateKeyframeInScript,
  addKeyframeToScript,
  shiftPositionsInScript,
  scalePositionsInScript,
} from '@hyperframes/parsers/gsap-writer-acorn';
import type { GsapAnimation, GsapMethod, ParsedGsap } from '@hyperframes/parsers';

const parsed: ParsedGsap = parseGsapScriptAcorn(scriptContent);
// parsed.animations, parsed.timelineVar, parsed.preamble, parsed.postamble

// Mutation helpers operate on the script text and preserve unrelated code
const next = updateAnimationInScript(scriptContent, animationId, { duration: 2 });

High-level serialize / validate / keyframe-conversion helpers are on the main entry:

import {
  serializeGsapAnimations,
  getAnimationsForElementId,
  validateCompositionGsap,
  keyframesToGsapAnimations,
  gsapAnimationsToKeyframes,
} from '@hyperframes/parsers';

GSAP Constants

import {
  SUPPORTED_PROPS,    // animatable properties
  SUPPORTED_EASES,    // available easing functions
  PROPERTY_GROUPS,
} from '@hyperframes/parsers/gsap-constants';
import type { PropertyGroupName } from '@hyperframes/parsers/gsap-constants';

hf-ids

Deterministic element identity for stable diffing and editing:

import { ensureHfIds, mintHfId } from '@hyperframes/parsers/hf-ids';

// Stamp hf-id attributes onto every editable element in a document
const withIds = ensureHfIds(htmlString);

Spring Ease

import { generateSpringEaseData, SPRING_PRESETS } from '@hyperframes/parsers/spring-ease';

@hyperframes/core

Types, generators, runtime, and compiler — re-exports the parser API it needs.

@hyperframes/lint

The composition linter, built on the parsers.

@hyperframes/studio-server

The studio preview server, built on the parsers.

CLI

Create, preview, lint, and render compositions.

​When to Use

​Package Exports

​HTML Parsing

​Modifying HTML

​GSAP Script Parsing

​GSAP Constants

​hf-ids

​Spring Ease

​Related Packages

@hyperframes/core

@hyperframes/lint

@hyperframes/studio-server

CLI

When to Use

Package Exports

HTML Parsing

Modifying HTML

GSAP Script Parsing

GSAP Constants

hf-ids

Spring Ease

Related Packages