> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes.heygen.com/llms.txt
> Use this file to discover all available pages before exploring further.

# @hyperframes/parsers

> The GSAP + HTML parser/writer suite — standalone, zero @hyperframes/* dependencies.

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.

```bash theme={null}
npm install @hyperframes/parsers
```

## When to Use

<Tip>
  **Most users do not need to install `@hyperframes/parsers` directly.** [`@hyperframes/core`](/packages/core) re-exports the parser API it needs, and the [CLI](/packages/cli) / [studio](/packages/studio) depend on it transitively. Reach for it directly only when you want the parsing layer **without** pulling in the rest of core.
</Tip>

**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-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`, …)                   |

<Info>
  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).
</Info>

## HTML Parsing

Round-trip between HTML and structured data:

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

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

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

```typescript theme={null}
import {
  serializeGsapAnimations,
  getAnimationsForElementId,
  validateCompositionGsap,
  keyframesToGsapAnimations,
  gsapAnimationsToKeyframes,
} from '@hyperframes/parsers';
```

### GSAP Constants

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

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

```typescript theme={null}
import { generateSpringEaseData, SPRING_PRESETS } from '@hyperframes/parsers/spring-ease';
```

## Related Packages

<CardGroup cols={2}>
  <Card title="@hyperframes/core" icon="cube" href="/packages/core">
    Types, generators, runtime, and compiler — re-exports the parser API it needs.
  </Card>

  <Card title="@hyperframes/lint" icon="circle-check" href="/packages/lint">
    The composition linter, built on the parsers.
  </Card>

  <Card title="@hyperframes/studio-server" icon="server" href="/packages/studio-server">
    The studio preview server, built on the parsers.
  </Card>

  <Card title="CLI" icon="terminal" href="/packages/cli">
    Create, preview, lint, and render compositions.
  </Card>
</CardGroup>