@kitn.ai/ui 0.17.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. 46 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 46 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 46 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.17.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,7 @@
     },
     "./elements": {
       "types": "./dist/elements.d.ts",
-      "default": "./dist/kitn-chat.es.js"
+      "default": "./dist/kai.es.js"
     },
     "./elements/*": {
       "types": "./dist/elements/*.d.ts",
@@ -62,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": [
@@ -76,6 +85,7 @@
     "!src/**/*.test.tsx",
     "!src/**/*.mdx",
     "!src/stories",
+    "!src/elements/logos",
     "frameworks",
     "theme.css",
     "llms.txt",
@@ -84,7 +94,7 @@
   "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 && npm run build:elements",
+    "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",
@@ -93,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",
@@ -103,7 +114,11 @@
     "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",

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' +
       '```',
   },

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

@@ -1651,10 +1651,37 @@ function interactionPatternsBlock(): string {
     `});`,
   ].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, and preference capture.`,
+    `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,
@@ -1662,6 +1689,8 @@ function interactionPatternsBlock(): string {
     recoveryPattern,
     ``,
     preferencePattern,
+    ``,
+    statePattern,
   ].join('\n');
 }
 

package/src/components/artifact.tsx

@@ -35,13 +35,43 @@ export type ArtifactTab = 'preview' | 'code';
 /** A file the artifact can preview + show source for. */
 export type ArtifactFile = FileTreeFile;
 
+/** Imperative handle exposed via `controllerRef` — surfaces the artifact's latent
+ *  toolbar capabilities (history back/forward/reload/home, programmatic navigate,
+ *  file selection, open-in-new-tab, maximize/restore) so the `<kai-artifact>`
+ *  facade can forward them as instance methods. Each delegates to the SAME internal
+ *  handler the toolbar buttons use, so every existing event still fires. */
+export interface ArtifactController {
+  /** Go back in the artifact's own history stack (no-op when there's no prior entry). */
+  back(): void;
+  /** Go forward in the history stack (no-op when there's no forward entry). */
+  forward(): void;
+  /** Force-reload the current preview url (also re-renders an inline PDF). */
+  reload(): void;
+  /** Navigate to the `src` home url (no-op when there's no `src`). */
+  home(): void;
+  /** Push + load a url in the preview (the path-field submit path). */
+  navigate(url: string): void;
+  /** Select a file by path: highlights the tree, shows its source, navigates the preview. */
+  selectFile(path: string): void;
+  /** Open the current url in a new browser tab (no-op when there's no concrete url). */
+  openExternal(): void;
+  /** Enter the maximized view-state (fires onMaximizeChange/kai-maximize-change). */
+  maximize(): void;
+  /** Exit the maximized view-state. */
+  restore(): void;
+}
+
 export interface ArtifactProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, 'onSelect'> {
   /** URL the preview iframe frames. */
   src?: string;
   /** Files for the Code tab's tree (+ each file's preview `url`). */
   files?: ArtifactFile[];
-  /** Active tab. Default `preview`. */
+  /** Controlled active tab — when set, the artifact follows it (re-asserted on
+   *  every change). When undefined the tab is uncontrolled (see `defaultTab`). */
   tab?: ArtifactTab;
+  /** Uncontrolled INITIAL tab (used only when `tab` is undefined). The user can
+   *  then freely switch tabs; defaults to `preview`. */
+  defaultTab?: ArtifactTab;
   /** Selected file path (syncs tree highlight + Code source + preview). */
   activeFile?: string;
   /** iframe `sandbox` override. Default `allow-scripts allow-forms`. */
@@ -80,6 +110,15 @@ export interface ArtifactProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>,
   standalone?: boolean;
   /** Make the path field read-only (visible, nav-tracking, non-editable). */
   readonlyPath?: boolean;
+  /** Friendly address shown in the path field INSTEAD of the real current url
+   *  (read-only, non-navigable). Use when the framed url is not consumer-facing
+   *  (e.g. a `data:` blob) so a clean address is shown instead of leaking it.
+   *  Unset = show the real url (editable per `readonlyPath`). */
+  displayUrl?: string;
+  /** Receive the imperative controller once mounted. The `<kai-artifact>` facade
+   *  forwards these as element methods (back/forward/reload/home/navigate/
+   *  selectFile/openExternal/maximize/restore). */
+  controllerRef?: (controller: ArtifactController) => void;
 }
 
 const DEFAULT_SANDBOX = 'allow-scripts allow-forms';
@@ -116,7 +155,9 @@ export function Artifact(props: ArtifactProps): JSX.Element {
   const merged = mergeProps(
     {
       files: [] as ArtifactFile[],
-      tab: 'preview' as ArtifactTab,
+      // No `tab` default: a present `tab` means controlled. The uncontrolled
+      // initial tab comes from `defaultTab` (seeded into the internal signal below).
+      defaultTab: 'preview' as ArtifactTab,
       sandbox: DEFAULT_SANDBOX,
       showNav: true,
       showReload: true,
@@ -135,6 +176,7 @@ export function Artifact(props: ArtifactProps): JSX.Element {
     'src',
     'files',
     'tab',
+    'defaultTab',
     'activeFile',
     'sandbox',
     'iframeTitle',
@@ -152,6 +194,8 @@ export function Artifact(props: ArtifactProps): JSX.Element {
     'openInTab',
     'standalone',
     'readonlyPath',
+    'displayUrl',
+    'controllerRef',
     'class',
   ]);
 
@@ -169,7 +213,11 @@ export function Artifact(props: ArtifactProps): JSX.Element {
   const canBack = () => cursor() > 0;
   const canForward = () => cursor() < history().length - 1;
 
-  const [tab, setTab] = createSignal<ArtifactTab>(local.tab);
+  // Seed the internal tab: a present `tab` (controlled) wins; otherwise the
+  // uncontrolled `defaultTab` (which merges to 'preview'). The user can then
+  // switch freely unless `tab` is set (the effect below re-asserts the controlled
+  // value on each change).
+  const [tab, setTab] = createSignal<ArtifactTab>(local.tab ?? local.defaultTab);
   const [activeFile, setActiveFile] = createSignal<string | undefined>(local.activeFile);
   const [reloadKey, setReloadKey] = createSignal(0);
 
@@ -208,8 +256,12 @@ export function Artifact(props: ArtifactProps): JSX.Element {
 
   let iframeEl: HTMLIFrameElement | undefined;
 
-  // Controlled syncing: when the consumer changes the props, follow them.
-  createEffect(() => setTab(local.tab));
+  // Controlled syncing: when the consumer changes the props, follow them. `tab` is
+  // followed ONLY when it's actually set — an undefined `tab` means uncontrolled,
+  // so the internal signal (seeded from defaultTab) is left for the user to drive.
+  createEffect(() => {
+    if (local.tab !== undefined) setTab(local.tab);
+  });
   createEffect(() => setActiveFile(local.activeFile));
   // `src` change → navigate. Use `on(local.src, …)` so the effect tracks ONLY
   // the `src` prop — NOT `currentUrl()` — otherwise navigating away (file click,
@@ -290,6 +342,38 @@ export function Artifact(props: ArtifactProps): JSX.Element {
     if (local.src) navigate(local.src);
   };
 
+  // Explicitly drive the maximize view-state to a target (the imperative twin of
+  // the toggle button). Fires onMaximizeChange only when the value actually flips,
+  // matching toggleMaximize's "report on change" contract.
+  const setMaximizeState = (next: boolean) => {
+    if (maximized() === next) return;
+    setMaximized(next);
+    local.onMaximizeChange?.(next);
+  };
+
+  // --- Imperative controller (Pattern C): hand the facade a handle over the
+  //     artifact's latent toolbar capabilities. Every method delegates to the
+  //     SAME internal handler the toolbar buttons use, so navigate/tab-change/
+  //     file-select/maximize-change all still fire. ---
+  onMount(() => {
+    local.controllerRef?.({
+      back: () => goBack(),
+      forward: () => goForward(),
+      reload: () => reload(),
+      home: () => goHome(),
+      navigate: (url) => navigate(url),
+      // Resolve the file for the path so highlight + source + preview all sync;
+      // a path with no matching file entry is a no-op (nothing to show).
+      selectFile: (path) => {
+        const file = fileFor(path);
+        if (file) selectFile(path, file);
+      },
+      openExternal: () => openInNewTab(),
+      maximize: () => setMaximizeState(true),
+      restore: () => setMaximizeState(false),
+    });
+  });
+
   // Best-effort: if the consumer opted into `allow-same-origin`, keep the path
   // field truthful as the framed doc navigates itself. Cross-origin (the secure
   // default) throws and we keep our own stack.
@@ -311,9 +395,10 @@ export function Artifact(props: ArtifactProps): JSX.Element {
     const input = (e.currentTarget as HTMLFormElement).elements.namedItem(
       'kai-artifact-path',
     ) as HTMLInputElement | null;
-    if (local.readonlyPath) {
-      // Submit is a no-op while read-only; keep the field reflecting currentUrl.
-      if (input) input.value = currentUrl();
+    if (local.readonlyPath || local.displayUrl != null) {
+      // Submit is a no-op while read-only or showing a friendly displayUrl; keep
+      // the field reflecting the shown value (never push the real, possibly data:, url).
+      if (input) input.value = local.displayUrl ?? currentUrl();
       return;
     }
     if (input && input.value) navigate(input.value);
@@ -330,7 +415,7 @@ export function Artifact(props: ArtifactProps): JSX.Element {
     >
       <Show when={showAnyToolbar()}>
         <ArtifactToolbar
-          url={currentUrl}
+          url={() => local.displayUrl ?? currentUrl()}
           tab={tab}
           canBack={canBack}
           canForward={canForward}
@@ -352,7 +437,7 @@ export function Artifact(props: ArtifactProps): JSX.Element {
           onToggleMaximize={toggleMaximize}
           canOpenInTab={canOpenInTab}
           onOpenInTab={openInNewTab}
-          readonlyPath={() => local.readonlyPath}
+          readonlyPath={() => local.readonlyPath || local.displayUrl != null}
         />
       </Show>
       <div class="relative min-h-0 flex-1">
@@ -420,7 +505,7 @@ function ArtifactToolbar(props: ToolbarProps): JSX.Element {
   return (
     <div
       data-artifact-toolbar
-      class="flex shrink-0 items-center gap-1.5 border-b border-border bg-muted/40 px-2 py-1.5"
+      class="flex shrink-0 items-center gap-1.5 border-b border-border bg-surface px-2 py-1.5"
     >
       <Show when={props.showNav()}>
         <Button
@@ -595,7 +680,7 @@ interface CodeProps {
 function ArtifactCode(props: CodeProps): JSX.Element {
   return (
     <div class="absolute inset-0 flex">
-      <div class="w-56 shrink-0 overflow-auto border-r border-border bg-muted/20 py-1.5 scrollbar-thin">
+      <div class="w-56 shrink-0 overflow-auto border-r border-border bg-surface-sunken py-1.5 scrollbar-thin">
         <FileTree
           files={props.files}
           activeFile={props.activeFile()}
@@ -728,7 +813,7 @@ function ArtifactPdfPreview(props: { url: string; reloadKey: number }): JSX.Elem
         aria-label="PDF preview"
         aria-busy={state() === 'loading'}
         tabindex="0"
-        class="absolute inset-0 flex flex-col items-center gap-3 overflow-auto bg-muted/20 p-3 scrollbar-thin focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset"
+        class="absolute inset-0 flex flex-col items-center gap-3 overflow-auto bg-surface-sunken p-3 scrollbar-thin focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset"
       />
       <Show when={isPdfPreviewEnabled() && state() === 'loading'}>
         <div class="pointer-events-none absolute inset-0 flex items-center justify-center">

package/src/components/attachment-types.ts

@@ -0,0 +1,13 @@
+/** A message attachment descriptor. Pure type — kept JSX-free for the
+ *  framework-neutral consumers (state core, React hook typecheck). */
+export interface AttachmentData {
+  id: string;
+  type: 'file' | 'source-document';
+  filename?: string;
+  mediaType?: string;
+  url?: string;
+  title?: string;
+}
+
+export type AttachmentMediaCategory = 'image' | 'video' | 'audio' | 'document' | 'source' | 'unknown';
+export type AttachmentVariant = 'grid' | 'inline' | 'list';

package/src/components/attachments.tsx

@@ -11,23 +11,13 @@ import {
   Video,
   X,
 } from 'lucide-solid';
+import type { AttachmentData, AttachmentMediaCategory, AttachmentVariant } from './attachment-types';
+export type { AttachmentData, AttachmentMediaCategory, AttachmentVariant } from './attachment-types';
 
 // ============================================================================
 // Types
 // ============================================================================
 
-export interface AttachmentData {
-  id: string;
-  type: 'file' | 'source-document';
-  filename?: string;
-  mediaType?: string;
-  url?: string;
-  title?: string;
-}
-
-export type AttachmentMediaCategory = 'image' | 'video' | 'audio' | 'document' | 'source' | 'unknown';
-export type AttachmentVariant = 'grid' | 'inline' | 'list';
-
 const mediaCategoryIcons: Record<AttachmentMediaCategory, typeof ImageIcon> = {
   audio: Music2,
   document: FileText,
@@ -159,12 +149,12 @@ function Attachment(props: AttachmentProps) {
           ctx.variant === 'grid' && 'size-24 overflow-hidden rounded-lg',
           ctx.variant === 'inline' && [
             'flex h-8 cursor-pointer select-none items-center gap-1.5',
-            'rounded-md bg-muted/50 px-1.5 text-foreground',
+            'rounded-md bg-surface-strong px-1.5 text-foreground',
             'font-medium text-sm transition-all',
             'hover:bg-muted',
           ],
           ctx.variant === 'list' && [
-            'flex w-full items-center gap-3 rounded-lg bg-muted/30 p-3 text-foreground',
+            'flex w-full items-center gap-3 rounded-lg bg-surface p-3 text-foreground',
             'hover:bg-muted/50',
           ],
           local.class,