The main editing surface returned by openComposition — query, mutate, animate, and serialize a composition.
Composition is the object returned by openComposition. Every SDK edit goes through this interface. Typed methods are convenience wrappers over dispatch(); all validation runs in dispatch() regardless of which entry point you use.
import { openComposition } from "@hyperframes/sdk";import type { Composition } from "@hyperframes/sdk";const comp: Composition = await openComposition(html);
Typed methods are the recommended way to apply common edits. Each one calls dispatch() internally, so all patch events, history, and persistence behavior is identical.
Insert an HTML fragment as a child of parent at zero-based sibling index. Pass null for parent to insert at the document body root. The fragment must be single-root and must not contain <script> tags. Returns the minted hf-id of the inserted root element.
const newId = comp.addElement("hf-scene", 0, '<div class="clip">New clip</div>');comp.setText(newId, "Inserted clip");
Return a map of enter/exit times and active GSAP labels for every timed element. The SDK derives enterAt/exitAt using data-duration when present, falling back to data-end − data-start. GSAP labels are parsed fresh from the script each call. Elements with no timing attributes are excluded.
Apply a sparse timing map in one batch. All entries are dispatched inside a single batch() call so the history sees one undo step. Entries for unknown IDs are silently skipped.
Add a new keyframed tween for targetSelector at the given timeline position and duration. Returns the newly minted animationId. Position is a number in seconds (not a label-relative string).
Atomically remove an existing tween and add a replacement keyframed tween. Returns the replacement’s animationId. Because position-derived IDs renumber after the removal, the returned ID may differ from the input animationId — treat the return value as the new canonical ID.
Return a flat array of all elements in the composition, including elements nested inside sub-compositions. Each ElementSnapshot carries the element’s id, scopedId, tag, inlineStyles, classNames, attributes, text, timing fields, and animationIds. The array is a fresh copy; mutations to the returned objects have no effect.
For elements inside inlined sub-compositions, use scopedId (e.g. "hf-host/hf-leaf") as the dispatch target, not id. Top-level elements have scopedId === id.
Return the snapshot for one element by ID. Accepts both bare IDs (top-level elements) and scoped IDs (sub-composition elements). Returns null if no element matches.
const el = comp.getElement("hf-title");if (el) { console.log(el.tag, el.inlineStyles);}
Search elements by structured query. Returns an array of scopedId strings for matching elements. All fields in FindQuery are optional and combined with AND logic.
Field
Type
Description
tag
string
Exact HTML tag name, lowercase ("div", "img").
text
string
Substring match against the element’s text field.
name
string
Exact match against data-name attribute.
track
number
Exact track index (data-track).
composition
string
Filter to elements inside a specific sub-composition host by its hf-id.
Return a SelectionProxy that resolves getSelection() at call time and dispatches operations to all selected elements. The proxy captures the ID list when you call selection() — subsequent selection changes do not affect an already-captured proxy.
const sel = comp.selection();sel.setStyle({ opacity: "0.5" });sel.removeElement(); // removes all currently selected elements
Return a curried ElementHandle for a single element. The handle stores only the ID string, so there is no stale-reference hazard if the DOM changes between calls.
const title = comp.element("hf-title");title.setText("Hello");title.setStyle({ fontWeight: "700" });
Apply a data-shaped edit operation. All typed methods call this internally. Use dispatch when you need to apply op types that do not have a typed wrapper, when you are building automation that constructs ops programmatically, or when you need to set a custom origin.
Coalesce multiple dispatches into one undo entry and one patch event. If the callback throws, all DOM mutations that ran inside the batch are rolled back atomically and the model is restored to its state before batch() was called.
Dry-run validation. Returns { ok: true } when dispatch(op) would succeed, or { ok: false, code, message, hint? } when it would fail or be a no-op.Use this as a feature-detection gate before rendering controls that depend on GSAP timeline availability, or before showing UI that applies optional edits.
Fires after every committed change with a PatchEvent containing RFC 6902 forward and inverse patches, the origin, and semantic opTypes. Use this to mirror edits into a host history stack, collaboration layer, or audit log.
Always guard against ORIGIN_APPLY_PATCHES in patch listeners. Failing to skip that origin causes an infinite loop when your host replays inverse patches back into the SDK via applyPatches().
Return the current composition as an HTML string reflecting all mutations applied since openComposition. The base HTML is never modified; this always returns a fresh serialization of the live document.
Return a copy of the current override set — the sparse delta accumulated on top of the base template. Store this instead of the full HTML when the base template is shared.
Apply RFC 6902 patches directly to the live document. The default origin is ORIGIN_APPLY_PATCHES, which prevents patch listeners from forwarding these back in an undo loop. Use this when the host owns the undo stack and needs to replay inverse patches from its own history.
// Host undo: replay inverse patches from the host stackconst { inversePatches } = hostHistory.pop();comp.applyPatches(inversePatches);
Drain the persist queue. Resolves when any pending write has been committed to the adapter. No-op when no persist adapter was provided. Call this before process exit or navigation away to avoid losing queued writes.
comp.setText("hf-title", "Final title");await comp.flush();comp.dispose();
Tear down the session: unsubscribe preview adapter listeners, stop the persist queue, stop the history module, and clear all event handlers. After dispose(), the Composition object is inert; continued calls produce no-ops or errors.
comp.dispose();
Always call dispose() when you are done with a session. Skipping it leaks listeners attached to the preview adapter.
