use-scroll-animate 1.4.0 → 2.0.0

package/CHANGELOG.md

@@ -7,6 +7,74 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-10-07
+
+2.0 collects the 1.6–1.9 roadmap (native scroll timeline, Svelte/Solid/Web Component entries, exit animations and `parallax()`, docs and demo) and removes what 1.9 deprecated. See **MIGRATION from 1.x** below.
+
+### ⚠ Breaking changes
+- **`engine` defaults to `'auto'`**: presets run on the native scroll-driven timeline (`animation-timeline: view()`) where supported — scroll-linked instead of time-based. `'auto'` still picks the JS engine when an element sets `duration`, `delay`, `offset` or `stagger` itself. Set `defaultEngine: 'js'` for 1.x behaviour.
+- **Removed** the `createReactHooks` / `createVueComposables` re-exports from the main entry: import them from `use-scroll-animate/react` / `use-scroll-animate/vue`.
+- **ESM-first package** (`"type": "module"`): `import` → `dist/*.js` + `dist/*.d.ts`, `require` → `dist/*.cjs` + `dist/*.d.cts` for every entry; `main` is `dist/index.cjs`.
+- **Removed legacy build artefacts**: the `module` field, `dist/index.esm.js`, `dist/index.mjs`, `dist/*.d.mts`, the per-file `dist/types/*` declarations, and `use-scroll-animate/dist/*` deep imports (only the documented entry points resolve). `dist/index.umd.js` and `dist/element.umd.js` keep their CDN URLs.
+- **ES2020 output** (was ES2018): optional chaining / nullish coalescing are no longer down-levelled. Every browser that has `Animation.commitStyles()` (Chrome 84, Firefox 75, Safari 13.1), which the library already relied on, supports ES2020. Together with the removed re-exports: UMD 7.55 → 6.99 kB gz, core-only import 5.63 → 5.40 kB gz.
+- `engines.node >= 18` declared (only relevant for SSR imports).
+
+### Added
+- **Native scroll-driven engine** (1.6): new `engine: 'auto' | 'js' | 'css'` option (`defaultEngine` config, `data-sa-engine` attribute). With `'auto'`/`'css'`, browsers that support `animation-timeline: view()` run the preset on a native `ViewTimeline` (scroll-linked, off the main thread); others fall back to the JS engine (default `'auto'`, see Breaking changes). New `viewRange` option (`data-sa-view-range`) and `supportsScrollTimeline()` helper.
+- **Svelte actions** (1.7): `use-scroll-animate/svelte` exports `scrollAnimate` and `scrollStagger` (`use:` actions with `update`/`destroy`; no `svelte` import).
+- **Solid primitives** (1.7): `use-scroll-animate/solid` exports the `scrollAnimate` / `scrollStagger` directives (typed via `JSX.Directives`) and `useScrollAnimate()` ref primitive. `solid-js` is an optional peer dependency.
+- **`<scroll-animate>` Web Component** (1.7): `use-scroll-animate/element` exports `defineScrollAnimate(tagName?, instance?)`; attributes mirror `data-sa-*`, and it dispatches `sa:enter`/`sa:leave`/`sa:start`/`sa:complete`/`sa:progress` events. `dist/element.umd.js` registers it on load for CDN use.
+- **Subpath exports** (1.7): `./react`, `./vue`, `./svelte`, `./solid`, `./element` (ESM + CJS, each with types). Entries share code through `dist/chunks/`, so importing several never duplicates the core. Optional peer dependencies: `solid-js`, `svelte`.
+- **Exit animations** (1.8): `exit: true | preset | presets | { from, to }` (`data-sa-exit`, `exit` attribute on `<scroll-animate>`) plays the entrance (or the given animation) in reverse when the element leaves the viewport and replays the entrance on re-entry; implies `repeat` unless set. Scroll-linked over the `exit` range with the native engine; class swap in class-name mode; skipped under reduced motion.
+- **`parallax(target, { speed, axis, progressVar, root, respectReducedMotion })`** (1.8): standalone parallax helper on the scroll-progress scale used by `progressVar`. Writes the progress to `--sa-parallax` and the offset to the individual `translate` property (composes with `transform`/entrance animations); no offset under reduced motion; listens only while targets are visible; returns a stop function. < 1 kB gzipped when tree-shaken.
+- **Size budgets** (1.6): `size-budget.json` defines a gzip budget per entry (UMD bundle and tree-shaken imports); `npm run size:check` fails when one is exceeded and runs in CI.
+- **Docs** (1.9): `docs/API.md` (full API reference), `docs/migration-from-aos.md`, `docs/migration-from-gsap-scrolltrigger.md`, `docs/deprecations.md` (now "Upgrading to 2.0"), and `demo/index.html` — a no-build preset playground (every preset clickable, scroll-triggered cards, parallax) that loads the UMD bundle.
+
+### Changed
+- The default instance export is annotated `/* @__PURE__ */`, so bundlers drop the core when only standalone helpers such as `parallax` are imported (1.8).
+- Size budgets for the UMD bundle and "import everything" raised from 7.5 to 8 kB gzip for exit + parallax (1.8).
+- Build (1.7): ESM/CJS entries are small files that import shared chunks from `dist/chunks/`; the UMD bundles stay single files.
+- Build uses Rollup's ESM config (`rollup.config.mjs`); `@rollup/plugin-commonjs` dropped (no CommonJS inputs). `npm run build` cleans `dist/` first.
+
+### Fixed
+- Class-name mode: `destroy()` now clears pending completion timers, so `onComplete` no longer fires after the instance was destroyed. Other instances' timers are unaffected.
+
+### Repository
+- Dependabot (npm + GitHub Actions, weekly, grouped), issue templates (bug report, feature request) and a pull-request template.
+
+### MIGRATION from 1.x
+
+1. **React / Vue imports**
+   ```diff
+   - import { createReactHooks } from 'use-scroll-animate';
+   + import { createReactHooks } from 'use-scroll-animate/react';
+   - import { createVueComposables } from 'use-scroll-animate';
+   + import { createVueComposables } from 'use-scroll-animate/vue';
+   ```
+   (1.9 already logged a dev-only warning for these.)
+2. **Engine**: if you rely on time-based entrances (`duration`/`delay` set globally via `defaultDuration`/`defaultDelay`, `onComplete` timing, `threshold`-based triggering), keep 1.x behaviour with
+   ```js
+   ScrollAnimate.configure({ defaultEngine: 'js' });      // default instance
+   createScrollAnimate({ defaultEngine: 'js' });          // own instances
+   ```
+   or per element `engine: 'js'` / `data-sa-engine="js"`. Elements that set `duration`, `delay`, `offset` or `stagger` themselves already stay on JS.
+3. **Deep imports**: replace `use-scroll-animate/dist/index.js`, `dist/index.mjs`, `dist/index.esm.js` or `dist/types/...` with `use-scroll-animate` (or a subpath entry). Type-only imports come from the package name: `import type { AnimateOptions } from 'use-scroll-animate'`.
+4. **CommonJS** consumers: `require('use-scroll-animate')` keeps working (now `dist/index.cjs`). If you referenced `dist/index.js` as CommonJS by path, it is ESM now.
+5. **`<script>` / CDN**: no change — `https://unpkg.com/use-scroll-animate/dist/index.umd.js` (global `ScrollAnimate`) and `dist/element.umd.js`.
+6. **Old browsers**: if you must support browsers without ES2020 (pre-2020 Safari/Chrome), transpile `use-scroll-animate` in your bundler, or stay on 1.x.
+
+## [1.5.0] - 2026-10-07
+
+### Added
+- `watch(root?)` instance method: automatically observes `[data-sa]` elements added to the DOM later; returns a stop function, and `destroy()` stops all watchers.
+- `progressVar` option and `data-sa-progress-var` attribute: expose scroll progress (0–1) as a CSS custom property.
+
+### Fixed
+- Stopping `staggerChildren` or cancelling a triggered `sequence()` before the content entered the viewport left it at `opacity: 0`; it is now restored (also affects React/Vue `useScrollStagger` unmounting off-screen).
+
+### Tests / CI
+- 47 new tests covering reduced motion, SSR, unmount cleanup and lifecycle; CI job timeout and `npm pack --dry-run`.
+
 ## [1.4.0] - 2026-10-06
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 # use-scroll-animate 🚀
 
-**A lightweight (~5KB gzipped), dependency-free scroll animation library for the modern web.**
+**A lightweight (~5.7KB gzipped), dependency-free scroll animation library for the modern web.**
 
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/HarrisonCN/use-scroll-animate?style=flat-square)](https://github.com/HarrisonCN/use-scroll-animate/releases)
 [![GitHub repo size](https://img.shields.io/github/repo-size/HarrisonCN/use-scroll-animate?style=flat-square)](https://github.com/HarrisonCN/use-scroll-animate)
@@ -19,17 +19,57 @@ In 2025, performance is everything. Traditional scroll animation libraries often
 `use-scroll-animate` is built differently:
 - ⚡ **Zero Dependencies**: Pure Vanilla JS/TypeScript.
 - 🚀 **High Performance**: Powered by `IntersectionObserver` and the native `Web Animations API`. No scroll event listeners by default (the opt-in scroll-progress mode uses a single passive, rAF-throttled listener, only while tracked elements are on screen).
-- 🪶 **Ultra Lightweight**: ~4.8KB gzipped for the core (tree-shaken, minified ESM); everything incl. `sequence`, `staggerChildren` and the React/Vue helpers is ~6.1KB (UMD ~6.2KB).
-- 🧩 **Framework Agnostic**: Works seamlessly with Vanilla JS, React, Vue, Svelte, and more. First-class React Hooks and Vue Composables included.
+- 🪶 **Ultra Lightweight**: ~5.4–5.7KB gzipped for the core (tree-shaken, minified ESM); everything from the main entry is ~6.8KB (UMD ~7.0KB); `parallax()` alone < 1KB. Every entry has a gzip budget enforced in CI (`size-budget.json`, `npm run size:check`).
+- 🧩 **Framework Agnostic**: Vanilla JS, React hooks, Vue composables, Svelte actions, Solid directives and a `<scroll-animate>` Web Component, each as its own entry point (`use-scroll-animate/react`, `/vue`, `/svelte`, `/solid`, `/element`).
 - ♿ **Accessible**: Respects `prefers-reduced-motion` out of the box (content is shown immediately, no entrance or parallax motion).
 - 🖥️ **SSR-safe**: Importing (and even calling) the API on the server is a no-op.
 
+## v2.0.0 🎉
+
+- **Native scroll-driven animations by default** (`engine: 'auto'`) where the browser supports `animation-timeline: view()`, JS everywhere else.
+- **ESM-first package** with types for every entry: `use-scroll-animate`, `/react`, `/vue`, `/svelte`, `/solid`, `/element`.
+- **Breaking:** React/Vue factories moved to `/react` and `/vue`; `dist/index.mjs`, `dist/index.esm.js`, `dist/types/*` and `dist/*` deep imports are gone; ES2020 output. The CDN URLs `dist/index.umd.js` and `dist/element.umd.js` are unchanged. Upgrade steps: [MIGRATION](./CHANGELOG.md#migration-from-1x).
+
+## Documentation
+
+- 📖 [API reference](./docs/API.md) — every export, option, attribute and config key
+- 🎛️ [Demo / preset playground](./demo/index.html) — every preset clickable, no build step (open `demo/index.html` from a clone)
+- 🔁 Migration guides: [from AOS](./docs/migration-from-aos.md) · [from GSAP ScrollTrigger](./docs/migration-from-gsap-scrolltrigger.md)
+- ⚠️ [Upgrading to 2.0](./docs/deprecations.md) — what 2.0 removed and what replaces it (also the MIGRATION section of the [CHANGELOG](./CHANGELOG.md))
+
 ## Installation
 
 ```bash
 npm install use-scroll-animate
 ```
 
+## Native scroll-driven engine (`engine`) 🏎️
+
+In browsers that support CSS scroll-driven animations (`CSS.supports('animation-timeline: view()')`), presets can run on the browser's native **view timeline** instead of the JavaScript engine. The animation is then linked to the scroll position (it plays as the element scrolls in, off the main thread) rather than started by IntersectionObserver and played over a fixed `duration`.
+
+```js
+ScrollAnimate.observe('.card', { animation: 'fade-in-up' });            // native where supported (default 'auto')
+ScrollAnimate.observe('.card', { animation: 'fade-in-up', engine: 'js' }); // always time-based
+const sa = createScrollAnimate({ defaultEngine: 'js' });                 // 1.x behaviour for an instance
+```
+
+```html
+<div data-sa data-sa-animation="zoom-in" data-sa-engine="auto" data-sa-view-range="entry 0%, cover 40%">…</div>
+```
+
+| `engine` | Behaviour |
+|---|---|
+| `'auto'` | **Default since 2.0.** Native view timeline when supported, otherwise JS. Also JS when the element sets `duration`, `delay`, `offset` or `stagger` itself (those only mean something for a time-based animation). |
+| `'css'` | Native view timeline whenever supported (ignores time-based options), otherwise JS. |
+| `'js'` | IntersectionObserver + time-based Web Animation (the 1.x default). `createScrollAnimate({ defaultEngine: 'js' })` restores 1.x behaviour everywhere. |
+
+Notes:
+- With the native engine, `duration`, `delay`, `threshold`, `offset` and `stagger` don't apply; the animation spans `viewRange` (default `['entry 0%', 'entry 100%']`, i.e. from the moment the element starts entering until it is fully in view). `easing` still applies.
+- `once` (default) freezes the end state when the animation completes, so scrolling back up does not reverse it; with `repeat: true` it keeps following the scroll in both directions.
+- Callbacks (`onEnter`, `onLeave`, `onStart`, `onComplete`), `onProgress`, `progressVar` and `parallax` keep working.
+- Class-name mode (`useClassNames`), `prefers-reduced-motion`, `animate()`, `sequence()` and `staggerChildren()` always use the JS engine.
+- `supportsScrollTimeline()` is exported if you want to branch on support yourself.
+
 ## v1.4.0 New Features ✨
 
 ### True scroll progress (`progressMode: 'scroll'`)
@@ -78,7 +118,7 @@ tl.cancel();       // stop and leave everything visible
 Finished `once` elements are dropped from the registry right after they animate (unless they still need parallax/`onProgress`), so long pages and SPAs don't keep thousands of records alive. They're remembered in a `WeakSet`, so `init()`/`observe()` never replay them. Set `createScrollAnimate({ autoUnregister: false })` to keep them listed in `getObservedElements()` as before.
 
 ### Proper `exports` map
-Node ESM (`import`) resolves to `dist/index.mjs`, CommonJS (`require`) to `dist/index.js`, each with matching bundled types. The legacy `main`/`module`/`unpkg` fields and `dist/*` deep imports keep working.
+ESM-first since 2.0: `import` resolves to `dist/*.js` + `dist/*.d.ts`, `require` to `dist/*.cjs` + `dist/*.d.cts`, for the main entry and every subpath. See [2.0](#v200-) below.
 
 ## v1.3.0: Custom Easing 🎨
 
@@ -144,12 +184,73 @@ We've added high-quality physics-based easing presets:
 | `onStart` / `onComplete` / `onEnter` / `onLeave` | `(el) => void` | – | Lifecycle callbacks |
 | `onProgress` | `(el, progress) => void` | – | Progress (0–1) as the element scrolls — visible ratio, or true scroll progress with `progressMode: 'scroll'` |
 | `progressMode` | `'ratio'` \| `'scroll'` | `'ratio'` | How `onProgress`/parallax progress is measured (`'scroll'`: 0 = top enters at the bottom, 1 = bottom leaves at the top) |
+| `engine` | `'auto'` \| `'js'` \| `'css'` | `'auto'` | Run presets on the browser's native scroll-driven timeline when supported (`'auto'`/`'css'`), falling back to JS. See [Native scroll-driven engine](#native-scroll-driven-engine-engine-) |
+| `exit` | `boolean` \| preset \| `{ from, to }` | `false` | Animate out (reverse) when leaving the viewport, back in on re-entry. Implies `repeat`. See [Exit animations](#exit-animations-exit) |
+| `viewRange` | `[string, string]` | `['entry 0%', 'entry 100%']` | Native engine only: view-timeline range of the entrance |
+| `progressVar` | `string` | – | Write progress (0–1, same value as `onProgress`) to this CSS custom property, e.g. `'--sa-progress'`, for scroll-driven effects in plain CSS |
 
-Every option is also available as a data attribute: `data-sa-animation`, `data-sa-duration`, `data-sa-delay`, `data-sa-easing`, `data-sa-threshold`, `data-sa-root-margin`, `data-sa-once`, `data-sa-repeat`, `data-sa-offset`, `data-sa-stagger`, `data-sa-progress`, `data-sa-parallax-x|y|rotate|scale|speed`.
+Every option is also available as a data attribute: `data-sa-animation`, `data-sa-duration`, `data-sa-delay`, `data-sa-easing`, `data-sa-threshold`, `data-sa-root-margin`, `data-sa-once`, `data-sa-repeat`, `data-sa-offset`, `data-sa-stagger`, `data-sa-progress`, `data-sa-progress-var` (bare attribute = `--sa-progress`), `data-sa-engine`, `data-sa-exit` (bare = `true`, or a preset), `data-sa-view-range` (`"entry 0%, cover 40%"`), `data-sa-parallax-x|y|rotate|scale|speed`.
 
 **Presets:** `fade-in`, `fade-in-up|down|left|right`, `zoom-in`, `zoom-out`, `scale-up`, `flip-x`, `flip-y`, `flip-up`, `flip-down`, `slide-up|down|left|right`, `bounce`, `rotate-in`, `rotate-left`, `rotate-right`, `blur-in`, `blur-in-up`, `skew-in`, `scale-x`, `scale-y`, `clip-up|down|left|right`, `clip-circle`, `shimmer`, `pulse`, `swing`. Combine them with an array, e.g. `['fade-in', 'clip-up']`.
 
-**Global config** (`createScrollAnimate(config)` / `configure()`): `defaultAnimation`, `defaultDuration`, `defaultDelay`, `defaultEasing`, `defaultThreshold`, `defaultRootMargin`, `defaultRepeat`, `defaultOnce`, `defaultOffset`, `hiddenClass`, `visibleClass`, `useClassNames`, `disabled`, `root`, `autoUnregister` (default `true`).
+**Global config** (`createScrollAnimate(config)` / `configure()`): `defaultAnimation`, `defaultDuration`, `defaultDelay`, `defaultEasing`, `defaultThreshold`, `defaultRootMargin`, `defaultRepeat`, `defaultOnce`, `defaultOffset`, `hiddenClass`, `visibleClass`, `useClassNames`, `disabled`, `root`, `autoUnregister` (default `true`), `defaultEngine` (default `'auto'`).
+
+### Progress as a CSS variable (`progressVar`)
+
+Drive any CSS property from scroll position without writing JavaScript callbacks. The element's progress is written to a custom property on the element itself:
+
+```html
+<div data-sa data-sa-progress="scroll" data-sa-progress-var class="hero">…</div>
+
+<style>
+  @media (prefers-reduced-motion: no-preference) {
+    .hero { transform: translateY(calc((1 - var(--sa-progress, 0)) * 60px)); opacity: calc(0.4 + var(--sa-progress, 0)); }
+  }
+</style>
+```
+
+```js
+ScrollAnimate.observe('.bar', { progressVar: '--fill', progressMode: 'scroll' });
+// .bar::after { transform: scaleX(var(--fill, 0)); }
+```
+
+It uses the same rAF-throttled / IntersectionObserver pipeline as `onProgress`, keeps updating after the entrance animation, and is still written under reduced motion (it is data) — guard motion in your CSS with `prefers-reduced-motion` as above.
+
+### Exit animations (`exit`)
+
+Animate elements out when they leave the viewport, and back in when they return:
+
+```js
+ScrollAnimate.observe('.card', { animation: 'fade-in-up', exit: true });          // reverse of the entrance
+ScrollAnimate.observe('.toast', { animation: 'zoom-in', exit: 'fade-in-down' });  // leave with another preset (played in reverse)
+```
+
+```html
+<div data-sa data-sa-animation="fade-in-left" data-sa-exit>…</div>
+<div data-sa data-sa-exit="zoom-out">…</div>
+```
+
+`exit` accepts `true`, a preset name, an array of presets or `{ from, to }`; the exit plays that animation **in reverse** over `duration` (no delay) and the element stays in its hidden state until it re-enters. It implies `repeat: true` (set `repeat` explicitly to override). With the native engine the exit is scroll-linked too (the view timeline's `exit` range). In class-name mode the hidden/visible classes are swapped back. Under `prefers-reduced-motion` nothing moves and the element stays visible.
+
+### Parallax helper (`parallax()`)
+
+```js
+import { parallax } from 'use-scroll-animate';
+
+const stop = parallax('.hero-bg', { speed: 0.3 });     // lags behind the scroll (background)
+parallax('.badge', { speed: -0.15, axis: 'x' });        // drifts sideways, ahead of the scroll
+stop(); // remove listeners and the inline styles it set
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `speed` | `0.2` | Total shift while the element crosses the viewport, as a fraction of the viewport (`0.2` = 20vh / 20vw). Positive = slower than the page, negative = faster |
+| `axis` | `'y'` | `'y'` or `'x'` |
+| `progressVar` | `'--sa-parallax'` | CSS custom property receiving the scroll progress (0–1, same scale as `progressVar` with `progressMode: 'scroll'`) |
+| `root` | viewport | Scroll container |
+| `respectReducedMotion` | `true` | Under `prefers-reduced-motion: reduce` only the variable is written, no offset |
+
+It writes the offset to the individual CSS **`translate`** property, so it composes with entrance animations and any `transform` you set. One IntersectionObserver plus a passive, rAF-throttled scroll listener that is attached only while a target is on screen. Tree-shaken it adds under 1 kB gzipped. (The older `parallax: { x, y, rotate, scale }` option still works; it writes `transform`.)
 
 ## Instance API
 
@@ -157,6 +258,7 @@ Every option is also available as a data attribute: `data-sa-animation`, `data-s
 import ScrollAnimate, { createScrollAnimate } from 'use-scroll-animate';
 
 ScrollAnimate.init(root?);            // observe every [data-sa] element (safe to call again after DOM changes)
+const stop = ScrollAnimate.watch(root?); // init() + auto-observe [data-sa] elements added later; stop() to end
 ScrollAnimate.observe(target, opts);  // selector, Element, NodeList or Element[]
 ScrollAnimate.unobserve(target);      // stop observing (elements that never animated are made visible)
 ScrollAnimate.animate(target, opts);  // play an animation right now
@@ -170,6 +272,22 @@ const sa = createScrollAnimate({ root: document.querySelector('#scroller') }); /
 import { sequence, staggerChildren, getScrollProgress } from 'use-scroll-animate';
 ```
 
+### Watching the DOM (`watch()`)
+
+For SPAs, CMS content, infinite lists or anything rendered after page load, `watch()` replaces "call `init()` again after every DOM change":
+
+```js
+import ScrollAnimate from 'use-scroll-animate';
+
+const stop = ScrollAnimate.watch();              // or watch(document.querySelector('#app'))
+// [data-sa] elements inserted later — even deep inside a new subtree, or an existing
+// element that gains the data-sa attribute — are observed with their data-sa-* options.
+// Elements removed from the DOM are released; finished `once` elements are never replayed.
+stop();                                          // stop watching (destroy() also stops every watcher)
+```
+
+It uses a single `MutationObserver` per call and is a no-op on the server or without `MutationObserver`.
+
 Via a `<script>` tag (UMD build), the default instance lives at `ScrollAnimate.default`:
 
 ```html
@@ -177,11 +295,13 @@ Via a `<script>` tag (UMD build), the default instance lives at `ScrollAnimate.d
 <script>ScrollAnimate.default.init();</script>
 ```
 
-## React & Vue
+## Frameworks
+
+### React & Vue
 
 ```jsx
 import React from 'react';
-import { createReactHooks } from 'use-scroll-animate';
+import { createReactHooks } from 'use-scroll-animate/react';
 const { useScrollAnimate, useScrollStagger } = createReactHooks(React);
 
 function Card() {
@@ -192,7 +312,7 @@ function Card() {
 
 ```js
 import { ref, onMounted, onUnmounted } from 'vue';
-import { createVueComposables } from 'use-scroll-animate';
+import { createVueComposables } from 'use-scroll-animate/vue';
 const { useScrollAnimate, useScrollStagger } = createVueComposables({ ref, onMounted, onUnmounted });
 const { animateRef } = useScrollAnimate({ animation: 'fade-in-left' });
 const { staggerRef } = useScrollStagger({ stagger: 60, observeChildren: true }); // <ul ref="staggerRef">
@@ -206,7 +326,61 @@ function Feed({ items }) {
 }
 ```
 
-Hooks and composables share the core engine, so `once`, `offset`, custom easing functions, parallax and reduced-motion handling behave exactly like the vanilla API.
+> Since 2.0 `createReactHooks` / `createVueComposables` are only available from `use-scroll-animate/react` / `use-scroll-animate/vue`.
+
+### Svelte (`use-scroll-animate/svelte`)
+
+Actions, no `svelte` import needed (Svelte 3, 4 and 5):
+
+```svelte
+<script>
+  import { scrollAnimate, scrollStagger } from 'use-scroll-animate/svelte';
+  let items = [];
+</script>
+
+<h2 use:scrollAnimate={{ animation: 'fade-in-up', duration: 800 }}>Title</h2>
+<ul use:scrollStagger={{ stagger: 60, observeChildren: true }}>
+  {#each items as item}<li>{item}</li>{/each}
+</ul>
+```
+
+Updating the action's parameter swaps the callbacks immediately; other options are applied if the element has not animated yet (so visible content is never re-hidden). Pass `instance` to use your own `createScrollAnimate()` instance.
+
+### Solid (`use-scroll-animate/solid`)
+
+Directives and a `ref` primitive (`solid-js` is an optional peer dependency, needed only for this entry):
+
+```tsx
+import { scrollAnimate, scrollStagger, useScrollAnimate } from 'use-scroll-animate/solid';
+scrollAnimate; scrollStagger; // keep the directive imports (TypeScript)
+
+<div use:scrollAnimate={{ animation: 'zoom-in' }}>…</div>
+<ul use:scrollStagger={{ stagger: 60 }}>…</ul>
+<div ref={useScrollAnimate({ animation: 'fade-in-left' })}>…</div>
+```
+
+`use:scrollAnimate` / `use:scrollStagger` are typed through `JSX.Directives`. Elements are observed on mount and released on cleanup.
+
+### Web Component (`use-scroll-animate/element`)
+
+```html
+<script type="module">
+  import { defineScrollAnimate } from 'use-scroll-animate/element';
+  defineScrollAnimate(); // registers <scroll-animate>; defineScrollAnimate('my-reveal') for another tag
+</script>
+
+<scroll-animate animation="fade-in-up" duration="800" easing="spring">…</scroll-animate>
+```
+
+Or without a build step (registers `<scroll-animate>` on load):
+
+```html
+<script src="https://unpkg.com/use-scroll-animate/dist/element.umd.js"></script>
+```
+
+Attributes are the `data-sa-*` attributes without the prefix (`animation`, `duration`, `delay`, `easing`, `threshold`, `root-margin`, `offset`, `once`, `repeat`, `engine`, `view-range`, `progress`, `progress-var`, `exit`, `parallax-*`). The element dispatches `sa:enter`, `sa:leave`, `sa:start`, `sa:complete` and, with `progress`/`progress-var`, `sa:progress` (`event.detail.progress`). It renders as `display: block` unless you style it.
+
+All integrations share the core engine (and, through shared chunks, the same code when you import several entries), so `once`, `offset`, custom easing functions, parallax, the native engine and reduced-motion handling behave exactly like the vanilla API.
 
 ## Contributing
 

package/README_ja.md

@@ -23,6 +23,12 @@
 - 🧩 **フレームワークに依存しない**：Vanilla JS、React、Vue、Svelteなどとシームレスに動作。一流の React Hooks と Vue Composables を内蔵。
 - ♿ **アクセシブル**：`prefers-reduced-motion` を標準でサポート。
 
+## ドキュメント
+
+- [API リファレンス](./docs/API.md)（英語）· [デモ](./demo/index.html)（全プリセットをクリックで再生、ビルド不要）
+- 移行ガイド：[AOS から](./docs/migration-from-aos.md) · [GSAP ScrollTrigger から](./docs/migration-from-gsap-scrolltrigger.md)
+- [2.0 へのアップグレード](./docs/deprecations.md)：`createReactHooks` / `createVueComposables` は `use-scroll-animate/react` / `/vue` からのみ。`dist/index.mjs`・`dist/index.esm.js`・`dist/types/*`・`dist/*` ディープインポートは削除、デフォルトエンジンは `'auto'`。CDN の `dist/index.umd.js` は変更なし。詳細は [CHANGELOG](./CHANGELOG.md) の MIGRATION。
+
 ## インストール
 
 ```bash
@@ -46,6 +52,19 @@ npm install use-scroll-animate
 </script>
 ```
 
+## ネイティブのスクロール駆動エンジン `engine`（v1.6）
+
+CSS スクロール駆動アニメーション（`CSS.supports('animation-timeline: view()')`）に対応したブラウザでは、プリセットをブラウザ標準の **view timeline** 上で実行できます。進行度はスクロール位置に連動し（メインスレッド外）、IntersectionObserver で開始して固定の `duration` で再生する方式ではありません。
+
+```js
+ScrollAnimate.observe('.card', { animation: 'fade-in-up', engine: 'auto' });
+const sa = createScrollAnimate({ defaultEngine: 'auto' });
+```
+
+- `'auto'`：**2.0 からのデフォルト**。対応ブラウザではネイティブ、非対応なら JS。要素が `duration`・`delay`・`offset`・`stagger` を自分で指定した場合も JS。`'css'`：対応時は常にネイティブ。`'js'`：1.x の動作（`defaultEngine: 'js'` で全体に適用）。
+- ネイティブエンジンでは `duration`・`delay`・`threshold`・`offset`・`stagger` は無効で、範囲は `viewRange`（デフォルト `['entry 0%', 'entry 100%']`）。`easing` は有効。HTML：`data-sa-engine`、`data-sa-view-range`。
+- `once`（デフォルト）は完了時に最終状態を固定、`repeat: true` ではスクロールに双方向で追従。クラス名モード・reduced motion・`animate()`・`sequence()`・`staggerChildren()` は常に JS エンジン。`supportsScrollTimeline()` もエクスポート。
+
 ## v1.4.0 の新機能 ✨
 
 - **本当のスクロール進捗 `progressMode: 'scroll'`**（オプトイン）：`onProgress` はデフォルトで要素の表示比率を返すため、画面より高い要素では 1 に到達しません。有効にすると、要素の上端がビューポート下端に達したとき `0`、下端がビューポート上端を抜けたとき `1` になります。パララックスも同じ進捗を使用します。HTML では `data-sa-progress="scroll"`。ヘルパー `getScrollProgress(el, root?)` もエクスポートされています。
@@ -78,7 +97,7 @@ npm install use-scroll-animate
 
 - **新しいプリセット**：`scale-up`、`blur-in-up`、`flip-up`、`flip-down`、`rotate-left`、`rotate-right`、clip-path による `clip-up`、`clip-down`、`clip-left`、`clip-right`、`clip-circle`。
 - **メモリ使用量の削減**：`once` 要素はアニメーション開始後に自動でレジストリから削除されます（パララックス/`onProgress` が必要な要素を除く）。`WeakSet` で記憶されるため、`init()`/`observe()` で再生されることはありません。従来の挙動は `createScrollAnimate({ autoUnregister: false })`。
-- **正しい `exports` マップ**：Node ESM は `dist/index.mjs`、CommonJS は `dist/index.js` に解決され、それぞれ対応する型定義付き。従来の `main`/`module`/`unpkg` と `dist/*` のディープインポートも引き続き利用可能。
+- **正しい `exports` マップ**：2.0 から ESM 優先：`import` → `dist/*.js` + `*.d.ts`、`require` → `dist/*.cjs` + `*.d.cts`。
 
 ## v1.2.0 の新機能
 
@@ -87,6 +106,43 @@ npm install use-scroll-animate
 - **新しいプリセット**：`shimmer`（シマー）、`pulse`（パルス）、`swing`（スイング）を追加。
 - **多言語サポート**：中国語と日本語のドキュメントを追加。
 
+## フレームワーク連携（v1.7）
+
+各連携は独立したエントリポイント（`use-scroll-animate/react`・`/vue`・`/svelte`・`/solid`・`/element`）で、コアのコードを共有します。
+
+```svelte
+<!-- Svelte：action（svelte の import 不要） -->
+<script>import { scrollAnimate, scrollStagger } from 'use-scroll-animate/svelte';</script>
+<div use:scrollAnimate={{ animation: 'fade-in-up' }}>…</div>
+```
+
+```tsx
+// Solid：ディレクティブ + ref プリミティブ（solid-js は optional な peer 依存）
+import { scrollAnimate, useScrollAnimate } from 'use-scroll-animate/solid';
+<div use:scrollAnimate={{ animation: 'zoom-in' }}>…</div>
+```
+
+```html
+<!-- Web Component：属性は data-sa-* から接頭辞を除いたもの。sa:enter / sa:leave / sa:start / sa:complete / sa:progress イベントを発火 -->
+<script type="module">
+  import { defineScrollAnimate } from 'use-scroll-animate/element';
+  defineScrollAnimate();
+</script>
+<scroll-animate animation="fade-in-up" duration="800">…</scroll-animate>
+```
+
+## 退場アニメーションとパララックス（v1.8）
+
+```js
+ScrollAnimate.observe('.card', { animation: 'fade-in-up', exit: true });          // ビューポート外へ出るとき入場を逆再生
+ScrollAnimate.observe('.toast', { animation: 'zoom-in', exit: 'fade-in-down' });  // 別プリセットを逆再生して退場
+import { parallax } from 'use-scroll-animate';
+parallax('.hero-bg', { speed: 0.3 });  // 正：ページより遅い、負：速い。axis: 'x' も可
+```
+
+- `exit`：`true`・プリセット名・配列・`{ from, to }`。`repeat: true` を暗黙に有効化。`data-sa-exit` 属性にも対応。reduced motion 時は再生しません。
+- `parallax()`：進行度を CSS 変数（既定 `--sa-parallax`）に、オフセットを個別の `translate` プロパティに書き込むため `transform` と競合しません。reduced motion 時はオフセットなし。停止関数を返します。
+
 ## 主な設定
 
 | オプション | 型 | デフォルト | 説明 |

package/README_zh.md

@@ -23,6 +23,12 @@
 - 🧩 **框架无关**：完美支持原生 JS、React、Vue、Svelte 等。内置一流的 React Hooks 和 Vue Composables。
 - ♿ **无障碍**：原生支持 `prefers-reduced-motion`。
 
+## 文档
+
+- [API 参考](./docs/API.md)（英文）· [演示页](./demo/index.html)（每个预设都可点击，无需构建）
+- 迁移指南：[从 AOS 迁移](./docs/migration-from-aos.md) · [从 GSAP ScrollTrigger 迁移](./docs/migration-from-gsap-scrolltrigger.md)
+- [升级到 2.0](./docs/deprecations.md)：`createReactHooks` / `createVueComposables` 只能从 `use-scroll-animate/react` / `/vue` 导入；`dist/index.mjs`、`dist/index.esm.js`、`dist/types/*` 与 `dist/*` 深层导入已移除；默认引擎改为 `'auto'`。CDN 地址 `dist/index.umd.js` 不变。详见 [CHANGELOG](./CHANGELOG.md) 的 MIGRATION 部分。
+
 ## 安装
 
 ```bash
@@ -46,6 +52,20 @@ npm install use-scroll-animate
 </script>
 ```
 
+## 原生滚动驱动引擎 `engine`（v1.6）
+
+在支持 CSS 滚动驱动动画（`CSS.supports('animation-timeline: view()')`）的浏览器中，预设动画可以运行在浏览器原生的 **view timeline** 上：动画进度跟随滚动位置（在主线程之外），而不是由 IntersectionObserver 触发后按固定 `duration` 播放。
+
+```js
+ScrollAnimate.observe('.card', { animation: 'fade-in-up', engine: 'auto' });
+const sa = createScrollAnimate({ defaultEngine: 'auto' }); // 实例级默认
+```
+
+- `'auto'`：**2.0 起的默认值**，支持时使用原生时间线，否则回退 JS；若元素自行设置了 `duration`、`delay`、`offset` 或 `stagger`，则使用 JS。`'css'`：支持时始终使用原生时间线。`'js'`：1.x 的行为（`defaultEngine: 'js'` 可全局恢复）。
+- 原生引擎下 `duration`、`delay`、`threshold`、`offset`、`stagger` 不生效；动画区间由 `viewRange` 决定（默认 `['entry 0%', 'entry 100%']`），`easing` 仍然有效。HTML：`data-sa-engine`、`data-sa-view-range="entry 0%, cover 40%"`。
+- `once`（默认）在动画完成后固定最终状态；`repeat: true` 时随滚动双向播放。回调、`onProgress`、`progressVar`、视差照常工作。
+- 类名模式、`prefers-reduced-motion`、`animate()`、`sequence()`、`staggerChildren()` 始终使用 JS 引擎。另导出 `supportsScrollTimeline()`。
+
 ## v1.4.0 新特性 ✨
 
 - **真实滚动进度 `progressMode: 'scroll'`**（可选）：`onProgress` 默认返回元素的可见比例，对高于屏幕的元素永远到不了 1。开启后进度为：元素顶部到达视口底部时为 `0`，底部离开视口顶部时为 `1`。视差同样使用该进度。HTML 写法：`data-sa-progress="scroll"`；另导出辅助函数 `getScrollProgress(el, root?)`。
@@ -78,7 +98,7 @@ npm install use-scroll-animate
 
 - **新预设**：`scale-up`、`blur-in-up`、`flip-up`、`flip-down`、`rotate-left`、`rotate-right`，以及 clip-path 揭示 `clip-up`、`clip-down`、`clip-left`、`clip-right`、`clip-circle`。
 - **更省内存**：`once` 元素动画触发后自动从注册表移除（仍需视差/`onProgress` 的除外），并记录在 `WeakSet` 中，`init()`/`observe()` 不会重复播放。如需旧行为可设置 `createScrollAnimate({ autoUnregister: false })`。
-- **规范的 `exports` 字段**：Node ESM 解析到 `dist/index.mjs`，CommonJS 解析到 `dist/index.js`，均带对应类型声明；原有 `main`/`module`/`unpkg` 与 `dist/*` 深层导入保持可用。
+- **规范的 `exports` 字段**：2.0 起以 ESM 为主：`import` → `dist/*.js` + `*.d.ts`，`require` → `dist/*.cjs` + `*.d.cts`。
 
 ## v1.2.0 新特性
 
@@ -87,6 +107,51 @@ npm install use-scroll-animate
 - **新预设**：新增 `shimmer`（流光）、`pulse`（脉冲）、`swing`（摇摆）。
 - **多语言支持**：新增中文和日文文档。
 
+## 框架集成（v1.7）
+
+每个集成都是独立的入口（`use-scroll-animate/react`、`/vue`、`/svelte`、`/solid`、`/element`），共享同一份核心代码。
+
+```svelte
+<!-- Svelte：action，无需引入 svelte -->
+<script>import { scrollAnimate, scrollStagger } from 'use-scroll-animate/svelte';</script>
+<div use:scrollAnimate={{ animation: 'fade-in-up' }}>…</div>
+<ul use:scrollStagger={{ stagger: 60 }}>…</ul>
+```
+
+```tsx
+// Solid：指令 + ref 原语（solid-js 为可选 peer 依赖）
+import { scrollAnimate, useScrollAnimate } from 'use-scroll-animate/solid';
+<div use:scrollAnimate={{ animation: 'zoom-in' }}>…</div>
+<div ref={useScrollAnimate({ animation: 'fade-in-left' })}>…</div>
+```
+
+```html
+<!-- Web Component：属性与 data-sa-* 相同（去掉前缀），并派发 sa:enter / sa:leave / sa:start / sa:complete / sa:progress 事件 -->
+<script type="module">
+  import { defineScrollAnimate } from 'use-scroll-animate/element';
+  defineScrollAnimate();
+</script>
+<scroll-animate animation="fade-in-up" duration="800">…</scroll-animate>
+<!-- 无构建：<script src="https://unpkg.com/use-scroll-animate/dist/element.umd.js"></script> -->
+```
+
+## 退场动画与视差辅助函数（v1.8）
+
+```js
+ScrollAnimate.observe('.card', { animation: 'fade-in-up', exit: true });          // 离开视口时反向播放入场动画
+ScrollAnimate.observe('.toast', { animation: 'zoom-in', exit: 'fade-in-down' });  // 用另一个预设（反向）退场
+```
+
+- `exit`：`true`、预设名、预设数组或 `{ from, to }`；离开视口时反向播放，再次进入时重新入场（默认隐含 `repeat: true`）。HTML：`data-sa-exit` / `data-sa-exit="zoom-out"`。原生引擎下退场同样随滚动驱动；减少动态效果时不播放。
+
+```js
+import { parallax } from 'use-scroll-animate';
+const stop = parallax('.hero-bg', { speed: 0.3 });   // 正值：比页面慢（背景）；负值：比页面快
+parallax('.badge', { speed: -0.15, axis: 'x' });
+```
+
+- `parallax(target, { speed = 0.2, axis = 'y', progressVar = '--sa-parallax', root, respectReducedMotion = true })`：进度写入 CSS 变量，位移写入独立的 `translate` 属性（与 `transform` 和入场动画互不冲突）；`prefers-reduced-motion` 时只写变量不位移。返回停止函数。
+
 ## 核心配置
 
 | 选项 | 类型 | 默认值 | 描述 |
@@ -100,6 +165,8 @@ npm install use-scroll-animate
 | `stagger` | `number` | `0` | 同批次显现的兄弟元素之间的额外延迟 (ms) |
 | `onProgress` | `(el, progress) => void` | – | 滚动进度回调 (0–1) |
 | `progressMode` | `'ratio'` \| `'scroll'` | `'ratio'` | 进度计算方式：可见比例或真实滚动进度 |
+| `engine` | `'auto'` \| `'js'` \| `'css'` | `'auto'` | 支持时使用原生滚动驱动时间线，否则回退 JS |
+| `viewRange` | `[string, string]` | `['entry 0%', 'entry 100%']` | 仅原生引擎：入场动画的时间线区间 |
 
 ## 许可证