SDK Quickstart - HyperFrames

This guide walks you through the core SDK loop from scratch. You will open a composition HTML string, find and edit elements by their stable hf-id, serialize the result, and then extend the example to save changes to disk automatically.

Open, edit, serialize

Install the package

npm install @hyperframes/sdk

Open a composition

openComposition parses the HTML, stamps any elements that lack data-hf-id attributes, and returns a Composition session.

import { openComposition } from "@hyperframes/sdk";

const html = `<div class="clip" data-start="0" data-duration="5"
                data-hf-id="hf-title">Launch day</div>`;

const comp = await openComposition(html);

The call is async because it runs the ID-stamping pass over the DOM before returning.

Find elements

Use getElements() for a flat snapshot of everything in the composition, or find() to filter by tag, text content, data-name attribute, track index, or sub-composition host.

// All elements
const all = comp.getElements();

// Elements whose text contains "Launch"
const ids = comp.find({ text: "Launch" });

// A specific element by its hf-id
const el = comp.getElement("hf-title");
console.log(el?.text); // "Launch day"

find() returns an array of scopedId strings. For top-level elements, scopedId === id. For elements inside inlined sub-compositions, it is "hf-HOST/hf-LEAF".

Edit elements with typed methods

Typed methods are the most readable way to mutate a composition. Each one translates directly into a dispatched EditOp and emits a patch event.

// Change text
comp.setText("hf-title", "Launch day — we shipped!");

// Change inline styles (camelCase property names)
comp.setStyle("hf-title", {
  color: "#FFD60A",
  fontSize: "96px",
  fontWeight: "700",
});

// Set or clear an attribute (null removes it)
comp.setAttribute("hf-logo", "src", "/assets/logo-v2.png");

// Adjust clip timing
comp.setTiming("hf-title", { start: 0.5, duration: 4 });

// Set a composition variable
comp.setVariableValue("brandColor", "#6C5CE7");

Use batch() when several mutations should collapse into one undo entry, one persist write, and one change event:

comp.batch(() => {
  comp.setText("hf-title", "Launch day — we shipped!");
  comp.setStyle("hf-title", { color: "#FFD60A" });
  comp.setTiming("hf-title", { start: 0.5, duration: 4 });
});

Serialize and dispose

serialize() returns the full updated HTML string. Call dispose() when you are done to release event handlers and any internal state.

const updatedHtml = comp.serialize();
comp.dispose();

// updatedHtml is ready to write to disk, send to a renderer, or store in a database.

Add a persistence adapter

The headless pattern above is fine for one-shot transforms. When you want the SDK to autosave after every edit, pass a PersistAdapter. The filesystem adapter (@hyperframes/sdk/adapters/fs) writes to a local directory and keeps a rolling version history.

import { openComposition } from "@hyperframes/sdk";
import { createFsAdapter } from "@hyperframes/sdk/adapters/fs";
import { readFile } from "node:fs/promises";

// Load the current HTML from disk (or use a template string on first run).
const html = await readFile("./project/index.html", "utf8").catch(() => "<div></div>");

const comp = await openComposition(html, {
  persist: createFsAdapter({ root: "./project" }),
  persistPath: "index.html",
});

// Persistence failures surface as events, not thrown errors.
comp.on("persist:error", ({ error }) => {
  console.error("Autosave failed:", error.message);
});

comp.setText("hf-title", "Autosaved title");
comp.setStyle("hf-title", { color: "#22C55E" });

// Drain any pending write before the process exits.
await comp.flush();
comp.dispose();

The adapter writes ./project/index.html after every mutation and keeps up to 20 version snapshots under ./project/.hf-versions/.

Disabling undo (history: false) does not disable autosave. The two are independent. Passing history: false is only necessary when you are managing the undo stack yourself.

Next steps

Querying & Editing Elements

FindQuery fields, scopedId for sub-compositions, batch semantics, and element handles.

Undo, Redo & Patches

History module, patch events for host sync, and applyPatches loop prevention.

Persistence

Adapter selection, version history, and implementing a custom adapter.

openComposition reference

Full option reference — adapters, overrides, coalesce window, and more.

​Open, edit, serialize

​Add a persistence adapter

​Next steps

Querying & Editing Elements

Undo, Redo & Patches

Persistence

openComposition reference

Open, edit, serialize

Add a persistence adapter

Next steps