@kitn.ai/ui 0.15.1 → 0.17.0

package/src/elements/element-types.d.ts

@@ -5,8 +5,9 @@
 
 // Re-exports for `import { … } from '@kitn.ai/ui/elements'`.
 export type { ChatMessage, ChatMessageAction } from './chat-types';
-export { configureCodeHighlighting, isCodeHighlightingEnabled } from '../primitives/highlighter';
 export type { CodeHighlightingOptions } from '../primitives/highlighter';
+export declare function configureCodeHighlighting(options: CodeHighlightingOptions): void;
+export declare function isCodeHighlightingEnabled(): boolean;
 
 export interface KaiArtifactElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
@@ -79,11 +80,11 @@ export interface KaiCardsElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
   theme?: 'light' | 'dark' | 'auto';
   /** The stream of card envelopes to render. Set as a JS PROPERTY: `el.cards = [...]`. */
-  cards?: { type: string; id: string; data: unknown; title?: string; resolution?: { kind: "action"; action: string; payload?: unknown; at?: string } | { kind: "submit"; data: unknown; at?: string } }[];
+  cards?: { type: string; id: string; data: unknown; title?: string; resolution?: { kind: "action"; action: string; payload?: unknown; at?: string } | { kind: "submit"; data: unknown; at?: string } | { kind: "dismissed"; at?: string } | { kind: "expired"; reason?: string; at?: 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. */
   types?: Record<string, string>;
   /** Optional CardPolicy handling child events. Property: `el.policy`. */
-  policy?: { onSubmit?: (cardId: string, data: unknown) => void; onAction?: (cardId: string, action: string, payload?: unknown) => void; onSendPrompt?: (text: string, opts: { mode: "compose" | "send"; context?: unknown; }) => void; onOpen?: (url: string, target: "tab" | "artifact") => void; onState?: (cardId: string, patch: unknown) => void; onDismiss?: (cardId: string) => void; onError?: (cardId: string, message: string) => void; maxSendPromptMode?: "compose" | "send" };
+  policy?: { onSubmit?: (cardId: string, data: unknown) => void; onAction?: (cardId: string, action: string, payload?: unknown) => void; onSendPrompt?: (text: string, opts: { mode: "compose" | "send"; context?: unknown; }) => void; onOpen?: (url: string, target: "tab" | "artifact") => void; onState?: (cardId: string, patch: unknown) => void; onDismiss?: (cardId: string) => void; onReopen?: (cardId: string) => void; onError?: (cardId: string, message: string) => void; maxSendPromptMode?: "compose" | "send" };
 }
 
 export interface KaiChainOfThoughtElement extends HTMLElement {
@@ -97,7 +98,7 @@ export interface KaiChatElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
   theme?: 'light' | 'dark' | 'auto';
   /** 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 } }[];
+  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" }[];
   /** 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. */
   value?: string;
   /** Placeholder text shown in the empty input. */
@@ -185,6 +186,25 @@ export interface KaiCodeBlockElement extends HTMLElement {
   proseSize?: "xs" | "sm" | "base" | "lg";
 }
 
+export interface KaiCompareElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** 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. */
+  data?: Record<string, unknown>;
+  /** Stable id correlating every emitted event. Attribute: `compare-id`. */
+  compareId?: string;
+  /** Re-hydrate / control the user's pick. Set as a JS PROPERTY: `el.selection = { chosenId, rejectedIds }`. Renders the collapsed winner. */
+  selection?: Record<string, unknown>;
+  /** Layout: `'auto'` (default — columns when wide, tabs when narrow, by CONTAINER width) | `'columns'` (side-by-side) | `'tabs'` (pills to switch). Attribute: `layout`. */
+  layout?: "auto" | "columns" | "tabs";
+  /** Prose/text size for the rendered candidates. Attribute: `prose-size`. */
+  proseSize?: "xs" | "sm" | "base" | "lg";
+  /** Shiki theme for code blocks in the candidates. Attribute: `code-theme`. */
+  codeTheme?: string;
+  /** Whether code blocks are syntax-highlighted. Attribute: `code-highlight`. */
+  codeHighlight?: boolean;
+}
+
 export interface KaiConfirmElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
   theme?: 'light' | 'dark' | 'auto';
@@ -346,7 +366,7 @@ export interface KaiMessageElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
   theme?: 'light' | 'dark' | 'auto';
   /** The full message object. Set as a JS property. */
-  message?: { id: string; role: "user" | "assistant"; content: string; reasoning?: { text: string; label?: string }; tools?: { type: string; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; output?: Record<string, unknown>; toolCallId?: string; errorText?: string }[]; attachments?: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }[]; actions?: ("copy" | "like" | "dislike" | "regenerate" | "edit" | { id: string; label: string; icon?: string; tooltip?: string })[]; avatar?: { src?: string; fallback?: string; alt?: string } };
+  message?: { id: string; role: "user" | "assistant"; content: string; reasoning?: { text: string; label?: string }; tools?: { type: string; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; output?: Record<string, unknown>; toolCallId?: string; errorText?: string }[]; attachments?: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }[]; actions?: ("copy" | "like" | "dislike" | "regenerate" | "edit" | { id: string; label: string; icon?: string; tooltip?: string })[]; avatar?: { src?: string; fallback?: string; alt?: string }; feedback?: "like" | "dislike" };
   /** Convenience for simple cases when not passing a `message` object. */
   role?: "user" | "assistant";
   /** Convenience content (used when `message` is not set). */
@@ -601,6 +621,21 @@ export interface KaiThinkingBarElement extends HTMLElement {
   stopLabel?: string;
 }
 
+export interface KaiToastRegionElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** The toasts to render. Newest is shown on top. Set as a JS property (array); pass a new array reference to update. */
+  toasts: { id: string; message: string; variant?: undefined | "neutral" | "success"; action?: undefined | { label: string; onAction: () => void | false }; duration?: undefined | number; dismissible?: undefined | boolean; target?: undefined | HTMLElement }[];
+  /** Stack anchor: `'top-center'` (default), `'top-right'`, `'bottom-center'`, … */
+  position?: "top-center" | "top-right" | "top-left" | "bottom-center" | "bottom-right" | "bottom-left";
+  /** Max simultaneously-visible toasts; the rest queue. Defaults to `3`. */
+  max?: number;
+  /** Stacking: 'expanded' (default, full column) | 'collapsed' (Sonner-style pile that expands on hover/focus). Attribute: stack. */
+  stack?: "expanded" | "collapsed";
+  /** Container element to anchor this region to (JS property). Set by the store for a scoped region; unset = the global viewport region. */
+  target?: HTMLElement;
+}
+
 export interface KaiToolElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
   theme?: 'light' | 'dark' | 'auto';
@@ -629,7 +664,7 @@ export interface KaiWorkspaceElement extends HTMLElement {
   /** Id of the open conversation, highlighted in the sidebar. */
   activeId?: 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 } }[];
+  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" }[];
   value?: string;
   placeholder?: string;
   loading?: boolean;
@@ -671,6 +706,7 @@ declare global {
     'kai-checkpoint': KaiCheckpointElement;
     'kai-choice': KaiChoiceElement;
     'kai-code-block': KaiCodeBlockElement;
+    'kai-compare': KaiCompareElement;
     'kai-confirm': KaiConfirmElement;
     'kai-context': KaiContextElement;
     'kai-conversations': KaiConversationsElement;
@@ -703,6 +739,7 @@ declare global {
     'kai-tasks': KaiTasksElement;
     'kai-text-shimmer': KaiTextShimmerElement;
     'kai-thinking-bar': KaiThinkingBarElement;
+    'kai-toast-region': KaiToastRegionElement;
     'kai-tool': KaiToolElement;
     'kai-voice-input': KaiVoiceInputElement;
     'kai-workspace': KaiWorkspaceElement;

package/src/elements/framework-usage.json

@@ -113,6 +113,18 @@
       "solid": "import { CodeBlock } from '@kitn.ai/ui';\n\n<CodeBlock\n  code={code}\n/>"
     }
   },
+  {
+    "tag": "kai-compare",
+    "displayName": "Compare",
+    "hasSolid": false,
+    "snippets": {
+      "html": "<script type=\"module\" src=\"https://cdn.jsdelivr.net/npm/@kitn.ai/ui/dist/kitn-chat.es.js\"></script>\n\n<kai-compare></kai-compare>\n<script type=\"module\">\n  const el = document.querySelector('kai-compare');\n  el.addEventListener('kai-compare-select', (e) => console.log(e.detail));\n  el.addEventListener('kai-error', (e) => console.log(e.detail));\n  el.addEventListener('kai-ready', (e) => console.log(e.detail));\n</script>",
+      "react": "import { Compare } from '@kitn.ai/ui/react';\n\n<Compare\n  onCompareSelect={(e) => console.log(e.detail)}\n  onError={(e) => console.log(e.detail)}\n  onReady={(e) => console.log(e.detail)}\n/>",
+      "vue": "<kai-compare\n  @kai-compare-select=\"onCompareSelect\"\n  @kai-error=\"onError\"\n  @kai-ready=\"onReady\"\n/>",
+      "svelte": "<script>\n  import '@kitn.ai/ui/elements';\n</script>\n\n<kai-compare\n  on:kai-compare-select={onCompareSelect}\n  on:kai-error={onError}\n  on:kai-ready={onReady}\n></kai-compare>",
+      "angular": "<kai-compare\n  (kai-compare-select)=\"onCompareSelect($event)\"\n  (kai-error)=\"onError($event)\"\n  (kai-ready)=\"onReady($event)\"\n></kai-compare>"
+    }
+  },
   {
     "tag": "kai-confirm",
     "displayName": "Confirm",
@@ -522,6 +534,19 @@
       "solid": "import { ThinkingBar } from '@kitn.ai/ui';\n\n<ThinkingBar\n  onStop={(e) => console.log(e.detail)}\n/>"
     }
   },
+  {
+    "tag": "kai-toast-region",
+    "displayName": "ToastRegion",
+    "hasSolid": true,
+    "snippets": {
+      "html": "<script type=\"module\" src=\"https://cdn.jsdelivr.net/npm/@kitn.ai/ui/dist/kitn-chat.es.js\"></script>\n\n<kai-toast-region></kai-toast-region>\n<script type=\"module\">\n  const el = document.querySelector('kai-toast-region');\n  el.toasts = /* … */;\n  el.addEventListener('kai-action', (e) => console.log(e.detail));\n  el.addEventListener('kai-dismiss', (e) => console.log(e.detail));\n</script>",
+      "react": "import { ToastRegion } from '@kitn.ai/ui/react';\n\n<ToastRegion\n  toasts={toasts}\n  onAction={(e) => console.log(e.detail)}\n  onDismiss={(e) => console.log(e.detail)}\n/>",
+      "vue": "<kai-toast-region\n  :toasts.prop=\"toasts\"\n  @kai-action=\"onAction\"\n  @kai-dismiss=\"onDismiss\"\n/>",
+      "svelte": "<script>\n  import '@kitn.ai/ui/elements';\n</script>\n\n<kai-toast-region\n  {toasts}\n  on:kai-action={onAction}\n  on:kai-dismiss={onDismiss}\n></kai-toast-region>",
+      "angular": "<kai-toast-region\n  [toasts]=\"toasts\"\n  (kai-action)=\"onAction($event)\"\n  (kai-dismiss)=\"onDismiss($event)\"\n></kai-toast-region>",
+      "solid": "import { ToastRegion } from '@kitn.ai/ui';\n\n<ToastRegion\n  toasts={toasts}\n  onAction={(e) => console.log(e.detail)}\n  onDismiss={(e) => console.log(e.detail)}\n/>"
+    }
+  },
   {
     "tag": "kai-tool",
     "displayName": "Tool",

package/src/elements/message.tsx

@@ -1,10 +1,8 @@
-import { For, Show, createSignal, onMount, onCleanup } from 'solid-js';
+import { Show, createSignal, onMount, onCleanup } from 'solid-js';
 import { defineWebComponent } from './define';
 import { ChatConfig, useChatConfig, type ProseSize } from '../primitives/chat-config';
-import { Message, MessageAvatar, MessageContent, MessageActionBar } from '../components/message';
-import { Reasoning, ReasoningTrigger, ReasoningContent } from '../components/reasoning';
-import { Tool } from '../components/tool';
-import { Attachments, Attachment, AttachmentPreview, AttachmentInfo } from '../components/attachments';
+import { Message, MessageAvatar, MessageBody } from '../components/message';
+import { createMessageFeedback } from '../primitives/message-feedback';
 import type { ChatMessage } from './chat-types';
 
 interface Props extends Record<string, unknown> {
@@ -33,8 +31,10 @@ interface Props extends Record<string, unknown> {
 
 /** Events fired by `<kai-message>`. */
 interface Events {
-  /** An action button was clicked. `action` is the built-in name or custom id. */
-  'kai-message-action': { messageId: string; action: string };
+  /** 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. */
+  'kai-message-action': { messageId: string; action: string; state?: 'on' | 'off' };
 }
 
 /**
@@ -58,6 +58,12 @@ defineWebComponent<Props, Events>('kai-message', {
   const outer = useChatConfig();
   const msg = (): ChatMessage =>
     props.message ?? { id: 'message', role: props.role ?? 'assistant', content: props.content ?? '' };
+  // Copy + vote state lives here (above the rendered body) so it survives a
+  // re-render when the host swaps in a fresh `message` object during streaming.
+  const feedback = createMessageFeedback({
+    emit: (detail) => dispatch('kai-message-action', detail),
+    target: () => element,
+  });
 
   // Read declarative <kai-action> children from light DOM.
   // Shadow DOM with no <slot> suppresses them visually — they're invisible data carriers.
@@ -89,45 +95,21 @@ defineWebComponent<Props, Events>('kai-message', {
     element.hasAttribute('markdown') || props.markdown === true || props.markdown === false;
   const useMarkdown = () => (markdownExplicit() ? flag('markdown') : !isUser());
 
+  const mergedActions = () => [...(msg().actions ?? []), ...slottedActions()];
   const body = () => (
-    <>
-      <Show when={msg().reasoning}>
-        <Reasoning class="mb-2 w-full">
-          <ReasoningTrigger>{msg().reasoning!.label ?? 'Reasoning'}</ReasoningTrigger>
-          <ReasoningContent markdown>{msg().reasoning!.text}</ReasoningContent>
-        </Reasoning>
-      </Show>
-      <For each={msg().tools ?? []}>
-        {(tp) => <Tool toolPart={tp} class="mb-2 w-full" />}
-      </For>
-      <Show when={msg().attachments?.length}>
-        <Attachments variant="inline" class={isUser() ? 'mb-2 justify-end' : 'mb-2'}>
-          <For each={msg().attachments!}>
-            {(att) => (
-              <Attachment data={att}>
-                <AttachmentPreview />
-                <AttachmentInfo />
-              </Attachment>
-            )}
-          </For>
-        </Attachments>
-      </Show>
-      <MessageContent
-        markdown={useMarkdown()}
-        class={isUser()
-          ? 'bg-muted text-primary max-w-[85%] rounded-2xl px-4 py-2'
-          : 'bg-transparent p-0'}
-      >
-        {msg().content}
-      </MessageContent>
-      <Show when={(msg().actions?.length ?? 0) > 0 || slottedActions().length > 0}>
-        <MessageActionBar
-          actions={[...(msg().actions ?? []), ...slottedActions()]}
-          reveal={reveal()}
-          onAction={(action) => dispatch('kai-message-action', { messageId: msg().id, action })}
-        />
-      </Show>
-    </>
+    <MessageBody
+      content={msg().content}
+      reasoning={msg().reasoning}
+      tools={msg().tools}
+      attachments={msg().attachments}
+      isUser={isUser()}
+      markdown={useMarkdown()}
+      actions={mergedActions()}
+      actionsReveal={reveal()}
+      activeFeedback={feedback.resolveFeedback(msg())}
+      copied={feedback.isCopied(msg().id)}
+      onAction={(action) => feedback.handleAction(msg(), action)}
+    />
   );
 
   // Row carries `group` so a hover-revealed action bar fades in on row hover.

package/src/elements/register-impl.ts

@@ -0,0 +1,58 @@
+// Component registration implementation. Importing this file defines all kitn
+// custom elements as a side effect. It is dynamically imported (browser-only)
+// from ./register.ts so the elements entry is SSR-import-safe — see the comment
+// there. This file is hand-maintained (the generator gen-element-api.mjs SKIPs
+// register.ts AND this file); keep the component import list here in sync.
+import './conversation-list';
+import './prompt-input';
+import './chat';
+import './chat-workspace';
+// Composable leaf elements (spike — see docs/handoff + examples/composable)
+import './thinking-bar';
+import './model-switcher';
+import './attachments';
+// Phase 1 — message-rendering core
+import './message';
+import './markdown';
+import './code-block';
+import './reasoning';
+import './tool';
+// Phase 2 — header / meta
+import './context-meter';
+import './feedback-bar';
+import './chat-scope-picker';
+// Phase 3 — input ecosystem
+// (NB: SlashCommand is context-bound to PromptInput — it observes the input
+//  value via usePromptInput() — so it is NOT a standalone element. It will fold
+//  into <kai-prompt-input> as a `slash-commands` property in a later pass.)
+import './prompt-suggestions';
+import './file-upload';
+import './voice-input';
+// Phase 4 — indicators & leaves
+import './loader';
+import './text-shimmer';
+import './image';
+import './checkpoint';
+import './message-skills';
+import './source';
+import './response-stream';
+import './empty';
+import './chain-of-thought';
+import './resizable';
+import './file-tree';
+import './artifact';
+import './scroll-button';
+import './popover';
+import './switch';
+import './toast';
+// Generative-UI cards (Card Contract)
+import './card';
+import './form';
+import './link-preview';
+import './embed';
+import './confirm-card';
+import './tasks';
+import './choice';
+import './cards';
+// Dual-response comparison (preference capture)
+import './compare';

package/src/elements/register.ts

@@ -1,56 +1,31 @@
 // Single entry that registers all kitn custom elements. Importing this file
-// (or the built bundle) defines the elements as a side effect.
-import './conversation-list';
-import './prompt-input';
-import './chat';
-import './chat-workspace';
-// Composable leaf elements (spike — see docs/handoff + examples/composable)
-import './thinking-bar';
-import './model-switcher';
-import './attachments';
-// Phase 1 — message-rendering core
-import './message';
-import './markdown';
-import './code-block';
-import './reasoning';
-import './tool';
-// Phase 2 — header / meta
-import './context-meter';
-import './feedback-bar';
-import './chat-scope-picker';
-// Phase 3 — input ecosystem
-// (NB: SlashCommand is context-bound to PromptInput — it observes the input
-//  value via usePromptInput() — so it is NOT a standalone element. It will fold
-//  into <kai-prompt-input> as a `slash-commands` property in a later pass.)
-import './prompt-suggestions';
-import './file-upload';
-import './voice-input';
-// Phase 4 — indicators & leaves
-import './loader';
-import './text-shimmer';
-import './image';
-import './checkpoint';
-import './message-skills';
-import './source';
-import './response-stream';
-import './empty';
-import './chain-of-thought';
-import './resizable';
-import './file-tree';
-import './artifact';
-import './scroll-button';
-import './popover';
-import './switch';
-// Generative-UI cards (Card Contract)
-import './card';
-import './form';
-import './link-preview';
-import './embed';
-import './confirm-card';
-import './tasks';
-import './choice';
-import './cards';
+// (or the built bundle) defines the elements as a side effect — but ONLY in a
+// browser/DOM context.
+//
+// SSR-safe: the kai-* elements bundle Solid's client runtime, which touches
+// `window` at module-eval (delegateEvents(events, doc = window.document)). With
+// no `window`, a static import would throw. So the actual component registration
+// lives in ./register-impl and is loaded behind a browser check + dynamic
+// import() — static ESM imports hoist + evaluate unconditionally, so a bare `if`
+// cannot gate them; a dynamic import() can. On the server this module is inert
+// (no DOM → no registration → no throw); in the browser it registers as before.
+//
+// Registration is async (a microtask after this module loads). Consumers that
+// need the upgraded element (e.g. the React runtime) guard with
+// customElements.whenDefined(), which resolves once the impl chunk has run.
+if (typeof window !== 'undefined' && typeof customElements !== 'undefined') {
+  void import('./register-impl');
+}
 
 export type { ChatMessage, ChatMessageAction } from './chat-types';
 export { configureCodeHighlighting, isCodeHighlightingEnabled } from '../primitives/highlighter';
 export type { CodeHighlightingOptions } from '../primitives/highlighter';
+
+// Imperative toast API — usable directly from the elements entry so consumers
+// who only import the web-components bundle still get `toast()`. The store is
+// SSR-safe (no DOM touched until the first toast is raised on the client).
+export { toast, configureToasts } from '../primitives/toast-store';
+export type {
+  ToastConfig,
+  ToastItem, ToastVariant, ToastAction, ToastOptions, ToastHandle,
+} from '../primitives/toast-store';

package/src/elements/remote.tsx

@@ -81,6 +81,10 @@ function buildWrappedPolicy(element: HTMLElement, userPolicy: CardPolicy | undef
       emit({ kind: 'dismiss', cardId });
       userPolicy?.onDismiss?.(cardId);
     },
+    onReopen(cardId) {
+      emit({ kind: 'reopen', cardId });
+      userPolicy?.onReopen?.(cardId);
+    },
     onError(cardId, message) {
       emit({ kind: 'error', cardId, message });
       userPolicy?.onError?.(cardId, message);

package/src/elements/styles.css

@@ -1,6 +1,12 @@
 /* Element-bundle stylesheet. Compiled to compiled.css and injected into each
    custom element's shadow root. Mirrors .storybook/styles.css but scans src/. */
 @import "tailwindcss";
+/* tw-animate-css supplies the animate-in/animate-out + slide/fade/zoom utilities
+   the kit uses for every overlay enter/exit (toast, popover, tooltip, dropdown,
+   hover-card, the message action-row hide). Without this @import those classes
+   compile to nothing and all the animations are silently dead. Compiled into
+   compiled.css at build time, so it's a build-time dep only (no consumer import). */
+@import "tw-animate-css";
 @import "../../theme.css";
 @plugin "@tailwindcss/typography";
 
@@ -65,6 +71,19 @@
   }
   *::-webkit-scrollbar-thumb:hover { background-color: var(--color-scrollbar-thumb-hover); }
   *::-webkit-scrollbar-corner { background: transparent; }
+
+  /* Respect a user's reduced-motion preference: disable the tw-animate-css
+     enter/exit keyframe animations (toasts, overlays, cards) so they appear and
+     disappear instantly instead of sliding/fading. Targets the utility classes
+     tw-animate-css emits (.animate-in / .animate-out) plus any arbitrary
+     `animate-[…]` keyframe utility. */
+  @media (prefers-reduced-motion: reduce) {
+    .animate-in,
+    .animate-out,
+    [class*="animate-["] {
+      animation: none !important;
+    }
+  }
 }
 
 @layer components {

package/src/elements/toast.tsx

@@ -0,0 +1,74 @@
+import { defineWebComponent } from './define';
+import { ToastRegion, type ToastDismissReason, type ToastPosition } from '../components/toast';
+import { toast as toastStore, type ToastItem } from '../primitives/toast-store';
+
+interface Props extends Record<string, unknown> {
+  /** The toasts to render. Newest is shown on top. Set as a JS property (array);
+   *  pass a new array reference to update. */
+  toasts: ToastItem[];
+  /** Stack anchor: `'top-center'` (default), `'top-right'`, `'bottom-center'`, … */
+  position?: ToastPosition;
+  /** Max simultaneously-visible toasts; the rest queue. Defaults to `3`. */
+  max?: number;
+  /** Stacking: 'expanded' (default, full column) | 'collapsed' (Sonner-style
+   *  pile that expands on hover/focus). Attribute: stack. */
+  stack?: 'expanded' | 'collapsed';
+  /** Container element to anchor this region to (JS property). Set by the store
+   *  for a scoped region; unset = the global viewport region. */
+  target?: HTMLElement;
+}
+
+interface Events {
+  /** A toast left the stack. `reason` is `'timeout' | 'close' | 'action'`. */
+  'kai-dismiss': { id: string; reason: ToastDismissReason };
+  /** A toast's action button was pressed. */
+  'kai-action': { id: string; label: string };
+}
+
+/**
+ * `<kai-toast-region>` — the viewport overlay that renders the toast stack.
+ *
+ * It is the substrate behind the imperative `toast()` API: the store lazily
+ * mounts ONE of these on `document.body` and binds the list to `toasts`. It is
+ * also usable declaratively — set `el.toasts = [...]` (a JS property, never an
+ * attribute) and listen for `kai-dismiss` / `kai-action`.
+ *
+ * Because it is a real `kai-*` element it carries its own shadow root + the
+ * shared kit stylesheet, so it is viewport-positioned AND kit-styled.
+ */
+defineWebComponent<Props, Events>('kai-toast-region', {
+  toasts: [],
+  position: 'top-center',
+  max: 3,
+  stack: 'expanded',
+  target: undefined,
+}, (props, { dispatch }) => {
+  // `max` may arrive as a string attribute (`<kai-toast-region max="2">`).
+  const max = () => {
+    const raw = props.max as unknown;
+    const n = typeof raw === 'string' ? parseInt(raw, 10) : raw;
+    return typeof n === 'number' && !Number.isNaN(n) ? n : 3;
+  };
+
+  const remove = (id: string) => {
+    // Drop from the shared store (imperative path). For purely-declarative
+    // consumers the store simply won't contain the id — the dispatched event
+    // is the signal for them to update their own `toasts` array.
+    toastStore.dismiss(id);
+  };
+
+  return (
+    <ToastRegion
+      toasts={props.toasts ?? []}
+      position={props.position}
+      max={max()}
+      stack={props.stack as 'expanded' | 'collapsed' | undefined}
+      target={props.target as HTMLElement | undefined}
+      onDismiss={(id, reason) => {
+        remove(id);
+        dispatch('kai-dismiss', { id, reason });
+      }}
+      onAction={(id, label) => dispatch('kai-action', { id, label })}
+    />
+  );
+});

package/src/index.ts

@@ -18,6 +18,16 @@ export type { CodeHighlightingOptions } from './primitives/highlighter';
 export { configurePdfPreview, isPdfPreviewEnabled } from './primitives/pdf-preview';
 export type { PdfPreviewOptions } from './primitives/pdf-preview';
 
+// Toasts: imperative `toast()` API + the reactive store behind <kai-toast-region>
+export { toast, configureToasts, ensureMounted as ensureToastRegion, getToasts } from './primitives/toast-store';
+export type {
+  ToastItem, ToastVariant, ToastAction, ToastOptions, ToastHandle, ToastFn, ToastConfig,
+} from './primitives/toast-store';
+export { Toast, ToastRegion } from './components/toast';
+export type {
+  ToastRegionProps, ToastDismissReason, ToastPosition,
+} from './components/toast';
+
 // Card Contract (generative-UI foundation)
 export { CARD_CONTRACT_VERSION } from './primitives/card-contract';
 export type {
@@ -27,6 +37,10 @@ export { applyResolution, resolutionFromEvent } from './primitives/card-resoluti
 export { CardProvider, useCardHost } from './primitives/card-host';
 export type { CardProviderProps } from './primitives/card-host';
 export { CARD_EVENT_NAME, emitCardEvent, routeCardEvent, listenForCardEvents } from './primitives/card-routing';
+export { dismissRecovery, defaultIsReopenable } from './primitives/card-recovery';
+export type {
+  RecoveryToast, ReopenEnv, DismissRecoveryOptions,
+} from './primitives/card-recovery';
 export { validateAgainstSchema } from './primitives/card-validate';
 export type { JsonSchema, ValidationResult } from './primitives/card-validate';
 
@@ -47,6 +61,8 @@ export type { CardComponent, CardComponentMap, CardTagMap } from './primitives/c
 // Card: kai-card (base shell) + kai-form (JSON-Schema form renderer)
 export { Card } from './components/card';
 export type { CardProps } from './components/card';
+export { DismissedStub, stubIntent } from './components/dismissed-stub';
+export type { DismissedStubProps, DismissedCardType } from './components/dismissed-stub';
 export { Form, validateForm, buildResult, widgetFor, orderedKeys, coerceValue } from './components/form';
 export type {
   FormProps,
@@ -168,6 +184,20 @@ export {
 } from './components/chat-container';
 export { Message, MessageAvatar, MessageContent, MessageActions, MessageAction, MessageCopyButton } from './components/message';
 export type { MessageCopyButtonProps } from './components/message';
+export { ResponseCompare, useResolved } from './components/response-compare';
+export type { ResponseCompareProps, CompareLayout, ResolvedController } from './components/response-compare';
+export {
+  normalizeCandidates,
+  buildSelection,
+  isAnyStreaming,
+} from './components/response-compare';
+export type {
+  CompareCandidate,
+  ComparePair,
+  CompareCollapse,
+  ResponseCompareData,
+  CompareSelection,
+} from './components/response-compare';
 export { MessageSkills } from './components/message-skills';
 export type { Skill as MessageSkill } from './components/message-skills';
 export {

package/src/primitives/card-contract.ts

@@ -38,18 +38,24 @@ export type CardEvent =
   | { kind: 'resize'; cardId: string; height: number }
   | { kind: 'state'; cardId: string; patch: unknown }
   | { kind: 'dismiss'; cardId: string }
+  | { kind: 'reopen'; cardId: string }
   | { kind: 'error'; cardId: string; message: string };
 
 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; payload?: unknown; at?: string }
-  | { kind: 'submit'; data: unknown; at?: string };
+  | { 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 {
@@ -65,6 +71,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';