@lovince/motion 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lovince Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,255 @@
-# Temporary Holding Version
+# @lovince/motion
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A framework-agnostic motion system. **CSS** handles light interface motion,
+**GSAP** orchestrates timelines and scroll scenes, and **Lenis** provides
+smooth scrolling. Every animation has an owner, a cleanup and a
+reduced-motion policy.
+
+> **Status: `0.1.0`, experimental.** The API may change before `1.0`.
+
+```bash
+bun add @lovince/motion
+bun add gsap lenis      # only for the entries that use them
+```
+
+The goal is not to animate everything. It is to make the motion a site does
+have consistent, interruptible and accessible.
+
+## Entries
+
+Each engine sits behind its own entry, so an app pays only for what it imports
+and a missing optional peer breaks nothing else.
+
+| Import | Needs | Gives |
+|---|---|---|
+| `@lovince/motion` | — | `createMotion`, preferences, `revealOnScroll`, `fadeIn`, `splitText`, `focusTarget`, `whenMotionAllowed`, motion config and tokens |
+| `@lovince/motion/gsap` | `gsap` | `createTimeline`, `createStagger`, `createScrollReveal`, `createParallax`, `createHorizontalScroll`, `gsapScrollDriver` |
+| `@lovince/motion/scroll` | `lenis` | `createSmoothScroll` |
+| `@lovince/motion/presets` | `gsap` | `heroEntrance`, `revealText`, `revealImage`, `followState`, `createPageTransition` |
+| `@lovince/motion/vue` | `vue` | `useMotion`, `useMotionEffect`, `v-reveal` |
+| `@lovince/motion/styles.css` | — | tokens + utilities + reveal presets (or `tokens.css`, `utilities.css`, `presets.css` on their own) |
+
+`gsap`, `lenis` and `vue` are optional peers, so your app controls their
+versions and there is never a second copy at runtime.
+
+## Who owns what
+
+| Engine | Owns |
+|---|---|
+| CSS | Hover, focus and press feedback, underlines, small transitions, decorative loops, simple scroll reveals |
+| GSAP | Hero sequences, staggered and split typography, scroll-linked scenes, pinning, horizontal galleries, page transitions |
+| Lenis | Smooth scrolling, as one service per scroller, on GSAP's clock when both are used |
+
+Give each animation one owner. Never animate the same element with CSS and
+GSAP at once.
+
+## Quick start
+
+```ts
+import '@lovince/motion/styles.css'
+import { createMotion, revealOnScroll } from '@lovince/motion'
+import { gsapScrollDriver } from '@lovince/motion/gsap'
+import { heroEntrance } from '@lovince/motion/presets'
+import { createSmoothScroll } from '@lovince/motion/scroll'
+
+const motion = createMotion({ root: '#app' })
+
+heroEntrance({ label: '.eyebrow', heading: 'h1', body: '.lede', actions: '.ctas', media: '.hero-image' }, { context: motion })
+revealOnScroll('[data-reveal]', { context: motion })
+const scroll = createSmoothScroll({ driver: gsapScrollDriver() })
+
+// When this view goes away:
+motion.destroy()   // reverts every tween, trigger, observer and split it owns
+scroll.destroy()
+```
+
+## The model
+
+- **`createMotion()` is the owner.** It scopes selectors to a root, holds every
+  effect and cleanup, and `destroy()` reverts them all, newest first. Each API
+  takes `{ context }`. Without one, the call gets its own context and returns
+  a cleanup.
+- **Effects re-run when the preference changes.** An effect sets up and returns
+  its undo. If the user switches reduced motion on or off while the page is
+  open, the effect is undone and run again with `scope.reduced` updated.
+  Progress carries over, so a finished entrance never replays.
+- **Outcomes, not timeouts.** Anything that ends returns a promise that settles
+  once, `'finished'` or `'cancelled'`, and never rejects. Destroying the
+  owning context cancels it. Nothing waits on a timer.
+- **One vocabulary.** The entrances `fade`, `fade-up`, `fade-down`,
+  `slide-left`, `slide-right`, `scale` and `clip` mean the same in CSS
+  reveals, `fadeIn` (Web Animations) and every GSAP API.
+- **Tokens decide.** Durations, curves and travel distances come from
+  `@lovince/tokens`. `defaultMotionConfig` uses `duration.travel` and
+  `ease.out` (`power3.out`), and the CSS `--motion-*` properties are aliases
+  of `--lovince-*` ones, so CSS and GSAP move alike.
+
+```ts
+const config: MotionConfig = { duration: 0.72, ease: 'power3.out', stagger: 0.08, respectReducedMotion: true }
+```
+
+## Reduced motion
+
+One central policy: under `prefers-reduced-motion: reduce`, motion is replaced
+by its end state, not merely shortened.
+
+| API | Under reduced motion |
+|---|---|
+| `revealOnScroll`, `createScrollReveal` | Content is shown; nothing is hidden |
+| `fadeIn`, `createTimeline`, presets | Jump to the end state; promises settle `finished` |
+| `createParallax`, `createHorizontalScroll` | Not created; the static layout stands |
+| `revealText` | The text is never split |
+| `followState` | States apply instantly |
+| `createSmoothScroll` | No Lenis; native scrolling, switching live |
+
+The stylesheet has the same rules, so CSS-only motion respects it too. Set
+`respectReducedMotion: false` only for motion that carries meaning.
+
+## Progressive enhancement
+
+Content is never hidden by CSS alone. A reveal hides an element only by
+setting `data-motion-state="hidden"` from script, and cleanup removes it. If
+JavaScript, GSAP or the stylesheet fails to load, the page is simply static.
+On the server no effect runs, and every entry imports safely.
+
+## CSS layer
+
+```html
+<a class="motion-link" href="/docs">Docs</a>
+<section data-motion-reveal="fade-up">…</section>
+<h1 class="motion-fade-up" style="--motion-delay: 0.1s">Hello</h1>
+```
+
+`revealOnScroll(targets, { effect, once, threshold, rootMargin, stagger })` uses
+IntersectionObserver, with no GSAP. Elements entering together get a
+`--motion-delay` stagger. `fadeIn(targets, { effect, distance, duration,
+stagger })` runs a Web Animations entrance with `fill: backwards`, so nothing
+lingers afterwards.
+
+Utilities: `.motion-link`, `.motion-lift`, `.motion-press`, `.motion-fade-up`,
+`.motion-fade-in`, `.motion-scale-in`, `.motion-spin`, `.motion-pulse`. All of
+them are opt-in classes, and none touches an element that didn't ask for it.
+
+## GSAP layer
+
+```ts
+const intro = createTimeline((tl, scope) => {
+  tl.from(scope.select('h1'), { autoAlpha: 0, y: 28 })
+    .from(scope.select('.lede'), { autoAlpha: 0, y: 18, duration: 0.5 }, '-=0.4')
+}, { context: motion })
+
+await intro.finished          // 'finished' | 'cancelled'
+```
+
+- `createTimeline(build, { context, vars, scrollTrigger })`: tweens are
+  reverted on destroy. A `scrollTrigger` is dropped under reduced motion.
+- `createStagger(targets, { effect, stagger, onScroll })`: a collection, in
+  document order.
+- `createScrollReveal(targets, { effect, start, repeat })`: batches items
+  entering together.
+- `createParallax(targets, { speed, axis })`: linear, scrubbed, measured once.
+  Keep `speed` small.
+- `createHorizontalScroll(section, track, { minWidth })`: pins below
+  `minWidth` only. Tabbing to an off-screen item scrolls it into view.
+- `splitText(element, { by, mask, onResplit })`: words, chars or lines. It
+  keeps inline markup, handles any script via `Intl.Segmenter`, reads whole
+  words to screen readers, and re-splits lines when the width changes.
+  `revert()` restores the original nodes.
+
+ScrollTrigger is registered on first use, not at import.
+
+## Smooth scrolling
+
+```ts
+const scroll = createSmoothScroll({ driver: gsapScrollDriver(), lenis: { lerp: 0.1 } })
+scroll.scrollTo('#pricing', { offset: -64 })
+scroll.stop() // e.g. while a modal is open
+```
+
+There is one service per scroller. A second call for the same scroller
+shares the instance, and the last `destroy()` tears it down, so components
+can each ask for it safely. With `gsapScrollDriver()`, Lenis runs on GSAP's
+ticker and keeps ScrollTrigger in sync: one frame loop, not two. Without a
+driver, Lenis runs its own loop. Prefer native scrolling for apps, long forms
+and content-heavy pages.
+
+## Presets
+
+- `heroEntrance({ label, heading, body, actions, media })`: reading order,
+  overlapped into one entrance. `actions` children stagger.
+- `revealText(target, { by: 'words' | 'lines' | 'chars', onScroll })`: line
+  reveals rise from behind a mask, and rebuild where they were on resize.
+- `revealImage(frames, { scale })`: the frame opens upward while the image
+  settles from a slight zoom. Only clip-path and transform change.
+- `followState(target, { attribute, states })`: animates to whatever state the
+  component reports (e.g. `data-state` from `@lovince/ui-vue`), so a menu can
+  never look open while it is closed.
+- `createPageTransition({ leave, enter, focus })`: `await leave(old)`, swap,
+  `enter(next)`. Every call settles, a new call cancels the last, and focus
+  moves into the new page.
+
+## Frameworks
+
+**Vanilla.** Create a context after the DOM exists, and call
+`destroy()` when the view is removed.
+
+**Vue / Nuxt.**
+
+```vue
+<script setup lang="ts">
+import { useMotion, useMotionEffect, vReveal } from '@lovince/motion/vue'
+import { createSmoothScroll } from '@lovince/motion/scroll'
+import { gsapScrollDriver } from '@lovince/motion/gsap'
+import { heroEntrance } from '@lovince/motion/presets'
+
+const root = ref<HTMLElement | null>(null)
+useMotion((motion) => heroEntrance({ heading: 'h1', body: 'p' }, { context: motion }), { root })
+const scroll = useMotionEffect(() => createSmoothScroll({ driver: gsapScrollDriver() }))
+</script>
+
+<template>
+  <section ref="root"><h1>Hello</h1><p v-reveal="'fade-up'">…</p></section>
+</template>
+```
+
+Everything starts on mount and is reverted on unmount. Nothing runs during
+server rendering.
+
+**React.**
+
+```tsx
+useLayoutEffect(() => {
+  const motion = createMotion({ root: ref.current })
+  heroEntrance({ heading: 'h1' }, { context: motion })
+  return motion.destroy // Strict Mode's double run is safe: destroy reverts fully
+}, [])
+```
+
+**Svelte.**
+
+```svelte
+<script>
+  import { onMount } from 'svelte'
+  import { createMotion, revealOnScroll } from '@lovince/motion'
+  let root
+  onMount(() => {
+    const motion = createMotion({ root })
+    revealOnScroll('[data-reveal]', { context: motion })
+    return motion.destroy
+  })
+</script>
+```
+
+## Performance
+
+- Only `transform`, `opacity` and, for reveals, `clip-path` animate.
+- Parallax and pinning measure through ScrollTrigger's refresh, never per
+  scroll event. Line splits re-measure only when the width changes.
+- No permanent `will-change`. GSAP sets it per tween.
+- One clock: Lenis rides GSAP's ticker when both are present.
+- The main entry is under 6 KB gzip with no engine. GSAP and Lenis load only
+  through their entries.
+
+## License
+
+MIT

package/dist/accessibility/focus-management.d.ts

@@ -0,0 +1,9 @@
+import { MotionTarget } from '../core/types';
+/**
+ * Moves focus to the first element a target names, making it focusable for
+ * this purpose if it is not. Used after page transitions, so keyboard and
+ * screen-reader users land on the new content. Returns whether focus moved.
+ */
+export declare const focusTarget: (target: MotionTarget, options?: {
+    readonly preventScroll?: boolean;
+}) => boolean;

package/dist/accessibility/index.d.ts

@@ -0,0 +1,2 @@
+export { focusTarget } from './focus-management';
+export { whenMotionAllowed } from './reduced-motion';

package/dist/accessibility/reduced-motion.d.ts

@@ -0,0 +1,7 @@
+import { Cleanup } from '../core/types';
+/**
+ * Runs `setup` only while the user has not asked for reduced motion, tearing
+ * it down when they do and setting it up again if they change back. For
+ * motion that has no reduced form at all, such as decorative loops.
+ */
+export declare const whenMotionAllowed: (setup: () => Cleanup | void) => Cleanup;

package/dist/core/cleanup.d.ts

@@ -0,0 +1,10 @@
+import { Cleanup } from './types';
+export declare const noop: Cleanup;
+export type Disposer = {
+    /** Registers a cleanup; runs it at once if already disposed. Returns a function that runs it early. */
+    readonly add: (cleanup: Cleanup) => Cleanup;
+    /** Runs every cleanup, newest first. Safe to call more than once. */
+    readonly dispose: () => void;
+    readonly disposed: () => boolean;
+};
+export declare const createDisposer: () => Disposer;

package/dist/core/config.d.ts

@@ -0,0 +1,7 @@
+import { DistanceName, MotionConfig } from './types';
+export declare const defaultMotionConfig: MotionConfig;
+export declare const resolveConfig: (overrides?: Partial<MotionConfig>) => MotionConfig;
+/** Travel distances, in rem, on the spacing scale. The CSS layer reads the same steps as `--motion-distance-*`. */
+export declare const motionDistance: Readonly<Record<DistanceName, string>>;
+/** A distance in pixels, for engines that animate numbers. Follows the user's root font size. */
+export declare const distancePx: (name: DistanceName) => number;

package/dist/core/context.d.ts

@@ -0,0 +1,40 @@
+import { Cleanup, MotionConfig, MotionTarget } from './types';
+export type MotionRoot = Element | Document;
+/** What an effect sees each time it runs. */
+export type MotionScope = {
+    readonly root: MotionRoot;
+    readonly config: MotionConfig;
+    /** True when motion should be skipped: the user asked for less and the config respects it. */
+    readonly reduced: boolean;
+    readonly select: (target: MotionTarget) => Element[];
+};
+/**
+ * Sets an animation up and returns how to undo it. It runs again, after its
+ * cleanup, whenever the motion preference changes, so carry anything that must
+ * survive a re-run (progress, "already played") outside the function.
+ */
+export type MotionEffect = (scope: MotionScope) => Cleanup | void;
+export type MotionContext = {
+    readonly root: MotionRoot | null;
+    readonly config: MotionConfig;
+    readonly reduced: () => boolean;
+    readonly select: (target: MotionTarget) => Element[];
+    readonly effect: (setup: MotionEffect) => Cleanup;
+    /** Ties any other teardown to this context. */
+    readonly add: (cleanup: Cleanup) => Cleanup;
+    readonly destroy: () => void;
+    readonly destroyed: () => boolean;
+};
+export type MotionOptions = {
+    /** Scopes selectors and GSAP contexts. A selector is looked up in the document. */
+    readonly root?: MotionRoot | string | null;
+    readonly config?: Partial<MotionConfig>;
+};
+/**
+ * A scope that owns animations: every effect and cleanup registered here ends
+ * with `destroy()`. On the server, and when its root is missing, effects never
+ * run, so nothing is hidden that could not be revealed.
+ */
+export declare const createMotion: (options?: MotionOptions) => MotionContext;
+/** Runs an effect in the given context, or in one of its own that the returned cleanup destroys. */
+export declare const runInContext: (context: MotionContext | undefined, setup: MotionEffect, config?: Partial<MotionConfig>) => Cleanup;

package/dist/core/entrance.d.ts

@@ -0,0 +1,22 @@
+import { DistanceName, EntranceName } from './types';
+/** Where an entrance starts, as engine-neutral numbers. `x`/`y` are in units of the chosen travel distance. */
+export type EntranceFrom = {
+    readonly opacity: number;
+    readonly x: number;
+    readonly y: number;
+    readonly scale: number;
+    /** Starts clipped away from the bottom edge, revealed upward. */
+    readonly clip: boolean;
+};
+export declare const ENTRANCES: Readonly<Record<EntranceName, EntranceFrom>>;
+export declare const CLIP_HIDDEN = "inset(0% 0% 100% 0%)";
+export declare const CLIP_SHOWN = "inset(0% 0% 0% 0%)";
+export type ResolvedEntrance = {
+    readonly opacity: number;
+    readonly x: number;
+    readonly y: number;
+    readonly scale: number;
+    readonly clipPath: string | null;
+};
+/** An entrance's starting state in pixels, ready for any engine. */
+export declare const resolveEntrance: (name: EntranceName, distance?: DistanceName) => ResolvedEntrance;

package/dist/core/index.d.ts

@@ -0,0 +1,7 @@
+export { createDisposer, noop, type Disposer } from './cleanup';
+export { defaultMotionConfig, distancePx, motionDistance, resolveConfig } from './config';
+export { createMotion, runInContext, type MotionContext, type MotionEffect, type MotionOptions, type MotionRoot, type MotionScope, } from './context';
+export { CLIP_HIDDEN, CLIP_SHOWN, ENTRANCES, resolveEntrance, type EntranceFrom, type ResolvedEntrance } from './entrance';
+export { getMotionPreference, prefersReducedMotion, watchMotionPreference } from './preferences';
+export { isElement, resolveTargets } from './targets';
+export { DISTANCE_NAMES, ENTRANCE_NAMES, type Cleanup, type DistanceName, type EntranceName, type MotionConfig, type MotionOutcome, type MotionPreference, type MotionTarget, } from './types';

package/dist/core/preferences.d.ts

@@ -0,0 +1,6 @@
+import { Cleanup, MotionPreference } from './types';
+/** The user's motion preference. `no-preference` on the server and where it cannot be read. */
+export declare const getMotionPreference: () => MotionPreference;
+export declare const prefersReducedMotion: () => boolean;
+/** Calls back whenever the preference changes while the page is open. */
+export declare const watchMotionPreference: (listener: (preference: MotionPreference) => void) => Cleanup;

package/dist/core/targets.d.ts

@@ -0,0 +1,4 @@
+import { MotionTarget } from './types';
+export declare const isElement: (value: unknown) => value is Element;
+/** Every element a target names, in order and without duplicates. Missing targets and bad selectors give `[]`, never a throw. */
+export declare const resolveTargets: (target: MotionTarget, scope?: ParentNode | null) => Element[];

package/dist/core/types.d.ts

@@ -0,0 +1,20 @@
+/** What an animation acts on. Selectors resolve inside the owning context's root. */
+export type MotionTarget = Element | string | Iterable<Element> | ArrayLike<Element> | null | undefined;
+export type Cleanup = () => void;
+export type MotionPreference = 'reduce' | 'no-preference';
+export type MotionConfig = {
+    /** Seconds, as GSAP counts them. */
+    readonly duration: number;
+    /** A GSAP ease name; the CSS layer uses the matching token curve. */
+    readonly ease: string;
+    /** Seconds between items in a collection. */
+    readonly stagger: number;
+    readonly respectReducedMotion: boolean;
+};
+export declare const ENTRANCE_NAMES: readonly ["fade", "fade-up", "fade-down", "slide-left", "slide-right", "scale", "clip"];
+/** One vocabulary for every engine: CSS reveals, WAAPI and GSAP all accept these names. */
+export type EntranceName = (typeof ENTRANCE_NAMES)[number];
+export declare const DISTANCE_NAMES: readonly ["sm", "md", "lg"];
+export type DistanceName = (typeof DISTANCE_NAMES)[number];
+/** How an animation ended. Cancellation is an outcome, never a rejection. */
+export type MotionOutcome = 'finished' | 'cancelled';

package/dist/css/dom.d.ts

@@ -0,0 +1,9 @@
+export declare const styleOf: (element: Element) => CSSStyleDeclaration | null;
+/** The CSS curve for a GSAP ease name from the token set, so both engines move alike. */
+export declare const cssEase: (gsapEase: string) => string;
+/** Resolves once, with an outcome; later calls are ignored. */
+export declare const createOutcome: <T>() => {
+    readonly promise: Promise<T>;
+    readonly settle: (value: T) => void;
+    readonly settled: () => boolean;
+};

package/dist/css/fade-in.d.ts

@@ -0,0 +1,25 @@
+import { MotionContext } from '../core/context';
+import { DistanceName, EntranceName, MotionOutcome, MotionTarget } from '../core/types';
+export type FadeInOptions = {
+    readonly context?: MotionContext;
+    readonly effect?: EntranceName;
+    readonly distance?: DistanceName;
+    /** Seconds. Defaults to the context's duration. */
+    readonly duration?: number;
+    readonly delay?: number;
+    readonly stagger?: number;
+    /** A CSS easing; defaults to the token curve matching the context's GSAP ease. */
+    readonly easing?: string;
+};
+export type MotionAnimation = {
+    /** Settles once: `finished`, or `cancelled` when stopped or its context is destroyed. Never rejects. */
+    readonly finished: Promise<MotionOutcome>;
+    readonly cancel: () => void;
+};
+/**
+ * A one-shot entrance on the Web Animations API: no GSAP, nothing left behind.
+ * `fill: backwards` hides elements only while they wait their turn; once done
+ * the animation drops away and the element's own styles apply. With reduced
+ * motion it settles at once and the content simply stays visible.
+ */
+export declare const fadeIn: (targets: MotionTarget, options?: FadeInOptions) => MotionAnimation;

package/dist/css/index.d.ts

@@ -0,0 +1,3 @@
+export { cssEase } from './dom';
+export { fadeIn, type FadeInOptions, type MotionAnimation } from './fade-in';
+export { REVEAL_ATTR, STATE_ATTR, revealOnScroll, type RevealOptions } from './reveal';

package/dist/css/reveal.d.ts

@@ -0,0 +1,22 @@
+import { MotionContext } from '../core/context';
+import { Cleanup, EntranceName, MotionTarget } from '../core/types';
+export declare const REVEAL_ATTR = "data-motion-reveal";
+export declare const STATE_ATTR = "data-motion-state";
+export type RevealOptions = {
+    readonly context?: MotionContext;
+    /** Used when an element has no `data-motion-reveal` of its own. */
+    readonly effect?: EntranceName;
+    /** Reveal once, or hide again on leaving the viewport. */
+    readonly once?: boolean;
+    readonly threshold?: number;
+    readonly rootMargin?: string;
+    /** Seconds between elements that enter together. */
+    readonly stagger?: number;
+};
+/**
+ * Reveals elements as they scroll into view, with the stylesheet's
+ * `[data-motion-reveal]` presets doing the motion. Content is hidden only once
+ * this has run, and cleanup leaves it visible, so a failed or skipped setup
+ * never strands it invisible. Needs no GSAP.
+ */
+export declare const revealOnScroll: (targets: MotionTarget, options?: RevealOptions) => Cleanup;

package/dist/dom-CK6FnKcV.js

@@ -0,0 +1,74 @@
+import { a as e, n as t, o as n, r, s as i, t as a } from "./targets-x7JiHhWI.js";
+import { duration as o, ease as s, space as c } from "@lovince/tokens";
+//#region src/core/config.ts
+var l = {
+	duration: o.travel,
+	ease: s.out.gsap,
+	stagger: .08,
+	respectReducedMotion: !0
+}, u = (e = {}) => ({
+	...l,
+	...e
+}), d = {
+	sm: c[3],
+	md: c[6],
+	lg: c[12]
+}, f = () => {
+	if (typeof document > "u") return 16;
+	let e = Number.parseFloat(getComputedStyle(document.documentElement).fontSize);
+	return Number.isFinite(e) && e > 0 ? e : 16;
+}, p = (e) => Number.parseFloat(d[e]) * f(), m = (e) => typeof document > "u" ? null : e == null ? document : typeof e == "string" ? t(e)[0] ?? null : a(e) || e instanceof Document ? e : null, h = (a = {}) => {
+	let o = u(a.config), s = m(a.root), c = n(), l = /* @__PURE__ */ new Set(), d = r(), f = () => o.respectReducedMotion && d === "reduce", p = (e) => s === null ? [] : t(e, s), h = () => s === null ? null : {
+		root: s,
+		config: o,
+		reduced: f(),
+		select: p
+	}, g = (e) => {
+		let t = h();
+		e.cleanup = (t === null ? void 0 : e.setup(t)) ?? i;
+	};
+	return c.add(e((e) => {
+		if (e !== d) {
+			d = e;
+			for (let e of l) e.cleanup(), g(e);
+		}
+	})), c.add(() => {
+		for (let e of [...l].reverse()) e.cleanup();
+		l.clear();
+	}), {
+		root: s,
+		config: o,
+		reduced: f,
+		select: p,
+		effect: (e) => {
+			if (c.disposed()) return i;
+			let t = {
+				setup: e,
+				cleanup: i
+			};
+			return l.add(t), g(t), () => {
+				l.delete(t) && t.cleanup();
+			};
+		},
+		add: c.add,
+		destroy: c.dispose,
+		destroyed: c.disposed
+	};
+}, g = (e, t, n) => {
+	if (e !== void 0) return e.effect(t);
+	let r = h({ config: n });
+	return r.effect(t), r.destroy;
+}, _ = (e) => typeof HTMLElement < "u" && (e instanceof HTMLElement || e instanceof SVGElement) ? e.style : null, v = (e) => Object.values(s).find((t) => t.gsap === e)?.css ?? s.out.css, y = () => {
+	let e = () => void 0, t = !1;
+	return {
+		promise: new Promise((t) => {
+			e = t;
+		}),
+		settle: (n) => {
+			t || (t = !0, e(n));
+		},
+		settled: () => t
+	};
+};
+//#endregion
+export { g as a, d as c, h as i, u as l, v as n, l as o, _ as r, p as s, y as t };

package/dist/focus-management-DTJ2C7Pn.js

@@ -0,0 +1,8 @@
+import { n as e } from "./targets-x7JiHhWI.js";
+//#region src/accessibility/focus-management.ts
+var t = "a[href], button, input, select, textarea, summary, [tabindex], [contenteditable=\"true\"]", n = (n, r = {}) => {
+	let i = e(n)[0];
+	return i === void 0 || !(i instanceof HTMLElement || i instanceof SVGElement) ? !1 : (i.matches(t) || (i.setAttribute("tabindex", "-1"), i.addEventListener("blur", () => i.removeAttribute("tabindex"), { once: !0 })), i.focus({ preventScroll: r.preventScroll ?? !0 }), i.ownerDocument.activeElement === i);
+};
+//#endregion
+export { n as t };

package/dist/gsap/engine.d.ts

@@ -0,0 +1,17 @@
+import { ScrollTrigger } from 'gsap/ScrollTrigger';
+import { MotionScope } from '../core/context';
+import { DistanceName, EntranceName } from '../core/types';
+/** ScrollTrigger, registered on first use rather than at import, so importing this layer has no side effects. */
+export declare const scrollTrigger: () => typeof ScrollTrigger;
+/** The element GSAP should scope selectors and `gsap.context` to; the document needs none. */
+export declare const scopeElement: (scope: MotionScope) => Element | undefined;
+/** Where an entrance starts, as GSAP vars. `autoAlpha` also hides it from assistive tech until it shows. */
+export declare const entranceFrom: (effect: EntranceName, distance?: DistanceName) => gsap.TweenVars;
+/** Where every entrance ends. */
+export declare const entranceTo: (effect: EntranceName) => gsap.TweenVars;
+/** Adds an entrance to a timeline. `fromTo` keeps clip reveals exact; `gsap.context` reverts either way. */
+export declare const addEntrance: (timeline: gsap.core.Timeline, targets: gsap.TweenTarget, effect: EntranceName, options?: {
+    readonly distance?: DistanceName;
+    readonly vars?: gsap.TweenVars;
+    readonly position?: gsap.Position;
+}) => gsap.core.Timeline;

package/dist/gsap/horizontal-scroll.d.ts

@@ -0,0 +1,14 @@
+import { MotionContext } from '../core/context';
+import { Cleanup, MotionTarget } from '../core/types';
+export type HorizontalScrollOptions = {
+    readonly context?: MotionContext;
+    /** Below this width the section stays a normal, natively scrollable layout. */
+    readonly minWidth?: string;
+};
+/**
+ * Pins a section and moves its track sideways as the page scrolls. Narrow
+ * screens and reduced motion get the static layout. Keyboard focus moving to
+ * an off-screen item scrolls the page to the point where that item is in view,
+ * so tabbing through the gallery always shows what is focused.
+ */
+export declare const createHorizontalScroll: (section: MotionTarget, track: MotionTarget, options?: HorizontalScrollOptions) => Cleanup;

package/dist/gsap/index.d.ts

@@ -0,0 +1,8 @@
+export { addEntrance, entranceFrom, entranceTo, scrollTrigger } from './engine';
+export { createHorizontalScroll, type HorizontalScrollOptions } from './horizontal-scroll';
+export { createParallax, type ParallaxOptions } from './parallax';
+export { createScrollReveal, type ScrollRevealOptions } from './scroll-reveal';
+export { splitText, type SplitBy, type SplitOptions, type SplitText } from './split-text';
+export { createStagger, type StaggerOptions } from './stagger';
+export { createTimeline, type ManagedTimeline, type TimelineBuild, type TimelineOptions } from './timeline';
+export { gsapScrollDriver } from '../scroll/gsap-integration';

package/dist/gsap/parallax.d.ts

@@ -0,0 +1,14 @@
+import { MotionContext } from '../core/context';
+import { Cleanup, MotionTarget } from '../core/types';
+export type ParallaxOptions = {
+    readonly context?: MotionContext;
+    /** Travel across the viewport as a fraction of the element's size; negative moves against the scroll. Keep it small. */
+    readonly speed?: number;
+    readonly axis?: 'x' | 'y';
+};
+/**
+ * Scroll-linked drift, linear and scrubbed to scroll progress. Each element
+ * moves relative to its own scroll range, so nothing is measured on scroll.
+ * Skipped entirely under reduced motion: parallax has no gentle form.
+ */
+export declare const createParallax: (targets: MotionTarget, options?: ParallaxOptions) => Cleanup;