mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-03 12:54:29 +00:00
Vance Ingalls
bd27ea31ad
The #1817 deploy added 15 pages but Mintlify only published changed files
incrementally; the 14 unmodified pages 404'd on production while
editing-affordances (touched in 9140ee51b) deployed fine. Trailing-newline
touch forces Mintlify to re-emit all SDK pages.
80 lines
4.8 KiB
Plaintext
80 lines
4.8 KiB
Plaintext
---
|
|
title: "SDK Overview"
|
|
description: "Headless, framework-neutral composition editing engine — query, mutate, patch, and persist without a browser UI."
|
|
---
|
|
|
|
`@hyperframes/sdk` is the editing engine inside HyperFrames Studio and the CLI. It opens composition HTML, exposes query and mutation APIs, emits RFC 6902 JSON patches, tracks undo/redo, and persists changes through pluggable adapters — all without requiring React, Studio, or a browser UI.
|
|
|
|
```bash
|
|
npm install @hyperframes/sdk
|
|
```
|
|
|
|
## Mental model
|
|
|
|
**Every edit targets a stable `hf-id`.** The SDK stamps all elements with `data-hf-id` identifiers before any query or mutation runs. This means edits never depend on mouse state or a UI selection — agents and backend jobs operate on the same surface as a Studio user.
|
|
|
|
**Typed methods are sugar over `dispatch()`.** `comp.setText("hf-title", "Hello")` is exactly equivalent to `comp.dispatch({ type: "setText", target: "hf-title", value: "Hello" })`. Both go through the same validation and emit the same patch event. Use typed methods for clarity; use `dispatch()` when you're building data-driven automation or want to feed programmatic op arrays.
|
|
|
|
**Patches are the source of truth for history and sync.** Every committed change emits a `PatchEvent` with forward patches and inverse patches (RFC 6902 `add`/`remove`/`replace` ops). The undo stack replays inverse patches; embedded hosts replay the same patches into their own state machine; collaboration layers forward them to other clients. You can subscribe to `patch` events and mirror SDK mutations anywhere without re-parsing the HTML.
|
|
|
|
**Adapters decouple persistence and preview.** The SDK never reaches the filesystem or an iframe directly. You supply a `PersistAdapter` (memory, filesystem, S3, HTTP — same interface) and optionally a `PreviewAdapter`. The session fires `persist:error` events on write failures instead of throwing. This makes the SDK equally at home in a Node.js agent, a browser editor, and a CI pipeline.
|
|
|
|
**Standalone vs embedded mode.** In standalone mode you own the HTML and the SDK owns history and autosave. In embedded (override) mode you supply a base template and a sparse `OverrideSet` delta; the SDK folds the delta onto the template at open time, accumulates further edits into the override set, and lets you store only the delta — the base template stays untouched.
|
|
|
|
## Guides
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Quickstart" icon="bolt" href="/sdk/quickstart">
|
|
Open a composition, make edits, serialize, and add persistence in five minutes.
|
|
</Card>
|
|
<Card title="Querying & Editing Elements" icon="magnifying-glass" href="/sdk/guides/querying-and-editing">
|
|
getElements, find, typed methods, batch, element handles, and selection.
|
|
</Card>
|
|
<Card title="Timing & Animation" icon="clock" href="/sdk/guides/timing-and-animation">
|
|
setTiming, setHold, GSAP tween and keyframe operations.
|
|
</Card>
|
|
<Card title="Undo, Redo & Patches" icon="arrow-rotate-left" href="/sdk/guides/undo-redo-and-patches">
|
|
History module, patch events, applyPatches, and origin tagging.
|
|
</Card>
|
|
<Card title="Persistence" icon="floppy-disk" href="/sdk/guides/persistence">
|
|
Memory, filesystem, and custom adapters. Version history and flush.
|
|
</Card>
|
|
<Card title="Embedded Override Mode" icon="layers" href="/sdk/guides/embedded-override-mode">
|
|
Template-driven products with host-owned undo and delta storage.
|
|
</Card>
|
|
<Card title="Canvas Integration" icon="paintbrush" href="/sdk/guides/canvas-integration">
|
|
Connecting the SDK to an iframe preview surface.
|
|
</Card>
|
|
<Card title="Editing Affordances" icon="sliders" href="/sdk/guides/editing-affordances">
|
|
Resolve which controls to show for a live element.
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
## Reference
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="openComposition" icon="door-open" href="/sdk/reference/open-composition">
|
|
The single entry point — options, modes, and examples.
|
|
</Card>
|
|
<Card title="Composition" icon="cube" href="/sdk/reference/composition">
|
|
Full method reference for the session object.
|
|
</Card>
|
|
<Card title="Edit Operations" icon="pen-to-square" href="/sdk/reference/edit-operations">
|
|
Every EditOp variant with field-level documentation.
|
|
</Card>
|
|
<Card title="Types" icon="brackets-curly" href="/sdk/reference/types">
|
|
HyperFramesElement, FindQuery, PatchEvent, OverrideSet, and more.
|
|
</Card>
|
|
<Card title="Adapters" icon="plug" href="/sdk/reference/adapters">
|
|
PersistAdapter and PreviewAdapter interfaces and built-in implementations.
|
|
</Card>
|
|
<Card title="Utilities" icon="wrench" href="/sdk/reference/utilities">
|
|
buildDocument, flatElements, UnsupportedOpError, and helper exports.
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
<Tip>
|
|
If you want to render a composition to MP4 or WebM rather than edit it, see the [CLI](/packages/cli) or [producer](/packages/producer). The SDK is the editing layer — rendering is a separate pipeline.
|
|
</Tip>
|
|
|