@kitn.ai/ui 0.17.0 → 0.18.0

package/dist/llms/llms.txt

@@ -1,7 +1,7 @@
 <!-- AUTO-GENERATED by scripts/gen-llms.mjs — do not edit by hand. Run `npm run build`. -->
 # @kitn.ai/ui
 
-> Framework-agnostic, Shadow-DOM web components for building AI chat interfaces — works in React, Vue, Angular, Svelte, or plain HTML. 46 custom elements, every one prefixed `kai-` (e.g. `<kai-chat>`, `<kai-artifact>`): streaming responses, markdown + code rendering, reasoning/tool panels, attachments, conversation sidebar, voice input. Zero framework dependency for consumers; the SolidJS runtime it is authored in is bundled in, so the host needs nothing.
+> Framework-agnostic, Shadow-DOM web components for building AI chat interfaces — works in React, Vue, Angular, Svelte, or plain HTML. 78 custom elements, every one prefixed `kai-` (e.g. `<kai-chat>`, `<kai-artifact>`): streaming responses, markdown + code rendering, reasoning/tool panels, attachments, conversation sidebar, voice input. Zero framework dependency for consumers; the SolidJS runtime it is authored in is bundled in, so the host needs nothing.
 
 ## Install
 
@@ -13,7 +13,7 @@ npm install solid-js
 
 ## #1 rule: array/object data goes on JS PROPERTIES, not HTML attributes
 
-This is the single most common mistake. Arrays and objects (`messages`, `models`, `context`, `suggestions`, `slashCommands`, …) MUST be assigned as JavaScript properties on the element. They CANNOT be passed as HTML attributes — an HTML attribute is always a string and will be ignored or mis-parsed.
+This is the single most common mistake. Arrays and objects (`messages`, `models`, `context`, `suggestions`, `triggers`, …) MUST be assigned as JavaScript properties on the element. They CANNOT be passed as HTML attributes — an HTML attribute is always a string and will be ignored or mis-parsed.
 
 ```js
 const chat = document.querySelector('kai-chat');
@@ -35,7 +35,7 @@ Drop an element into any framework (React, Vue, plain HTML). Data in via JS prop
 - `<kai-prompt-input>` — standalone composer with send button.
 
 **Layer 2 — composable primitives** (`import { … } from '@kitn.ai/ui'`):
-All 46 elements are also exported individually. Use them for custom layouts or features `<kai-chat>` does not expose (ChainOfThought, FeedbackBar, ThinkingBar, VoiceInput, …). Your bundler tree-shakes the rest.
+All 78 elements are also exported individually. Use them for custom layouts or features `<kai-chat>` does not expose (ChainOfThought, FeedbackBar, ThinkingBar, VoiceInput, …). Your bundler tree-shakes the rest.
 
 ## Key rules for the web components
 
@@ -97,7 +97,7 @@ For Tailwind builds: `@import "@kitn.ai/ui/theme.css"` in your CSS.
 
 ## Docs
 
-- Full element reference (all 46 elements, every prop/event): ./llms-full.txt — https://kitn.dev/llms-full.txt
+- Full element reference (all 78 elements, every prop/event): ./llms-full.txt — https://kitn.dev/llms-full.txt
 - Machine-readable Custom Elements Manifest: https://unpkg.com/@kitn.ai/ui/dist/custom-elements.json
 - Working examples: https://github.com/kitn-ai/ui/tree/main/examples
 - Storybook: https://storybook.kitn.dev

package/dist/mcp.es.js

@@ -113,6 +113,33 @@ Call component_reference with no name (or name: "list") to list all ${all.length
       lines.push(`- **${prop.name}**${def}${desc ? ` — ${desc}` : ""}`);
     }
   }
+  const slots = el.slots ?? [];
+  if (slots.length > 0) {
+    lines.push(
+      "",
+      "### Composition slots",
+      'Project your own markup into these named regions — add a light-DOM child with a `slot="…"` attribute (e.g. `<div slot="sidebar">…</div>`).'
+    );
+    for (const slot of slots) {
+      const desc = slot.description?.trim() ?? "";
+      lines.push(`- **${slot.name}**${desc ? ` — ${desc}` : ""}`);
+    }
+  }
+  const parts = el.cssParts ?? [];
+  if (parts.length > 0) {
+    lines.push(
+      "",
+      "### Styleable parts (`::part`)",
+      "Restyle these from outside the Shadow DOM via `" + tag + "::part(name) { … }`."
+    );
+    for (const part of parts) {
+      const desc = part.description?.trim() ?? "";
+      lines.push(`- **${part.name}**${desc ? ` — ${desc}` : ""}`);
+      if (part.recipe) {
+        lines.push("  ```css", `  ${part.recipe}`, "  ```");
+      }
+    }
+  }
   return lines.join("\n");
 }
 const reference = {
@@ -1771,17 +1798,45 @@ function interactionPatternsBlock() {
     `  recordPreference({ prompt, chosen: chosenId, rejected: rejectedIds });`,
     `});`
   ].join("\n");
+  const statePattern = [
+    `--- Pattern: State helpers + streaming (new-array contract) ---`,
+    `// Setter contract: always (prev) => next — every helper returns a new array.`,
+    `// Vanilla adapter (works with any element ref):`,
+    `// const set = (fn) => { el.messages = fn(el.messages ?? []); };`,
+    ``,
+    `// Low-level helpers from @kitn.ai/ui/state:`,
+    `// import { appendMessage, updateMessage, appendContent, createAssistantStream } from '@kitn.ai/ui/state';`,
+    ``,
+    `// Streaming loop (framework-agnostic):`,
+    `// const stream = createAssistantStream(set);`,
+    `// stream.appendText(chunk);       // text delta`,
+    `// stream.appendReasoning(chunk);  // reasoning delta`,
+    `// stream.upsertTool(toolCall);    // tool call delta`,
+    `// stream.done();                  // seal the message`,
+    ``,
+    `// One-liner for React (batteries-included):`,
+    `// import { useKaiChat } from '@kitn.ai/ui/react';`,
+    `// const chat = useKaiChat();`,
+    `// <Chat {...chat.bind} />`,
+    ``,
+    `// One-liner for Solid (batteries-included):`,
+    `// import { createKaiChat } from '@kitn.ai/ui';`,
+    `// const chat = createKaiChat();`,
+    `// <kai-chat {...chat.bind} on:kai-submit={chat.handleSubmit} />`
+  ].join("\n");
   return [
     `=== INTERACTION PATTERNS ===`,
     ``,
-    `Optional snippets for confirmations, card recovery, and preference capture.`,
+    `Optional snippets for confirmations, card recovery, preference capture, and state/streaming helpers.`,
     `Drop in the one(s) you need; all imports resolve from @kitn.ai/ui.`,
     ``,
     toastPattern,
     ``,
     recoveryPattern,
     ``,
-    preferencePattern
+    preferencePattern,
+    ``,
+    statePattern
   ].join("\n");
 }
 function rejectIntegration(id) {
@@ -2081,9 +2136,9 @@ const RULES = [
     // Rule 1 — array/object data set as an HTML attribute
     // Source: for-ai-agents.mdx §1; context7.json rule 2
     id: "array-as-attribute",
-    test: (t) => /\b(messages|models|context|suggestions|slashCommands)\s*=\s*["']/.test(t),
+    test: (t) => /\b(messages|models|context|suggestions|triggers)\s*=\s*["']/.test(t),
     title: "Array/object prop set as an HTML attribute (silent failure)",
-    cause: "An HTML attribute is always a string. Passing `messages`, `models`, `context`, `suggestions`, or `slashCommands` as an HTML attribute silently fails — the element receives a stringified value it cannot parse.",
+    cause: "An HTML attribute is always a string. Passing `messages`, `models`, `context`, `suggestions`, or `triggers` as an HTML attribute silently fails — the element receives a stringified value it cannot parse.",
     fix: "Set the property in JavaScript, not as an HTML attribute. Only scalar props (`placeholder`, `loading`, `theme`) work as attributes.\n\n```js\n// ✅ Works — set messages in JavaScript as a property\nconst chat = document.querySelector('kai-chat');\nchat.messages = [{ id: '1', role: 'assistant', content: 'Hello!' }];\n```\n\n```html\n<!-- ❌ Fails — messages cannot be an HTML attribute -->\n<kai-chat messages=\"[...]\"></kai-chat>\n```"
   },
   {
@@ -2093,7 +2148,7 @@ const RULES = [
     test: (t) => /don'?t\s+update|doesn'?t\s+re.?render|no\s+re.?render|\.push\(|\bpush(?:es|ing)?\s+(?:to|into|onto)\b|mutate|in.place/.test(t),
     title: "In-place mutation does not trigger a re-render",
     cause: "Mutating an existing message object or array in place (e.g. `chat.messages.push(…)` or `chat.messages[i].content = …`) does not trigger a re-render. The element only reacts when it detects a new array/object reference.",
-    fix: "Assign a NEW array (and a new object) on every change — never mutate in place.\n\n```js\n// ✅ Triggers re-render — new array + new object reference\nchat.messages = [\n  ...chat.messages,\n  { id: crypto.randomUUID(), role: 'user', content: userText },\n];\n\n// ✅ During streaming — replace with a new array + new object on every chunk\nchat.messages = chat.messages.map((m) =>\n  m.id === assistantId ? { ...m, content: accumulated } : m\n);\n\n// ❌ Does NOT trigger re-render\nchat.messages.push(newMsg);\nchat.messages[i].content = accumulated;\n```"
+    fix: "Assign a NEW array (and a new object) on every change — never mutate in place.\n\n```js\n// ✅ Triggers re-render — new array + new object reference\nchat.messages = [\n  ...chat.messages,\n  { id: crypto.randomUUID(), role: 'user', content: userText },\n];\n\n// ✅ During streaming — replace with a new array + new object on every chunk\nchat.messages = chat.messages.map((m) =>\n  m.id === assistantId ? { ...m, content: accumulated } : m\n);\n\n// ❌ Does NOT trigger re-render\nchat.messages.push(newMsg);\nchat.messages[i].content = accumulated;\n```\n\nThe ergonomic path: helpers in `@kitn.ai/ui/state` (`appendMessage`, `updateMessage`, `appendContent`) and `createAssistantStream` handle the new-reference contract for you. `useKaiChat` (React) and `createKaiChat` (Solid) own state entirely so mutation is never an option.\n\n// setMessages((m) => appendMessage(m, msg)) // new array, no footgun"
   },
   {
     // Rule 3 — listening for events on a parent / wrong element
@@ -2112,8 +2167,8 @@ const RULES = [
     id: "wrong-prefix",
     test: (t) => /\bkitn-/.test(t),
     title: "Wrong element prefix `kitn-` (should be `kai-`)",
-    cause: "The custom element prefix is `kai-` (e.g. `<kai-chat>`, `<kai-artifact>`). `kitn-chat` is only a bundle filename — it is not a registered element name. Using `<kitn-chat>` results in an unknown element that renders nothing.",
-    fix: "Replace the `kitn-` prefix with `kai-` everywhere.\n\n```html\n<!-- ✅ Correct element prefix -->\n<kai-chat></kai-chat>\n<kai-artifact></kai-artifact>\n\n<!-- ❌ Wrong — kitn-chat is a bundle filename, not an element -->\n<kitn-chat></kitn-chat>\n```"
+    cause: "The custom element prefix is `kai-` (e.g. `<kai-chat>`, `<kai-artifact>`). `kitn-` is a legacy name (the register-all bundle is `kai.es.js`) — it is not a registered element name. Using `<kitn-chat>` results in an unknown element that renders nothing.",
+    fix: "Replace the `kitn-` prefix with `kai-` everywhere.\n\n```html\n<!-- ✅ Correct element prefix -->\n<kai-chat></kai-chat>\n<kai-artifact></kai-artifact>\n\n<!-- ❌ Wrong — kitn-chat is not an element (the bundle is kai.es.js) -->\n<kitn-chat></kitn-chat>\n```"
   },
   {
     // Rule 6 — custom elements not registered / renders nothing (React #1 failure)

package/dist/primitives/composer-model.d.ts

@@ -0,0 +1,22 @@
+export interface EntityRef {
+    kind: string;
+    id: string;
+    label: string;
+    icon?: string;
+    promptText?: string;
+    data?: Record<string, unknown>;
+}
+export type Segment = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'entity';
+    entity: EntityRef;
+};
+export type ComposerDoc = Segment[];
+export declare function normalizeValue(value: string | ComposerDoc | null | undefined): ComposerDoc;
+export declare function serializeToText(doc: ComposerDoc, opts?: {
+    entity?: (e: EntityRef) => string;
+}): string;
+export declare function entitiesOf(doc: ComposerDoc): EntityRef[];
+export declare function docIsEmpty(doc: ComposerDoc): boolean;

package/dist/primitives/composer-triggers.d.ts

@@ -0,0 +1,19 @@
+export interface ActiveTrigger {
+    char: string;
+    query: string;
+    start: number;
+}
+export declare function detectTrigger(text: string, caret: number, chars: string[]): ActiveTrigger | null;
+/**
+ * Wraps detectTrigger with a list of trigger definitions.
+ * Returns { def, query, start } when a trigger is active, else null.
+ * Accepts generic defs so it does not import from composer.tsx (no cycle).
+ */
+export declare function activeTriggerFor<T extends {
+    char: string;
+    kind: string;
+}>(text: string, caret: number, defs: T[]): {
+    def: T;
+    query: string;
+    start: number;
+} | null;

package/dist/primitives/create-kai-chat.d.ts

@@ -0,0 +1,38 @@
+import { ChatMessage } from '../elements/chat-types';
+import { AttachmentData } from '../components/attachments';
+import { AssistantStream, SetMessages } from '../state';
+export interface CreateKaiChatOptions {
+    /** Seed messages, read once at creation and copied. Later changes are ignored — drive updates through the returned ops. */
+    initialMessages?: ChatMessage[];
+    /** Seed suggestions, read once at creation and copied. Later changes are ignored. */
+    initialSuggestions?: string[];
+    onSubmit?: (detail: {
+        value: string;
+        attachments: AttachmentData[];
+    }) => void | Promise<void>;
+}
+/** Solid store: consumer-owned chat state + the same ergonomic ops as `useKaiChat`. */
+export interface KaiChatStore {
+    messages: () => ChatMessage[];
+    setMessages: SetMessages;
+    suggestions: () => string[];
+    loading: () => boolean;
+    append: (msg: ChatMessage) => void;
+    update: (id: string, patch: Partial<ChatMessage> | ((m: ChatMessage) => ChatMessage)) => void;
+    remove: (id: string) => void;
+    addSuggestion: (s: string) => void;
+    removeSuggestion: (s: string) => void;
+    clearSuggestions: () => void;
+    streamAssistant: (init?: Partial<ChatMessage>) => AssistantStream;
+    handleSubmit: (event: CustomEvent<{
+        value: string;
+        attachments: AttachmentData[];
+    }>) => void;
+    /** Spread onto `<kai-chat {...chat.bind} />` (reactive getters). Wire submit via `on:kai-submit={chat.handleSubmit}`. */
+    bind: {
+        readonly messages: ChatMessage[];
+        readonly loading: boolean;
+        readonly suggestions: string[];
+    };
+}
+export declare function createKaiChat(options?: CreateKaiChatOptions): KaiChatStore;

package/dist/primitives/toast-store.d.ts

@@ -1,9 +1,17 @@
 import { ToastPosition } from '../components/toast';
-export type ToastVariant = 'neutral' | 'success';
+export type ToastVariant = 'neutral' | 'success' | 'warning' | 'error' | 'info';
+/** Visual treatment: `'pill'` (default, compact single-line) or `'card'` (richer
+ *  rounded card with an optional description line). */
+export type ToastAppearance = 'pill' | 'card';
 export interface ToastConfig {
     stack?: 'expanded' | 'collapsed';
     position?: ToastPosition;
     max?: number;
+    /** Default appearance for imperatively-raised toasts. Defaults to `'pill'`. */
+    appearance?: ToastAppearance;
+    /** Default high-contrast inverse treatment for imperatively-raised toasts.
+     *  Defaults to `false`. */
+    inverse?: boolean;
 }
 /**
  * Configure the imperative `toast()` singleton — call once at app start.
@@ -23,6 +31,15 @@ export interface ToastItem {
     id: string;
     message: string;
     variant?: ToastVariant;
+    /** Visual treatment: `'pill'` (default, compact single-line) or `'card'` (richer
+     *  rounded card with an optional description line). */
+    appearance?: ToastAppearance;
+    /** High-contrast inverse surface — works on either appearance, popping in light
+     *  AND dark. Defaults to `false`. */
+    inverse?: boolean;
+    /** Secondary line shown below the message in the `'card'` appearance. The
+     *  `'pill'` appearance ignores it. */
+    description?: string;
     action?: ToastAction;
     /** Auto-dismiss delay in ms. `0` = sticky (never auto-dismisses). When an
      *  `action` is present the effective floor is 4000ms so it stays long enough
@@ -40,6 +57,13 @@ export interface ToastItem {
 export interface ToastOptions {
     id?: string;
     variant?: ToastVariant;
+    /** Visual treatment: `'pill'` (default) or `'card'`. Falls back to the value set
+     *  via `configureToasts`, then `'pill'`. */
+    appearance?: ToastAppearance;
+    /** High-contrast inverse surface. Falls back to `configureToasts`, then `false`. */
+    inverse?: boolean;
+    /** Secondary line shown below the message in the `'card'` appearance. */
+    description?: string;
     action?: ToastAction;
     duration?: number;
     dismissible?: boolean;
@@ -67,8 +91,14 @@ export declare function ensureMounted(target?: HTMLElement | null): HTMLElement
 export declare function isToastRegionMounted(): boolean;
 export interface ToastFn {
     (message: string, opts?: ToastOptions): ToastHandle;
-    /** Raise a success (emerald check) toast. */
+    /** Raise a success (green check) toast. */
     success: (message: string, opts?: ToastOptions) => ToastHandle;
+    /** Raise a warning (amber) toast — e.g. an agent needs your input. */
+    warning: (message: string, opts?: ToastOptions) => ToastHandle;
+    /** Raise an error (destructive/red) toast — e.g. an agent failed. */
+    error: (message: string, opts?: ToastOptions) => ToastHandle;
+    /** Raise an info (blue) toast. */
+    info: (message: string, opts?: ToastOptions) => ToastHandle;
     /** Dismiss a toast by id. */
     dismiss: (id: string) => void;
     /** Dismiss every active toast. */

package/dist/primitives/use-speech-recognition.d.ts

@@ -0,0 +1,26 @@
+export interface UseSpeechRecognitionOptions {
+    /** Emit live, non-final partials via the `onInterim` callback passed to start(). */
+    interim?: boolean;
+}
+export interface SpeechRecognitionStartOptions {
+    /** BCP-47 language tag, e.g. `en-US`. */
+    lang?: string;
+    /** Called with each interim (non-final) transcript when `interim` is enabled. */
+    onInterim?: (text: string) => void;
+}
+/**
+ * Wrap the browser's Web Speech `SpeechRecognition` (Chrome/Safari; no Firefox).
+ * Mirrors `useVoiceRecorder`'s shape: an `isListening` signal, an `error` signal,
+ * and `start`/`stop` controls. `start()` resolves with the final transcript when
+ * recognition ends; `stop()` ends the in-progress session (resolving start()).
+ *
+ * Caveat (documented at the element): in Chrome this is cloud-based — audio is
+ * sent to Google — so it is "native to the browser," not on-device/private.
+ */
+export declare function useSpeechRecognition(options?: UseSpeechRecognitionOptions): {
+    isSupported: boolean;
+    isListening: import('solid-js').Accessor<boolean>;
+    error: import('solid-js').Accessor<string | null>;
+    start: (opts?: SpeechRecognitionStartOptions) => Promise<string>;
+    stop: () => void;
+};