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 every declared variable’s full schema — id, type, label, default, and any type-specific fields (min/max/step for numbers, options for enums, source for fonts, etc). Returns [] when the composition declares no variables.
for (const v of comp.listVariables()) { console.log(v.id, v.type, v.default);}
Manage the data-composition-variables schema itself. declareVariable adds a new
typed declaration (creating the attribute when the composition has none);
updateVariableDeclaration replaces an existing declaration wholesale — the id is
immutable, rename by remove + declare; removeVariableDeclaration deletes a
declaration (the last removal drops the whole attribute). All three validate via
can() (E_DUPLICATE_VARIABLE, E_VARIABLE_NOT_FOUND, E_INVALID_ARGS,
E_INVALID_VARIABLE_ID — the id must match /^[A-Za-z_][A-Za-z0-9_-]*$/ since it
becomes a CSS custom-property name, data-var-* value, and CLI --variables key;
and E_FRAGMENT_COMPOSITION). Declarations live on the composition’s declaration
root: the <html> element for a full document, or the composition root element
([data-composition-id]) for a template / fragment sub-composition. Despite its
name, E_FRAGMENT_COMPOSITION now fires only when the source has no root
element at all to carry the schema — a fragment that has a composition root
accepts declarations. (The code is kept for compatibility; the fix is “add a
composition root element”, not necessarily “add an <html>”.)
Read-only variable APIs (no dispatch). getVariableDeclarations returns the typed
schema (same strict filter the render pipeline uses). getVariableValues resolves
values exactly like the runtime’s getVariables() — declared defaults merged under
the given overrides — so callers can predict what a composition script will read for
a given --variables payload. validateVariableValues runs the same checks as
--strict-variables (undeclared / type-mismatch / enum-out-of-range).
getVariableUsage statically scans every inline script for getVariables() reads
and cross-references the schema: { usedIds, unusedDeclarations, undeclaredReads, scanIncomplete } — scanIncomplete flips when scripts access variables dynamically,
making usedIds a lower bound.
Apply ephemeral variable values to the preview surface (never persisted — use
setVariableValue to change a default). Pass null to restore declared defaults.
Delegates to the preview adapter’s optional setPreviewVariables; returns false
when no adapter support is available.
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 only top-level elements, each carrying its full subtree — no id appears twice (unlike getElements, which flattens every nested element into the same array). Use this when you need one entry per top-level clip rather than every element in the tree.
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 every GSAP tween id parsed from the composition’s script, regardless of whether its target selector currently matches a live DOM element. This differs from a given ElementSnapshot’s own animationIds field, which only lists tweens whose selector resolves to that specific element.
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.
