@hyperframes/sdk 0.6.113

package/dist/adapters/types.d.ts

@@ -0,0 +1,65 @@
+import type { PersistErrorEvent } from "../types.js";
+export interface PersistVersionEntry {
+    /** Opaque key identifying this version (adapter-defined format) */
+    key: string;
+    /** Full HTML content — may be omitted by adapters that load content lazily via loadFrom() */
+    content?: string;
+    timestamp?: number;
+}
+/**
+ * Injectable storage adapter — decouples the SDK from the underlying persistence mechanism.
+ * Implementations: memory (tests/demos), fs (local dev), S3 (cloud), HTTP (Pacific).
+ *
+ * Contract:
+ * - read() returns undefined for a path never written
+ * - write() is idempotent (second write overwrites)
+ * - flush() resolves when any queued writes are committed
+ * - listVersions() returns entries newest-first
+ * - loadFrom() returns content for the given version key (undefined if not found)
+ * - on('persist:error') fires when a write fails; the error must not propagate as a thrown exception
+ */
+export interface PersistAdapter {
+    read(path: string): Promise<string | undefined>;
+    write(path: string, content: string): Promise<void>;
+    /** Force all pending writes to commit before returning */
+    flush(): Promise<void>;
+    listVersions(path: string): Promise<PersistVersionEntry[]>;
+    loadFrom(path: string, versionKey: string): Promise<string | undefined>;
+    on(event: "persist:error", handler: (event: PersistErrorEvent) => void): () => void;
+}
+export interface ElementAtPointResult {
+    id: string;
+    tag: string;
+}
+export interface DraftProps {
+    dx?: number;
+    dy?: number;
+    width?: number;
+    height?: number;
+}
+/**
+ * Injectable preview adapter — decouples the SDK from the host preview surface.
+ * The null/headless adapter stubs all methods (no browser needed).
+ *
+ * The SDK is NOT in the 60fps draft loop — consumers call applyDraft() directly on
+ * the preview at 60fps; commitPreview() fires once on pointer-up to derive and
+ * dispatch the resulting op.
+ */
+export interface PreviewAdapter {
+    /** Sync hit-test at composition coordinates. Requires same-origin iframe. */
+    elementAtPoint(x: number, y: number, opts?: {
+        atTime?: number;
+    }): ElementAtPointResult | null;
+    /** Apply draft CSS markers to the preview element (60fps, SDK not involved) */
+    applyDraft(id: string, props: DraftProps): void;
+    /** Derive op from draft markers, dispatch it, emit patch event, clear markers */
+    commitPreview(): void;
+    /** Revert draft markers without committing. Model never changed. */
+    cancelPreview(): void;
+    /** Set preview selection; fires selectionchange on the session */
+    select(ids: string[], opts?: {
+        additive?: boolean;
+    }): void;
+    on(event: "selection", handler: (ids: string[]) => void): () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/adapters/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAIrD,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ,6FAA6F;IAC7F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAChD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,0DAA0D;IAC1D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACxE,EAAE,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACrF;AAID,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,oBAAoB,GAAG,IAAI,CAAC;IAE9F,+EAA+E;IAC/E,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAEhD,iFAAiF;IACjF,aAAa,IAAI,IAAI,CAAC;IAEtB,oEAAoE;IACpE,aAAa,IAAI,IAAI,CAAC;IAEtB,kEAAkE;IAClE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAI3D,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACtE"}

package/dist/adapters/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/adapters/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":""}

package/dist/document.d.ts

@@ -0,0 +1,25 @@
+/**
+ * SDK document model — adaptation layer on top of @hyperframes/core.
+ *
+ * F6 decision: SDK builds ON core, no parser duplication.
+ * - ensureHfIds (from core) is the parse entry point: all construction starts here.
+ * - DOMParser is NOT used (browser-only). linkedom is the node-safe primitive.
+ * - ParsedHtml (core) is the Studio timeline view (timed elements only).
+ *   HyperFramesElement is the editing view (ALL editable elements, with raw attrs).
+ */
+import type { HyperFramesElement, SdkDocument } from "./types.js";
+/**
+ * Build the element tree from an already-parsed (hf-id-stamped) linkedom Document.
+ * Walks the live DOM directly — no serialize/re-parse round trip. This is what
+ * the session's query API uses against its mutable document.
+ */
+export declare function buildRoots(document: Document): HyperFramesElement[];
+/**
+ * Parse an HTML string into the SDK document model.
+ * Calls ensureHfIds first so every element has a stable data-hf-id.
+ * Uses linkedom — node-safe (works in agents, CI, server-side).
+ */
+export declare function buildDocument(html: string): SdkDocument;
+/** Flat walk of the element tree — returns every element in document order */
+export declare function flatElements(roots: readonly HyperFramesElement[]): HyperFramesElement[];
+//# sourceMappingURL=document.d.ts.map

package/dist/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA0LlE;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,QAAQ,GAAG,kBAAkB,EAAE,CAWnE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAoBvD;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,kBAAkB,EAAE,GAAG,kBAAkB,EAAE,CAQvF"}

package/dist/document.js

@@ -0,0 +1,238 @@
+/**
+ * SDK document model — adaptation layer on top of @hyperframes/core.
+ *
+ * F6 decision: SDK builds ON core, no parser duplication.
+ * - ensureHfIds (from core) is the parse entry point: all construction starts here.
+ * - DOMParser is NOT used (browser-only). linkedom is the node-safe primitive.
+ * - ParsedHtml (core) is the Studio timeline view (timed elements only).
+ *   HyperFramesElement is the editing view (ALL editable elements, with raw attrs).
+ */
+import { parseHTML } from "linkedom";
+import { ensureHfIds } from "@hyperframes/core/hf-ids";
+import { parseGsapScriptAcornForWrite } from "@hyperframes/core/gsap-parser-acorn";
+import { findRoot, getElementStyles, isNewHostBoundary } from "./engine/model.js";
+// Tags that carry no editable content and must not enter the element tree.
+const EXCLUDED_TAGS = new Set([
+    "script",
+    "style",
+    "template",
+    "meta",
+    "link",
+    "noscript",
+    "base",
+    "head",
+]);
+// Snapshot text is TRIMMED for display (markup indentation produces noisy
+// whitespace text nodes). setText writes verbatim — engine getOwnText/setOwnText
+// operate on raw text. el.text is a display value, not a round-trip identity.
+function ownText(el) {
+    let text = "";
+    el.childNodes.forEach((n) => {
+        if (n.nodeType === 3)
+            text += n.nodeValue ?? "";
+    });
+    const trimmed = text.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+// Parsing the GSAP script (acorn AST walk) is the expensive part and depends
+// only on the script text, so memoize the {tween id, selector} pairs by script.
+// Selector→hf-id resolution still runs each call — it depends on the live DOM,
+// which changes on dispatch. Single-entry cache covers the hot path (same comp,
+// repeated getElements() rebuilds) and stays bounded.
+let gsapLocatedCacheKey = null;
+let gsapLocatedCacheVal = [];
+function parseLocatedCached(script) {
+    if (gsapLocatedCacheKey === script)
+        return gsapLocatedCacheVal;
+    const parsed = parseGsapScriptAcornForWrite(script);
+    gsapLocatedCacheVal = parsed
+        ? parsed.located.map(({ id, animation }) => ({ id, selector: animation.targetSelector }))
+        : [];
+    gsapLocatedCacheKey = script;
+    return gsapLocatedCacheVal;
+}
+/**
+ * Map each element's data-hf-id → the GSAP tween ids targeting it. Tween ids
+ * come from the acorn parser's stable `targetSelector-method-position` scheme —
+ * the SAME id-space the studio-api read path and the SDK GSAP ops use, so these
+ * ids are dispatchable as-is via setGsapTween/removeGsapTween. Best-effort: a
+ * malformed selector or unparseable script yields no entries (animationIds: []).
+ */
+function buildAnimationIdMap(document) {
+    const map = new Map();
+    const script = extractGsapScript(document);
+    if (!script)
+        return map;
+    for (const { id, selector } of parseLocatedCached(script)) {
+        if (!selector)
+            continue;
+        let matches = [];
+        try {
+            matches = Array.from(document.querySelectorAll(selector));
+        }
+        catch {
+            continue; // selector not valid for querySelectorAll — skip
+        }
+        for (const el of matches) {
+            const hfId = el.getAttribute("data-hf-id");
+            if (!hfId)
+                continue;
+            const list = map.get(hfId);
+            if (list)
+                list.push(id);
+            else
+                map.set(hfId, [id]);
+        }
+    }
+    return map;
+}
+// fallow-ignore-next-line complexity
+function buildElement(el, scopePrefix, animationIdsByHfId) {
+    const tag = el.tagName.toLowerCase();
+    if (EXCLUDED_TAGS.has(tag))
+        return null;
+    const id = el.getAttribute("data-hf-id") ?? "";
+    if (!id)
+        return null; // should never happen after ensureHfIds, but guard defensively
+    // scopedId: if we're inside a sub-comp scope, prefix with "scopePrefix/".
+    // The host element itself is in the PARENT scope (no prefix change for its own id).
+    const scopedId = scopePrefix ? `${scopePrefix}/${id}` : id;
+    // Children inherit the scope prefix from their parent.
+    // If this element is a new host boundary (starts a new sub-comp scope), its
+    // children use THIS element's scopedId as their prefix.
+    // Otherwise, children inherit the same prefix that this element used.
+    const childPrefix = isNewHostBoundary(el) ? scopedId : scopePrefix;
+    const inlineStyles = getElementStyles(el);
+    const classAttr = el.getAttribute("class") ?? "";
+    const classNames = classAttr
+        .split(/\s+/)
+        .map((c) => c.trim())
+        .filter(Boolean);
+    const attributes = {};
+    for (const attr of Array.from(el.attributes)) {
+        if (attr.name === "style" || attr.name === "class" || attr.name.startsWith("data-hf-")) {
+            continue;
+        }
+        attributes[attr.name] = attr.value;
+    }
+    const startAttr = el.getAttribute("data-start");
+    const endAttr = el.getAttribute("data-end");
+    const trackAttr = el.getAttribute("data-track-index");
+    const start = startAttr !== null ? parseFloat(startAttr) : null;
+    const duration = start !== null && endAttr !== null ? Math.max(0, parseFloat(endAttr) - start) : null;
+    const trackIndex = trackAttr !== null ? parseInt(trackAttr, 10) : null;
+    const children = [];
+    for (const child of Array.from(el.children)) {
+        const built = buildElement(child, childPrefix, animationIdsByHfId);
+        if (built)
+            children.push(built);
+    }
+    return {
+        id,
+        scopedId,
+        tag,
+        children,
+        inlineStyles,
+        classNames,
+        attributes,
+        text: ownText(el),
+        start,
+        duration,
+        trackIndex,
+        animationIds: animationIdsByHfId.get(id) ?? [],
+    };
+}
+// fallow-ignore-next-line complexity
+function extractGsapScript(doc) {
+    // GSAP script is the first <script> tag whose text references gsap. Marker
+    // set must match studio sdkShadow.ts isGsapScriptBody so both pick the same
+    // script from a given composition.
+    for (const script of Array.from(doc.querySelectorAll("script"))) {
+        const text = script.textContent ?? "";
+        if (text.includes("gsap") || text.includes("__timelines") || text.includes("ScrollTrigger")) {
+            return text;
+        }
+    }
+    return null;
+}
+function extractStyles(doc) {
+    const styleEl = doc.querySelector("style");
+    return styleEl ? styleEl.textContent : null;
+}
+// Root resolution delegates to the engine's findRoot so dimension extraction
+// and mutations agree on which element is the composition root.
+// fallow-ignore-next-line complexity
+function extractDimensions(doc) {
+    const stage = findRoot(doc);
+    if (!stage)
+        return { width: null, height: null };
+    // data-width/data-height are the runtime's forced override — prefer them.
+    const wAttr = stage.getAttribute("data-width");
+    const hAttr = stage.getAttribute("data-height");
+    const style = stage.getAttribute?.("style") ?? "";
+    const wm = /width:\s*(\d+)px/.exec(style);
+    const hm = /height:\s*(\d+)px/.exec(style);
+    return {
+        width: wAttr !== null ? parseInt(wAttr, 10) : wm ? parseInt(wm[1] ?? "", 10) : null,
+        height: hAttr !== null ? parseInt(hAttr, 10) : hm ? parseInt(hm[1] ?? "", 10) : null,
+    };
+}
+function extractDuration(doc) {
+    const root = findRoot(doc) ?? doc.body;
+    const dur = root?.getAttribute("data-duration");
+    return dur ? parseFloat(dur) : null;
+}
+/**
+ * Build the element tree from an already-parsed (hf-id-stamped) linkedom Document.
+ * Walks the live DOM directly — no serialize/re-parse round trip. This is what
+ * the session's query API uses against its mutable document.
+ */
+export function buildRoots(document) {
+    const body = document.body;
+    const roots = [];
+    const animationIdsByHfId = buildAnimationIdMap(document);
+    if (body) {
+        for (const child of Array.from(body.children)) {
+            const built = buildElement(child, "", animationIdsByHfId);
+            if (built)
+                roots.push(built);
+        }
+    }
+    return roots;
+}
+/**
+ * Parse an HTML string into the SDK document model.
+ * Calls ensureHfIds first so every element has a stable data-hf-id.
+ * Uses linkedom — node-safe (works in agents, CI, server-side).
+ */
+export function buildDocument(html) {
+    const stamped = ensureHfIds(html);
+    const hasShell = /<!doctype|<html[\s>]/i.test(stamped);
+    const wrapped = !hasShell;
+    const { document } = wrapped
+        ? parseHTML(`<!DOCTYPE html><html><head></head><body>${stamped}</body></html>`)
+        : parseHTML(stamped);
+    const dims = extractDimensions(document);
+    return {
+        roots: buildRoots(document),
+        gsapScript: extractGsapScript(document),
+        styles: extractStyles(document),
+        width: dims.width,
+        height: dims.height,
+        compositionDuration: extractDuration(document),
+        html: stamped,
+    };
+}
+/** Flat walk of the element tree — returns every element in document order */
+export function flatElements(roots) {
+    const result = [];
+    function walk(el) {
+        result.push(el);
+        for (const child of el.children)
+            walk(child);
+    }
+    for (const root of roots)
+        walk(root);
+    return result;
+}
+//# sourceMappingURL=document.js.map

package/dist/document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"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"}

package/dist/engine/apply-patches.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Bounded RFC 6902 patch applier — handles only the path patterns emitted by mutate.ts.
+ *
+ * Not a general-purpose JSON Patch implementation. Translates the well-defined path
+ * grammar back into DOM mutations. Used by applyPatches() for host undo (T3 mode).
+ *
+ * Supports only the emit subset (add/remove/replace) — move/copy/test ops and
+ * unknown paths are silently ignored, matching the JsonPatchOp contract.
+ */
+import type { JsonPatchOp, OverrideSet } from "../types.js";
+import type { ParsedDocument } from "./model.js";
+/**
+ * Replay a stored override-set onto a freshly-parsed base document (T3 init).
+ * A null value means the property was explicitly deleted — emit a remove patch
+ * so the base document matches the session state. (Removing a non-existent
+ * property is a no-op in applyOne, so this is safe against fresh-base misses.)
+ */
+export declare function applyOverrideSet(parsed: ParsedDocument, overrides: OverrideSet): void;
+export declare function applyPatchesToDocument(parsed: ParsedDocument, patches: readonly JsonPatchOp[]): void;
+//# sourceMappingURL=apply-patches.d.ts.map

package/dist/engine/apply-patches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-patches.d.ts","sourceRoot":"","sources":["../../src/engine/apply-patches.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAwFjD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CAwBrF;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,SAAS,WAAW,EAAE,GAC9B,IAAI,CAMN"}

package/dist/engine/apply-patches.js

@@ -0,0 +1,284 @@
+/**
+ * Bounded RFC 6902 patch applier — handles only the path patterns emitted by mutate.ts.
+ *
+ * Not a general-purpose JSON Patch implementation. Translates the well-defined path
+ * grammar back into DOM mutations. Used by applyPatches() for host undo (T3 mode).
+ *
+ * Supports only the emit subset (add/remove/replace) — move/copy/test ops and
+ * unknown paths are silently ignored, matching the JsonPatchOp contract.
+ */
+import { findById, findRoot, setElementStyles, setOwnText, setGsapScript, setStyleSheet, } from "./model.js";
+import { keyToPath, stylePath } from "./patches.js";
+import { writeVariableDefault, clearVariableDefault } from "./variableModel.js";
+// fallow-ignore-next-line complexity
+function parsePath(path) {
+    const styleM = /^\/elements\/([^/]+)\/inlineStyles\/(.+)$/.exec(path);
+    if (styleM)
+        return { type: "style", id: styleM[1], prop: styleM[2] };
+    const textM = /^\/elements\/([^/]+)\/text$/.exec(path);
+    if (textM)
+        return { type: "text", id: textM[1] };
+    const attrM = /^\/elements\/([^/]+)\/attributes\/(.+)$/.exec(path);
+    if (attrM)
+        return {
+            type: "attribute",
+            id: attrM[1],
+            prop: attrM[2]?.replace(/~1/g, "/").replace(/~0/g, "~"),
+        };
+    const timingM = /^\/elements\/([^/]+)\/timing\/(.+)$/.exec(path);
+    if (timingM)
+        return { type: "timing", id: timingM[1], field: timingM[2] };
+    const holdM = /^\/elements\/([^/]+)\/hold\/(.+)$/.exec(path);
+    if (holdM)
+        return { type: "hold", id: holdM[1], field: holdM[2] };
+    const elemM = /^\/elements\/([^/]+)$/.exec(path);
+    if (elemM)
+        return { type: "element", id: elemM[1] };
+    const varM = /^\/variables\/(.+)$/.exec(path);
+    if (varM)
+        return { type: "variable", id: varM[1] };
+    const metaM = /^\/metadata\/(.+)$/.exec(path);
+    if (metaM)
+        return { type: "metadata", field: metaM[1] };
+    if (path === "/script/gsap")
+        return { type: "script" };
+    if (path === "/style/css")
+        return { type: "stylesheet" };
+    return null;
+}
+// ─── Variable JSON model helper ───────────────────────────────────────────────
+/**
+ * Apply a variable patch to `data-composition-variables`. A remove op (null)
+ * deletes the declaration's `default` key, restoring its "no authored default"
+ * state — the exact inverse of a first-set that added a default to a
+ * default-less variable, so undo of such a set round-trips. A value op upserts
+ * the matching declaration's `default`. No-ops when the attr/decl is absent.
+ * Shares the model logic with mutate.ts via ./variableModel.ts.
+ */
+function applyVariableDefault(document, id, newDefault) {
+    if (newDefault === null) {
+        clearVariableDefault(document, id);
+    }
+    else {
+        writeVariableDefault(document, id, newDefault);
+    }
+}
+// ─── Patch application ───────────────────────────────────────────────────────
+/**
+ * Replay a stored override-set onto a freshly-parsed base document (T3 init).
+ * A null value means the property was explicitly deleted — emit a remove patch
+ * so the base document matches the session state. (Removing a non-existent
+ * property is a no-op in applyOne, so this is safe against fresh-base misses.)
+ */
+export function applyOverrideSet(parsed, overrides) {
+    const patches = [];
+    const rootId = findRoot(parsed.document)?.getAttribute("data-hf-id") ?? null;
+    for (const [key, value] of Object.entries(overrides)) {
+        const path = keyToPath(key);
+        if (!path)
+            continue;
+        if (value === null) {
+            patches.push({ op: "remove", path });
+        }
+        else {
+            patches.push({ op: "replace", path, value });
+        }
+        // A scalar `var.{id}` override must also restore the `--{id}` CSS custom
+        // prop on the root. Current sessions persist a paired style override, but
+        // sets written before the model/CSS split only carry `var.{id}`; derive the
+        // CSS here so `var(--{id})` bindings rehydrate. Object (font/image) values
+        // are never CSS, so they are skipped.
+        if (rootId && key.startsWith("var.") && value !== null && typeof value !== "object") {
+            const cssPath = stylePath(rootId, `--${key.slice("var.".length)}`);
+            patches.push({ op: "replace", path: cssPath, value: String(value) });
+        }
+        else if (rootId && key.startsWith("var.") && value === null) {
+            patches.push({ op: "remove", path: stylePath(rootId, `--${key.slice("var.".length)}`) });
+        }
+    }
+    applyPatchesToDocument(parsed, patches);
+}
+export function applyPatchesToDocument(parsed, patches) {
+    for (const patch of patches) {
+        const p = parsePath(patch.path);
+        if (!p)
+            continue;
+        applyOne(parsed, patch, p);
+    }
+}
+// fallow-ignore-next-line complexity
+function applyOne(parsed, patch, p) {
+    switch (p.type) {
+        case "style": {
+            const el = p.id ? findById(parsed.document, p.id) : null;
+            if (!el || !p.prop)
+                return;
+            if (patch.op === "remove") {
+                setElementStyles(el, { [p.prop]: null });
+            }
+            else {
+                setElementStyles(el, { [p.prop]: String(patch.value) });
+            }
+            break;
+        }
+        case "text": {
+            const el = p.id ? findById(parsed.document, p.id) : null;
+            if (!el)
+                return;
+            if (patch.op === "remove") {
+                setOwnText(el, "");
+            }
+            else {
+                setOwnText(el, String(patch.value ?? ""));
+            }
+            break;
+        }
+        case "attribute": {
+            const el = p.id ? findById(parsed.document, p.id) : null;
+            if (!el || !p.prop)
+                return;
+            if (patch.op === "remove") {
+                el.removeAttribute(p.prop);
+            }
+            else {
+                el.setAttribute(p.prop, String(patch.value ?? ""));
+            }
+            break;
+        }
+        case "timing": {
+            const el = p.id ? findById(parsed.document, p.id) : null;
+            if (!el || !p.field)
+                return;
+            if (p.field === "start") {
+                if (patch.op === "remove")
+                    el.removeAttribute("data-start");
+                else
+                    el.setAttribute("data-start", String(patch.value));
+            }
+            else if (p.field === "duration") {
+                // Patch value is the data-duration value — set directly.
+                if (patch.op === "remove")
+                    el.removeAttribute("data-duration");
+                else
+                    el.setAttribute("data-duration", String(patch.value));
+            }
+            else if (p.field === "end") {
+                // Patch value is the absolute data-end time — set directly, no re-derivation.
+                if (patch.op === "remove")
+                    el.removeAttribute("data-end");
+                else
+                    el.setAttribute("data-end", String(patch.value));
+            }
+            else if (p.field === "trackIndex") {
+                if (patch.op === "remove")
+                    el.removeAttribute("data-track-index");
+                else
+                    el.setAttribute("data-track-index", String(patch.value));
+            }
+            break;
+        }
+        case "hold": {
+            const el = p.id ? findById(parsed.document, p.id) : null;
+            if (!el || !p.field)
+                return;
+            const attrName = `data-hold-${p.field}`;
+            if (patch.op === "remove")
+                el.removeAttribute(attrName);
+            else
+                el.setAttribute(attrName, String(patch.value));
+            break;
+        }
+        case "element": {
+            if (!p.id)
+                return;
+            if (patch.op === "remove") {
+                const el = findById(parsed.document, p.id);
+                el?.remove();
+            }
+            else if (patch.op === "add" && patch.value) {
+                const v = patch.value;
+                const parent = v.parentId
+                    ? findById(parsed.document, v.parentId)
+                    : parsed.document.body;
+                if (!parent)
+                    return;
+                // Parse within the target document to avoid cross-document node issues.
+                const tmp = parsed.document.createElement("div");
+                tmp.innerHTML = v.html;
+                const node = tmp.firstElementChild;
+                if (!node)
+                    return;
+                const children = Array.from(parent.children);
+                const ref = children[v.siblingIndex] ?? null;
+                parent.insertBefore(node, ref);
+            }
+            break;
+        }
+        case "variable": {
+            if (!p.id)
+                return;
+            // B1: update the JSON model (data-composition-variables) so
+            // getVariables() returns the correct value in both preview and render.
+            // CSS compat is handled by explicit style-path patches emitted by mutate.ts,
+            // so we do NOT write CSS here — the style case above handles those patches.
+            applyVariableDefault(parsed.document, p.id, patch.op === "remove" ? null : patch.value);
+            break;
+        }
+        case "script": {
+            if (patch.op === "remove") {
+                setGsapScript(parsed.document, "");
+            }
+            else {
+                setGsapScript(parsed.document, String(patch.value ?? ""));
+            }
+            break;
+        }
+        case "stylesheet": {
+            if (patch.op === "remove") {
+                setStyleSheet(parsed.document, "");
+            }
+            else {
+                setStyleSheet(parsed.document, String(patch.value ?? ""));
+            }
+            break;
+        }
+        case "metadata": {
+            const root = findRoot(parsed.document);
+            if (!root || !p.field)
+                return;
+            // Mirror mutate.ts: style always written; the data-* forced-override
+            // attribute is updated only when the composition already carries it.
+            if (p.field === "width") {
+                if (patch.op === "remove") {
+                    setElementStyles(root, { width: null });
+                    root.removeAttribute("data-width");
+                }
+                else {
+                    setElementStyles(root, { width: `${patch.value}px` });
+                    if (root.hasAttribute("data-width"))
+                        root.setAttribute("data-width", String(patch.value));
+                }
+            }
+            else if (p.field === "height") {
+                if (patch.op === "remove") {
+                    setElementStyles(root, { height: null });
+                    root.removeAttribute("data-height");
+                }
+                else {
+                    setElementStyles(root, { height: `${patch.value}px` });
+                    if (root.hasAttribute("data-height")) {
+                        root.setAttribute("data-height", String(patch.value));
+                    }
+                }
+            }
+            else if (p.field === "duration") {
+                if (patch.op === "remove")
+                    root.removeAttribute("data-duration");
+                else
+                    root.setAttribute("data-duration", String(patch.value));
+            }
+            break;
+        }
+    }
+}
+//# sourceMappingURL=apply-patches.js.map