# @agent-native/toolkit

Reusable app-building UI and helpers for Agent-Native apps.

`@agent-native/core` owns the foundational runtime contracts: actions, server
plugins, DB, app state, agent chat transport, sharing stores, collaboration
transport, and other framework primitives. `@agent-native/toolkit` owns reusable
app-building surfaces: shadcn-style UI primitives, app-shell helpers, shared
hooks, sharing and collaboration display UI, portable rich editors, Context
X-Ray presentation, and visual design controls.

Existing `@agent-native/core` imports remain supported during the migration
window through compatibility re-exports. Those re-exports are temporary
migration support. Toolkit stays Core-free: controlled Toolkit views receive
data and callbacks from Core runtime adapters instead of importing runtime
state, actions, or server contracts.

The Toolkit docs catalog is one discovery shelf for reusable app-building
capabilities, even when an implementation remains Core-owned. Scheduling,
Creative Context, and Pinpoint are Toolkit capability modules installed on
demand. They remain separate npm packages with independent lifecycle manifests
and docs. Dispatch is a separate product rather than a Toolkit module.

## Imports

```tsx
import { ToolkitProvider } from "@agent-native/toolkit/provider";
import {
  ChatHistoryList,
  ChatHistoryRail,
} from "@agent-native/toolkit/chat-history";
import { PresenceBar } from "@agent-native/toolkit/collab-ui";
import { ContextMeterView } from "@agent-native/toolkit/context-ui";
import {
  DataTable,
  DateRangePicker,
  GenericChartPanel,
  MetricCard,
  StatsCard,
  buildDashboardPanelGroups,
} from "@agent-native/toolkit/dashboard";
import { DataGrid } from "@agent-native/toolkit/data-grid";
import {
  CanvasCommentPins,
  DrawOverlay,
} from "@agent-native/toolkit/canvas-annotations";
import {
  createCanvasGestureController,
  createCanvasInteractionCore,
} from "@agent-native/toolkit/canvas-interactions";
import { VisualTweakControl } from "@agent-native/toolkit/design-tweaks";
import { SharedRichEditor } from "@agent-native/toolkit/editor";
import { VisibilityBadge } from "@agent-native/toolkit/sharing";
import { Button } from "@agent-native/toolkit/ui/button";
import { Toaster } from "@agent-native/toolkit/ui/sonner";
import { useToast } from "@agent-native/toolkit/hooks/use-toast";
import {
  SidebarFooterActions,
  useSetHeaderActions,
} from "@agent-native/toolkit/app-shell";
```

Import `@agent-native/toolkit/styles.css` after Tailwind to include Toolkit's
source scanning. If an app renders `SharedRichEditor`, also import
`@agent-native/toolkit/editor.css`. If an app renders `ChatHistoryList` or
`ChatHistoryRail`, also import `@agent-native/toolkit/chat-history.css`.

`DrawOverlay` backs the Design and Slides drawing tools. `CanvasCommentPins`
provides lightweight, transient pins that send canvas context to an agent.
Translation, agent-chat routing, document context, and storage-backed review
threads stay with the app.

`createCanvasGestureController` provides a headless move and resize state
machine with zoom conversion, modifier policies, previews, cancellation, and a
single commit boundary. Apps provide adapters for selection, rendering, and
persistence. `createCanvasInteractionCore` exposes the same shared geometry,
text-activation, Escape, nudge, and shortcut policies without owning state.

Use `ChatHistoryRail` for app sidebars. It shows five recent chats by default,
progressively discloses up to fifteen, and keeps the app-provided New chat
action in a footer row with the ellipsis disclosure on its right. The app
continues to own thread persistence, sorting, routing, and mutations through
Core.

Use `SidebarFooterActions` for the shared left-sidebar utility row. Provide the
app-owned controls through its slots; the rendered order is feedback, search,
then collapse, with the same order stacked in collapsed sidebars.

Inside template apps, prefer local adapters such as `@/components/ui/button` so
apps can replace their primitives without changing every callsite.

## Dashboard kit

`@agent-native/toolkit/dashboard` is an ejectable, presentation-only dashboard
kit. It includes metric and stats cards, tables, a date-range picker, panel
ordering and layout helpers, and `GenericChartPanel`. Supply rows, schema, and
callbacks through app-owned action-backed adapters; the kit never fetches data,
stores dashboard state, resolves credentials, or imports Core runtime APIs.

Inspect or take ownership of the complete unit with:

```bash
agent-native eject inspect toolkit/dashboard
agent-native eject toolkit/dashboard --app <app> --apply
```

For durable dashboards, use `@agent-native/core/dashboard-storage` in the app's
server layer. Instantiate its schema and access-scoped store per app, rather
than sharing dashboard rows between apps. Resolve panel data with a
`PanelSourceResolver`; the built-in `program` resolver runs an app-owned data
program and is the zero-wiring default. Provider-specific resolvers stay in the
app that owns their credentials and query policy.

## Data grid kit

`@agent-native/toolkit/data-grid` provides the spreadsheet-like interaction
layer without owning a data model. Supply rows, typed columns, editor slots,
selection state, and commit callbacks from the app. Keyboard navigation,
selection, column resizing, and the scroll surface are shared; `renderHeader`,
`renderBody`, `renderRow`, and `renderFooter` let an app preserve product-
specific headers, grouping, and row actions while adopting the same grid
mechanics.

```tsx
<DataGrid
  rows={rows}
  columns={columns}
  getRowId={(row) => row.id}
  onCellCommit={({ row, column, value }) =>
    updateCell(row.id, column.id, value)
  }
/>
```

The kit never fetches data, calls actions, resolves credentials, or persists
edits. Eject it with `agent-native eject toolkit/data-grid --app <app>` when a
product needs a deeper local visual or interaction change.

## Customize Or Take Ownership

Use public props, slots, callbacks, stable classes, and local adapters first.
If a product needs a deeper override, the published package includes readable
TypeScript under `node_modules/@agent-native/toolkit/src/`. Treat it as a
read-only reference: copy the smallest component or helper into app-owned
source, change the app import, and customize that copy. Do not edit
`node_modules` or deep-import private `src` files at runtime.

Keep Core runtime contracts intact when taking ownership of Toolkit UI. Actions,
application state, auth/access, persistence, agent execution, chat transport,
and page-to-sidebar thread handoff remain on their public Core APIs. Copied UI
is an app-owned snapshot and will not receive upstream fixes automatically.