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

package/build/animation/createLottieComponent.js

@@ -0,0 +1,131 @@
+import { mergeRefs } from "../utils/mergeRefs.js";
+import { polymorphicForwardRef } from "./polymorphicForwardRef.js";
+import { renderStyledElement } from "./renderStyledElement.js";
+import { LottieInstanceContext } from "./LottieInstanceContext.js";
+import { lottieDisplayClass, lottieDisplayStyles } from "./LottieDisplay.js";
+import { useLottieAnimation } from "./useLottieAnimation.js";
+import { useCallback, useEffect, useImperativeHandle, useMemo, useRef } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/animation/createLottieComponent.tsx
+/**
+* The class the element around the animation carries when you place the
+* animation yourself, and the name React deduplicates its stylesheet by.
+*/
+const lottieRootClass = "lottie-root";
+/**
+* The rules that element carries, at zero specificity and inside the library's
+* cascade layer, so any rule the consumer writes beats them per property.
+*
+* The column is what puts the controls below the animation, and `position` is
+* what the overlays anchor to. The second rule is what lets the animation take
+* the space the controls leave, since the display's own default height is a
+* full 100% that would otherwise push them out of the box.
+*
+* The descendant rule is written as two separate `:where()` selectors rather
+* than one wrapping the combinator. The two are identical CSS at identical zero
+* specificity, so the split form costs nothing and reads as two independent
+* claims about specificity.
+*
+* The third rule is what this element looks like once it fills the screen. A
+* browser paints a black backdrop behind whatever goes fullscreen and leaves
+* the element itself transparent, so without a surface of its own the animation
+* sits on black and the control bar, whose colours are all inherited, keeps the
+* page's dark text and becomes close to unreadable. Measured in Chromium
+* against the real bar. `Canvas` and `CanvasText` are the system page colours
+* and are taken as a pair, so the two can never contradict each other the way a
+* background without a matching foreground can; they follow the consumer's
+* declared colour scheme rather than a colour this library picked, and the rule
+* is zero-specificity like every other, so one line of their own CSS replaces
+* either. It cannot be verified here, since this environment has no Fullscreen
+* API at all.
+*/
+const lottieRootStyles = `:where(.${lottieRootClass}){position:relative;display:flex;flex-direction:column}:where(.${lottieRootClass}) > :where(.${lottieDisplayClass}){flex:1;height:auto}:where(.${lottieRootClass}:fullscreen){background:Canvas;color:CanvasText}`;
+/**
+* Builds the component all three public ones are: the full, svg and light
+* builds differ in the engine they load and in the renderers they admit, and in
+* nothing else.
+*
+* `Renderers` is what narrows a smaller build to the renderers it actually
+* contains, so asking it for one it does not have is a compile error rather
+* than a blank animation and a runtime throw.
+*/
+function createLottieComponent(engine) {
+	return polymorphicForwardRef(function Lottie({ as, children, className, lottieRef, src, renderer, rendererSettings, loop, speed, direction, autoplay, segment, assetsPath, debug, subscriptions, ...rest }, ref) {
+		const instance = useLottieAnimation(engine, {
+			src,
+			renderer,
+			rendererSettings,
+			loop,
+			speed,
+			direction,
+			autoplay,
+			segment,
+			assetsPath,
+			debug,
+			subscriptions
+		});
+		const { setDisplayRef, setRootRef } = instance;
+		useImperativeHandle(lottieRef, () => ({
+			reload: instance.reload,
+			play: instance.play,
+			pause: instance.pause,
+			stop: instance.stop,
+			seek: instance.seek,
+			scrubStart: instance.scrubStart,
+			scrubTo: instance.scrubTo,
+			scrubEnd: instance.scrubEnd,
+			playSegments: instance.playSegments,
+			resetSegments: instance.resetSegments,
+			setSpeed: instance.setSpeed,
+			setDirection: instance.setDirection,
+			setLoop: instance.setLoop,
+			animationItem: instance.animationItem
+		}));
+		const attached = useRef(0);
+		const countDisplay = useCallback((node) => {
+			attached.current += node === null ? -1 : 1;
+			setDisplayRef(node);
+		}, [setDisplayRef]);
+		const published = useMemo(() => ({
+			...instance,
+			setDisplayRef: countDisplay
+		}), [instance, countDisplay]);
+		const hasChildren = children !== void 0;
+		useEffect(() => {
+			if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
+				if (!hasChildren || attached.current === 1) return;
+				if (attached.current === 0) console.warn("[lottie-react] <Lottie> was given children and none of them is a <LottieDisplay>, so the animation has nowhere to be drawn. Add one where the animation should go. A display rendered conditionally has not appeared yet on this pass, which is the one case where this warning is expected.");
+				else console.warn(`[lottie-react] <Lottie> was given ${attached.current} <LottieDisplay> children and an animation can only be drawn in one of them, so the last to attach is the one that gets it. Render one display per animation.`);
+			}
+		}, [hasChildren]);
+		const attachDisplay = useMemo(() => mergeRefs(ref, countDisplay, setRootRef), [
+			ref,
+			countDisplay,
+			setRootRef
+		]);
+		const attachWrapper = useMemo(() => mergeRefs(ref, setRootRef), [ref, setRootRef]);
+		const tag = typeof as === "string" ? as : "div";
+		if (!hasChildren) return renderStyledElement({
+			tag,
+			styleClass: lottieDisplayClass,
+			styles: lottieDisplayStyles,
+			className,
+			attributes: rest,
+			ref: attachDisplay
+		});
+		return /* @__PURE__ */ jsx(LottieInstanceContext.Provider, {
+			value: published,
+			children: renderStyledElement({
+				tag,
+				styleClass: lottieRootClass,
+				styles: lottieRootStyles,
+				className,
+				attributes: rest,
+				ref: attachWrapper,
+				children
+			})
+		});
+	});
+}
+//#endregion
+export { createLottieComponent };

package/build/animation/hasExpressions.cjs

@@ -0,0 +1,25 @@
+//#region src/animation/hasExpressions.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Whether a parsed animation carries an expression anywhere in it.
+*
+* An expression is a non-empty string under the key `x` on an animatable
+* property, which is also how the engine finds them. The type of the value is
+* what decides, not the key: inside keyframes `x` names the numeric easing
+* handles, and on a mask it names the expansion property, an object which may
+* itself carry an expression one level down. The walk covers objects and
+* arrays across the whole document rather than `layers` alone, because a
+* precomp's layers live under `assets`, and it stops at the first find. It
+* assumes the tree shape parsed JSON always has: an object that referenced
+* itself would recurse without end.
+*/
+function hasExpressions(value) {
+	if (Array.isArray(value)) return value.some(hasExpressions);
+	if (!isRecord(value)) return false;
+	if (typeof value.x === "string" && value.x !== "") return true;
+	return Object.values(value).some(hasExpressions);
+}
+//#endregion
+exports.hasExpressions = hasExpressions;

package/build/animation/hasExpressions.js

@@ -0,0 +1,25 @@
+//#region src/animation/hasExpressions.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Whether a parsed animation carries an expression anywhere in it.
+*
+* An expression is a non-empty string under the key `x` on an animatable
+* property, which is also how the engine finds them. The type of the value is
+* what decides, not the key: inside keyframes `x` names the numeric easing
+* handles, and on a mask it names the expansion property, an object which may
+* itself carry an expression one level down. The walk covers objects and
+* arrays across the whole document rather than `layers` alone, because a
+* precomp's layers live under `assets`, and it stops at the first find. It
+* assumes the tree shape parsed JSON always has: an object that referenced
+* itself would recurse without end.
+*/
+function hasExpressions(value) {
+	if (Array.isArray(value)) return value.some(hasExpressions);
+	if (!isRecord(value)) return false;
+	if (typeof value.x === "string" && value.x !== "") return true;
+	return Object.values(value).some(hasExpressions);
+}
+//#endregion
+export { hasExpressions };

package/build/animation/normalizeAnimationSource.cjs

@@ -0,0 +1,38 @@
+//#region src/animation/normalizeAnimationSource.ts
+/**
+* Turns the `src` prop into the pair of fields lottie-web understands, or
+* `null` when it is not something an animation could be loaded from.
+*
+* A non-empty string is a URL or path that the engine fetches and parses as
+* JSON. A `.lottie` archive is **not** supported: it is a zip, and nothing here
+* or in lottie-web unpacks one.
+*
+* An object is the parsed animation itself, and it is **always** shallow-copied
+* before the engine sees it. lottie-web writes `__complete` onto whatever it is
+* handed, so a frozen object throws `TypeError: Cannot add property __complete`
+* and takes the whole load down with it. That happens with `import * as data
+* from "./animation.json"` under Node's own JSON modules, whose namespace is
+* not extensible.
+*
+* The copy is unconditional rather than guarded by `Object.isExtensible`,
+* because the shape of that namespace object differs by toolchain: Node's is
+* not extensible while a bundler's usually is. A guard would therefore behave
+* differently depending on who built the consumer's application, and a copy
+* behaves the same everywhere. It costs about 70 nanoseconds and does not grow
+* with the animation, since only the top level is copied.
+*
+* The copy does not protect the objects inside `layers`, which the engine
+* annotates in place. That is harmless, because those writes are idempotent
+* flags, and avoiding it would mean deep-copying the entire animation on every
+* load.
+*/
+function normalizeAnimationSource(source) {
+	if (typeof source === "string") {
+		const path = source.trim();
+		return path.length > 0 ? { path } : null;
+	}
+	if (typeof source === "object" && source !== null && !Array.isArray(source)) return { animationData: { ...source } };
+	return null;
+}
+//#endregion
+exports.normalizeAnimationSource = normalizeAnimationSource;

package/build/animation/normalizeAnimationSource.js

@@ -0,0 +1,38 @@
+//#region src/animation/normalizeAnimationSource.ts
+/**
+* Turns the `src` prop into the pair of fields lottie-web understands, or
+* `null` when it is not something an animation could be loaded from.
+*
+* A non-empty string is a URL or path that the engine fetches and parses as
+* JSON. A `.lottie` archive is **not** supported: it is a zip, and nothing here
+* or in lottie-web unpacks one.
+*
+* An object is the parsed animation itself, and it is **always** shallow-copied
+* before the engine sees it. lottie-web writes `__complete` onto whatever it is
+* handed, so a frozen object throws `TypeError: Cannot add property __complete`
+* and takes the whole load down with it. That happens with `import * as data
+* from "./animation.json"` under Node's own JSON modules, whose namespace is
+* not extensible.
+*
+* The copy is unconditional rather than guarded by `Object.isExtensible`,
+* because the shape of that namespace object differs by toolchain: Node's is
+* not extensible while a bundler's usually is. A guard would therefore behave
+* differently depending on who built the consumer's application, and a copy
+* behaves the same everywhere. It costs about 70 nanoseconds and does not grow
+* with the animation, since only the top level is copied.
+*
+* The copy does not protect the objects inside `layers`, which the engine
+* annotates in place. That is harmless, because those writes are idempotent
+* flags, and avoiding it would mean deep-copying the entire animation on every
+* load.
+*/
+function normalizeAnimationSource(source) {
+	if (typeof source === "string") {
+		const path = source.trim();
+		return path.length > 0 ? { path } : null;
+	}
+	if (typeof source === "object" && source !== null && !Array.isArray(source)) return { animationData: { ...source } };
+	return null;
+}
+//#endregion
+export { normalizeAnimationSource };

package/build/animation/polymorphicForwardRef.cjs

@@ -0,0 +1,18 @@
+//#region src/animation/polymorphicForwardRef.ts
+/**
+* `forwardRef`, with the render function's own type parameters kept.
+*
+* A component that chooses its element through `as` is generic in that tag, and
+* React's `forwardRef` is not: its signature settles the props at one type, so
+* the tag is lost and `as="button" type="button"` stops typechecking while
+* invented props start passing. Handing the same runtime function a signature
+* that carries the parameters through is what restores per-element props.
+*
+* The assertion lives here, alone, so that there is one of it and so that what
+* removes it is written beside it. React 18 is the whole reason it exists,
+* because a function component receives a `ref` only through `forwardRef`
+* there.
+*/
+const polymorphicForwardRef = require("react").forwardRef;
+//#endregion
+exports.polymorphicForwardRef = polymorphicForwardRef;

package/build/animation/polymorphicForwardRef.js

@@ -0,0 +1,19 @@
+import { forwardRef } from "react";
+//#region src/animation/polymorphicForwardRef.ts
+/**
+* `forwardRef`, with the render function's own type parameters kept.
+*
+* A component that chooses its element through `as` is generic in that tag, and
+* React's `forwardRef` is not: its signature settles the props at one type, so
+* the tag is lost and `as="button" type="button"` stops typechecking while
+* invented props start passing. Handing the same runtime function a signature
+* that carries the parameters through is what restores per-element props.
+*
+* The assertion lives here, alone, so that there is one of it and so that what
+* removes it is written beside it. React 18 is the whole reason it exists,
+* because a function component receives a `ref` only through `forwardRef`
+* there.
+*/
+const polymorphicForwardRef = forwardRef;
+//#endregion
+export { polymorphicForwardRef };

package/build/animation/renderStyledElement.cjs

@@ -0,0 +1,31 @@
+const require_styleLayer = require("./styleLayer.cjs");
+const require_stylePrecedence = require("./stylePrecedence.cjs");
+let react = require("react");
+let react_jsx_runtime = require("react/jsx-runtime");
+//#region src/animation/renderStyledElement.tsx
+/**
+* Renders one element carrying a library class, together with the stylesheet
+* that class names.
+*
+* The class and the `href` are one string, so React deduplicates the rules by
+* the same name the rules are scoped to: two components can only collide in the
+* document if they already collide in CSS, which is visible rather than silent.
+*
+* Built through `createElement` rather than as JSX, because JSX cannot take an
+* element type that is still generic: `<Tag />` where the tag comes from `as`
+* is `TS2604, no construct or call signatures`. Narrowing to one concrete tag
+* instead needs an assertion, which this does not.
+*/
+function renderStyledElement({ tag, styleClass, styles, className, attributes, ref, children }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [(0, react.createElement)(tag, {
+		...attributes,
+		className: className ? `${styleClass} ${className}` : styleClass,
+		ref
+	}, children), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("style", {
+		href: styleClass,
+		precedence: require_stylePrecedence.stylePrecedence,
+		children: `@layer ${require_styleLayer.styleLayer}{${styles}}`
+	})] });
+}
+//#endregion
+exports.renderStyledElement = renderStyledElement;

package/build/animation/renderStyledElement.js

@@ -0,0 +1,31 @@
+import { styleLayer } from "./styleLayer.js";
+import { stylePrecedence } from "./stylePrecedence.js";
+import { createElement } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/animation/renderStyledElement.tsx
+/**
+* Renders one element carrying a library class, together with the stylesheet
+* that class names.
+*
+* The class and the `href` are one string, so React deduplicates the rules by
+* the same name the rules are scoped to: two components can only collide in the
+* document if they already collide in CSS, which is visible rather than silent.
+*
+* Built through `createElement` rather than as JSX, because JSX cannot take an
+* element type that is still generic: `<Tag />` where the tag comes from `as`
+* is `TS2604, no construct or call signatures`. Narrowing to one concrete tag
+* instead needs an assertion, which this does not.
+*/
+function renderStyledElement({ tag, styleClass, styles, className, attributes, ref, children }) {
+	return /* @__PURE__ */ jsxs(Fragment, { children: [createElement(tag, {
+		...attributes,
+		className: className ? `${styleClass} ${className}` : styleClass,
+		ref
+	}, children), /* @__PURE__ */ jsx("style", {
+		href: styleClass,
+		precedence: stylePrecedence,
+		children: `@layer ${styleLayer}{${styles}}`
+	})] });
+}
+//#endregion
+export { renderStyledElement };

package/build/animation/resolveSeekTarget.cjs

@@ -0,0 +1,97 @@
+//#region src/animation/resolveSeekTarget.ts
+/**
+* Narrows an unknown value to a marker we can use.
+*
+* A marker whose After Effects comment parsed as JSON without a `name` fails
+* here, which matches the engine: such a marker cannot be addressed by name at
+* all, so a designer can label something the code has no way to reach.
+*/
+function isMarker(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("time" in value) || typeof value.time !== "number") return false;
+	if ("duration" in value) {
+		const { duration } = value;
+		if (duration !== void 0 && typeof duration !== "number") return false;
+	}
+	if (!("payload" in value)) return false;
+	const { payload } = value;
+	if (typeof payload !== "object" || payload === null) return false;
+	return "name" in payload && typeof payload.name === "string";
+}
+/**
+* The animation's markers, or an empty list when it has none we can read.
+*
+* The `in` check is what makes the undeclared property readable without a cast:
+* it narrows to a record whose value is `unknown`, which the guard above then
+* takes the rest of the way.
+*/
+function readMarkers(item) {
+	if (!("markers" in item)) return [];
+	const { markers } = item;
+	if (!Array.isArray(markers)) return [];
+	return markers.filter(isMarker);
+}
+function findMarker(item, name) {
+	for (const marker of readMarkers(item)) if (marker.payload.name === name) return marker;
+	return null;
+}
+/** The frame a target asks for, before it is held inside the playable range. */
+function requestedFrame(item, target) {
+	if (typeof target === "number") return target;
+	const { frame, percent, seconds, marker } = target;
+	if (frame !== void 0) return frame;
+	if (percent !== void 0) return item.totalFrames * percent / 100;
+	if (seconds !== void 0) return seconds * item.frameRate;
+	const found = marker === void 0 ? null : findMarker(item, marker);
+	return found === null ? null : found.time - item.firstFrame;
+}
+/**
+* Turns a seek target into a frame inside the playable range.
+*
+* Returns `null` when the target names nothing the animation has, which is an
+* unknown marker or a number that is not finite. `requested` is what was asked
+* for and `frame` is what is reachable, so a caller can tell that a position
+* was pulled back to the range without this having to say anything about it.
+*/
+function resolveSeekTarget(item, target) {
+	const requested = requestedFrame(item, target);
+	if (requested === null || !Number.isFinite(requested)) return null;
+	const last = Math.max(item.totalFrames - .001, 0);
+	return {
+		frame: Math.min(Math.max(requested, 0), last),
+		requested
+	};
+}
+/** Distinguishes one range from a list of them, which share an array type. */
+function isSingleRange(segments) {
+	return typeof segments[0] === "number";
+}
+/**
+* Turns what a caller passed into the list of ranges the engine takes.
+*
+* Returns `null` when nothing playable was described: a range whose ends are
+* equal or not finite, an empty list, an unknown marker, or a marker carrying
+* no duration. That last one is a labelled position rather than a labelled
+* span, and the engine would respond to it by playing the entire animation.
+*
+* A marker's frames are used as they are. Unlike a seek, a range endpoint is
+* absolute, so the correction that seeking needs would be wrong here.
+*
+* The result is always freshly built, never the caller's own arrays, because
+* the engine queues whatever it is handed and the input is typed `readonly`.
+*/
+function resolveSegments(item, segments) {
+	if ("marker" in segments) {
+		const marker = findMarker(item, segments.marker);
+		if (marker === null || !marker.duration) return null;
+		return [[marker.time, marker.time + marker.duration]];
+	}
+	const ranges = isSingleRange(segments) ? [segments] : segments;
+	if (ranges.length === 0) return null;
+	for (const [start, end] of ranges) if (!Number.isFinite(start) || !Number.isFinite(end) || start === end) return null;
+	return ranges.map(([start, end]) => [start, end]);
+}
+//#endregion
+exports.readMarkers = readMarkers;
+exports.resolveSeekTarget = resolveSeekTarget;
+exports.resolveSegments = resolveSegments;

package/build/animation/resolveSeekTarget.js

@@ -0,0 +1,95 @@
+//#region src/animation/resolveSeekTarget.ts
+/**
+* Narrows an unknown value to a marker we can use.
+*
+* A marker whose After Effects comment parsed as JSON without a `name` fails
+* here, which matches the engine: such a marker cannot be addressed by name at
+* all, so a designer can label something the code has no way to reach.
+*/
+function isMarker(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("time" in value) || typeof value.time !== "number") return false;
+	if ("duration" in value) {
+		const { duration } = value;
+		if (duration !== void 0 && typeof duration !== "number") return false;
+	}
+	if (!("payload" in value)) return false;
+	const { payload } = value;
+	if (typeof payload !== "object" || payload === null) return false;
+	return "name" in payload && typeof payload.name === "string";
+}
+/**
+* The animation's markers, or an empty list when it has none we can read.
+*
+* The `in` check is what makes the undeclared property readable without a cast:
+* it narrows to a record whose value is `unknown`, which the guard above then
+* takes the rest of the way.
+*/
+function readMarkers(item) {
+	if (!("markers" in item)) return [];
+	const { markers } = item;
+	if (!Array.isArray(markers)) return [];
+	return markers.filter(isMarker);
+}
+function findMarker(item, name) {
+	for (const marker of readMarkers(item)) if (marker.payload.name === name) return marker;
+	return null;
+}
+/** The frame a target asks for, before it is held inside the playable range. */
+function requestedFrame(item, target) {
+	if (typeof target === "number") return target;
+	const { frame, percent, seconds, marker } = target;
+	if (frame !== void 0) return frame;
+	if (percent !== void 0) return item.totalFrames * percent / 100;
+	if (seconds !== void 0) return seconds * item.frameRate;
+	const found = marker === void 0 ? null : findMarker(item, marker);
+	return found === null ? null : found.time - item.firstFrame;
+}
+/**
+* Turns a seek target into a frame inside the playable range.
+*
+* Returns `null` when the target names nothing the animation has, which is an
+* unknown marker or a number that is not finite. `requested` is what was asked
+* for and `frame` is what is reachable, so a caller can tell that a position
+* was pulled back to the range without this having to say anything about it.
+*/
+function resolveSeekTarget(item, target) {
+	const requested = requestedFrame(item, target);
+	if (requested === null || !Number.isFinite(requested)) return null;
+	const last = Math.max(item.totalFrames - .001, 0);
+	return {
+		frame: Math.min(Math.max(requested, 0), last),
+		requested
+	};
+}
+/** Distinguishes one range from a list of them, which share an array type. */
+function isSingleRange(segments) {
+	return typeof segments[0] === "number";
+}
+/**
+* Turns what a caller passed into the list of ranges the engine takes.
+*
+* Returns `null` when nothing playable was described: a range whose ends are
+* equal or not finite, an empty list, an unknown marker, or a marker carrying
+* no duration. That last one is a labelled position rather than a labelled
+* span, and the engine would respond to it by playing the entire animation.
+*
+* A marker's frames are used as they are. Unlike a seek, a range endpoint is
+* absolute, so the correction that seeking needs would be wrong here.
+*
+* The result is always freshly built, never the caller's own arrays, because
+* the engine queues whatever it is handed and the input is typed `readonly`.
+*/
+function resolveSegments(item, segments) {
+	if ("marker" in segments) {
+		const marker = findMarker(item, segments.marker);
+		if (marker === null || !marker.duration) return null;
+		return [[marker.time, marker.time + marker.duration]];
+	}
+	const ranges = isSingleRange(segments) ? [segments] : segments;
+	if (ranges.length === 0) return null;
+	for (const [start, end] of ranges) if (!Number.isFinite(start) || !Number.isFinite(end) || start === end) return null;
+	return ranges.map(([start, end]) => [start, end]);
+}
+//#endregion
+export { readMarkers, resolveSeekTarget, resolveSegments };

package/build/animation/styleLayer.cjs

@@ -0,0 +1,24 @@
+//#region src/animation/styleLayer.ts
+/**
+* The cascade layer every library stylesheet is wrapped in.
+*
+* The wrapper exists for consumers whose own CSS lives in cascade layers,
+* Tailwind 4 being the common case. Unlayered rules outrank all layered rules,
+* so without a layer of our own even a zero-specificity default beats every
+* utility class. Inside a layer, the defaults can be ranked below the
+* consumer's layers with one declaration written before their own styles load:
+*
+* ```css
+* @layer lottie-react;
+* ```
+*
+* A consumer whose CSS is unlayered needs nothing: unlayered rules beat
+* layered ones, so their styles keep winning as before.
+*
+* Named after the package, like the style precedence, because a name a
+* consumer already associates with the library cannot collide with a layer
+* ladder of their own.
+*/
+const styleLayer = "lottie-react";
+//#endregion
+exports.styleLayer = styleLayer;

package/build/animation/styleLayer.js

@@ -0,0 +1,24 @@
+//#region src/animation/styleLayer.ts
+/**
+* The cascade layer every library stylesheet is wrapped in.
+*
+* The wrapper exists for consumers whose own CSS lives in cascade layers,
+* Tailwind 4 being the common case. Unlayered rules outrank all layered rules,
+* so without a layer of our own even a zero-specificity default beats every
+* utility class. Inside a layer, the defaults can be ranked below the
+* consumer's layers with one declaration written before their own styles load:
+*
+* ```css
+* @layer lottie-react;
+* ```
+*
+* A consumer whose CSS is unlayered needs nothing: unlayered rules beat
+* layered ones, so their styles keep winning as before.
+*
+* Named after the package, like the style precedence, because a name a
+* consumer already associates with the library cannot collide with a layer
+* ladder of their own.
+*/
+const styleLayer = "lottie-react";
+//#endregion
+export { styleLayer };

package/build/animation/stylePrecedence.cjs

@@ -0,0 +1,12 @@
+//#region src/animation/stylePrecedence.ts
+/**
+* How React ranks every stylesheet this library renders.
+*
+* One value for all of them, so they sit together in a block a consumer can
+* rank their own CSS against as a unit. It names the package rather than a
+* position, because React treats a precedence it meets first as lower, so a
+* position would only be right by accident of render order.
+*/
+const stylePrecedence = "lottie-react";
+//#endregion
+exports.stylePrecedence = stylePrecedence;

package/build/animation/stylePrecedence.js

@@ -0,0 +1,12 @@
+//#region src/animation/stylePrecedence.ts
+/**
+* How React ranks every stylesheet this library renders.
+*
+* One value for all of them, so they sit together in a block a consumer can
+* rank their own CSS against as a unit. It names the package rather than a
+* position, because React treats a precedence it meets first as lower, so a
+* position would only be right by accident of render order.
+*/
+const stylePrecedence = "lottie-react";
+//#endregion
+export { stylePrecedence };