@hyperframes/parsers 0.7.15 → 0.7.17

package/dist/gsapSerialize-Bei7m7M7.d.ts

@@ -0,0 +1,166 @@
+import { K as Keyframe, V as ValidationResult } from './types-Cg0ZTXEf.js';
+import { PropertyGroupName } from './gsapConstants.js';
+
+/**
+ * Recast-free GSAP helpers: serialization, keyframe<->animation conversion,
+ * validation, and shared types.
+ *
+ * This module MUST NOT import recast / @babel/parser. It is part of the
+ * isomorphic core layer that the barrel and browser code depend on. AST
+ * parsing of GSAP source lives in the Node-only `./gsapParser` module.
+ */
+
+type GsapMethod = "set" | "to" | "from" | "fromTo";
+/** How a tween was constructed in source — drives display classification and editability. */
+type GsapProvenanceKind = "literal" | "helper" | "loop" | "runtime-dynamic";
+/**
+ * Origin of a parsed tween. `literal` tweens map 1:1 to a source call and edit
+ * directly; `helper`/`loop` tweens are expanded from a reused construct (unroll
+ * to edit); `runtime-dynamic` tweens come from live introspection (override to
+ * edit). Absent provenance is treated as `literal`.
+ */
+interface GsapProvenance {
+    kind: GsapProvenanceKind;
+    /** Helper function name (kind === "helper"). */
+    fn?: string;
+    /** 1-based ordinal of the originating call site / loop construct in source order. */
+    callSite?: number;
+    /** 0-based iteration index (kind === "loop"). */
+    iteration?: number;
+    /** Source offset [start, end] of the originating call/loop, when known. */
+    sourceRange?: [number, number];
+}
+/** How a tween's keyframes can be edited, derived from its provenance. */
+type KeyframeEditability = "direct" | "unroll" | "source";
+/**
+ * Map provenance to an editing strategy:
+ * - `direct` — literal tween, maps 1:1 to source; edit in place.
+ * - `unroll` — helper/loop expansion; unroll to literal tweens, then edit.
+ * - `source` — runtime-dynamic value; not statically editable, edit the code.
+ */
+declare function editabilityForProvenance(provenance?: GsapProvenance): KeyframeEditability;
+interface GsapAnimation {
+    id: string;
+    targetSelector: string;
+    method: GsapMethod;
+    position: number | string;
+    properties: Record<string, number | string>;
+    fromProperties?: Record<string, number | string>;
+    duration?: number;
+    ease?: string;
+    /** Non-editable GSAP config (stagger, yoyo, repeat, etc.) preserved for round-trips. */
+    extras?: Record<string, unknown>;
+    /** Native GSAP keyframes data — present when the tween uses keyframes: { ... }. */
+    keyframes?: GsapKeyframesData;
+    /** Arc motion path config — present when the tween uses motionPath for curved position interpolation. */
+    arcPath?: ArcPathConfig;
+    /** True when the tween has a `keyframes` property that couldn't be statically resolved (dynamic). */
+    hasUnresolvedKeyframes?: boolean;
+    /** True when the tween's target selector couldn't be statically resolved (dynamic). */
+    hasUnresolvedSelector?: boolean;
+    /** Absolute start time computed by walking the timeline chain (handles +=, -=, <, >, labels). */
+    resolvedStart?: number;
+    /** True when no position arg was authored — the tween is sequentially placed by GSAP. */
+    implicitPosition?: boolean;
+    /** Which property group this tween belongs to (position, scale, size, rotation, visual, other).
+     *  Undefined for legacy mixed tweens that bundle multiple groups. */
+    propertyGroup?: PropertyGroupName;
+    /** True for a base `gsap.set(...)` (a static hold that runs immediately, OFF the
+     *  timeline) rather than `tl.set(...)`. Carries no timeline position and shows no
+     *  keyframe marker — used to persist a static value (e.g. a 3D transform) without
+     *  introducing a 0% keyframe. */
+    global?: boolean;
+    /** How this tween was constructed in source. Absent ⇒ literal. */
+    provenance?: GsapProvenance;
+}
+interface GsapPercentageKeyframe {
+    percentage: number;
+    properties: Record<string, number | string>;
+    ease?: string;
+}
+type GsapKeyframeFormat = "percentage" | "object-array" | "simple-array";
+interface GsapKeyframesData {
+    format: GsapKeyframeFormat;
+    keyframes: GsapPercentageKeyframe[];
+    ease?: string;
+    easeEach?: string;
+}
+interface ArcPathSegment {
+    curviness: number;
+    cp1?: {
+        x: number;
+        y: number;
+    };
+    cp2?: {
+        x: number;
+        y: number;
+    };
+}
+interface ArcPathConfig {
+    enabled: boolean;
+    autoRotate: boolean | number;
+    segments: ArcPathSegment[];
+}
+interface MotionPathShape {
+    arcPath: ArcPathConfig;
+    waypoints: Array<{
+        x: number;
+        y: number;
+    }>;
+}
+/**
+ * Build arcPath segments + waypoints from resolved path coordinates. Shared by
+ * the AST parser (coords from literal nodes) and the runtime scanner (coords
+ * from a live `vars.motionPath`), so both produce identical arc config.
+ */
+declare function buildArcPath(coords: Array<{
+    x: number;
+    y: number;
+}>, curviness: number, autoRotate: boolean | number, isCubic: boolean): MotionPathShape | undefined;
+interface ParsedGsap {
+    animations: GsapAnimation[];
+    timelineVar: string;
+    preamble: string;
+    postamble: string;
+    multipleTimelines?: boolean;
+    unsupportedTimelinePattern?: boolean;
+}
+
+interface SplitAnimationsOptions {
+    originalId: string;
+    newId: string;
+    splitTime: number;
+    elementStart: number;
+    elementDuration: number;
+}
+interface SplitAnimationsResult {
+    script: string;
+    /** Non-ID-selector animations that the engine cannot safely retarget. */
+    skippedSelectors: string[];
+}
+declare function serializeGsapAnimations(animations: GsapAnimation[], timelineVar?: string, options?: {
+    includeMediaSync?: boolean;
+    preamble?: string;
+    postamble?: string;
+}): string;
+/**
+ * Filter animations to those targeting `#<elementId>` (id-only match). For the
+ * studio panel's id-OR-selector matching, see `getAnimationsForElement` in
+ * `useGsapTweenCache.ts` — distinct on purpose, hence the distinct name.
+ */
+declare function getAnimationsForElementId(animations: GsapAnimation[], elementId: string): GsapAnimation[];
+declare function validateCompositionGsap(script: string): ValidationResult;
+declare function keyframesToGsapAnimations(elementId: string, keyframes: Keyframe[], elementStartTime: number, base?: {
+    x?: number;
+    y?: number;
+    scale?: number;
+}): GsapAnimation[];
+declare function gsapAnimationsToKeyframes(animations: GsapAnimation[], elementStartTime: number, options?: {
+    baseX?: number;
+    baseY?: number;
+    baseScale?: number;
+    clampTimeToZero?: boolean;
+    skipBaseSet?: boolean;
+}): Keyframe[];
+
+export { type ArcPathConfig as A, type GsapAnimation as G, type KeyframeEditability as K, type MotionPathShape as M, type ParsedGsap as P, type SplitAnimationsOptions as S, type ArcPathSegment as a, type GsapKeyframesData as b, type GsapMethod as c, type GsapPercentageKeyframe as d, type GsapProvenance as e, type GsapProvenanceKind as f, type SplitAnimationsResult as g, editabilityForProvenance as h, getAnimationsForElementId as i, gsapAnimationsToKeyframes as j, keyframesToGsapAnimations as k, buildArcPath as l, type GsapKeyframeFormat as m, serializeGsapAnimations as s, validateCompositionGsap as v };

package/dist/gsapWriterAcorn.d.ts

@@ -1,4 +1,5 @@
-import { G as GsapAnimation, A as ArcPathConfig, S as SplitAnimationsOptions, g as SplitAnimationsResult, a as ArcPathSegment } from './gsapSerialize-B_JRTCeV.js';
+import { G as GsapAnimation, A as ArcPathConfig, S as SplitAnimationsOptions, g as SplitAnimationsResult, a as ArcPathSegment } from './gsapSerialize-Bei7m7M7.js';
+import './types-Cg0ZTXEf.js';
 import './gsapConstants.js';
 
 declare function updateAnimationInScript(script: string, animationId: string, updates: Partial<GsapAnimation> & {

package/dist/gsapWriterAcorn.js

@@ -370,6 +370,31 @@ function objectExpressionToRecord(node, scope, source) {
 function isGsapTimelineCall(node) {
   return node?.type === "CallExpression" && node.callee?.type === "MemberExpression" && node.callee.object?.name === "gsap" && node.callee.property?.name === "timeline";
 }
+function staticMemberKey(node) {
+  if (!node || node.type !== "MemberExpression") return null;
+  if (node.computed) {
+    const p = node.property;
+    if (p?.type === "Literal" && typeof p.value === "string") return p.value;
+    return null;
+  }
+  return node.property?.type === "Identifier" ? node.property.name : null;
+}
+function isStaticMemberRef(node) {
+  return node?.type === "MemberExpression" && staticMemberKey(node) !== null;
+}
+function sameMemberAccess(a, b) {
+  if (a?.type !== "MemberExpression" || b?.type !== "MemberExpression") return false;
+  if (staticMemberKey(a) !== staticMemberKey(b) || staticMemberKey(a) === null) return false;
+  const ao = a.object;
+  const bo = b.object;
+  if (ao?.type === "Identifier" && bo?.type === "Identifier") return ao.name === bo.name;
+  if (ao?.type === "MemberExpression" && bo?.type === "MemberExpression")
+    return sameMemberAccess(ao, bo);
+  return false;
+}
+function timelineRootSource(ref, script) {
+  return ref.kind === "identifier" ? ref.name : script.slice(ref.node.start, ref.node.end);
+}
 function extractTimelineDefaults(callNode, scope) {
   const arg = callNode.arguments?.[0];
   if (!arg || arg.type !== "ObjectExpression") return void 0;
@@ -389,6 +414,7 @@ function extractTimelineDefaults(callNode, scope) {
 }
 function findTimelineVar(ast, scope) {
   let timelineVar = null;
+  let ref = null;
   let timelineCount = 0;
   let defaults;
   const emptyScope = scope ?? /* @__PURE__ */ new Map();
@@ -396,8 +422,9 @@ function findTimelineVar(ast, scope) {
     VariableDeclarator(node) {
       if (isGsapTimelineCall(node.init)) {
         timelineCount += 1;
-        if (!timelineVar) {
-          timelineVar = node.id?.name ?? null;
+        if (!ref && node.id?.type === "Identifier") {
+          timelineVar = node.id.name;
+          ref = { kind: "identifier", name: node.id.name };
           defaults = extractTimelineDefaults(node.init, emptyScope);
         }
       }
@@ -405,15 +432,21 @@ function findTimelineVar(ast, scope) {
     AssignmentExpression(node) {
       if (isGsapTimelineCall(node.right)) {
         timelineCount += 1;
-        if (!timelineVar) {
+        if (!ref) {
           const left = node.left;
-          if (left?.type === "Identifier") timelineVar = left.name;
-          defaults = extractTimelineDefaults(node.right, emptyScope);
+          if (left?.type === "Identifier") {
+            timelineVar = left.name;
+            ref = { kind: "identifier", name: left.name };
+            defaults = extractTimelineDefaults(node.right, emptyScope);
+          } else if (isStaticMemberRef(left)) {
+            ref = { kind: "member", node: left };
+            defaults = extractTimelineDefaults(node.right, emptyScope);
+          }
         }
       }
     }
   });
-  return { timelineVar, timelineCount, defaults };
+  return { timelineVar, ref, timelineCount, defaults };
 }
 var BUILTIN_VAR_KEYS = /* @__PURE__ */ new Set(["duration", "ease", "delay"]);
 var DROPPED_VAR_KEYS = /* @__PURE__ */ new Set(["onComplete", "onStart", "onUpdate", "onRepeat"]);
@@ -426,14 +459,15 @@ var EXTRAS_KEYS = /* @__PURE__ */ new Set([
   "overwrite",
   "immediateRender"
 ]);
-function isTimelineRootedCall(callNode, timelineVar) {
+function isTimelineRootedCall(callNode, ref) {
   let obj = callNode.callee?.object;
   while (obj?.type === "CallExpression") {
     obj = obj.callee?.object;
   }
-  return obj?.type === "Identifier" && obj.name === timelineVar;
+  if (ref.kind === "identifier") return obj?.type === "Identifier" && obj.name === ref.name;
+  return sameMemberAccess(obj, ref.node);
 }
-function findAllTweenCalls(ast, timelineVar, scope, targetBindings) {
+function findAllTweenCalls(ast, ref, scope, targetBindings) {
   const results = [];
   function visit(node, ancestors) {
     if (!node || typeof node !== "object") return;
@@ -442,7 +476,7 @@ function findAllTweenCalls(ast, timelineVar, scope, targetBindings) {
       const callee = node.callee;
       const gsapSetArg = node.arguments?.[0];
       const isGlobalSet = callee?.type === "MemberExpression" && callee.object?.type === "Identifier" && callee.object.name === "gsap" && callee.property?.type === "Identifier" && callee.property.name === "set" && (gsapSetArg?.type === "StringLiteral" || gsapSetArg?.type === "Literal" && typeof gsapSetArg.value === "string");
-      if (callee?.type === "MemberExpression" && callee.property?.type === "Identifier" && (isTimelineRootedCall(node, timelineVar) || isGlobalSet) && GSAP_METHODS.has(callee.property.name)) {
+      if (callee?.type === "MemberExpression" && callee.property?.type === "Identifier" && (isTimelineRootedCall(node, ref) || isGlobalSet) && GSAP_METHODS.has(callee.property.name)) {
         const method = callee.property.name;
         const args = node.arguments;
         const selectorValue = args.length >= 1 ? resolveTargetSelector(args[0], nodeAncestors, scope, targetBindings) ?? "__unresolved__" : "__unresolved__";
@@ -895,8 +929,9 @@ function parseGsapScriptAcornForWrite(script) {
     const scope = collectScopeBindings(ast);
     const targetBindings = collectTargetBindings(ast, scope);
     const detection = findTimelineVar(ast, scope);
-    const timelineVar = detection.timelineVar ?? "tl";
-    const calls = findAllTweenCalls(ast, timelineVar, scope, targetBindings);
+    const ref = detection.ref ?? { kind: "identifier", name: "tl" };
+    const timelineVar = timelineRootSource(ref, script);
+    const calls = findAllTweenCalls(ast, ref, scope, targetBindings);
     sortBySourcePosition(calls);
     const rawAnims = calls.map((call) => tweenCallToAnimation(call, scope, script));
     applyTimelineDefaults(rawAnims, detection.defaults);
@@ -907,7 +942,7 @@ function parseGsapScriptAcornForWrite(script) {
       call,
       animation: animations[i]
     }));
-    return { ast, timelineVar, hasTimeline: detection.timelineVar !== null, located };
+    return { ast, timelineVar, hasTimeline: detection.ref !== null, located };
   } catch {
     return null;
   }
@@ -1063,9 +1098,11 @@ function reconcileEditableProps(ms, objNode, source, newProps, nonEditableOverri
   }
   ms.overwrite(objNode.start, objNode.end, `{ ${entries.join(", ")} }`);
 }
-function isTimelineRooted(node, timelineVar) {
+function isTimelineRooted(node, timelineVar, script) {
   if (node?.type === "Identifier") return node.name === timelineVar;
-  if (node?.type === "CallExpression") return isTimelineRooted(node.callee?.object, timelineVar);
+  if (node?.type === "MemberExpression") return script.slice(node.start, node.end) === timelineVar;
+  if (node?.type === "CallExpression")
+    return isTimelineRooted(node.callee?.object, timelineVar, script);
   return false;
 }
 function findInsertionPoint(parsed) {
@@ -1372,10 +1409,17 @@ function updateKeyframeInScript(script, animationId, percentage, properties, eas
   if (kfPropNode.value?.type !== "ObjectExpression") return script;
   const match = findKfPropByPct(kfPropNode.value, percentage);
   if (!match) return script;
-  const record = { ...properties };
-  if (ease) record.ease = ease;
   const ms = new MagicString(script);
-  ms.overwrite(match.prop.value.start, match.prop.value.end, recordToCode(record));
+  if (match.prop.value?.type === "ObjectExpression") {
+    for (const [k, v] of Object.entries(properties)) {
+      upsertProp(ms, match.prop.value, k, v);
+    }
+    if (ease !== void 0) upsertProp(ms, match.prop.value, "ease", ease);
+  } else {
+    const record = { ...properties };
+    if (ease) record.ease = ease;
+    ms.overwrite(match.prop.value.start, match.prop.value.end, recordToCode(record));
+  }
   return ms.toString();
 }
 function updateArrayKeyframeByPct(script, arrayNode, percentage, properties, ease) {
@@ -1854,18 +1898,18 @@ function splitIntoPropertyGroupsFromScript(script, animationId) {
   const newIds = (reParsed?.located ?? []).filter((l) => l.animation.targetSelector === animation.targetSelector).map((l) => l.id);
   return { script: result, ids: newIds };
 }
-function isTimelineMethodCall(expr, timelineVar, method) {
-  return expr?.type === "CallExpression" && expr.callee?.type === "MemberExpression" && isTimelineRooted(expr.callee.object, timelineVar) && expr.callee.property?.name === method;
+function isTimelineMethodCall(expr, timelineVar, method, script) {
+  return expr?.type === "CallExpression" && expr.callee?.type === "MemberExpression" && isTimelineRooted(expr.callee.object, timelineVar, script) && expr.callee.property?.name === method;
 }
-function isAddLabelCall(expr, timelineVar, name) {
+function isAddLabelCall(expr, timelineVar, name, script) {
   const firstArg = expr?.arguments?.[0];
-  return isTimelineMethodCall(expr, timelineVar, "addLabel") && firstArg?.type === "Literal" && firstArg.value === name;
+  return isTimelineMethodCall(expr, timelineVar, "addLabel", script) && firstArg?.type === "Literal" && firstArg.value === name;
 }
-function findLabelStatements(parsed, name) {
+function findLabelStatements(parsed, name, script) {
   const targets = [];
   acornWalk2.simple(parsed.ast, {
     ExpressionStatement(node) {
-      if (isAddLabelCall(node.expression, parsed.timelineVar, name)) targets.push(node);
+      if (isAddLabelCall(node.expression, parsed.timelineVar, name, script)) targets.push(node);
     }
   });
   return targets;
@@ -1873,7 +1917,7 @@ function findLabelStatements(parsed, name) {
 function addLabelToScript(script, name, position) {
   const parsed = parseGsapScriptAcornForWrite(script);
   if (!parsed) return script;
-  const existing = findLabelStatements(parsed, name)[0];
+  const existing = findLabelStatements(parsed, name, script)[0];
   if (existing) {
     const ms2 = new MagicString(script);
     const posArg = existing.expression.arguments?.[1];
@@ -1891,7 +1935,7 @@ function addLabelToScript(script, name, position) {
 function removeLabelFromScript(script, name) {
   const parsed = parseGsapScriptAcornForWrite(script);
   if (!parsed) return script;
-  const targets = findLabelStatements(parsed, name);
+  const targets = findLabelStatements(parsed, name, script);
   if (!targets.length) return script;
   const ms = new MagicString(script);
   for (const target of targets) {