@depup/lottie-react 3.0.0-depup.0 → 3.1.0-depup.0

package/build/animation/useLottieLight.cjs

@@ -1,4 +1,6 @@
+"use client";
 const require_runtime = require("../_virtual/_rolldown/runtime.cjs");
+const require_configureLottie = require("./configureLottie.cjs");
 const require_useLottieAnimation = require("./useLottieAnimation.cjs");
 let lottie_web_build_player_lottie_light_js = require("lottie-web/build/player/lottie_light.js");
 lottie_web_build_player_lottie_light_js = require_runtime.__toESM(lottie_web_build_player_lottie_light_js, 1);
@@ -13,8 +15,14 @@ lottie_web_build_player_lottie_light_js = require_runtime.__toESM(lottie_web_bui
 * drawn at its static value; {@link useLottieSvg} is the smaller build that
 * keeps expressions.
 */
+/** The light engine: svg only, no expressions, no `eval`. */
+const lightEngine = {
+	player: lottie_web_build_player_lottie_light_js.default,
+	name: require_configureLottie.LottieEngineName.light
+};
 function useLottieLight(options) {
-	return require_useLottieAnimation.useLottieAnimation(lottie_web_build_player_lottie_light_js.default, options);
+	return require_useLottieAnimation.useLottieAnimation(lightEngine, options);
 }
 //#endregion
+exports.lightEngine = lightEngine;
 exports.useLottieLight = useLottieLight;

package/build/animation/useLottieLight.d.cts

@@ -1,16 +1,7 @@
+import "./configureLottie.cjs";
 import { LottieInstance, LottieRenderer } from "./types.cjs";
 import { UseLottieOptions } from "./useLottieAnimation.cjs";
 //#region src/animation/useLottieLight.d.ts
-/**
- * Loads and drives an animation using the light build of the engine.
- *
- * Identical to {@link useLottie} except that `svg` is the only renderer, which
- * the type enforces: the light build does not contain the other two, and asking
- * it for one throws at runtime while its own declarations claim otherwise.
- * It also carries no expression engine, so a property an expression drives is
- * drawn at its static value; {@link useLottieSvg} is the smaller build that
- * keeps expressions.
- */
 declare function useLottieLight(options: UseLottieOptions<typeof LottieRenderer.svg>): LottieInstance;
 //#endregion
 export { useLottieLight };

package/build/animation/useLottieLight.d.ts

@@ -1,16 +1,7 @@
+import "./configureLottie.js";
 import { LottieInstance, LottieRenderer } from "./types.js";
 import { UseLottieOptions } from "./useLottieAnimation.js";
 //#region src/animation/useLottieLight.d.ts
-/**
- * Loads and drives an animation using the light build of the engine.
- *
- * Identical to {@link useLottie} except that `svg` is the only renderer, which
- * the type enforces: the light build does not contain the other two, and asking
- * it for one throws at runtime while its own declarations claim otherwise.
- * It also carries no expression engine, so a property an expression drives is
- * drawn at its static value; {@link useLottieSvg} is the smaller build that
- * keeps expressions.
- */
 declare function useLottieLight(options: UseLottieOptions<typeof LottieRenderer.svg>): LottieInstance;
 //#endregion
 export { useLottieLight };

package/build/animation/useLottieLight.js

@@ -1,3 +1,5 @@
+"use client";
+import { LottieEngineName } from "./configureLottie.js";
 import { useLottieAnimation } from "./useLottieAnimation.js";
 import lottieLight from "lottie-web/build/player/lottie_light.js";
 //#region src/animation/useLottieLight.ts
@@ -11,8 +13,13 @@ import lottieLight from "lottie-web/build/player/lottie_light.js";
 * drawn at its static value; {@link useLottieSvg} is the smaller build that
 * keeps expressions.
 */
+/** The light engine: svg only, no expressions, no `eval`. */
+const lightEngine = {
+	player: lottieLight,
+	name: LottieEngineName.light
+};
 function useLottieLight(options) {
-	return useLottieAnimation(lottieLight, options);
+	return useLottieAnimation(lightEngine, options);
 }
 //#endregion
-export { useLottieLight };
+export { lightEngine, useLottieLight };

package/build/animation/useLottieSvg.cjs

@@ -1,4 +1,6 @@
+"use client";
 const require_runtime = require("../_virtual/_rolldown/runtime.cjs");
+const require_configureLottie = require("./configureLottie.cjs");
 const require_useLottieAnimation = require("./useLottieAnimation.cjs");
 let lottie_web_build_player_lottie_svg_js = require("lottie-web/build/player/lottie_svg.js");
 lottie_web_build_player_lottie_svg_js = require_runtime.__toESM(lottie_web_build_player_lottie_svg_js, 1);
@@ -11,8 +13,14 @@ lottie_web_build_player_lottie_svg_js = require_runtime.__toESM(lottie_web_build
 * it for one throws at runtime while its own declarations claim otherwise.
 * Unlike {@link useLottieLight} it keeps the expression engine.
 */
+/** The svg engine: svg only, expressions kept. */
+const svgEngine = {
+	player: lottie_web_build_player_lottie_svg_js.default,
+	name: require_configureLottie.LottieEngineName.svg
+};
 function useLottieSvg(options) {
-	return require_useLottieAnimation.useLottieAnimation(lottie_web_build_player_lottie_svg_js.default, options);
+	return require_useLottieAnimation.useLottieAnimation(svgEngine, options);
 }
 //#endregion
+exports.svgEngine = svgEngine;
 exports.useLottieSvg = useLottieSvg;

package/build/animation/useLottieSvg.d.cts

@@ -1,14 +1,7 @@
+import "./configureLottie.cjs";
 import { LottieInstance, LottieRenderer } from "./types.cjs";
 import { UseLottieOptions } from "./useLottieAnimation.cjs";
 //#region src/animation/useLottieSvg.d.ts
-/**
- * Loads and drives an animation using the svg build of the engine.
- *
- * Identical to {@link useLottie} except that `svg` is the only renderer, which
- * the type enforces: the svg build does not contain the other two, and asking
- * it for one throws at runtime while its own declarations claim otherwise.
- * Unlike {@link useLottieLight} it keeps the expression engine.
- */
 declare function useLottieSvg(options: UseLottieOptions<typeof LottieRenderer.svg>): LottieInstance;
 //#endregion
 export { useLottieSvg };

package/build/animation/useLottieSvg.d.ts

@@ -1,14 +1,7 @@
+import "./configureLottie.js";
 import { LottieInstance, LottieRenderer } from "./types.js";
 import { UseLottieOptions } from "./useLottieAnimation.js";
 //#region src/animation/useLottieSvg.d.ts
-/**
- * Loads and drives an animation using the svg build of the engine.
- *
- * Identical to {@link useLottie} except that `svg` is the only renderer, which
- * the type enforces: the svg build does not contain the other two, and asking
- * it for one throws at runtime while its own declarations claim otherwise.
- * Unlike {@link useLottieLight} it keeps the expression engine.
- */
 declare function useLottieSvg(options: UseLottieOptions<typeof LottieRenderer.svg>): LottieInstance;
 //#endregion
 export { useLottieSvg };

package/build/animation/useLottieSvg.js

@@ -1,3 +1,5 @@
+"use client";
+import { LottieEngineName } from "./configureLottie.js";
 import { useLottieAnimation } from "./useLottieAnimation.js";
 import lottieSvg from "lottie-web/build/player/lottie_svg.js";
 //#region src/animation/useLottieSvg.ts
@@ -9,8 +11,13 @@ import lottieSvg from "lottie-web/build/player/lottie_svg.js";
 * it for one throws at runtime while its own declarations claim otherwise.
 * Unlike {@link useLottieLight} it keeps the expression engine.
 */
+/** The svg engine: svg only, expressions kept. */
+const svgEngine = {
+	player: lottieSvg,
+	name: LottieEngineName.svg
+};
 function useLottieSvg(options) {
-	return useLottieAnimation(lottieSvg, options);
+	return useLottieAnimation(svgEngine, options);
 }
 //#endregion
-export { useLottieSvg };
+export { svgEngine, useLottieSvg };

package/build/controls/LottieControls.cjs

@@ -1,3 +1,4 @@
+"use client";
 const require_renderStyledElement = require("../animation/renderStyledElement.cjs");
 const require_useLottieInstance = require("../animation/useLottieInstance.cjs");
 const require_types = require("../animation/types.cjs");

package/build/controls/LottieControls.js

@@ -1,3 +1,4 @@
+"use client";
 import { renderStyledElement } from "../animation/renderStyledElement.js";
 import { useLottieInstance } from "../animation/useLottieInstance.js";
 import { LottieState } from "../animation/types.js";

package/build/index.cjs

@@ -1,13 +1,14 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_configureLottie = require("./animation/configureLottie.cjs");
 const require_useLottieInstance = require("./animation/useLottieInstance.cjs");
 const require_LottieDisplay = require("./animation/LottieDisplay.cjs");
 const require_types = require("./animation/types.cjs");
-const require_Lottie = require("./animation/Lottie.cjs");
-const require_LottieLight = require("./animation/LottieLight.cjs");
-const require_LottieSvg = require("./animation/LottieSvg.cjs");
 const require_useLottie = require("./animation/useLottie.cjs");
+const require_Lottie = require("./animation/Lottie.cjs");
 const require_useLottieLight = require("./animation/useLottieLight.cjs");
+const require_LottieLight = require("./animation/LottieLight.cjs");
 const require_useLottieSvg = require("./animation/useLottieSvg.cjs");
+const require_LottieSvg = require("./animation/LottieSvg.cjs");
 const require_LottieControls = require("./controls/LottieControls.cjs");
 const require_LottieInteractions = require("./interactions/LottieInteractions.cjs");
 const require_lottieInView = require("./interactions/lottieInView.cjs");
@@ -27,6 +28,7 @@ exports.LottieRenderer = require_types.LottieRenderer;
 exports.LottieState = require_types.LottieState;
 exports.LottieSubscription = require_types.LottieSubscription;
 exports.LottieSvg = require_LottieSvg.LottieSvg;
+exports.configureLottie = require_configureLottie.configureLottie;
 exports.lottieInView = require_lottieInView.lottieInView;
 exports.lottieScrollScrub = require_lottieScrollScrub.lottieScrollScrub;
 exports.useLottie = require_useLottie.useLottie;

package/build/index.d.cts

@@ -1,3 +1,4 @@
+import { ConfigureLottieOptions, configureLottie } from "./animation/configureLottie.cjs";
 import { LottieDirection, LottieHandle, LottieInstance, LottieRenderer, LottieSeekTarget, LottieSegments, LottieState, LottieSubscription, LottieSubscriptions } from "./animation/types.cjs";
 import { UseLottieOptions } from "./animation/useLottieAnimation.cjs";
 import { Lottie, LottieProps } from "./animation/Lottie.cjs";
@@ -16,4 +17,4 @@ import { LottieScrollScrubOptions, lottieScrollScrub } from "./interactions/lott
 import { useLottieInteractions } from "./interactions/useLottieInteractions.cjs";
 import { LottieError, LottieErrorProps } from "./overlays/LottieError.cjs";
 import { LottieLoading, LottieLoadingProps } from "./overlays/LottieLoading.cjs";
-export { Lottie, LottieControls, type LottieControlsProps, LottieDirection, LottieDisplay, type LottieDisplayProps, LottieError, type LottieErrorProps, type LottieHandle, type LottieInViewOptions, type LottieInstance, type LottieInteraction, type LottieInteractionContext, LottieInteractions, type LottieInteractionsProps, LottieLight, type LottieLightProps, LottieLoading, type LottieLoadingProps, type LottieProps, LottieRenderer, type LottieScrollScrubOptions, type LottieSeekTarget, type LottieSegments, LottieState, LottieSubscription, type LottieSubscriptions, LottieSvg, type LottieSvgProps, type UseLottieOptions, lottieInView, lottieScrollScrub, useLottie, useLottieInstance, useLottieInteractions, useLottieLight, useLottieSvg };
+export { type ConfigureLottieOptions, Lottie, LottieControls, type LottieControlsProps, LottieDirection, LottieDisplay, type LottieDisplayProps, LottieError, type LottieErrorProps, type LottieHandle, type LottieInViewOptions, type LottieInstance, type LottieInteraction, type LottieInteractionContext, LottieInteractions, type LottieInteractionsProps, LottieLight, type LottieLightProps, LottieLoading, type LottieLoadingProps, type LottieProps, LottieRenderer, type LottieScrollScrubOptions, type LottieSeekTarget, type LottieSegments, LottieState, LottieSubscription, type LottieSubscriptions, LottieSvg, type LottieSvgProps, type UseLottieOptions, configureLottie, lottieInView, lottieScrollScrub, useLottie, useLottieInstance, useLottieInteractions, useLottieLight, useLottieSvg };

package/build/index.d.ts

@@ -1,3 +1,4 @@
+import { ConfigureLottieOptions, configureLottie } from "./animation/configureLottie.js";
 import { LottieDirection, LottieHandle, LottieInstance, LottieRenderer, LottieSeekTarget, LottieSegments, LottieState, LottieSubscription, LottieSubscriptions } from "./animation/types.js";
 import { UseLottieOptions } from "./animation/useLottieAnimation.js";
 import { Lottie, LottieProps } from "./animation/Lottie.js";
@@ -16,4 +17,4 @@ import { LottieScrollScrubOptions, lottieScrollScrub } from "./interactions/lott
 import { useLottieInteractions } from "./interactions/useLottieInteractions.js";
 import { LottieError, LottieErrorProps } from "./overlays/LottieError.js";
 import { LottieLoading, LottieLoadingProps } from "./overlays/LottieLoading.js";
-export { Lottie, LottieControls, type LottieControlsProps, LottieDirection, LottieDisplay, type LottieDisplayProps, LottieError, type LottieErrorProps, type LottieHandle, type LottieInViewOptions, type LottieInstance, type LottieInteraction, type LottieInteractionContext, LottieInteractions, type LottieInteractionsProps, LottieLight, type LottieLightProps, LottieLoading, type LottieLoadingProps, type LottieProps, LottieRenderer, type LottieScrollScrubOptions, type LottieSeekTarget, type LottieSegments, LottieState, LottieSubscription, type LottieSubscriptions, LottieSvg, type LottieSvgProps, type UseLottieOptions, lottieInView, lottieScrollScrub, useLottie, useLottieInstance, useLottieInteractions, useLottieLight, useLottieSvg };
+export { type ConfigureLottieOptions, Lottie, LottieControls, type LottieControlsProps, LottieDirection, LottieDisplay, type LottieDisplayProps, LottieError, type LottieErrorProps, type LottieHandle, type LottieInViewOptions, type LottieInstance, type LottieInteraction, type LottieInteractionContext, LottieInteractions, type LottieInteractionsProps, LottieLight, type LottieLightProps, LottieLoading, type LottieLoadingProps, type LottieProps, LottieRenderer, type LottieScrollScrubOptions, type LottieSeekTarget, type LottieSegments, LottieState, LottieSubscription, type LottieSubscriptions, LottieSvg, type LottieSvgProps, type UseLottieOptions, configureLottie, lottieInView, lottieScrollScrub, useLottie, useLottieInstance, useLottieInteractions, useLottieLight, useLottieSvg };

package/build/index.js

@@ -1,12 +1,13 @@
+import { configureLottie } from "./animation/configureLottie.js";
 import { useLottieInstance } from "./animation/useLottieInstance.js";
 import { LottieDisplay } from "./animation/LottieDisplay.js";
 import { LottieDirection, LottieRenderer, LottieState, LottieSubscription } from "./animation/types.js";
-import { Lottie } from "./animation/Lottie.js";
-import { LottieLight } from "./animation/LottieLight.js";
-import { LottieSvg } from "./animation/LottieSvg.js";
 import { useLottie } from "./animation/useLottie.js";
+import { Lottie } from "./animation/Lottie.js";
 import { useLottieLight } from "./animation/useLottieLight.js";
+import { LottieLight } from "./animation/LottieLight.js";
 import { useLottieSvg } from "./animation/useLottieSvg.js";
+import { LottieSvg } from "./animation/LottieSvg.js";
 import { LottieControls } from "./controls/LottieControls.js";
 import { LottieInteractions } from "./interactions/LottieInteractions.js";
 import { lottieInView } from "./interactions/lottieInView.js";
@@ -14,4 +15,4 @@ import { lottieScrollScrub } from "./interactions/lottieScrollScrub.js";
 import { useLottieInteractions } from "./interactions/useLottieInteractions.js";
 import { LottieError } from "./overlays/LottieError.js";
 import { LottieLoading } from "./overlays/LottieLoading.js";
-export { Lottie, LottieControls, LottieDirection, LottieDisplay, LottieError, LottieInteractions, LottieLight, LottieLoading, LottieRenderer, LottieState, LottieSubscription, LottieSvg, lottieInView, lottieScrollScrub, useLottie, useLottieInstance, useLottieInteractions, useLottieLight, useLottieSvg };
+export { Lottie, LottieControls, LottieDirection, LottieDisplay, LottieError, LottieInteractions, LottieLight, LottieLoading, LottieRenderer, LottieState, LottieSubscription, LottieSvg, configureLottie, lottieInView, lottieScrollScrub, useLottie, useLottieInstance, useLottieInteractions, useLottieLight, useLottieSvg };

package/build/interactions/LottieInteractions.cjs

@@ -1,3 +1,4 @@
+"use client";
 const require_LottieInstanceContext = require("../animation/LottieInstanceContext.cjs");
 const require_LottieRegistryContext = require("../animation/LottieRegistryContext.cjs");
 const require_useInteractionsRunner = require("./useInteractionsRunner.cjs");

package/build/interactions/LottieInteractions.js

@@ -1,3 +1,4 @@
+"use client";
 import { LottieInstanceContext } from "../animation/LottieInstanceContext.js";
 import { LottieRegistryContext, createLottieRegistry } from "../animation/LottieRegistryContext.js";
 import { useInteractionsRunner, useSingleInstanceSource } from "./useInteractionsRunner.js";

package/build/interactions/lottieInView.cjs

@@ -1,3 +1,4 @@
+"use client";
 const require_types = require("../animation/types.cjs");
 //#region src/interactions/lottieInView.ts
 function isInViewOptions(value) {

package/build/interactions/lottieInView.js

@@ -1,3 +1,4 @@
+"use client";
 import { LottieState } from "../animation/types.js";
 //#region src/interactions/lottieInView.ts
 function isInViewOptions(value) {

package/build/interactions/lottieScrollScrub.cjs

@@ -1,3 +1,4 @@
+"use client";
 const require_types = require("../animation/types.cjs");
 const require_coverProgress = require("./coverProgress.cjs");
 //#region src/interactions/lottieScrollScrub.ts
@@ -11,6 +12,15 @@ function isScrubOptions(value) {
 	if ("onRangeEnter" in value && typeof value.onRangeEnter !== "function") return false;
 	return !("onRangeLeave" in value && typeof value.onRangeLeave !== "function");
 }
+/** Whether an element has anything to scroll along the axis right now. */
+function canScrollAlong(element, axis) {
+	return axis === "inline" ? element.scrollWidth > element.clientWidth : element.scrollHeight > element.clientHeight;
+}
+function timelineIsUsable(timeline, axis) {
+	const source = timeline.source;
+	if (source === null || source === document.scrollingElement) return true;
+	return canScrollAlong(source, axis);
+}
 function attachScrollScrub(context, raw) {
 	const options = isScrubOptions(raw) ? raw : {};
 	const range = options.range ?? [0, 1];
@@ -18,13 +28,14 @@ function attachScrollScrub(context, raw) {
 	let observer = null;
 	let observedRoot = null;
 	let timeline = null;
+	let useTimeline = false;
 	let frameHandle = null;
 	let scrubbing = false;
 	let gestureStarted = false;
 	let previousBand = null;
 	let warnedInactive = false;
 	const readProgress = (root) => {
-		if (timeline !== null) {
+		if (useTimeline && timeline !== null) {
 			const time = timeline.currentTime;
 			if (typeof time === "number") return Math.min(Math.max(time / 100, 0), 1);
 			if (time !== null && typeof time === "object" && "value" in time && typeof time.value === "number") return Math.min(Math.max(time.value / 100, 0), 1);
@@ -64,6 +75,7 @@ function attachScrollScrub(context, raw) {
 		if (scrubbing) return;
 		scrubbing = true;
 		previousBand = null;
+		useTimeline = timeline !== null && timelineIsUsable(timeline, axis);
 		if (context.lottie.state !== require_types.LottieState.loading) {
 			gestureStarted = true;
 			context.lottie.scrubStart();
@@ -93,6 +105,7 @@ function attachScrollScrub(context, raw) {
 		observer?.disconnect();
 		observer = null;
 		timeline = null;
+		useTimeline = false;
 		observedRoot = root;
 		if (root === null) return;
 		const ViewTimelineCtor = globalThis.ViewTimeline;
@@ -136,9 +149,10 @@ function attachScrollScrub(context, raw) {
 * </LottieInteractions>
 * ```
 *
-* Progress is the platform's own scroll timeline where the browser has one,
-* and the same arithmetic measured by hand where it does not; the numbers
-* agree by construction. While the animation is out of view nothing samples
+* Progress is the platform's own scroll timeline where the browser has one
+* and its scroller is one that scrolls, and the same arithmetic measured by
+* hand against the viewport where it does not; the numbers agree by
+* construction. While the animation is out of view nothing samples
 * at all, and playback state is held by the scrub gesture, so whatever was
 * true before the scrub is restored when it leaves.
 */

package/build/interactions/lottieScrollScrub.d.cts

@@ -36,9 +36,10 @@ interface LottieScrollScrubOptions {
  * </LottieInteractions>
  * ```
  *
- * Progress is the platform's own scroll timeline where the browser has one,
- * and the same arithmetic measured by hand where it does not; the numbers
- * agree by construction. While the animation is out of view nothing samples
+ * Progress is the platform's own scroll timeline where the browser has one
+ * and its scroller is one that scrolls, and the same arithmetic measured by
+ * hand against the viewport where it does not; the numbers agree by
+ * construction. While the animation is out of view nothing samples
  * at all, and playback state is held by the scrub gesture, so whatever was
  * true before the scrub is restored when it leaves.
  */

package/build/interactions/lottieScrollScrub.d.ts

@@ -36,9 +36,10 @@ interface LottieScrollScrubOptions {
  * </LottieInteractions>
  * ```
  *
- * Progress is the platform's own scroll timeline where the browser has one,
- * and the same arithmetic measured by hand where it does not; the numbers
- * agree by construction. While the animation is out of view nothing samples
+ * Progress is the platform's own scroll timeline where the browser has one
+ * and its scroller is one that scrolls, and the same arithmetic measured by
+ * hand against the viewport where it does not; the numbers agree by
+ * construction. While the animation is out of view nothing samples
  * at all, and playback state is held by the scrub gesture, so whatever was
  * true before the scrub is restored when it leaves.
  */

package/build/interactions/lottieScrollScrub.js

@@ -1,3 +1,4 @@
+"use client";
 import { LottieState } from "../animation/types.js";
 import { bandEdges, bandProgress, coverProgress } from "./coverProgress.js";
 //#region src/interactions/lottieScrollScrub.ts
@@ -11,6 +12,15 @@ function isScrubOptions(value) {
 	if ("onRangeEnter" in value && typeof value.onRangeEnter !== "function") return false;
 	return !("onRangeLeave" in value && typeof value.onRangeLeave !== "function");
 }
+/** Whether an element has anything to scroll along the axis right now. */
+function canScrollAlong(element, axis) {
+	return axis === "inline" ? element.scrollWidth > element.clientWidth : element.scrollHeight > element.clientHeight;
+}
+function timelineIsUsable(timeline, axis) {
+	const source = timeline.source;
+	if (source === null || source === document.scrollingElement) return true;
+	return canScrollAlong(source, axis);
+}
 function attachScrollScrub(context, raw) {
 	const options = isScrubOptions(raw) ? raw : {};
 	const range = options.range ?? [0, 1];
@@ -18,13 +28,14 @@ function attachScrollScrub(context, raw) {
 	let observer = null;
 	let observedRoot = null;
 	let timeline = null;
+	let useTimeline = false;
 	let frameHandle = null;
 	let scrubbing = false;
 	let gestureStarted = false;
 	let previousBand = null;
 	let warnedInactive = false;
 	const readProgress = (root) => {
-		if (timeline !== null) {
+		if (useTimeline && timeline !== null) {
 			const time = timeline.currentTime;
 			if (typeof time === "number") return Math.min(Math.max(time / 100, 0), 1);
 			if (time !== null && typeof time === "object" && "value" in time && typeof time.value === "number") return Math.min(Math.max(time.value / 100, 0), 1);
@@ -64,6 +75,7 @@ function attachScrollScrub(context, raw) {
 		if (scrubbing) return;
 		scrubbing = true;
 		previousBand = null;
+		useTimeline = timeline !== null && timelineIsUsable(timeline, axis);
 		if (context.lottie.state !== LottieState.loading) {
 			gestureStarted = true;
 			context.lottie.scrubStart();
@@ -93,6 +105,7 @@ function attachScrollScrub(context, raw) {
 		observer?.disconnect();
 		observer = null;
 		timeline = null;
+		useTimeline = false;
 		observedRoot = root;
 		if (root === null) return;
 		const ViewTimelineCtor = globalThis.ViewTimeline;
@@ -136,9 +149,10 @@ function attachScrollScrub(context, raw) {
 * </LottieInteractions>
 * ```
 *
-* Progress is the platform's own scroll timeline where the browser has one,
-* and the same arithmetic measured by hand where it does not; the numbers
-* agree by construction. While the animation is out of view nothing samples
+* Progress is the platform's own scroll timeline where the browser has one
+* and its scroller is one that scrolls, and the same arithmetic measured by
+* hand against the viewport where it does not; the numbers agree by
+* construction. While the animation is out of view nothing samples
 * at all, and playback state is held by the scrub gesture, so whatever was
 * true before the scrub is restored when it leaves.
 */

package/build/interactions/types.d.cts

@@ -10,7 +10,11 @@ import { LottieInstance } from "../animation/types.cjs";
  * at the moment an event fires without the behaviour ever re-attaching.
  */
 interface LottieInteractionContext {
-  /** The animation: values, commands, `subscribe`, `root`. Read fresh each use. */
+  /**
+   * The animation: values, commands, `subscribe`, `root`. Live: every member
+   * answers the current animation, so keeping or destructuring it is safe; a
+   * value pulled out of it is a copy of that moment.
+   */
   readonly lottie: LottieInstance;
   /** The descriptor's options as they are right now. */
   options: () => unknown;

package/build/interactions/types.d.ts

@@ -10,7 +10,11 @@ import { LottieInstance } from "../animation/types.js";
  * at the moment an event fires without the behaviour ever re-attaching.
  */
 interface LottieInteractionContext {
-  /** The animation: values, commands, `subscribe`, `root`. Read fresh each use. */
+  /**
+   * The animation: values, commands, `subscribe`, `root`. Live: every member
+   * answers the current animation, so keeping or destructuring it is safe; a
+   * value pulled out of it is a copy of that moment.
+   */
   readonly lottie: LottieInstance;
   /** The descriptor's options as they are right now. */
   options: () => unknown;

package/build/interactions/useInteractionsRunner.cjs

@@ -3,6 +3,14 @@ const require_useStableValue = require("../utils/useStableValue.cjs");
 const require_LottieRegistryContext = require("../animation/LottieRegistryContext.cjs");
 let react = require("react");
 //#region src/interactions/useInteractionsRunner.ts
+function createLiveInstanceView(box) {
+	const view = {};
+	for (const key of Object.keys(box.current)) Object.defineProperty(view, key, {
+		enumerable: true,
+		get: () => box.current[key]
+	});
+	return view;
+}
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -41,6 +49,7 @@ function useInteractionsRunner(source, interactions) {
 		options: projectData(interaction.options)
 	})));
 	const runtime = (0, react.useRef)(/* @__PURE__ */ new Map()).current;
+	const views = (0, react.useRef)(/* @__PURE__ */ new WeakMap()).current;
 	const armSlot = (box, slot, memory) => {
 		const interaction = latest.current[slot];
 		const record = {
@@ -50,10 +59,13 @@ function useInteractionsRunner(source, interactions) {
 			listeners: /* @__PURE__ */ new Set(),
 			memory: memory ?? {}
 		};
+		let view = views.get(box);
+		if (view === void 0) {
+			view = createLiveInstanceView(box);
+			views.set(box, view);
+		}
 		const context = {
-			get lottie() {
-				return box.current;
-			},
+			lottie: view,
 			options: () => latest.current[slot]?.options,
 			onChange: (listener) => {
 				record.listeners.add(listener);

package/build/interactions/useInteractionsRunner.js

@@ -3,6 +3,14 @@ import { useStableValue } from "../utils/useStableValue.js";
 import { createLottieRegistry } from "../animation/LottieRegistryContext.js";
 import { useEffect, useRef, useState } from "react";
 //#region src/interactions/useInteractionsRunner.ts
+function createLiveInstanceView(box) {
+	const view = {};
+	for (const key of Object.keys(box.current)) Object.defineProperty(view, key, {
+		enumerable: true,
+		get: () => box.current[key]
+	});
+	return view;
+}
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -41,6 +49,7 @@ function useInteractionsRunner(source, interactions) {
 		options: projectData(interaction.options)
 	})));
 	const runtime = useRef(/* @__PURE__ */ new Map()).current;
+	const views = useRef(/* @__PURE__ */ new WeakMap()).current;
 	const armSlot = (box, slot, memory) => {
 		const interaction = latest.current[slot];
 		const record = {
@@ -50,10 +59,13 @@ function useInteractionsRunner(source, interactions) {
 			listeners: /* @__PURE__ */ new Set(),
 			memory: memory ?? {}
 		};
+		let view = views.get(box);
+		if (view === void 0) {
+			view = createLiveInstanceView(box);
+			views.set(box, view);
+		}
 		const context = {
-			get lottie() {
-				return box.current;
-			},
+			lottie: view,
 			options: () => latest.current[slot]?.options,
 			onChange: (listener) => {
 				record.listeners.add(listener);

package/build/interactions/useLottieInteractions.cjs

@@ -1,3 +1,4 @@
+"use client";
 const require_useInteractionsRunner = require("./useInteractionsRunner.cjs");
 //#region src/interactions/useLottieInteractions.ts
 /**

package/build/interactions/useLottieInteractions.js

@@ -1,3 +1,4 @@
+"use client";
 import { useInteractionsRunner, useSingleInstanceSource } from "./useInteractionsRunner.js";
 //#region src/interactions/useLottieInteractions.ts
 /**

package/build/overlays/LottieError.cjs

@@ -1,3 +1,4 @@
+"use client";
 const require_renderStyledElement = require("../animation/renderStyledElement.cjs");
 const require_useLottieInstance = require("../animation/useLottieInstance.cjs");
 const require_types = require("../animation/types.cjs");

package/build/overlays/LottieError.js

@@ -1,3 +1,4 @@
+"use client";
 import { renderStyledElement } from "../animation/renderStyledElement.js";
 import { useLottieInstance } from "../animation/useLottieInstance.js";
 import { LottieState } from "../animation/types.js";

package/build/overlays/LottieLoading.cjs

@@ -1,3 +1,4 @@
+"use client";
 const require_renderStyledElement = require("../animation/renderStyledElement.cjs");
 const require_useLottieInstance = require("../animation/useLottieInstance.cjs");
 const require_types = require("../animation/types.cjs");

package/build/overlays/LottieLoading.js

@@ -1,3 +1,4 @@
+"use client";
 import { renderStyledElement } from "../animation/renderStyledElement.js";
 import { useLottieInstance } from "../animation/useLottieInstance.js";
 import { LottieState } from "../animation/types.js";

package/changes.json

@@ -1,5 +1,5 @@
 {
   "bumped": {},
-  "timestamp": "2026-08-16T00:26:02.638Z",
+  "timestamp": "2026-08-17T00:14:39.892Z",
   "totalUpdated": 0
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@depup/lottie-react",
-  "version": "3.0.0-depup.0",
+  "version": "3.1.0-depup.0",
   "description": "Lottie animations in React: one component for the easy path, the whole engine when you need control. (with updated dependencies)",
   "keywords": [
     "lottie-react",
@@ -156,13 +156,13 @@
     "@size-limit/preset-small-lib": "^13.0.3",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "^16.3.2",
-    "@testing-library/user-event": "^14.6.3",
+    "@testing-library/user-event": "^14.6.4",
     "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",
     "@vitejs/plugin-react": "^6.0.5",
     "@vitest/coverage-v8": "^4.1.10",
-    "concurrently": "^10.0.4",
+    "concurrently": "^10.0.5",
     "happy-dom": "^20.11.2",
     "publint": "^0.3.23",
     "size-limit": "^13.0.3",
@@ -174,8 +174,8 @@
     "changes": {},
     "depsUpdated": 0,
     "originalPackage": "lottie-react",
-    "originalVersion": "3.0.0",
-    "processedAt": "2026-08-16T00:26:07.347Z",
+    "originalVersion": "3.1.0",
+    "processedAt": "2026-08-17T00:14:54.679Z",
     "smokeTest": "passed"
   }
 }