@kitn.ai/ui 0.16.0 → 0.18.0

package/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/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@kitn.ai/ui",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "type": "module",
+  "sideEffects": [
+    "**/*.css",
+    "./dist/kai.es.js",
+    "./dist/elements/*.js"
+  ],
   "description": "Framework-agnostic, Shadow-DOM web components for building AI chat interfaces — works in React, Vue, Angular, Svelte, or plain HTML. Authored in SolidJS.",
   "keywords": [
     "web-components",
@@ -33,8 +38,8 @@
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "unpkg": "./dist/kitn-chat.es.js",
-  "jsdelivr": "./dist/kitn-chat.es.js",
+  "unpkg": "./dist/kai.es.js",
+  "jsdelivr": "./dist/kai.es.js",
   "customElements": "dist/custom-elements.json",
   "bin": {
     "kai-mcp": "./bin/mcp.js"
@@ -46,7 +51,15 @@
     },
     "./elements": {
       "types": "./dist/elements.d.ts",
-      "default": "./dist/kitn-chat.es.js"
+      "default": "./dist/kai.es.js"
+    },
+    "./elements/*": {
+      "types": "./dist/elements/*.d.ts",
+      "default": "./dist/elements/*.js"
+    },
+    "./autoloader": {
+      "types": "./dist/elements/autoloader.d.ts",
+      "default": "./dist/elements/autoloader.js"
     },
     "./theme.css": "./theme.css",
     "./theme.tokens.css": "./dist/theme.tokens.css",
@@ -54,9 +67,13 @@
       "types": "./dist/react/index.d.ts",
       "default": "./dist/react.js"
     },
+    "./state": {
+      "types": "./dist/state/index.d.ts",
+      "default": "./dist/state.js"
+    },
     "./provider": {
-      "types": "./dist/kitn-chat-provider.d.ts",
-      "default": "./dist/kitn-chat-provider.es.js"
+      "types": "./dist/kai-provider.d.ts",
+      "default": "./dist/kai-provider.es.js"
     }
   },
   "files": [
@@ -68,6 +85,7 @@
     "!src/**/*.test.tsx",
     "!src/**/*.mdx",
     "!src/stories",
+    "!src/elements/logos",
     "frameworks",
     "theme.css",
     "llms.txt",
@@ -76,7 +94,8 @@
   "scripts": {
     "prepublishOnly": "npm run build",
     "prebuild": "npm run build:css",
-    "build": "vite build --config vite.config.ts && vite build --config vite.config.provider.ts && vite build --config vite.config.react.ts && vite build --config vite.config.barrel.ts && vite build --config vite.config.mcp.ts",
+    "build": "vite build --config vite.config.ts && vite build --config vite.config.provider.ts && vite build --config vite.config.react.ts && vite build --config vite.config.barrel.ts && vite build --config vite.config.state.ts && vite build --config vite.config.mcp.ts && npm run build:elements && node scripts/verify-elements-bundle.mjs && node scripts/verify-react-wrappers.mjs",
+    "build:elements": "node scripts/gen-elements-manifest.mjs && vite build --config vite.config.elements.ts && node scripts/gen-element-dts.mjs",
     "postbuild": "npm run build:theme && npm run build:api && npm run build:schemas",
     "build:theme": "node scripts/build-theme-tokens.mjs",
     "build:api": "node scripts/gen-element-api.mjs",
@@ -84,6 +103,7 @@
     "test": "vitest run",
     "test:react": "vitest run --config vitest.react.config.ts",
     "test:storybook": "vitest run --project=storybook",
+    "test:storybook:ci": "node scripts/run-storybook-tests.mjs",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.react.json && tsc --noEmit -p tsconfig.react.test.json && tsc --noEmit -p tsconfig.mcp.json",
     "examples": "echo 'Serving repo root on http://localhost:8000 — open http://localhost:8000/examples/composable/index.html' && python3 -m http.server 8000",
@@ -94,25 +114,28 @@
     "build:css:watch": "tailwindcss -i src/elements/styles.css -o src/elements/compiled.css --watch",
     "dev:provider": "vite examples/remote-provider --port 6007 --strictPort",
     "dev:host": "vite examples/remote-host --port 6006 --strictPort",
-    "test:e2e": "playwright test"
+    "test:e2e": "playwright test",
+    "test:composer-ivp": "playwright test --config playwright.composer.config.ts",
+    "test:slots-ivp": "playwright test --config playwright.slots.config.ts",
+    "test:menu-ivp": "playwright test --config playwright.menu.config.ts",
+    "test:command-ivp": "playwright test --config playwright.command.config.ts"
   },
   "dependencies": {
     "@floating-ui/dom": "^1.7.6",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@shikijs/langs": "^4.2.0",
-    "@shikijs/themes": "^4.2.0",
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.1.0",
     "lucide-solid": "^0.400.0",
     "marked": "^18.0.0",
-    "shiki": "^4.0.2",
     "solid-element": "^1.9.1",
     "solid-js": "^1.9.0",
-    "tailwind-merge": "^2.5.0",
+    "tailwind-merge": "^3.0.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@playwright/test": "^1.60.0",
+    "@shikijs/langs": "^4.2.0",
+    "@shikijs/themes": "^4.2.0",
     "@solidjs/testing-library": "^0.8.0",
     "@storybook/addon-a11y": "^10.4.2",
     "@storybook/addon-docs": "^10.3.5",
@@ -137,6 +160,7 @@
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "remark-gfm": "^4.0.1",
+    "shiki": "^4.0.2",
     "storybook": "^10.3.5",
     "storybook-dark-mode": "^5.0.0",
     "storybook-solidjs-vite": "^10.0.12",

package/src/agent-tooling/mcp/manifest.ts

@@ -46,6 +46,18 @@ export interface CemCssProperty {
   default?: string;
 }
 
+export interface CemSlot {
+  name: string;
+  description?: string;
+}
+
+export interface CemCssPart {
+  name: string;
+  description?: string;
+  /** Our extension: a copy-paste styling example. */
+  recipe?: string;
+}
+
 export interface Declaration {
   tagName?: string;
   name: string;
@@ -55,6 +67,8 @@ export interface Declaration {
   attributes?: CemAttribute[];
   events?: CemEvent[];
   cssProperties?: CemCssProperty[];
+  slots?: CemSlot[];
+  cssParts?: CemCssPart[];
 }
 
 interface CemModule {

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

@@ -27,11 +27,11 @@ const RULES: Rule[] = [
     // 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),
+      /\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 — ' +
+      '`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. ' +
@@ -72,7 +72,11 @@ const RULES: Rule[] = [
       '// ❌ Does NOT trigger re-render\n' +
       'chat.messages.push(newMsg);\n' +
       'chat.messages[i].content = accumulated;\n' +
-      '```',
+      '```\n\n' +
+      'The 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
@@ -108,15 +112,15 @@ const RULES: Rule[] = [
     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.',
+      '`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 a bundle filename, not an element -->\n' +
+      '<!-- ❌ Wrong — kitn-chat is not an element (the bundle is kai.es.js) -->\n' +
       '<kitn-chat></kitn-chat>\n' +
       '```',
   },
@@ -223,6 +227,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 +307,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/reference.ts

@@ -104,6 +104,38 @@ function formatReference(tag: string): string {
     }
   }
 
+  // ── Composition slots ──────────────────────────────────────────────────────
+  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}` : ''}`);
+    }
+  }
+
+  // ── Styleable parts (::part) ───────────────────────────────────────────────
+  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');
 }
 

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

@@ -1530,7 +1530,168 @@ 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');
+
+  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');
 }
 
 // ── error text ────────────────────────────────────────────────────────────────