# 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.