@hyperframes/sdk 0.6.113

package/dist/engine/mutate.js

@@ -0,0 +1,1243 @@
+/**
+ * Op handlers for Phase 3a (non-parser ops).
+ *
+ * Each handler: mutates the linkedom Document, returns {forward, inverse} RFC 6902 patches.
+ * Pure with respect to events — callers emit events from the patches.
+ *
+ * Phase 3b (parser-backed) will add setClassStyle + 7 GSAP ops as additional handlers.
+ */
+import { resolveScoped, escapeHfId, findRoot, getElementStyles, setElementStyles, toCamel, getOwnText, setOwnText, getSiblingIndex, getGsapScript, setGsapScript, getStyleSheet, setStyleSheet, } from "./model.js";
+import { stylePath, textPath, attrPath, timingPath, holdPath, elementPath, variablePath, metaPath, gsapScriptPath, styleSheetPath, scalarChange, scalarDelete, valueChange, patchAdd, patchRemove, } from "./patches.js";
+import { upsertCssRule } from "./cssWriter.js";
+import { mintHfId, EXCLUDED_TAGS } from "@hyperframes/core/hf-ids";
+import { parseGsapScriptAcornForWrite } from "@hyperframes/core/gsap-parser-acorn";
+import { addAnimationToScript, addAnimationWithKeyframesToScript, updateAnimationInScript, removeAnimationFromScript, removePropertyFromAnimation, addKeyframeToScript, removeKeyframeFromScript, removeAllKeyframesFromScript, convertToKeyframesFromScript, materializeKeyframesFromScript, splitIntoPropertyGroupsFromScript, splitAnimationsInScript, updateKeyframeInScript, addLabelToScript, removeLabelFromScript, setArcPathInScript, updateArcSegmentInScript, removeArcPathFromScript, unrollDynamicAnimations, } from "@hyperframes/core/gsap-writer-acorn";
+import { deriveKeyframeBackfillDefaults } from "./keyframeBackfill.js";
+import { readVariableDefault, writeVariableDefault } from "./variableModel.js";
+const EMPTY = { forward: [], inverse: [] };
+// ─── setAttribute safety ────────────────────────────────────────────────────
+// Composition-reserved attributes — changing these breaks element identity or
+// the core/studio data model. Reject before mutating.
+const RESERVED_ATTRS = new Set([
+    "data-hf-id",
+    "data-composition-id",
+    "data-width",
+    "data-height",
+    "data-start",
+    "data-end",
+    "data-track-index",
+    "data-hold-start",
+    "data-hold-end",
+    "data-hold-fill",
+]);
+const DANGEROUS_URI_SCHEMES = /^(?:javascript|vbscript):/i;
+const DANGEROUS_DATA_URI = /^data\s*:\s*text\/html/i;
+const URI_BEARING_ATTRS = new Set([
+    "src",
+    "href",
+    "action",
+    "formaction",
+    "poster",
+    "srcset",
+    "xlink:href",
+]);
+function validateSetAttribute(name, value) {
+    const lower = name.toLowerCase();
+    if (RESERVED_ATTRS.has(lower)) {
+        throw new Error(`setAttribute: "${name}" is a reserved composition attribute and cannot be reassigned. ` +
+            `Use the appropriate typed method (setTiming, setHold, etc.) instead.`);
+    }
+    if (lower.startsWith("on")) {
+        throw new Error(`setAttribute: event-handler attributes ("${name}") are not permitted — ` +
+            `they produce executable HTML that cannot be safely serialized.`);
+    }
+    if (value !== null && URI_BEARING_ATTRS.has(lower)) {
+        const trimmed = value.trim();
+        if (DANGEROUS_URI_SCHEMES.test(trimmed) || DANGEROUS_DATA_URI.test(trimmed)) {
+            throw new Error(`setAttribute: unsafe URI value for "${name}".`);
+        }
+    }
+}
+export class UnsupportedOpError extends Error {
+    // Stable error code — part of the public API contract (F7); hosts switch on
+    // err.code rather than the message.
+    // fallow-ignore-next-line unused-class-member
+    code = "E_UNSUPPORTED_OP";
+    constructor(opType) {
+        super(`Op '${opType}' requires the Phase 3b parser-backed engine and is not available yet. ` +
+            `Use can(op) to feature-detect before dispatching.`);
+        this.name = "UnsupportedOpError";
+    }
+}
+// ─── Target normalization ────────────────────────────────────────────────────
+function targets(target) {
+    return Array.isArray(target) ? target : [target];
+}
+// ─── Op dispatch ────────────────────────────────────────────────────────────
+function dispatchRemoveGsapKeyframe(parsed, op) {
+    return handleRemoveGsapKeyframeByPercentage(parsed, op.animationId, op.percentage);
+}
+function applyGsapKeyframeOp(parsed, op) {
+    switch (op.type) {
+        case "setGsapKeyframe":
+            return handleSetGsapKeyframe(parsed, op.animationId, op.keyframeIndex, op.position, op.value, op.ease);
+        case "addGsapKeyframe":
+            return handleAddGsapKeyframe(parsed, op.animationId, op.position, op.value);
+        case "removeGsapKeyframe":
+            return dispatchRemoveGsapKeyframe(parsed, op);
+        case "removeAllKeyframes":
+            return handleRemoveAllKeyframes(parsed, op.animationId);
+        case "convertToKeyframes":
+            return handleConvertToKeyframes(parsed, op.animationId, op.resolvedFromValues);
+        case "materializeKeyframes":
+            return handleMaterializeKeyframes(parsed, op.animationId, op.keyframes, op.easeEach, op.resolvedSelector);
+        case "splitIntoPropertyGroups":
+            return handleSplitIntoPropertyGroups(parsed, op.animationId);
+        case "splitAnimations":
+            return handleSplitAnimations(parsed, op);
+        default:
+            return undefined;
+    }
+}
+function applyArcPathOp(parsed, op) {
+    const s = getGsapScript(parsed.document) ?? "";
+    switch (op.type) {
+        case "setArcPath": {
+            const cfg = {
+                ...op.config,
+                segments: op.config.segments.map((seg) => ({ ...seg, curviness: seg.curviness ?? 1 })),
+            };
+            return handleArcPathScript(parsed, s, setArcPathInScript(s, op.animationId, cfg));
+        }
+        case "updateArcSegment":
+            return handleArcPathScript(parsed, s, updateArcSegmentInScript(s, op.animationId, op.segmentIndex, op.update));
+        case "removeArcPath":
+            return handleArcPathScript(parsed, s, removeArcPathFromScript(s, op.animationId));
+        case "unrollDynamicAnimations":
+            return handleArcPathScript(parsed, s, unrollDynamicAnimations(s, op.animationId, op.elements));
+        default:
+            return undefined;
+    }
+}
+function applyGsapWithKeyframesOp(parsed, op) {
+    switch (op.type) {
+        case "addWithKeyframes":
+            return handleAddWithKeyframes(parsed, op);
+        case "replaceWithKeyframes":
+            return handleReplaceWithKeyframes(parsed, op);
+        default:
+            return undefined;
+    }
+}
+function applyGsapOp(parsed, op) {
+    const kf = applyGsapKeyframeOp(parsed, op);
+    if (kf !== undefined)
+        return kf;
+    const arc = applyArcPathOp(parsed, op);
+    if (arc !== undefined)
+        return arc;
+    const wkf = applyGsapWithKeyframesOp(parsed, op);
+    if (wkf !== undefined)
+        return wkf;
+    switch (op.type) {
+        case "addGsapTween":
+            return handleAddGsapTween(parsed, op.target, op.tween);
+        case "setGsapTween":
+            return handleSetGsapTween(parsed, op.animationId, op.properties);
+        case "removeGsapProperty":
+            return handleRemoveGsapProperty(parsed, op.animationId, op.property, op.from);
+        case "removeGsapTween":
+            return handleRemoveGsapTween(parsed, op.animationId);
+        case "deleteAllForSelector":
+            return handleDeleteAllForSelector(parsed, op.selector);
+        default:
+            return undefined;
+    }
+}
+export function applyOp(parsed, op) {
+    const gsap = applyGsapOp(parsed, op);
+    if (gsap !== undefined)
+        return gsap;
+    switch (op.type) {
+        case "setStyle":
+            return handleSetStyle(parsed, targets(op.target), op.styles);
+        case "setText":
+            return handleSetText(parsed, targets(op.target), op.value);
+        case "setAttribute":
+            return handleSetAttribute(parsed, targets(op.target), op.name, op.value);
+        case "setTiming":
+            return handleSetTiming(parsed, targets(op.target), {
+                start: op.start,
+                duration: op.duration,
+                trackIndex: op.trackIndex,
+            });
+        case "setHold":
+            return handleSetHold(parsed, targets(op.target), op.hold);
+        case "moveElement":
+            return handleMoveElement(parsed, targets(op.target), op.x, op.y);
+        case "removeElement":
+            return handleRemoveElement(parsed, targets(op.target));
+        case "addElement":
+            return handleAddElement(parsed, op.parent, op.index, op.html);
+        case "reorderElements":
+            return handleReorderElements(parsed, op.entries);
+        case "setCompositionMetadata":
+            return handleSetCompositionMetadata(parsed, op);
+        case "setVariableValue":
+            return handleSetVariableValue(parsed, op.id, op.value);
+        case "setClassStyle":
+            return handleSetClassStyle(parsed, op.selector, op.styles);
+        case "addLabel":
+            return handleAddLabel(parsed, op.name, op.position);
+        case "removeLabel":
+            return handleRemoveLabel(parsed, op.name);
+        default:
+            throw new UnsupportedOpError(op.type);
+    }
+}
+// ─── Op handlers ────────────────────────────────────────────────────────────
+function handleSetStyle(parsed, ids, styles) {
+    const result = { forward: [], inverse: [] };
+    for (const id of ids) {
+        const el = resolveScoped(parsed.document, id);
+        if (!el)
+            continue;
+        const old = getElementStyles(el);
+        setElementStyles(el, styles);
+        for (const [prop, value] of Object.entries(styles)) {
+            // Normalize to the camelCase key the style map + patch grammar use. A
+            // hyphenated op key ("transform-origin") otherwise misses the camelCase
+            // store, so oldValue is always null → undo deletes/loses the prior value,
+            // a removal skips its inverse patch entirely (DOM/patch-log desync), and
+            // the patch path/override-set key diverge from the camelCase grammar.
+            const key = toCamel(prop);
+            const path = stylePath(id, key);
+            const oldValue = old[key] ?? null;
+            if (value !== null) {
+                const p = scalarChange(path, oldValue, value);
+                result.forward.push(p.forward);
+                result.inverse.push(p.inverse);
+            }
+            else if (oldValue !== null) {
+                const p = scalarDelete(path, oldValue);
+                result.forward.push(p.forward);
+                result.inverse.push(p.inverse);
+            }
+        }
+    }
+    return result;
+}
+function handleMoveElement(parsed, ids, x, y) {
+    // HF elements are positioned via data-x / data-y (parsed by htmlParser.ts,
+    // emitted by hyperframes generator). CSS left/top is not the convention.
+    const rx = handleSetAttribute(parsed, ids, "data-x", String(x));
+    const ry = handleSetAttribute(parsed, ids, "data-y", String(y));
+    return {
+        forward: [...rx.forward, ...ry.forward],
+        inverse: [...ry.inverse, ...rx.inverse],
+    };
+}
+function handleSetText(parsed, ids, value) {
+    const result = { forward: [], inverse: [] };
+    for (const id of ids) {
+        const el = resolveScoped(parsed.document, id);
+        if (!el)
+            continue;
+        const oldText = getOwnText(el);
+        setOwnText(el, value);
+        const path = textPath(id);
+        // getOwnText always returns string ("" for empty) — use it directly so
+        // the forward patch is always op:'replace', not op:'add'. An op:'add' on
+        // a text path is semantically wrong for external JSON-patch consumers
+        // (the path already exists; add would fail on strict appliers).
+        const p = scalarChange(path, oldText, value);
+        result.forward.push(p.forward);
+        result.inverse.push(p.inverse);
+    }
+    return result;
+}
+function handleSetAttribute(parsed, ids, name, value) {
+    validateSetAttribute(name, value);
+    const result = { forward: [], inverse: [] };
+    for (const id of ids) {
+        const el = resolveScoped(parsed.document, id);
+        if (!el)
+            continue;
+        const oldValue = el.getAttribute(name);
+        const path = attrPath(id, name);
+        if (value !== null) {
+            el.setAttribute(name, value);
+            const p = scalarChange(path, oldValue, value);
+            result.forward.push(p.forward);
+            result.inverse.push(p.inverse);
+        }
+        else if (oldValue !== null) {
+            el.removeAttribute(name);
+            const p = scalarDelete(path, oldValue);
+            result.forward.push(p.forward);
+            result.inverse.push(p.inverse);
+        }
+    }
+    return result;
+}
+// fallow-ignore-next-line complexity
+function handleSetTiming(parsed, ids, timing) {
+    const result = { forward: [], inverse: [] };
+    // Parse GSAP script once; updateAnimationInScript re-parses internally per call but
+    // we avoid re-fetching the script element on every iteration.
+    const origScript = getGsapScript(parsed.document);
+    const parsedGsap = origScript ? parseGsapScriptAcornForWrite(origScript) : null;
+    let currentScript = origScript;
+    for (const id of ids) {
+        const el = resolveScoped(parsed.document, id);
+        if (!el)
+            continue;
+        const oldStartStr = el.getAttribute("data-start");
+        const oldEndStr = el.getAttribute("data-end");
+        const oldDurationStr = el.getAttribute("data-duration");
+        const oldTrackStr = el.getAttribute("data-track-index");
+        const oldStart = oldStartStr !== null ? parseFloat(oldStartStr) : null;
+        const oldEnd = oldEndStr !== null ? parseFloat(oldEndStr) : null;
+        const oldDurationAttr = oldDurationStr !== null ? parseFloat(oldDurationStr) : null;
+        // Prefer an explicit data-duration — the attribute clips are authored with and
+        // the runtime reads — falling back to data-end − data-start. Reading only
+        // data-end left oldDuration null for duration-authored clips, collapsing the
+        // GSAP duration-scale ratio to 1 and scaling nothing.
+        const oldDuration = oldDurationAttr !== null
+            ? oldDurationAttr
+            : oldStart !== null && oldEnd !== null
+                ? oldEnd - oldStart
+                : null;
+        const oldTrack = oldTrackStr !== null ? parseInt(oldTrackStr, 10) : null;
+        const newStart = timing.start ?? oldStart;
+        const newDuration = timing.duration ?? oldDuration;
+        if (timing.start !== undefined && newStart !== null) {
+            const path = timingPath(id, "start");
+            const p = scalarChange(path, oldStart, newStart);
+            result.forward.push(p.forward);
+            result.inverse.push(p.inverse);
+            el.setAttribute("data-start", String(newStart));
+        }
+        // Write to whichever timing attribute the clip actually uses. A data-duration
+        // clip updates data-duration only on a real resize (duration is invariant
+        // under a move); a data-end clip updates data-end whenever start or duration
+        // changes (end = start + duration). Writing a fresh data-end beside a stale
+        // data-duration had no playback effect.
+        if (oldDurationStr !== null) {
+            if (timing.duration !== undefined && newDuration !== null) {
+                const path = timingPath(id, "duration");
+                const p = scalarChange(path, oldDurationAttr, newDuration);
+                result.forward.push(p.forward);
+                result.inverse.push(p.inverse);
+                el.setAttribute("data-duration", String(newDuration));
+            }
+            // A clip carrying BOTH data-duration and data-end must keep data-end in
+            // sync (end = start + duration) on any start/duration change, else the
+            // stale data-end inverts the clip (end < start) for runtimes that read it.
+            if (oldEndStr !== null && newStart !== null && newDuration !== null) {
+                const newEnd = newStart + newDuration;
+                const endPath = timingPath(id, "end");
+                const ep = scalarChange(endPath, oldEnd, newEnd);
+                result.forward.push(ep.forward);
+                result.inverse.push(ep.inverse);
+                el.setAttribute("data-end", String(newEnd));
+            }
+        }
+        else if ((timing.duration !== undefined || timing.start !== undefined) &&
+            newStart !== null &&
+            newDuration !== null) {
+            const newEnd = newStart + newDuration;
+            // Store the computed end value directly (not the logical duration) so the inverse
+            // patch is self-contained and doesn't require data-start to be restored first.
+            const path = timingPath(id, "end");
+            const p = scalarChange(path, oldEnd, newEnd);
+            result.forward.push(p.forward);
+            result.inverse.push(p.inverse);
+            el.setAttribute("data-end", String(newEnd));
+        }
+        if (timing.trackIndex !== undefined) {
+            const newTrack = timing.trackIndex;
+            const path = timingPath(id, "trackIndex");
+            const p = scalarChange(path, oldTrack, newTrack);
+            result.forward.push(p.forward);
+            result.inverse.push(p.inverse);
+            el.setAttribute("data-track-index", String(newTrack));
+        }
+        // Sync GSAP tween positions: the GSAP script is the source of truth at play time —
+        // the timeline rebuilds from it on every seek. Without this, DOM attribute edits
+        // have zero playback effect; the script's position/duration silently overrides them.
+        // Match against BOTH the element's data-hf-id (the canonical form) AND its DOM
+        // id: the Studio GSAP panel / ensureElementAddressable author tweens as
+        // `#domId`, which selectorMatchesId(hfId) never matched — so moving/resizing
+        // those clips left their tweens unsynced.
+        const matchHfId = el.getAttribute("data-hf-id") ?? id;
+        const matchDomId = el.getAttribute("id");
+        if (parsedGsap && currentScript) {
+            // A missing data-start means an implicit start of 0 (matching the server
+            // shiftGsapPositions path); a malformed attr parses to NaN. Sanitize to a
+            // finite number so a start-less/blank clip still shifts and never feeds
+            // NaN into the tween positions.
+            const oldStartNum = oldStart !== null && Number.isFinite(oldStart) ? oldStart : 0;
+            // Per-tween shift/scale (mirrors shiftGsapPositions/scaleGsapPositions): a
+            // multi-tween stagger maps each tween's own intra-clip position by the
+            // start DELTA and scales its duration by the clip-duration RATIO. Writing
+            // the absolute newStart/newDuration onto every tween would collapse the
+            // stagger onto one point and blow each tween's duration to the full clip.
+            const startChanged = timing.start !== undefined && newStart !== null;
+            const durChanged = timing.duration !== undefined && newDuration !== null;
+            const ratio = durChanged && oldDuration !== null && oldDuration > 0 && newDuration !== null
+                ? newDuration / oldDuration
+                : 1;
+            const remapStart = startChanged && newStart !== null ? newStart : oldStartNum;
+            for (const { id: animId, animation } of parsedGsap.located) {
+                const matches = selectorMatchesId(animation.targetSelector, matchHfId) ||
+                    (matchDomId !== null && selectorMatchesId(animation.targetSelector, matchDomId));
+                if (!matches)
+                    continue;
+                // Skip tweens whose position is a label or relative string ("+=0.5",
+                // "<", ">"): relative positions already track their neighbours, and a
+                // string position can't be safely shifted by the clip delta here.
+                // ponytail: known ceiling — string positions are not re-synced on
+                // move/resize; numeric positions only.
+                if (typeof animation.position !== "number")
+                    continue;
+                const updates = {};
+                // Don't write an absolute position onto an auto-sequenced tween (no
+                // explicit position arg → parsed as implicitPosition): the writer would
+                // APPEND a position arg, collapsing the stagger onto one point. Duration
+                // still scales below.
+                if ((startChanged || durChanged) && animation.implicitPosition !== true) {
+                    const shifted = remapStart + (animation.position - oldStartNum) * ratio;
+                    updates.position = Math.max(0, Math.round(shifted * 1000) / 1000);
+                }
+                if (durChanged && typeof animation.duration === "number" && animation.duration > 0) {
+                    updates.duration = Math.max(0.001, Math.round(animation.duration * ratio * 1000) / 1000);
+                }
+                if (Object.keys(updates).length === 0)
+                    continue;
+                currentScript = updateAnimationInScript(currentScript, animId, updates);
+            }
+        }
+    }
+    // Flush accumulated GSAP script changes as a single patch pair.
+    if (origScript && currentScript && currentScript !== origScript) {
+        setGsapScript(parsed.document, currentScript);
+        const gsapResult = gsapScriptChange(origScript, currentScript);
+        result.forward.push(...gsapResult.forward);
+        result.inverse.push(...gsapResult.inverse);
+    }
+    return result;
+}
+function handleSetHold(parsed, ids, hold) {
+    const result = { forward: [], inverse: [] };
+    for (const id of ids) {
+        const el = resolveScoped(parsed.document, id);
+        if (!el)
+            continue;
+        const fields = [
+            ["start", String(hold.start)],
+            ["end", String(hold.end)],
+            ["fill", hold.fill],
+        ];
+        for (const [field, newVal] of fields) {
+            const attrName = `data-hold-${field}`;
+            const oldVal = el.getAttribute(attrName);
+            const path = holdPath(id, field);
+            el.setAttribute(attrName, newVal);
+            const p = scalarChange(path, oldVal, newVal);
+            result.forward.push(p.forward);
+            result.inverse.push(p.inverse);
+        }
+    }
+    return result;
+}
+function handleRemoveElement(parsed, ids) {
+    const result = { forward: [], inverse: [] };
+    const origScript = getGsapScript(parsed.document);
+    let currentScript = origScript;
+    for (const id of ids) {
+        const el = resolveScoped(parsed.document, id);
+        if (!el)
+            continue;
+        const parentEl = el.parentElement;
+        const parentId = parentEl?.getAttribute("data-hf-id") ?? null;
+        const siblingIndex = getSiblingIndex(el);
+        const html = el.outerHTML;
+        // Collect all bare hf-ids in the subtree BEFORE removal so GSAP cascade
+        // removes animations targeting any sub-composition element, not just the host.
+        const subtreeIds = collectSubtreeHfIds(el);
+        el.remove();
+        const path = elementPath(id);
+        result.forward.push(patchRemove(path));
+        result.inverse.push(patchAdd(path, { html, parentId, siblingIndex }));
+        if (currentScript) {
+            for (const subtreeId of subtreeIds) {
+                currentScript = cascadeRemoveAnimations(currentScript, subtreeId);
+            }
+        }
+    }
+    if (origScript && currentScript && currentScript !== origScript) {
+        setGsapScript(parsed.document, currentScript);
+        const gsapResult = gsapScriptChange(origScript, currentScript);
+        result.forward.push(...gsapResult.forward);
+        result.inverse.push(...gsapResult.inverse);
+    }
+    return result;
+}
+// ─── addElement handler ───────────────────────────────────────────────────────
+/**
+ * Resolve all existing hf-ids in the document into `assigned` so that
+ * mintHfId cannot issue an id that already exists in the composition.
+ */
+function collectDocumentHfIds(document) {
+    const assigned = new Set();
+    for (const el of Array.from(document.querySelectorAll("[data-hf-id]"))) {
+        const id = el.getAttribute("data-hf-id");
+        if (id)
+            assigned.add(id);
+    }
+    return assigned;
+}
+/**
+ * Stamp data-hf-id onto every un-stamped element in `root` and its
+ * descendants, minting ids against `assigned` (the live document's id set).
+ * Returns the minted id of `root` (or its existing id if already stamped).
+ */
+function mintFragmentIds(root, assigned) {
+    if (!root.getAttribute("data-hf-id") && !EXCLUDED_TAGS.has(root.tagName.toLowerCase())) {
+        root.setAttribute("data-hf-id", mintHfId(root, assigned));
+    }
+    for (const el of Array.from(root.querySelectorAll("*"))) {
+        if (EXCLUDED_TAGS.has(el.tagName.toLowerCase()))
+            continue;
+        if (el.getAttribute("data-hf-id"))
+            continue; // pinned
+        el.setAttribute("data-hf-id", mintHfId(el, assigned));
+    }
+    return root.getAttribute("data-hf-id") ?? "";
+}
+/**
+ * Insert an HTML fragment (single-root) as a child of `parent` at `index`.
+ * Mints ids against the LIVE document's existing id set so new ids can never
+ * collide with elements already in the composition. Returns the minted root id
+ * via result.meta.newId — mirrors the `animationId` pattern in addGsapTween.
+ *
+ * Inverse = patchRemove of the new element's path; mirrors handleRemoveElement's
+ * inverse = patchAdd. Forward/inverse are thus symmetric with that handler.
+ */
+/**
+ * Parse an HTML fragment in the target document and return its single root
+ * element, or null when it is empty, multi-root, or contains a <script>.
+ * The dispatch path skips validateOp, so these guards are re-enforced here:
+ * never insert raw <script>, never silently drop extra roots.
+ */
+function parseInsertableFragment(document, html) {
+    // Same temp-div approach as apply-patches.ts to avoid cross-document issues.
+    const tmp = document.createElement("div");
+    tmp.innerHTML = html;
+    if (tmp.querySelector("script"))
+        return null;
+    const node = tmp.firstElementChild;
+    if (!node || node.nextElementSibling)
+        return null;
+    return node;
+}
+function handleAddElement(parsed, parent, index, html) {
+    // Resolve parent element (null → document body). Narrow rather than assert:
+    // _dispatch does not run validateOp, so a bad parent id must not crash here.
+    const parentEl = parent === null
+        ? (parsed.document.body ?? null)
+        : resolveScoped(parsed.document, parent);
+    if (!parentEl)
+        return EMPTY;
+    const node = parseInsertableFragment(parsed.document, html);
+    if (!node)
+        return EMPTY;
+    // Mint ids against the LIVE doc's existing id set (the #1 landmine — a fresh
+    // ensureHfIds(fragment) is blind to existing doc ids and can collide).
+    // Order: mint → capture outerHTML → insert → build patch (id needed for path).
+    const assigned = collectDocumentHfIds(parsed.document);
+    const newId = mintFragmentIds(node, assigned);
+    const stampedHtml = node.outerHTML;
+    // Insert at `index` — append if index >= childCount (RFC-6902 insert semantics).
+    const ref = Array.from(parentEl.children)[index] ?? null;
+    parentEl.insertBefore(node, ref);
+    // parentId for the inverse/replay patch: preserve the caller's id verbatim
+    // (scoped "hf-host/hf-leaf" path or composition id), not the bare data-hf-id —
+    // apply-patches resolves it via findById→resolveScoped, so dropping the host
+    // prefix would re-insert under the wrong (canonical) parent on redo/replay.
+    const parentId = parent;
+    const path = elementPath(newId);
+    return {
+        forward: [patchAdd(path, { html: stampedHtml, parentId, siblingIndex: index })],
+        inverse: [patchRemove(path)],
+        meta: { newId },
+    };
+}
+function handleReorderElements(parsed, entries) {
+    const result = { forward: [], inverse: [] };
+    // Last write wins per target — a duplicated target collapses to one zIndex
+    // patch instead of emitting redundant same-path patches in one dispatch.
+    const lastByTarget = new Map();
+    for (const { target, zIndex } of entries)
+        lastByTarget.set(target, zIndex);
+    for (const [target, zIndex] of lastByTarget) {
+        const sub = handleSetStyle(parsed, [target], { zIndex: String(zIndex) });
+        result.forward.push(...sub.forward);
+        result.inverse.push(...sub.inverse);
+    }
+    return result;
+}
+// fallow-ignore-next-line complexity
+function handleSetCompositionMetadata(parsed, op) {
+    const result = { forward: [], inverse: [] };
+    const root = findRoot(parsed.document);
+    if (!root)
+        return result;
+    // The runtime treats data-width/data-height as a FORCED override of inline
+    // style when present (core/runtime/init.ts applyCompositionSizing). So:
+    // style is always written; the data-* attribute is updated only when the
+    // composition already carries it — otherwise a style-only write would be
+    // clobbered on load. Absent attributes stay absent (keeps inverses exact).
+    if (op.width !== undefined) {
+        const styles = getElementStyles(root);
+        const oldAttr = root.getAttribute("data-width");
+        const oldWidth = oldAttr ?? styles["width"] ?? null;
+        const newVal = `${op.width}px`;
+        setElementStyles(root, { width: newVal });
+        if (oldAttr !== null)
+            root.setAttribute("data-width", String(op.width));
+        const path = metaPath("width");
+        const p = scalarChange(path, oldWidth !== null ? parseFloat(oldWidth) : null, op.width);
+        result.forward.push(p.forward);
+        result.inverse.push(p.inverse);
+    }
+    if (op.height !== undefined) {
+        const styles = getElementStyles(root);
+        const oldAttr = root.getAttribute("data-height");
+        const oldHeight = oldAttr ?? styles["height"] ?? null;
+        const newVal = `${op.height}px`;
+        setElementStyles(root, { height: newVal });
+        if (oldAttr !== null)
+            root.setAttribute("data-height", String(op.height));
+        const path = metaPath("height");
+        const p = scalarChange(path, oldHeight !== null ? parseFloat(oldHeight) : null, op.height);
+        result.forward.push(p.forward);
+        result.inverse.push(p.inverse);
+    }
+    if (op.duration !== undefined) {
+        const oldDur = root.getAttribute("data-duration");
+        const oldVal = oldDur !== null ? parseFloat(oldDur) : null;
+        root.setAttribute("data-duration", String(op.duration));
+        const path = metaPath("duration");
+        const p = scalarChange(path, oldVal, op.duration);
+        result.forward.push(p.forward);
+        result.inverse.push(p.inverse);
+    }
+    return result;
+}
+// ─── Variable JSON model helpers ─────────────────────────────────────────────
+// readVariableDefault / writeVariableDefault now live in ./variableModel.ts,
+// shared with the patch-replay path (apply-patches.ts) so the model shape can't
+// diverge between forward mutation and replay.
+/**
+ * True when the value is a FontValue or ImageValue object
+ * (object-valued; must NOT be written as a CSS custom property).
+ */
+function isObjectVariableValue(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function handleSetVariableValue(parsed, id, value) {
+    const root = findRoot(parsed.document);
+    if (!root)
+        return EMPTY;
+    const modelPath = variablePath(id);
+    const oldVarDefault = readVariableDefault(parsed.document, id);
+    if (isObjectVariableValue(value)) {
+        // Object values (font / image): write to JSON model only — objects are not
+        // valid CSS custom property values (LOCKED §7).
+        writeVariableDefault(parsed.document, id, value);
+        const p = valueChange(modelPath, oldVarDefault ?? null, value);
+        return { forward: [p.forward], inverse: [p.inverse] };
+    }
+    // Scalar values: update the JSON model (B1 — drives the runtime) and also
+    // keep the CSS custom prop as secondary / compat for compositions that
+    // CSS-bind directly to --{id}.
+    const cssVar = `--${id}`;
+    const rootId = root.getAttribute("data-hf-id");
+    const oldStyles = getElementStyles(root);
+    const oldCssValue = oldStyles[cssVar] ?? null;
+    const newVal = String(value);
+    setElementStyles(root, { [cssVar]: newVal });
+    writeVariableDefault(parsed.document, id, value);
+    // Emit explicit patches for both the JSON model (canonical) and the CSS compat
+    // prop. Keeping them separate means apply-patches.ts can handle each path type
+    // purely (variable path → model only; style path → CSS only), so inverse patches
+    // correctly restore the exact pre-call state without CSS-side-effect ambiguity.
+    const modelP = valueChange(modelPath, oldVarDefault ?? null, value);
+    const forward = [modelP.forward];
+    const inverse = [modelP.inverse];
+    if (rootId) {
+        const cssPatch = scalarChange(stylePath(rootId, cssVar), oldCssValue, newVal);
+        forward.push(cssPatch.forward);
+        inverse.push(cssPatch.inverse);
+    }
+    return { forward, inverse };
+}
+// ─── GSAP selector helpers ───────────────────────────────────────────────────
+function selectorMatchesId(selector, id) {
+    return (selector === `[data-hf-id="${id}"]` ||
+        selector === `[data-hf-id='${id}']` ||
+        selector === `#${id}`);
+}
+// v1 limitation: selectorMatchesId uses bare-id matching across the whole script, so a
+// selector targeting "hf-leaf" will cascade-remove animations for both "hf-parent/hf-leaf"
+// and any other element whose scoped or bare id matches "hf-leaf". Acceptable for typical
+// single-comp use; sub-composition authors with leaf-id collisions should use
+// fully-qualified selectors.
+/** Collect all bare data-hf-id values from el and all its descendants. */
+function collectSubtreeHfIds(el) {
+    const ids = [];
+    const own = el.getAttribute("data-hf-id");
+    if (own)
+        ids.push(own);
+    for (const child of Array.from(el.querySelectorAll("[data-hf-id]"))) {
+        const id = child.getAttribute("data-hf-id");
+        if (id)
+            ids.push(id);
+    }
+    return ids;
+}
+function cascadeRemoveAnimations(script, id) {
+    // Re-parse after each removal: animation ids are positional, so removing one
+    // tween renumbers the survivors — ids from a single up-front parse go stale and
+    // no-op, orphaning later tweens on the removed element. Same fix as
+    // stripGsapForId in htmlParser.ts (R3 #3); this is its SDK-side twin.
+    let current = script;
+    for (;;) {
+        const parsedGsap = parseGsapScriptAcornForWrite(current);
+        if (!parsedGsap)
+            return current;
+        const match = parsedGsap.located.find((l) => selectorMatchesId(l.animation.targetSelector, id));
+        if (!match)
+            return current;
+        const next = removeAnimationFromScript(current, match.id);
+        if (next === current)
+            return current; // guard against a non-removing match
+        current = next;
+    }
+}
+// ─── addWithKeyframes / replaceWithKeyframes handlers ────────────────────────
+function handleAddWithKeyframes(parsed, op) {
+    const script = getGsapScript(parsed.document);
+    if (!script)
+        throw new Error("No GSAP script block found in the composition.");
+    // Dispatch skips validateOp — re-enforce the empty-keyframes guard here so we
+    // never emit a degenerate `keyframes: {}` tween.
+    if (op.keyframes.length === 0)
+        return EMPTY;
+    const { script: newScript, id: animationId } = addAnimationWithKeyframesToScript(script, op.targetSelector, op.position, op.duration, op.keyframes, op.ease);
+    if (!animationId)
+        return EMPTY;
+    setGsapScript(parsed.document, newScript);
+    return { ...gsapScriptChange(script, newScript), meta: { animationId } };
+}
+function handleReplaceWithKeyframes(parsed, op) {
+    const script = getGsapScript(parsed.document);
+    if (!script)
+        throw new Error("No GSAP script block found in the composition.");
+    if (op.keyframes.length === 0)
+        return EMPTY;
+    // #11: tween IDs are position-derived and re-point after any structural edit,
+    // so a stale `animationId` can resolve to a DIFFERENT tween. Require the
+    // located animation to still target the selector the caller expects; if it is
+    // absent or now points at another element, bail rather than silently replace
+    // the wrong tween. (validateOp's gsapAnimationMissing only catches absent ids.)
+    const located = locateGsapAnimation(parsed, op.animationId);
+    if (!located || located.animation.targetSelector !== op.targetSelector)
+        return EMPTY;
+    // Step 1: remove the existing tween. Position-derived IDs renumber, so the
+    // inverse patch restores the full GSAP script rather than trying to re-insert
+    // by ID (handled by the coarse gsapScriptChange patch pair).
+    const afterRemove = removeAnimationFromScript(script, op.animationId);
+    // Defense in depth: if the id resolved to nothing the script is unchanged —
+    // bail rather than degrade the replace into a plain add (duplicate tween).
+    if (afterRemove === script)
+        return EMPTY;
+    // Step 2: insert the replacement keyframed tween.
+    const { script: newScript, id: animationId } = addAnimationWithKeyframesToScript(afterRemove, op.targetSelector, op.position, op.duration, op.keyframes, op.ease);
+    if (!animationId)
+        return EMPTY;
+    setGsapScript(parsed.document, newScript);
+    return { ...gsapScriptChange(script, newScript), meta: { animationId } };
+}
+// ─── setClassStyle handler ────────────────────────────────────────────────────
+function handleSetClassStyle(parsed, selector, styles) {
+    const oldCss = getStyleSheet(parsed.document);
+    const newCss = upsertCssRule(oldCss, selector, styles);
+    if (newCss === oldCss)
+        return EMPTY;
+    setStyleSheet(parsed.document, newCss);
+    const path = styleSheetPath();
+    return {
+        forward: [
+            oldCss === "" ? { op: "add", path, value: newCss } : { op: "replace", path, value: newCss },
+        ],
+        inverse: [oldCss === "" ? { op: "remove", path } : { op: "replace", path, value: oldCss }],
+    };
+}
+// ─── GSAP script patch helpers ───────────────────────────────────────────────
+function gsapScriptChange(oldScript, newScript) {
+    const path = gsapScriptPath();
+    return {
+        forward: [{ op: "replace", path, value: newScript }],
+        inverse: [{ op: "replace", path, value: oldScript }],
+    };
+}
+// ─── Phase 3b handlers ───────────────────────────────────────────────────────
+// Build the GSAP target selector for an add op. The SDK's whole element↔tween
+// attribution is data-hf-id based (selectorMatchesId, cascadeRemoveAnimations,
+// buildAnimationIdMap), so ALWAYS emit the canonical [data-hf-id="…"] form.
+//
+// Resolve the target first: a normal element resolves to itself (hf-id ==
+// target). A sub-composition ROOT addressed by its composition id resolves —
+// via resolveScoped's comp-id fallback — to the host element, whose own
+// data-hf-id we then emit. The fidelity resolver unifies this with the server
+// writer's [data-composition-id="…"] form because both querySelector to the
+// same host node.
+function gsapTargetSelector(document, bareTarget) {
+    const el = resolveScoped(document, bareTarget);
+    if (!el)
+        return `[data-hf-id="${escapeHfId(bareTarget)}"]`;
+    const hfId = el.getAttribute("data-hf-id");
+    if (hfId)
+        return `[data-hf-id="${escapeHfId(hfId)}"]`;
+    // Resolved a sub-comp root that carries data-composition-id but no own
+    // data-hf-id (rare/defensive) — address it by its composition id.
+    const compId = el.getAttribute("data-composition-id");
+    if (compId)
+        return `[data-composition-id="${escapeHfId(compId)}"]`;
+    return `[data-hf-id="${escapeHfId(bareTarget)}"]`;
+}
+// fallow-ignore-next-line complexity
+function handleAddGsapTween(parsed, target, tween) {
+    const script = getGsapScript(parsed.document);
+    if (!script)
+        throw new Error("No GSAP script block found in the composition.");
+    const extras = {};
+    if (tween.repeat !== undefined)
+        extras.repeat = tween.repeat;
+    if (tween.yoyo !== undefined)
+        extras.yoyo = tween.yoyo;
+    if (tween.stagger !== undefined)
+        extras.stagger = tween.stagger;
+    // A fromTo's destination may arrive as either `toProperties` or `properties`
+    // (the Studio add path sets `properties`). Fall back the same way for every
+    // method — the old fromTo-only branch read `toProperties` alone and wrote an
+    // empty to-vars object, so fromTo animations added via cutover animated to {}.
+    const toProps = (tween.toProperties ?? tween.properties ?? {});
+    // Scoped ids like "hf-host/hf-leaf" must use the bare leaf id in the GSAP
+    // selector — only the leaf part is written as data-hf-id on the DOM element.
+    const bareTarget = target.includes("/") ? (target.split("/").at(-1) ?? target) : target;
+    const animation = {
+        targetSelector: gsapTargetSelector(parsed.document, bareTarget),
+        method: tween.method,
+        position: tween.position ?? 0,
+        ...(tween.duration !== undefined ? { duration: tween.duration } : {}),
+        ...(tween.ease ? { ease: tween.ease } : {}),
+        properties: toProps,
+        ...(tween.fromProperties
+            ? { fromProperties: tween.fromProperties }
+            : {}),
+        ...(Object.keys(extras).length > 0 ? { extras } : {}),
+    };
+    const { script: newScript, id: animationId } = addAnimationToScript(script, animation);
+    if (!animationId)
+        return EMPTY;
+    setGsapScript(parsed.document, newScript);
+    return { ...gsapScriptChange(script, newScript), meta: { animationId } };
+}
+// fallow-ignore-next-line complexity
+function handleSetGsapTween(parsed, animationId, properties) {
+    const script = getGsapScript(parsed.document);
+    if (!script)
+        throw new Error("No GSAP script block found in the composition.");
+    const updates = {};
+    if (properties.duration !== undefined)
+        updates.duration = properties.duration;
+    if (properties.ease !== undefined)
+        updates.ease = properties.ease;
+    if (properties.position !== undefined)
+        updates.position = properties.position;
+    const toProps = properties.toProperties ?? properties.properties;
+    if (toProps)
+        updates.properties = toProps;
+    if (properties.fromProperties)
+        updates.fromProperties = properties.fromProperties;
+    const extras = {};
+    if (properties.repeat !== undefined)
+        extras.repeat = properties.repeat;
+    if (properties.yoyo !== undefined)
+        extras.yoyo = properties.yoyo;
+    if (properties.stagger !== undefined)
+        extras.stagger = properties.stagger;
+    if (Object.keys(extras).length > 0)
+        updates.extras = extras;
+    const newScript = updateAnimationInScript(script, animationId, updates);
+    if (newScript === script)
+        return EMPTY;
+    setGsapScript(parsed.document, newScript);
+    return gsapScriptChange(script, newScript);
+}
+function handleRemoveGsapProperty(parsed, animationId, property, from) {
+    const script = getGsapScript(parsed.document);
+    if (!script)
+        return EMPTY;
+    const newScript = removePropertyFromAnimation(script, animationId, property, from ?? false);
+    if (newScript === script)
+        return EMPTY;
+    setGsapScript(parsed.document, newScript);
+    return gsapScriptChange(script, newScript);
+}
+function handleRemoveGsapTween(parsed, animationId) {
+    const script = getGsapScript(parsed.document);
+    if (!script)
+        throw new Error("No GSAP script block found in the composition.");
+    const newScript = removeAnimationFromScript(script, animationId);
+    if (newScript === script)
+        return EMPTY;
+    setGsapScript(parsed.document, newScript);
+    return gsapScriptChange(script, newScript);
+}
+function handleRemoveAllKeyframes(parsed, animationId) {
+    const script = getGsapScript(parsed.document);
+    if (!script)
+        return EMPTY;
+    const newScript = removeAllKeyframesFromScript(script, animationId);
+    if (newScript === script)
+        return EMPTY;
+    setGsapScript(parsed.document, newScript);
+    return gsapScriptChange(script, newScript);
+}
+function handleConvertToKeyframes(parsed, animationId, resolvedFromValues) {
+    const script = getGsapScript(parsed.document);
+    if (!script)
+        return EMPTY;
+    const newScript = convertToKeyframesFromScript(script, animationId, resolvedFromValues);
+    if (newScript === script)
+        return EMPTY;
+    setGsapScript(parsed.document, newScript);
+    return gsapScriptChange(script, newScript);
+}
+function handleMaterializeKeyframes(parsed, animationId, keyframes, easeEach, resolvedSelector) {
+    const script = getGsapScript(parsed.document);
+    if (!script)
+        return EMPTY;
+    const newScript = materializeKeyframesFromScript(script, animationId, keyframes, easeEach, resolvedSelector);
+    if (newScript === script)
+        return EMPTY;
+    setGsapScript(parsed.document, newScript);
+    return gsapScriptChange(script, newScript);
+}
+function handleSplitIntoPropertyGroups(parsed, animationId) {
+    const script = getGsapScript(parsed.document);
+    if (!script)
+        return EMPTY;
+    const { script: newScript } = splitIntoPropertyGroupsFromScript(script, animationId);
+    if (newScript === script)
+        return EMPTY;
+    setGsapScript(parsed.document, newScript);
+    return gsapScriptChange(script, newScript);
+}
+function handleSplitAnimations(parsed, op) {
+    const script = getGsapScript(parsed.document);
+    if (!script)
+        return EMPTY;
+    const { script: newScript } = splitAnimationsInScript(script, {
+        originalId: op.originalId,
+        newId: op.newId,
+        splitTime: op.splitTime,
+        elementStart: op.elementStart,
+        elementDuration: op.elementDuration,
+    });
+    if (newScript === script)
+        return EMPTY;
+    setGsapScript(parsed.document, newScript);
+    return gsapScriptChange(script, newScript);
+}
+function handleArcPathScript(parsed, oldScript, newScript) {
+    if (newScript === oldScript)
+        return EMPTY;
+    setGsapScript(parsed.document, newScript);
+    return gsapScriptChange(oldScript, newScript);
+}
+function handleDeleteAllForSelector(parsed, selector) {
+    const script = getGsapScript(parsed.document);
+    if (!script)
+        return EMPTY;
+    const parsedForWrite = parseGsapScriptAcornForWrite(script);
+    if (!parsedForWrite)
+        return EMPTY;
+    // Compare quote-insensitively: [data-hf-id='x'] and [data-hf-id="x"] are the
+    // same selector. A strict === missed the alternate quote style and matched
+    // nothing while can() reported ok.
+    const wanted = selector.replace(/'/g, '"');
+    const matching = parsedForWrite.located.filter((l) => l.animation.targetSelector.replace(/'/g, '"') === wanted);
+    if (matching.length === 0)
+        return EMPTY;
+    let newScript = script;
+    for (const m of [...matching].reverse()) {
+        newScript = removeAnimationFromScript(newScript, m.id);
+    }
+    if (newScript === script)
+        return EMPTY;
+    setGsapScript(parsed.document, newScript);
+    // ponytail: skips stripStudioEditsFromTarget (data-hf-studio-path-offset cleanup) —
+    // studio path offset is cosmetic once all animations are gone; session reloads after write
+    return gsapScriptChange(script, newScript);
+}
+function resolveKeyframe(parsed, animationId, keyframeIndex) {
+    const script = getGsapScript(parsed.document);
+    if (!script)
+        return null;
+    const parsedForWrite = parseGsapScriptAcornForWrite(script);
+    const located = parsedForWrite?.located.find((l) => l.id === animationId);
+    const kfs = located?.animation.keyframes?.keyframes;
+    const kf = kfs?.[keyframeIndex];
+    if (!kfs || !kf || keyframeIndex < 0)
+        return null;
+    return { script, kf, kfs };
+}
+// fallow-ignore-next-line complexity
+function handleSetGsapKeyframe(parsed, animationId, keyframeIndex, position, value, ease) {
+    const resolved = resolveKeyframe(parsed, animationId, keyframeIndex);
+    if (!resolved)
+        return EMPTY;
+    const { script, kf: existingKf } = resolved;
+    const currentPct = existingKf.percentage;
+    const targetPct = position ?? currentPct;
+    const props = value
+        ? value
+        : { ...existingKf.properties };
+    const resolvedEase = ease ?? existingKf.ease;
+    let newScript = script;
+    if (targetPct !== currentPct) {
+        newScript = removeKeyframeFromScript(newScript, animationId, currentPct);
+        // Thread the same backfill defaults the add path uses so a move (remove +
+        // re-add at a new percentage) seeds new props into sibling keyframes the same
+        // way, keeping both entry points behaviorally identical.
+        newScript = addKeyframeToScript(newScript, animationId, targetPct, props, resolvedEase, deriveKeyframeBackfillDefaults(props));
+    }
+    else {
+        newScript = updateKeyframeInScript(newScript, animationId, currentPct, props, resolvedEase);
+    }
+    if (newScript === script)
+        return EMPTY;
+    setGsapScript(parsed.document, newScript);
+    return gsapScriptChange(script, newScript);
+}
+function handleAddGsapKeyframe(parsed, animationId, percentage, value) {
+    const script = getGsapScript(parsed.document);
+    if (!script)
+        throw new Error("No GSAP script block found in the composition.");
+    const props = value;
+    const newScript = addKeyframeToScript(script, animationId, percentage, props, undefined, deriveKeyframeBackfillDefaults(props));
+    if (newScript === script)
+        return EMPTY;
+    setGsapScript(parsed.document, newScript);
+    return gsapScriptChange(script, newScript);
+}
+function handleRemoveGsapKeyframeByPercentage(parsed, animationId, percentage) {
+    const script = getGsapScript(parsed.document);
+    if (!script)
+        return EMPTY;
+    const parsedForWrite = parseGsapScriptAcornForWrite(script);
+    const located = parsedForWrite?.located.find((l) => l.id === animationId);
+    const kfs = located?.animation.keyframes?.keyframes;
+    if (!kfs)
+        return EMPTY;
+    // No-op on ambiguity: duplicate-percentage keyframes can't be disambiguated.
+    const TOLERANCE = 0.001;
+    const matches = kfs.filter((k) => Math.abs(k.percentage - percentage) <= TOLERANCE);
+    const sole = matches[0];
+    if (matches.length !== 1 || !sole)
+        return EMPTY;
+    const pct = sole.percentage;
+    const newScript = removeKeyframeFromScript(script, animationId, pct);
+    if (newScript === script)
+        return EMPTY;
+    setGsapScript(parsed.document, newScript);
+    return gsapScriptChange(script, newScript);
+}
+function handleAddLabel(parsed, name, position) {
+    const script = getGsapScript(parsed.document);
+    if (!script)
+        return EMPTY;
+    const newScript = addLabelToScript(script, name, position);
+    if (newScript === script)
+        return EMPTY;
+    setGsapScript(parsed.document, newScript);
+    return gsapScriptChange(script, newScript);
+}
+function handleRemoveLabel(parsed, name) {
+    const script = getGsapScript(parsed.document);
+    if (!script)
+        return EMPTY;
+    const newScript = removeLabelFromScript(script, name);
+    if (newScript === script)
+        return EMPTY;
+    setGsapScript(parsed.document, newScript);
+    return gsapScriptChange(script, newScript);
+}
+// ─── Validation (can(op)) ────────────────────────────────────────────────────
+const CAN_OK = { ok: true };
+function canErr(code, message, hint) {
+    return hint ? { ok: false, code, message, hint } : { ok: false, code, message };
+}
+/** E_NO_GSAP_SCRIPT CanResult when the composition has no GSAP script, else null. */
+function gsapScriptMissing(parsed) {
+    return getGsapScript(parsed.document) === null
+        ? canErr("E_NO_GSAP_SCRIPT", "No GSAP script block found in the composition.", "This composition does not use GSAP animations.")
+        : null;
+}
+/** The located GSAP animation for `animationId`, or undefined. */
+function locateGsapAnimation(parsed, animationId) {
+    const script = getGsapScript(parsed.document);
+    if (!script)
+        return undefined;
+    return parseGsapScriptAcornForWrite(script)?.located.find((l) => l.id === animationId);
+}
+/**
+ * E_TARGET_NOT_FOUND CanResult when no GSAP animation resolves to `animationId`,
+ * else null. Without this, can() returned ok for stale/positional ids that then
+ * no-op'd at apply — the caller believed the edit would land.
+ */
+function gsapAnimationMissing(parsed, animationId) {
+    if (getGsapScript(parsed.document) === null)
+        return null; // reported by gsapScriptMissing
+    return locateGsapAnimation(parsed, animationId)
+        ? null
+        : canErr("E_TARGET_NOT_FOUND", `No GSAP animation found with id "${animationId}".`, "Animation ids are positional and shift after edits — re-read them from comp before dispatching.");
+}
+/** Validate updateArcSegment: the tween must have an enabled arc with that segment. */
+function validateArcSegment(parsed, op) {
+    const arc = locateGsapAnimation(parsed, op.animationId)?.animation.arcPath;
+    if (!arc?.enabled)
+        return canErr("E_ARC_NOT_ENABLED", `Animation "${op.animationId}" has no enabled arc path.`, "Call setArcPath({ enabled: true }) before updating a segment.");
+    if (op.segmentIndex < 0 || op.segmentIndex >= arc.segments.length)
+        return canErr("E_INVALID_ARGS", `Segment index ${op.segmentIndex} is out of range (0..${arc.segments.length - 1}).`);
+    return CAN_OK;
+}
+/** Dry-run validation — returns CanResult for the given op against current document state. */
+// fallow-ignore-next-line complexity
+export function validateOp(parsed, op) {
+    switch (op.type) {
+        case "setStyle":
+        case "setText":
+        case "setAttribute":
+        case "setTiming":
+        case "setHold":
+        case "moveElement":
+        case "removeElement": {
+            const ids = targets(op.target);
+            if (ids.length === 0)
+                return canErr("E_TARGET_NOT_FOUND", "No target ids provided.");
+            const missing = ids.filter((id) => resolveScoped(parsed.document, id) === null);
+            if (missing.length > 0)
+                return canErr("E_TARGET_NOT_FOUND", `Element(s) not found: ${missing.join(", ")}.`, "Verify the id against comp.getElements() or comp.find().");
+            return CAN_OK;
+        }
+        case "addElement": {
+            if (op.parent !== null && resolveScoped(parsed.document, op.parent) === null)
+                return canErr("E_TARGET_NOT_FOUND", `Parent element not found: "${op.parent}".`, "Verify the parent id against comp.getElements() or comp.find().");
+            if (op.index < 0)
+                return canErr("E_INVALID_ARGS", `index must be >= 0 (got ${op.index}).`);
+            if (!op.html || op.html.trim().length === 0)
+                return canErr("E_INVALID_HTML", "html must not be empty.");
+            // Parse to check for <script> and zero-element fragments.
+            // Use the same temp-div pattern as apply-patches.ts for consistency.
+            const tmp = parsed.document.createElement("div");
+            tmp.innerHTML = op.html;
+            if (tmp.firstElementChild === null)
+                return canErr("E_INVALID_HTML", "html parses to zero element nodes.");
+            if (tmp.querySelector("script") !== null)
+                return canErr("E_INVALID_HTML", "<script> elements are not permitted in addElement html.", "GSAP is managed by the composition's single script block; add tweens via addGsapTween.");
+            return CAN_OK;
+        }
+        case "reorderElements": {
+            if (op.entries.length === 0)
+                return CAN_OK;
+            const missing = op.entries
+                .map((e) => e.target)
+                .filter((id) => resolveScoped(parsed.document, id) === null);
+            if (missing.length > 0)
+                return canErr("E_TARGET_NOT_FOUND", `Element(s) not found: ${missing.join(", ")}.`, "Verify the id against comp.getElements() or comp.find().");
+            return CAN_OK;
+        }
+        case "setVariableValue":
+            if (findRoot(parsed.document) === null)
+                return canErr("E_NO_ROOT", "Composition root element not found.");
+            return CAN_OK;
+        case "setCompositionMetadata":
+        case "setClassStyle":
+            return CAN_OK;
+        case "addGsapTween":
+        case "addLabel": {
+            if (op.type === "addGsapTween" && resolveScoped(parsed.document, op.target) === null)
+                return canErr("E_TARGET_NOT_FOUND", `Element not found: ${op.target}.`, "Verify the id against comp.getElements() or comp.find().");
+            const script = getGsapScript(parsed.document);
+            if (!script)
+                return canErr("E_NO_GSAP_SCRIPT", "No GSAP script block found in the composition.", "This composition does not use GSAP animations.");
+            const p = parseGsapScriptAcornForWrite(script);
+            if (!p || !p.hasTimeline)
+                return canErr("E_NO_GSAP_TIMELINE", "No gsap.timeline() declaration found in the GSAP script.", "addGsapTween / addLabel require a timeline variable (e.g. var tl = gsap.timeline(...)).");
+            return CAN_OK;
+        }
+        case "setGsapTween":
+        case "setGsapKeyframe":
+        case "addGsapKeyframe":
+        case "removeGsapKeyframe":
+        case "removeGsapProperty":
+        case "removeGsapTween":
+        case "removeAllKeyframes":
+        case "convertToKeyframes":
+        case "splitIntoPropertyGroups":
+        case "setArcPath":
+        case "removeArcPath":
+            return gsapScriptMissing(parsed) ?? gsapAnimationMissing(parsed, op.animationId) ?? CAN_OK;
+        case "updateArcSegment":
+            return (gsapScriptMissing(parsed) ??
+                gsapAnimationMissing(parsed, op.animationId) ??
+                validateArcSegment(parsed, op));
+        case "splitAnimations":
+        case "deleteAllForSelector":
+        case "removeLabel":
+            return gsapScriptMissing(parsed) ?? CAN_OK;
+        case "addWithKeyframes":
+            return (gsapScriptMissing(parsed) ??
+                (op.keyframes.length === 0
+                    ? canErr("E_INVALID_ARGS", "addWithKeyframes requires at least one keyframe.", "An empty keyframe list would create an animation with no keyframes.")
+                    : CAN_OK));
+        case "replaceWithKeyframes":
+            return (gsapScriptMissing(parsed) ??
+                gsapAnimationMissing(parsed, op.animationId) ??
+                (op.keyframes.length === 0
+                    ? canErr("E_INVALID_ARGS", "replaceWithKeyframes requires at least one keyframe.", "An empty keyframe list would create an animation with no keyframes.")
+                    : CAN_OK));
+        case "unrollDynamicAnimations":
+            return (gsapScriptMissing(parsed) ??
+                gsapAnimationMissing(parsed, op.animationId) ??
+                (op.elements.length === 0
+                    ? canErr("E_INVALID_ARGS", "unrollDynamicAnimations requires at least one element.", "An empty element list would delete the animation; pass the resolved element list.")
+                    : CAN_OK));
+        case "materializeKeyframes":
+            return (gsapScriptMissing(parsed) ??
+                gsapAnimationMissing(parsed, op.animationId) ??
+                (op.keyframes.length === 0
+                    ? canErr("E_INVALID_ARGS", "materializeKeyframes requires at least one keyframe.", "An empty keyframe list would empty the animation; pass the resolved keyframes.")
+                    : CAN_OK));
+        default:
+            return canErr("E_UNKNOWN_OP", `Unknown op type: "${op.type}".`);
+    }
+}
+//# sourceMappingURL=mutate.js.map