# animui agent guide

`animui` is the installed React 19 package for the animui component kit. It contains 250 typed entries: 132 Free and 118 Pro. Treat the installed package as the source of truth for imports, exports, and declarations.

## Progressive discovery

Do not load the whole catalog or all declarations into context. From the package root, use:

```sh
node bin/animui.mjs list [query]
node bin/animui.mjs info <id>
node bin/animui.mjs doctor [project-directory]
```

`list` searches the 250-entry `agent-manifest.json`. `info` prints the id, title, description, kind, tier, import path, exports, types path, and the entry declaration text. Detailed API and provenance notes are in `docs/components/<id>.md`. `doctor` is read-only and checks compatibility with a target project. The CLI is bundled with this archive and works offline.

## Use in a target app

Install the archive or the package available to the target project, then import the original foundation stylesheet exactly once:

```tsx
import 'animui/styles.css';
import { Button } from 'animui/button';
```

Use the component's catalog import and its shipped declaration. Import individual subpaths; do not invent a barrel path. In Next.js App Router, use entries from a client component and load the stylesheet from the root layout. Preserve the target project's existing routing, styling, data flow, and build setup. Compose the available widgets with real application data and callbacks rather than replacing them with placeholders.

The catalog and declarations are authoritative for the current package. Component docs may retain obsolete source install commands or historical import paths; adapt them to the actual installed exports. Pro declarations are reconstructed from documentation and runtime evidence, so verify behavior and types in the target app. There is no `Demo` export. `SheetTrigger` is unavailable; use the shipped `SheetStack`, `Sheet`, and `useSheetStack().push()` / close API.

Do not add `any`, `@ts-ignore`, fake APIs, or a custom reimplementation when an animui widget exists. Do not assume a component is flawless from its name or documentation. After integration, run the target project's real build and typecheck, then exercise the changed behavior in a focused browser check with representative data and callbacks. Report gaps or unverified device, media, accessibility, or production behavior explicitly.


## Integration details and known limits

Read `docs/integration.md` for bundler/font setup, client boundaries and theme handling. Inspect `integrationNotes` in `info` before choosing a domain-specific block. In particular, AiComposer keeps its original sample conversation and simulated replies; `onSend` emits a message but does not make the block a connected AI backend. Its current API cannot control conversation history. For actual chat data, inspect composable entries such as `chat-thread` and input/action components and connect the host project's backend. Do not promise data customizations that an entry's props do not expose.