nexi-agent 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,24 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kaaylabs
4
+
5
+ Portions copyright (c) 2026 Shane Levine (Beautiful UI, MIT — see LICENSE.beautiful-ui)
6
+ and Florian Kiem (shadow-plugin, MIT).
7
+
8
+ Permission is hereby granted, free of charge, to any person obtaining a copy
9
+ of this software and associated documentation files (the "Software"), to deal
10
+ in the Software without restriction, including without limitation the rights
11
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
12
+ copies of the Software, and to permit persons to whom the Software is
13
+ furnished to do so, subject to the following conditions:
14
+
15
+ The above copyright notice and this permission notice shall be included in all
16
+ copies or substantial portions of the Software.
17
+
18
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24
+ SOFTWARE.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Shane Levine
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,602 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
1
+ # nexi-agent
2
+
3
+ **React components for building AI-agent interfaces:** chat threads, streaming
4
+ answers, reasoning traces, tool calls, approvals, task progress, data tables and
5
+ more. You install them, import them, and pass in your own data.
6
+
7
+ **[Browse every component live →](https://nexi-agent-component-package.vercel.app)** (previews, copyable code and props)
8
+
9
+ ```tsx
10
+ <ThinkingState done="Thought for 3 seconds" rows={[{ primary: "Reading the ticket" }]} />
11
+ <StreamingText content="The deploy failed because the API key expired." />
12
+ <ApprovalCard questions={[{ q: "Rotate the key now?", type: "radio", options: ["Yes", "Later"] }]} />
13
+ ```
14
+
15
+ - **43 components:** all 33 from [Beautiful UI](https://www.beautifului.dev), plus 10
16
+ more (chat thread, markdown, dialog, toast, avatar…).
17
+ - **No hardcoded content.** Every word and every row comes from your props.
18
+ - **Fully themeable** through CSS variables, with dark mode built in.
19
+ - **Works in any React 18/19 app** (Vite, Next.js App Router, Remix, CRA). Tailwind
20
+ is optional.
21
+ - **TypeScript-first.** Every component, prop and data type is exported.
22
+
23
+ ---
24
+
25
+ ## Table of contents
26
+
27
+ 1. [Quick start](#1-quick-start)
28
+ 2. [Setup](#2-setup)
29
+ 3. [What's inside](#3-whats-inside)
30
+ 4. [How to use the components](#4-how-to-use-the-components)
31
+ 5. [Recipes](#5-recipes)
32
+ 6. [Customising](#6-customising)
33
+ 7. [Working on this repo](#7-working-on-this-repo)
34
+ 8. [Docker](#8-docker)
35
+ 9. [Releasing](#9-releasing)
36
+ 10. [Troubleshooting](#10-troubleshooting)
37
+ 11. [Credits and license](#11-credits-and-license)
38
+
39
+ ---
40
+
41
+ ## 1. Quick start
42
+
43
+ ```bash
44
+ npm install nexi-agent
45
+ ```
46
+
47
+ ```tsx
48
+ // main.tsx (or your root layout)
49
+ import "nexi-agent/styles.css";
50
+ import { NexiProvider } from "nexi-agent";
51
+
52
+ root.render(
53
+ <NexiProvider>
54
+ <App />
55
+ </NexiProvider>,
56
+ );
57
+ ```
58
+
59
+ ```tsx
60
+ // anywhere inside
61
+ import { StreamingText } from "nexi-agent";
62
+
63
+ <StreamingText content="Hello! I'm your agent." />;
64
+ ```
65
+
66
+ That's all. To see every component with sample data first, open the
67
+ [docs site](https://nexi-agent-component-package.vercel.app).
68
+
69
+ ---
70
+
71
+ ## 2. Setup
72
+
73
+ ### Requirements
74
+
75
+ - React **18 or 19** (`react` and `react-dom` are peer dependencies)
76
+ - Node **20+** to build this repo (22 LTS recommended)
77
+
78
+ ### Install
79
+
80
+ | From | Command | When |
81
+ | --- | --- | --- |
82
+ | **npm** | `npm install nexi-agent` | the normal way |
83
+ | **Git** | `npm install github:abiramavarshini-kl/nexi-agent-component-package` (add `#main` or `#v0.1.0` to pin) | an unreleased commit or branch. npm builds the package on install. |
84
+ | **A local file** | in this repo: `npm run build && npm pack`, then in your app: `npm install ../path/nexi-agent-0.1.0.tgz` | testing unreleased changes in another app |
85
+
86
+ ### Styles: pick one
87
+
88
+ | Your app | Add this | Result |
89
+ | --- | --- | --- |
90
+ | **No Tailwind** (or Tailwind v3) | `import "nexi-agent/styles.css";` once, at the root | precompiled CSS with everything the components need |
91
+ | **Tailwind v4** | in your main CSS, after `@import "tailwindcss";`: `@import "nexi-agent/tailwind.css";` | one combined build; you can also use our tokens (`bg-surface`, `text-ink-2`, `shadow-card`…) in your own markup |
92
+
93
+ ### The provider
94
+
95
+ Wrap your UI in `<NexiProvider>` once. It applies the font, text size and colour
96
+ scope (the `.nexi` class) without touching the rest of your page.
97
+
98
+ ```tsx
99
+ <NexiProvider>…</NexiProvider> // light
100
+ <NexiProvider dark>…</NexiProvider> // dark, for this subtree
101
+ <NexiProvider contents>…</NexiProvider> // no wrapper box (display: contents)
102
+ ```
103
+
104
+ ### Fonts (optional)
105
+
106
+ The design uses **Inter** and **JetBrains Mono**. Load them in your app (Google
107
+ Fonts or `next/font`); otherwise the system fonts are used.
108
+
109
+ ```html
110
+ <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
111
+ ```
112
+
113
+ ### Next.js
114
+
115
+ It works out of the box: the bundle is marked `"use client"`, so you can import
116
+ components straight into App Router pages. Put the CSS import in `app/layout.tsx`.
117
+
118
+ ---
119
+
120
+ ## 3. What's inside
121
+
122
+ ### Conversation
123
+
124
+ | Component | What it shows |
125
+ | --- | --- |
126
+ | `MessageThread` / `Message` | the scrolling chat: user bubbles, agent turns that can hold any component, auto-scroll |
127
+ | `StreamingText` | an answer revealed word by word, with inline citations, sources, action buttons and follow-ups |
128
+ | `Markdown` | a formatted markdown answer (headings, lists, tables, code); safe, and works while text streams in |
129
+ | `ChatComposer` | a compact chat panel with tabs, replies and an input |
130
+ | `PromptBar` | a full input: `@` sources, `/` commands, model picker, attachments, dictation |
131
+ | `SelectionActions` | highlight text → ask the agent to rewrite it → keep or discard |
132
+
133
+ ### Agent activity
134
+
135
+ | Component | What it shows |
136
+ | --- | --- |
137
+ | `ThinkingState` | an expandable reasoning trace (Steps · Reasoning · Search · Coding) |
138
+ | `ToolChips` | tool calls as compact rows, plus file-diff chips |
139
+ | `TaskRows` | tasks with running / failed / completed status |
140
+ | `LoadingState` | a pixel loader with shimmering label and live timer |
141
+ | `AgentScreen` | a live view of the agent's screen (image or video stream) |
142
+ | `ContextCards` | retrieved document chunks (RAG) and their sources |
143
+
144
+ ### Decisions
145
+
146
+ | Component | What it shows |
147
+ | --- | --- |
148
+ | `ApprovalCard` | questions the user answers before the agent acts (human in the loop) |
149
+ | `RecommendationCard` | a suggested action with a confidence meter and alternatives |
150
+ | `DiffTable` | proposed row additions and removals the user can accept one by one |
151
+ | `Dialog` | a confirm or small-form modal |
152
+
153
+ ### Data
154
+
155
+ | Component | What it shows |
156
+ | --- | --- |
157
+ | `RecordsTable` | a spreadsheet-style grid: tags, sorting, resizing, AI-calculated columns |
158
+ | `FilterTable` | a table filtered by status chips |
159
+ | `InsightCards` | a carousel of insights with live charts (`InsightCompareCard`, `InsightAnomalyCard`, `InsightAllocationCard` also work alone) |
160
+ | `CodeBlock` | a code listing or unified diff, with copy |
161
+ | `Flowchart` | a workflow canvas with draggable step and condition cards |
162
+ | `UsageMeter` | tokens or credits used against a limit |
163
+
164
+ ### App shell and feedback
165
+
166
+ | Component | What it shows |
167
+ | --- | --- |
168
+ | `SidebarNav` | collapsible workspace switcher, navigation and chat history |
169
+ | `SearchList` | a command search with live filtering |
170
+ | `EmptyState` | "nothing here yet" or error panels |
171
+ | `ToastProvider` / `useToast` | short notifications |
172
+ | `FineTuneCard` | an inspector with draggable number fields |
173
+ | `GlideMenu` | a menu with a gliding hover highlight |
174
+
175
+ ### Atoms (small building blocks)
176
+
177
+ `Avatar` · `Badge` · `Button` · `Chip` · `EntityChip` · `Monogram` ·
178
+ `ProgressRing` · `SegmentedControl` · `Shimmer` · `StatusPill` · `StreamText` ·
179
+ `Switch` · `TextRow` · `Tooltip` · `ValuePill` · `NexiProvider`
180
+
181
+ ```tsx
182
+ <Badge tone="green" dot>Completed</Badge>
183
+ <Button variant="accent" size="sm">Run</Button>
184
+ <StatusPill tone="orange">Running</StatusPill>
185
+ <Avatar name="Maya Chen" src={photo} status="online" />
186
+ <Tooltip content="Copy answer"><button>…</button></Tooltip>
187
+ <SegmentedControl options={["Day", "Week"]} value={range} onChange={setRange} />
188
+ ```
189
+
190
+ ---
191
+
192
+ ## 4. How to use the components
193
+
194
+ Every component follows the same four conventions. Once you know them, you know
195
+ the whole library.
196
+
197
+ ### ① Content comes from props, and nothing is built in
198
+
199
+ A component without props renders empty, never with placeholder text. Pass your
200
+ data:
201
+
202
+ ```tsx
203
+ <TaskRows
204
+ rows={[
205
+ { key: "fetch", label: "Fetch invoices", amount: "42 files", status: "done", details: [] },
206
+ { key: "match", label: "Match payments", amount: "38 rows", status: "running", step: 2, details: [] },
207
+ ]}
208
+ />
209
+ ```
210
+
211
+ ### ② UI words go in `labels`
212
+
213
+ Button text, aria-labels and messages like "No results found" have English
214
+ defaults. Override any of them, for wording or translation. Some are functions,
215
+ so you can handle plurals:
216
+
217
+ ```tsx
218
+ <DiffTable
219
+ rows={rows}
220
+ labels={{
221
+ apply: (n) => `Apply ${n} edit${n === 1 ? "" : "s"}`,
222
+ toggleHint: "Click a row to include or exclude it",
223
+ }}
224
+ />
225
+ ```
226
+
227
+ ### ③ User actions come back as callbacks
228
+
229
+ | Component | Callbacks |
230
+ | --- | --- |
231
+ | `PromptBar`, `ChatComposer` | `onSend(text, attachments)`, `onModelChange`, `onAttach(files)`, `onDictate()` |
232
+ | `ApprovalCard` | `onSubmitted(answers)`, `onAnswerChange` |
233
+ | `StreamingText` | `onFollowUp(text)`, `onAction(i)`, `onDone()` |
234
+ | `SelectionActions` | `onAction(action)`: return the rewritten text (or a promise of it); `onKeep`, `onDiscard` |
235
+ | `DiffTable` | `onApply(keptRows)` |
236
+ | `RecommendationCard` | `onAccept(option)` |
237
+ | `RecordsTable` | `onSelectionChange(ids)`, `onCalculate(column)` |
238
+ | `SidebarNav` | `onNewChat`, `onPick(id)`, `onNavigate(key)`, `onWorkspaceMenu(key)` |
239
+ | `Dialog` | `onConfirm()` (async is fine; return `false` to keep it open), `onOpenChange` |
240
+ | `Flowchart` | `onConditionChange`, `onSelect` |
241
+ | `Markdown` | `onLinkClick(href)`, `onCopyCode(code)` |
242
+
243
+ ### ④ Sample data lives in `nexi-agent/demo`
244
+
245
+ Each component has a ready-made fixture, which is useful for prototyping and for
246
+ seeing what shape the props take:
247
+
248
+ ```tsx
249
+ import { RecordsTable } from "nexi-agent";
250
+ import { recordsTableDemo } from "nexi-agent/demo";
251
+
252
+ <RecordsTable {...recordsTableDemo} />;
253
+ ```
254
+
255
+ Fixture names are the component name in camelCase plus `Demo` (`approvalCardDemo`,
256
+ `promptBarDemo`…). Read them in [`src/demo/`](src/demo). Nothing from `demo` reaches
257
+ your bundle unless you import it.
258
+
259
+ ### Types
260
+
261
+ All props and data types are exported:
262
+
263
+ ```ts
264
+ import type { ApprovalQuestion, ToolStep, RecordRow, PromptBarProps, ThreadMessage } from "nexi-agent";
265
+ ```
266
+
267
+ ---
268
+
269
+ ## 5. Recipes
270
+
271
+ ### A complete chat screen
272
+
273
+ ```tsx
274
+ import { useState } from "react";
275
+ import { EmptyState, LoadingState, Markdown, MessageThread, PromptBar, type ThreadMessage } from "nexi-agent";
276
+
277
+ export function Chat() {
278
+ const [messages, setMessages] = useState<ThreadMessage[]>([]);
279
+ const [busy, setBusy] = useState(false);
280
+
281
+ const send = async (text: string) => {
282
+ setMessages((m) => [...m, { id: crypto.randomUUID(), role: "user", content: text }]);
283
+ setBusy(true);
284
+ const reply = await askAgent(text); // your API
285
+ setMessages((m) => [...m, { id: crypto.randomUUID(), role: "assistant", name: "Agent", content: <Markdown content={reply} /> }]);
286
+ setBusy(false);
287
+ };
288
+
289
+ return (
290
+ <div style={{ display: "flex", flexDirection: "column", height: "100vh", maxWidth: 720, margin: "0 auto" }}>
291
+ <MessageThread
292
+ className="flex-1"
293
+ messages={messages}
294
+ empty={<EmptyState title="Ask anything" description="Answers show up here." />}
295
+ footer={busy && <LoadingState label="Thinking" />}
296
+ />
297
+ <PromptBar onSend={send} placeholder="Message the agent…" />
298
+ </div>
299
+ );
300
+ }
301
+ ```
302
+
303
+ ### Streaming an answer as it arrives
304
+
305
+ Keep appending to a string. Both `Markdown` and `StreamingText` handle partial
306
+ text.
307
+
308
+ ```tsx
309
+ const [answer, setAnswer] = useState("");
310
+
311
+ const res = await fetch("/api/chat", { method: "POST", body: JSON.stringify({ prompt }) });
312
+ const reader = res.body!.pipeThrough(new TextDecoderStream()).getReader();
313
+ for (;;) {
314
+ const { value, done } = await reader.read();
315
+ if (done) break;
316
+ setAnswer((a) => a + value);
317
+ }
318
+
319
+ <Markdown content={answer} />; // formatted
320
+ <StreamingText content={answer} fill />; // word-by-word reveal + sources / follow-ups
321
+ ```
322
+
323
+ ### Showing the agent's work
324
+
325
+ ```tsx
326
+ <ThinkingState
327
+ variant="Steps"
328
+ active="Working"
329
+ done="Finished in 6s"
330
+ rows={steps.map((s) => ({ primary: s.title, secondary: s.detail }))}
331
+ />
332
+
333
+ <ToolChips
334
+ steps={[
335
+ { icon: "read", label: "Read file", chip: "invoices.csv", mono: true, detail: [{ text: "1,204 rows" }] },
336
+ { icon: "run", label: "Run", chip: "npm test", mono: true, detail: [{ text: "✓ 34 passed" }] },
337
+ ]}
338
+ />
339
+ ```
340
+
341
+ ### Asking before acting
342
+
343
+ ```tsx
344
+ <ApprovalCard
345
+ questions={[
346
+ { q: "Send the reminder emails?", type: "radio", options: ["Send now", "Schedule for 9am"] },
347
+ { q: "Who should get them?", type: "check", options: ["Overdue", "Due this week"] },
348
+ ]}
349
+ onSubmitted={(answers) => agent.resume(answers)}
350
+ />
351
+ ```
352
+
353
+ ### Confirm and notify
354
+
355
+ ```tsx
356
+ // once, near the root
357
+ <ToastProvider>
358
+ <App />
359
+ </ToastProvider>
360
+
361
+ // in any component
362
+ const { toast } = useToast();
363
+ const [open, setOpen] = useState(false);
364
+
365
+ <Dialog
366
+ open={open}
367
+ onOpenChange={setOpen}
368
+ title="Delete this run?"
369
+ description="Its logs and outputs will be removed."
370
+ destructive
371
+ labels={{ confirm: "Delete" }}
372
+ onConfirm={async () => {
373
+ await deleteRun(id);
374
+ toast({ title: "Run deleted", tone: "success" });
375
+ }}
376
+ />
377
+ ```
378
+
379
+ ---
380
+
381
+ ## 6. Customising
382
+
383
+ ### Colours
384
+
385
+ Every colour is a CSS variable. Override them globally or for any section:
386
+
387
+ ```css
388
+ :root {
389
+ --accent: oklch(0.58 0.22 300); /* buttons, links, focus */
390
+ --accent-ink: oklch(0.5 0.2 300); /* accent-coloured text */
391
+ --accent-tint: oklch(0.95 0.03 300); /* soft accent backgrounds */
392
+ }
393
+
394
+ .billing { --accent: #0f9d58; } /* only inside .billing */
395
+ ```
396
+
397
+ | Token | Controls |
398
+ | --- | --- |
399
+ | `--page` `--canvas` `--surface` `--inset` `--field` | backgrounds, from the page down to inputs |
400
+ | `--ink` `--ink-2` `--ink-3` | text: primary, secondary, muted |
401
+ | `--line` `--line-strong` | borders and dividers |
402
+ | `--accent` `--green` `--orange` `--red` (+ `-tint`) | brand and status colours |
403
+ | `--tooltip-bg` `--tooltip-fg` | tooltips and chart labels |
404
+
405
+ ### Dark mode
406
+
407
+ Use `<NexiProvider dark>`, or put `class="dark"` on `<html>` to follow your app's
408
+ own theme switch.
409
+
410
+ ### Size and spacing
411
+
412
+ - Most components accept `className` for margins, width and positioning.
413
+ - Cards have a sensible maximum width (about 320–440px); wrap them to size them.
414
+ `RecordsTable`, `SidebarNav` and `StreamingText` also accept `fill` to take the
415
+ parent's size.
416
+ - Atoms take `size` / `tone` / `variant`: `<Badge size="sm" tone="red" variant="outline">`,
417
+ `<Button size="xs" variant="quiet">`, `<Avatar size="lg" square>`.
418
+
419
+ ### Wording and language
420
+
421
+ Use the `labels` prop on any component (see [②](#-ui-words-go-in-labels)).
422
+
423
+ ---
424
+
425
+ ## 7. Working on this repo
426
+
427
+ ### Get going
428
+
429
+ ```bash
430
+ git clone https://github.com/abiramavarshini-kl/nexi-agent-component-package.git nexi-agent
431
+ cd nexi-agent
432
+ npm install # installs and builds dist/
433
+ npm run playground # opens the docs site at http://localhost:5173
434
+ ```
435
+
436
+ ### Scripts
437
+
438
+ | Command | What it does |
439
+ | --- | --- |
440
+ | `npm run build` | builds `dist/`: ESM + CJS bundles, type files, `styles.css`, `tailwind.css` |
441
+ | `npm test` | builds, then renders every component twice: empty, and with demo data |
442
+ | `npm run typecheck` | runs the TypeScript checks |
443
+ | `npm run playground` | builds, then starts the playground dev server |
444
+ | `npm pack` | creates the `.tgz` file to test-install in another app |
445
+
446
+ ### The playground (docs site)
447
+
448
+ [`playground/`](playground) is the public docs site: a Vite app with a page per
449
+ component (live preview, copyable code, sample data and a props table), an
450
+ introduction, an all-on-one-page gallery at `/all`, and dark mode. It uses the
451
+ built `dist/`, so after editing `src/`, run `npm run build` and the site updates.
452
+
453
+ - **Examples:** `playground/src/examples/<Name>.tsx`. Each file is rendered as the
454
+ preview *and* shown as the code, so the two can't disagree.
455
+ - **Page list and descriptions:** `playground/src/registry.ts`.
456
+ - **Props tables:** generated from the TypeScript source by
457
+ `playground/scripts/make-props.mjs` on every `dev`/`build`. Write a `/** comment */`
458
+ above a prop and it shows up as the description.
459
+
460
+ ### Deploying the docs site (Vercel)
461
+
462
+ [`vercel.json`](vercel.json) holds the whole setup, so there's nothing to configure
463
+ in the dashboard:
464
+
465
+ 1. On [vercel.com](https://vercel.com), **Add New → Project** and import this GitHub
466
+ repository.
467
+ 2. Leave **Root Directory** as the repo root and the framework preset as **Other**
468
+ (`vercel.json` sets the install, build and output commands). Click **Deploy**.
469
+ 3. Every push to `main` redeploys the site. Every other branch and pull request gets
470
+ its own preview URL.
471
+
472
+ To use your own domain, go to **Project → Settings → Domains**.
473
+
474
+ To check a deploy locally first: `npm run build && npm --prefix playground run build && npm --prefix playground run preview`.
475
+
476
+ ### Day-to-day workflow
477
+
478
+ ```bash
479
+ # 1. edit src/…
480
+ npm test # 2. build + check every component renders
481
+ git add -A && git commit -m "…"
482
+ git push # dist/ and .tgz files are git-ignored; no packing needed
483
+ ```
484
+
485
+ You only need `npm pack` to try the package in a separate app.
486
+
487
+ ### Project structure
488
+
489
+ ```
490
+ src/
491
+ atoms/ small building blocks (Badge, Button, Avatar, Tooltip…)
492
+ primitives/ the main components (ApprovalCard, PromptBar, MessageThread…)
493
+ provider/ NexiProvider
494
+ demo/ sample data for every component → "nexi-agent/demo"
495
+ lib/ cn() class helper, icon shims
496
+ styles/ foundation.css: design tokens, theme, animations
497
+ index.ts generated export list (don't edit by hand)
498
+ scripts/
499
+ make-index.mjs regenerates src/index.ts on every build
500
+ build-css.mjs builds dist/styles.css and dist/tailwind.css
501
+ make-foundation.py regenerates foundation.css from upstream Beautiful UI
502
+ test/smoke.test.tsx render test for every component
503
+ playground/ the docs site, deployed to Vercel (not published to npm)
504
+ vercel.json Vercel build settings for the docs site
505
+ ```
506
+
507
+ ### Adding a component
508
+
509
+ 1. Create `src/primitives/MyThing.tsx` with `export default function MyThing(props)`,
510
+ or `src/atoms/MyThing.tsx` with a named export.
511
+ 2. Follow the conventions: content props default to empty, UI words go in
512
+ `labels`, user actions go out through callbacks, the outer element accepts
513
+ `className`, and you export a `MyThingProps` type.
514
+ 3. Add `src/demo/MyThing.ts` exporting `myThingDemo`, and re-export it from
515
+ `src/demo/index.ts`.
516
+ 4. Add `playground/src/examples/MyThing.tsx` (a default-exported example) and a row
517
+ in `playground/src/registry.ts`. It gets its own docs page.
518
+ 5. Run `npm test`. The export list regenerates automatically, and the test fails
519
+ if the component has no demo fixture or crashes.
520
+
521
+ ---
522
+
523
+ ## 8. Docker
524
+
525
+ Docker builds and tests the library, then serves the playground. You don't need
526
+ Node on the host.
527
+
528
+ ```bash
529
+ docker compose up --build playground # nginx gallery → http://localhost:8080
530
+ docker compose up -d --build playground # same, in the background
531
+ docker compose down # stop
532
+
533
+ docker compose --profile dev up --build dev # Vite dev server → http://localhost:5173
534
+ ```
535
+
536
+ Without Compose:
537
+
538
+ ```bash
539
+ docker build -t nexi-agent-playground .
540
+ docker run --rm -p 8080:80 nexi-agent-playground # → http://localhost:8080
541
+
542
+ docker build --target test -t nexi-agent-test . # build + smoke test only
543
+ ```
544
+
545
+ | Dockerfile stage | Purpose |
546
+ | --- | --- |
547
+ | `deps` | installs dependencies |
548
+ | `build` | builds `dist/` |
549
+ | `test` | runs the smoke test (the build fails if a component breaks) |
550
+ | `dev` | playground dev server |
551
+ | `playground` | builds the playground as static files |
552
+ | `web` *(default)* | nginx serving the playground on port 80 |
553
+
554
+ ---
555
+
556
+ ## 9. Releasing
557
+
558
+ The package is on npm as [`nexi-agent`](https://www.npmjs.com/package/nexi-agent).
559
+ To release a new version:
560
+
561
+ ```bash
562
+ npm version patch # 0.1.0 → 0.1.1; use minor / major for bigger changes
563
+ git push --follow-tags # pushes the commit and the v0.1.1 tag
564
+ npm login # once per machine
565
+ npm publish # runs typecheck + build, then asks you to confirm with 2FA
566
+ ```
567
+
568
+ A version number can't be published twice, so bump it with `npm version` each time.
569
+ Publishing needs 2FA on the npm account. The docs site redeploys from `main` on
570
+ its own, so there's nothing to do there.
571
+
572
+ ---
573
+
574
+ ## 10. Troubleshooting
575
+
576
+ | Problem | Fix |
577
+ | --- | --- |
578
+ | Components appear unstyled | Import `nexi-agent/styles.css` once at the root (or `tailwind.css` for Tailwind v4 apps). |
579
+ | A component renders empty | That's by design: pass your content props, or spread its fixture from `nexi-agent/demo`. |
580
+ | `Invalid hook call` / two copies of React | Make sure your app has a single React. With a linked local package, add `resolve: { dedupe: ["react", "react-dom"] }` to your Vite config. |
581
+ | Your app still shows old behaviour after reinstalling a `.tgz` | The version didn't change, so npm reused its cache. Delete `node_modules/nexi-agent` and install again. |
582
+ | `npm warn allow-scripts … nexi-agent (prepare: npm run build)` when installing from Git | Harmless: npm has already built the package while fetching it from GitHub. You don't need to approve the script. |
583
+ | `useToast must be used inside <ToastProvider>` | Wrap your app (or that part of it) in `<ToastProvider>`. |
584
+ | Fonts look different from the screenshots | Load Inter and JetBrains Mono (see [Fonts](#fonts-optional)). |
585
+ | `npm run build` fails on Windows | Use Node 20+ and run from the repo root. The build scripts are written to work on Windows. |
586
+
587
+ ---
588
+
589
+ ## 11. Credits and license
590
+
591
+ MIT © Kaaylabs.
592
+
593
+ The components are adapted from [Beautiful UI](https://www.beautifului.dev) © 2026
594
+ Shane Levine (MIT, see `LICENSE.beautiful-ui`), with shadow styles from
595
+ shadow-plugin © Florian Kiem (MIT).
596
+
597
+ **Changes from upstream:** all demo content moved out of the components into
598
+ `nexi-agent/demo`. Every component takes its text through props and `labels` and
599
+ reports actions through callbacks. The commercial icon set was replaced with free
600
+ `iconoir-react` icons, and global page styles were scoped to `.nexi`. Added:
601
+ `Avatar`, `Badge`, `Tooltip`, `NexiProvider`, `MessageThread`, `Markdown`,
602
+ `EmptyState`, `Dialog`, `ToastProvider`, `UsageMeter` and the playground.