@xpert-ai/plugin-motion 0.1.0

package/dist/assets/upstream/MOTION-SPEC.md

@@ -0,0 +1,127 @@
+# MOTION-SPEC.md — the motion standard
+
+This is the "taste engine" of motion-anything. It encodes **how to use motion well**, so that
+every recipe and the router skill produce restrained, accessible, product-grade animation instead
+of decoration for its own sake.
+
+> Inspiration: this spec is aligned with widely-respected motion guidance (Material motion,
+> Apple HIG, and Emil Kowalski's animation principles). Recipes should cite their lineage in
+> `recipe.motion.yaml > license.upstream` where applicable.
+
+---
+
+## 1. First principles
+
+1. **Motion must mean something.** Every animation either (a) gives feedback, (b) shows a
+   relationship/continuity, or (c) directs attention. If it does none of these, cut it.
+2. **The best motion is felt, not noticed.** If users consciously notice the animation, it is
+   usually too slow, too big, or too frequent.
+3. **Restraint is the craft.** More motion is not better. A single, well-placed moment beats ten.
+4. **Performance is part of taste.** Janky motion reads as cheap. Animate GPU-friendly properties.
+5. **Accessibility is non-negotiable.** Always honor `prefers-reduced-motion`.
+
+## 2. Timing scale (duration tokens)
+
+Use these tokens; do not invent arbitrary durations.
+
+| Token | ms | Use for |
+|-------|----|---------|
+| `instant` | 80–120 | Hover/press feedback, tiny state flips |
+| `fast` | 140–220 | Micro-interactions, button/toggle states, small reveals |
+| `base` | 220–320 | Standard transitions, card/element entrances |
+| `slow` | 320–500 | Page/section transitions, larger reveals |
+| `deliberate` | 500–800 | Hero moments, celebratory bursts, onboarding |
+| `cinematic` | 800–2000 | Video transitions, launch-film moments only |
+
+Rule of thumb: **the larger the moving element or distance, the longer the duration** — but stay
+in band. UI micro-interactions should almost always be `fast`.
+
+## 3. Easing tokens
+
+| Token | curve | Use for |
+|-------|-------|---------|
+| `ease-out` | `cubic-bezier(0.16, 1, 0.3, 1)` | **Default** for things entering / responding to the user |
+| `ease-in` | `cubic-bezier(0.4, 0, 1, 1)` | Things leaving the screen |
+| `ease-in-out` | `cubic-bezier(0.65, 0, 0.35, 1)` | Moves that start and end on screen |
+| `spring-soft` | spring(stiffness 170, damping 26) | Playful, organic; toggles, drags, delight |
+| `spring-snappy` | spring(stiffness 300, damping 30) | Crisp, responsive controls |
+
+Default to **`ease-out`** for UI. Linear easing is for continuous loops only (spinners, marquees).
+
+## 4. Restraint budget
+
+Per visible viewport ("view"):
+
+- **≤ 1** celebratory / attention-grabbing moment (`feedback-delight`, `emphasis`).
+- **≤ 3** simultaneous entrance animations; stagger the rest. Stagger step **40–80ms**, capped so
+  the whole sequence finishes within `slow`.
+- **No competing loops.** At most one ambient/looping animation on screen at a time.
+- **Never auto-play celebratory motion.** Delight triggers on user intent (tap/submit), not on load.
+
+Each recipe declares its own budget in `recipe.motion.yaml > restraint`. The router must respect the
+sum across recipes it composes — if two recipes both want the "one celebratory moment", pick one.
+
+## 5. Performance rules
+
+- Animate **`transform` and `opacity`** only for anything that moves or fades. Avoid animating
+  `width`, `height`, `top`, `left`, `margin` (they trigger layout). Use `transform: translate/scale`.
+- Promote heavy animations with `will-change` sparingly; remove it after the animation ends.
+- Target **60fps**. If a recipe can't hold 60fps on a mid-range laptop, simplify it.
+- Clean up: cancel timers/RAF, remove injected DOM nodes (e.g. particles) after they finish.
+
+## 6. Accessibility — `prefers-reduced-motion`
+
+Every recipe MUST degrade gracefully. Acceptable reduced-motion fallbacks:
+
+- `scale-only` — keep a tiny scale/opacity cue, drop travel and particles.
+- `crossfade` — replace movement with a short opacity change.
+- `none` — show the end state instantly (valid for purely decorative motion).
+
+Reference pattern (every recipe's CSS should include something like this):
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  /* drop travel, particles, and long durations; keep a minimal cue or none */
+}
+```
+
+## 7. Category taxonomy
+
+Recipes are tagged with one primary `category`. This is what the router matches intent against.
+
+| Category | What it is | Default duration | Default easing |
+|----------|------------|------------------|----------------|
+| `entrance` | Elements appearing (fade/slide/scale in) | `base` | `ease-out` |
+| `exit` | Elements leaving | `fast` | `ease-in` |
+| `scroll-reveal` | Reveal on scroll into view | `base` | `ease-out` |
+| `hover-press` | Pointer feedback (magnetic, lift, press) | `fast` | `ease-out` / `spring-snappy` |
+| `state-transition` | Toggle / tab / accordion / expand | `fast` | `ease-in-out` |
+| `feedback-delight` | Celebratory micro-moments (like-burst, confetti) | `deliberate` | `ease-out` / `spring-soft` |
+| `emphasis` | Draw attention (pulse, shake, count-up) | `fast`–`base` | `ease-out` |
+| `loading` | Pending/progress states | loop | linear |
+| `page-transition` | Between routes/sections | `slow` | `ease-in-out` |
+| `text-kinetic` | Animated typography (for web & video) | `base`–`cinematic` | varies |
+| `video-transition` | Shot-to-shot transitions for video | `cinematic` | `ease-in-out` |
+
+## 8. Intent → motion mapping (for the router)
+
+The router maps fuzzy human language to categories + recipes. Common cues:
+
+| User says (incl. 中文) | Likely category |
+|------------------------|-----------------|
+| "snappy", "responsive", "丝滑", "干脆" | `hover-press`, `state-transition` (`fast`, `spring-snappy`) |
+| "delightful", "surprise", "fun", "惊喜感", "好玩" | `feedback-delight` |
+| "elegant", "smooth", "premium", "高级", "优雅" | `entrance`, `scroll-reveal` (`base`/`slow`, `ease-out`) |
+| "draws attention", "pop", "强调", "突出" | `emphasis` |
+| "cinematic", "launch video", "发布视频", "电影感" | `video-transition`, `text-kinetic` (`cinematic`) |
+| "alive", "playful", "有生命力", "活泼" | `hover-press`, `feedback-delight` (`spring-soft`) |
+
+When intent is ambiguous, prefer the **more restrained** option and ask one clarifying question.
+
+## 9. Definition of done for any produced motion
+
+- [ ] Serves feedback, continuity, or attention (§1).
+- [ ] Duration + easing pulled from the tokens (§2–3), appropriate to element size.
+- [ ] Within the restraint budget for the view (§4).
+- [ ] Transforms/opacity only; cleans up after itself (§5).
+- [ ] Has a working `prefers-reduced-motion` fallback (§6).

package/dist/assets/upstream/README.md

@@ -0,0 +1,283 @@
+# motion-anything
+
+<p align="center"><sub>A project in the <a href="https://github.com/nexu-io/open-design"><b>nexu.io · Open Design</b></a> family — the same team's take on motion. If motion-anything clicks for you, <a href="https://github.com/nexu-io/open-design">Open Design</a> is where the full agent-era design studio lives.</sub></p>
+
+> **Describe the feeling — your AI ships the animation.** The agentic motion layer: a local-first, chat-native motion engine. Generate animated pages and launch videos from one sentence, then edit motion **on the running page, component by component** — 4 triggers, 13 motion verbs, spring easing, a full keyframe editor. Driven by **8 coding-agent engines + BYOK** (Claude Code · Codex · Cursor · OpenCode · Grok Build · Hermes · Gemini · Open Design Cloud), armed with **403 curated motion recipes**, wired into the **Open Design ecosystem** (59 `DESIGN.md` brand packs · 58 HyperFrames video templates · 112 HTML prototype templates · 2,680 icons), and exported to anything: JSON · CSS · React · Lottie · MP4 · GIF · portable skills. Zero npm dependencies. No watermark. No per-render fees.
+
+<p align="center">
+  <img src="docs/assets/hero.jpg" alt="motion-anything — Anything becomes motion, on your laptop. Editorial dark banner with light-mode app windows: the component-motion workbench and the launch-video compositor, plus a stats row — 403 motion recipes, 230 portable skills, 2,680 icons, 59 design systems." width="100%" />
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square" /></a>
+  <a href="#engines"><img alt="Engines" src="https://img.shields.io/badge/engines-8%20CLIs%20%2B%20BYOK-111?style=flat-square" /></a>
+  <a href="#the-library"><img alt="Recipes" src="https://img.shields.io/badge/motion%20recipes-403-8b7cf6?style=flat-square" /></a>
+  <a href="#export-anything"><img alt="Export" src="https://img.shields.io/badge/export-JSON%20%C2%B7%20CSS%20%C2%B7%20React%20%C2%B7%20Lottie%20%C2%B7%20MP4%20%C2%B7%20GIF-9b59b6?style=flat-square" /></a>
+  <a href="#quickstart"><img alt="Quickstart" src="https://img.shields.io/badge/quickstart-1%20command-green?style=flat-square" /></a>
+  <a href="#architecture"><img alt="Zero deps" src="https://img.shields.io/badge/npm%20dependencies-0-ff6b35?style=flat-square" /></a>
+</p>
+
+<p align="center">
+  <a href="#the-library"><img alt="Design systems" src="https://img.shields.io/badge/design%20systems-59-1abc9c?style=flat-square" /></a>
+  <a href="#the-library"><img alt="Video templates" src="https://img.shields.io/badge/HyperFrames%20video%20templates-58-e67e22?style=flat-square" /></a>
+  <a href="#the-library"><img alt="HTML templates" src="https://img.shields.io/badge/HTML%20prototype%20templates-112-3498db?style=flat-square" /></a>
+  <a href="#the-library"><img alt="Icons" src="https://img.shields.io/badge/icons-2680-f39c12?style=flat-square" /></a>
+  <a href="#open-design-ecosystem"><img alt="Portable skills" src="https://img.shields.io/badge/portable%20skills-230-8b7cf6?style=flat-square" /></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/nexu-io/open-design"><img alt="Family" src="https://img.shields.io/badge/family-nexu--io%2Fopen--design-ff7043?style=flat-square&logo=github&logoColor=white" /></a>
+  <a href="https://x.com/OpenDesignHQ"><img alt="Follow on X" src="https://img.shields.io/badge/follow-%40OpenDesignHQ-000000?style=flat-square&logo=x&logoColor=white" /></a>
+</p>
+
+<p align="center"><b>English</b> · <a href="README.zh-CN.md">简体中文</a></p>
+
+---
+
+## Showcase
+
+Every tile below is a **live, dependency-free recipe** from the library — real GPU shaders, canvas engines and kinetic text, faithfully ported so they run with two `<script>` tags on any page (no React, no three.js, no build step). All tiles are animated GIFs recorded from the actual previews.
+
+<table>
+<tr>
+<td width="50%"><a href="recipes/slides/fx-typewriter-multi/"><img src="docs/assets/effects/typewriter-multi.gif" alt="Typewriter multi — terminal-style lines typing in sequence" /></a></td>
+<td width="50%"><a href="recipes/web/shiny-text/"><img src="docs/assets/effects/shiny-text.gif" alt="Shiny text — a highlight band sweeps across the label" /></a></td>
+</tr>
+<tr>
+<td><b><a href="recipes/slides/fx-typewriter-multi/">typewriter-multi</a></b> · kinetic text<br/><sub>Terminal-style multi-line typing with live cursors — agent-boot energy.</sub></td>
+<td><b><a href="recipes/web/shiny-text/">shiny-text</a></b> · kinetic text<br/><sub>A sheen sweeps across text-clipped gradient type. One class to use.</sub></td>
+</tr>
+<tr>
+<td width="50%"><a href="recipes/web/star-border/"><img src="docs/assets/effects/star-border.gif" alt="Star border — a slow light circles the button border" /></a></td>
+<td width="50%"><a href="recipes/web/rotating-text/"><img src="docs/assets/effects/rotating-text.gif" alt="Rotating text — words cycle in place" /></a></td>
+</tr>
+<tr>
+<td><b><a href="recipes/web/star-border/">star-border</a></b> · ambient CTA<br/><sub>A slow light orbits the border of your call-to-action. Pure CSS.</sub></td>
+<td><b><a href="recipes/web/rotating-text/">rotating-text</a></b> · kinetic text<br/><sub>One line, many claims — words cycle in place with a soft travel.</sub></td>
+</tr>
+<tr>
+<td width="50%"><a href="recipes/web/magnet-lines/"><img src="docs/assets/effects/magnet-lines.gif" alt="Magnet lines — a grid of lines tracks the pointer" /></a></td>
+<td width="50%"><a href="recipes/web/elastic-slider/"><img src="docs/assets/effects/elastic-slider.gif" alt="Elastic slider — a springy gradient fill follows the drag" /></a></td>
+</tr>
+<tr>
+<td><b><a href="recipes/web/magnet-lines/">magnet-lines</a></b> · interactive<br/><sub>A field of compass needles that swivel toward your pointer.</sub></td>
+<td><b><a href="recipes/web/elastic-slider/">elastic-slider</a></b> · feedback<br/><sub>A slider whose fill overshoots with a spring — tactile, GPU-safe.</sub></td>
+</tr>
+<tr>
+<td width="50%"><a href="recipes/web/bounce-cards/"><img src="docs/assets/effects/bounce-cards.gif" alt="Bounce cards — a stack fans out with a bounce" /></a></td>
+<td width="50%"><a href="recipes/web/strands/"><img src="docs/assets/effects/strands.gif" alt="Strands — flowing luminous fibers" /></a></td>
+</tr>
+<tr>
+<td><b><a href="recipes/web/bounce-cards/">bounce-cards</a></b> · entrance<br/><sub>A card stack fans out with a staggered bounce as it enters the view.</sub></td>
+<td><b><a href="recipes/web/strands/">strands</a></b> · GPU shader<br/><sub>Luminous fibers drifting like hair in water — a quiet hero backdrop.</sub></td>
+</tr>
+<tr>
+<td width="50%"><a href="recipes/web/silk/"><img src="docs/assets/effects/silk.gif" alt="Silk — flowing silky fabric waves" /></a></td>
+<td width="50%"><a href="recipes/web/waves/"><img src="docs/assets/effects/waves.gif" alt="Waves — perlin-warped line field with a pointer wake" /></a></td>
+</tr>
+<tr>
+<td><b><a href="recipes/web/silk/">silk</a></b> · GPU shader<br/><sub>Flowing fabric, ported from a three.js scene to a single fragment shader.</sub></td>
+<td><b><a href="recipes/web/waves/">waves</a></b> · canvas 2D<br/><sub>A perlin-warped line field with a pointer wake — organic, editorial, calm.</sub></td>
+</tr>
+<tr>
+<td width="50%"><a href="recipes/web/faulty-terminal/"><img src="docs/assets/effects/faulty-terminal.gif" alt="Faulty terminal — CRT glitch grid" /></a></td>
+<td width="50%"><a href="recipes/web/pixel-blast/"><img src="docs/assets/effects/pixel-blast.gif" alt="Pixel blast — drifting pixel pattern with click ripples" /></a></td>
+</tr>
+<tr>
+<td><b><a href="recipes/web/faulty-terminal/">faulty-terminal</a></b> · GPU shader<br/><sub>A glitching CRT grid for cyber / dev-tool moods.</sub></td>
+<td><b><a href="recipes/web/pixel-blast/">pixel-blast</a></b> · GPU shader · interactive<br/><sub>A drifting pixel pattern that ripples outward from every click.</sub></td>
+</tr>
+</table>
+
+### Kinetic text
+
+Motion is not only backgrounds — text is a first-class citizen. These run on plain DOM, dependency-free:
+
+<table>
+<tr>
+<td width="50%"><a href="recipes/web/decrypted-text/"><img src="docs/assets/effects/decrypted-text.gif" alt="Decrypted text — glyphs resolve into ACCESS GRANTED" /></a></td>
+<td width="50%"><a href="recipes/web/text-scramble/"><img src="docs/assets/effects/text-scramble.gif" alt="Text scramble — a techy decode reveal between phrases" /></a></td>
+</tr>
+<tr>
+<td><b><a href="recipes/web/decrypted-text/">decrypted-text</a></b> · kinetic text<br/><sub>Random glyphs resolve left-to-right into the real line — hacker-movie energy, one attribute to use.</sub></td>
+<td><b><a href="recipes/web/text-scramble/">text-scramble</a></b> · kinetic text<br/><sub>Decode-reveal between any phrases, programmable via <code>scrambleTo(el, text)</code>.</sub></td>
+</tr>
+<tr>
+<td width="50%"><a href="recipes/web/count-up/"><img src="docs/assets/effects/count-up.gif" alt="Count up — stats rolling from zero to their values" /></a></td>
+<td width="50%"><a href="recipes/web/true-focus/"><img src="docs/assets/effects/true-focus.gif" alt="True focus — a focus frame hops word to word, blurring the rest" /></a></td>
+</tr>
+<tr>
+<td><b><a href="recipes/web/count-up/">count-up</a></b> · kinetic text<br/><sub>Numbers roll up to their value on view — the stat-block moment, eased properly.</sub></td>
+<td><b><a href="recipes/web/true-focus/">true-focus</a></b> · kinetic text<br/><sub>A focus frame hops word to word while the rest stays blurred — spotlight your claim.</sub></td>
+</tr>
+</table>
+
+<p align="center"><sub>35 of the library's distinctive effects are faithful dependency-free ports — see <a href="ATTRIBUTION.md">ATTRIBUTION.md</a> for sources and permissions. The full library holds <b>403 recipes</b>.</sub></p>
+
+---
+
+## Product tour
+
+<table>
+<tr>
+<td valign="top">
+<img src="docs/assets/home.png" alt="Home — describe the motion you want in one sentence" /><br/>
+<sub><b>Home</b> — one sentence in, animated artifact out. Pick a design system (59 brand packs) and a motion profile (Subtle → Cinematic), or just type.</sub>
+</td>
+</tr>
+</table>
+
+<table>
+<tr>
+<td width="50%" valign="top">
+<img src="docs/assets/workbench.png" alt="Workbench — component-level motion editing on the running page, with the agent's plan, a keyframes inspector and the timeline" /><br/>
+<sub><b>Workbench</b> — the heart. The agent plans, generates and self-checks on the left; click any component on the <i>running</i> page and give it motion — triggers, presets or a 6-track keyframe editor with scrub + auto-keyframe. The timeline below warns when a view exceeds the restraint budget.</sub>
+</td>
+<td width="50%" valign="top">
+<img src="docs/assets/video-editor.png" alt="Video editor — layers, five scenes with transitions, film background and reference upload" /><br/>
+<sub><b>Video editor</b> — a canvas compositor for launch videos: text / shape / image / video layers, five scenes with real transitions, a shared film background, kinetic typography, and in-browser WebCodecs MP4 export. No watermark, nothing uploaded.</sub>
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+<img src="docs/assets/motion-path.png" alt="Motion path — draw a curve on the canvas and the selected text travels it" /><br/>
+<sub><b>Motion paths</b> — draw a line on the canvas, and the selected layer travels it: as drawn, or snapped to a clean line / circle / ellipse, with eased speed and per-character text motion on top.</sub>
+</td>
+<td width="50%" valign="top">
+<img src="docs/assets/motion-presets.png" alt="Motion presets — entrance, emphasis, attention and exit presets stack onto any layer" /><br/>
+<sub><b>Motion presets</b> — entrance / emphasis / attention / exit presets stack onto any layer (text, image, video, shapes), plus the full 200+ recipe library one click away.</sub>
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+<img src="docs/assets/library.png" alt="Library — recipe cards with live animated previews" /><br/>
+<sub><b>Library</b> — 403 curated recipes with live card previews, searchable by intent. Every recipe carries <code>avoid_when</code> and a restraint budget: taste is enforced, not hoped for.</sub>
+</td>
+<td width="50%" valign="top">
+<img src="docs/assets/engines.png" alt="Engines — 8 coding-agent CLIs plus BYOK" /><br/>
+<sub><b>Engines</b> — bring the agent you already pay for. 8 CLIs auto-detected on your PATH, plus BYOK for direct Anthropic / OpenAI / Google API calls. Keys never leave your machine.</sub>
+</td>
+</tr>
+</table>
+
+<table>
+<tr>
+<td valign="top">
+<img src="docs/assets/dark-mode.png" alt="Dark mode" /><br/>
+<sub><b>Dark mode</b> — the whole app, both ways. Follows your OS in system mode.</sub>
+</td>
+</tr>
+</table>
+
+---
+
+## Why motion-anything
+
+Motion is one of the highest-leverage, lowest-understood parts of digital craft. Four problems keep great motion out of reach:
+
+1. **AI-generated pages are dead ends** — you can generate a landing page, but tweaking its motion means re-rolling the whole page or hand-writing CSS. There is a gap between generating and refining. *motion-anything edits motion on the running page, per component, and writes it back to the file.*
+2. **AI has no taste** — default output is either everything-fades-in-at-once or a fireworks show. *Here, taste is a feature: every recipe declares <code>avoid_when</code> and a restraint budget; the editor warns when a view exceeds it; <code>prefers-reduced-motion</code> is always honored; GPU-safe properties only.*
+3. **The ecosystem is scattered** — GSAP, Framer Motion, anime.js, Lottie… each a learning curve. *You express intent ("a liquid-metal background"), the router picks from curated recipes. You never need to know a library name.*
+4. **Tools lock you in** — proprietary models, per-render fees, watermarks, handoff-only artifacts. *This is Apache-2.0, local-first, engine-agnostic, and everything exports.*
+
+**vs. Figma Motion** — their artifact is a handoff; ours is the running page itself. Their timeline has no interaction triggers; hover and click are first-class here. Their motion lives in their app; ours exports to JSON / CSS / React / Lottie or a portable skill any agent can use.
+
+---
+
+## Open Design ecosystem
+
+motion-anything is not a standalone island — it is the **motion layer of the [Open Design](https://github.com/nexu-io/open-design) family**, and the interop is real, not a logo wall:
+
+- **Every recipe is an Open-Design-compatible `SKILL.md`** — export any of the 230 portable skills and drop it straight into Open Design's `skills/` (or any agent that reads skills).
+- **59 brand packs in Open Design's `DESIGN.md` format** — generation starts on-brand; the same contract your team already uses in OD drives motion here.
+- **58 HyperFrames video templates + 112 OD HTML prototype templates** shipped in the library — briefs get matched against them so output starts from proven structure, not a blank canvas.
+- **Open Design Cloud is a first-class engine** — the same ACP runtime (`vela`) that powers OD drives motion-anything, with one recharge across GPT / Claude / Gemini / DeepSeek.
+- **Shared craft assets** — agent engine icons, the icon library (2,680 icons · 38 categories), and the design language all come from the same family.
+
+The loop: *pick a beautiful design system (OD's superpower) → generate a brand-grade page → give it motion, per component (our superpower) → export it back as a skill anyone's agent can reuse.*
+
+---
+
+## Quickstart
+
+```bash
+git clone https://github.com/nexu-io/motion-anything.git
+cd motion-anything
+node cli/bin/motion.js serve 4399
+# open http://localhost:4399
+```
+
+That is the whole install. **No npm install — the project has zero dependencies.** You need Node 18+ and at least one agent engine: any supported CLI on your PATH (it will be auto-detected), or an API key for BYOK (Settings → Execution mode).
+
+---
+
+## Engines
+
+Your prompt runs on **your** agent — the CLI session you already pay for, or your own API key. Nothing is proxied through anyone's server.
+
+| Engine | Vendor | Transport |
+|---|---|---|
+| Claude Code | Anthropic | headless `-p` + stream-json |
+| Codex CLI | OpenAI | `exec --json` event stream |
+| Cursor Agent | Cursor | stream-json |
+| OpenCode | OpenCode | `run --format json` event stream |
+| Grok Build | xAI | plain text via prompt file |
+| Hermes | xAI | ACP (JSON-RPC over stdio) |
+| Gemini CLI | Google | plain text |
+| Open Design Cloud | nexu.io | ACP via the `vela` CLI |
+| BYOK | Anthropic / OpenAI / Google | direct API with your key |
+
+---
+
+## The library
+
+- **403 motion recipes** — 77 real effects with live previews, plus curated reference cards. Categories: ambient backgrounds, feedback & delight, interaction, text, transitions.
+- **Standardized manifests** — every recipe is a folder with `recipe.motion.yaml`, a self-contained `preview.html`, the implementation, and a `SKILL.md`. Three fields you will not find elsewhere: `intent_keywords`, `avoid_when`, `restraint`.
+- **59 design-system brand packs** + **58 video templates** + **112 HTML prototype templates** + **2,680 icons** — generation starts brand-grade, not blank.
+- **230 portable skills** — export any recipe as a `SKILL.md` and drop it into [Open Design](https://github.com/nexu-io/open-design) or any agent that reads skills.
+
+The taste contract lives in [`MOTION-SPEC.md`](MOTION-SPEC.md). The library golden path (how to add a recipe) lives in [`AGENTS.md`](AGENTS.md).
+
+---
+
+## Export anything
+
+| From | To |
+|---|---|
+| Any component's motion | JSON (portable) · CSS · React · Lottie |
+| Any animated page | MP4 (freezable-timeline frame capture) · GIF · single-file HTML |
+| Any launch video | MP4 via in-browser WebCodecs — no watermark, no upload, no fees |
+| Any recipe | a portable `SKILL.md` for your agent |
+
+---
+
+## Architecture
+
+Plain files, no build step, zero npm dependencies — the whole app is deliberately boring to run:
+
+- `app/index.html` — the entire client (workbench, editors, library, i18n ×4) in one file.
+- `cli/bin/motion.js` — server + CLI in one file: static serving, project store, and the engine dispatch (stream-json / JSONL events / plain / ACP / BYOK behind one interface).
+- `app/video/` — the canvas compositor: engine, WebCodecs MP4 export, HTML frame capture, vendored `mp4-muxer` + `gifenc` (MIT).
+- `recipes/` — the library. `recipes/web/_fx/shaderbg.js` (58 lines) is the dependency-free WebGL runner behind all shader recipes.
+- `skills/` — the router skill + bundled companion skills.
+
+Agents are first-class citizens of the codebase itself: [`AGENTS.md`](AGENTS.md) is a working agreement any coding agent can follow, and [`PROGRESS.md`](PROGRESS.md) keeps the state.
+
+---
+
+## Roadmap
+
+- **v0.1** — recipe library + router skill + workbench + video line + 8 engines + BYOK ← *we are here*
+- **v0.x** — richer video motion (recipe reuse inside video), deeper Figma import, streaming BYOK
+- **v1** — auto-add motion to existing Open Design artifacts; design-component → motion auto-assign
+
+---
+
+## License & credits
+
+[Apache-2.0](LICENSE). A project in the [nexu.io](https://github.com/nexu-io) / Open Design family.
+Third-party sources and permissions are recorded in [`ATTRIBUTION.md`](ATTRIBUTION.md).
+
+---
+
+📖 中文文档见 [README.zh-CN.md](README.zh-CN.md)

package/dist/assets/upstream/SOURCES.md

@@ -0,0 +1,107 @@
+# SOURCES.md — 动效来源盘点 & 收录路线图
+
+> 这份文档回答两件事：(1) 外面有哪些可作"原料"的开源/主流动效来源；(2) 我们按什么原则、
+> 什么优先级把它们纳入 motion-anything。
+> 配合阅读：产品定位见 `README.md`；动效标准见 `MOTION-SPEC.md`；manifest 字段见 `AGENTS.md`。
+>
+> _状态：v0 草案（2026-06-25）。第 5 节的建库 schema 拍板后再落到 AGENTS.md。_
+
+## 0. 一句话定位
+
+我们不是"又一个素材站"。我们建的是一个 **可被 AI 检索 / 选择 / 参数化 / 导出 / 注入的 motion
+system（motion intelligence layer）**。所以：**来源只是原料，统一的 manifest 才是产品。**
+收录的价值 ≠ 收了多少个站，而 = 把多少异构来源**归一化**成了我们的标准。
+
+## 1. 收录三原则
+
+1. **意图驱动，不按来源分类。** 来源（Lottie / Remotion…）只作元数据，用于许可与溯源，不作分类轴。
+2. **克制优先。** 每条 recipe 必带 `restraint` / `avoid_when`（MOTION-SPEC）。宁缺毋滥——知道"何时不加"是产品的灵魂。
+3. **许可证先行。** 逐一核实 license。注意：**素材文件的版权 ≠ 库本身的开源许可**（Lottie 库是 MIT，但 LottieFiles 上的素材版权归作者）。
+
+## 2. 来源盘点（按产物形态；许可证需在集成前逐一复核）
+
+### ① 声明式 / JSON 动效格式 —— 与 motion-as-JSON 最对口
+| 名称 | 形态 | 许可（待核实） | 梯队 | 备注 |
+|------|------|----------------|------|------|
+| Lottie (lottie-web / dotLottie) | JSON | 库 MIT；素材归作者 | **T1** | AE 导出 JSON，跨端。最契合 motion-JSON 桥接 |
+| Rive (.riv) | JSON+状态机 | 运行时开源；文件归作者 | **T1** | 带交互/状态机，比 Lottie 强 |
+| Theatre.js | JSON+可视化编辑 | Apache-2.0 | **T1** | 几乎就是我们想做的"motion-as-JSON 编辑器" |
+| SVG (SMIL / SVGator) | 标记/JSON | 视来源 | T2 | 轻量矢量动画 |
+
+### ② Web 代码动效引擎 / 库 —— 运行时层
+| 名称 | 形态 | 许可（待核实） | 梯队 | 备注 |
+|------|------|----------------|------|------|
+| GSAP | JS | 2025 起全部免费 | **T1** | 最强；Webflow 收购后含所有插件 |
+| Framer Motion / Motion (motion.dev) | JS/React | MIT | **T1** | 声明式，React + vanilla |
+| Motion One | JS | MIT | **T1** | WAAPI 封装，轻量 |
+| Anime.js / React Spring / AutoAnimate | JS | MIT | T1 | 通用补间 / 物理 / 自动过渡 |
+| Lenis · Locomotive · AOS · ScrollReveal | JS | MIT | T2 | 滚动驱动 |
+| Splitting.js · SplitType · Typed.js | JS | MIT | T2 | 文字动效 |
+| Animate.css · Animista · Hover.css · UIverse | CSS | MIT 等 | T2 | 纯 CSS 类/生成器 |
+
+### ③ UI 动效组件库 —— 组件级，与"组件级编辑"最对口
+| 名称 | 形态 | 许可（待核实） | 梯队 | 备注 |
+|------|------|----------------|------|------|
+| Aceternity UI | React+FM+Tailwind | 免费+Pro 混合 | **T1** | 注意区分免费/付费组件 |
+| Magic UI | React+FM | MIT | **T1** | shadcn 风格动效组件 |
+| Motion Primitives | React+FM | MIT | **T1** | 专做 Framer Motion 基元 |
+| Animata | React/HTML | MIT | **T1** | 开源动效组件集合 |
+| React Bits · Cult UI · Syntax UI | React | 多为 MIT | T2 | 社区动效组件 |
+
+### ④ 程序化 / 代码视频模板 —— 代码即视频
+| 名称 | 形态 | 许可（待核实） | 梯队 | 备注 |
+|------|------|----------------|------|------|
+| Remotion | React→视频 | **公司需商业许可**（个人/小团队免费） | **T2** | 许可有坑，务必先读条款 |
+| Motion Canvas | TS→视频 | MIT | T2 | 程序化动画视频 |
+| Revideo | TS→视频 | 基于 Motion Canvas | T3 | 关注即可 |
+
+### ⑤ AI 视频生成 —— 多为闭源 SaaS（你提到的 HeyGen 在这）
+| 名称 | 形态 | 许可 | 梯队 | 备注 |
+|------|------|------|------|------|
+| HeyGen | 数字人视频 | 闭源 SaaS | **T3** | "生成视频"≠"可复用动效配方" |
+| Runway · Pika · 可灵 · Veo · Sora | AI 视频 | 闭源 SaaS | T3 | 同上，作为"导出/生成目标"而非配方 |
+
+### ⑥ 设计工具内动效 —— 上游 / 导入源
+| 名称 | 形态 | 许可 | 梯队 | 备注 |
+|------|------|------|------|------|
+| Figma (Smart Animate / Figma Motion) | 设计文件 | SaaS | T2 | 重要导入源；无 JSON 互通（我们的机会） |
+| After Effects | 设计文件 | SaaS | T2 | Lottie 的源头 |
+| Jitter · Cavalry · Spline(3D) | 设计文件 | SaaS/混合 | T3 | 关注 |
+
+## 3. 三梯队总览
+
+- **T1 必收**（能归一成 motion-JSON / 能导出为 skill）：代码型 web 动效（GSAP/Framer/Motion One/CSS）、Lottie、Rive、Theatre.js、UI 动效组件。
+- **T2 桥接**（当作导入/导出目标，不是配方本身）：Remotion / Motion Canvas（视频）、Figma / AE（设计源）、滚动/文字类库。
+- **T3 只索引、不纳入标准库**（放链接指针即可）：LottieFiles 海量站、HeyGen/Runway 等闭源 SaaS。
+
+## 4. 归一化映射（来源 → 我们的 manifest）
+
+每条收录项最终都要落成 `recipes/<surface>/<id>/recipe.motion.yaml` + motion-JSON：
+- 代码型（GSAP/Framer/CSS）→ 直接抽成 recipe 的实现文件 + motion-JSON 参数。
+- Lottie/Rive → 作为 `tech: lottie/rive` 的实现，motion-JSON 记录 timing/触发，文件本体作资产引用。
+- 组件库 → 拆出"动效部分"归一化；UI 外壳不收。
+- 视频（Remotion）→ 不进配方库，进"导出目标"（export-as-video 管线）。
+
+## 5. 建库 schema 提案（⚠️ 待拍板，再落到 AGENTS.md）
+
+不按单一树状分类，而是给每条 recipe 打**三层标签**：
+
+```
+检索层（agent 怎么找到它）   ：场景 canvas × 对象 target × 意图 intent
+能力层（这条 recipe 能干什么）：runtime × 格式 format × 可导出 export × 可参数化 params
+品味层（何时该用 / 不该用）   ：restraint × avoid_when            ← 差异化灵魂
+元数据（溯源/合规，不作分类轴）：来源 source × 许可 license
+```
+
+- **场景 canvas**：web 页面 / slides / launch·release 视频 / app UI（首页 chips 已有）
+- **对象 target**：标题·文字 / 按钮·CTA / 卡片 / 列表 / 图片·媒体 / 整页·区块 / 转场
+- **意图 intent**：入场 / 强调 / 反馈·delight / 引导注意 / 过渡 / 加载 / 叙事节奏
+- **能力**：runtime（css/js/framer/gsap/lottie/rive）、format（code/json/video）、export（skill/json/lottie/html/video）、params（可调的 duration/easing/distance/stagger…）
+- **品味**：`restraint.max_per_view`、`avoid_when`
+
+## 6. 下一步
+
+1. **先对齐第 5 节的 schema**（这是"建库思路 + 分类思路"的核心，需要你拍板）。
+2. 确认后：把三层标签写进 `AGENTS.md` 的 manifest schema，并升级现有 6 条 recipe 做样板。
+3. 再从 **T1** 选 1–2 个来源（建议：代码型 web 动效 + Lottie）做归一化试点，验证 schema 跑得通。
+4. 全程遵守原则 2/3：克制 + 许可证核实。