@kitn.ai/ui 0.16.0 → 0.18.0

package/dist/llms/llms.txt

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

package/dist/mcp.es.js

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

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

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

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

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

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

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

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

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

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

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

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

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