@kitn.ai/ui 0.16.0 → 0.17.0

package/dist/kitn-chat.es.js

@@ -1 +1 @@
-import{c as i,i as g}from"./register-ujhr1nBS.js";export{i as configureCodeHighlighting,g as isCodeHighlightingEnabled};
+import{A as s,B as a,q as i,v as o}from"./register-JyTglR6m.js";export{s as configureCodeHighlighting,a as configureToasts,i as isCodeHighlightingEnabled,o as toast};

package/dist/llms/llms-full.txt

@@ -3,7 +3,7 @@
 
 # @kitn.ai/ui
 
-> Framework-agnostic, Shadow-DOM web components for building AI chat interfaces — works in React, Vue, Angular, Svelte, or plain HTML. 44 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. 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.
 
 ## Install
 
@@ -37,7 +37,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 44 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 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.
 
 ## Key rules for the web components
 
@@ -99,7 +99,7 @@ For Tailwind builds: `@import "@kitn.ai/ui/theme.css"` in your CSS.
 
 ## Docs
 
-- Full element reference (all 44 elements, every prop/event): ./llms-full.txt — https://kitn.dev/llms-full.txt
+- Full element reference (all 46 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
@@ -173,7 +173,7 @@ The same rule applies to every array/object property (`models`, `context`, `sugg
 
 ---
 
-## Element reference (44 elements, generated from custom-elements.json)
+## Element reference (46 elements, generated from custom-elements.json)
 
 Every element also accepts the `theme` attribute. Array/object properties are marked with a `—` attribute: they must be set as JS properties.
 
@@ -253,9 +253,9 @@ _No events._
 
 | Property | Attribute | Type | Description |
 |---|---|---|---|
-| `cards` | — | `undefined \| { type: string; id: string; data: unknown; title?: undefined \| string; resolution?: undefined \| { kind: "action"; action: string; payload?: unknown; at?: undefined \| string } \| { kind: "submit"; data: unknown; at?: undefined \| string } }[]` | The stream of card envelopes to render. Set as a JS PROPERTY: `el.cards = [...]`. |
+| `cards` | — | `undefined \| { type: string; id: string; data: unknown; title?: undefined \| string; resolution?: undefined \| { kind: "action"; action: string; payload?: unknown; at?: undefined \| string } \| { kind: "submit"; data: unknown; at?: undefined \| string } \| { kind: "dismissed"; at?: undefined \| string } \| { kind: "expired"; reason?: undefined \| string; at?: undefined \| string } }[]` | The stream of card envelopes to render. Set as a JS PROPERTY: `el.cards = [...]`. |
 | `types` | — | `undefined \| Record<string, string>` | Optional type→tag overrides/additions (merged over the built-ins). Property: `el.types`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type. |
-| `policy` | — | `undefined \| { onSubmit?: undefined \| (cardId: string, data: unknown) => void; onAction?: undefined \| (cardId: string, action: string, payload?: unknown) => void; onSendPrompt?: undefined \| (text: string, opts: { mode: "compose" \| "send"; context?: unknown; }) => void; onOpen?: undefined \| (url: string, target: "tab" \| "artifact") => void; onState?: undefined \| (cardId: string, patch: unknown) => void; onDismiss?: undefined \| (cardId: string) => void; onError?: undefined \| (cardId: string, message: string) => void; maxSendPromptMode?: undefined \| "compose" \| "send" }` | Optional CardPolicy handling child events. Property: `el.policy`. |
+| `policy` | — | `undefined \| { onSubmit?: undefined \| (cardId: string, data: unknown) => void; onAction?: undefined \| (cardId: string, action: string, payload?: unknown) => void; onSendPrompt?: undefined \| (text: string, opts: { mode: "compose" \| "send"; context?: unknown; }) => void; onOpen?: undefined \| (url: string, target: "tab" \| "artifact") => void; onState?: undefined \| (cardId: string, patch: unknown) => void; onDismiss?: undefined \| (cardId: string) => void; onReopen?: undefined \| (cardId: string) => void; onError?: undefined \| (cardId: string, message: string) => void; maxSendPromptMode?: undefined \| "compose" \| "send" }` | Optional CardPolicy handling child events. Property: `el.policy`. |
 
 _No events._
 
@@ -279,7 +279,7 @@ _No events._
 
 | Property | Attribute | Type | Description |
 |---|---|---|---|
-| `messages` | — | `{ id: string; role: "user" \| "assistant"; content: string; reasoning?: undefined \| { text: string; label?: undefined \| string }; tools?: undefined \| { type: string; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string }[]; attachments?: undefined \| { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }[]; actions?: undefined \| ("copy" \| "like" \| "dislike" \| "regenerate" \| "edit" \| { id: string; label: string; icon?: undefined \| string; tooltip?: undefined \| string })[]; avatar?: undefined \| { src?: undefined \| string; fallback?: undefined \| string; alt?: undefined \| string } }[]` | The full message thread to render, newest last. Each entry carries its role, content, and optional reasoning/tools/attachments/actions. Set as a JS property (`el.messages = [...]`). |
+| `messages` | — | `{ id: string; role: "user" \| "assistant"; content: string; reasoning?: undefined \| { text: string; label?: undefined \| string }; tools?: undefined \| { type: string; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string }[]; attachments?: undefined \| { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }[]; actions?: undefined \| ("copy" \| "like" \| "dislike" \| "regenerate" \| "edit" \| { id: string; label: string; icon?: undefined \| string; tooltip?: undefined \| string })[]; avatar?: undefined \| { src?: undefined \| string; fallback?: undefined \| string; alt?: undefined \| string }; feedback?: undefined \| "like" \| "dislike" }[]` | The full message thread to render, newest last. Each entry carries its role, content, and optional reasoning/tools/attachments/actions. Set as a JS property (`el.messages = [...]`). |
 | `value` | `value` | `undefined \| string` | Controlled value of the input. When set, the host owns the input text and must update it on `kai-value-change`; leave unset for uncontrolled behavior. |
 | `placeholder` | `placeholder` | `undefined \| string` | Placeholder text shown in the empty input. |
 | `loading` | `loading` | `undefined \| false \| true` | When true, shows the loading/streaming state and disables submit (use while awaiting the assistant's reply). |
@@ -307,7 +307,7 @@ _No events._
 
 | Event | `detail` type | Description |
 |---|---|---|
-| `kai-message-action` | `CustomEvent<{ messageId: string; action: string }>` | An action button on a message was clicked. `action` is the built-in name or custom id. |
+| `kai-message-action` | `CustomEvent<{ messageId: string; action: string; state?: undefined \| "on" \| "off" }>` | An action button on a message was clicked. `action` is the built-in name or custom id. `state` is present only for the toggleable feedback votes: `'on'` when a like/dislike is set, `'off'` when re-tapped to clear. |
 | `kai-model-change` | `CustomEvent<{ modelId: string }>` | The header model switcher changed. |
 | `kai-search` | `CustomEvent<Record<string, never>>` | The Search button was clicked. |
 | `kai-slash-select` | `CustomEvent<{ command: { id: string; label: string; description?: undefined \| string; category?: undefined \| string } }>` | A slash command was chosen from the palette. |
@@ -368,6 +368,30 @@ _No events._
 
 ---
 
+### `kai-compare` / `Compare`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `data` | — | `undefined \| Record<string, unknown>` | The compare definition (prompt + the two candidates). Set as a JS PROPERTY: `el.data = { prompt, candidates: [A, B], collapse? }`. Import `ResponseCompareData` from `@kitn.ai/ui` for the full shape. |
+| `compareId` | `compare-id` | `undefined \| string` | Stable id correlating every emitted event. Attribute: `compare-id`. |
+| `selection` | — | `undefined \| Record<string, unknown>` | Re-hydrate / control the user's pick. Set as a JS PROPERTY: `el.selection = { chosenId, rejectedIds }`. Renders the collapsed winner. |
+| `layout` | `layout` | `undefined \| "auto" \| "columns" \| "tabs"` | Layout: `'auto'` (default — columns when wide, tabs when narrow, by CONTAINER width) \| `'columns'` (side-by-side) \| `'tabs'` (pills to switch). Attribute: `layout`. |
+| `proseSize` | `prose-size` | `undefined \| "xs" \| "sm" \| "base" \| "lg"` | Prose/text size for the rendered candidates. Attribute: `prose-size`. |
+| `codeTheme` | `code-theme` | `undefined \| string` | Shiki theme for code blocks in the candidates. Attribute: `code-theme`. |
+| `codeHighlight` | `code-highlight` | `undefined \| false \| true` | Whether code blocks are syntax-highlighted. Attribute: `code-highlight`. |
+
+**Events** (non-bubbling `CustomEvent`s — listen directly on the element):
+
+| Event | `detail` type | Description |
+|---|---|---|
+| `kai-compare-select` | `CustomEvent<{ chosenId: string; rejectedIds: string[]; at?: undefined \| number }>` | The user committed a pick. `detail` = `{ chosenId, rejectedIds, at }`. |
+| `kai-error` | `CustomEvent<{ compareId: string; message: string }>` | The definition was unusable. |
+| `kai-ready` | `CustomEvent<{ compareId: string }>` | Both candidates have settled and the pick is live. |
+
+---
+
 ### `kai-confirm` / `Confirm`
 
 **Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
@@ -587,7 +611,7 @@ _No events._
 
 | Property | Attribute | Type | Description |
 |---|---|---|---|
-| `message` | — | `undefined \| { id: string; role: "user" \| "assistant"; content: string; reasoning?: undefined \| { text: string; label?: undefined \| string }; tools?: undefined \| { type: string; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string }[]; attachments?: undefined \| { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }[]; actions?: undefined \| ("copy" \| "like" \| "dislike" \| "regenerate" \| "edit" \| { id: string; label: string; icon?: undefined \| string; tooltip?: undefined \| string })[]; avatar?: undefined \| { src?: undefined \| string; fallback?: undefined \| string; alt?: undefined \| string } }` | The full message object. Set as a JS property. |
+| `message` | — | `undefined \| { id: string; role: "user" \| "assistant"; content: string; reasoning?: undefined \| { text: string; label?: undefined \| string }; tools?: undefined \| { type: string; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string }[]; attachments?: undefined \| { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }[]; actions?: undefined \| ("copy" \| "like" \| "dislike" \| "regenerate" \| "edit" \| { id: string; label: string; icon?: undefined \| string; tooltip?: undefined \| string })[]; avatar?: undefined \| { src?: undefined \| string; fallback?: undefined \| string; alt?: undefined \| string }; feedback?: undefined \| "like" \| "dislike" }` | The full message object. Set as a JS property. |
 | `role` | `role` | `undefined \| "user" \| "assistant"` | Convenience for simple cases when not passing a `message` object. |
 | `content` | `content` | `undefined \| string` | Convenience content (used when `message` is not set). |
 | `markdown` | `markdown` | `undefined \| false \| true` | Force markdown on/off. Defaults to on for assistant, off for user. |
@@ -602,7 +626,7 @@ _No events._
 
 | Event | `detail` type | Description |
 |---|---|---|
-| `kai-message-action` | `CustomEvent<{ messageId: string; action: string }>` | An action button was clicked. `action` is the built-in name or custom id. |
+| `kai-message-action` | `CustomEvent<{ messageId: string; action: string; state?: undefined \| "on" \| "off" }>` | An action button was clicked. `action` is the built-in name or custom id. `state` is present only for the toggleable feedback votes: `'on'` when a like/dislike is set, `'off'` when re-tapped to clear. |
 
 ---
 
@@ -933,6 +957,27 @@ _No events._
 
 ---
 
+### `kai-toast-region` / `ToastRegion`
+
+**Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
+
+| Property | Attribute | Type | Description |
+|---|---|---|---|
+| `toasts` | — | `{ id: string; message: string; variant?: undefined \| "neutral" \| "success"; action?: undefined \| { label: string; onAction: () => void \| false }; duration?: undefined \| number; dismissible?: undefined \| false \| true; target?: undefined \| HTMLElement }[]` | The toasts to render. Newest is shown on top. Set as a JS property (array); pass a new array reference to update. |
+| `position` | `position` | `undefined \| "top-center" \| "top-right" \| "top-left" \| "bottom-center" \| "bottom-right" \| "bottom-left"` | Stack anchor: `'top-center'` (default), `'top-right'`, `'bottom-center'`, … |
+| `max` | `max` | `undefined \| number` | Max simultaneously-visible toasts; the rest queue. Defaults to `3`. |
+| `stack` | `stack` | `undefined \| "expanded" \| "collapsed"` | Stacking: 'expanded' (default, full column) \| 'collapsed' (Sonner-style pile that expands on hover/focus). Attribute: stack. |
+| `target` | — | `undefined \| HTMLElement` | Container element to anchor this region to (JS property). Set by the store for a scoped region; unset = the global viewport region. |
+
+**Events** (non-bubbling `CustomEvent`s — listen directly on the element):
+
+| Event | `detail` type | Description |
+|---|---|---|
+| `kai-action` | `CustomEvent<{ id: string; label: string }>` | A toast's action button was pressed. |
+| `kai-dismiss` | `CustomEvent<{ id: string; reason: "action" \| "timeout" \| "close" }>` | A toast left the stack. `reason` is `'timeout' \| 'close' \| 'action'`. |
+
+---
+
 ### `kai-tool` / `Tool`
 
 **Properties** (every element also accepts `theme="light|dark|auto"`; only scalar props work as HTML attributes):
@@ -973,7 +1018,7 @@ _No events._
 | `groups` | — | `{ id: string; userId?: undefined \| string; teamId?: undefined \| string; name: string; sortOrder: number; createdAt: string }[]` | Pre-bucketed conversation groups for the sidebar. Set as a JS property. |
 | `conversations` | — | `{ id: string; title: string; groupId?: undefined \| string; scope: { type: "document" \| "collection"; documentId?: undefined \| string; filters?: undefined \| { tags?: undefined \| string[]; authors?: undefined \| string[]; contentType?: undefined \| "transcript" \| "markdown"; dateRange?: undefined \| { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string }[]` | Flat conversation list (auto-bucketed if `groups` is empty). Set as a JS property. |
 | `activeId` | `active-id` | `undefined \| string` | Id of the open conversation, highlighted in the sidebar. |
-| `messages` | — | `{ id: string; role: "user" \| "assistant"; content: string; reasoning?: undefined \| { text: string; label?: undefined \| string }; tools?: undefined \| { type: string; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string }[]; attachments?: undefined \| { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }[]; actions?: undefined \| ("copy" \| "like" \| "dislike" \| "regenerate" \| "edit" \| { id: string; label: string; icon?: undefined \| string; tooltip?: undefined \| string })[]; avatar?: undefined \| { src?: undefined \| string; fallback?: undefined \| string; alt?: undefined \| string } }[]` | The active conversation's message thread, newest last. Set as a JS property. |
+| `messages` | — | `{ id: string; role: "user" \| "assistant"; content: string; reasoning?: undefined \| { text: string; label?: undefined \| string }; tools?: undefined \| { type: string; state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"; input?: undefined \| Record<string, unknown>; output?: undefined \| Record<string, unknown>; toolCallId?: undefined \| string; errorText?: undefined \| string }[]; attachments?: undefined \| { id: string; type: "file" \| "source-document"; filename?: undefined \| string; mediaType?: undefined \| string; url?: undefined \| string; title?: undefined \| string }[]; actions?: undefined \| ("copy" \| "like" \| "dislike" \| "regenerate" \| "edit" \| { id: string; label: string; icon?: undefined \| string; tooltip?: undefined \| string })[]; avatar?: undefined \| { src?: undefined \| string; fallback?: undefined \| string; alt?: undefined \| string }; feedback?: undefined \| "like" \| "dislike" }[]` | The active conversation's message thread, newest last. Set as a JS property. |
 | `value` | `value` | `undefined \| string` |  |
 | `placeholder` | `placeholder` | `undefined \| string` |  |
 | `loading` | `loading` | `undefined \| false \| true` |  |
@@ -1003,7 +1048,7 @@ _No events._
 | Event | `detail` type | Description |
 |---|---|---|
 | `kai-conversation-select` | `CustomEvent<{ id: string }>` | A conversation was selected in the sidebar. |
-| `kai-message-action` | `CustomEvent<{ messageId: string; action: string }>` | An action button on a message was clicked. |
+| `kai-message-action` | `CustomEvent<{ messageId: string; action: string; state?: undefined \| "on" \| "off" }>` | An action button on a message was clicked. `state` is present only for the toggleable feedback votes: `'on'` when a like/dislike is set, `'off'` when re-tapped to clear. |
 | `kai-model-change` | `CustomEvent<{ modelId: string }>` | The header model switcher changed. |
 | `kai-new-chat` | `CustomEvent<Record<string, never>>` | The "New chat" button was clicked. |
 | `kai-search` | `CustomEvent<Record<string, never>>` | The Search button was clicked. |

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. 44 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. 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.
 
 ## Install
 
@@ -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 44 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 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.
 
 ## 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 44 elements, every prop/event): ./llms-full.txt — https://kitn.dev/llms-full.txt
+- Full element reference (all 46 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

@@ -1678,7 +1678,111 @@ function compose(archetype, integration, placement, framework, suggestions, audi
     `Env vars to set:`,
     envLines
   ].join("\n");
-  return [header, block1, block2, block3].join("\n\n");
+  const block4 = [
+    `=== LOADING OPTIONS ===`,
+    ``,
+    `The scaffold uses \`import '@kitn.ai/ui/elements'\` (register-all) — the right`,
+    `default: it registers every kai-* element and is SSR-safe, so leave it as is.`,
+    `Two opt-in modes load less if a page only ever uses a few elements:`,
+    ``,
+    `  Per-element (bundler apps): import '@kitn.ai/ui/elements/<file>'`,
+    `    Registers just that element; your bundler tree-shakes the rest away.`,
+    `    Example: import '@kitn.ai/ui/elements/chat'  (client-only — not for SSR)`,
+    ``,
+    `  Autoloader (no-build / CDN pages): a <script type="module"> tag pointing at`,
+    `    dist/elements/autoloader.js — loads each kai-* element on demand as it`,
+    `    appears in the DOM. A CDN/static-file tool; not importable through a bundler.`,
+    ``,
+    `Run the debug tool with "reduce bundle size" for the full breakdown and sizes.`
+  ].join("\n");
+  const block5 = interactionPatternsBlock();
+  return [header, block1, block2, block3, block4, block5].join("\n\n");
+}
+function interactionPatternsBlock() {
+  const toastPattern = [
+    `--- Pattern: toast() — confirmation + Undo ---`,
+    `// toast is IMPERATIVE — call it; there is no <kai-toast> to place. The first`,
+    `// call auto-mounts one <kai-toast-region> on document.body. Exported from`,
+    `// both '@kitn.ai/ui' and '@kitn.ai/ui/elements'.`,
+    `import { toast } from '@kitn.ai/ui/elements';`,
+    ``,
+    `toast('Copied to clipboard');      // neutral, auto-dismisses`,
+    `toast.success('Saved');            // emerald success variant`,
+    ``,
+    `// Undo affordance: an action floors the duration so there's time to act.`,
+    `const t = toast('Item deleted', {`,
+    `  action: { label: 'Undo', onAction: () => restoreItem() },`,
+    `});`,
+    `// t.update({ message: 'Restored', variant: 'success' });  t.dismiss();`,
+    ``,
+    `// Collapsed (Sonner-style) stacking — toasts pile + expand on hover/focus.`,
+    `// Opt in once at startup, or per-region via <kai-toast-region stack="collapsed">.`,
+    `import { configureToasts } from '@kitn.ai/ui/elements';`,
+    `configureToasts({ stack: 'collapsed' });`
+  ].join("\n");
+  const recoveryPattern = [
+    `--- Pattern: dismissRecovery() — card dismiss + Undo (DEFERRED, not deleted) ---`,
+    `// Dismissing a generative-UI card does NOT delete its envelope — it stamps a`,
+    `// 'dismissed' resolution and collapses to a reopenable stub. Keep dismissed`,
+    `// envelopes in your array; wire the policy with dismissRecovery().`,
+    `import { dismissRecovery } from '@kitn.ai/ui';`,
+    `import { toast } from '@kitn.ai/ui/elements';`,
+    ``,
+    `// Adapter: map dismissRecovery's toast shape onto the imperative toast().`,
+    `const toastAdapter = {`,
+    `  show: ({ message, action, durationMs }) => {`,
+    `    const h = toast(message, {`,
+    `      duration: durationMs,`,
+    `      action: action && { label: action.label, onAction: action.onClick },`,
+    `    });`,
+    `    return { dismiss: h.dismiss };`,
+    `  },`,
+    `};`,
+    ``,
+    `const { onDismiss, onReopen } = dismissRecovery({`,
+    `  get: () => cards,                 // your current envelopes`,
+    `  set: (next) => setCards(next),    // a NEW array reference (never mutate in place)`,
+    `  toast: toastAdapter,`,
+    `});`,
+    `// Hand { onDismiss, onReopen } to the CardPolicy on <kai-cards> / <kai-remote>.`
+  ].join("\n");
+  const preferencePattern = [
+    `--- Pattern: kai-compare — capture an A/B preference pair ---`,
+    `// <kai-compare> shows EXACTLY two candidates for one prompt. data is a JS`,
+    `// PROPERTY; stream both columns with a fresh data ref per chunk; picking is`,
+    `// terminal and fires kai-compare-select { chosenId, rejectedIds }.`,
+    `import type { ResponseCompareData, CompareSelection } from '@kitn.ai/ui';`,
+    ``,
+    `const el = document.querySelector('kai-compare')!;`,
+    `el.data = {`,
+    `  prompt,`,
+    `  candidates: [`,
+    `    { id: 'a', content: '', streaming: true },`,
+    `    { id: 'b', content: '', streaming: true },`,
+    `  ],`,
+    `} satisfies ResponseCompareData;`,
+    ``,
+    `// Stream BOTH: replace data with a NEW object per chunk; clear streaming when`,
+    `// a candidate settles. The pick unlocks once both have settled (kai-ready).`,
+    `// el.data = { ...el.data, candidates: [{ ...a, content: aText }, { ...b, content: bText }] };`,
+    ``,
+    `el.addEventListener('kai-compare-select', (e) => {`,
+    `  const { chosenId, rejectedIds } = (e as CustomEvent<CompareSelection>).detail;`,
+    `  recordPreference({ prompt, chosen: chosenId, rejected: rejectedIds });`,
+    `});`
+  ].join("\n");
+  return [
+    `=== INTERACTION PATTERNS ===`,
+    ``,
+    `Optional snippets for confirmations, card recovery, and preference capture.`,
+    `Drop in the one(s) you need; all imports resolve from @kitn.ai/ui.`,
+    ``,
+    toastPattern,
+    ``,
+    recoveryPattern,
+    ``,
+    preferencePattern
+  ].join("\n");
 }
 function rejectIntegration(id) {
   const valid = listIntegrations().map((i) => `${i.id} (${i.title})`).join(", ");
@@ -2053,6 +2157,17 @@ const RULES = [
     cause: "A plain Vite/CRA React SPA has no server — there are no `/api` routes. A scaffolded Next.js route handler (`export async function POST`) does not run there, so `fetch('/api/chat')` 404s.",
     fix: "Either run the backend somewhere real, or skip it entirely for local dev:\n\n```ts\n// Option A — use Next.js where route handlers are supported\n// app/api/chat/route.ts: export async function POST(req) { ... }\n\n// Option B — add a Vite dev-server middleware/proxy\n// vite.config.ts: server: { proxy: { '/api': 'http://localhost:3001' } }\n\n// Option C — run a separate Express/Hono server\n// framework: 'express' in your harness config\n\n// Option D — zero-config local dev with mock integration (no backend needed)\n// Use `integration: 'mock'` in the scaffold tool\n```"
   },
+  {
+    // Rule 9 — reduce bundle size / footprint / "how much does @kitn.ai/ui add"
+    // Source: dist/elements/<file>.js per-element exports; dist/autoloader.js
+    id: "bundle-footprint",
+    test: (t) => /bundle\s*size|footprint|tree.?shak|how\s+much.*does.*@kitn|reduce.*import|import.*only.*element|per.?element\s+import|autoload|cdn.*no.?build|no.?build.*cdn/i.test(
+      t
+    ),
+    title: "Reducing bundle footprint — three load modes",
+    cause: "The default `import '@kitn.ai/ui/elements'` registers every `kai-*` element. If your page uses only one or two elements, that pulls in the full ~119 KB gz bundle. Two opt-in modes let you load only what you need.",
+    fix: "**Mode 1 — register-all (default, SSR-safe):**\nBest for multi-element apps or any SSR/meta-framework. Load once and every `kai-*` element is available.\n\n```js\nimport '@kitn.ai/ui/elements';  // ~119 KB gz — registers everything\n```\n\n**Mode 2 — per-element import (tree-shaking, bundler apps):**\nUse `import '@kitn.ai/ui/elements/<file>'` to register only one element. A bundler (Vite, webpack, Rollup) will tree-shake to just its chunks (~73 KB gz for `kai-chat` alone). Client-only — do not use in SSR entry points.\n\n```js\n// Registers only <kai-chat> (~73 KB gz vs ~119 KB gz register-all)\nimport '@kitn.ai/ui/elements/chat';\n\n// Other examples:\nimport '@kitn.ai/ui/elements/code-block';  // <kai-code-block>\nimport '@kitn.ai/ui/elements/confirm-card'; // <kai-confirm>\n```\n\nThe file name is the element's source basename from `element-manifest.json` (e.g. `kai-chat` → `chat`, `kai-confirm` → `confirm-card`).\n\n**Mode 3 — autoloader (no-build / CDN pages only):**\nWatches the DOM and dynamically imports each `kai-*` element's module on demand. A page that uses only `<kai-chat>` never downloads the other elements. It is a CDN / static-file tool — load it from a `<script type=\"module\">` tag. It is NOT importable through a bundler: Vite/webpack relocate it and the on-demand imports 404. Client-only.\n\n```html\n<script type=\"module\" src=\"https://cdn.jsdelivr.net/npm/@kitn.ai/ui@<version>/dist/elements/autoloader.js\"><\/script>\n```\n\nIn a BUNDLED app (Vite/webpack/Next) use Mode 1 or Mode 2 instead — not the autoloader.\n\n**SSR note:** use Mode 1 (register-all) in SSR apps — per-element imports and the autoloader are client-only (they call DOM APIs at module eval). Modes 1 & 2 are side-effect imports; keep them even if your linter flags them as \"unused\"."
+  },
   {
     // Rule 5 — SSR / server component / document is not defined
     // Source: for-ai-agents.mdx (client-only import); context7.json rule 2 (property rule requires DOM)
@@ -2065,6 +2180,47 @@ const RULES = [
     title: "SSR / server-side rendering — element requires the browser DOM",
     cause: '`kai-*` elements are client-side web components. They require `document` and `customElements` to register and render. Importing them in a server component (Next.js App Router server component, Nuxt SSR, etc.) throws "document is not defined" or silently produces no output.',
     fix: "Register the element on the client only. Use your framework's \"client-only\" / island / dynamic-import pattern.\n\n```js\n// ✅ Plain HTML / vanilla — import in a <script type=\"module\">\nimport '@kitn.ai/ui/elements';\n\n// ✅ Next.js App Router — mark the component with \"use client\"\n'use client';\nimport '@kitn.ai/ui/elements';\n\n// ✅ Next.js — dynamic import with ssr: false\nimport dynamic from 'next/dynamic';\nconst KaiChat = dynamic(() => import('@kitn.ai/ui/elements').then(() => 'kai-chat'), { ssr: false });\n\n// ✅ React wrapper (already client-safe)\nimport { Chat } from '@kitn.ai/ui/react';\n```"
+  },
+  {
+    // Rule 10 — toast() is the imperative API; there is no <kai-toast> to place
+    // Source: src/primitives/toast-store.ts (the `toast` fn + auto-mounted region)
+    id: "toast-imperative",
+    test: (t) => {
+      if (/<kai-toast(-region)?\b/.test(t)) return true;
+      if (/\btoast(s)?\b|notification|snackbar/i.test(t) && /how.*(show|raise|trigger|fire|display)|show.*toast|raise.*toast|trigger.*toast|toast.*(not|isn'?t|won'?t).*(show|appear|render)|where.*toast|add.*toast|kai-|@kitn/i.test(t))
+        return true;
+      return false;
+    },
+    title: "Toast is an imperative call — `toast('…')`, not a `<kai-toast>` you place",
+    cause: "Toasts are raised IMPERATIVELY by calling `toast(message)` — there is no `<kai-toast>` element you add to your markup. The first call lazily mounts ONE `<kai-toast-region>` on `document.body` (a real, kit-styled, viewport-positioned element) and every later toast feeds that same region. Trying to place a toast element by hand, or looking for a `messages`/`toasts` prop to push into, is the wrong model.",
+    fix: "Import `toast` and call it. It is exported from BOTH the root `@kitn.ai/ui` and the `@kitn.ai/ui/elements` bundle, so the web-components-only consumer gets it too. It is SSR-safe (no DOM is touched until the first call on the client).\n\n```js\nimport { toast } from '@kitn.ai/ui/elements'; // or '@kitn.ai/ui'\n\n// ✅ Fire-and-forget\ntoast('Copied to clipboard');\ntoast.success('Saved');\n\n// ✅ With an Undo action + an imperative handle\nconst t = toast('Item deleted', {\n  action: { label: 'Undo', onAction: () => restore() },\n});\nt.update({ message: 'Restored', variant: 'success' });\nt.dismiss();\n```\n\nThe auto-mounted `<kai-toast-region>` carries its own shadow root + kit styles — do NOT add a `<kai-toast-region>` tag yourself unless you deliberately want a second, declaratively-controlled region."
+  },
+  {
+    // Rule 11 — dismissed cards are DEFERRED (reopenable stub), not deleted
+    // Source: src/primitives/card-recovery.ts (dismissRecovery) + the dismissed stub
+    id: "card-dismiss-deferred",
+    test: (t) => {
+      const cardCtx = /\bcard(s)?\b|envelope|kai-card|kai-cards|kai-confirm|kai-choice|kai-tasks|kai-form|generative.?ui|resolution|dismissRecovery/i;
+      if (!cardCtx.test(t)) return false;
+      return /dismiss|reopen|re-?open|\bundo\b|disappear|remove.*card|card.*(gone|remove|delete|vanish)|filter.*out|stub/i.test(t);
+    },
+    title: "Dismissed cards are DEFERRED (a reopenable stub), not deleted",
+    cause: "Dismissing a generative-UI card does NOT delete its envelope from history. The card stamps a `{ kind: 'dismissed' }` resolution onto its envelope and collapses to a small reopenable stub (\"Proposed: <title> — dismissed · Reopen\"). If you filter `dismissed` envelopes out of your cards array, the stub vanishes and the user can never reopen it — and you lose the audit trail of what was proposed.",
+    fix: "Keep dismissed envelopes in the array. Wire dismiss/reopen with `dismissRecovery()` (from `@kitn.ai/ui`), which builds the `onDismiss`/`onReopen` half of a `CardPolicy` over your store and can show a \"Dismissed · Undo\" toast via an injected adapter.\n\n```ts\nimport { dismissRecovery } from '@kitn.ai/ui';\nimport { toast } from '@kitn.ai/ui/elements';\n\n// Adapter: map dismissRecovery's toast shape onto the imperative toast().\nconst toastAdapter = {\n  show: ({ message, action, durationMs }) => {\n    const handle = toast(message, {\n      duration: durationMs,\n      action: action && { label: action.label, onAction: action.onClick },\n    });\n    return { dismiss: handle.dismiss };\n  },\n};\n\nconst { onDismiss, onReopen } = dismissRecovery({\n  get: () => cards,            // your current envelopes\n  set: (next) => setCards(next), // NEW array reference (never mutate in place)\n  toast: toastAdapter,\n});\n// Pass these on the CardPolicy you hand to <kai-cards> / <kai-remote>.\n```\n\n`onDismiss` writes `dismissed` immutably (Undo restores the prior resolution); `onReopen` clears it back to live (or stamps `expired` when the host says the card is no longer reopenable). Never mutate the array in place — re-render needs a new ref."
+  },
+  {
+    // Rule 12 — kai-compare contract: two candidates, JS data prop, stream both, terminal pick
+    // Source: src/elements/compare.tsx + src/components/response-compare-types.ts
+    id: "compare-contract",
+    test: (t) => {
+      if (/<kai-compare\b|kai-compare-select|ResponseCompareData|response.?compare/i.test(t)) return true;
+      if (/compar(e|ing|ison)|side.by.side|a\/b|two\s+(responses|candidates|answers|completions)|dual.?response/i.test(t) && /kai-|@kitn|candidate|prefer(ence)?|chosen|reject/i.test(t))
+        return true;
+      return false;
+    },
+    title: "`kai-compare` — two candidates, `data` as a JS property, terminal pick",
+    cause: "`<kai-compare>` shows EXACTLY two assistant candidates for one prompt and lets the user pick the better one. The `data` value is an array/object, so it must be set as a JS PROPERTY (never an HTML attribute). Both candidates can stream — but, like `kai-chat`, that needs a NEW `data` reference per chunk (mutating in place will not re-render). The pick is a COMMIT (not a Submit): it fires once and the card collapses.",
+    fix: "Set `data` in JS with two candidates, stream by reassigning a fresh `data` object per chunk, and listen for `kai-compare-select` directly on the element.\n\n```ts\nimport { toast } from '@kitn.ai/ui/elements';\nimport type { ResponseCompareData, CompareSelection } from '@kitn.ai/ui';\n\nconst el = document.querySelector('kai-compare')!;\n// data is a JS PROPERTY — exactly two candidates, each with a unique id.\nel.data = {\n  prompt: 'Summarise the report',\n  candidates: [\n    { id: 'a', content: '', streaming: true },\n    { id: 'b', content: '', streaming: true },\n  ],\n} satisfies ResponseCompareData;\n\n// Stream BOTH columns: replace data with a NEW object per chunk.\nel.data = { ...el.data, candidates: [{ ...a, content: aText }, { ...b, content: bText }] };\n// Clear `streaming` on a candidate when it settles — the pick stays disabled\n// until BOTH have settled, then `kai-ready` fires.\n\n// Picking is terminal: emits { chosenId, rejectedIds, at } and collapses.\nel.addEventListener('kai-compare-select', (e) => {\n  const { chosenId, rejectedIds } = (e as CustomEvent<CompareSelection>).detail;\n  recordPreference({ prompt, chosen: chosenId, rejected: rejectedIds });\n});\n```\n\nA malformed definition (not two candidates, missing/duplicate ids) fires `kai-error` instead. The event is non-bubbling — listen on the element, not on `document`."
   }
 ];
 function buildText(matched) {

package/dist/primitives/card-contract.d.ts

@@ -60,6 +60,9 @@ export type CardEvent = {
 } | {
     kind: 'dismiss';
     cardId: string;
+} | {
+    kind: 'reopen';
+    cardId: string;
 } | {
     kind: 'error';
     cardId: string;
@@ -67,10 +70,13 @@ export type CardEvent = {
 };
 export type CardEventKind = CardEvent['kind'];
 /** How a card was resolved by the user — the re-hydration channel for the chromed
- *  read-only state. Mirrors the two terminal CardEvents (minus `cardId`): the
- *  resolution is just the event that resolved the card. `at` is optional ISO-8601
- *  provenance (data only; never rendered). Additive — does not bump the contract
- *  version. */
+ *  read-only state. The terminal kinds (`action`/`submit`) mirror the two terminal
+ *  CardEvents (minus `cardId`): the resolution is just the event that resolved the
+ *  card. `dismissed` is a DEFERRED (non-terminal) state — the user set the card
+ *  aside; it can be re-opened. `expired` is terminal — a dismissed card the host
+ *  decided can no longer be re-opened (e.g. the agent proceeded, or it went stale).
+ *  `at` is optional ISO-8601 provenance (data only; never rendered). Additive —
+ *  does not bump the contract version. */
 export type CardResolution = {
     kind: 'action';
     action: string;
@@ -80,6 +86,13 @@ export type CardResolution = {
     kind: 'submit';
     data: unknown;
     at?: string;
+} | {
+    kind: 'dismissed';
+    at?: string;
+} | {
+    kind: 'expired';
+    reason?: string;
+    at?: string;
 };
 /** What every card is handed (via native context or the iframe bridge). */
 export interface CardHost {
@@ -97,6 +110,9 @@ export interface CardPolicy {
     onOpen?: (url: string, target: 'tab' | 'artifact') => void;
     onState?: (cardId: string, patch: unknown) => void;
     onDismiss?: (cardId: string) => void;
+    /** A dismissed card asked to be re-opened. The host decides whether it can come
+     *  back (clear the resolution → live again) or has expired (stamp `expired`). */
+    onReopen?: (cardId: string) => void;
     onError?: (cardId: string, message: string) => void;
     /** Cap on send-prompt: 'compose' (default) forbids silent sends. 'send' to allow. */
     maxSendPromptMode?: 'compose' | 'send';

package/dist/primitives/card-recovery.d.ts

@@ -0,0 +1,55 @@
+import { CardEnvelope, CardPolicy, CardResolution } from './card-contract';
+/** The minimal toast surface this helper needs. Inject a real adapter (e.g. one
+ *  backed by `kai-toast-region`) — this module never imports the toast itself. */
+export interface RecoveryToast {
+    show(opts: {
+        message: string;
+        action?: {
+            label: string;
+            onClick: () => void;
+        };
+        durationMs?: number;
+    }): {
+        dismiss(): void;
+    };
+}
+/** Context handed to a custom `isReopenable` predicate. */
+export interface ReopenEnv {
+    cardId: string;
+    /** The card's current resolution at reopen time (should be `dismissed`). */
+    resolution: CardResolution | undefined;
+    /** `Date.now()` at reopen time (injected for testability). */
+    now: number;
+}
+export interface DismissRecoveryOptions {
+    /** Read the current cards array. */
+    get: () => CardEnvelope[];
+    /** Write the next cards array (a NEW reference). */
+    set: (next: CardEnvelope[]) => void;
+    /** Optional injected toast adapter for the "Dismissed · Undo" affordance. */
+    toast?: RecoveryToast;
+    /** Override the default re-openable rule. Return false to expire instead. */
+    isReopenable?: (env: ReopenEnv) => boolean;
+    /** A dismissed card older than this (ms since `dismissed.at`) is no longer
+     *  re-openable (→ expired). Omit/Infinity = never stale. */
+    staleAfterMs?: number;
+    /** Auto-dismiss the Undo toast after this long. Default 6000ms. */
+    undoMs?: number;
+    /** Injected clock (defaults to Date.now); keeps the helper testable. */
+    now?: () => number;
+}
+/** Default re-openable rule: a card can come back unless it carries a terminal
+ *  resolution OR it has gone stale (`staleAfterMs` elapsed since `dismissed.at`).
+ *  A `dismissed` card with no/invalid `at` is always re-openable. */
+export declare function defaultIsReopenable(env: ReopenEnv, staleAfterMs?: number): boolean;
+/**
+ * Build the `{ onDismiss, onReopen }` policy handlers for the card dismiss/recovery
+ * flow over a host store (`get`/`set`).
+ *
+ * - `onDismiss(cardId)` — stamps `{ kind:'dismissed', at }` immutably and, when a
+ *   `toast` is injected, shows "Dismissed" with an Undo that restores the card's
+ *   prior resolution (live again when there was none).
+ * - `onReopen(cardId)` — clears the resolution (live) when `isReopenable`, else
+ *   stamps `{ kind:'expired', at }`.
+ */
+export declare function dismissRecovery(opts: DismissRecoveryOptions): Pick<CardPolicy, 'onDismiss' | 'onReopen'>;

package/dist/primitives/message-feedback.d.ts

@@ -0,0 +1,35 @@
+import { ChatMessage, FeedbackVote } from '../elements/chat-types';
+/** Detail shape emitted by the action row. `state` is present only for the
+ *  toggleable feedback votes: `'on'` when a vote is set, `'off'` when cleared.
+ *  Copy / regenerate / edit / custom actions omit it. */
+export interface MessageActionDetail {
+    messageId: string;
+    action: string;
+    state?: 'on' | 'off';
+}
+export interface MessageFeedbackOptions {
+    /** Emit the `kai-message-action` detail (facade maps this to `dispatch` /
+     *  `onMessageAction`). */
+    emit: (detail: MessageActionDetail) => void;
+    /** How long the copy check stays before auto-clearing. Defaults to 2000ms. */
+    copiedDuration?: number;
+    /** Container the copy/feedback toasts should be scoped to (the chat, by
+     *  default) so they appear in-chat rather than at the page top. */
+    target?: () => HTMLElement | undefined;
+}
+export interface MessageFeedback {
+    /** Resolve the active vote for a message: a controlled `m.feedback` wins,
+     *  else the facade's own optimistic map. */
+    resolveFeedback: (m: Pick<ChatMessage, 'id' | 'feedback'>) => FeedbackVote | undefined;
+    /** Whether a message's copy button should currently show its check. */
+    isCopied: (id: string) => boolean;
+    /** Route a clicked action through copy / vote / passthrough handling. */
+    handleAction: (m: Pick<ChatMessage, 'id' | 'content' | 'feedback'>, action: string) => void;
+}
+/**
+ * Create the action-row feedback controller for one message list (or one
+ * standalone message). Owns the optimistic `feedbackMap` + transient
+ * `copiedIds`, resolves the controlled-wins vote, and turns clicks into
+ * clipboard writes, toasts, and `kai-message-action` emissions.
+ */
+export declare function createMessageFeedback(opts: MessageFeedbackOptions): MessageFeedback;

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

@@ -0,0 +1,88 @@
+import { ToastPosition } from '../components/toast';
+export type ToastVariant = 'neutral' | 'success';
+export interface ToastConfig {
+    stack?: 'expanded' | 'collapsed';
+    position?: ToastPosition;
+    max?: number;
+}
+/**
+ * Configure the imperative `toast()` singleton — call once at app start.
+ * `toast.success('…')` has no element to set a prop on, so this is how you opt
+ * the auto-mounted region into collapsed stacking / a position / a max. Updates
+ * any already-mounted regions too, so call order doesn't matter.
+ */
+export declare function configureToasts(config: ToastConfig): void;
+/** An action button rendered inside the toast. Returning `false` from
+ *  `onAction` keeps the toast open (e.g. to show a follow-up); any other
+ *  return value dismisses it. */
+export interface ToastAction {
+    label: string;
+    onAction: () => void | false;
+}
+export interface ToastItem {
+    id: string;
+    message: string;
+    variant?: ToastVariant;
+    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
+     *  to act on. Defaults to 2000ms. */
+    duration?: number;
+    /** Whether the × close affordance is shown. Defaults to `true`. */
+    dismissible?: boolean;
+    /** Container to scope this toast WITHIN — it floats anchored to that element's
+     *  bounds instead of the viewport. Omit for a global, viewport-anchored toast.
+     *  The chat targets itself by default so its copy/feedback toasts stay in-chat. */
+    target?: HTMLElement;
+}
+/** Options accepted by `toast()` — everything but the message. Pass `id` to
+ *  update an existing toast in place. */
+export interface ToastOptions {
+    id?: string;
+    variant?: ToastVariant;
+    action?: ToastAction;
+    duration?: number;
+    dismissible?: boolean;
+    /** Scope this toast to a container's bounds (e.g. a chat) instead of the
+     *  viewport. Omit for a global, viewport-anchored toast. */
+    target?: HTMLElement;
+}
+/** Handle returned from `toast()` for imperative control. */
+export interface ToastHandle {
+    id: string;
+    dismiss: () => void;
+    update: (patch: Partial<Omit<ToastItem, 'id'>>) => void;
+}
+/** Default auto-dismiss delay. Long enough to read + reach before it leaves. */
+export declare const DEFAULT_TOAST_DURATION = 5000;
+/** Minimum auto-dismiss delay when the toast carries an action (e.g. Undo) — it
+ *  has to stay up long enough to actually act on. */
+export declare const ACTION_TOAST_FLOOR = 7000;
+/** The live toast list (reactive). The region facade binds to this. */
+export declare function getToasts(): ToastItem[];
+/** Resolve the effective duration, applying the action floor. */
+declare function resolveDuration(item: Pick<ToastItem, 'duration' | 'action'>): number;
+export declare function ensureMounted(target?: HTMLElement | null): HTMLElement | undefined;
+/** Test-only: whether `ensureMounted` has run. */
+export declare function isToastRegionMounted(): boolean;
+export interface ToastFn {
+    (message: string, opts?: ToastOptions): ToastHandle;
+    /** Raise a success (emerald check) toast. */
+    success: (message: string, opts?: ToastOptions) => ToastHandle;
+    /** Dismiss a toast by id. */
+    dismiss: (id: string) => void;
+    /** Dismiss every active toast. */
+    clear: () => void;
+}
+/**
+ * Raise a transient toast. Returns a `{ id, dismiss, update }` handle.
+ *
+ * ```ts
+ * toast('Copied to clipboard');
+ * toast.success('Saved');
+ * const t = toast('Working…', { duration: 0 });
+ * t.update({ message: 'Done', variant: 'success', duration: 2000 });
+ * ```
+ */
+export declare const toast: ToastFn;
+export { resolveDuration };