@kitnai/chat 0.7.0 → 0.8.1

package/src/components/text-shimmer.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { TextShimmer } from './text-shimmer';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const meta = {
   title: 'Components/TextShimmer',
@@ -9,14 +10,12 @@ const meta = {
     layout: 'padded',
     docs: {
       controls: { exclude: ['use:eventListener'] },
-      description: {
-        component: [
-          'An animated text effect that sweeps a light gradient across its content, rendered into any element tag via `as`.',
-          '**When to use:** to signal an in-progress / loading state with a label — e.g. "Thinking", "Generating", "Searching" — or to draw subtle attention to a transient status line.',
-          '**How to use:** wrap text in `<TextShimmer>`; tune `duration` (seconds per sweep) and `spread` (gradient width, clamped 5–45). Use `as` to change the wrapping tag (e.g. `"h2"`) and pass any standard HTML attributes.',
-          '**Placement:** loading indicators, streaming status lines, thinking bars, and placeholder labels.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'An animated text effect that sweeps a light gradient across its content, rendered into any element tag via `as`.',
+        '**When to use:** to signal an in-progress / loading state with a label — e.g. "Thinking", "Generating", "Searching" — or to draw subtle attention to a transient status line.',
+        '**How to use:** wrap text in `<TextShimmer>`; tune `duration` (seconds per sweep) and `spread` (gradient width, clamped 5–45). Use `as` to change the wrapping tag (e.g. `"h2"`) and pass any standard HTML attributes.',
+        '**Placement:** loading indicators, streaming status lines, thinking bars, and placeholder labels.',
+      ]),
     },
   },
   argTypes: {

package/src/components/thinking-bar.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { fn } from 'storybook/test';
 import { ThinkingBar } from './thinking-bar';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const meta = {
   title: 'Components/ThinkingBar',
@@ -10,14 +11,12 @@ const meta = {
     layout: 'padded',
     docs: {
       controls: { exclude: ['use:eventListener'] },
-      description: {
-        component: [
-          'A status row that shows a shimmering "thinking" label, optionally clickable to expand reasoning, with an optional stop/cancel action.',
-          '**When to use:** while the assistant is generating or reasoning, to show live activity and give the user a way to interrupt or to open the reasoning trace.',
-          '**How to use:** set `text` for the label. Pass `onClick` to make the label a button (adds a chevron) — typically to toggle a reasoning panel. Pass `onStop` (with optional `stopLabel`) to render the interrupt action.',
-          '**Placement:** above or in place of a streaming message, or at the top of a reasoning/chain-of-thought block.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A status row that shows a shimmering "thinking" label, optionally clickable to expand reasoning, with an optional stop/cancel action.',
+        '**When to use:** while the assistant is generating or reasoning, to show live activity and give the user a way to interrupt or to open the reasoning trace.',
+        '**How to use:** set `text` for the label. Pass `onClick` to make the label a button (adds a chevron) — typically to toggle a reasoning panel. Pass `onStop` (with optional `stopLabel`) to render the interrupt action.',
+        '**Placement:** above or in place of a streaming message, or at the top of a reasoning/chain-of-thought block.',
+      ]),
     },
   },
   argTypes: {

package/src/components/tool.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { Tool } from './tool';
 import type { ToolPart } from './tool';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const streamingPart: ToolPart = {
   type: 'search_documents',
@@ -40,14 +41,12 @@ const meta = {
     layout: 'padded',
     docs: {
       controls: { exclude: ['use:eventListener'] },
-      description: {
-        component: [
-          'A collapsible panel that visualizes a single tool call — its name, state (processing / ready / completed / error), input, output, error, and call ID.',
-          '**When to use:** to surface assistant tool/function calls in the conversation, so users can inspect what was run and what came back.',
-          '**How to use:** pass a `toolPart` describing the call (`type`, `state`, optional `input`, `output`, `errorText`, `toolCallId`). State drives the icon and badge automatically. Set `defaultOpen` to start expanded.',
-          '**Placement:** inline within an assistant message, typically between text segments where the tool was invoked.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A collapsible panel that visualizes a single tool call — its name, state (processing / ready / completed / error), input, output, error, and call ID.',
+        '**When to use:** to surface assistant tool/function calls in the conversation, so users can inspect what was run and what came back.',
+        '**How to use:** pass a `toolPart` describing the call (`type`, `state`, optional `input`, `output`, `errorText`, `toolCallId`). State drives the icon and badge automatically. Set `defaultOpen` to start expanded.',
+        '**Placement:** inline within an assistant message, typically between text segments where the tool was invoked.',
+      ]),
     },
   },
   argTypes: {

package/src/components/tool.tsx

@@ -150,7 +150,7 @@ function Tool(props: ToolProps) {
             <Show when={output()}>
               <div>
                 <h4 class="text-muted-foreground mb-2 text-sm font-medium">Output</h4>
-                <div class="max-h-60 overflow-auto rounded bg-muted/50 p-2 font-mono text-sm">
+                <div tabindex={0} class="max-h-60 overflow-auto rounded bg-muted/50 p-2 font-mono text-sm">
                   <pre class="whitespace-pre-wrap">{formatValue(output())}</pre>
                 </div>
               </div>
@@ -158,7 +158,7 @@ function Tool(props: ToolProps) {
 
             <Show when={state() === 'output-error' && local.toolPart.errorText}>
               <div>
-                <h4 class="mb-2 text-sm font-medium text-red-500">Error</h4>
+                <h4 class="mb-2 text-sm font-medium text-red-600 dark:text-red-400">Error</h4>
                 <div class="rounded bg-red-500/10 p-2 text-sm">
                   {local.toolPart.errorText}
                 </div>

package/src/components/voice-input.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { fn } from 'storybook/test';
 import { VoiceInput } from './voice-input';
+import { componentDescription } from '../stories/docs/element-controls';
 
 /** Sample transcription handler — resolves the recorded audio to text. */
 const transcribe = async (_audio: Blob): Promise<string> => {
@@ -16,14 +17,12 @@ const meta = {
     layout: 'padded',
     docs: {
       controls: { exclude: ['use:eventListener'] },
-      description: {
-        component: [
-          'A microphone button that records audio, shows recording (pulse rings) and processing (spinner) states, then hands the audio off for transcription.',
-          '**When to use:** to let users dictate input by voice instead of typing — speech-to-text for the prompt field.',
-          '**How to use:** provide `onTranscribe(audio)` returning a `Promise<string>` (your STT call) and `onTranscription(text)` to receive the result. Click toggles recording; transcription runs automatically on stop. Set `disabled` to block input.',
-          '**Placement:** inside the prompt input action bar, next to send and other input actions.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A microphone button that records audio, shows recording (pulse rings) and processing (spinner) states, then hands the audio off for transcription.',
+        '**When to use:** to let users dictate input by voice instead of typing — speech-to-text for the prompt field.',
+        '**How to use:** provide `onTranscribe(audio)` returning a `Promise<string>` (your STT call) and `onTranscription(text)` to receive the result. Click toggles recording; transcription runs automatically on stop. Set `disabled` to block input.',
+        '**Placement:** inside the prompt input action bar, next to send and other input actions.',
+      ]),
     },
   },
   argTypes: {

package/src/elements/artifact.stories.tsx

@@ -0,0 +1,291 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal, onMount, type JSX } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+import type { ArtifactFile } from '../components/artifact';
+
+// Custom DOM elements — declare the tags for JSX.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kc-artifact': JSX.HTMLAttributes<HTMLElement> & {
+        src?: string;
+        tab?: string;
+        'active-file'?: string;
+        sandbox?: string;
+        'iframe-title'?: string;
+        ref?: (el: HTMLElement) => void;
+      };
+    }
+  }
+}
+
+// Storybook serves examples/artifact-fixtures at /artifact-fixtures (see
+// .storybook/main.ts staticDirs). These are real, cross-linked pages so
+// relative-link nav, back/forward and multi-format all work in the iframe.
+const BASE = '/artifact-fixtures';
+
+const FILES: ArtifactFile[] = [
+  {
+    path: 'index.html',
+    url: `${BASE}/index.html`,
+    type: 'html',
+    language: 'html',
+    code: `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <link rel="stylesheet" href="css/site.css" />
+    <title>Starboard — Home</title>
+  </head>
+  <body>
+    <h1>Starboard</h1>
+    <a href="about.html">About</a>
+  </body>
+</html>`,
+  },
+  {
+    path: 'about.html',
+    url: `${BASE}/about.html`,
+    type: 'html',
+    language: 'html',
+    code: `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <link rel="stylesheet" href="css/site.css" />
+    <title>Starboard — About</title>
+  </head>
+  <body data-page="about">
+    <h1>About Starboard</h1>
+    <a href="index.html">← Home</a>
+  </body>
+</html>`,
+  },
+  {
+    path: 'css/site.css',
+    url: `${BASE}/css/site.css`,
+    type: 'other',
+    language: 'css',
+    code: `:root { --accent: #6ea8fe; }
+body { font-family: system-ui, sans-serif; }
+.card { border: 1px solid var(--accent); border-radius: 14px; }`,
+  },
+  {
+    path: 'assets/logo.svg',
+    url: `${BASE}/assets/logo.svg`,
+    type: 'image',
+  },
+  {
+    path: 'assets/report.pdf',
+    url: `${BASE}/assets/report.pdf`,
+    type: 'pdf',
+  },
+];
+
+/** A bordered, sized box the artifact fills. */
+function Frame(props: { children: JSX.Element; height?: string }) {
+  return (
+    <div
+      style={{
+        height: props.height ?? '520px',
+        width: '100%',
+        'max-width': '900px',
+        border: '1px solid var(--color-border, #e4e4e7)',
+        'border-radius': '12px',
+        overflow: 'hidden',
+      }}
+    >
+      {props.children}
+    </div>
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kc-artifact
+  src="https://your-backend.example/artifacts/abc/index.html"
+  style="display:block;height:520px"
+></kc-artifact>
+
+<script type="module">
+  import '@kitnai/chat/elements'; // registers the custom elements
+
+  const el = document.querySelector('kc-artifact');
+  // \`files\` is a JS property (array): tree labels (folders from \`/\`), a preview
+  // \`url\` per file, and \`code\` for the Code tab.
+  el.files = [
+    { path: 'index.html', url: '…/index.html', type: 'html', code: '<!DOCTYPE …' },
+    { path: 'about.html', url: '…/about.html', type: 'html', code: '<!DOCTYPE …' },
+    { path: 'assets/logo.svg', url: '…/logo.svg', type: 'image' },
+  ];
+
+  el.addEventListener('navigate', (e) => console.log('navigate', e.detail.url));
+  el.addEventListener('tabchange', (e) => console.log('tab', e.detail.tab));
+  el.addEventListener('fileselect', (e) => console.log('file', e.detail.path));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kc-artifact',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kc-artifact'),
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: specDescription('kc-artifact', [
+        '`<kc-artifact>` is the framework-agnostic **web component** for a framed, switchable **generated-artifact viewer** — the "canvas / artifacts" pattern (Claude Artifacts, ChatGPT Canvas, V0, bolt). It frames a consumer-served URL in a **sandboxed `<iframe>`** with a functional nav toolbar, and a **Preview | Code** toggle whose Code tab shows a file tree (`<kc-file-tree>`) + the active file source (`<kc-code-block>`). Isolated in **Shadow DOM**.',
+        "**When to use:** to show an AI-generated artifact (a web page, doc, image, or PDF your backend hosts) beside the conversation — typically inside a `<kc-resizable>` panel. The component **frames** content; your backend serves it, so relative links, back/forward, reload and multi-format work natively.",
+        "**How to use:** register once with `import '@kitnai/chat/elements'`, set `src` to the hosted URL, and set the `files` **property** (a JS array of `{ path, url?, code?, language?, type? }`) for the Code tab tree. The iframe `sandbox` defaults to `allow-scripts allow-forms` (**not** `allow-same-origin`); widen it via the `sandbox` attribute only if you trust the artifact. Listen for **`navigate`** (`detail.url`), **`tabchange`** (`detail.tab`), and **`fileselect`** (`detail.path`).",
+        '**Placement:** the preview/canvas panel of a compose-your-own-chat shell — e.g. `list | chat | artifact`. It **fills** its container, so give the parent (or the element) a height.',
+        'See the **Code** tab for HTML usage.',
+      ]),
+    },
+  },
+  args: { tab: 'preview', sandbox: 'allow-scripts allow-forms' },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Interactive playground — frames a live, cross-linked fixture. Flip Preview/Code. */
+export const Playground: Story = {
+  render: (args: { src?: string; tab?: string; sandbox?: string }) => {
+    let el: HTMLElement & { files?: ArtifactFile[] };
+    onMount(() => {
+      if (el) el.files = FILES;
+    });
+    return (
+      <Frame>
+        <kc-artifact
+          ref={(e) => (el = e as HTMLElement & { files?: ArtifactFile[] })}
+          src={args.src ?? `${BASE}/index.html`}
+          tab={args.tab ?? 'preview'}
+          sandbox={args.sandbox ?? 'allow-scripts allow-forms'}
+          iframe-title="Starboard artifact preview"
+        />
+      </Frame>
+    );
+  },
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Opens on the Code tab — file tree + syntax-highlighted source. */
+export const CodeTab: Story = {
+  name: 'Code tab',
+  render: () => {
+    let el: HTMLElement & { files?: ArtifactFile[] };
+    onMount(() => {
+      if (el) el.files = FILES;
+    });
+    return (
+      <Frame>
+        <kc-artifact
+          ref={(e) => (el = e as HTMLElement & { files?: ArtifactFile[] })}
+          src={`${BASE}/index.html`}
+          tab="code"
+          active-file="index.html"
+          iframe-title="Starboard artifact preview"
+        />
+      </Frame>
+    );
+  },
+};
+
+/** Multi-format: the preview frames an image fixture natively. */
+export const ImagePreview: Story = {
+  name: 'Image (multi-format)',
+  render: () => {
+    let el: HTMLElement & { files?: ArtifactFile[] };
+    onMount(() => {
+      if (el) el.files = FILES;
+    });
+    return (
+      <Frame>
+        <kc-artifact
+          ref={(e) => (el = e as HTMLElement & { files?: ArtifactFile[] })}
+          src={`${BASE}/assets/logo.svg`}
+          iframe-title="Logo image"
+        />
+      </Frame>
+    );
+  },
+};
+
+/** Multi-format: PDFs render inline via pdf.js (loaded on demand from a CDN). */
+export const PdfPreview: Story = {
+  name: 'PDF (multi-format)',
+  render: () => {
+    let el: HTMLElement & { files?: ArtifactFile[] };
+    onMount(() => {
+      if (el) el.files = FILES;
+    });
+    return (
+      <Frame>
+        <kc-artifact
+          ref={(e) => (el = e as HTMLElement & { files?: ArtifactFile[] })}
+          src={`${BASE}/assets/report.pdf`}
+          iframe-title="Report PDF"
+        />
+      </Frame>
+    );
+  },
+};
+
+/** When inline rendering can't work (CORS / 404 / blocked CDN) the viewer shows
+ *  an "Open in new tab / Download" card. Here the src 404s to force that path. */
+export const PdfFallback: Story = {
+  name: 'PDF (fallback card)',
+  render: () => (
+    <Frame>
+      <kc-artifact
+        src={`${BASE}/assets/does-not-exist.pdf`}
+        iframe-title="Missing PDF"
+      />
+    </Frame>
+  ),
+};
+
+/** Logs the emitted events so you can see the controlled nav model in action. */
+export const WithEvents: Story = {
+  name: 'Events',
+  render: () => {
+    const [log, setLog] = createSignal<string[]>([]);
+    let el: HTMLElement & { files?: ArtifactFile[] };
+    onMount(() => {
+      if (!el) return;
+      el.files = FILES;
+      el.addEventListener('navigate', (e) =>
+        setLog((l) => [`navigate → ${(e as CustomEvent).detail.url}`, ...l].slice(0, 6)),
+      );
+      el.addEventListener('tabchange', (e) =>
+        setLog((l) => [`tabchange → ${(e as CustomEvent).detail.tab}`, ...l].slice(0, 6)),
+      );
+      el.addEventListener('fileselect', (e) =>
+        setLog((l) => [`fileselect → ${(e as CustomEvent).detail.path}`, ...l].slice(0, 6)),
+      );
+    });
+    return (
+      <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
+        <Frame height="420px">
+          <kc-artifact
+            ref={(e) => (el = e as HTMLElement & { files?: ArtifactFile[] })}
+            src={`${BASE}/index.html`}
+            iframe-title="Starboard artifact preview"
+          />
+        </Frame>
+        <pre
+          style={{
+            'font-size': '12px',
+            'max-width': '900px',
+            padding: '10px 12px',
+            'border-radius': '8px',
+            background: 'var(--color-muted, #f4f4f5)',
+            color: 'var(--color-muted-foreground, #71717a)',
+            'min-height': '96px',
+            margin: '0',
+          }}
+        >
+          {log().length ? log().join('\n') : '(navigate the preview / switch tabs / pick a file…)'}
+        </pre>
+      </div>
+    );
+  },
+};

package/src/elements/artifact.tsx

@@ -0,0 +1,72 @@
+import { defineWebComponent } from './define';
+import { Artifact, type ArtifactFile, type ArtifactTab } from '../components/artifact';
+
+interface Props extends Record<string, unknown> {
+  /** URL the preview iframe frames. Consumer-controlled. */
+  src?: string;
+  /** Files for the Code tab tree + each file's preview `url`. Set as a JS property (array). */
+  files: ArtifactFile[];
+  /** Active tab: `preview` (default) or `code`. */
+  tab?: ArtifactTab;
+  /** Selected file path — syncs the tree highlight, Code source, and preview. */
+  activeFile?: string;
+  /** iframe `sandbox` override. Secure default `allow-scripts allow-forms` (NOT `allow-same-origin`). */
+  sandbox?: string;
+  /** Accessible title for the preview iframe. */
+  iframeTitle?: string;
+}
+
+interface Events extends Record<string, unknown> {
+  /** Fired when the preview navigates. `detail.url` = the new location. */
+  navigate: { url: string };
+  /** Fired when the Preview|Code tab changes. `detail.tab`. */
+  tabchange: { tab: ArtifactTab };
+  /** Fired when a file is selected. `detail.path`. */
+  fileselect: { path: string };
+}
+
+/**
+ * `<kc-artifact>` — a framed, switchable generated-artifact viewer: a sandboxed
+ * preview iframe with a functional nav toolbar (back · forward · reload · home +
+ * editable path field) and a Preview|Code toggle; the Code tab shows a file tree
+ * (`<kc-file-tree>`) + the active file's source via `<kc-code-block>`. The
+ * component self-navigates the iframe and emits `navigate` / `tabchange` /
+ * `fileselect`. Designed to FILL its container (e.g. a `<kc-resizable>` panel).
+ */
+defineWebComponent<Props, Events>('kc-artifact', {
+  src: undefined,
+  files: [],
+  tab: 'preview',
+  activeFile: undefined,
+  sandbox: 'allow-scripts allow-forms',
+  iframeTitle: undefined,
+}, (props, { dispatch }) => (
+  <>
+    {/* The artifact fills its container; the internal column flex (toolbar
+        flex-shrink:0, body flex:1/min-height:0) is in the Solid component. Wrap
+        in a definite `1fr` grid cell (NOT :host) so the facade's sibling
+        portal-mount div can't steal a grid track — see resizable.tsx. */}
+    <style>{':host{display:block;height:100%;min-height:0}'}</style>
+    <div
+      style={{
+        display: 'grid',
+        'grid-template-rows': 'minmax(0, 1fr)',
+        'grid-template-columns': 'minmax(0, 1fr)',
+        height: '100%',
+        'min-height': '0',
+      }}
+    >
+      <Artifact
+        src={props.src}
+        files={props.files}
+        tab={props.tab}
+        activeFile={props.activeFile}
+        sandbox={props.sandbox}
+        iframeTitle={props.iframeTitle}
+        onNavigate={(url) => dispatch('navigate', { url })}
+        onTabChange={(tab) => dispatch('tabchange', { tab })}
+        onFileSelect={(path) => dispatch('fileselect', { path })}
+      />
+    </div>
+  </>
+));

package/src/elements/{kitn-attachments.stories.tsx → attachments.stories.tsx}

@@ -2,15 +2,14 @@ import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
 import './register'; // side effect: registers the custom elements
 import type { AttachmentData } from '../components/attachments';
-import { ElementSpec } from '../stories/docs/element-spec';
-import { argTypesFor } from '../stories/docs/element-controls';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace JSX {
     interface IntrinsicElements {
-      'kitn-attachments': JSX.HTMLAttributes<HTMLElement> & {
+      'kc-attachments': JSX.HTMLAttributes<HTMLElement> & {
         variant?: string;
         'hover-card'?: boolean | string;
         removable?: boolean | string;
@@ -60,7 +59,7 @@ const imageItems: AttachmentData[] = [
   },
 ];
 
-/** Render `<kitn-attachments>` with an `items` property and the given flags. */
+/** Render `<kc-attachments>` with an `items` property and the given flags. */
 function AttachmentsElement(props: {
   items: AttachmentData[];
   variant?: string;
@@ -83,7 +82,7 @@ function AttachmentsElement(props: {
     }
   });
   return (
-    <kitn-attachments
+    <kc-attachments
       ref={(e) => (el = e as HTMLElement)}
       style={{ display: 'block', padding: '24px', 'max-width': '720px' }}
     />
@@ -91,7 +90,7 @@ function AttachmentsElement(props: {
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-attachments id="att" variant="grid" removable></kitn-attachments>
+<kc-attachments id="att" variant="grid" removable></kc-attachments>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -110,7 +109,7 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 </script>`;
 
 const HOVER_SNIPPET = `<!-- inline/list chips with a hover-card image preview -->
-<kitn-attachments id="att" variant="inline" hover-card></kitn-attachments>
+<kc-attachments id="att" variant="inline" hover-card></kc-attachments>
 
 <script type="module">
   import '@kitnai/chat/elements';
@@ -125,20 +124,18 @@ const HOVER_SNIPPET = `<!-- inline/list chips with a hover-card image preview --
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-attachments',
+  title: 'Web Components/kc-attachments',
   tags: ['autodocs'],
-  argTypes: argTypesFor('kitn-attachments'),
+  argTypes: argTypesFor('kc-attachments'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-attachments>` is the framework-agnostic **web component** for a set of file/source attachments, and the exemplar for the "collapse a compound primitive to ONE configurable element" pattern: the sub-parts the SolidJS layer composes become attributes here. Isolated in **Shadow DOM**.',
+      description: specDescription('kc-attachments', [
+          '`<kc-attachments>` is the framework-agnostic **web component** for a set of file/source attachments, and the exemplar for the "collapse a compound primitive to ONE configurable element" pattern: the sub-parts the SolidJS layer composes become attributes here. Isolated in **Shadow DOM**.',
           '**When to use:** rendering attachment chips/tiles in a non-Solid app. In SolidJS, compose the `Attachment*` primitives for fully custom layouts.',
           "**How to use:** register once with `import '@kitnai/chat/elements'`, set the data via the `items` **property**, pick a layout with `variant` (`grid` | `inline` | `list`), add `removable` to get per-item remove buttons (emits a `remove` **CustomEvent** with `{ id }`), and `hover-card` for inline/list previews (image attachments preview their thumbnail).",
           'See the **Code** tab for HTML usage.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;
@@ -146,12 +143,6 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
-/** Full generated API reference — properties, events, tokens, and composed-from. */
-export const API: Story = {
-  render: () => <ElementSpec tag="kitn-attachments" />,
-  parameters: { layout: 'padded' },
-};
-
 /** Visual tiles (the default `grid` variant) — image attachments render as real
  *  `<img>` thumbnails; non-image files fall back to a media-type icon. */
 export const Grid: Story = {

package/src/elements/attachments.tsx

@@ -1,5 +1,5 @@
 import { For, Show } from 'solid-js';
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import {
   Attachments,
   Attachment,
@@ -31,14 +31,14 @@ interface Props extends Record<string, unknown> {
   emptyText?: string;
 }
 
-/** Events fired by `<kitn-attachments>`. */
+/** Events fired by `<kc-attachments>`. */
 interface Events {
   /** A remove button was clicked. */
   remove: { id: string };
 }
 
 /**
- * `<kitn-attachments>` — the exemplar for the "collapse a compound primitive to
+ * `<kc-attachments>` — the exemplar for the "collapse a compound primitive to
  * ONE configurable element" pattern (Route 1). The presentation knobs that the
  * SolidJS layer expresses by composing sub-parts (`<AttachmentPreview>`,
  * `<AttachmentInfo>`, `<AttachmentHoverCard>`, `<AttachmentRemove>`) become
@@ -52,7 +52,7 @@ interface Events {
  * as an event. For fully-custom hover content, the SolidJS primitives remain the
  * escape hatch (a templated slot — "Route 2" — is a deliberate future add).
  */
-defineKitnElement<Props, Events>('kitn-attachments', {
+defineWebComponent<Props, Events>('kc-attachments', {
   items: [],
   variant: 'grid',
   hoverCard: false,