harebear-ui 0.5.0 → 0.7.0

package/AGENTS.md

@@ -14,6 +14,7 @@ Consumers get compiled ESM + types from `dist/` and a Tailwind stylesheet (`hare
 | `pnpm gen`               | Regenerate `src/index.ts` from component export lists. Run after adding or renaming exports.      |
 | `pnpm format`            | Biome format + safe fixes.                                                                        |
 | `pnpm shadcn add <name>` | Pull a new shadcn component into `src/components/ui/`.                                            |
+| `pnpm shots [filter]`    | Regenerate README images in `.github/assets/` (needs `pnpm dev` running, Chrome and `cwebp`).     |
 
 ## Layout
 
@@ -31,8 +32,11 @@ src/
   hooks/, lib/utils.ts  Shared hooks and cn().
 playground/screens/     Reference screens that use only public exports (#admin, #chat, #records, #home, #auth, #catalog). Visual spec and usage examples.
 docs/COMPONENTS.md      Consumer-facing catalog. Shipped. Test-enforced to mention every export.
+docs/guides/            Getting started (per framework), theming, working with agents. Shipped.
 llms.txt, skills/       Consumer-facing agent docs. Shipped.
-bin/harebear-ui.mjs     `npx harebear-ui init|docs` for consuming apps.
+bin/harebear-ui.mjs     `npx harebear-ui init|docs [name...]` for consuming apps. Zero dependencies.
+scripts/screenshots.mjs `pnpm shots`: captures playground screens and renders .github/assets/art/*.html to images.
+.github/assets/         README imagery (not shipped): logo.svg, screens/*.webp, hero/light-dark/agents art, social.png.
 test/                   Vitest: API snapshot, docs coverage, token integrity, behavior.
 ```
 
@@ -41,11 +45,24 @@ test/                   Vitest: API snapshot, docs coverage, token integrity, be
 1. Pick the folder by purpose (`admin`, `data`, `ai`, `auth`; `ui` only for shadcn primitives).
 2. Follow the existing files: `"use client"` first line, named function component, props interface exported as `<Name>Props`, `data-slot="<kebab-name>"` on the root, `className` merged last with `cn()`, rest props spread on the root.
 3. Style only with tokens (`bg-card`, `text-muted-foreground`, `bg-primary-soft`, `shadow-card`, `rounded-xl`). No hex, no palette colors. Status takes a `tone` (`success | warning | danger | info | neutral`).
-4. `pnpm gen`, then add the component to `docs/COMPONENTS.md` (the docs test fails otherwise) and to the index in `llms.txt`.
+4. `pnpm gen`, then add the component to `docs/COMPONENTS.md` (the docs test fails otherwise) and to the index in `llms.txt`. Use a heading like ``### `Name` `` or a table row with the name in backticks, so `npx harebear-ui docs Name` finds it.
 5. Use it in a playground screen if it is visual, and look at it in light and dark mode and at 375px width.
 6. Add a behavior test in `test/components.test.tsx` if it has logic. `pnpm test -u` to accept the new export in the snapshot.
 7. `pnpm check`.
 
+## Looking at your work
+
+- `pnpm dev`, then open http://localhost:5199/#admin (or `#chat`, `#agent`, `#records`, `#home`, `#auth`, `#catalog`).
+- `?mode=dark` or `?mode=light` pins the theme without touching localStorage; `?shot` hides the screen switcher. Example: http://localhost:5199/?mode=dark&shot#agent
+- A headless capture: `pnpm shots admin` writes `.github/assets/screens/admin-*.webp`.
+
+## README imagery
+
+- `.github/assets/logo.svg` is the mark. It is hand-written SVG; edit it directly. `logo.png` is exported from it.
+- Screens are real playground captures. Art (`hero`, `light-dark`, `agents`) is HTML in `.github/assets/art/` that composes those captures, rendered by `pnpm shots`. `social.png` is the hero at 1x for GitHub's social preview (upload it by hand in repo Settings).
+- After a visible change to a screen or the theme, run `pnpm shots` and commit the images with the change. Check the results by eye before committing.
+- If `npx harebear-ui init` output changes, update the terminal text in `art/agents.html` to match.
+
 ## Changing shadcn primitives
 
 - Keep upstream file structure so `pnpm shadcn add <name> -o` diffs stay readable. Change class strings, add variants; avoid restructuring.

package/README.md

@@ -1,28 +1,72 @@
-# harebear-ui
-
-Pre-themed React components for admin tools, data apps, and AI chat. shadcn/ui primitives restyled to one opinionated design system, plus the composites you end up building every time: app shell, KPI cards, data table, trend charts, chat thread, prompt composer, model picker.
-
-React 19 · Tailwind CSS v4 · Radix · TanStack Table v9 · Recharts 3 · TypeScript
-
-## Install
+<p align="center">
+  <img src=".github/assets/logo.svg" width="72" height="72" alt="harebear-ui logo" />
+</p>
+
+<h1 align="center">harebear-ui</h1>
+
+<p align="center">
+  Pre-themed React components for admin tools, data apps and AI chat.<br />
+  shadcn/ui restyled to one design system, plus the composites you build every time. Agent-ready out of the box.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/harebear-ui"><img src="https://img.shields.io/npm/v/harebear-ui?style=flat-square&color=5b84ff&labelColor=101012" alt="npm version" /></a>
+  <a href="https://github.com/HMilbradt/harebear-ui/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/HMilbradt/harebear-ui/ci.yml?branch=main&style=flat-square&labelColor=101012&label=CI" alt="CI status" /></a>
+  <img src="https://img.shields.io/badge/React-19-5b84ff?style=flat-square&labelColor=101012" alt="React 19" />
+  <img src="https://img.shields.io/badge/Tailwind_CSS-v4-a98ae0?style=flat-square&labelColor=101012" alt="Tailwind CSS v4" />
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/harebear-ui?style=flat-square&color=3cb8a8&labelColor=101012" alt="MIT license" /></a>
+</p>
+
+<p align="center">
+  <img src=".github/assets/hero.webp" alt="harebear-ui: an admin dashboard, an agent chat with approvals and a records table, all in dark mode" />
+</p>
+
+<p align="center">
+  <a href="docs/guides/getting-started.md"><b>Get started</b></a> ·
+  <a href="docs/COMPONENTS.md"><b>Components</b></a> ·
+  <a href="docs/guides/theming.md"><b>Theming</b></a> ·
+  <a href="docs/guides/agents.md"><b>AI agents</b></a> ·
+  <a href="playground/screens"><b>Reference screens</b></a>
+</p>
+
+## Why
+
+Every internal tool, dashboard and chat app ends up needing the same pieces: an app shell with a collapsible sidebar, KPI cards, a sortable table with a detail panel, trend charts, a chat thread with a composer and tool calls. shadcn/ui gives you primitives to build them. harebear-ui gives you them built, in one consistent look, so you (or your agent) spend the time on the product.
+
+- **Every shadcn/ui primitive**, same names and props, restyled to one set of tokens.
+- **Composites on top:** `AppShell`, `StatCard`, `DataTable`, `TrendChart`, `ChatShell`, `PromptInput`, `ToolStep`, `ApprovalCard`, `LoginForm` and more.
+- **Light and dark from one accent.** Change the brand color, radius and font with props or CSS variables.
+- **Docs agents can use.** `npx harebear-ui init` installs project rules and a Claude Code skill; `npx harebear-ui docs DataTable` prints one component's API.
+
+## Screens
+
+Built only from public exports. Each one is a file in [`playground/screens/`](playground/screens) you can copy from.
+
+<table>
+  <tr>
+    <td width="50%"><a href="playground/screens/admin.tsx"><img src=".github/assets/screens/admin-dark.webp" alt="Admin dashboard with KPI cards, a visitors trend chart and traffic sources" /></a><br /><b>Admin dashboard</b>: <code>AppShell</code>, <code>StatCard</code>, <code>TrendChart</code>, <code>BarList</code></td>
+    <td width="50%"><a href="playground/screens/agent.tsx"><img src=".github/assets/screens/agent-dark.webp" alt="Agent chat waiting on a command approval, with a details panel" /></a><br /><b>Agent with approvals</b>: <code>ChatShell</code>, <code>ToolGroup</code>, <code>ApprovalCard</code></td>
+  </tr>
+  <tr>
+    <td width="50%"><a href="playground/screens/chat.tsx"><img src=".github/assets/screens/chat-dark.webp" alt="AI chat with a conversation list, highlighted code and a prompt composer" /></a><br /><b>AI chat</b>: <code>ChatPanel</code>, <code>ChatMessage</code>, <code>CodeSnippet</code>, <code>PromptInput</code></td>
+    <td width="50%"><a href="playground/screens/records.tsx"><img src=".github/assets/screens/records-dark.webp" alt="Customer table with status badges and a detail panel for the selected row" /></a><br /><b>Records</b>: <code>DataTable</code>, <code>KeyValueGrid</code>, <code>Timeline</code></td>
+  </tr>
+  <tr>
+    <td width="50%"><a href="playground/screens/home.tsx"><img src=".github/assets/screens/home-dark.webp" alt="Status home page with service tiles and uptime bars" /></a><br /><b>Status home</b>: <code>LinkTile</code>, <code>StatusBars</code>, <code>Sparkline</code></td>
+    <td width="50%"><a href="playground/screens/auth.tsx"><img src=".github/assets/screens/auth-dark.webp" alt="Sign-in page" /></a><br /><b>Auth</b>: <code>AuthLayout</code>, <code>LoginForm</code>, <code>SignupForm</code></td>
+  </tr>
+</table>
+
+## Quick start
+
+Needs React 19 and Tailwind CSS v4.
 
 ```bash
 npm i harebear-ui
-```
-
-```bash
 npx harebear-ui init
 ```
 
-`init` adds the stylesheet import to your Tailwind entry CSS, writes a harebear-ui section into `AGENTS.md` (or `CLAUDE.md`), and installs a Claude Code skill in `.claude/skills/`. Flags: `--css <file>`, `--no-agents`, `--no-skill`.
-
-Manual setup, if you prefer:
-
-```css
-/* app.css */
-@import "tailwindcss";
-@import "harebear-ui/styles.css";
-```
+`init` adds the stylesheet import after `@import "tailwindcss"`, writes a harebear-ui section into `AGENTS.md` (or `CLAUDE.md`), and installs a Claude Code skill. Then wrap your root:
 
 ```tsx
 import { ThemeProvider, Toaster, TooltipProvider } from "harebear-ui"
@@ -39,24 +83,26 @@ export function Root() {
 }
 ```
 
-Requires Tailwind CSS v4 in the app. Geist and Geist Mono are bundled.
-
-## Use
+And build:
 
 ```tsx
-import { AppShell, PageHeader, StatCard, Button, DataTable } from "harebear-ui"
+import { AppShell, Button, DataTable, PageHeader, StatCard } from "harebear-ui"
 ```
 
-Everything imports from the package root. Primitives keep shadcn/ui names and props.
+Everything imports from the package root. Geist and Geist Mono are bundled.
 
-- **Component catalog:** [docs/COMPONENTS.md](docs/COMPONENTS.md), also at `node_modules/harebear-ui/docs/COMPONENTS.md` or `npx harebear-ui docs`.
-- **Reference screens:** [playground/screens](playground/screens) has an admin dashboard, an AI chat, a data table with detail panel, and a status home page built only from public exports.
+Step-by-step setup for **Vite**, **Next.js** and **React Router**, plus troubleshooting: [Getting started](docs/guides/getting-started.md).
 
 ## Theming
 
-Light and dark mode, accent, radius, and font are runtime props on `ThemeProvider` (`useTheme()` changes them live). Every component reads shadcn-named tokens, so you can override any of them in CSS:
+<img src=".github/assets/light-dark.webp" alt="The same admin dashboard split diagonally between light and dark mode" />
+
+Light, dark and system modes, accent, radius and font are `ThemeProvider` props, changeable live with `useTheme()`. Every component reads shadcn-named tokens, so you can override any of them in CSS:
 
 ```css
+@import "tailwindcss";
+@import "harebear-ui/styles.css";
+
 :root {
   --brand: #0f8a7e;
   --radius: 0.625rem;
@@ -66,19 +112,42 @@ Light and dark mode, accent, radius, and font are runtime props on `ThemeProvide
 }
 ```
 
-For SSR apps, render `<ThemeScript />` in `<head>` to avoid a flash of the wrong mode.
+SSR apps render `<ThemeScript />` in `<head>` to avoid a flash of the wrong mode. More in [Theming](docs/guides/theming.md).
 
-## For AI agents
+## Built for AI agents
 
-The package ships its own agent docs:
+<img src=".github/assets/agents.webp" alt="Terminal running harebear-ui init and docs, with the four agent files it sets up" />
 
-| File                          | For                                                    |
-| ----------------------------- | ------------------------------------------------------ |
-| `llms.txt`                    | Short index: setup, rules, component list.             |
-| `docs/COMPONENTS.md`          | Every export with props and examples.                  |
-| `skills/harebear-ui/SKILL.md` | Claude Code skill; `npx harebear-ui init` installs it. |
+The package carries its own agent docs, so Claude Code, Codex, Cursor and friends know what exists and how to use it:
 
-Working on this repo with an agent: see [AGENTS.md](AGENTS.md).
+| File                          | For                                                                   |
+| ----------------------------- | --------------------------------------------------------------------- |
+| `llms.txt`                    | Short index: setup, rules, every export by group.                     |
+| `docs/COMPONENTS.md`          | Every export with props and examples. Test-enforced to stay complete. |
+| `docs/guides/`                | Setup per framework, theming, working with agents.                    |
+| `skills/harebear-ui/SKILL.md` | Claude Code skill; `npx harebear-ui init` installs it.                |
+
+Agents look up one component at a time instead of reading the whole catalog:
+
+```bash
+npx harebear-ui docs DataTable StatCard   # exports
+npx harebear-ui docs Prompt               # prefix: PromptInput, PromptInputChip, PromptInputSelect
+npx harebear-ui docs Tokens               # a section
+```
+
+Prompts that work, and what to check before you accept an agent's UI: [Working with AI agents](docs/guides/agents.md).
+
+## What's inside
+
+| Group         | Exports                                                                                                                     |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Layout, admin | `SidebarLayout`, `AppShell`, `PageHeader`, `StatCard`, `StatusBadge`, `UsageMeter`, `Timeline`, `UserMenu`, `ConfirmDialog` |
+| Data          | `DataTable`, `TrendChart`, `BarList`, `Sparkline`, `StatusBars`                                                             |
+| AI and chat   | `ChatShell`, `ChatPanel`, `ChatMessage`, `PromptInput`, `ModelPicker`, `ToolGroup`, `ApprovalCard`, `CodeSnippet`, `Prose`  |
+| Auth          | `AuthLayout`, `LoginForm`, `SignupForm`                                                                                     |
+| Primitives    | The full shadcn/ui registry: `Button`, `Dialog`, `Select`, `Sidebar`, `Tabs`, `Command`, `Chart`, and the rest              |
+
+The full list with props: [docs/COMPONENTS.md](docs/COMPONENTS.md).
 
 ## Develop
 
@@ -86,8 +155,11 @@ Working on this repo with an agent: see [AGENTS.md](AGENTS.md).
 pnpm install
 pnpm dev     # playground on :5199
 pnpm check   # lint, typecheck, test, build, package lint
+pnpm shots   # regenerate the README images (needs pnpm dev running, Chrome and cwebp)
 ```
 
+Working on this repo with an agent: see [AGENTS.md](AGENTS.md).
+
 ## License
 
 MIT

package/bin/harebear-ui.mjs

@@ -24,6 +24,7 @@ const AGENT_BLOCK = `${START}
 All UI in this project uses the \`harebear-ui\` component library (pre-themed shadcn/ui on Tailwind v4, plus admin, data table, chart, and AI chat components).
 
 - Read \`node_modules/harebear-ui/docs/COMPONENTS.md\` before building UI. It lists every component with props and examples.
+- Look up single entries with \`npx harebear-ui docs DataTable PromptInput\` (export names, a prefix, or a section such as \`Tokens\`).
 - Import from the package root: \`import { Button, Card, DataTable } from "harebear-ui"\`.
 - Style only with theme tokens (\`bg-card\`, \`bg-muted\`, \`text-muted-foreground\`, \`bg-primary-soft\`, \`text-success\`, \`shadow-card\`, \`rounded-xl\`). No hex or Tailwind palette colors.
 - Check new screens in light and dark mode and at phone width.
@@ -86,6 +87,50 @@ function installSkill() {
   console.log(`✓ Installed Claude Code skill to ${relative(cwd, destDir)}/SKILL.md`)
 }
 
+// Backticked identifiers in a heading or table cell: "`ChatMessage`" -> "chatmessage".
+const namesIn = (text) => [...text.matchAll(/`([A-Za-z]\w*)/g)].map((m) => m[1].toLowerCase())
+
+// The parts of the catalog about one export or section: "### `Name`" sections, primitive table rows
+// (with their table header), or a whole "## Section" by title. Exact names first, then prefix matches.
+function lookup(catalog, query) {
+  const q = query.toLowerCase()
+  const blocks = catalog.split(/^(?=#{2,3} )/m)
+  const section = blocks.find((b) => b.startsWith("## ") && b.split("\n", 1)[0].slice(3).toLowerCase() === q)
+  if (section) {
+    // A "## Section" block stops at its first "###"; take the subsections that follow it too.
+    const start = blocks.indexOf(section)
+    const end = blocks.findIndex((b, i) => i > start && b.startsWith("## "))
+    return blocks
+      .slice(start, end < 0 ? undefined : end)
+      .join("")
+      .trimEnd()
+  }
+  for (const match of [(n) => n === q, (n) => n.startsWith(q)]) {
+    const out = blocks.filter((b) => b.startsWith("### ") && namesIn(b.split("\n", 1)[0]).some(match))
+    let header = []
+    let headerShown = null
+    const rows = []
+    for (const line of catalog.split("\n")) {
+      if (!line.startsWith("|")) {
+        header = []
+        continue
+      }
+      if (header.length < 2) {
+        header.push(line)
+        continue
+      }
+      const [, first = "", second = ""] = line.split("|")
+      if (!namesIn(first + second).some(match)) continue
+      if (headerShown !== header) rows.push(...header)
+      headerShown = header
+      rows.push(line)
+    }
+    if (rows.length) out.push(rows.join("\n"))
+    if (out.length) return out.map((b) => b.trimEnd()).join("\n\n")
+  }
+  return undefined
+}
+
 switch (cmd) {
   case "init": {
     if (!existsSync(join(cwd, "package.json"))) {
@@ -109,9 +154,25 @@ Next: wrap your app root.
 `)
     break
   }
-  case "docs":
-    process.stdout.write(readFileSync(join(pkgRoot, "docs/COMPONENTS.md"), "utf8"))
+  case "docs": {
+    const catalog = readFileSync(join(pkgRoot, "docs/COMPONENTS.md"), "utf8")
+    const queries = args.filter((a) => !a.startsWith("--"))
+    if (queries.length === 0) {
+      process.stdout.write(catalog)
+      break
+    }
+    let missed = false
+    for (const q of queries) {
+      const found = lookup(catalog, q)
+      if (found) process.stdout.write(`${found}\n\n`)
+      else {
+        missed = true
+        console.error(`! Nothing in the catalog for "${q}". Run \`npx harebear-ui docs\` for the full catalog.`)
+      }
+    }
+    if (missed) process.exitCode = 1
     break
+  }
   default:
     console.log(`harebear-ui
 
@@ -119,7 +180,9 @@ Next: wrap your app root.
       Add the stylesheet import after @import "tailwindcss", add a harebear-ui
       section to AGENTS.md (or CLAUDE.md), and install the Claude Code skill.
 
-  npx harebear-ui docs
+  npx harebear-ui docs [name...]
       Print the component catalog (props and examples for every export).
+      With names, print only those entries: an export (DataTable, Button),
+      a name prefix (Prompt), or a section title (Tokens, Auth).
 `)
 }

package/dist/components/admin/status.d.ts

@@ -12,7 +12,9 @@ export interface StatusBadgeProps extends React.ComponentProps<typeof Badge> {
   tone?: StatusTone;
   /** Pulse the dot. */
   pulse?: boolean;
+  /** Below 640px show only the dot; the label stays for screen readers. For crowded mobile headers. */
+  compact?: boolean;
 }
 /** Pill with a status dot and label, e.g. Paid / Pending / Refunded. `size="lg"` lines up with sm buttons. */
-declare function StatusBadge({ tone, pulse, variant, children, className, ...props }: StatusBadgeProps): React.JSX.Element;
+declare function StatusBadge({ tone, pulse, compact, variant, children, className, ...props }: StatusBadgeProps): React.JSX.Element;
 export { StatusBadge, StatusDot };

package/dist/components/admin/status.js

@@ -20,7 +20,7 @@ function StatusDot({ tone = "neutral", pulse, className, ...props }) {
 	});
 }
 /** Pill with a status dot and label, e.g. Paid / Pending / Refunded. `size="lg"` lines up with sm buttons. */
-function StatusBadge({ tone = "neutral", pulse, variant = "secondary", children, className, ...props }) {
+function StatusBadge({ tone = "neutral", pulse, compact, variant = "secondary", children, className, ...props }) {
 	return /* @__PURE__ */ jsxs(Badge, {
 		"data-slot": "status-badge",
 		variant,
@@ -29,7 +29,10 @@ function StatusBadge({ tone = "neutral", pulse, variant = "secondary", children,
 		children: [/* @__PURE__ */ jsx(StatusDot, {
 			tone,
 			pulse
-		}), children]
+		}), compact ? /* @__PURE__ */ jsx("span", {
+			className: "sr-only sm:not-sr-only",
+			children
+		}) : children]
 	});
 }
 export { StatusBadge, StatusDot };

package/dist/components/ai/approval.d.ts

@@ -14,12 +14,14 @@ export interface ApprovalCardProps extends Omit<React.ComponentProps<"section">,
   actions?: React.ReactNode;
   /** Small print under the actions. */
   footer?: React.ReactNode;
+  /** Why the agent wants this, shown first in the body after a bold "Why:". */
+  reason?: React.ReactNode;
 }
 /**
  * Highlighted card for anything the agent is waiting on the user for: a tool approval, a question, a choice.
  * Body text goes in children (e.g. the agent's reason).
  */
-declare function ApprovalCard({ title, description, icon, code, codeLabel, actions, footer, className, children, ...props }: ApprovalCardProps): React.JSX.Element;
+declare function ApprovalCard({ title, description, icon, code, codeLabel, actions, footer, reason, className, children, ...props }: ApprovalCardProps): React.JSX.Element;
 export interface ApprovalResultProps extends React.ComponentProps<"div"> {
   decision: "approved" | "denied";
   /** Trailing time, e.g. "10:42". */

package/dist/components/ai/approval.js

@@ -9,7 +9,7 @@ import { CheckIcon, ShieldAlertIcon, XIcon } from "lucide-react";
 * Highlighted card for anything the agent is waiting on the user for: a tool approval, a question, a choice.
 * Body text goes in children (e.g. the agent's reason).
 */
-function ApprovalCard({ title, description, icon = /* @__PURE__ */ jsx(ShieldAlertIcon, {}), code, codeLabel, actions, footer, className, children, ...props }) {
+function ApprovalCard({ title, description, icon = /* @__PURE__ */ jsx(ShieldAlertIcon, {}), code, codeLabel, actions, footer, reason, className, children, ...props }) {
 	const id = React.useId();
 	return /* @__PURE__ */ jsxs("section", {
 		"data-slot": "approval-card",
@@ -34,9 +34,12 @@ function ApprovalCard({ title, description, icon = /* @__PURE__ */ jsx(ShieldAle
 					})]
 				})]
 			}),
-			children && /* @__PURE__ */ jsx("div", {
+			(reason || children) && /* @__PURE__ */ jsxs("div", {
 				className: "text-[14.5px] leading-relaxed whitespace-pre-wrap wrap-anywhere [&_strong]:font-semibold",
-				children
+				children: [reason && /* @__PURE__ */ jsxs("p", { children: [/* @__PURE__ */ jsx("strong", { children: "Why: " }), reason] }), reason && children ? /* @__PURE__ */ jsx("div", {
+					className: "mt-2",
+					children
+				}) : children]
 			}),
 			code !== void 0 && /* @__PURE__ */ jsxs(CodeBlock, { children: [/* @__PURE__ */ jsxs(CodeBlockHeader, { children: [/* @__PURE__ */ jsx(CodeBlockTitle, { children: codeLabel ?? "command" }), /* @__PURE__ */ jsx(CodeBlockActions, { children: /* @__PURE__ */ jsx(CodeBlockCopyButton, { value: code }) })] }), /* @__PURE__ */ jsx(CodeBlockContent, {
 				wrap: true,

package/dist/components/ai/chat.d.ts

@@ -10,8 +10,11 @@ export interface ChatThreadProps extends React.ComponentProps<"div"> {
 declare function ChatThread({ autoScroll, className, contentClassName, children, ...props }: ChatThreadProps): React.JSX.Element;
 export interface ChatMessageProps extends React.ComponentProps<"div"> {
   role: "user" | "assistant";
-  /** Assistant avatar. Defaults to a sparkle in a tinted circle. */
-  avatar?: React.ReactNode;
+  /**
+   * Assistant avatar. Defaults to a sparkle in a tinted circle. `false` renders no avatar and lets the content use
+   * the full width, for agent threads where one turn is many blocks (text, tool groups, approvals).
+   */
+  avatar?: React.ReactNode | false;
   /** Rendered under assistant content, usually <MessageActions />. */
   actions?: React.ReactNode;
   /** User bubble color: "muted" (gray, default) or "soft" (tinted with the accent). */

package/dist/components/ai/chat.js

@@ -58,7 +58,7 @@ function ChatMessage({ role, avatar, actions, variant = "muted", className, chil
 		"data-role": "assistant",
 		className: cn("flex items-start gap-4", className),
 		...props,
-		children: [avatar ?? /* @__PURE__ */ jsx(AssistantAvatar, {}), /* @__PURE__ */ jsxs("div", {
+		children: [avatar === false ? null : avatar ?? /* @__PURE__ */ jsx(AssistantAvatar, {}), /* @__PURE__ */ jsxs("div", {
 			className: "flex min-w-0 flex-1 flex-col gap-3.5",
 			children: [children, actions]
 		})]

package/dist/components/ai/code-block.d.ts

@@ -17,7 +17,11 @@ export interface CodeSnippetProps extends Omit<React.ComponentProps<typeof CodeB
  */
 declare function CodeSnippet({ code, language, highlight, lineNumbers, hideCopy, className, ...props }: CodeSnippetProps): React.JSX.Element;
 /** Inline monospace span for commands and identifiers. */
-declare function InlineCode({ className, ...props }: React.ComponentProps<"code">): React.JSX.Element;
+export interface InlineCodeProps extends React.ComponentProps<"code"> {
+  /** Cut string children longer than this many characters with an ellipsis; the full text becomes the tooltip. */
+  truncate?: number;
+}
+declare function InlineCode({ truncate, className, children, title, ...props }: InlineCodeProps): React.JSX.Element;
 /**
  * Typography for long-form and model output. Styles plain HTML children
  * (p, ul, ol, li, strong, a, code, pre, h1-h4, blockquote, table), so it works

package/dist/components/ai/code-block.js

@@ -40,12 +40,14 @@ function CodeSnippet({ code, language, highlight = true, lineNumbers, hideCopy,
 		})]
 	});
 }
-/** Inline monospace span for commands and identifiers. */
-function InlineCode({ className, ...props }) {
+function InlineCode({ truncate, className, children, title, ...props }) {
+	const cut = truncate !== void 0 && typeof children === "string" && children.length > truncate;
 	return /* @__PURE__ */ jsx("code", {
 		"data-slot": "inline-code",
+		title: title ?? (cut ? children : void 0),
 		className: cn("rounded-[6px] bg-muted px-1.5 py-0.5 font-mono text-[12.5px]", className),
-		...props
+		...props,
+		children: cut ? `${children.slice(0, truncate)}…` : children
 	});
 }
 /**

package/dist/components/ai/conversation-list.d.ts

@@ -10,6 +10,8 @@ export interface Conversation {
   tone?: StatusTone;
   /** Pulse the status dot. */
   pulse?: boolean;
+  /** With `onDelete`: block deleting this row. A string is shown as the reason, e.g. "Stop the agent first". */
+  deleteDisabled?: boolean | string;
 }
 export interface ConversationGroup {
   /** e.g. "Today", "Yesterday", "Previous 7 days". */
@@ -22,6 +24,13 @@ export interface ConversationListProps extends Omit<React.ComponentProps<"nav">,
   onSelect?: (id: string) => void;
   /** Trailing control per row, e.g. a delete button. On devices that can hover it shows on hover and focus; on touch it is always visible. */
   renderAction?: (conversation: Conversation) => React.ReactNode;
+  /**
+   * Adds a delete button to each row that asks for confirmation first, then calls this. Ignored when `renderAction`
+   * is set. Use `Conversation.deleteDisabled` to block it per row.
+   */
+  onDelete?: (conversation: Conversation) => void;
+  /** Body of the delete confirmation. Default "This cannot be undone." */
+  deleteDescription?: React.ReactNode;
   /** Shown when there are no conversations. Default "No conversations yet". */
   empty?: React.ReactNode;
 }
@@ -29,12 +38,17 @@ export interface ConversationListProps extends Omit<React.ComponentProps<"nav">,
  * Grouped list of chat threads for a sidebar. Inside a Sidebar it closes the mobile sheet on select,
  * and hides itself when the sidebar is collapsed to its icon rail.
  */
-declare function ConversationList({ groups, activeId, onSelect, renderAction, empty, className, ...props }: ConversationListProps): React.JSX.Element;
+declare function ConversationList({ groups, activeId, onSelect, renderAction, onDelete, deleteDescription, empty, className, ...props }: ConversationListProps): React.JSX.Element;
 /**
  * Buckets items into Today / Yesterday / Previous 7 days / Earlier by a timestamp (ms or Date),
  * newest first, and drops empty groups. Pass `now` for deterministic tests.
  */
 declare function groupByDate<T>(items: T[], getDate: (item: T) => number | Date, toConversation: (item: T) => Conversation, now?: number | Date): ConversationGroup[];
+/**
+ * Short timestamp for lists and headers: the time today ("9:41 AM"), the date this year ("Nov 3"), else with the
+ * year ("Nov 3, 2025"). Uses the browser locale unless `locale` is given. Pass `now` for deterministic tests.
+ */
+declare function formatWhen(date: number | Date, now?: number | Date, locale?: string | string[]): string;
 export interface NewConversationButtonProps extends React.ComponentProps<typeof Button> {
   /** Default "New conversation". */
   label?: string;
@@ -48,4 +62,4 @@ export interface NewConversationButtonProps extends React.ComponentProps<typeof
  * tooltip; on mobile it closes the sidebar sheet after the click.
  */
 declare function NewConversationButton({ label, icon, shortcut, variant, onClick, className, ...props }: NewConversationButtonProps): React.JSX.Element;
-export { ConversationList, NewConversationButton, groupByDate };
+export { ConversationList, NewConversationButton, formatWhen, groupByDate };