Skip to main content
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

ImportDescription
@hyperframes/parsersHTML parser, GSAP serialize/validate helpers, hf-ids, shared types
@hyperframes/parsers/gsap-parser-acornAcorn-based GSAP parser (browser-safe, read path)
@hyperframes/parsers/gsap-writer-acornAcorn-based GSAP writer (mutation helpers)
@hyperframes/parsers/gsap-parser-recastRecast-based GSAP parser/writer (legacy implementation)
@hyperframes/parsers/gsap-constantsSUPPORTED_PROPS, SUPPORTED_EASES, property groups
@hyperframes/parsers/spring-easeSpring-ease curve generation
@hyperframes/parsers/hf-idsDeterministic element id stamping
@hyperframes/parsers/slideshowSlideshow manifest parser (parseSlideshowManifest, resolveSlideshow)
@hyperframes/parsers/compositionPure, browser-safe composition primitives (data types, font aliases, URL helper)
@hyperframes/parsers/asset-pathsNode-only asset-path rewriting helpers (rewriteAssetPath, …)
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.