Edit a composition with the SDK

Open composition HTML, query and edit elements, serialize the result, and add persistence.

Use @hyperframes/sdk when an application must inspect or change composition HTML without opening Studio. If you only need playback, use the Player. If you only need a rendered file, use the CLI or Producer.

The core loop is open, query, edit, and serialize. The SDK adds stable data-hf-id values where they are missing so later edits target the same elements.

Open, edit, serialize

1. Install the package

   npm install @hyperframes/sdk
   
2. 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.

3. 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".

4. 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",
   });
   
   // Adjust clip timing
   comp.setTiming("hf-title", { start: 0.5, duration: 4 });
   

   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 });
   });
   
5. 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 persist edits, pass a PersistAdapter. Rapid changes are coalesced and written in order, with the latest state winning rather than one disk write per UI event.

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.

Related topics

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.