Embedded Override Mode

Embedded override mode is the pattern for template-driven products: you maintain one base composition HTML file and store only the per-instance delta (the OverrideSet) alongside it. When a user edits their instance, the SDK accumulates further changes into that same delta — the base stays untouched. This is exactly how a canvas embedder (for example, AI Studio) persists in-composition edits as a stable, reopenable delta.

Opening with overrides

Pass the stored delta as overrides when you call openComposition. The SDK applies the saved changes to the base template, so the session exposes the user’s exact edited state immediately:

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

// Stored delta — loaded from your database or storage layer.
const storedOverrides = {
  "hf-title.text": "Acme Corp Launch",
  "hf-logo.attr.src": "/customers/acme/logo.png",
  "hf-subtitle.style.color": "#0EA5E9",
};

const comp = await openComposition(templateHtml, {
  overrides: storedOverrides,
  history: false, // host owns undo — see below
});

After openComposition returns, comp.getElements() reflects the overridden state. Any further edits accumulate into the same delta automatically.

Reading the current delta

Call getOverrides() to retrieve the current delta for storage. It returns a copy ready to serialize and save:

comp.setText("hf-cta", "Get started free");
comp.setStyle("hf-cta", { backgroundColor: "#22C55E" });

const nextOverrides = comp.getOverrides();
// { "hf-title.text": "Acme Corp Launch", ..., "hf-cta.text": "Get started free", ... }

await db.saveOverrides(sessionId, nextOverrides);

On the next session open, pass nextOverrides as overrides again — the user sees their exact state. Elements inserted with addElement() are stored in the delta too, including their parent and sibling position. Later text, style, or attribute edits replay onto the restored element:

const id = comp.addElement("hf-stage", 1, "<p>Available today</p>");
comp.setText(id, "Available worldwide");

const reopened = await openComposition(templateHtml, {
  overrides: comp.getOverrides(),
});
reopened.getElement(id)?.text; // "Available worldwide"

getOverrides() saves each added or restored element’s current position among all child nodes, including surrounding text. Removing a temporary sibling does not shift the element when reopened. Store the returned set without sorting its keys. The SDK keeps the latest edit order so later child edits apply after their parent’s snapshot.

Override set key format

Keys follow the pattern hfId.prop.path. The common forms are:

Key	Meaning
`"hf-title.text"`	Inner text of element `hf-title`
`"hf-logo.attr.src"`	`src` attribute on `hf-logo`
`"hf-x.style.fontSize"`	Inline `fontSize` style on `hf-x`
`"hf-card"` with an element snapshot	Added or restored element, with its HTML, parent, and sibling position
`"hf-card"` with value `null`	Removal marker — element was deleted

A null value is a removal marker. When the SDK serializes the composition it omits that element entirely. This lets the host distinguish “never touched” (key absent) from “user deleted” (key present, value null). Sub-composition elements use scoped IDs — "hf-host/hf-leaf.text" — where the host and leaf are separated by /. Periods in an authored ID stay part of that ID: editing hf-title.main produces "hf-title.main.text", which restores the edit to that same element when reopened. Non-null whole-element values must be snapshots returned by getOverrides(). Opening a delta skips scalar values and incomplete snapshots under whole-element keys.

Font and image variable overrides

Variable overrides (from setVariableValue) live under the var.{id} key. Font and image values are objects, not strings:

import type { FontValue, ImageValue } from "@hyperframes/sdk";

// Font variable — name is the CSS font-family, source is the stylesheet URL.
const fontOverride: FontValue = {
  name: "Inter",
  source: "https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap",
};

// Image variable — url is the src; alt and fit are optional.
const imageOverride: ImageValue = {
  url: "/customers/acme/hero.jpg",
  alt: "Acme hero image",
  fit: "cover",
};

comp.setVariableValue("brand-font", fontOverride);
comp.setVariableValue("hero-image", imageOverride);

const overrides = comp.getOverrides();
// {
//   "var.brand-font": { name: "Inter", source: "https://…" },
//   "var.hero-image": { url: "/customers/acme/hero.jpg", alt: "…", fit: "cover" },
// }

When you read an OverrideSet value at a var.* key, narrow before treating it as a scalar — the type is string | number | boolean | Record<string, unknown> | null.

Disabling SDK undo

In embedded mode the host typically owns the undo stack. The SDK already leaves history off by default in embedded mode (any session opened with overrides), so you usually don’t need to do anything. Pass history: false explicitly only to make that intent obvious in standalone code paths, or as a guard if a call site may or may not supply overrides:

const comp = await openComposition(templateHtml, {
  overrides: storedOverrides,
  history: false,
});

history: false only disables the SDK’s internal undo stack. Persistence (the persist adapter, if you supply one) is independent — omitting it does not affect autosave. In embedded mode, however, the host typically owns both undo and persistence, so you usually pass neither.

Host-owned undo via `applyPatches()`

When the host pops an undo entry and needs to replay the inverse patches back into the SDK, use applyPatches(). The SDK applies the patches to the live document, updates the internal override set, and emits a patch event tagged with ORIGIN_APPLY_PATCHES.

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

// Host undo stack entry — inversePatches came from a prior 'patch' event.
function hostUndo(inversePatches: JsonPatchOp[]) {
  comp.applyPatches(inversePatches);
}

// Guard against undo loops — skip ORIGIN_APPLY_PATCHES events in the patch listener.
comp.on("patch", ({ patches, inversePatches, origin }) => {
  if (origin === ORIGIN_APPLY_PATCHES) return; // already from host undo — do not re-push
  hostHistory.push({ patches, inversePatches });
});

applyPatches() accepts an optional opts.origin override if you want to tag the event with a different sentinel, but the default ORIGIN_APPLY_PATCHES is the expected value for host undo/redo flows. See Undo, Redo, and Patches for the full patch event contract and inverse patch handling.

Full example

import { openComposition, ORIGIN_APPLY_PATCHES } from "@hyperframes/sdk";
import type { JsonPatchOp, OverrideSet } from "@hyperframes/sdk";

async function openUserSession(
  templateHtml: string,
  storedOverrides: OverrideSet,
) {
  const hostHistory: Array<{ patches: readonly JsonPatchOp[]; inversePatches: readonly JsonPatchOp[] }> = [];
  let historyIndex = hostHistory.length;

  const comp = await openComposition(templateHtml, {
    overrides: storedOverrides,
    history: false,
  });

  // Record every user edit in the host undo stack.
  comp.on("patch", ({ patches, inversePatches, origin }) => {
    if (origin === ORIGIN_APPLY_PATCHES) return;
    // Discard any redo entries ahead of the cursor.
    hostHistory.splice(historyIndex);
    hostHistory.push({ patches, inversePatches });
    historyIndex = hostHistory.length;
  });

  return {
    comp,

    undo() {
      if (historyIndex === 0) return;
      const { inversePatches } = hostHistory[--historyIndex];
      comp.applyPatches([...inversePatches]);
    },

    redo() {
      if (historyIndex >= hostHistory.length) return;
      const { patches } = hostHistory[historyIndex++];
      comp.applyPatches([...patches]);
    },

    async save() {
      // Only store the delta — not the full HTML.
      return comp.getOverrides();
    },
  };
}

openComposition reference

Full OpenCompositionOptions including overrides, history, and persist.

Types reference

OverrideSet, FontValue, ImageValue, PatchEvent, and ORIGIN_APPLY_PATCHES.

Undo, Redo, and Patches

Patch event format, inverse patch contract, and undo loop prevention.

Canvas integration

Wiring the SDK to a live preview iframe inside an editor canvas.

Start here

Command line

SDK guides

SDK reference

Composition, design & animation

Composition reference

Rendering paths

Cloud infrastructure

Advanced rendering

Packages

Agent setup

Contributing & community

Embedded Override Mode

Opening with overrides

Reading the current delta

Override set key format

Font and image variable overrides

Disabling SDK undo

Host-owned undo via `applyPatches()`

Full example

openComposition reference

Types reference

Undo, Redo, and Patches

Canvas integration

​Opening with overrides

​Reading the current delta

​Override set key format

​Font and image variable overrides

​Disabling SDK undo

​Host-owned undo via applyPatches()

​Full example

openComposition reference

Types reference

Undo, Redo, and Patches

Canvas integration

Opening with overrides

Reading the current delta

Override set key format

Font and image variable overrides

Disabling SDK undo

Host-owned undo via `applyPatches()`

Full example