@topy-ai/maggie 0.8.10 → 0.8.12

package/references/generative-visuals.md

@@ -0,0 +1,90 @@
+# Generative visuals (creative coding)
+
+Patterns for generating marketing visuals in code - hero backgrounds, textures, 3D
+product shots, data-viz, and stylized images - distilled from the leading creative-
+coding libraries. We adopt **patterns, not code**. Output becomes a deliverable as a
+**still** (canvas/SVG export) or a **loop** (captured via
+[design-motion production](design-motion-production.md) Part C or
+[ffmpeg recipes](ffmpeg-recipes.md), then assembled in `maggie-video`). Determinism
+by seeding matches `maggie-spirit`'s philosophy: same seed -> same pixels.
+
+## Libraries
+
+| Library | What / model | Lang | License | Marketing fit |
+|---|---|---|---|---|
+| three.js | WebGL 3D: Scene + Camera + WebGLRenderer; `renderer.render(scene,camera)` in a loop | JS | MIT | 3D product spins, logo stings, depth-y hero backgrounds |
+| Babylon.js | Higher-level 3D engine (PBR, asset pipeline); heavier | JS/TS | Apache-2.0 | 3D product config; alt to three when its pipeline earns the weight |
+| react-three-fiber | three.js as React JSX (`<mesh><boxGeometry/>…`), `useFrame` | JS/TS | MIT | 3D on a React site |
+| p5.js | Canvas sketch: `setup()` once + `draw()` per frame; `random()/noise()` with `randomSeed()/noiseSeed()` | JS | **LGPL-2.1** | generative hero backgrounds, flow fields, noise art |
+| paper.js | Vector scene graph (Path/Group), boolean ops, hit-testing | JS | MIT | editable vector hero art, print-quality SVG |
+| two.js | One 2D API across SVG/Canvas/WebGL renderers | JS | MIT | vector art you want to export as SVG or capture from canvas |
+| rough.js | Hand-drawn/sketchy shapes; `{seed}` = reproducible | JS/TS | MIT | approachable hand-made brand style, doodle accents |
+| zdog | Pseudo-3D round/flat vector, designer-friendly | JS | MIT | cute 3D-ish icons, mascot/logo spins |
+| pts | Computational geometry (Space + Form + Pt) | TS/JS | Apache-2.0 | geometric/particle hero art |
+| hydra | Live-coded video synth (chained GLSL ops) | JS | **AGPL-3.0** | trippy animated backgrounds - **pattern only, do not ship its code** |
+| regl | Functional WebGL (stateless draw commands) | JS | MIT | custom shader backgrounds/gradients when three is overkill |
+| d3 | Data-driven SVG (scales + selections) | JS | ISC | bespoke infographics - but defer standard charts to the `dataviz` skill |
+| fogleman/primitive | Reproduce an image with N geometric primitives (CLI) | Go | MIT | stylize a product photo into abstract art (still or GIF) |
+| svg.js | Lightweight SVG DOM manipulation | JS | MIT | programmatic SVG icons/badges/dividers |
+| nannou | Rust creative framework (desktop) | Rust | MIT/Apache | note only - high-perf generative art in Rust |
+
+**License flags:** hydra is **AGPL-3.0**, p5 is **LGPL-2.1**, processing (non-core)
+is GPL - fine as *idea* sources, but do not vendor their code into shipped product;
+reimplement the pattern or use an MIT equivalent (two.js / pts / regl / svg.js).
+
+## Patterns and the deliverable path
+
+- **2D generative** (p5 / paper / two / rough / zdog / pts / svg.js): `setup()` once +
+  `draw()`/`update()` per frame. Use for brand-tinted hero/section backgrounds,
+  textures, doodle accents, geometric motifs. **Still:** SVG-capable libs serialize
+  their `<svg>` (crisp, editable, print-ready); canvas libs use `canvas.toDataURL()`
+  -> PNG. **Loop:** run the sketch headless and capture via design-motion Part C, or
+  in-browser with CCapture.js (MIT), then hand to `maggie-video`.
+- **3D** (three / babylon / r3f): Scene + Camera + Renderer; animate by frame index.
+  Product spins, 3D logo stings, depth-y backgrounds. **Still:**
+  `renderer.domElement.toDataURL()` (set `preserveDrawingBuffer:true`); **loop:** drive
+  by frame, capture as above. Prefer three/r3f (MIT); babylon only when needed.
+- **Data-viz** (d3): `d3-scale` + `d3-selection`; SVG is the native output. For
+  standard charts, **defer to the `dataviz` skill** (its palette/spec); pull in d3
+  only for bespoke marks (arc diagrams, force layouts, custom infographics).
+- **Live visuals** (hydra): chained feedback-graph ops -> animated GLSL. Renders to a
+  canvas -> capture -> `maggie-video`. **AGPL: idea only**; for an MIT shader
+  background use regl.
+- **Image -> primitives** (fogleman/primitive, MIT, Go CLI): stylize a photo into
+  abstract geometry.
+
+  ```bash
+  primitive -i input.png -o output.svg -n 100 -m 1
+  # -n shapes (50-200); -m mode (1 triangle,2 rect,3 ellipse,4 circle,6 beziers,8 polygon);
+  # output type by extension: PNG/JPG (raster), SVG (vector), GIF (animated, needs ImageMagick)
+  ```
+
+  **Still:** PNG/SVG directly; **loop:** `.gif` or `%d`-numbered PNG frames ->
+  `maggie-video`. It is randomized (no seed): generate once and **store the artifact**;
+  do not regenerate on every build.
+
+## Determinism
+
+p5 `randomSeed()/noiseSeed()`, rough.js `{seed}`, and a seeded PRNG in place of
+`Math.random` give byte-reproducible stills; the frame-index/virtual-clock rule from
+[programmatic video](programmatic-video.md) gives reproducible motion. `primitive`
+and `hydra` are non-deterministic - capture and store their output as a fixed asset.
+
+## Placement
+
+- **maggie-spirit** owns seeded brand marks/characters; borrow the 2D-canvas sketch
+  model and seed discipline for flat-vector mark construction (zdog/two.js/rough).
+  Generative *backgrounds/scenes* do not live here.
+- **maggie-design** owns generative hero backgrounds, section textures, 3D product
+  shots and image stylization as page/brand visuals; it points at this reference and
+  cross-links design-motion / `maggie-video` for capture-to-deliverable.
+- **Reference-only:** d3 (defer to `dataviz`), hydra (AGPL, idea only), regl, babylon,
+  nannou/processing/openFrameworks (desktop notes), svg.js.
+
+## Credits
+
+Patterns adapted (not code) from three.js, p5.js, d3, paper.js, two.js, rough.js,
+zdog, pts, hydra, regl, Babylon.js, react-three-fiber, fogleman/primitive, svg.js,
+nannou - licenses in the table above. Capture pipeline: see
+[programmatic video](programmatic-video.md), [design-motion production](design-motion-production.md),
+[ffmpeg recipes](ffmpeg-recipes.md).

package/references/image-recipes.md

@@ -0,0 +1,89 @@
+# Image recipes
+
+The distilled, correct image-processing command layer for marketing assets, used by
+`maggie-image`. These are the commands `maggie_image.py` generates. Distilled from
+ImageMagick, sharp, svgo, resvg, squoosh and imagemin (reference library category P).
+We **invoke binaries at arm's length** (adopt defaults, not code).
+
+**Tool posture.** ImageMagick (`magick` on IM7, else `convert`) is almost always
+present and covers nearly every raster op, so it is the **primary** path; dedicated
+tools (svgo, resvg, cwebp, avifenc, pngquant) are the **better-quality alternative
+used automatically when installed**. Web-delivery quality defaults follow sharp/
+squoosh: JPEG/WebP ~80, AVIF ~50. OG/social are **cover-cropped**; logos **pad**.
+Strip metadata on anything public (privacy + bytes).
+
+## Resize + fit (the most-used op)
+
+```bash
+# cover / crop to exactly WxH (fills the frame, center-crop)
+convert in.jpg -strip -resize 1200x630^ -gravity center -extent 1200x630 -quality 82 out.jpg
+# contain / letterbox with a pad color
+convert in.jpg -strip -resize 1200x630 -background '#ffffff' -gravity center -extent 1200x630 out.jpg
+# downscale-only (never enlarge): -resize 1200x630>
+```
+
+sharp's smart crop (`fit:'cover', position:attention`) avoids cutting off a face;
+ImageMagick has no equal, so for portraits prefer sharp when available.
+
+## WebP / AVIF (file-size wins)
+
+```bash
+convert in.png -strip -quality 80 -define webp:method=6 out.webp   # or: cwebp -q 80 -m 6 in.png -o out.webp
+convert in.png -strip -quality 50 out.avif                         # or: avifenc -s 6 --min 20 --max 40 in.png out.avif
+```
+
+## Channel / OG presets
+
+Cover-crop to the target: OG 1200x630, Twitter 1600x900, square 1080x1080, story/reel
+1080x1920, landscape 1920x1080, LinkedIn 1200x627, Pinterest 1000x1500. Same command
+as cover resize with the preset size, `-strip -quality 82`.
+
+## Favicon + OG set
+
+```bash
+convert in.png -define icon:auto-resize=64,48,32,16 favicon.ico      # multi-res .ico
+convert in.png -strip -resize 180x180 apple-touch-icon.png          # + 16/32/48/192/512 PNGs
+```
+
+## Strip metadata / compress
+
+```bash
+convert in.jpg -strip out.jpg                                        # drop EXIF/GPS/ICC
+convert in.jpg -strip -interlace Plane -quality 82 out.jpg           # progressive JPEG
+pngquant --quality 60-82 --strip --output out.png in.png            # lossy PNG (best); IM fallback: -colors 256 -define png:compression-level=9
+```
+
+## SVG optimize / render
+
+```bash
+svgo --multipass -i in.svg -o out.svg      # keeps viewBox + title (responsive + a11y). If svgo absent, leave the SVG alone - never rasterize as a substitute.
+resvg -w 512 in.svg out.png                # best-fidelity SVG -> PNG (or rsvg-convert -w 512); IM fallback (-background none -density 384) is lower fidelity
+```
+
+## Montage / contact sheet (carousels, screenshot grids)
+
+```bash
+montage a.png b.png c.png -tile 3x -geometry 400x400+10+10 -background '#ffffff' sheet.jpg
+```
+
+## The CLI
+
+`maggie_image.py` generates each command above (and runs it with `--run` when the
+tool is on PATH; `--force-im` forces the ImageMagick path). It detects IM6 `convert`
+vs IM7 `magick`:
+
+```bash
+maggie tool maggie_image.py social --input hero.png --output og.jpg --preset og
+maggie tool maggie_image.py --run webp --input hero.png --output hero.webp --quality 80
+maggie tool maggie_image.py --run favicon --input logo.png --out-dir public/
+maggie tool maggie_image.py svg2png --input logo.svg --output logo.png --width 512
+maggie tool maggie_image.py presets
+```
+
+## Licenses
+
+Invoked at arm's length: ImageMagick (permissive), SVGO (MIT), resvg (MIT/Apache),
+sharp (Apache-2.0), squoosh codecs (Apache-2.0), imagemin (MIT), cwebp/avifenc
+(BSD). **Avoid vendoring code from** Upscayl (AGPL-3.0) - for AI upscaling invoke the
+separate `realesrgan-ncnn-vulkan` binary instead. sharp/squoosh quality defaults are
+adopted as the preset numbers.

package/references/video-timeline-model.md

@@ -97,16 +97,18 @@ shape renders through ffmpeg without any GPL engine.
 
 `maggie_video.py compile --spec timeline.json` compiles this model into one ffmpeg
 `filter_complex` command (printed; run with `--run`). Supported today: a main video
-track of clips (video/image) fit `cover`/`contain` to the canvas, hard-cut `concat`
-or sequential `crossfade` (from `transitions`), **ken-burns on image clips**
+track of clips (video/image) fit `cover`/`contain`, hard-cut `concat` or sequential
+`crossfade` (from `transitions`), **ken-burns on image *and* video clips**
 (`"kenBurns":{"zoom":"in"|"out","amount":0.12}` or a `zoom` effect, via `zoompan`),
 image/text/caption overlays with `position`+`duration` timing and `rect` placement,
-**text opacity keyframes** (`effects:[{"type":"opacity","keyframes":[{"t","v"}...]}]`,
-via a drawtext `alpha` expression), and an `audio[]` mix with per-track
-`position`/`gain` plus `loudnorm`. Output is bounded to the computed video duration
-and uses the shared web-safe profile. Not compiled yet (emitted as `# NOTE:` lines):
-ken-burns on *video* clips, non-opacity overlay effects, and sidechain ducking - set
-static values or use a programmatic engine for those.
+**overlay keyframes** - opacity (`effects:[{"type":"opacity","keyframes":[{"t","v"}]}]`
+-> drawtext/alpha), **move/slide** (`{"type":"move","x":[{t,v}],"y":[{t,v}]}` ->
+animated x/y), and **zoom on sized image overlays** (`{"type":"zoom","keyframes":...}`
+with `rect` w+h) - and an `audio[]` mix with per-track `position`/`gain`, **sidechain
+ducking** (`"ducking":{"under":"<asset>"}` -> `sidechaincompress`), plus `loudnorm`.
+Output is bounded to the computed video duration and uses the shared web-safe profile.
+Remaining programmatic-engine territory (emitted as `# NOTE:` lines): animated text
+font size and free-form overlay shrink/pop below 1x.
 
 ```bash
 maggie tool maggie_video.py compile --spec timeline.json          # print the command

package/references/web-animation-patterns.md

@@ -0,0 +1,364 @@
+# Web / UI animation patterns
+
+Engine-neutral motion vocabulary for marketing web pages, distilled from the leading
+open-source animation libraries. We adopt **patterns and per-library guidance, not
+code** — we rarely ship these libraries; we copy the technique (the eases, the
+IntersectionObserver reveal, the spring config, the Lottie workflow). Feeds
+`maggie-landing-page` (B7 motion + the mandatory tagline reveal) and
+`maggie-design-motion` (its *website* context).
+
+Rule of thumb: a marketing page needs **CSS transitions + IntersectionObserver +
+one tiny helper** far more often than a 30KB animation engine. Reach for a library
+only when the pattern below says so. Default is zero-dependency.
+
+---
+
+## 1. The libraries
+
+Each entry: what it is · core API shape (real snippet) · license · when to reach for it.
+
+### GSAP (greensock/GSAP) — v3.15
+Framework-agnostic JS animation engine: tweens, timelines, eases, plugins
+(ScrollTrigger, SplitText, MorphSVG, Flip, MotionPath). The gold standard for
+sequenced, scroll-driven work.
+```js
+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
+gsap.from(".card", {
+  scrollTrigger: { trigger: ".card", start: "top 80%", once: true },
+  y: 32, opacity: 0, stagger: 0.08,
+});
+```
+**License: custom "Standard no-charge license" (NOT MIT/OSI).** As of 2024 (Webflow)
+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`.
+**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.
+
+### Motion / framer-motion (motiondivision/motion)
+Hybrid engine: a tiny imperative `animate()` for vanilla JS plus declarative
+`<motion.div>` for React/Vue. Uses the native WAAPI where possible (GPU, 120fps),
+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 });
+// 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.
+
+### anime.js (juliangarnier/anime) — v4
+Small, elegant timeline/stagger/easing lib. V4 is ESM tree-shakable.
+```js
+import { animate, stagger } from "animejs";
+animate(".square", {
+  x: 320, rotate: { from: -180 }, duration: 1250,
+  delay: stagger(65, { from: "center" }), ease: "inOutQuint",
+});
+```
+**License: MIT.** **Reach for it when:** you want expressive staggers/keyframes
+lighter than GSAP and don't need ScrollTrigger-grade scroll control.
+
+### lottie-web (airbnb/lottie-web)
+Plays **Lottie JSON** (vector animations exported from After Effects via Bodymovin)
+in the browser as SVG/canvas/HTML.
+```js
+const anim = lottie.loadAnimation({
+  container: el, renderer: "svg", loop: true, autoplay: true,
+  path: "hero.json",                       // or animationData: <obj>
+});
+anim.playSegments([0, 60], true);          // play part of the timeline
+anim.setSpeed(1); anim.pause();
+```
+**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.
+
+### rlottie (Samsung/rlottie)
+Native (C++) Lottie renderer — the runtime behind Lottie on native/embedded (not a
+web lib). Category O. **License: MIT** (mostly; some vendored parts differ, see
+COPYING). **Reach for it when:** the same Lottie JSON must also play in a native app
+(our Expo/RN surfaces) — same asset, native renderer. On web it's lottie-web.
+
+### theatre.js (theatre-js/theatre)
+In-browser motion-design **editor**: scrub a timeline, keyframe any JS object's
+props, then play the saved sequence at runtime via `@theatre/core`.
+```js
+import { getProject } from "@theatre/core";
+const sheet = getProject("Hero").sheet("Intro");
+const obj = sheet.object("Logo", { x: 0, opacity: 0 });
+obj.onValuesChange((v) => { el.style.transform = `translateX(${v.x}px)`; el.style.opacity = v.opacity; });
+sheet.sequence.play({ iterationCount: 1 });
+```
+**License: Apache-2.0.** **Reach for it when:** a complex bespoke sequence is easier
+to hand-author on a timeline than in code. Niche for marketing pages; mostly a
+design-time tool. Note for `maggie-design-motion`, not landing pages.
+
+### auto-animate (formkit/auto-animate)
+Zero-config: one call and children added/removed/moved animate automatically.
+```js
+import autoAnimate from "@formkit/auto-animate";
+autoAnimate(document.getElementById("list"));   // React: const [ref] = useAutoAnimate()
+```
+**License: MIT.** **Reach for it when:** lists, filters, accordions, or reordering UI
+need smooth transitions with no keyframes. Great low-effort polish for interactive
+sections (pricing toggles, FAQ, filtered galleries).
+
+### AOS (michalsnik/aos)
+Animate-on-scroll via HTML data-attributes + a prebuilt CSS set.
+```html
+<div data-aos="fade-up" data-aos-delay="50" data-aos-duration="800"
+     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.
+
+### 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).
+
+### tsparticles (tsparticles/tsparticles)
+Config-driven particle backgrounds/confetti.
+```js
+await tsParticles.load({ id: "tsparticles", options: {
+  background: { color: "#0d1117" },
+  particles: { number: { value: 60 }, move: { enable: true } },
+}});
+```
+**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.
+
+### rive (rive-app/rive-runtime)
+Interactive vector animations driven by **state machines** (inputs → states), not
+just linear playback. `rive-runtime` is the C++ core; on web you use `@rive-app/canvas`.
+```js
+import { Rive } from "@rive-app/canvas";
+const r = new Rive({ src: "button.riv", canvas, autoplay: true,
+  stateMachines: "State Machine 1", onLoad: () => r.resizeDrawingSurfaceToCanvas() });
+r.stateMachineInputs("State Machine 1").find(i => i.name === "hover").value = true;
+```
+**License: MIT.** **Reach for it when:** an element must *react* (hover/click/scroll
+drives animation state) — interactive mascots, animated toggles. Heavier workflow
+(needs the Rive editor); overkill for passive decoration — prefer Lottie for that.
+
+### vivus (maxwellito/vivus)
+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
+```
+**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
+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 */});
+```
+**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.
+
+### barba.js (barbajs/barba)
+SPA-style page transitions over MPAs: intercepts navigation, animates the old
+container out and the new one in (no full reload).
+```js
+barba.init({ transitions: [{
+  name: "fade",
+  leave: ({ current }) => gsap.to(current.container, { opacity: 0 }),
+  enter: ({ next })    => gsap.from(next.container, { opacity: 0 }),
+}]});
+// markup: <main data-barba="wrapper"><section data-barba="container" data-barba-namespace="home">
+```
+**License: MIT.** **Reach for it when:** a multi-page marketing site wants seamless
+cross-page transitions. Needs care for SEO/analytics/scroll-restore; often more than
+a landing page needs.
+
+### react-spring (pmndrs/react-spring)
+Spring-physics animation for React (hooks).
+```js
+import { animated, useSpring } from "@react-spring/web";
+const styles = useSpring({ from: { opacity: 0, y: 24 }, to: { opacity: 1, y: 0 } });
+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.
+
+### animate.css (animate-css/animate.css)
+Prebuilt CSS keyframe classes (`animate__animated animate__fadeInUp`).
+```html
+<h1 class="animate__animated animate__fadeInUp">Hi</h1>
+```
+**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.
+
+### Category O (offline / desktop, NOT web)
+- **synfig** (synfig/synfig) — desktop 2D vector animation studio. **GPL-3.0.**
+- **friction** (friction2d/friction) — desktop motion-graphics/vector animator.
+  **GPL-3.0.** Sparse docs.
+Both are authoring tools, not runtimes. Note as offline/GPL; they can *produce*
+assets (e.g. exported video/sequences) but nothing here ships to the web.
+
+---
+
+## 2. Engine-neutral pattern set (what we actually adopt)
+
+For each pattern: the technique, which libs embody it, and where it belongs
+(**LP** = `maggie-landing-page`, **DM** = `maggie-design-motion` website context).
+
+### Eased entrances — the good cubic-beziers
+Default to expressive ease-out curves, never browser defaults (`ease`, `linear`,
+`ease-in-out`). House base curve: `cubic-bezier(0.22, 1, 0.36, 1)` ("ease-out-quint",
+~500ms for layout/position; GSAP's `power3/power4.out` equivalent). Hover
+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.**
+
+### 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`).
+Libs: Motion `spring`, react-spring, GSAP (via plugins). **DM;** light touch on LP
+(mostly micro-interactions).
+
+### 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`
+listener. Engine-neutral baseline (no dependency):
+```js
+const io = new IntersectionObserver((entries) => {
+  for (const e of entries) if (e.isIntersecting) {
+    e.target.classList.add("in");           // CSS transitions transform+opacity
+    io.unobserve(e.target);                 // once
+  }
+}, { threshold: 0.2, rootMargin: "0px 0px -10% 0px" });
+document.querySelectorAll("[data-reveal]").forEach((el) => io.observe(el));
+```
+Libs that embody it: Motion `inView`, AOS (`data-aos` + `once`), GSAP ScrollTrigger
+(`once:true`). **LP (core) + DM.**
+
+### Stagger
+Sequence a group so items arrive one after another (reading order), stepped
+~60–80ms, capped (~400ms total for menus). Libs: GSAP `stagger`, anime
+`stagger(65,{from:"center"})`, Motion `stagger`. Hand-rolled: per-item
+`transition-delay: calc(var(--i) * 60ms)`. **LP (menu entrance, card grids) + DM.**
+
+### SVG draw-on
+Line art draws itself via `stroke-dasharray`/`stroke-dashoffset` animated to 0.
+Libs: Vivus (`type:"oneByOne"`), or pure CSS for a single path. **DM (logos,
+diagrams);** occasional LP hero accent.
+
+### Typing
+Rotate/type phrases in a hero. Pattern: type → pause → delete → next, respect
+reduced-motion by rendering the final string. Lib: typed.js (**GPL — reimplement**,
+don't bundle). **LP (hero headline variants) + DM.**
+
+### Page transitions + smooth scroll
+Cross-page: animate container out/in instead of a hard reload (barba.js, or a
+framework's view-transitions). Smooth scroll: eased momentum scrolling (lenis),
+commonly paired with scroll-triggered motion (`lenis.raf` → GSAP ScrollTrigger).
+**DM / full-site builds;** a single landing page rarely needs barba. Lenis already
+used by `maggie-clone`.
+
+### Particles
+Subtle generative backdrop or confetti. Lib: tsparticles (config: `particles.number`,
+`move`, `background`). Use sparingly; cap count, pause offscreen, kill on
+reduced-motion. **LP hero (optional accent) + DM.**
+
+### The Lottie workflow
+Pipeline: **design in After Effects → export with Bodymovin → `.json` →** play with
+**lottie-web** on web / **rlottie** on native (same JSON asset, two renderers).
+```js
+lottie.loadAnimation({ container: el, renderer: "svg", loop: true, autoplay: true, path: "hero.json" });
+```
+**When to use Lottie vs code vs looped video:**
+- **Lottie** — designer-authored vector illustration/icon motion; scalable, crisp,
+  small, loopable, recolorable, interactive (segments/speed). The default for
+  "animated illustration." Prefer `renderer:"svg"`; use `canvas` for heavy files.
+- **Code (CSS/GSAP/Motion)** — UI motion tied to the DOM: entrances, hovers,
+  scroll reveals, state changes. Anything that must respond to layout/interaction.
+- **Looped video (mp4/webm)** — photographic/complex/3D content that isn't vector
+  and doesn't need interaction or recolor. Heaviest payload; provide a poster and
+  `prefers-reduced-motion` fallback. (See `references/programmatic-video.md`.)
+Libs: lottie-web (web), rlottie (native). **DM (primary);** LP for a hero/spot
+illustration when a designer supplies the JSON.
+
+---
+
+## 3. Performance & accessibility rules (shared by all of them)
+
+- **Animate only `transform` and `opacity`.** Never `top`/`left`/`width`/`height`/
+  `margin` (they trigger layout/paint and jank). Use `transform: translate/scale`
+  for position and size. Prefer the compositor; add `will-change` only on the
+  element about to animate, and remove it after.
+- **No scroll/resize listeners for reveal.** Use IntersectionObserver for visibility
+  and `requestAnimationFrame` for any per-frame work; throttle/debounce the rest.
+  Never run animation logic directly in a `scroll` handler.
+- **Respect `prefers-reduced-motion`.** Replace movement with a plain opacity change
+  (or show the final state instantly). Gate every nontrivial effect:
+  ```css
+  @media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after { animation-duration:.01ms!important;
+      animation-iteration-count:1!important; transition-duration:.01ms!important; }
+  }
+  ```
+  In JS, branch on `matchMedia("(prefers-reduced-motion: reduce)").matches` before
+  typing, particles, smooth-scroll, or autoplay loops.
+- **Reveal once; don't re-fire** on scroll-back (`once:true` / `unobserve`).
+- **Pause offscreen / on hidden tab** (Lottie, particles, video): check
+  `document.hidden` / IntersectionObserver and stop rAF to save battery/CPU.
+- **Keep durations honest:** entrances 300–800ms; hovers 200–300ms; never block
+  interaction or delay content paint behind an animation. Don't animate above the
+  fold in a way that hides LCP text.
+
+---
+
+## License quick-reference
+
+| Library | License | Note |
+|---|---|---|
+| GSAP | Custom "no-charge" | **Not OSI/MIT.** Free (incl. all plugins) but proprietary — flag before bundling. |
+| Motion / framer-motion | MIT | Paid Motion+ add-on optional, not required. |
+| anime.js | MIT | |
+| lottie-web | MIT | |
+| rlottie | MIT | Some vendored parts differ (see COPYING). |
+| theatre.js | Apache-2.0 | |
+| auto-animate | MIT | |
+| AOS | MIT | |
+| typed.js | **GPL** | **Flag — don't bundle in proprietary output; reimplement.** |
+| tsparticles | MIT | |
+| rive-runtime | MIT | Web runtime is `@rive-app/canvas`. |
+| vivus | MIT | |
+| lenis | MIT | |
+| barba.js | MIT | |
+| react-spring | MIT | |
+| animate.css | **Hippocratic 2.1** | **Flag — ethical-source, not OSI. Reimplement keyframes.** |
+| synfig / friction | GPL-3.0 | Desktop authoring tools (category O), not web runtimes. |
+
+Most are MIT and safe to reference/learn from freely. The four to flag: **GSAP**
+(proprietary no-charge), **typed.js** (GPL), **animate.css** (Hippocratic 2.1), and
+**synfig/friction** (GPL desktop tools). For the flagged ones we adopt the *pattern*
+and author our own code.