animai

# AnimAI **Production-safe 3D & motion components your AI agent can install.** AI agents are great at UI — and notoriously bad at WebGL. Ask one for a Three.js hero and you'll usually get VRAM leaks, SSR crashes, and hydration bugs. AnimAI fixes that with a registry of **pre-vetted React Three Fiber & GSAP components** that are certified leak-free, SSR-safe, and performance-budgeted — then injected into your Next.js app with **AST-safe edits** (never regex) by a CLI or an MCP server your agent calls directly. ```bash npx animai add hero-orbital-rig ``` ## Why vetted matters Every component ships with a machine-generated **vetting report**, produced by the harness in [`scripts/vet.mjs`](scripts/vet.mjs) and enforced in CI: | Check | Guarantee | |---|---| | Dispose audit | a `useEffect` cleanup disposes every geometry/material/texture — no VRAM leaks | | SSR gate | WebGL is loaded via `next/dynamic { ssr: false }` — no server crashes | | GSAP rule | animations use `useGSAP()` — timelines revert cleanly in Strict Mode | | Canvas sizing | `<Canvas>` always gets an explicitly sized container | ## Use it from your AI agent (MCP) Add one line to your agent's MCP config (Cursor, Claude Code, Windsurf): ```json { "mcpServers": { "animai": { "command": "npx", "args": ["-y", "animai", "mcp"] } } } ``` Your agent gets two flat, deterministic tools: - `search_motion_library` — natural-language search over the registry - `fetch_motion_component` — exact vetted source + dependencies + integration steps ## Use it from the CLI ```bash npx animai search "dark 3d hero" # find components npx animai add hero-orbital-rig # write files + AST-patch your route npx animai add hero-orbital-rig --dry-run npx animai add hero-orbital-rig --target main npx animai doctor hero-orbital-rig # check peer-dependency versions npx animai update hero-orbital-rig # re-fetch latest (guards your local edits) npx animai login <license-key> # unlock Pro components ``` `add` writes the component + SSR-safe loader into `app/components/` and injects the JSX into your route using `@ast-grep/napi` Find & Patch — imports and nodes are inserted through the AST, so your source is never corrupted by string replacement. ## Free & Pro The CLI, MCP server, and a growing set of components are free (MIT). Pro components are delivered through a licensed registry — the public npm package and CDN never contain Pro source. See [docs/registry.md](docs/registry.md). ## Repository layout | Path | What it is | |---|---| | `src/` | CLI + MCP server + registry client (the `animai` npm package) | | `registry/` | Component source of truth (`manifest.json` + code per component) | | `scripts/` | Registry/CDN build steps + the vetting harness | | `web/` | animai.dev — browse, docs, and a live MCP playground | | `worker/` | Cloudflare Worker serving the licensed registry (Polar) | | `docs/` | [vetting](docs/vetting.md) and [registry](docs/registry.md) architecture | | `examples/next-demo` | Minimal Next.js target app for trying `add` locally | ## Develop ```bash npm install npm run build # build registry data + compile TypeScript npm run vet # run the vetting harness, write reports npm run vet:check # CI gate — non-zero exit on any critical failure npm run demo:dry-run # preview an AST injection against examples/next-demo npm run mcp # start the MCP server on stdio ``` ## License MIT for the tooling and free components. Pro components are licensed per the terms at animai.dev.