@candor-ui/react 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Methodic LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This licence covers only the free-tier items listed in scripts/tiers.json. See
+LICENSE.md.

package/README.md

@@ -1,3 +1,188 @@
-# Temporary Holding Version
+# @candor-ui/react
 
-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.
+Candor UI's free tier as an npm package: React components and hooks for agent chat (thread, messages, tool calls,
+reasoning, composer, citations), the building blocks they use, the theme, and adapters for the Vercel AI SDK, the
+Claude Agent SDK and AG-UI. MIT licensed. By [Methodic LLC](https://themethodic.com).
+
+It's the same code as the free `@candor/*` items in the shadcn registry, for people who'd rather `npm install` than
+copy code into their app. If you want to own and edit the source, install with the shadcn CLI instead
+(`npx shadcn@latest add @candor/thread ...`); see https://candor.themethodic.com.
+
+> **Pro and Premium items aren't on npm.** This package contains only the free (MIT) tier. Pro components and Premium
+> blocks and templates install through the licensed shadcn registry (`@candor` with your licence key), not npm.
+
+## Install
+
+```bash
+npm install @candor-ui/react
+```
+
+Needs React 19 and Tailwind CSS 4. Radix, lucide-react, class-variance-authority, clsx, tailwind-merge, the Inter font
+and tw-animate-css come with it.
+
+## Styles (Tailwind 4)
+
+The components are styled with Tailwind classes and Candor's tokens. Import the theme after Tailwind in your global CSS:
+
+```css
+@import "tailwindcss";
+@import "@candor-ui/react/styles.css";
+```
+
+`styles.css` brings Candor's tokens (colours, type scale, radii, shadows, motion), the light, dark and high-contrast
+themes, Inter, tw-animate-css and an `@source` for the package's own files, so Tailwind generates the classes the
+components use even though it skips `node_modules` when scanning your app. If your setup doesn't follow `@source`
+from imported CSS, add it yourself, relative to your CSS file:
+
+```css
+@source "../node_modules/@candor-ui/react/dist";
+```
+
+Themes switch with `data-theme="light" | "dark" | "hc"` on `<html>`; with no attribute they follow the system. To
+restyle, override the roles after the import: colours by their shadcn names (`--primary`, `--background`...),
+everything else by its `--cd-*` name.
+
+If your CSS already defines shadcn's variables (e.g. `create-next-app`'s or `shadcn init`'s `globals.css`), remove
+those `:root`, `.dark` and `@theme inline` blocks or put them before the import, and don't redefine `--font-sans`
+after it.
+
+## Components
+
+```tsx
+"use client"
+import * as React from "react"
+import { Thread, Message, Composer, type MessageData } from "@candor-ui/react"
+
+const messages: MessageData[] = [
+  { id: "1", author: { role: "user" }, status: "complete", blocks: [{ kind: "paragraph", nodes: [{ kind: "text", text: "Hi" }] }] },
+]
+
+export function Chat() {
+  const [value, setValue] = React.useState("")
+  return (
+    <Thread footer={<Composer value={value} onChange={setValue} onSubmit={() => setValue("")} />}>
+      {messages.map((m) => <Message key={m.id} message={m} />)}
+    </Thread>
+  )
+}
+```
+
+The main entry exports every free component, hook and type, plus `cn`. Two names are shared by a component and a data
+type; the component keeps the name and the type gets a `Data` suffix: `Message` / `MessageData`, `ToolCall` /
+`ToolCallData`.
+
+Client components carry `"use client"`, so they work from Server Components in the Next.js App Router. Hooks
+(`useCopy`, `useCandorChat`...) are for client components, as usual.
+
+## With the Vercel AI SDK: `@candor-ui/react/ai-sdk`
+
+```bash
+npm install ai @ai-sdk/react
+```
+
+```tsx
+"use client"
+import { useChat } from "@ai-sdk/react"
+import { Thread, Message, Composer } from "@candor-ui/react"
+import { useCandorChat } from "@candor-ui/react/ai-sdk"
+
+export function Chat() {
+  const chat = useChat()
+  const { messages, composer, approvals, respond } = useCandorChat(chat, { agent: { id: "a", name: "Assistant", role: "assistant" } })
+  return (
+    <Thread footer={<Composer {...composer} />}>
+      {messages.map((m) => <Message key={m.id} message={m} />)}
+    </Thread>
+  )
+}
+```
+
+Also exports `fromAiSdkMessages` / `fromAiSdkMessage` to map `UIMessage`s yourself.
+
+## With the Claude Agent SDK: `@candor-ui/react/claude` and `@candor-ui/react/claude/server`
+
+```bash
+npm install @anthropic-ai/claude-agent-sdk
+```
+
+The agent runs on your server. `@candor-ui/react/claude/server` is **server only** (it needs Node and your
+credentials); the main entry and the client subpaths never import it.
+
+```ts
+// app/api/agent/route.ts
+import { query } from "@anthropic-ai/claude-agent-sdk"
+import { streamClaudeAgent } from "@candor-ui/react/claude/server"
+
+export async function POST(request: Request) {
+  const { prompt, sessionId } = await request.json()
+  return streamClaudeAgent(
+    ({ canUseTool, abortController }) =>
+      query({ prompt, options: { canUseTool, abortController, resume: sessionId, includePartialMessages: true } }),
+    { signal: request.signal, owner: userId },
+  )
+}
+
+// app/api/agent/approve/route.ts
+import { answerClaudeAgentApproval } from "@candor-ui/react/claude/server"
+
+export async function POST(request: Request) {
+  const { id, approved, reason } = await request.json()
+  return Response.json({ ok: answerClaudeAgentApproval(id, approved, reason, userId) })
+}
+```
+
+```tsx
+"use client"
+import { useClaudeAgent } from "@candor-ui/react/claude"
+
+const { messages, composer, approvals, respond, usage } = useClaudeAgent({ api: "/api/agent", approveApi: "/api/agent/approve", agent })
+```
+
+`@candor-ui/react/claude` also exports `fromClaudeAgentEvents` and the event types. Waiting permission requests live
+in the server process's memory: run the agent on one Node server or container, not serverless functions spread over
+instances.
+
+## With AG-UI: `@candor-ui/react/ag-ui`
+
+```bash
+npm install @ag-ui/client @ag-ui/core
+```
+
+```tsx
+"use client"
+import { useAgUi } from "@candor-ui/react/ag-ui"
+
+const { messages, composer, approvals, respond } = useAgUi({ url: "/api/agent", agent })
+```
+
+Also exports `fromAgUiEvents` and the event types.
+
+## Entry points
+
+| Import | Contents | Needs |
+| --- | --- | --- |
+| `@candor-ui/react` | components, hooks, types, `cn` | react, react-dom |
+| `@candor-ui/react/ai-sdk` | `useCandorChat`, `fromAiSdkMessages` | `ai`, `@ai-sdk/react` |
+| `@candor-ui/react/claude` | `useClaudeAgent`, `fromClaudeAgentEvents` | `@anthropic-ai/claude-agent-sdk` (types) |
+| `@candor-ui/react/claude/server` | `streamClaudeAgent`, `answerClaudeAgentApproval` (server only) | `@anthropic-ai/claude-agent-sdk` |
+| `@candor-ui/react/ag-ui` | `useAgUi`, `fromAgUiEvents` | `@ag-ui/client`, `@ag-ui/core` |
+| `@candor-ui/react/styles.css` | theme and tokens for Tailwind 4 | tailwindcss 4 |
+
+The SDKs are optional peer dependencies: install only the ones for the subpaths you use.
+
+## Building this package
+
+The contents are generated from the repo at build time, so they can't drift from the registry: the item list is
+`free` in `scripts/tiers.json`, each item's file comes from `registry.json`, and the build fails if a free item imports
+a non-free one.
+
+```bash
+cd packages/react
+npm install --no-package-lock
+npm run build     # dist/
+npm pack          # runs the build first
+```
+
+## Licence
+
+MIT, (c) 2026 Methodic LLC. See [LICENSE](LICENSE).

package/dist/adapters/ag-ui.d.ts

@@ -0,0 +1,75 @@
+import { type Event } from "@ag-ui/core";
+import type { AgentIdentity, EntityRef, Message } from "../lib/chat.js";
+/** Events of Candor's own, mixed into the AG-UI stream by useAgUi. */
+export type CandorAgUiEvent = 
+/** What the user sent. Added in the browser, with the same id as the AG-UI user message. */
+{
+    type: "candor_user";
+    id: string;
+    text: string;
+    references?: EntityRef[];
+}
+/** A person answered an interrupt; the next run resumes with it. */
+ | {
+    type: "candor_answer";
+    interruptId: string;
+    approved: boolean;
+    reason?: string;
+}
+/** The run failed outside the protocol's own events (the request, the stream). */
+ | {
+    type: "candor_error";
+    message: string;
+};
+export type AgUiEvent = Event | CandorAgUiEvent;
+/** An interrupt waiting on a person. */
+export type AgUiApproval = {
+    /** The interrupt's id; answer it with `respond(id, …)`. */
+    id: string;
+    /** The agent's machine-readable reason, e.g. "tool_approval". */
+    reason: string;
+    /** The agent's own sentence for the request, when it sent one. */
+    message?: string;
+    /** A sentence to show: the agent's message, or a plain one naming the tool. */
+    title: string;
+    /** Set when the interrupt asks to run a tool call. */
+    toolCallId?: string;
+    /** The tool's name, when the tool call is in the thread. */
+    tool?: string;
+    /** The tool call's arguments, when they arrived and parse. */
+    input?: unknown;
+    /** When the agent stops waiting (ISO 8601). */
+    expiresAt?: string;
+    /** The shape the agent expects an answer in, when it says. */
+    responseSchema?: Record<string, unknown>;
+};
+/** Tokens the runs reported, summed. A count no run reported stays unknown. AG-UI reports no cost. */
+export type AgUiUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+};
+export type FromAgUiOptions = {
+    /** Who the agent is. Candor always names the agent. */
+    agent: AgentIdentity;
+    /** A run is open now: the last reply is still streaming, and no interrupt can be answered yet. */
+    running?: boolean;
+    /** A plain-words title for a tool call: "Read notes.md". `input` is undefined until the arguments arrive. */
+    toolTitle?: (tool: string, input: unknown) => string | undefined;
+    /** The time to judge interrupt expiry by. Defaults to now. */
+    now?: Date;
+};
+export type AgUiState = {
+    messages: Message[];
+    /** Interrupts waiting on a person, oldest first. Empty while a run is open; expired ones are left out. */
+    approvals: AgUiApproval[];
+    /** The thread the runs belong to. Send it back to continue the conversation. */
+    threadId?: string;
+    usage?: AgUiUsage;
+    /** Something the person should know that isn't part of a reply, such as an expired request. */
+    notice?: string;
+};
+/**
+ * Turns AG-UI events into Candor messages, waiting approvals and usage.
+ * Pure (given `now`), so it can run on every render; useAgUi calls it for you.
+ */
+export declare function fromAgUiEvents(events: AgUiEvent[], options: FromAgUiOptions): AgUiState;