@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.
Mental model
Every edit targets a stablehf-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
Quickstart
Open a composition, make edits, serialize, and add persistence in five minutes.
Querying & Editing Elements
getElements, find, typed methods, batch, element handles, and selection.
Timing & Animation
setTiming, setHold, GSAP tween and keyframe operations.
Undo, Redo & Patches
History module, patch events, applyPatches, and origin tagging.
Persistence
Memory, filesystem, and custom adapters. Version history and flush.
Embedded Override Mode
Template-driven products with host-owned undo and delta storage.
Canvas Integration
Connecting the SDK to an iframe preview surface.
Editing Affordances
Resolve which controls to show for a live element.
Reference
openComposition
The single entry point — options, modes, and examples.
Composition
Full method reference for the session object.
Edit Operations
Every EditOp variant with field-level documentation.
Types
HyperFramesElement, FindQuery, PatchEvent, OverrideSet, and more.
Adapters
PersistAdapter and PreviewAdapter interfaces and built-in implementations.
Utilities
buildDocument, flatElements, UnsupportedOpError, and helper exports.