@aigentyc/chat-sdk 0.2.5 → 0.3.0

package/dist/theme.d.cts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-export { T as ThemeConfig } from './types-DKJ_-nbG.cjs';
+export { T as ThemeConfig } from './types-DlNwk-bG.cjs';
 
 /**
  * Theme configuration for the chat widget.

package/dist/theme.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-export { T as ThemeConfig } from './types-DKJ_-nbG.js';
+export { T as ThemeConfig } from './types-DlNwk-bG.js';
 
 /**
  * Theme configuration for the chat widget.

package/dist/tools.cjs

@@ -1,8 +1,9 @@
 "use client";
 'use strict';
 
-var chunkDMGYQ6NN_cjs = require('./chunk-DMGYQ6NN.cjs');
-require('./chunk-J2K7EJYP.cjs');
+var chunk7AZMWPKX_cjs = require('./chunk-7AZMWPKX.cjs');
+var chunkTLGZSXTU_cjs = require('./chunk-TLGZSXTU.cjs');
+require('./chunk-BPV66QNM.cjs');
 require('./chunk-JOO6C3XT.cjs');
 var chunkJ2H6MLQF_cjs = require('./chunk-J2H6MLQF.cjs');
 var chunkQ7T3VAJV_cjs = require('./chunk-Q7T3VAJV.cjs');
@@ -12,17 +13,25 @@ require('./chunk-525KS5HM.cjs');
 
 
 
+Object.defineProperty(exports, "getToolDisplayData", {
+  enumerable: true,
+  get: function () { return chunk7AZMWPKX_cjs.getToolDisplayData; }
+});
+Object.defineProperty(exports, "normalizeToolRows", {
+  enumerable: true,
+  get: function () { return chunk7AZMWPKX_cjs.normalizeToolRows; }
+});
 Object.defineProperty(exports, "ComponentRenderer", {
   enumerable: true,
-  get: function () { return chunkDMGYQ6NN_cjs.ComponentRenderer; }
+  get: function () { return chunkTLGZSXTU_cjs.ComponentRenderer; }
 });
 Object.defineProperty(exports, "SearchKnowledgeBaseRenderer", {
   enumerable: true,
-  get: function () { return chunkDMGYQ6NN_cjs.SearchKnowledgeBaseRenderer; }
+  get: function () { return chunkTLGZSXTU_cjs.SearchKnowledgeBaseRenderer; }
 });
 Object.defineProperty(exports, "ToolRenderer", {
   enumerable: true,
-  get: function () { return chunkDMGYQ6NN_cjs.ToolRenderer; }
+  get: function () { return chunkTLGZSXTU_cjs.ToolRenderer; }
 });
 Object.defineProperty(exports, "JsonRenderResult", {
   enumerable: true,

package/dist/tools.d.cts

@@ -1,7 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { g as ToolRendererProps } from './types-DKJ_-nbG.cjs';
-export { d as ComponentAction, h as ToolResult } from './types-DKJ_-nbG.cjs';
+import { g as ToolRendererProps } from './types-DlNwk-bG.cjs';
+export { d as ComponentAction, h as ToolResult } from './types-DlNwk-bG.cjs';
 export { J as JsonRenderResult } from './JsonRenderResult-Ftw4AKwb.cjs';
+export { g as getToolDisplayData, n as normalizeToolRows } from './normalize-KzCLLqpU.cjs';
 import 'react';
 import '@json-render/core';
 

package/dist/tools.d.ts

@@ -1,7 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { g as ToolRendererProps } from './types-DKJ_-nbG.js';
-export { d as ComponentAction, h as ToolResult } from './types-DKJ_-nbG.js';
+import { g as ToolRendererProps } from './types-DlNwk-bG.js';
+export { d as ComponentAction, h as ToolResult } from './types-DlNwk-bG.js';
 export { J as JsonRenderResult } from './JsonRenderResult-Ftw4AKwb.js';
+export { g as getToolDisplayData, n as normalizeToolRows } from './normalize-KzCLLqpU.js';
 import 'react';
 import '@json-render/core';
 

package/dist/tools.js

@@ -1,6 +1,7 @@
 "use client";
-export { ComponentRenderer, SearchKnowledgeBaseRenderer, ToolRenderer } from './chunk-U3FXVLUK.js';
-import './chunk-FYPJSHCL.js';
+export { getToolDisplayData, normalizeToolRows } from './chunk-XEAAB5ZM.js';
+export { ComponentRenderer, SearchKnowledgeBaseRenderer, ToolRenderer } from './chunk-PQCGQ32Q.js';
+import './chunk-FPQ3UCCJ.js';
 import './chunk-PS3U7T37.js';
 export { JsonRenderResult } from './chunk-RPDJXB3U.js';
 export { VisualizationRenderer } from './chunk-5T4FJ2SR.js';

package/dist/{types-DKJ_-nbG.d.cts → types-DlNwk-bG.d.cts}

@@ -121,12 +121,33 @@ interface SlotMap {
     loader?: ComponentType<SlotProps>;
     /** Custom feedback (thumbs up/down) component */
     feedback?: ComponentType<SlotProps>;
-    /** Per-tool-name component overrides (keyed by tool name) */
+    /**
+     * Per-tool-name component overrides. Keys are tool NAMES (e.g. `searchProducts`,
+     * `calculateSeverance`). Values receive `ToolRendererProps`.
+     *
+     * Use this when you want to render a specific tool's output with custom UI.
+     *
+     * @example
+     * ```tsx
+     * slots={{ tools: { searchProducts: ProductGrid } }}
+     * ```
+     */
     tools?: Record<string, ComponentType<ToolRendererProps>>;
     /**
-     * Per-tool render-mode overrides.
+     * Per-render-mode component overrides. Keys are render MODES (not tool names):
+     * `visualization` | `json_render` | `legacy` | `preset` | `text`.
      *
-     * Keys are tool names, values are components that receive `ToolRendererProps`.
+     * Use this when you want to replace the default renderer for an entire category
+     * of tool outputs (e.g. swap the built-in recharts visualization for your own).
+     *
+     * **Common confusion**: if you want to override a specific tool, use `tools`
+     * (by name), not `toolRenderers` (by mode). Passing a tool name here does
+     * nothing (the SDK will emit a dev warning).
+     *
+     * @example
+     * ```tsx
+     * slots={{ toolRenderers: { visualization: MyChartRenderer } }}
+     * ```
      */
     toolRenderers?: Record<string, ComponentType<ToolRendererProps>>;
     /** Custom live-chat panel */
@@ -275,6 +296,15 @@ interface ChatEventCallbacks {
     onLiveChatEnded?: (endedBy: string) => void;
     /** Fired on any error (network, auth, etc.) */
     onError?: (error: Error) => void;
+    /**
+     * Fired when the user starts a brand-new conversation (clearMessages + new
+     * sessionId). Useful for resetting external state the consumer tracks.
+     */
+    onNewConversation?: (sessionId: string) => void;
+    /** Fired when the user stops generation mid-stream (stopGeneration()). */
+    onStopGeneration?: () => void;
+    /** Fired when messages are cleared (but session kept). */
+    onClearMessages?: () => void;
     /**
      * Generic interaction event (link click, copy, feedback, etc.).
      * Useful for external analytics pipelines.

package/dist/{types-DKJ_-nbG.d.ts → types-DlNwk-bG.d.ts}

@@ -121,12 +121,33 @@ interface SlotMap {
     loader?: ComponentType<SlotProps>;
     /** Custom feedback (thumbs up/down) component */
     feedback?: ComponentType<SlotProps>;
-    /** Per-tool-name component overrides (keyed by tool name) */
+    /**
+     * Per-tool-name component overrides. Keys are tool NAMES (e.g. `searchProducts`,
+     * `calculateSeverance`). Values receive `ToolRendererProps`.
+     *
+     * Use this when you want to render a specific tool's output with custom UI.
+     *
+     * @example
+     * ```tsx
+     * slots={{ tools: { searchProducts: ProductGrid } }}
+     * ```
+     */
     tools?: Record<string, ComponentType<ToolRendererProps>>;
     /**
-     * Per-tool render-mode overrides.
+     * Per-render-mode component overrides. Keys are render MODES (not tool names):
+     * `visualization` | `json_render` | `legacy` | `preset` | `text`.
      *
-     * Keys are tool names, values are components that receive `ToolRendererProps`.
+     * Use this when you want to replace the default renderer for an entire category
+     * of tool outputs (e.g. swap the built-in recharts visualization for your own).
+     *
+     * **Common confusion**: if you want to override a specific tool, use `tools`
+     * (by name), not `toolRenderers` (by mode). Passing a tool name here does
+     * nothing (the SDK will emit a dev warning).
+     *
+     * @example
+     * ```tsx
+     * slots={{ toolRenderers: { visualization: MyChartRenderer } }}
+     * ```
      */
     toolRenderers?: Record<string, ComponentType<ToolRendererProps>>;
     /** Custom live-chat panel */
@@ -275,6 +296,15 @@ interface ChatEventCallbacks {
     onLiveChatEnded?: (endedBy: string) => void;
     /** Fired on any error (network, auth, etc.) */
     onError?: (error: Error) => void;
+    /**
+     * Fired when the user starts a brand-new conversation (clearMessages + new
+     * sessionId). Useful for resetting external state the consumer tracks.
+     */
+    onNewConversation?: (sessionId: string) => void;
+    /** Fired when the user stops generation mid-stream (stopGeneration()). */
+    onStopGeneration?: () => void;
+    /** Fired when messages are cleared (but session kept). */
+    onClearMessages?: () => void;
     /**
      * Generic interaction event (link click, copy, feedback, etc.).
      * Useful for external analytics pipelines.

package/dist/ui.cjs

@@ -1,8 +1,8 @@
 "use client";
 'use strict';
 
-var chunkQDFPJJ5Y_cjs = require('./chunk-QDFPJJ5Y.cjs');
-var chunkC24QG43M_cjs = require('./chunk-C24QG43M.cjs');
+var chunkOU5OZKYH_cjs = require('./chunk-OU5OZKYH.cjs');
+var chunkTZ7EM3EG_cjs = require('./chunk-TZ7EM3EG.cjs');
 var chunkJI5KCSOI_cjs = require('./chunk-JI5KCSOI.cjs');
 var chunkAWAJOSFP_cjs = require('./chunk-AWAJOSFP.cjs');
 var chunk525KS5HM_cjs = require('./chunk-525KS5HM.cjs');
@@ -442,163 +442,163 @@ TableCaption.displayName = "TableCaption";
 
 Object.defineProperty(exports, "Alert", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.Alert; }
+  get: function () { return chunkOU5OZKYH_cjs.Alert; }
 });
 Object.defineProperty(exports, "AlertDescription", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.AlertDescription; }
+  get: function () { return chunkOU5OZKYH_cjs.AlertDescription; }
 });
 Object.defineProperty(exports, "AlertTitle", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.AlertTitle; }
+  get: function () { return chunkOU5OZKYH_cjs.AlertTitle; }
 });
 Object.defineProperty(exports, "Badge", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.Badge; }
+  get: function () { return chunkOU5OZKYH_cjs.Badge; }
 });
 Object.defineProperty(exports, "Carousel", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.Carousel; }
+  get: function () { return chunkOU5OZKYH_cjs.Carousel; }
 });
 Object.defineProperty(exports, "CarouselContent", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.CarouselContent; }
+  get: function () { return chunkOU5OZKYH_cjs.CarouselContent; }
 });
 Object.defineProperty(exports, "CarouselItem", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.CarouselItem; }
+  get: function () { return chunkOU5OZKYH_cjs.CarouselItem; }
 });
 Object.defineProperty(exports, "CarouselNext", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.CarouselNext; }
+  get: function () { return chunkOU5OZKYH_cjs.CarouselNext; }
 });
 Object.defineProperty(exports, "CarouselPrevious", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.CarouselPrevious; }
+  get: function () { return chunkOU5OZKYH_cjs.CarouselPrevious; }
 });
 Object.defineProperty(exports, "Dialog", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.Dialog; }
+  get: function () { return chunkOU5OZKYH_cjs.Dialog; }
 });
 Object.defineProperty(exports, "DialogClose", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.DialogClose; }
+  get: function () { return chunkOU5OZKYH_cjs.DialogClose; }
 });
 Object.defineProperty(exports, "DialogContent", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.DialogContent; }
+  get: function () { return chunkOU5OZKYH_cjs.DialogContent; }
 });
 Object.defineProperty(exports, "DialogDescription", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.DialogDescription; }
+  get: function () { return chunkOU5OZKYH_cjs.DialogDescription; }
 });
 Object.defineProperty(exports, "DialogFooter", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.DialogFooter; }
+  get: function () { return chunkOU5OZKYH_cjs.DialogFooter; }
 });
 Object.defineProperty(exports, "DialogHeader", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.DialogHeader; }
+  get: function () { return chunkOU5OZKYH_cjs.DialogHeader; }
 });
 Object.defineProperty(exports, "DialogTitle", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.DialogTitle; }
+  get: function () { return chunkOU5OZKYH_cjs.DialogTitle; }
 });
 Object.defineProperty(exports, "DialogTrigger", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.DialogTrigger; }
+  get: function () { return chunkOU5OZKYH_cjs.DialogTrigger; }
 });
 Object.defineProperty(exports, "DropdownMenu", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.DropdownMenu; }
+  get: function () { return chunkOU5OZKYH_cjs.DropdownMenu; }
 });
 Object.defineProperty(exports, "DropdownMenuContent", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.DropdownMenuContent; }
+  get: function () { return chunkOU5OZKYH_cjs.DropdownMenuContent; }
 });
 Object.defineProperty(exports, "DropdownMenuItem", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.DropdownMenuItem; }
+  get: function () { return chunkOU5OZKYH_cjs.DropdownMenuItem; }
 });
 Object.defineProperty(exports, "DropdownMenuTrigger", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.DropdownMenuTrigger; }
+  get: function () { return chunkOU5OZKYH_cjs.DropdownMenuTrigger; }
 });
 Object.defineProperty(exports, "Input", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.Input; }
+  get: function () { return chunkOU5OZKYH_cjs.Input; }
 });
 Object.defineProperty(exports, "Progress", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.Progress; }
+  get: function () { return chunkOU5OZKYH_cjs.Progress; }
 });
 Object.defineProperty(exports, "ScrollArea", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.ScrollArea; }
+  get: function () { return chunkOU5OZKYH_cjs.ScrollArea; }
 });
 Object.defineProperty(exports, "ScrollBar", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.ScrollBar; }
+  get: function () { return chunkOU5OZKYH_cjs.ScrollBar; }
 });
 Object.defineProperty(exports, "Select", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.Select; }
+  get: function () { return chunkOU5OZKYH_cjs.Select; }
 });
 Object.defineProperty(exports, "SelectContent", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.SelectContent; }
+  get: function () { return chunkOU5OZKYH_cjs.SelectContent; }
 });
 Object.defineProperty(exports, "SelectItem", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.SelectItem; }
+  get: function () { return chunkOU5OZKYH_cjs.SelectItem; }
 });
 Object.defineProperty(exports, "SelectTrigger", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.SelectTrigger; }
+  get: function () { return chunkOU5OZKYH_cjs.SelectTrigger; }
 });
 Object.defineProperty(exports, "SelectValue", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.SelectValue; }
+  get: function () { return chunkOU5OZKYH_cjs.SelectValue; }
 });
 Object.defineProperty(exports, "Separator", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.Separator; }
-});
-Object.defineProperty(exports, "Textarea", {
-  enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.Textarea; }
+  get: function () { return chunkOU5OZKYH_cjs.Separator; }
 });
 Object.defineProperty(exports, "Tooltip", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.Tooltip; }
+  get: function () { return chunkOU5OZKYH_cjs.Tooltip; }
 });
 Object.defineProperty(exports, "TooltipContent", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.TooltipContent; }
+  get: function () { return chunkOU5OZKYH_cjs.TooltipContent; }
 });
 Object.defineProperty(exports, "TooltipProvider", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.TooltipProvider; }
+  get: function () { return chunkOU5OZKYH_cjs.TooltipProvider; }
 });
 Object.defineProperty(exports, "TooltipTrigger", {
   enumerable: true,
-  get: function () { return chunkQDFPJJ5Y_cjs.TooltipTrigger; }
+  get: function () { return chunkOU5OZKYH_cjs.TooltipTrigger; }
 });
 Object.defineProperty(exports, "Button", {
   enumerable: true,
-  get: function () { return chunkC24QG43M_cjs.Button; }
+  get: function () { return chunkTZ7EM3EG_cjs.Button; }
 });
 Object.defineProperty(exports, "Collapsible", {
   enumerable: true,
-  get: function () { return chunkC24QG43M_cjs.Collapsible; }
+  get: function () { return chunkTZ7EM3EG_cjs.Collapsible; }
 });
 Object.defineProperty(exports, "CollapsibleContent", {
   enumerable: true,
-  get: function () { return chunkC24QG43M_cjs.CollapsibleContent; }
+  get: function () { return chunkTZ7EM3EG_cjs.CollapsibleContent; }
 });
 Object.defineProperty(exports, "CollapsibleTrigger", {
   enumerable: true,
-  get: function () { return chunkC24QG43M_cjs.CollapsibleTrigger; }
+  get: function () { return chunkTZ7EM3EG_cjs.CollapsibleTrigger; }
+});
+Object.defineProperty(exports, "Textarea", {
+  enumerable: true,
+  get: function () { return chunkTZ7EM3EG_cjs.Textarea; }
 });
 Object.defineProperty(exports, "Spinner", {
   enumerable: true,

package/dist/ui.js

@@ -1,6 +1,6 @@
 "use client";
-export { Alert, AlertDescription, AlertTitle, Badge, Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger, Input, Progress, ScrollArea, ScrollBar, Select, SelectContent, SelectItem, SelectTrigger, SelectValue, Separator, Textarea, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from './chunk-KVEJAPWA.js';
-export { Button, Collapsible, CollapsibleContent, CollapsibleTrigger } from './chunk-7L4FS6G7.js';
+export { Alert, AlertDescription, AlertTitle, Badge, Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger, Input, Progress, ScrollArea, ScrollBar, Select, SelectContent, SelectItem, SelectTrigger, SelectValue, Separator, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from './chunk-3KSMOHNY.js';
+export { Button, Collapsible, CollapsibleContent, CollapsibleTrigger, Textarea } from './chunk-JHWSG5IB.js';
 export { Spinner } from './chunk-4QT25AXI.js';
 export { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from './chunk-NPJKLYLV.js';
 import { cn } from './chunk-3RW7O444.js';

package/llms.txt

@@ -68,9 +68,33 @@ Peer deps required: `react>=19`, `react-dom>=19`. The CSS import is required for
 
 ## Slots
 
-Replace any UI piece via the `slots` prop:
+Replace any UI piece via the `slots` prop. Every slot receives `DefaultComponent` as a prop so you can compose with — or fully replace — the built-in UI.
 
-`header`, `welcome`, `message`, `input`, `footer`, `loader`, `suggestions`, `tools` (keyed per tool name).
+**Available slot names:**
+
+- `header`, `footer`, `input`, `welcomePage`, `loader` — layout chrome
+- `assistantMessage`, `userMessage`, `systemMessage` — per-role message rendering
+- `feedback` — thumbs-up/down + copy row under assistant messages
+- `emptyState` — shown when no messages and no welcome
+- `tools` — `Record<toolName, Component>` (keyed by **tool name**, e.g. `searchProducts`)
+- `toolRenderers` — `Record<renderMode, Component>` (keyed by **render mode**, e.g. `visualization`)
+- `liveChatPanel`, `satisfactionRating`, `visitorIdentityForm`, `floatingButton` — live-chat + widget chrome
+
+**Common confusion:** `tools` is by **tool name**, `toolRenderers` is by **render mode**. If you want to override a specific tool's display, use `tools`. In dev mode the SDK emits a console warning if a tool name leaks into `toolRenderers`.
+
+```tsx
+import type { AssistantMessageSlotProps } from "@aigentyc/chat-sdk";
+
+function MyAssistantMsg({ text, DefaultComponent, ...rest }: AssistantMessageSlotProps & { DefaultComponent: any }) {
+  return (
+    <div className="my-wrapper">
+      <DefaultComponent text={text} {...rest} />
+    </div>
+  );
+}
+
+<Chat slots={{ assistantMessage: MyAssistantMsg }} projectId="..." apiEndpoint="..." />
+```
 
 ## Tool rendering
 
@@ -285,17 +309,163 @@ import { useAigentycChat } from "@aigentyc/chat-sdk/hooks";
 
 const { newConversation, clearMessages } = useAigentycChat({ projectId: "...", apiEndpoint: "..." });
 
-<button onClick={newConversation}>New conversation</button>  // new sessionId + clears
-<button onClick={clearMessages}>Clear messages</button>      // clears, keeps session
+<button onClick={newConversation}>New conversation</button>  // new sessionId + clears + returns to welcome
+<button onClick={clearMessages}>Clear messages</button>      // clears, keeps session, returns to welcome
+```
+
+### Recipe: headless — full control with every event
+
+```tsx
+"use client";
+import { useAigentycChat } from "@aigentyc/chat-sdk/hooks";
+
+export default function MyCustomChat() {
+  const {
+    messages,
+    status,
+    sendMessage,
+    stopGeneration,
+    newConversation,
+    clearMessages,
+    activeTools,
+    liveChat,
+    sessionId,
+  } = useAigentycChat({
+    projectId: "proj_...",
+    apiEndpoint: "https://app.aigentyc.ai",
+    apiKey: "tyco_pk_...",
+    onMessageSent: (m) => console.log("sent", m),
+    onMessageReceived: (m) => console.log("received", m),
+    onStreamStart: () => console.log("stream started"),
+    onStreamEnd: () => console.log("stream ended"),
+    onToolCall: (name, args) => console.log("tool", name, args),
+    onToolResult: (name, result) => console.log("tool result", name, result),
+    onNewConversation: (newSessionId) => console.log("new session", newSessionId),
+    onStopGeneration: () => console.log("stopped"),
+    onClearMessages: () => console.log("cleared"),
+    onError: (err) => console.error(err),
+  });
+
+  return (
+    <div>
+      <div className="history">
+        {messages.map((m) => (
+          <div key={m.id}>
+            <b>{m.role}:</b> {m.content}
+          </div>
+        ))}
+      </div>
+      {status === "streaming" && <button onClick={stopGeneration}>Stop</button>}
+      <button onClick={newConversation}>New</button>
+    </div>
+  );
+}
+```
+
+### Recipe: control message part order (tools-first vs text-first)
+
+```tsx
+// Text parts render before tool cards (default, best for Q&A/RAG)
+<Chat messagePartOrder="text-first" projectId="..." apiEndpoint="..." />
+
+// Tool cards render before text (best for tool-heavy apps — product cards, forms, etc.)
+<Chat messagePartOrder="tools-first" projectId="..." apiEndpoint="..." />
+
+// Render parts in the stream order (whatever the API returns)
+<Chat messagePartOrder="stream-order" projectId="..." apiEndpoint="..." />
+```
+
+### Recipe: customize MessageFeedback (thumbs up/down) styling
+
+```tsx
+import { MessageFeedback } from "@aigentyc/chat-sdk/ai-elements";
+
+// Option 1: strip defaults and style from scratch
+<Chat
+  slots={{
+    feedback: (props) => (
+      <MessageFeedback {...props} unstyled classNames={{
+        root: "my-feedback-row",
+        thumbsUp: "my-thumb-btn",
+        thumbsDown: "my-thumb-btn",
+      }} />
+    ),
+  }}
+/>
+
+// Option 2: full render override
+<Chat
+  slots={{
+    feedback: (props) => (
+      <MessageFeedback
+        {...props}
+        renderActions={({ onPositive, onNegative, onCopy, feedback }) => (
+          <div className="flex gap-2">
+            <button onClick={onPositive} className={feedback === "positive" ? "active" : ""}>👍</button>
+            <button onClick={onNegative} className={feedback === "negative" ? "active" : ""}>👎</button>
+            <button onClick={onCopy}>Copy</button>
+          </div>
+        )}
+      />
+    ),
+  }}
+/>
+```
+
+### Recipe: normalize messy tool data shapes
+
+Custom tools (especially `data_store`) can return rows in a few shapes. Use the helper so renderers don't care:
+
+```tsx
+import { normalizeToolRows } from "@aigentyc/chat-sdk";
+
+function ProductGrid({ result }: ToolRendererProps) {
+  // Handles: flat array, { rows: [...] } wrapper, raw DB rows { id, data: {...} }
+  const rows = normalizeToolRows(result?.data);
+  return (
+    <div className="grid grid-cols-2 gap-2">
+      {rows.map((row, i) => <div key={i}>{row.name as string} — ${row.price as number}</div>)}
+    </div>
+  );
+}
+```
+
+### Recipe: catch tool-renderer crashes without killing the chat
+
+Wrap a risky slot in `ChatErrorBoundary`:
+
+```tsx
+import { ChatErrorBoundary } from "@aigentyc/chat-sdk";
+
+<Chat
+  slots={{
+    tools: {
+      myRiskyTool: (props) => (
+        <ChatErrorBoundary
+          label="product grid"
+          onError={(e) => Sentry.captureException(e)}
+          fallback={(err, retry) => <div>Failed. <button onClick={retry}>Retry</button></div>}
+        >
+          <MyProductGrid {...props} />
+        </ChatErrorBoundary>
+      ),
+    },
+  }}
+/>
 ```
+The built-in tool dispatcher already wraps each tool in a boundary, so a single broken renderer never takes down the rest of the chat. Use `ChatErrorBoundary` manually only around custom slots you haven't tested in production.
 
 ## Troubleshooting
 
 | Symptom | Likely cause | Fix |
 | --- | --- | --- |
 | Unstyled / broken layout | Missing CSS import | `import "@aigentyc/chat-sdk/theme/styles.css"` |
-| 401 / 403 from API | `apiKey` missing or wrong scope | Create key with `Chat: Full` permission |
+| 401 / "Missing Authorization" on embed | No `apiKey` passed — required for all third-party domain embeds | Pass `apiKey` prop (or `NEXT_PUBLIC_AIGENTYC_API_KEY` / `VITE_AIGENTYC_API_KEY` env var). The "no apiKey needed" path only works inside `app.aigentyc.com` itself (session cookie). |
+| 403 / invalid origin | API key's Allowed Origins list doesn't include your embed domain | Dashboard → Settings → API Keys → edit → add domain |
 | CORS error in browser | Allowed Origins on API key doesn't include current URL | Add `http://localhost:5173` (Vite) or `http://localhost:3000` (Next) to the key's Allowed Origins |
+| Slot override doesn't render | Using `toolRenderers` keyed by tool name | Use `tools` for per-tool overrides; `toolRenderers` is per render mode. Dev console warns automatically. |
+| Welcome doesn't reappear after "new conversation" | Old SDK version (pre-0.2) | Upgrade — `newConversation()` now triggers a bidirectional welcome toggle |
+| Dark mode leaks white backgrounds | Custom CSS / old SDK | As of 0.2, internal components use `bg-background`/`bg-card` vars — upgrade if you see white leaks |
 | `Cannot find module @ai-sdk/react` | Stale install from old SDK version | `rm -rf node_modules package-lock.json && npm install` (peers are bundled now) |
 | Hebrew text shows LTR | Forgot `language="he"` | Pass `language="he"` to `<Chat>` |
 | Tool result shows raw JSON | Custom tool with no renderer | Add `slots.tools[toolName]` or set `uiRenderMode: "hidden"` server-side |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigentyc/chat-sdk",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "React SDK for building AI-powered chat interfaces connected to the Aigentyc platform",
   "type": "module",
   "sideEffects": [
@@ -115,6 +115,7 @@
   "files": [
     "dist",
     "bin",
+    "claude-skill",
     "README.md",
     "AGENTS.md",
     "llms.txt",