@remotion/gsap 4.0.517

package/README.md

@@ -0,0 +1,18 @@
+# @remotion/gsap
+
+Use GSAP timelines in Remotion
+
+[![NPM Downloads](https://img.shields.io/npm/dm/@remotion/gsap.svg?style=flat&color=black&label=Downloads)](https://npmcharts.com/compare/@remotion/gsap?minimal=true)
+
+## Installation
+
+```bash
+npm install @remotion/gsap --save-exact
+```
+
+When installing a Remotion package, make sure to align the version of all `remotion` and `@remotion/*` packages to the same version.
+Remove the `^` character from the version number to use the exact version.
+
+## Usage
+
+See the [documentation](https://www.remotion.dev/docs/gsap) for more information.

package/dist/esm/index.mjs

@@ -0,0 +1,390 @@
+// src/use-gsap-timeline.ts
+import { gsap } from "gsap";
+import { useLayoutEffect, useRef, useState } from "react";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+
+// src/frame-time.ts
+var frameToSeconds = (frame, fps) => {
+  if (!Number.isFinite(frame)) {
+    throw new TypeError(`frame must be finite, received ${String(frame)}`);
+  }
+  if (!Number.isFinite(fps) || fps <= 0) {
+    throw new RangeError(`fps must be a positive finite number, received ${String(fps)}`);
+  }
+  return Math.max(0, frame) / fps;
+};
+
+// src/use-gsap-timeline.ts
+var EMPTY_DEPENDENCIES = [];
+var CALLBACK_KEYS = [
+  "onStart",
+  "onUpdate",
+  "onComplete",
+  "onRepeat",
+  "onReverseComplete",
+  "onInterrupt"
+];
+var getTimelineAnimations = (timeline) => [
+  timeline,
+  ...timeline.getChildren(true, true, true)
+];
+var animationVars = (animation) => animation.vars;
+var isWalkable = (value) => {
+  if (typeof value !== "object" || value === null)
+    return false;
+  if (Array.isArray(value))
+    return true;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+};
+var findCallbacksInValue = (value, seen = new Set) => {
+  if (!isWalkable(value) || seen.has(value)) {
+    return [];
+  }
+  seen.add(value);
+  const entries = Array.isArray(value) ? value.map((entry, index) => [String(index), entry]) : Object.entries(value);
+  const found = [];
+  for (const [key, nestedValue] of entries) {
+    if (CALLBACK_KEYS.includes(key) && typeof nestedValue === "function") {
+      found.push(key);
+    }
+    found.push(...findCallbacksInValue(nestedValue, seen));
+  }
+  return [...new Set(found)];
+};
+var findTimelineCallbacks = (timeline) => {
+  const animations = getTimelineAnimations(timeline);
+  return [
+    ...new Set(animations.flatMap((animation) => findCallbacksInValue(animationVars(animation))))
+  ];
+};
+var isElementTarget = (target) => typeof target === "object" && target !== null && target.nodeType === 1;
+var describeTarget = (target) => {
+  if (target === null) {
+    return "null";
+  }
+  if (typeof target !== "object") {
+    return typeof target;
+  }
+  const keys = Object.keys(target).filter((key) => key !== "_gsap");
+  const preview = keys.slice(0, 3).join(", ");
+  return `plain object {${preview}${keys.length > 3 ? ", …" : ""}}`;
+};
+var findNonElementTargets = (timeline) => {
+  const found = [];
+  for (const animation of getTimelineAnimations(timeline)) {
+    const targets = animation.targets?.();
+    if (!targets) {
+      continue;
+    }
+    for (const target of targets) {
+      if (!isElementTarget(target)) {
+        found.push(describeTarget(target));
+      }
+    }
+  }
+  return [...new Set(found)];
+};
+var GSAP_RANDOM_TOKEN = /random\(\s*(-?[\d.]|\[)/;
+var findNondeterministicVars = (value, seen = new Set) => {
+  if (typeof value === "string") {
+    return GSAP_RANDOM_TOKEN.test(value) ? [`"${value.slice(0, 120)}"`] : [];
+  }
+  if (!isWalkable(value) || seen.has(value)) {
+    return [];
+  }
+  seen.add(value);
+  const found = [];
+  const record = value;
+  if (!Array.isArray(value)) {
+    if (record.repeatRefresh === true) {
+      found.push("repeatRefresh: true");
+    }
+    const { stagger } = record;
+    if (typeof stagger === "object" && stagger !== null && stagger.from === "random") {
+      found.push("stagger: {from: 'random'}");
+    }
+  }
+  for (const nested of Array.isArray(value) ? value : Object.values(record)) {
+    found.push(...findNondeterministicVars(nested, seen));
+  }
+  return [...new Set(found)];
+};
+var findTimelineNondeterminism = (timeline) => {
+  const animations = getTimelineAnimations(timeline);
+  return [
+    ...new Set(animations.flatMap((animation) => findNondeterministicVars(animationVars(animation))))
+  ];
+};
+var findStrayAnimations = (timeline, preexisting) => {
+  const owned = new Set(getTimelineAnimations(timeline));
+  const problems = [];
+  for (const animation of gsap.globalTimeline.getChildren(true, true, true)) {
+    if (owned.has(animation) || preexisting.has(animation)) {
+      continue;
+    }
+    const vars = animationVars(animation);
+    const callbacks = findCallbacksInValue(vars);
+    const delay = typeof vars.delay === "number" ? vars.delay : 0;
+    if (callbacks.length > 0) {
+      problems.push(`a wall-clock animation with callbacks (${callbacks.join(", ")})`);
+    } else if (animation.totalDuration() > 0 || delay > 0) {
+      problems.push("a wall-clock animation that is not attached to the provided timeline");
+    }
+  }
+  return problems;
+};
+var assertNoCallbacks = (value) => {
+  const callbacks = findCallbacksInValue(value);
+  if (callbacks.length > 0) {
+    throw new Error(`useGsapTimeline does not allow timeline callbacks (${callbacks.join(", ")}). Derive visual state from the timeline instead of side effects.`);
+  }
+};
+var guardTimelineMethods = (timeline) => {
+  const originalPaused = timeline.paused.bind(timeline);
+  const originalTotalTime = timeline.totalTime.bind(timeline);
+  const originalKill = timeline.kill.bind(timeline);
+  const playbackError = () => {
+    throw new Error("useGsapTimeline builders must not start playback. Remove play(), resume(), restart(), reverse(), or paused(false).");
+  };
+  timeline.play = playbackError;
+  timeline.resume = playbackError;
+  timeline.restart = playbackError;
+  timeline.reverse = playbackError;
+  timeline.pause = () => {
+    throw new Error("useGsapTimeline owns timeline pause state. Do not call timeline.pause() inside the builder.");
+  };
+  timeline.paused = (value) => {
+    if (value === false) {
+      return playbackError();
+    }
+    if (value !== undefined) {
+      throw new Error("useGsapTimeline owns timeline pause state. Read timeline.paused() if needed, but do not set it.");
+    }
+    return originalPaused();
+  };
+  const seekingError = () => {
+    throw new Error("useGsapTimeline owns timeline seeking. Remove seek(), time(), totalTime(), progress(), totalProgress(), tweenTo(), or tweenFromTo() from the builder.");
+  };
+  for (const method of ["timeScale", "duration", "totalDuration"]) {
+    const original = timeline[method].bind(timeline);
+    timeline[method] = (...args) => {
+      if (args.length > 0) {
+        throw new Error(`useGsapTimeline does not support timeline.${method}(value). The Remotion frame drives the timeline at a fixed 1:1 time scale; author tween durations directly.`);
+      }
+      return original();
+    };
+  }
+  timeline.seek = seekingError;
+  timeline.time = seekingError;
+  timeline.totalTime = seekingError;
+  timeline.progress = seekingError;
+  timeline.totalProgress = seekingError;
+  timeline.tweenTo = seekingError;
+  timeline.tweenFromTo = seekingError;
+  timeline.kill = () => {
+    throw new Error("useGsapTimeline owns timeline cleanup. Do not call timeline.kill() inside the builder.");
+  };
+  const originalEventCallback = timeline.eventCallback.bind(timeline);
+  timeline.eventCallback = (...args) => {
+    if (args.length > 1 && typeof args[1] === "function") {
+      throw new Error("useGsapTimeline does not allow timeline.eventCallback().");
+    }
+    return originalEventCallback(...args);
+  };
+  timeline.then = () => {
+    throw new Error("useGsapTimeline does not allow timeline.then() callbacks.");
+  };
+  const originalTo = timeline.to.bind(timeline);
+  timeline.to = (...args) => {
+    assertNoCallbacks(args[1]);
+    return originalTo(...args);
+  };
+  const originalFrom = timeline.from.bind(timeline);
+  timeline.from = (...args) => {
+    assertNoCallbacks(args[1]);
+    return originalFrom(...args);
+  };
+  const originalFromTo = timeline.fromTo.bind(timeline);
+  timeline.fromTo = (...args) => {
+    assertNoCallbacks(args[1]);
+    assertNoCallbacks(args[2]);
+    return originalFromTo(...args);
+  };
+  const originalSet = timeline.set.bind(timeline);
+  timeline.set = (...args) => {
+    assertNoCallbacks(args[1]);
+    return originalSet(...args);
+  };
+  const originalAdd = timeline.add.bind(timeline);
+  timeline.add = (...args) => {
+    if (typeof args[0] === "function") {
+      throw new Error("useGsapTimeline does not allow callback functions in timeline.add().");
+    }
+    return originalAdd(...args);
+  };
+  timeline.call = () => {
+    throw new Error("useGsapTimeline does not allow timeline.call().");
+  };
+  return {
+    isPaused: () => originalPaused(),
+    pause: () => {
+      originalPaused(true);
+    },
+    renderAt: (seconds) => {
+      originalTotalTime(0, true);
+      originalTotalTime(seconds, true);
+    },
+    restoreForContextRevert: () => {
+      for (const method of [
+        "play",
+        "resume",
+        "restart",
+        "reverse",
+        "pause",
+        "paused",
+        "seek",
+        "time",
+        "totalTime",
+        "timeScale",
+        "duration",
+        "totalDuration",
+        "progress",
+        "totalProgress",
+        "tweenTo",
+        "tweenFromTo",
+        "kill",
+        "eventCallback",
+        "then",
+        "to",
+        "from",
+        "fromTo",
+        "set",
+        "add",
+        "call"
+      ]) {
+        delete timeline[method];
+      }
+    },
+    kill: () => {
+      originalKill();
+    }
+  };
+};
+var useGsapTimeline = (build, { dependencies = EMPTY_DEPENDENCIES } = {}) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const scopeRef = useRef(null);
+  const controlsRef = useRef(null);
+  const builtForRef = useRef(null);
+  const buildRef = useRef(build);
+  const frameRef = useRef(frame);
+  const fpsRef = useRef(fps);
+  const [remountNonce, setRemountNonce] = useState(0);
+  buildRef.current = build;
+  frameRef.current = frame;
+  fpsRef.current = fps;
+  useLayoutEffect(() => {
+    const scope = scopeRef.current;
+    builtForRef.current = scope;
+    if (!scope) {
+      return;
+    }
+    const state = { timeline: null, controls: null };
+    const context = gsap.context(() => {
+      return;
+    }, scope);
+    try {
+      context.add(() => {
+        state.timeline = gsap.timeline({ paused: true });
+        state.controls = guardTimelineMethods(state.timeline);
+        const selector = gsap.utils.selector(scope);
+        const preexisting = new Set(gsap.globalTimeline.getChildren(true, true, true));
+        const originalTickerAdd = gsap.ticker.add.bind(gsap.ticker);
+        gsap.ticker.add = () => {
+          throw new Error("useGsapTimeline builders must not register gsap.ticker callbacks. The Remotion frame is the only clock.");
+        };
+        let result;
+        try {
+          result = buildRef.current({
+            timeline: state.timeline,
+            scope,
+            selector
+          });
+        } finally {
+          gsap.ticker.add = originalTickerAdd;
+        }
+        if (!state.controls.isPaused()) {
+          throw new Error("useGsapTimeline builders must not start playback. Remove play(), resume(), restart(), or reverse().");
+        }
+        if (result instanceof Promise) {
+          throw new TypeError("useGsapTimeline builders must be synchronous. Load data before building the timeline.");
+        }
+        const callbacks = findTimelineCallbacks(state.timeline);
+        if (callbacks.length > 0) {
+          throw new Error(`useGsapTimeline does not allow timeline callbacks (${callbacks.join(", ")}). Derive visual state from the timeline instead of side effects.`);
+        }
+        const nonElementTargets = findNonElementTargets(state.timeline);
+        if (nonElementTargets.length > 0) {
+          throw new Error(`useGsapTimeline tweens must target DOM or SVG elements, but found: ${nonElementTargets.join("; ")}. Tweening plain objects animates in the Player but freezes in stills and renders, because nothing re-reads the object after a frame seek. Animate elements through the scoped selector or refs, or derive numeric values with Remotion's useCurrentFrame() and interpolate().`);
+        }
+        const nondeterminism = findTimelineNondeterminism(state.timeline);
+        if (nondeterminism.length > 0) {
+          throw new Error(`useGsapTimeline rejects nondeterministic tween configuration (${nondeterminism.join("; ")}). GSAP resolves these with unseeded Math.random, so every mount and every render process disagrees. Derive stable values from data or Remotion's seeded random().`);
+        }
+        const strays = findStrayAnimations(state.timeline, preexisting);
+        if (strays.length > 0) {
+          throw new Error(`useGsapTimeline builders created ${strays.join("; ")}. Animations that are not children of the provided timeline advance on the wall clock instead of the Remotion frame. Attach them to the timeline, or use a plain zero-duration gsap.set() for static state.`);
+        }
+        state.controls.pause();
+        const ownedTimeline = state.timeline;
+        const startTimeOnOwnedClock = (child) => {
+          let time = child.startTime();
+          let parent = child.parent;
+          while (parent && parent !== ownedTimeline) {
+            time = parent.startTime() + time / (parent.timeScale() || 1);
+            parent = parent.parent;
+          }
+          return time;
+        };
+        const startTimes = [
+          ...new Set(state.timeline.getChildren(true, true, true).map((child) => startTimeOnOwnedClock(child)).filter((startTime) => Number.isFinite(startTime)).sort((a, b) => a - b))
+        ];
+        const totalDuration = state.timeline.totalDuration();
+        const cycleDuration = state.timeline.duration();
+        const primeEnd = Number.isFinite(totalDuration) ? totalDuration : Number.isFinite(cycleDuration) ? cycleDuration : 3600;
+        for (const startTime of [...startTimes, primeEnd]) {
+          state.controls.renderAt(startTime);
+        }
+        state.controls.renderAt(frameToSeconds(frameRef.current, fpsRef.current));
+      });
+      controlsRef.current = state.controls;
+    } catch (error) {
+      state.controls?.restoreForContextRevert();
+      context.revert();
+      state.controls?.kill();
+      throw error;
+    }
+    return () => {
+      controlsRef.current = null;
+      state.controls?.restoreForContextRevert();
+      context.revert();
+      state.controls?.kill();
+    };
+  }, [...dependencies, remountNonce]);
+  useLayoutEffect(() => {
+    const controls = controlsRef.current;
+    if (controls) {
+      controls.renderAt(frameToSeconds(frame, fps));
+    }
+  }, [fps, frame]);
+  useLayoutEffect(() => {
+    if (scopeRef.current !== builtForRef.current) {
+      setRemountNonce((nonce) => nonce + 1);
+    }
+  });
+  return scopeRef;
+};
+export {
+  useGsapTimeline
+};

package/dist/frame-time.d.ts

@@ -0,0 +1 @@
+export declare const frameToSeconds: (frame: number, fps: number) => number;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="gsap" />
+export { useGsapTimeline } from './use-gsap-timeline';
+export type { GsapTimelineBuildContext, GsapTimelineBuilder, GsapScopeRef, UseGsapTimelineOptions, } from './use-gsap-timeline';

package/dist/use-gsap-timeline.d.ts

@@ -0,0 +1,24 @@
+/// <reference types="gsap" />
+import { type DependencyList } from 'react';
+export type GsapTimelineBuildContext<T extends Element> = {
+    /** A package-owned timeline that is already paused at time zero. */
+    timeline: gsap.core.Timeline;
+    /** The mounted element attached to the returned ref. */
+    scope: T;
+    /** A GSAP selector restricted to descendants of the scope element. */
+    selector: gsap.utils.SelectorFunc;
+};
+export type GsapTimelineBuilder<T extends Element> = (context: GsapTimelineBuildContext<T>) => unknown;
+export type UseGsapTimelineOptions = {
+    /** Rebuild the timeline when one of these values changes. */
+    dependencies?: DependencyList;
+};
+/** A React 18/19-compatible object ref for the scoped HTML or SVG root. */
+export type GsapScopeRef<T extends Element> = {
+    current: T | null;
+};
+/**
+ * Builds one scoped, paused GSAP timeline and seeks it from Remotion's frame.
+ * The hook never plays the timeline on GSAP's ticker.
+ */
+export declare const useGsapTimeline: <T extends Element>(build: GsapTimelineBuilder<T>, { dependencies }?: UseGsapTimelineOptions) => GsapScopeRef<T>;

package/package.json

@@ -0,0 +1,64 @@
+{
+	"name": "@remotion/gsap",
+	"version": "4.0.517",
+	"description": "Use GSAP timelines in Remotion",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"module": "dist/esm/index.mjs",
+	"repository": {
+		"url": "https://github.com/remotion-dev/remotion/tree/main/packages/gsap"
+	},
+	"type": "module",
+	"scripts": {
+		"test": "bun test src/test",
+		"formatting": "oxfmt src --check",
+		"format": "oxfmt src",
+		"lint": "eslint src",
+		"watch": "tsgo -w",
+		"make": "tsgo && bun --env-file=../.env.bundle bundle.ts"
+	},
+	"author": "Brayden Blackwell",
+	"contributors": [],
+	"license": "MIT",
+	"bugs": {
+		"url": "https://github.com/remotion-dev/remotion/issues"
+	},
+	"dependencies": {
+		"remotion": "4.0.517"
+	},
+	"peerDependencies": {
+		"gsap": ">=3.12.0 <4",
+		"react": ">=16.8.0",
+		"react-dom": ">=16.8.0"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"module": "./dist/esm/index.mjs",
+			"import": "./dist/esm/index.mjs"
+		},
+		"./package.json": "./package.json"
+	},
+	"devDependencies": {
+		"react": "19.2.3",
+		"react-dom": "19.2.3",
+		"@types/react": "19.2.7",
+		"@types/react-dom": "19.2.3",
+		"@remotion/eslint-config-internal": "4.0.517",
+		"@happy-dom/global-registrator": "14.5.1",
+		"eslint": "9.19.0",
+		"gsap": "3.15.0",
+		"@typescript/native-preview": "7.0.0-dev.20260217.1"
+	},
+	"keywords": [
+		"remotion",
+		"gsap",
+		"animation",
+		"video",
+		"react"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"homepage": "https://www.remotion.dev/docs/gsap"
+}