@hyperframes/core 0.6.121 → 0.7.0

package/dist/parsers/gsapParser.js

@@ -1350,6 +1350,71 @@ function insertInheritedStateSet(script, selector, position, properties) {
     }
     return recast.print(parsed.ast).code;
 }
+/** Marker on Studio-emitted pre-keyframe hold `set`s. `data` is a GSAP-reserved
+ * config key (attached to the tween, never applied to the target), so it carries
+ * the tag without triggering GSAP's "Invalid property" warning. */
+const STUDIO_HOLD_MARKER = "hf-hold";
+/** True for a `tl.set(...)` this module emitted to hold a keyframe before its tween.
+ * The Studio filters these out so they never appear as user keyframes/diamonds. */
+export function isStudioHoldSet(anim) {
+    return anim.method === "set" && anim.properties?.data === STUDIO_HOLD_MARKER;
+}
+/**
+ * Keep a `tl.set(selector, {x,y}, 0)` "hold" in front of every position-keyframed
+ * tween that starts after t=0, so the element holds its first keyframe's position
+ * BEFORE the tween plays instead of snapping to its CSS base (the universal NLE
+ * "hold before first keyframe" behavior). The set is tagged with `data: "hf-hold"`
+ * so this pass owns it: every call wipes the prior holds and recomputes from the
+ * current keyframes, keeping them in sync as keyframes are added/moved/deleted.
+ *
+ * Idempotent. Only position props (x/y/xPercent/yPercent) are held — opacity/scale
+ * keep their authored pre-tween behavior. A tween already starting at 0 needs no
+ * hold (no gap before it).
+ */
+export function syncPositionHoldsBeforeKeyframes(script) {
+    let parsed;
+    try {
+        parsed = parseGsapScript(script);
+    }
+    catch {
+        return script;
+    }
+    // 1. Drop every hold this pass previously emitted, so we recompute fresh.
+    let result = script;
+    const staleHoldIds = parsed.animations.filter(isStudioHoldSet).map((a) => a.id);
+    for (const id of staleHoldIds)
+        result = removeAnimationFromScript(result, id);
+    // 2. Re-add a hold for each position-keyframed tween that starts after t=0.
+    let reparsed;
+    try {
+        reparsed = parseGsapScript(result);
+    }
+    catch {
+        return result;
+    }
+    for (const anim of reparsed.animations) {
+        if (!anim.keyframes)
+            continue;
+        const start = anim.resolvedStart ?? (typeof anim.position === "number" ? anim.position : 0);
+        if (!(start > 0.001))
+            continue;
+        const firstKf = [...anim.keyframes.keyframes].sort((a, b) => a.percentage - b.percentage)[0];
+        if (!firstKf)
+            continue;
+        const posProps = {};
+        for (const [k, v] of Object.entries(firstKf.properties)) {
+            if (classifyPropertyGroup(k) === "position" && typeof v === "number")
+                posProps[k] = v;
+        }
+        if (Object.keys(posProps).length === 0)
+            continue;
+        result = insertInheritedStateSet(result, anim.targetSelector, 0, {
+            ...posProps,
+            data: STUDIO_HOLD_MARKER,
+        });
+    }
+    return result;
+}
 // fallow-ignore-next-line complexity
 export function splitAnimationsInScript(script, opts) {
     const parsed = parseGsapScript(script);
@@ -1404,9 +1469,27 @@ export function splitAnimationsInScript(script, opts) {
             }
             continue;
         }
+        // `<=` (not `<`) is deliberate: a tween whose end coincides exactly with
+        // the split boundary has fully played by splitTime, so it belongs to the
+        // first half and contributes its resting state to the clone. The spanning
+        // branch below handles only strictly-mid-flight tweens (pos < split < end).
         if (animEnd <= opts.splitTime) {
-            for (const [k, v] of Object.entries(anim.properties)) {
-                inheritedProps[k] = v;
+            // Only a completed .from() reverts the element to its natural state, so
+            // its recorded properties are the HIDDEN start (e.g. opacity:0), not the
+            // resting state — clearing them keeps the clone at its natural value
+            // instead of pinning it to the from-values (which made it invisible).
+            // .fromTo() and .to() both END at their to-values (no revert), so they
+            // fall through to `else` and inherit `anim.properties` (the to-values) —
+            // .fromTo() must NOT join the .from() clear-branch or the clone would
+            // drop the very state the fromTo just established.
+            if (anim.method === "from") {
+                for (const k of Object.keys(anim.properties))
+                    delete inheritedProps[k];
+            }
+            else {
+                for (const [k, v] of Object.entries(anim.properties)) {
+                    inheritedProps[k] = v;
+                }
             }
             continue;
         }
@@ -1523,20 +1606,81 @@ function locateAnimation(script, animationId) {
     const target = parsed.located.find((l) => l.id === animationId);
     return target ? { parsed, target } : null;
 }
+// Animation ids encode the tween's timeline position in ms
+// (`#puck-a-to-1200-position`). A gesture/convert can re-emit a tween at a
+// different position, changing its id — so a client that cached the old id (its
+// selectedGsapAnimations hasn't refreshed) edits a now-nonexistent id and the op
+// no-ops. Parse `{selector}-{method}-{posMs}-{group}` so we can fall back to the
+// same selector+method+group tween nearest the requested position.
+const ANIM_ID_RE = /^(.*)-(fromTo|from|to|set)-(\d+)-([a-z]+)$/;
 function locateAnimationWithFallback(script, animationId) {
     const loc = locateAnimation(script, animationId);
     if (loc)
         return loc;
     const convertedId = animationId.replace(/-from-|-fromTo-/, "-to-");
-    if (convertedId === animationId)
+    if (convertedId !== animationId) {
+        const converted = locateAnimation(script, convertedId);
+        if (converted)
+            return converted;
+    }
+    // Position-drift fallback: match by stable identity (selector+method+group),
+    // disambiguating by the position closest to the one the caller asked for.
+    const want = ANIM_ID_RE.exec(animationId);
+    if (!want)
         return null;
-    return locateAnimation(script, convertedId);
+    const [, sel, method, wantPosStr, group] = want;
+    const wantPos = Number(wantPosStr);
+    let parsed;
+    try {
+        parsed = parseGsapAst(script);
+    }
+    catch {
+        return null;
+    }
+    let best = null;
+    let bestDist = Number.POSITIVE_INFINITY;
+    for (const l of parsed.located) {
+        const m = ANIM_ID_RE.exec(l.id);
+        if (!m || m[1] !== sel || m[2] !== method || m[4] !== group)
+            continue;
+        const dist = Math.abs(Number(m[3]) - wantPos);
+        if (dist < bestDist) {
+            best = l;
+            bestDist = dist;
+        }
+    }
+    return best ? { parsed, target: best } : null;
 }
 /** Find the keyframes ObjectExpression node on a tween's varsArg, or null. */
 function findKeyframesObjectNode(varsArg) {
     const node = findPropertyNode(varsArg, "keyframes");
     return node?.type === "ObjectExpression" ? node : null;
 }
+/**
+ * Convert array-form keyframes (`keyframes: [{x,y}, …]`) to even-percentage object
+ * form (`{ "0%": {…}, "33.3%": {…}, … }`) IN PLACE, returning the new object node
+ * (or null if not array-form). GSAP distributes an array evenly, so this is
+ * runtime-identical — but it gives the percentage-keyed write ops something to
+ * target. Needed before INSERTING a keyframe at an arbitrary percentage, which an
+ * even array can't host.
+ */
+function convertArrayKeyframesToObjectNode(varsArg) {
+    if (varsArg?.type !== "ObjectExpression")
+        return null;
+    const prop = (varsArg.properties ?? []).find((p) => isObjectProperty(p) && propKeyName(p) === "keyframes");
+    if (!prop || prop.value?.type !== "ArrayExpression")
+        return null;
+    const els = (prop.value.elements ?? []).filter((e) => !!e && e.type === "ObjectExpression");
+    const n = els.length;
+    if (n === 0)
+        return null;
+    const entries = els.map((el, i) => {
+        const pct = n > 1 ? Math.round((i / (n - 1)) * 1000) / 10 : 0;
+        return `${JSON.stringify(`${pct}%`)}: ${recast.print(el).code}`;
+    });
+    prop.value = parseExpr(`{ ${entries.join(", ")} }`);
+    return prop.value;
+}
 /** Filter percentage-keyed properties from a keyframes ObjectExpression. */
 function filterPercentageProps(kfNode) {
     return kfNode.properties.filter((p) => {
@@ -1584,6 +1728,11 @@ export function addKeyframeToScript(script, animationId, percentage, properties,
     if (!loc)
         return script;
     let kfNode = findKeyframesObjectNode(loc.target.call.varsArg);
+    // Array-form keyframes can't host an arbitrary new percentage — normalize to
+    // object form in place first. (convertToKeyframesInScript below only converts
+    // FLAT tweens; it early-returns when keyframes already exist.)
+    if (!kfNode)
+        kfNode = convertArrayKeyframesToObjectNode(loc.target.call.varsArg);
     if (!kfNode) {
         script = convertToKeyframesInScript(script, animationId);
         loc = locateAnimationWithFallback(script, animationId);
@@ -1687,6 +1836,43 @@ export function addKeyframeToScript(script, animationId, percentage, properties,
  * remaining keyframe's properties.
  */
 export function removeKeyframeFromScript(script, animationId, percentage) {
+    // Array-form keyframes (`keyframes: [{x,y}, …]`) have no explicit percentages —
+    // GSAP distributes them evenly. The object-form path below can't see them
+    // (findKeyframesObjectNode only matches ObjectExpression), so removing from an
+    // array-form tween silently no-op'd. Resolve the element by its implicit
+    // percentage and splice it; collapse to a flat tween when fewer than two remain.
+    const arrLoc = locateAnimationWithFallback(script, animationId);
+    // findPropertyNode here returns the property's VALUE node directly.
+    const arrVal = arrLoc && findPropertyNode(arrLoc.target.call.varsArg, "keyframes");
+    if (arrLoc && arrVal?.type === "ArrayExpression") {
+        const elements = (arrVal.elements ?? []).filter((e) => !!e && e.type === "ObjectExpression");
+        const n = elements.length;
+        if (n === 0)
+            return script;
+        let matchIdx = -1;
+        let bestDist = Number.POSITIVE_INFINITY;
+        for (let i = 0; i < n; i++) {
+            const pct = n > 1 ? (i / (n - 1)) * 100 : 0;
+            const dist = Math.abs(pct - percentage);
+            if (dist <= PCT_TOLERANCE && dist < bestDist) {
+                matchIdx = i;
+                bestDist = dist;
+            }
+        }
+        if (matchIdx === -1)
+            return script;
+        const remaining = elements.filter((_, i) => i !== matchIdx);
+        if (remaining.length < 2) {
+            const sole = remaining[0];
+            const record = sole ? objectExpressionToRecord(sole, arrLoc.parsed.scope) : {};
+            collapseKeyframesToFlat(arrLoc.target.call.varsArg, record);
+        }
+        else {
+            const realIdx = arrVal.elements.indexOf(elements[matchIdx]);
+            arrVal.elements.splice(realIdx, 1);
+        }
+        return recast.print(arrLoc.parsed.ast).code;
+    }
     const ctx = locateKeyframeCtx(script, animationId, percentage);
     if (!ctx)
         return script;
@@ -1709,6 +1895,35 @@ export function removeKeyframeFromScript(script, animationId, percentage) {
  * Replace the properties (and optionally ease) at an existing keyframe percentage.
  */
 export function updateKeyframeInScript(script, animationId, percentage, properties, ease) {
+    // Array-form keyframes (`keyframes: [{x,y}, …]`) have no explicit percentages —
+    // GSAP distributes them evenly. The percentage-keyed object path below can't
+    // match them (findKeyframesObjectNode only matches ObjectExpression), so dragging
+    // a motion-path node on an array-authored tween silently no-op'd. Resolve the
+    // element by its implicit percentage and replace it in place. Mirrors the array
+    // branch in removeKeyframeFromScript.
+    const arrLoc = locateAnimationWithFallback(script, animationId);
+    const arrVal = arrLoc && findPropertyNode(arrLoc.target.call.varsArg, "keyframes");
+    if (arrLoc && arrVal?.type === "ArrayExpression") {
+        const elements = (arrVal.elements ?? []).filter((e) => !!e && e.type === "ObjectExpression");
+        const n = elements.length;
+        if (n === 0)
+            return script;
+        let matchIdx = -1;
+        let bestDist = Number.POSITIVE_INFINITY;
+        for (let i = 0; i < n; i++) {
+            const pct = n > 1 ? (i / (n - 1)) * 100 : 0;
+            const dist = Math.abs(pct - percentage);
+            if (dist <= PCT_TOLERANCE && dist < bestDist) {
+                matchIdx = i;
+                bestDist = dist;
+            }
+        }
+        if (matchIdx === -1)
+            return script;
+        const realIdx = arrVal.elements.indexOf(elements[matchIdx]);
+        arrVal.elements[realIdx] = buildKeyframeValueNode(properties, ease);
+        return recast.print(arrLoc.parsed.ast).code;
+    }
     const ctx = locateKeyframeCtx(script, animationId, percentage);
     if (!ctx)
         return script;
@@ -1991,6 +2206,135 @@ export function updateArcSegmentInScript(script, animationId, segmentIndex, upda
     }
     return recast.print(loc.parsed.ast).code;
 }
+/**
+ * Move a single motionPath waypoint (anchor) to a new position. The waypoint
+ * list is normalized to anchors for both straight and cubic paths, so
+ * `pointIndex` matches the node order the studio overlay renders; cubic control
+ * points are preserved. No-op when the animation/arc is missing or the index is
+ * out of range.
+ */
+export function updateMotionPathPointInScript(script, animationId, pointIndex, point) {
+    const loc = locateAnimation(script, animationId);
+    if (!loc)
+        return script;
+    const anim = loc.target.animation;
+    if (!anim.arcPath?.enabled)
+        return script;
+    const waypoints = extractArcWaypoints(anim);
+    if (pointIndex < 0 || pointIndex >= waypoints.length || waypoints.length < 2)
+        return script;
+    const nextWaypoints = waypoints.map((wp, i) => i === pointIndex ? { x: point.x, y: point.y } : wp);
+    const motionPathCode = buildMotionPathObjectCode({
+        waypoints: nextWaypoints,
+        segments: anim.arcPath.segments,
+        autoRotate: anim.arcPath.autoRotate,
+    });
+    const varsArg = loc.target.call.varsArg;
+    const existingProp = varsArg.properties.find((p) => isObjectProperty(p) && propKeyName(p) === "motionPath");
+    if (existingProp) {
+        existingProp.value = parseExpr(motionPathCode);
+    }
+    return recast.print(loc.parsed.ast).code;
+}
+/** True when any segment carries explicit cubic control points. Add/remove are
+ *  restricted to curviness (non-cubic) paths — synthesizing control points for
+ *  an inserted cubic anchor is out of scope. */
+function hasCubicSegments(segments) {
+    return segments.some((s) => s.cp1 != null || s.cp2 != null);
+}
+function writeMotionPathValue(loc, waypoints, segments, autoRotate) {
+    const motionPathCode = buildMotionPathObjectCode({ waypoints, segments, autoRotate });
+    const varsArg = loc.target.call.varsArg;
+    const existingProp = varsArg.properties.find((p) => isObjectProperty(p) && propKeyName(p) === "motionPath");
+    if (existingProp)
+        existingProp.value = parseExpr(motionPathCode);
+    return recast.print(loc.parsed.ast).code;
+}
+/**
+ * Insert a waypoint at `index` (between existing anchors), splitting the segment
+ * it lands on so the new neighbor inherits its curviness. Non-cubic paths only.
+ * No-op for missing animation/arc, out-of-range index, or cubic paths.
+ */
+export function addMotionPathPointInScript(script, animationId, index, point) {
+    const loc = locateAnimation(script, animationId);
+    if (!loc)
+        return script;
+    const anim = loc.target.animation;
+    if (!anim.arcPath?.enabled || hasCubicSegments(anim.arcPath.segments))
+        return script;
+    const waypoints = extractArcWaypoints(anim);
+    // Insert strictly between two anchors: index 1..length-1.
+    if (index < 1 || index > waypoints.length - 1)
+        return script;
+    const segments = [...anim.arcPath.segments];
+    waypoints.splice(index, 0, { x: point.x, y: point.y });
+    const splitCurviness = segments[index - 1]?.curviness ?? 1;
+    segments.splice(index - 1, 0, { curviness: splitCurviness });
+    return writeMotionPathValue(loc, waypoints, segments, anim.arcPath.autoRotate);
+}
+/**
+ * Remove the waypoint at `index`. Refuses to drop below two anchors (a path
+ * can't have fewer). Non-cubic paths only. No-op for missing animation/arc,
+ * out-of-range index, cubic paths, or a 2-point path.
+ */
+export function removeMotionPathPointInScript(script, animationId, index) {
+    const loc = locateAnimation(script, animationId);
+    if (!loc)
+        return script;
+    const anim = loc.target.animation;
+    if (!anim.arcPath?.enabled || hasCubicSegments(anim.arcPath.segments))
+        return script;
+    const waypoints = extractArcWaypoints(anim);
+    if (waypoints.length <= 2 || index < 0 || index >= waypoints.length)
+        return script;
+    const segments = [...anim.arcPath.segments];
+    waypoints.splice(index, 1);
+    // Drop the segment on the side that still exists (last anchor → preceding segment).
+    segments.splice(Math.min(index, segments.length - 1), 1);
+    return writeMotionPathValue(loc, waypoints, segments, anim.arcPath.autoRotate);
+}
+/**
+ * Author a fresh 2-anchor motionPath tween on a target element: a straight line
+ * from the element's home (0,0) to `point`, gentle ease, ready for waypoint
+ * editing. Mirrors `addAnimationWithKeyframesToScript`.
+ */
+export function addMotionPathToScript(script, targetSelector, position, duration, point, ease = "power1.inOut") {
+    // `id: null` on the failure paths is a deliberate sentinel: callers must
+    // null-check before chaining (e.g. locating the new tween). An empty string
+    // would silently flow into selector/locate calls and match nothing.
+    let parsed;
+    try {
+        parsed = parseGsapAst(script);
+    }
+    catch (e) {
+        console.warn("[gsap-parser] addMotionPathToScript parse failed:", e);
+        return { script, id: null };
+    }
+    if (parsed.located.length === 0 && parsed.detection.timelineVar === null) {
+        return { script, id: null };
+    }
+    const motionPathCode = buildMotionPathObjectCode({
+        waypoints: [
+            { x: 0, y: 0 },
+            { x: point.x, y: point.y },
+        ],
+        segments: [{ curviness: 1 }],
+        autoRotate: false,
+    });
+    const selector = JSON.stringify(targetSelector);
+    const varEntries = [
+        `motionPath: ${motionPathCode}`,
+        `duration: ${valueToCode(duration)}`,
+        `ease: ${JSON.stringify(ease)}`,
+    ];
+    const stmtCode = `${parsed.timelineVar}.to(${selector}, { ${varEntries.join(", ")} }, ${valueToCode(position)});`;
+    const newStatement = parseScript(stmtCode).program.body[0];
+    insertAfterAnchor(parsed, newStatement);
+    const result = recast.print(parsed.ast).code;
+    const reParsed = parseGsapAst(result);
+    const newId = reParsed.located[reParsed.located.length - 1]?.id ?? null;
+    return { script: result, id: newId };
+}
 export function removeArcPathFromScript(script, animationId) {
     return setArcPathInScript(script, animationId, {
         enabled: false,