@kitn.ai/ui 0.16.0 → 0.17.0

package/src/agent-tooling/mcp/tools/debug.ts

@@ -223,6 +223,53 @@ const RULES: Rule[] = [
       "// 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):**\n' +
+      'Best for multi-element apps or any SSR/meta-framework. ' +
+      'Load once and every `kai-*` element is available.\n\n' +
+      '```js\n' +
+      "import '@kitn.ai/ui/elements';  // ~119 KB gz — registers everything\n" +
+      '```\n\n' +
+      '**Mode 2 — per-element import (tree-shaking, bundler apps):**\n' +
+      'Use `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)\n" +
+      "import '@kitn.ai/ui/elements/chat';\n\n" +
+      "// Other examples:\n" +
+      "import '@kitn.ai/ui/elements/code-block';  // <kai-code-block>\n" +
+      "import '@kitn.ai/ui/elements/confirm-card'; // <kai-confirm>\n" +
+      '```\n\n' +
+      'The 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):**\n' +
+      'Watches 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\n' +
+      'In 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)
@@ -256,6 +303,143 @@ const RULES: Rule[] = [
       "import { 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) => {
+      // Placing a toast element by hand (the region auto-mounts — you never write it).
+      if (/<kai-toast(-region)?\b/.test(t)) return true;
+      // Asking how to show / trigger a toast or notification with kai context.
+      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\n' +
+      "import { toast } from '@kitn.ai/ui/elements'; // or '@kitn.ai/ui'\n\n" +
+      "// ✅ Fire-and-forget\n" +
+      "toast('Copied to clipboard');\n" +
+      "toast.success('Saved');\n\n" +
+      "// ✅ With an Undo action + an imperative handle\n" +
+      "const t = toast('Item deleted', {\n" +
+      "  action: { label: 'Undo', onAction: () => restore() },\n" +
+      '});\n' +
+      "t.update({ message: 'Restored', variant: 'success' });\n" +
+      't.dismiss();\n' +
+      '```\n\n' +
+      'The 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;
+      // dismiss / reopen / undo / disappear / filter-out signals in a card context.
+      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\n' +
+      "import { dismissRecovery } from '@kitn.ai/ui';\n" +
+      "import { toast } from '@kitn.ai/ui/elements';\n\n" +
+      '// Adapter: map dismissRecovery\'s toast shape onto the imperative toast().\n' +
+      'const 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\n' +
+      'const { 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;
+      // "compare two responses / candidates / A vs B" with a kai/UI context.
+      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\n' +
+      "import { toast } from '@kitn.ai/ui/elements';\n" +
+      "import type { ResponseCompareData, CompareSelection } from '@kitn.ai/ui';\n\n" +
+      "const el = document.querySelector('kai-compare')!;\n" +
+      '// data is a JS PROPERTY — exactly two candidates, each with a unique id.\n' +
+      'el.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.\n' +
+      "el.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.\n" +
+      "el.addEventListener('kai-compare-select', (e) => {\n" +
+      '  const { chosenId, rejectedIds } = (e as CustomEvent<CompareSelection>).detail;\n' +
+      '  recordPreference({ prompt, chosen: chosenId, rejected: rejectedIds });\n' +
+      '});\n' +
+      '```\n\n' +
+      'A 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: Rule[]): string {

package/src/agent-tooling/mcp/tools/scaffold.ts

@@ -1530,7 +1530,139 @@ function compose(
     envLines,
   ].join('\n');
 
-  return [header, block1, block2, block3].join('\n\n');
+  // SCAF-16: loading-options note — inform consumers about the two opt-in load modes
+  // (per-element tree-shaking + autoloader) without changing the default import above.
+  // Leads with "the default is right" rather than a size headline; the debug tool
+  // carries the full KB breakdown for developers who ask for it.
+  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');
+
+  // SCAF-17: interaction patterns — small, copy-pasteable snippets for the
+  // toast / card-recovery / preference-capture features. Appended as a reference
+  // section so the consumer can wire confirmations, undo, and A/B preference
+  // capture without leaving the scaffold. Does not change blocks 1–4.
+  const block5 = interactionPatternsBlock();
+
+  return [header, block1, block2, block3, block4, block5].join('\n\n');
+}
+
+// ── SCAF-17: reusable interaction-pattern snippets ─────────────────────────────
+
+/**
+ * The three interaction patterns from the chat-interactions feature set, emitted
+ * as a labeled reference section the scaffolder always appends:
+ *   1. `toast()` confirmation + Undo.
+ *   2. `dismissRecovery()` card-policy wiring (with a toast adapter).
+ *   3. `kai-compare` preference capture (two streams → kai-compare-select →
+ *      recordPreference({ prompt, chosen, rejected })).
+ *
+ * Framework-agnostic (plain TS / DOM) so it drops into any of the front-end
+ * targets; the imports are valid from `@kitn.ai/ui` (and `toast` also from
+ * `@kitn.ai/ui/elements`).
+ */
+function interactionPatternsBlock(): string {
+  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');
 }
 
 // ── error text ────────────────────────────────────────────────────────────────

package/src/components/chat-thread.tsx

@@ -1,10 +1,9 @@
 import { createSignal, For, Show } from 'solid-js';
 import { ChatConfig, useChatConfig } from '../primitives/chat-config';
 import { ChatContainer, ChatContainerContent, ChatContainerScrollAnchor } from './chat-container';
-import { Message, MessageAvatar, MessageContent, MessageActionBar } from './message';
-import { Reasoning, ReasoningTrigger, ReasoningContent } from './reasoning';
-import { Tool } from './tool';
-import { Attachments, Attachment, AttachmentPreview, AttachmentInfo, type AttachmentData } from './attachments';
+import { Message, MessageAvatar, MessageBody } from './message';
+import { type AttachmentData } from './attachments';
+import { createMessageFeedback, type MessageActionDetail } from '../primitives/message-feedback';
 import { ModelSwitcher } from './model-switcher';
 import { ScrollButton } from './scroll-button';
 import {
@@ -95,7 +94,7 @@ export interface ChatThreadProps {
   onSubmit?: (detail: { value: string; attachments: AttachmentData[] }) => void;
   onSuggestionClick?: (value: string) => void;
   onModelChange?: (modelId: string) => void;
-  onMessageAction?: (detail: { messageId: string; action: string }) => void;
+  onMessageAction?: (detail: MessageActionDetail) => void;
   onSearch?: () => void;
   onVoice?: () => void;
   onSlashSelect?: (command: SlashCommandItem) => void;
@@ -104,6 +103,15 @@ export interface ChatThreadProps {
 export function ChatThread(props: ChatThreadProps) {
   const outer = useChatConfig();
   const reveal = () => (props.actionsReveal === 'hover' ? 'hover' : 'always');
+  // Feedback (copy + vote) state lives ABOVE the per-message <For>, so streaming
+  // re-renders (a fresh `messages` array ref per chunk) don't wipe it.
+  // The copy/feedback toasts scope to the chat (this thread's root) so they appear
+  // in-chat rather than at the page top.
+  let rootEl: HTMLElement | undefined;
+  const feedback = createMessageFeedback({
+    emit: (detail) => props.onMessageAction?.(detail),
+    target: () => rootEl,
+  });
   const [internal, setInternal] = createSignal(props.value ?? '');
   const [attachments, setAttachments] = createSignal<AttachmentData[]>([]);
   const current = () => props.value ?? internal();
@@ -122,7 +130,7 @@ export function ChatThread(props: ChatThreadProps) {
 
   return (
     <ChatConfig proseSize={props.proseSize} codeTheme={props.codeTheme} codeHighlight={props.codeHighlight !== false} portalMount={outer.portalMount()}>
-      <div class={`flex h-full flex-col bg-background ${props.class ?? ''}`}>
+      <div ref={(e) => (rootEl = e as HTMLElement)} class={`flex h-full flex-col bg-background ${props.class ?? ''}`}>
         <Show when={showHeader()}>
           <header class="flex h-14 shrink-0 items-center justify-between border-b border-border px-5">
             <div class="flex items-center gap-2">
@@ -168,35 +176,19 @@ export function ChatThread(props: ChatThreadProps) {
               <For each={props.messages}>
                 {(m) => {
                   const body = (
-                    <>
-                      <Show when={m.reasoning}>
-                        <Reasoning class="mb-2 w-full">
-                          <ReasoningTrigger>{m.reasoning!.label ?? 'Reasoning'}</ReasoningTrigger>
-                          <ReasoningContent markdown>{m.reasoning!.text}</ReasoningContent>
-                        </Reasoning>
-                      </Show>
-                      <For each={m.tools ?? []}>{(tp) => <Tool toolPart={tp} class="mb-2 w-full" />}</For>
-                      <Show when={m.attachments?.length}>
-                        <Attachments variant="inline" class={m.role === 'user' ? 'mb-2 justify-end' : 'mb-2'}>
-                          <For each={m.attachments!}>
-                            {(att) => (<Attachment data={att}><AttachmentPreview /><AttachmentInfo /></Attachment>)}
-                          </For>
-                        </Attachments>
-                      </Show>
-                      <MessageContent
-                        markdown={m.role === 'assistant'}
-                        class={m.role === 'user' ? 'bg-muted text-primary max-w-[85%] rounded-2xl px-4 py-2' : 'bg-transparent p-0'}
-                      >
-                        {m.content}
-                      </MessageContent>
-                      <Show when={m.actions?.length}>
-                        <MessageActionBar
-                          actions={m.actions!}
-                          reveal={reveal()}
-                          onAction={(action) => props.onMessageAction?.({ messageId: m.id, action })}
-                        />
-                      </Show>
-                    </>
+                    <MessageBody
+                      content={m.content}
+                      reasoning={m.reasoning}
+                      tools={m.tools}
+                      attachments={m.attachments}
+                      isUser={m.role === 'user'}
+                      markdown={m.role === 'assistant'}
+                      actions={m.actions}
+                      actionsReveal={reveal()}
+                      activeFeedback={feedback.resolveFeedback(m)}
+                      copied={feedback.isCopied(m.id)}
+                      onAction={(action) => feedback.handleAction(m, action)}
+                    />
                   );
                   const rowGroup = reveal() === 'hover' ? 'group ' : '';
                   return (

package/src/components/choice-card.tsx

@@ -15,11 +15,12 @@ import { cn } from '../utils/cn';
 import { Button } from '../ui/button';
 import { HoverCard } from '../ui/hover-card';
 import { Card } from './card';
+import { DismissedStub } from './dismissed-stub';
 import type { CardEnvelope, CardEvent, CardHost, CardResolution } from '../primitives/card-contract';
 import { useCardResolution } from './use-card-resolution';
 import { emitCardEvent } from '../primitives/card-routing';
 import { useCardHost } from '../primitives/card-host';
-import { Check } from 'lucide-solid';
+import { Check, X } from 'lucide-solid';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types (choice.schema.json) — see src/primitives/card-schemas/choice.schema.json
@@ -49,6 +50,7 @@ export interface ChoiceCardData {
   options: ChoiceOption[]; // 1..N
   allowOther?: ChoiceAllowOther; // free-text escape
   submitLabel?: string; // label for the Submit button (default 'Submit')
+  dismissible?: boolean; // show a close affordance that emits `dismiss`
 }
 
 export type ChoiceCardEnvelope = CardEnvelope<'choice', ChoiceCardData>;
@@ -310,6 +312,15 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
     });
   };
 
+  // Dismiss: emit `dismiss` AND optimistically flip to a `dismissed` resolution so
+  // the card collapses to its re-openable stub immediately.
+  const onDismiss = (): void => {
+    if (res.isResolved()) return;
+    emit({ kind: 'dismiss', cardId: local.cardId });
+    res.setLocal({ kind: 'dismissed' });
+  };
+  const onReopen = (): void => emit({ kind: 'reopen', cardId: local.cardId });
+
   const focusRadio = (index: number): void => {
     const radios = groupRef?.querySelectorAll<HTMLElement>('[role="radio"]');
     radios?.[index]?.focus();
@@ -353,6 +364,10 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
           return <Card heading={local.heading} errorMessage="The card failed to render." />;
         }}
       >
+        <Show
+          when={!res.isDeferred()}
+          fallback={<DismissedStub type={CHOICE_CARD_TYPE} title={local.heading} onReopen={onReopen} />}
+        >
         <Card heading={local.heading}>
           <div class={cn('flex flex-col gap-3', local.class)}>
             <Show when={local.data?.prompt}>
@@ -421,12 +436,26 @@ export function ChoiceCard(props: ChoiceCardProps): JSX.Element {
                 </div>
               </Show>
 
-              <Button type="button" class="self-end" disabled={!canSubmit()} onClick={submit}>
-                {submitLabel()}
-              </Button>
+              <div class="flex w-full flex-wrap items-center justify-between gap-2">
+                <Show when={local.data?.dismissible === true}>
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="icon-sm"
+                    aria-label="Dismiss"
+                    onClick={onDismiss}
+                  >
+                    <X size={16} aria-hidden="true" />
+                  </Button>
+                </Show>
+                <Button type="button" class="ml-auto" disabled={!canSubmit()} onClick={submit}>
+                  {submitLabel()}
+                </Button>
+              </div>
             </Show>
           </div>
         </Card>
+        </Show>
       </ErrorBoundary>
     </Show>
   );