@topy-ai/maggie 0.8.15 → 0.8.17

package/references/web-animation-patterns.md

@@ -25,7 +25,8 @@ sequenced, scroll-driven work.
 gsap.registerPlugin(ScrollTrigger);
 const tl = gsap.timeline({ defaults: { ease: "power3.out", duration: 0.6 } });
 tl.from(".hero h1", { y: 40, opacity: 0 })
-  .from(".hero p",  { y: 24, opacity: 0 }, "-=0.3");   // overlap previous by 0.3s
+  .from(".hero p",  { y: 24, opacity: 0 }, "-=0.3")    // overlap previous by 0.3s
+  .from(".hero a",  { opacity: 0 }, "<");              // "<"/">" = start/end of prev tween
 gsap.from(".card", {
   scrollTrigger: { trigger: ".card", start: "top 80%", once: true },
   y: 32, opacity: 0, stagger: 0.08,
@@ -35,6 +36,10 @@ gsap.from(".card", {
 GSAP including all former Club plugins is 100% free for commercial use, but it is a
 proprietary license, not open source — flag it before bundling. CDN:
 `cdn.jsdelivr.net/npm/gsap@3.15/dist/gsap.min.js`.
+*Source note:* the `0.6`/`power3.out` above are our **house** defaults, not GSAP's
+(its own tween defaults are `0.5`/`power1.out` = quad); don't attribute them to GSAP.
+Parameterized ease strings — `"elastic.out(1,0.5)"`, `"back.out(1.7)"`,
+`"steps(12)"` — author a bespoke curve as a string.
 **Reach for it when:** a page needs a real timeline (chained, overlapping steps) or
 scroll-scrubbed sequencing beyond a one-shot reveal. Overkill for simple fades.
 
@@ -45,13 +50,17 @@ springs, `scroll()`, `inView()`, layout transitions.
 ```js
 import { animate, inView, scroll, stagger } from "motion";
 animate("#box", { x: 100, opacity: 1 }, { type: "spring", stiffness: 300, damping: 30 });
-inView(".card", (el) => { animate(el, { opacity: 1, y: 0 }); }, { amount: 0.3 });
+inView(".card", (el) => { animate(el, { opacity: 1, y: 0 }); }, { amount: "some" });
+// inView idiom is amount:"some"|"all" (a number works too) + margin (→ rootMargin)
 // React: <motion.div initial={{opacity:0,y:24}} whileInView={{opacity:1,y:0}} viewport={{once:true}}/>
 ```
 **License: MIT** (core; a paid "Motion+" add-on exists but isn't required).
 **Reach for it when:** the project is already React/Vue, or you want springs +
 scroll + inView from one small MIT lib. `inView` is a clean IntersectionObserver
-wrapper — our preferred engine when a dependency is acceptable.
+wrapper — our preferred engine when a dependency is acceptable. `motion/mini` is a
+WAAPI-only subset for the smallest payload. Spring also takes a **designer mode**
+`{ visualDuration, bounce }` (settle-time + bounciness, SwiftUI-style) instead of raw
+`stiffness/damping` — expose that to non-engineers (see the Spring pattern below).
 
 ### anime.js (juliangarnier/anime) — v4
 Small, elegant timeline/stagger/easing lib. V4 is ESM tree-shakable.
@@ -61,9 +70,14 @@ animate(".square", {
   x: 320, rotate: { from: -180 }, duration: 1250,
   delay: stagger(65, { from: "center" }), ease: "inOutQuint",
 });
+// 2D ripple from a grid cell (v4): delay: stagger(60, { grid: [cols, rows], from: "center" })
 ```
-**License: MIT.** **Reach for it when:** you want expressive staggers/keyframes
-lighter than GSAP and don't need ScrollTrigger-grade scroll control.
+**License: MIT** (v4: ESM, per-feature export subpaths — `animejs`, `animejs/stagger`,
+…; exports `animate, stagger, createTimeline, createTimer, createSpring, onScroll`,
+`eases/utils/svg/text`). **Reach for it when:** you want expressive staggers/keyframes
+lighter than GSAP and don't need ScrollTrigger-grade scroll control. Stagger vocabulary
+is rich: `from:'first'|'center'|'last'|'random'|index`, `grid:[x,y]`, `axis`,
+`reversed`, and an `ease` (even a spring) across the stagger.
 
 ### lottie-web (airbnb/lottie-web)
 Plays **Lottie JSON** (vector animations exported from After Effects via Bodymovin)
@@ -75,10 +89,16 @@ const anim = lottie.loadAnimation({
 });
 anim.playSegments([0, 60], true);          // play part of the timeline
 anim.setSpeed(1); anim.pause();
+lottie.freeze();                           // GLOBAL pause of every instance (tab hidden)
 ```
 **License: MIT.** **Reach for it when:** a designer delivers an AE/Lottie file and
 you need a crisp, scalable, small looped illustration (see §2 Lottie workflow).
-Default to `renderer: "svg"`; switch to `canvas` for heavy/many-layer files.
+Default to `renderer: "svg"`; switch to `canvas` for heavy/many-layer files. For a
+small payload load the **`lottie_light`** build (SVG-only, no expressions). Perf/sync
+hooks worth using: `progressiveLoad`, `setSubframe(false)`, and the fine-grained events
+`enterFrame`/`loopComplete`/`segmentStart`. `freeze()/unfreeze()` are **global**
+(all instances); per-instance use `pause`/`goToAndStop`. No built-in reduced-motion —
+gate it yourself.
 
 ### rlottie (Samsung/rlottie)
 Native (C++) Lottie renderer — the runtime behind Lottie on native/embedded (not a
@@ -117,20 +137,26 @@ Animate-on-scroll via HTML data-attributes + a prebuilt CSS set.
      data-aos-once="true" data-aos-anchor-placement="top-center"></div>
 <script>AOS.init({ once: true, duration: 800, easing: "ease-out-cubic" });</script>
 ```
-**License: MIT.** Uses IntersectionObserver internally. **Reach for it when:** a
-no-JS-authoring team wants declarative scroll reveals fast. For our output we
-usually hand-roll the same effect (§2) rather than ship AOS, but its attribute
-vocabulary (`fade-up`, `once`, per-element delay/offset) is the pattern to copy.
+**License: MIT.** **Correction (source-verified, v3.0.0-beta.6):** this release does
+**not** use IntersectionObserver — it is classic **scroll + `lodash.throttle`**
+(`throttleDelay:99`); the only observer is a MutationObserver for auto-refresh on DOM
+injection. So copy its attribute *vocabulary* (`fade-up`, `once`, per-element
+delay/offset/anchor-placement), but do **not** credit it for observer efficiency — our
+hand-rolled reveal (§2) with a real IntersectionObserver is the better engine.
+**Reach for it when:** a no-JS-authoring team wants declarative scroll reveals fast.
 
 ### typed.js (mattboldt/typed.js)
 Typewriter effect.
 ```js
 const typed = new Typed("#el", { strings: ["First.", "& second."], typeSpeed: 50, backSpeed: 30, loop: true });
 ```
-**License: GPL — flag it.** GNU GPL, not MIT. Do **not** bundle into proprietary
-output; reimplement the ~20-line effect yourself (or use a permissive alt) if you
-need typing. **Reach for the pattern when:** a hero rotates through phrases. Keep it
-short, respect reduced-motion (render the final string statically).
+**License: GPL-3.0 — flag it** (source-verified; the repo also ships paid
+`LIMITED`/`UNLIMITED_COMMERCIAL_LICENSE.md` with a Stripe link — a paid escape from
+copyleft). Do **not** bundle into proprietary/client output; reimplement the ~20-line
+effect yourself (or buy the commercial license). It also has **zero** reduced-motion
+handling (grep-confirmed) — you must gate it. **Reach for the pattern when:** a hero
+rotates through phrases. Keep it short, respect reduced-motion (render the final string
+statically).
 
 ### tsparticles (tsparticles/tsparticles)
 Config-driven particle backgrounds/confetti.
@@ -143,6 +169,27 @@ await tsParticles.load({ id: "tsparticles", options: {
 **License: MIT.** **Reach for it when:** a hero wants a subtle particle/constellation
 backdrop or a celebratory confetti burst. Use sparingly — it's a performance and
 taste liability; cap particle count, pause offscreen, disable on reduced-motion.
+Source notes: v3+ `load()` takes **one object** `{ id, element?, options?, url? }`
+(positional form gone); 22 presets (`confetti`/`fireworks`/`snow`/`stars`/`links`/…)
+are one-line `preset:` strings; ship the **slim** bundle + only the `@tsparticles/*`
+feature packages you use. It also ships CLI scaffolders (`npm create tsparticles@latest`,
+`create-confetti`) and an **MCP server** — precedent for an agent-driven particle config.
+(Legacy origin: `particles.js` v2 — single-file, unmaintained, snake_case schema; use
+tsparticles instead, which bundles a `pjs` compat shim.)
+
+### mojs (@mojs/core)
+Motion-graphics toolbelt for the web — the one lib here built for **celebratory point
+bursts / success micro-interactions** (likes, add-to-cart, CTA confirm), a genuine gap
+the others don't fill. Actively maintained.
+```js
+import { Burst, Shape } from "@mojs/core";
+new Burst({ left: x, top: y, count: 8, radius: { 0: 60 },
+  children: { shape: "circle", fill: "#e94560", duration: 700 } }).play();
+```
+**License: MIT.** Also `ShapeSwirl`, `Html` (tween real DOM), `Timeline`, `stagger`,
+custom eases via `easing.path("M0,100 ...")` / `easing.bezier()`. **Reach for it when:**
+a discrete interaction deserves a tactile burst — keep it to a single gesture, gate on
+reduced-motion.
 
 ### rive (rive-app/rive-runtime)
 Interactive vector animations driven by **state machines** (inputs → states), not
@@ -161,23 +208,32 @@ drives animation state) — interactive mascots, animated toggles. Heavier workf
 Animates SVG stroke draw-on ("self-drawing" line art).
 ```js
 new Vivus("my-svg", { type: "oneByOne", duration: 200, start: "inViewport" }, cb);
-// type: delayed | sync | oneByOne | scenario ; start: inViewport | manual | autostart
+// type: delayed|sync|async|nsync|oneByOne|scenario|scenario-sync ; start: inViewport|manual|autostart
+v.setFrameProgress(0.5);   // scrub draw 0..1 (drive from scroll); play(-1) rewinds
 ```
-**License: MIT.** **Reach for it when:** a logo/icon/diagram should draw itself in.
-The same effect is achievable with CSS `stroke-dasharray`/`stroke-dashoffset` — use
+**License: MIT.** Timing fns are statics (`Vivus.EASE_OUT`, custom `function(x)`), set
+whole (`animTimingFunction`) or per-path (`pathTimingFunction`); per-path
+`data-delay/duration`, `data-vivus-ignore`; bundles `pathformer` (primitives → path).
+**Reach for it when:** a logo/icon/diagram should draw itself in — and, via
+`setFrameProgress(0..1)`, a **scroll-linked** draw-on (extends §2's one-shot draw). The
+same effect is achievable with CSS `stroke-dasharray`/`stroke-dashoffset` — use
 that for one element, Vivus when orchestrating many paths.
 
 ### lenis (darkroomengineering/lenis)
 Smooth-scroll normalizer (momentum/eased scrolling). Already referenced by
 `maggie-clone`.
 ```js
-const lenis = new Lenis({ autoRaf: true });     // or drive lenis.raf(t) in your own rAF
-lenis.on("scroll", (e) => {/* sync scroll-linked effects */});
+const lenis = new Lenis({ autoRaf: true });     // DEFAULT is autoRaf:false → drive lenis.raf(t) yourself
+lenis.on("scroll", (e) => {/* e is the whole Lenis instance: e.scroll/.velocity/.progress/.direction */});
 ```
 **License: MIT.** **Reach for it when:** the design calls for premium eased scrolling
 and you pair it with scroll-triggered motion (commonly `lenis.raf` + GSAP
-ScrollTrigger). Accessibility caveat: disable/reduce under `prefers-reduced-motion`;
-never trap or override scroll in a way that breaks keyboard/anchor jumps.
+ScrollTrigger). **Source-verified defaults:** `lerp` is `0.1` (not 0.075 — that's
+`syncTouchLerp`), `autoRaf` defaults **false**, and `respectReducedMotion` is a
+first-class option (defaults true, falls back to native scroll via matchMedia).
+Attribute opt-outs: `data-lenis-prevent[-vertical|-horizontal]`. Accessibility caveat:
+keep `respectReducedMotion` on; never trap scroll in a way that breaks keyboard/anchor
+jumps.
 
 ### barba.js (barbajs/barba)
 SPA-style page transitions over MPAs: intercepts navigation, animates the old
@@ -203,6 +259,11 @@ return <animated.div style={styles}>…</animated.div>;
 ```
 **License: MIT.** **Reach for it when:** a React project wants physics-based
 (not duration-based) motion. For non-React, Motion's `spring` covers the same need.
+**Source-verified presets** (`tension`/`friction`[/`mass`]): default `{170,26}`,
+`gentle {120,14}`, `wobbly {180,12}`, `stiff {210,20}`, `slow {280,60}`,
+`molasses {280,120}`. The `AnimationConfig` also exposes a **designer-friendly**
+vocabulary — `frequency` + `damping(ratio)` (tension/friction derived from them),
+plus `clamp`, `bounce`, `decay` — prefer these when writing a config for non-engineers.
 
 ### animate.css (animate-css/animate.css)
 Prebuilt CSS keyframe classes (`animate__animated animate__fadeInUp`).
@@ -211,9 +272,20 @@ Prebuilt CSS keyframe classes (`animate__animated animate__fadeInUp`).
 ```
 **License: Hippocratic License 2.1 — flag it (NOT MIT).** An ethical-source license
 with use restrictions; not OSI-approved. Treat as a caution for commercial bundling;
-the keyframe recipes (`fadeInUp`, durations, timing) are fine to **reimplement**
-yourself. **Reach for the patterns when:** you want a quick named-entrance
-vocabulary — but author your own keyframes to stay license-clean.
+the keyframe recipes (`fadeInUp`, the `back_*` entrance/exit family, durations, timing)
+are fine to **reimplement** yourself. Two patterns worth copying wholesale: its
+**3-custom-prop timing system** (`--animate-duration` / `--animate-delay` /
+`--animate-repeat` + `calc()` utility multipliers) and its built-in **reduced-motion /
+print kill-switch** (collapses to 1ms and forces `*Out` animations to opacity 0 so
+content never sticks hidden). **Reach for the patterns when:** you want a quick
+named-entrance vocabulary — but author your own keyframes to stay license-clean.
+
+### Out of scope — pixijs (pixijs/pixijs)
+A WebGL/WebGPU **2D renderer**, not an animation engine: it ships no tween/easing (its
+`Ticker` gives only `deltaTime`). The particle/shader libs build *on* it; for standard
+DOM/CSS marketing motion it's out of scope — reach for it only for a heavy custom
+canvas scene, and bring your own tween (GSAP/Motion). (Notable: it ships 26 first-party
+`SKILL.md` agent skills — precedent for a library shipping its own skills.)
 
 ### Category O (offline / desktop, NOT web)
 - **synfig** (synfig/synfig) — desktop 2D vector animation studio. **GPL-3.0.**
@@ -236,14 +308,28 @@ Default to expressive ease-out curves, never browser defaults (`ease`, `linear`,
 color/opacity 300ms (never < 200ms). Other good ones: `cubic-bezier(0.16,1,0.3,1)`
 (ease-out-expo), `cubic-bezier(0.34,1.56,0.64,1)` (gentle back/overshoot).
 Libs: GSAP eases, anime `inOut*`, Motion. **LP + DM.**
+*Custom eases as data:* when a bespoke curve is needed, author it as data rather than
+code — GSAP parameterized strings (`"back.out(1.7)"`), mojs `easing.path()`/`bezier()`,
+vivus custom `function(x)`, or a popmotion-style `mirror/reverse` of a base ease. Store
+the curve with the motion spec (see Theatre.js data model below).
 
 ### Spring physics
 Duration-less, physics-based motion — natural for interactive/hover and anything
 that should feel tactile. Config shape is universal: `{ stiffness, damping, mass }`
 (Motion: `type:"spring", stiffness:300, damping:30`; react-spring: `config.gentle`).
+For configs a non-engineer will touch, prefer the **designer vocabulary** both engines
+expose — Motion `{ visualDuration, bounce }`, react-spring `frequency` +
+`damping(ratio)` (settle-time + bounciness), rather than raw stiffness/damping.
 Libs: Motion `spring`, react-spring, GSAP (via plugins). **DM;** light touch on LP
 (mostly micro-interactions).
 
+### Burst / success micro-interaction
+A discrete gesture (like, add-to-cart, CTA confirm) earns a one-shot radial burst from
+the click point — one shape stamped into N transformed copies with an opacity ramp.
+Lib: mojs `Burst` (or a hand-rolled radial-stamp, same idea as the Lottie Repeater in
+[generative visuals](generative-visuals.md)). One gesture only; gate on reduced-motion.
+**LP (primary CTA) + DM.**
+
 ### Scroll-reveal via IntersectionObserver — never scroll listeners
 Elements rise ~32px and fade over 600–800ms, **once**, when they cross into view.
 Always IntersectionObserver (or a lib that wraps it); never an unthrottled `scroll`
@@ -349,7 +435,10 @@ illustration when a designer supplies the JSON.
 | auto-animate | MIT | |
 | AOS | MIT | |
 | typed.js | **GPL** | **Flag — don't bundle in proprietary output; reimplement.** |
-| tsparticles | MIT | |
+| tsparticles | MIT | v3+ single-object `load()`; ships CLI scaffolders + an MCP server. |
+| particles.js | MIT | Legacy v2, unmaintained — use tsparticles (`pjs` compat). |
+| mojs (@mojs/core) | MIT | Celebratory point bursts / success micro-interactions. |
+| pixijs | MIT | WebGL 2D **renderer**, no tween — out of scope for DOM motion. |
 | rive-runtime | MIT | Web runtime is `@rive-app/canvas`. |
 | vivus | MIT | |
 | lenis | MIT | |
@@ -371,9 +460,10 @@ state**, replayed by a tiny headless runtime (`@theatre/core`) against three.js,
 HTML/SVG, or any JS variable. The borrowable pattern is the **declarative keyframe
 document**, not the editor: store motion as JSON - a `sequence` with `length` +
 `subUnitsPerUnit` (an fps snap-grid) -> **tracks keyed by property path** ->
-**keyframes** each carrying `{ position, value, handles:[lx,ly,rx,ry],
-type:'bezier'|'hold' }` (per-keyframe bezier handles = per-segment easing baked into
-data; `value` may be non-numeric). Playback mirrors CSS: `play({ iterationCount,
+**keyframes** each carrying `{ id, position, value, handles:[lx,ly,rx,ry],
+connectedRight:boolean, type?:'bezier'|'hold' }` (per-keyframe bezier handles =
+per-segment easing baked into data; `type` is optional, defaults bezier; `value` may be
+non-numeric). Playback mirrors CSS: `play({ iterationCount,
 range, rate, direction:'alternateReverse' })`. Author a brand motion once, commit the
 JSON as a reusable asset, replay it deterministically with no editor shipped - the
 authoring story for `maggie-design-motion` (keep the motion *spec* as data, not
@@ -395,4 +485,9 @@ hero as `inputs -> conditions -> states` - declare inputs (`hovered:bool`,
 `scroll:0..1`, `clicked:trigger`), bind DOM events to them, and switch CSS/WAAPI/GSAP
 timelines by state rather than scripting each handler; a number input + interpolation
 gives scroll-linked response, random-picked idle transitions give a "living" element.
-(Rive's own MIT player is also a legitimate option.)
+(Rive's own MIT player is also a legitimate option.) Source-verified, the model is
+richer than the sketch above: any input source maps onto one **unified listener bus**
+(pointer/scroll/keyboard/gamepad/text/focus), transitions can be guarded by **app data**
+via **ViewModel data-binding conditions** (not just events), comparator ops are a full
+enum (`eq/neq/lt/gt/lte/gte`), and nested state machines compose — so "driven by data,
+not handlers" is the portable lesson for a browser reimplementation.