motionary 0.0.0-stage → 6.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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,219 @@
-# Temporary Holding Version
+<div align="center">
 
-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.
+# Motionary
+
+**Scroll animations and animated Web Components for the modern web — 214 scroll presets, 90 effects, zero dependencies.**
+
+_Formerly **use-scroll-animate** — same API, same `<usa-*>` tags; the old npm package keeps working as an alias._
+
+[![npm](https://img.shields.io/npm/v/motionary?style=flat-square)](https://www.npmjs.com/package/motionary) [![CI](https://github.com/HarrisonCN/motionary/actions/workflows/ci.yml/badge.svg)](https://github.com/HarrisonCN/motionary/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](./LICENSE)
+
+[English](./README.md) | [简体中文](./README_zh.md) | [日本語](./README_ja.md)
+
+**[🛍 Animation Store](https://harrisoncn.github.io/motionary/showcase/)** · **[🧩 Components](https://harrisoncn.github.io/motionary/showcase/components.html)** · **[🎛 Playground](https://harrisoncn.github.io/motionary/showcase/playground.html)** · **[📜 Story](https://harrisoncn.github.io/motionary/showcase/story.html)**
+
+<sub>The Store lets you preview, tweak and copy all <b>227</b> animations — 214 scroll presets plus card, click, physics and page effects — at desktop and phone sizes.</sub>
+
+</div>
+
+Motionary reveals content as it scrolls into view (IntersectionObserver + Web Animations, or the browser's native scroll timeline) and ships 94 animated custom elements — cards, buttons, physics, page transitions, backgrounds, WebGL and more — that work in any framework, in plain HTML and in desktop web-view apps (Electron, Tauri, WebView2). Everything respects `prefers-reduced-motion`.
+
+## Install
+
+```bash
+npm i motionary
+```
+
+```html
+<!-- CDN (no build) -->
+<script src="https://unpkg.com/motionary@6/dist/index.umd.js"></script>            <!-- window.ScrollAnimate -->
+<script src="https://unpkg.com/motionary@6/dist/presets-extended.umd.js"></script> <!-- +181 presets -->
+<script src="https://unpkg.com/motionary@6/dist/components.umd.js"></script>       <!-- every <usa-*>, window.UsaComponents -->
+```
+
+jsDelivr works too: `https://cdn.jsdelivr.net/npm/motionary@6/dist/…`. Existing `use-scroll-animate` installs and `unpkg.com/use-scroll-animate@6` URLs keep working.
+
+## 30-second quickstart
+
+Mark elements with `data-sa` and pick a preset with `data-sa-animation` (every option has a `data-sa-*` attribute), or use the JS API:
+
+```html
+<!-- 1. HTML only: data attributes + one init() call -->
+<h2 data-sa data-sa-animation="fade-in-up">Hello</h2>
+<div data-sa data-sa-animation="bounce-in-up" data-sa-delay="150">Card</div>
+<script type="module">
+  import ScrollAnimate from 'motionary';
+  import 'motionary/presets/extended'; // optional: +181 presets (bounce-in-up, clip-diamond, …)
+  ScrollAnimate.init(); // picks up every [data-sa]
+</script>
+```
+
+```js
+// 2. JS API
+import ScrollAnimate, { staggerChildren, parallax, timeline } from 'motionary';
+
+ScrollAnimate.observe('.card', { animation: 'zoom-in-up', duration: 800, easing: 'spring' });
+staggerChildren(document.querySelector('.grid'), { animation: 'stagger-pop', stagger: 60 });
+parallax('.hero-bg', { speed: 0.3 });
+ScrollAnimate.observe('.logo', { animation: 'scrub-spin', engine: 'css', viewRange: ['cover 0%', 'cover 100%'] });
+```
+
+Frameworks — each adapter is its own entry point and cleans up on unmount:
+
+```jsx
+// React
+import React from 'react';
+import { createReactHooks } from 'motionary/react';
+const { useScrollAnimate } = createReactHooks(React);
+
+export function Card() {
+  const ref = useScrollAnimate({ animation: 'fade-in-up' });
+  return <div ref={ref}>Hello</div>;
+}
+```
+
+```vue
+<!-- Vue 3 -->
+<script setup>
+import { ref, onMounted, onUnmounted } from 'vue';
+import { createVueComposables } from 'motionary/vue';
+const { useScrollAnimate } = createVueComposables({ ref, onMounted, onUnmounted });
+const { animateRef } = useScrollAnimate({ animation: 'zoom-in' });
+</script>
+<template><div ref="animateRef">Hello</div></template>
+```
+
+```svelte
+<!-- Svelte 3–5 -->
+<script>
+  import { scrollAnimate } from 'motionary/svelte';
+</script>
+<div use:scrollAnimate={{ animation: 'flip-up' }}>Hello</div>
+```
+
+```jsx
+// Solid
+import { scrollAnimate } from 'motionary/solid';
+scrollAnimate; // keep the directive import (TypeScript)
+export const Card = () => <div use:scrollAnimate={{ animation: 'blur-in-up' }}>Hello</div>;
+```
+
+```ts
+// Angular (standalone) — the animated Web Components
+import { APP_INITIALIZER, CUSTOM_ELEMENTS_SCHEMA, Component } from '@angular/core';
+import { usaInitializer } from 'motionary/components/angular';
+import 'motionary/presets/extended'; // lets <usa-reveal effect> use every preset name
+// app.config.ts: providers: [{ provide: APP_INITIALIZER, multi: true, useFactory: usaInitializer() }]
+@Component({ standalone: true, schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `<usa-reveal effect="bounce-in-up"><h2>Hello</h2></usa-reveal>` })
+export class Hero {}
+```
+
+Animated components need no framework at all:
+
+```html
+<script type="module">
+  import { defineComponents } from 'motionary/components';
+  defineComponents(); // or lazyDefine() from 'motionary/components/lazy'
+</script>
+<usa-card effect="holo">…</usa-card>
+<usa-button deform="gooey">Buy</usa-button>
+<usa-fx effect="confetti" trigger="click"><button>Celebrate</button></usa-fx>
+```
+
+## What's inside
+
+| Area | What you get |
+|---|---|
+| **Scroll presets** | **214** reveal presets (33 core + 181 in `motionary/presets/extended`) in 14 families — fades, zooms, 3D flips & doors, overshoot slides, clip-path shapes, blur & mask, bounce & elastic, colour & light, depth, glitch / typewriter, stagger-ready and scroll-linked `scrub-*`; plus `timeline()` with 10 timeline presets |
+| **Cards, clicks & button morphs** | `<usa-card>` with 10 effects (flip, holo, glass, border glow, …), stacks & 3D carousel; 7 click components with 4 button deforms (squash · wobble · gooey · dent) and icon morphs; 12 registered card / click effects (holo, book-open, shockwave, ink-splash, emoji-rain, …) |
+| **Physics & bounce** | `<usa-spring>`, `<usa-draggable>` (spring-back · inertia · snap), `<usa-overscroll>`; `spring()` / `solveSpring()` with 7 spring presets; 7 physics effects (bounce-in, rubber-band, gravity-text, bell-swing, …) |
+| **Page transitions** | `pageTransition()`, `viewTransition()`, `sharedTransition()`, `flip()`, MPA transitions; 7 page effects (curtain, iris, pixel-dissolve, blinds, velocity-skew, …); `<usa-dialog>`, `<usa-view-switch>` |
+| **Generative backgrounds** | 6 canvas backgrounds (flow-field, voronoi, mesh-gradient, starfield, metaballs, contours) + 9 background elements (aurora, particles, grain, blobs, water ripple, Acrylic / Mica, …) |
+| **Sound-reactive** | `<usa-audio>` + Web Audio beat detection (`createBeatDetector()`, `onBeat()`); 3 audio visualisers (spectrum-bars, pulse-ring, wave-ring); any effect can fire on the beat |
+| **Cursor & gestures** | 5 cursor effects (comet / ribbon / sparkle trails, magnetic dots, spotlight) + `<usa-cursor>`; fling · twist · long-press → effects with `<usa-gesture-fx>`; `<usa-swipeable>`, `<usa-pinch-zoom>` |
+| **Themes** | 5 theme packs (neon · paper · glass · retro · brutalist) via `<usa-theme>` / `applyTheme()`, each with a signature effect; motion tokens (`/components/tokens`) |
+| **Micro-interactions** | 23 ready-made UI moments: copy-success, like-heart, add-to-cart, send-plane, upvote, trash-shake, input-shake, success-check, notify-badge, … |
+| **`<usa-player>` & stories** | `<usa-player>` plays JSON animations (keyframe tracks, presets, effects; load / view / scroll / click triggers) exported from the Playground; `<usa-story>` with 6 scroll-story templates |
+| **WebGL** | `<usa-shader>`, `<usa-distort>`, `<usa-liquid>`, `<usa-post-fx>` — 5 particle presets, 9 post effects (bloom, CRT, chromatic, glitch, …) with CSS fallbacks and a power-saving governor |
+
+90 effects share one registry (`registerEffect()` / `playEffect()` / `bindEffect()` / `<usa-fx>`, `motionary/components/fx`); the 5.x packs live in `motionary/components/effects`.
+
+### All 94 animated components
+
+Import one category (`motionary/components/cards`), everything (`motionary/components`), the CSS-on-demand build (`/components/lite`), or let `lazyDefine()` load only the tags on the page. Wrappers: `/components/react`, `/vue`, `/svelte`, `/solid`, `/angular`.
+
+| Entry | Elements |
+|---|---|
+| **Scroll reveal** (`/components/reveal`) | `<usa-reveal>` · `<usa-stagger>` · `<usa-scroll-progress>` · `<usa-scrolly>` |
+| **Text** (`/components/text`) | `<usa-typewriter>` · `<usa-split-text>` · `<usa-scramble>` · `<usa-counter>` · `<usa-shimmer-text>` · `<usa-text-rotate>` · `<usa-wave-text>` · `<usa-glitch>` · `<usa-gradient-text>` · `<usa-handwriting>` · `<usa-scroll-highlight>` |
+| **Interaction** (`/components/interaction`) | `<usa-ripple>` · `<usa-magnetic>` · `<usa-tilt>` · `<usa-spotlight>` · `<usa-press>` · `<usa-toggle>` |
+| **Feedback** (`/components/feedback`) | `<usa-spinner>` · `<usa-skeleton>` · `<usa-progress>` · `<usa-toaster>` · `<usa-check>` |
+| **Backgrounds** (`/components/background`) | `<usa-aurora>` · `<usa-particles>` · `<usa-grain>` · `<usa-marquee>` · `<usa-acrylic>` · `<usa-grid-glow>` · `<usa-blobs>` · `<usa-water-ripple>` · `<usa-dot-network>` |
+| **Transitions** (`/components/transitions`) | `<usa-dialog>` · `<usa-accordion>` · `<usa-view-switch>` |
+| **Spring & physics** (`/components/physics`) | `<usa-spring>` · `<usa-draggable>` · `<usa-overscroll>` |
+| **Cards** (`/components/cards`) | `<usa-card>` · `<usa-card-stack>` · `<usa-sticky-stack>` · `<usa-carousel-3d>` |
+| **Click & buttons** (`/components/click`) | `<usa-click>` · `<usa-button>` · `<usa-icon-morph>` · `<usa-like>` · `<usa-hold>` · `<usa-double-tap>` · `<usa-checkbox>` |
+| **UI kit** (`/components/ui`) | `<usa-tabs>` · `<usa-drawer>` · `<usa-bottom-sheet>` · `<usa-pull-refresh>` · `<usa-fab>` · `<usa-navbar>` · `<usa-slider>` · `<usa-rating>` · `<usa-tooltip>` · `<usa-popover>` · `<usa-badge>` · `<usa-avatar-stack>` |
+| **Page-wide** (`/components/page`) | `<usa-cursor>` · `<usa-fullpage>` · `<usa-loading-bar>` · `<usa-back-to-top>` · `<usa-ambient>` · `<usa-splash>` · `<usa-auto-skeleton>` · `<usa-motion-switch>` |
+| **Timeline** (`/components/timeline`) | `<usa-timeline>` |
+| **Gestures** (`/components/gesture`) | `<usa-swipeable>` · `<usa-pinch-zoom>` |
+| **SVG** (`/components/svg`) | `<usa-draw>` · `<usa-morph>` · `<usa-mask-reveal>` · `<usa-anim-icon>` |
+| **WebGL** (`/components/webgl`) | `<usa-shader>` · `<usa-distort>` · `<usa-liquid>` · `<usa-post-fx>` |
+| **3D depth** (`/components/depth`) | `<usa-cube>` · `<usa-depth>` |
+| **Layout** (`/components/layout`) | `<usa-auto-animate>` · `<usa-masonry>` |
+| **Packs** (`/components/packs`) | `<usa-pack>` |
+| **Effect registry** (`/components/fx`) | `<usa-fx>` |
+| **Effect packs** (`/components/effects`) | `<usa-player>` · `<usa-story>` · `<usa-audio>` · `<usa-theme>` · `<usa-gesture-fx>` |
+
+## Accessibility & reduced motion
+
+- With `prefers-reduced-motion: reduce`, scroll reveals show content immediately (no entrance, parallax or scrub motion), and components fall back to calm states (`staticAlternative()` / `adaptKeyframes()`).
+- `motionary/components/a11y`: `setMotionSensitivity()` levels let users drop flashes, loops or parallax; `announce()` live regions; `auditMotionA11y()`; `baselineReport()`. `<usa-motion-switch>` is a ready-made user-facing motion toggle.
+- Details: [docs/accessibility.md](./docs/accessibility.md).
+
+## Performance & size
+
+No scroll listeners by default (IntersectionObserver), animations on the compositor (`transform`, `opacity`, `filter`, `clip-path`), optional off-main-thread native scroll timelines (`engine: 'css'`). Every entry is tree-shakeable and has a gzip budget enforced in CI (`size-budget.json`). Measured for 6.1 (minified + gzip):
+
+| What you import | gzip |
+|---|---:|
+| `import ScrollAnimate from 'motionary'` (default instance) | 5.72 kB |
+| Everything from the main entry | 8.69 kB |
+| `dist/index.umd.js` (CDN) | 8.81 kB |
+| `parallax()` alone | 1.22 kB |
+| `motionary/presets/extended` (181 presets) | 4.69 kB |
+| `motionary/components/reveal` | 4.10 kB |
+| `motionary/components/effects` (8 effect packs) | 26.40 kB |
+| `motionary/components/lite` (every component, CSS on demand) | 68.48 kB |
+| `motionary/components` (every component + CSS) | 85.15 kB |
+| `dist/components.umd.js` (CDN, everything) | 106.75 kB |
+
+More: [docs/performance.md](./docs/performance.md).
+
+## Browser support
+
+Evergreen browsers since 2023: Chrome / Edge ≥ 111, Safari ≥ 16.4, Firefox ≥ 115, WebView2, Electron ≥ 24 (Custom Elements, Web Animations, IntersectionObserver, ResizeObserver, constructable stylesheets). View Transitions and scroll-driven animations are progressive — used when present, JS fallback otherwise. Importing on the server (SSR) is a no-op. Check a browser with `baselineReport()`.
+
+## Documentation
+
+- [API reference](./docs/API.md) — every export, option and `data-sa-*` attribute
+- [Presets](./docs/presets.md) — all 214 by category
+- [Components](./docs/components.md) — every `<usa-*>` element, attribute and event
+- [Frameworks & SSR](./docs/frameworks-ssr.md) · [Windows apps](./docs/windows-apps.md) · [Hybrid apps (MAUI, Flutter, Electron, Tauri)](./docs/hybrid-apps.md)
+- [Motion tokens](./docs/motion-tokens.md) · [Migrating from AOS](./docs/migration-from-aos.md) · [from GSAP ScrollTrigger](./docs/migration-from-gsap-scrolltrigger.md)
+- [Demo page](./demo/index.html) — every preset clickable, no build step
+
+## Upgrading
+
+- From `use-scroll-animate`: `npm i motionary` and replace `use-scroll-animate` with `motionary` in imports and CDN URLs — nothing else changes (the old package name keeps receiving the same releases).
+- [Upgrading to 6.0](./docs/upgrading-6.md) (`npx usa-codemod-6`) · [Upgrading to 5.0](./docs/upgrading-5.md) (`npx usa-codemod-5`) · [4.0](./docs/upgrading-4.md) · [3.0](./docs/upgrading-3.md) · [2.0](./docs/deprecations.md)
+- [Changelog](./CHANGELOG.md)
+
+## Roadmap
+
+One version per PR towards 7.0 — particles & fluids, text effects, light & materials, 3D scenes, morphing, transitions, weather, interactive physics: [docs/ROADMAP.md](./docs/ROADMAP.md).
+
+## Contributing & license
+
+Issues and PRs welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). MIT © HarrisonCN — see [LICENSE](./LICENSE).

package/README_ja.md

@@ -0,0 +1,219 @@
+<div align="center">
+
+# Motionary
+
+**モダン Web のためのスクロールアニメーションとアニメーション Web Components — 214 のスクロールプリセット、90 のエフェクト、依存ゼロ。**
+
+_旧名 **use-scroll-animate** — API と `<usa-*>` タグはそのまま。旧 npm パッケージもエイリアスとして公開を継続します。_
+
+[![npm](https://img.shields.io/npm/v/motionary?style=flat-square)](https://www.npmjs.com/package/motionary) [![CI](https://github.com/HarrisonCN/motionary/actions/workflows/ci.yml/badge.svg)](https://github.com/HarrisonCN/motionary/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](./LICENSE)
+
+[English](./README.md) | [简体中文](./README_zh.md) | [日本語](./README_ja.md)
+
+**[🛍 アニメーションストア](https://harrisoncn.github.io/motionary/showcase/)** · **[🧩 コンポーネント](https://harrisoncn.github.io/motionary/showcase/components.html)** · **[🎛 Playground](https://harrisoncn.github.io/motionary/showcase/playground.html)** · **[📜 ストーリー](https://harrisoncn.github.io/motionary/showcase/story.html)**
+
+<sub>ストアでは全 <b>227</b> 件のアニメーション（214 のスクロールプリセットとカード・クリック・物理・ページ効果）をデスクトップ／スマホ幅でプレビュー・調整・コピーできます。</sub>
+
+</div>
+
+Motionary はスクロールで表示される要素をアニメーションさせ（IntersectionObserver + Web Animations、またはブラウザ標準のスクロールタイムライン）、カード・ボタン・物理・ページトランジション・背景・WebGL など 94 個のアニメーション付きカスタム要素を提供します。どのフレームワークでも、素の HTML でも、デスクトップの Web ビューアプリ（Electron・Tauri・WebView2）でも動き、すべて `prefers-reduced-motion` を尊重します。
+
+## インストール
+
+```bash
+npm i motionary
+```
+
+```html
+<!-- CDN (no build) -->
+<script src="https://unpkg.com/motionary@6/dist/index.umd.js"></script>            <!-- window.ScrollAnimate -->
+<script src="https://unpkg.com/motionary@6/dist/presets-extended.umd.js"></script> <!-- +181 presets -->
+<script src="https://unpkg.com/motionary@6/dist/components.umd.js"></script>       <!-- every <usa-*>, window.UsaComponents -->
+```
+
+jsDelivr も利用できます：`https://cdn.jsdelivr.net/npm/motionary@6/dist/…`。既存の `use-scroll-animate` と `unpkg.com/use-scroll-animate@6` の URL もそのまま動きます。
+
+## 30 秒クイックスタート
+
+要素に `data-sa` を付け、`data-sa-animation` でプリセットを選びます（すべてのオプションに `data-sa-*` 属性あり）。JS API も使えます：
+
+```html
+<!-- 1. HTML only: data attributes + one init() call -->
+<h2 data-sa data-sa-animation="fade-in-up">Hello</h2>
+<div data-sa data-sa-animation="bounce-in-up" data-sa-delay="150">Card</div>
+<script type="module">
+  import ScrollAnimate from 'motionary';
+  import 'motionary/presets/extended'; // optional: +181 presets (bounce-in-up, clip-diamond, …)
+  ScrollAnimate.init(); // picks up every [data-sa]
+</script>
+```
+
+```js
+// 2. JS API
+import ScrollAnimate, { staggerChildren, parallax, timeline } from 'motionary';
+
+ScrollAnimate.observe('.card', { animation: 'zoom-in-up', duration: 800, easing: 'spring' });
+staggerChildren(document.querySelector('.grid'), { animation: 'stagger-pop', stagger: 60 });
+parallax('.hero-bg', { speed: 0.3 });
+ScrollAnimate.observe('.logo', { animation: 'scrub-spin', engine: 'css', viewRange: ['cover 0%', 'cover 100%'] });
+```
+
+フレームワーク — 各アダプターは独立したエントリで、アンマウント時に自動で後片付けします：
+
+```jsx
+// React
+import React from 'react';
+import { createReactHooks } from 'motionary/react';
+const { useScrollAnimate } = createReactHooks(React);
+
+export function Card() {
+  const ref = useScrollAnimate({ animation: 'fade-in-up' });
+  return <div ref={ref}>Hello</div>;
+}
+```
+
+```vue
+<!-- Vue 3 -->
+<script setup>
+import { ref, onMounted, onUnmounted } from 'vue';
+import { createVueComposables } from 'motionary/vue';
+const { useScrollAnimate } = createVueComposables({ ref, onMounted, onUnmounted });
+const { animateRef } = useScrollAnimate({ animation: 'zoom-in' });
+</script>
+<template><div ref="animateRef">Hello</div></template>
+```
+
+```svelte
+<!-- Svelte 3–5 -->
+<script>
+  import { scrollAnimate } from 'motionary/svelte';
+</script>
+<div use:scrollAnimate={{ animation: 'flip-up' }}>Hello</div>
+```
+
+```jsx
+// Solid
+import { scrollAnimate } from 'motionary/solid';
+scrollAnimate; // keep the directive import (TypeScript)
+export const Card = () => <div use:scrollAnimate={{ animation: 'blur-in-up' }}>Hello</div>;
+```
+
+```ts
+// Angular (standalone) — the animated Web Components
+import { APP_INITIALIZER, CUSTOM_ELEMENTS_SCHEMA, Component } from '@angular/core';
+import { usaInitializer } from 'motionary/components/angular';
+import 'motionary/presets/extended'; // lets <usa-reveal effect> use every preset name
+// app.config.ts: providers: [{ provide: APP_INITIALIZER, multi: true, useFactory: usaInitializer() }]
+@Component({ standalone: true, schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `<usa-reveal effect="bounce-in-up"><h2>Hello</h2></usa-reveal>` })
+export class Hero {}
+```
+
+アニメーションコンポーネントはフレームワーク不要：
+
+```html
+<script type="module">
+  import { defineComponents } from 'motionary/components';
+  defineComponents(); // or lazyDefine() from 'motionary/components/lazy'
+</script>
+<usa-card effect="holo">…</usa-card>
+<usa-button deform="gooey">Buy</usa-button>
+<usa-fx effect="confetti" trigger="click"><button>Celebrate</button></usa-fx>
+```
+
+## 機能一覧
+
+| 分野 | 内容 |
+|---|---|
+| **スクロールプリセット** | **214** 種の入場プリセット（コア 33 + `motionary/presets/extended` の 181）、14 系統：フェード、ズーム、3D フリップ・ドア、オーバーシュートスライド、clip-path 図形、ブラー・マスク、バウンス・弾性、色・光、奥行き、グリッチ / タイプライター、スタッガー向け、スクロール連動 `scrub-*`。`timeline()` と 10 種のタイムラインプリセットも |
+| **カード・クリック・ボタン変形** | `<usa-card>` の 10 エフェクト（flip・holo・glass・border glow など）、スタックと 3D カルーセル。クリック系 7 コンポーネント、4 種のボタン変形（squash · wobble · gooey · dent）とアイコンモーフ。登録済みカード / クリックエフェクト 12 種 |
+| **物理・バウンス** | `<usa-spring>`、`<usa-draggable>`（スプリングバック・慣性・スナップ）、`<usa-overscroll>`。`spring()` / `solveSpring()` と 7 種のバネプリセット、物理エフェクト 7 種 |
+| **ページトランジション** | `pageTransition()`・`viewTransition()`・`sharedTransition()`・`flip()`・MPA トランジション、ページエフェクト 7 種（curtain・iris・pixel-dissolve など）、`<usa-dialog>`・`<usa-view-switch>` |
+| **ジェネラティブ背景** | キャンバス背景 6 種（flow-field・voronoi・mesh-gradient・starfield・metaballs・contours）+ 背景要素 9 種（オーロラ・パーティクル・グレイン・Acrylic / Mica など） |
+| **サウンド連動** | `<usa-audio>` と Web Audio のビート検出（`createBeatDetector()`・`onBeat()`）、オーディオビジュアライザー 3 種、任意のエフェクトをビートで発火 |
+| **カーソル・ジェスチャー** | カーソルエフェクト 5 種 + `<usa-cursor>`、fling · twist · long-press でエフェクト（`<usa-gesture-fx>`）、`<usa-swipeable>`・`<usa-pinch-zoom>` |
+| **テーマ** | テーマ 5 種（neon · paper · glass · retro · brutalist）を `<usa-theme>` / `applyTheme()` で、各テーマに専用エフェクト。モーショントークン（`/components/tokens`） |
+| **マイクロインタラクション** | 既製の UI 演出 23 種：copy-success・like-heart・add-to-cart・send-plane・upvote・trash-shake など |
+| **`<usa-player>` とストーリー** | `<usa-player>` は Playground から書き出した JSON アニメーションを再生（キーフレーム・プリセット・エフェクト、load / view / scroll / click トリガー）。`<usa-story>` のストーリーテンプレート 6 種 |
+| **WebGL** | `<usa-shader>`・`<usa-distort>`・`<usa-liquid>`・`<usa-post-fx>` — パーティクル 5 種、ポストエフェクト 9 種（CSS フォールバックと省電力制御付き） |
+
+90 のエフェクトは 1 つのレジストリ（`registerEffect()` / `playEffect()` / `bindEffect()` / `<usa-fx>`、`motionary/components/fx`）を共有し、5.x のパックは `motionary/components/effects` にあります。
+
+### 全 94 コンポーネント
+
+カテゴリ単位（`motionary/components/cards`）、全部（`motionary/components`）、CSS 遅延読み込みの `/components/lite`、またはページ上のタグだけを読む `lazyDefine()` から選べます。ラッパー：`/components/react`・`/vue`・`/svelte`・`/solid`・`/angular`。
+
+| エントリ | 要素 |
+|---|---|
+| **スクロール表示** (`/components/reveal`) | `<usa-reveal>` · `<usa-stagger>` · `<usa-scroll-progress>` · `<usa-scrolly>` |
+| **テキスト** (`/components/text`) | `<usa-typewriter>` · `<usa-split-text>` · `<usa-scramble>` · `<usa-counter>` · `<usa-shimmer-text>` · `<usa-text-rotate>` · `<usa-wave-text>` · `<usa-glitch>` · `<usa-gradient-text>` · `<usa-handwriting>` · `<usa-scroll-highlight>` |
+| **インタラクション** (`/components/interaction`) | `<usa-ripple>` · `<usa-magnetic>` · `<usa-tilt>` · `<usa-spotlight>` · `<usa-press>` · `<usa-toggle>` |
+| **フィードバック** (`/components/feedback`) | `<usa-spinner>` · `<usa-skeleton>` · `<usa-progress>` · `<usa-toaster>` · `<usa-check>` |
+| **背景** (`/components/background`) | `<usa-aurora>` · `<usa-particles>` · `<usa-grain>` · `<usa-marquee>` · `<usa-acrylic>` · `<usa-grid-glow>` · `<usa-blobs>` · `<usa-water-ripple>` · `<usa-dot-network>` |
+| **トランジション** (`/components/transitions`) | `<usa-dialog>` · `<usa-accordion>` · `<usa-view-switch>` |
+| **バネ・物理** (`/components/physics`) | `<usa-spring>` · `<usa-draggable>` · `<usa-overscroll>` |
+| **カード** (`/components/cards`) | `<usa-card>` · `<usa-card-stack>` · `<usa-sticky-stack>` · `<usa-carousel-3d>` |
+| **クリック・ボタン** (`/components/click`) | `<usa-click>` · `<usa-button>` · `<usa-icon-morph>` · `<usa-like>` · `<usa-hold>` · `<usa-double-tap>` · `<usa-checkbox>` |
+| **UI キット** (`/components/ui`) | `<usa-tabs>` · `<usa-drawer>` · `<usa-bottom-sheet>` · `<usa-pull-refresh>` · `<usa-fab>` · `<usa-navbar>` · `<usa-slider>` · `<usa-rating>` · `<usa-tooltip>` · `<usa-popover>` · `<usa-badge>` · `<usa-avatar-stack>` |
+| **ページ全体** (`/components/page`) | `<usa-cursor>` · `<usa-fullpage>` · `<usa-loading-bar>` · `<usa-back-to-top>` · `<usa-ambient>` · `<usa-splash>` · `<usa-auto-skeleton>` · `<usa-motion-switch>` |
+| **タイムライン** (`/components/timeline`) | `<usa-timeline>` |
+| **ジェスチャー** (`/components/gesture`) | `<usa-swipeable>` · `<usa-pinch-zoom>` |
+| **SVG** (`/components/svg`) | `<usa-draw>` · `<usa-morph>` · `<usa-mask-reveal>` · `<usa-anim-icon>` |
+| **WebGL** (`/components/webgl`) | `<usa-shader>` · `<usa-distort>` · `<usa-liquid>` · `<usa-post-fx>` |
+| **3D 奥行き** (`/components/depth`) | `<usa-cube>` · `<usa-depth>` |
+| **レイアウト** (`/components/layout`) | `<usa-auto-animate>` · `<usa-masonry>` |
+| **パック** (`/components/packs`) | `<usa-pack>` |
+| **エフェクト登録** (`/components/fx`) | `<usa-fx>` |
+| **エフェクトパック** (`/components/effects`) | `<usa-player>` · `<usa-story>` · `<usa-audio>` · `<usa-theme>` · `<usa-gesture-fx>` |
+
+## アクセシビリティと reduced motion
+
+- `prefers-reduced-motion: reduce` ではスクロール表示はすぐに表示され（入場・パララックス・スクラブなし）、コンポーネントは落ち着いた状態になります（`staticAlternative()` / `adaptKeyframes()`）。
+- `motionary/components/a11y`：`setMotionSensitivity()` のレベルで点滅・ループ・パララックスを抑制、`announce()` ライブリージョン、`auditMotionA11y()`、`baselineReport()`。`<usa-motion-switch>` はユーザー向けのモーション切替です。
+- 詳細：[docs/accessibility.md](./docs/accessibility.md)。
+
+## パフォーマンスとサイズ
+
+デフォルトで scroll リスナーなし（IntersectionObserver）、アニメーションはコンポジター上（`transform`・`opacity`・`filter`・`clip-path`）、メインスレッド外のネイティブスクロールタイムライン（`engine: 'css'`）も選べます。全エントリはツリーシェイク可能で、gzip 予算を CI で強制（`size-budget.json`）。6.1 の実測（minify + gzip）：
+
+| インポート | gzip |
+|---|---:|
+| `import ScrollAnimate from 'motionary'` (default instance) | 5.72 kB |
+| Everything from the main entry | 8.69 kB |
+| `dist/index.umd.js` (CDN) | 8.81 kB |
+| `parallax()` alone | 1.22 kB |
+| `motionary/presets/extended` (181 presets) | 4.69 kB |
+| `motionary/components/reveal` | 4.10 kB |
+| `motionary/components/effects` (8 effect packs) | 26.40 kB |
+| `motionary/components/lite` (every component, CSS on demand) | 68.48 kB |
+| `motionary/components` (every component + CSS) | 85.15 kB |
+| `dist/components.umd.js` (CDN, everything) | 106.75 kB |
+
+詳細：[docs/performance.md](./docs/performance.md)。
+
+## 対応ブラウザ
+
+2023 年以降のエバーグリーンブラウザ：Chrome / Edge ≥ 111、Safari ≥ 16.4、Firefox ≥ 115、WebView2、Electron ≥ 24（Custom Elements・Web Animations・IntersectionObserver・ResizeObserver・constructable stylesheets）。View Transitions とスクロール駆動アニメーションはプログレッシブ（対応時に使用、それ以外は JS）。サーバー（SSR）での import は何もしません。`baselineReport()` で確認できます。
+
+## ドキュメント
+
+- [API リファレンス](./docs/API.md)（英語）— 全エクスポート・オプション・`data-sa-*` 属性
+- [プリセット一覧](./docs/presets.md)（全 214 種）
+- [コンポーネント](./docs/components.md)（全 `<usa-*>` 要素・属性・イベント）
+- [フレームワークと SSR](./docs/frameworks-ssr.md) · [Windows アプリ](./docs/windows-apps.md) · [ハイブリッドアプリ](./docs/hybrid-apps.md)
+- [モーショントークン](./docs/motion-tokens.md) · [AOS からの移行](./docs/migration-from-aos.md) · [GSAP ScrollTrigger からの移行](./docs/migration-from-gsap-scrolltrigger.md)
+- [デモ](./demo/index.html)（全プリセットをクリックで再生）
+
+## アップグレード
+
+- `use-scroll-animate` から：`npm i motionary` を実行し、import と CDN URL の `use-scroll-animate` を `motionary` に置き換えるだけです（旧パッケージ名も同じリリースを継続）。
+- [6.0 へのアップグレード](./docs/upgrading-6.md)（`npx usa-codemod-6`）· [5.0](./docs/upgrading-5.md)（`npx usa-codemod-5`）· [4.0](./docs/upgrading-4.md) · [3.0](./docs/upgrading-3.md) · [2.0](./docs/deprecations.md)
+- [変更履歴](./CHANGELOG.md)
+
+## ロードマップ
+
+7.0 まで 1 バージョン 1 PR — パーティクルと流体、テキスト効果、光と質感、3D シーン、モーフィング、トランジション、天気、インタラクティブ物理：[docs/ROADMAP.md](./docs/ROADMAP.md)。
+
+## コントリビュートとライセンス
+
+Issue と PR を歓迎します — [CONTRIBUTING.md](./CONTRIBUTING.md) を参照。MIT © HarrisonCN — [LICENSE](./LICENSE)。