@kitn.ai/ui 0.16.0 → 0.17.0

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

@@ -80,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 {
@@ -98,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. */
@@ -186,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';
@@ -347,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). */
@@ -602,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';
@@ -630,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;
@@ -672,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;
@@ -704,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

@@ -44,6 +44,7 @@ import './artifact';
 import './scroll-button';
 import './popover';
 import './switch';
+import './toast';
 // Generative-UI cards (Card Contract)
 import './card';
 import './form';
@@ -53,3 +54,5 @@ import './confirm-card';
 import './tasks';
 import './choice';
 import './cards';
+// Dual-response comparison (preference capture)
+import './compare';

package/src/elements/register.ts

@@ -20,3 +20,12 @@ if (typeof window !== 'undefined' && typeof customElements !== 'undefined') {
 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';

package/src/primitives/card-recovery.ts

@@ -0,0 +1,149 @@
+// src/primitives/card-recovery.ts
+// Recovery glue for the card dismiss/reopen flow. `dismissRecovery` builds the
+// `{ onDismiss, onReopen }` half of a CardPolicy for a host that keeps its cards in
+// some store: it writes a `dismissed` resolution onto the matching envelope (a NEW
+// array reference, never an in-place mutation, so a Solid/React host re-renders),
+// optionally shows an injected "Dismissed · Undo" toast (Undo restores the prior
+// resolution), and on reopen decides — via `isReopenable` — whether the card comes
+// back live (resolution cleared) or `expired`.
+//
+// The toast is an INJECTED ADAPTER, never an import — cards (and this helper) stay
+// decoupled from the toast module. The re-appear rule is the host's: "the agent
+// already proceeded" is a host fact, surfaced through `isReopenable`.
+import type { 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;
+}
+
+/** The terminal resolution kinds that block a reopen (a finished card can't come back). */
+const TERMINAL_KINDS = new Set<CardResolution['kind']>(['action', 'submit', 'expired']);
+
+/** 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 function defaultIsReopenable(env: ReopenEnv, staleAfterMs?: number): boolean {
+  const r = env.resolution;
+  if (r && TERMINAL_KINDS.has(r.kind)) return false;
+  if (
+    staleAfterMs !== undefined &&
+    Number.isFinite(staleAfterMs) &&
+    r?.kind === 'dismissed' &&
+    typeof r.at === 'string'
+  ) {
+    const at = Date.parse(r.at);
+    if (!Number.isNaN(at) && env.now - at >= staleAfterMs) return false;
+  }
+  return true;
+}
+
+/** Return a new cards array with `cardId`'s envelope stamped with `resolution`
+ *  (or cleared when `resolution` is undefined). Same reference if nothing changed. */
+function withResolution(
+  cards: CardEnvelope[],
+  cardId: string,
+  resolution: CardResolution | undefined,
+): CardEnvelope[] {
+  let changed = false;
+  const next = cards.map((c) => {
+    if (c.id !== cardId) return c;
+    changed = true;
+    if (resolution === undefined) {
+      if (c.resolution === undefined) return c;
+      const { resolution: _drop, ...rest } = c;
+      return rest;
+    }
+    return { ...c, resolution };
+  });
+  return changed ? next : cards;
+}
+
+/** The current resolution on `cardId`, if any. */
+function resolutionOf(cards: CardEnvelope[], cardId: string): CardResolution | undefined {
+  return cards.find((c) => c.id === cardId)?.resolution;
+}
+
+/**
+ * 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 function dismissRecovery(
+  opts: DismissRecoveryOptions,
+): Pick<CardPolicy, 'onDismiss' | 'onReopen'> {
+  const now = opts.now ?? (() => Date.now());
+  const reopenable = opts.isReopenable ?? ((env: ReopenEnv) => defaultIsReopenable(env, opts.staleAfterMs));
+  const undoMs = opts.undoMs ?? 6000;
+
+  const onDismiss = (cardId: string): void => {
+    const before = opts.get();
+    const prior = resolutionOf(before, cardId);
+    const dismissed: CardResolution = { kind: 'dismissed', at: new Date(now()).toISOString() };
+    opts.set(withResolution(before, cardId, dismissed));
+
+    opts.toast?.show({
+      message: 'Dismissed',
+      durationMs: undoMs,
+      action: {
+        label: 'Undo',
+        onClick: () => {
+          // Restore the prior resolution (undefined → live again). Read fresh in
+          // case the store moved on; only touch this card.
+          opts.set(withResolution(opts.get(), cardId, prior));
+        },
+      },
+    });
+  };
+
+  const onReopen = (cardId: string): void => {
+    const before = opts.get();
+    const current = resolutionOf(before, cardId);
+    const env: ReopenEnv = { cardId, resolution: current, now: now() };
+    if (reopenable(env)) {
+      opts.set(withResolution(before, cardId, undefined));
+    } else {
+      const expired: CardResolution = { kind: 'expired', at: new Date(now()).toISOString() };
+      opts.set(withResolution(before, cardId, expired));
+    }
+  };
+
+  return { onDismiss, onReopen };
+}