@kitnai/chat 0.3.1 → 0.4.0

package/src/elements/kitn-empty.stories.tsx

@@ -0,0 +1,110 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+
+// 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-empty': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-empty
+  empty-title="No conversations yet"
+  description="Start a new chat to see it appear here."
+>
+  <!-- Route 2 slots: your own icon and actions -->
+  <svg slot="media" width="28" height="28" viewBox="0 0 24 24" fill="none"
+       stroke="currentColor" stroke-width="2">
+    <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" />
+  </svg>
+
+  <!-- Slotted actions are light DOM, so style them with your own page CSS
+       (a ghost button with a + icon, here styled inline for portability). -->
+  <button
+    style="display:inline-flex; align-items:center; gap:.45rem;
+           font:500 13.5px/1 system-ui,sans-serif; padding:.5rem .85rem;
+           border-radius:9px; border:1px solid var(--color-border, #e5e5e5);
+           background:transparent; color:inherit; cursor:pointer;"
+  >
+    <svg width="16" height="16" viewBox="0 0 24 24" fill="none"
+         stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <path d="M5 12h14" /><path d="M12 5v14" />
+    </svg>
+    New chat
+  </button>
+</kitn-empty>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-empty',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-empty>` is the framework-agnostic **web component** for an empty-state block — an icon, a title, a description, and actions — isolated in **Shadow DOM**.',
+          '**When to use:** placeholder UI for an empty list/thread in a non-Solid app. In SolidJS, compose the `Empty*` primitives.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set `empty-title` (note `empty-title`, not `title`) and `description` via attributes, and use the **slots** (\"Route 2\") to project your own icon (`slot=\"media\"`) and actions (the default slot).",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Render the actual `<kitn-empty>` custom element with slotted children. */
+function EmptyElement() {
+  let el: HTMLElement | undefined;
+  onMount(() => {
+    if (!el) return;
+    el.setAttribute('empty-title', 'No conversations yet');
+    el.setAttribute('description', 'Start a new chat to see it appear here.');
+  });
+  return (
+    <kitn-empty ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '24px' }}>
+      <svg slot="media" width="28" height="28" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+        <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" />
+      </svg>
+      {/* Slotted actions are light DOM — style them with the host page's own
+          CSS. Here a ghost "+ New chat" button, styled inline so it renders
+          correctly in any context (mirrors the composable example's pill-btn). */}
+      <button
+        style={{
+          display: 'inline-flex',
+          'align-items': 'center',
+          gap: '0.45rem',
+          font: '500 13.5px/1 system-ui, sans-serif',
+          padding: '0.5rem 0.85rem',
+          'border-radius': '9px',
+          border: '1px solid var(--color-border, #e5e5e5)',
+          background: 'transparent',
+          color: 'inherit',
+          cursor: 'pointer',
+        }}
+      >
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M5 12h14" /><path d="M12 5v14" />
+        </svg>
+        New chat
+      </button>
+    </kitn-empty>
+  );
+}
+
+/** An empty state with a slotted icon and an action button. */
+export const Default: Story = {
+  render: () => <EmptyElement />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};

package/src/elements/kitn-feedback-bar.stories.tsx

@@ -0,0 +1,73 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import './register'; // side effect: registers the custom elements
+
+// 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-feedback-bar': JSX.HTMLAttributes<HTMLElement> & {
+        'bar-title'?: string;
+        'on:helpful'?: (e: CustomEvent) => void;
+        'on:nothelpful'?: (e: CustomEvent) => void;
+        'on:close'?: (e: CustomEvent) => void;
+      };
+    }
+  }
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-feedback-bar bar-title="Was this helpful?"></kitn-feedback-bar>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const bar = document.querySelector('kitn-feedback-bar');
+  bar.addEventListener('helpful', () => console.log('👍'));
+  bar.addEventListener('nothelpful', () => console.log('👎'));
+  bar.addEventListener('close', () => bar.remove());
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-feedback-bar',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-feedback-bar>` is the framework-agnostic **web component** for an inline thumbs up/down feedback banner with a dismiss button — isolated in **Shadow DOM**.',
+          '**When to use:** collecting a quick reaction after an answer or a completed task. In SolidJS, use the `FeedbackBar` primitive.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the label via the `bar-title` attribute (`title` is avoided — it's a global HTML attribute), and listen for the `helpful` / `nothelpful` / `close` **CustomEvents**.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** The default feedback prompt. */
+export const Default: Story = {
+  render: () => (
+    <div style={{ padding: '24px', 'max-width': '480px' }}>
+      <kitn-feedback-bar
+        on:helpful={() => console.log('helpful')}
+        on:nothelpful={() => console.log('not helpful')}
+        on:close={() => console.log('closed')}
+      />
+    </div>
+  ),
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** A custom label via the `bar-title` attribute. */
+export const CustomTitle: Story = {
+  render: () => (
+    <div style={{ padding: '24px', 'max-width': '480px' }}>
+      <kitn-feedback-bar bar-title="Did this answer your question?" />
+    </div>
+  ),
+};

package/src/elements/kitn-file-upload.stories.tsx

@@ -0,0 +1,81 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import './register'; // side effect: registers the custom elements
+
+// 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-file-upload': JSX.HTMLAttributes<HTMLElement> & {
+        multiple?: boolean | string;
+        accept?: string;
+        disabled?: boolean | string;
+        label?: string;
+        'on:filesadded'?: (e: CustomEvent<{ files: File[] }>) => void;
+      };
+    }
+  }
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-file-upload accept="image/*" label="Drop images here"></kitn-file-upload>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  document.querySelector('kitn-file-upload')
+    .addEventListener('filesadded', (e) =>
+      console.log(e.detail.files.map((f) => f.name)));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-file-upload',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-file-upload>` is the framework-agnostic **web component** for a click / drag-and-drop file dropzone — isolated in **Shadow DOM**.',
+          '**When to use:** accepting file or image uploads in a non-Solid app. In SolidJS, compose the `FileUpload` primitives.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the `accept` / `multiple` / `label` attributes, and listen for the `filesadded` **CustomEvent** (`e.detail.files` is a `File[]`). The default dropzone label can be replaced with your own markup via the default `<slot>`.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A dropzone accepting any files. */
+export const Default: Story = {
+  render: () => (
+    <div style={{ padding: '24px', 'max-width': '480px' }}>
+      <kitn-file-upload
+        on:filesadded={(e: CustomEvent<{ files: File[] }>) =>
+          console.log(e.detail.files.map((f) => f.name))}
+      />
+    </div>
+  ),
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Restricted to images, single file, with a custom label. */
+export const ImagesOnly: Story = {
+  render: () => (
+    <div style={{ padding: '24px', 'max-width': '480px' }}>
+      <kitn-file-upload accept="image/*" multiple={false} label="Click or drop an image" />
+    </div>
+  ),
+};
+
+/** A disabled dropzone (non-interactive). */
+export const Disabled: Story = {
+  render: () => (
+    <div style={{ padding: '24px', 'max-width': '480px' }}>
+      <kitn-file-upload disabled label="Uploads are disabled" />
+    </div>
+  ),
+};

package/src/elements/kitn-image.stories.tsx

@@ -0,0 +1,70 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+
+// 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-image': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+// A small inline SVG, base64-encoded — the same trick the composable example uses.
+const sampleSvg =
+  '<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96"><rect width="96" height="96" rx="16" fill="#7c3aed"/><text x="48" y="62" font-size="44" text-anchor="middle" fill="white">★</text></svg>';
+const sampleBase64 = btoa(unescape(encodeURIComponent(sampleSvg)));
+
+/** Render the actual `<kitn-image>` custom element with base64 + media-type. */
+function ImageElement() {
+  let el: (HTMLElement & { base64?: string; alt?: string }) | undefined;
+  onMount(() => {
+    if (el) {
+      el.base64 = sampleBase64;
+      el.alt = 'A purple star';
+      el.setAttribute('media-type', 'image/svg+xml');
+    }
+  });
+  return <kitn-image ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '16px' }} />;
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-image id="img" media-type="image/png" alt="A chart"></kitn-image>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const img = document.getElementById('img');
+  img.base64 = '<...base64 image data...>';
+  // or set raw bytes as a property:
+  // img.bytes = new Uint8Array([...]);
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-image',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-image>` is the framework-agnostic **web component** that renders a base64 or byte-array image, showing a skeleton fallback while it resolves, isolated in **Shadow DOM**.',
+          '**When to use:** displaying model-generated or in-memory images (without a hosted URL) in a non-Solid app. In SolidJS, use the `Image` primitive directly.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set `base64` (paired with the `media-type` attribute) or set raw `bytes` as a **property**, and add `alt` text.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A base64-encoded SVG with a media type and alt text. */
+export const Default: Story = {
+  render: () => <ImageElement />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};

package/src/elements/kitn-loader.stories.tsx

@@ -0,0 +1,87 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import './register'; // side effect: registers the custom elements
+
+// 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-loader': JSX.HTMLAttributes<HTMLElement> & {
+        variant?: string;
+        size?: string;
+        text?: string;
+      };
+    }
+  }
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-loader variant="dots" size="md"></kitn-loader>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-loader',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-loader>` is the framework-agnostic **web component** for an animated busy indicator — a dozen styles (circular, dots, wave, bars, text-shimmer, …) selected via the `variant` attribute, isolated in **Shadow DOM**.',
+          '**When to use:** showing a small "working" indicator anywhere outside the chat thread (toolbars, buttons, panels). In SolidJS, use the `Loader` primitive directly.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, then set `variant`, `size`, and (for text variants) `text` as plain HTML attributes.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+const VARIANTS = [
+  'circular', 'classic', 'pulse', 'pulse-dot', 'dots', 'typing',
+  'wave', 'bars', 'terminal', 'text-blink', 'text-shimmer', 'loading-dots',
+];
+
+/** The default circular spinner. */
+export const Default: Story = {
+  render: () => (
+    <div style={{ padding: '24px' }}>
+      <kitn-loader variant="circular" size="md" />
+    </div>
+  ),
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Every variant at the medium size, side by side. */
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', 'flex-wrap': 'wrap', gap: '32px', 'align-items': 'center', padding: '24px' }}>
+      {VARIANTS.map((v) => (
+        <div style={{ display: 'flex', 'flex-direction': 'column', 'align-items': 'center', gap: '8px', 'min-width': '90px' }}>
+          <kitn-loader variant={v} size="md" text="Loading" />
+          <code style={{ 'font-size': '11px', opacity: 0.6 }}>{v}</code>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+/** The three sizes (`sm` / `md` / `lg`) of the dots variant. */
+export const Sizes: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '32px', 'align-items': 'center', padding: '24px' }}>
+      {['sm', 'md', 'lg'].map((s) => (
+        <div style={{ display: 'flex', 'flex-direction': 'column', 'align-items': 'center', gap: '8px' }}>
+          <kitn-loader variant="dots" size={s} />
+          <code style={{ 'font-size': '11px', opacity: 0.6 }}>{s}</code>
+        </div>
+      ))}
+    </div>
+  ),
+};

package/src/elements/kitn-markdown.stories.tsx

@@ -0,0 +1,75 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+
+// 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-markdown': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const sampleMarkdown = `### Markdown
+Renders **bold**, _italic_, \`code\`, and lists:
+- one
+- two
+
+> and blockquotes.
+
+\`\`\`ts
+export function add(a: number, b: number): number {
+  return a + b;
+}
+\`\`\``;
+
+/** Render the actual `<kitn-markdown>` custom element with a `content` property. */
+function MarkdownElement(props: { content: string }) {
+  let el: (HTMLElement & { content?: string }) | undefined;
+  onMount(() => {
+    if (el) el.content = props.content;
+  });
+  return (
+    <kitn-markdown ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '16px', 'max-width': '720px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-markdown id="md" code-theme="github-dark-dimmed"></kitn-markdown>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const md = document.getElementById('md');
+  md.content = '### Hello\\nRenders **bold**, _italic_, and \\\`code\\\`.';
+  // md.setAttribute('code-highlight', 'false'); // skip Shiki entirely
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-markdown',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-markdown>` is the framework-agnostic **web component** that renders a markdown string (with fenced-code syntax highlighting via Shiki) as a standalone element, isolated in **Shadow DOM**.',
+          '**When to use:** showing model output or any markdown in a non-Solid app without pulling in a markdown stack. In SolidJS, use the `Markdown` primitive directly.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the source via the `content` **property** (`el.content = '...'`), and tune rendering with the `prose-size`, `code-theme`, and `code-highlight` attributes.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Headings, emphasis, lists, a blockquote, and a highlighted code fence. */
+export const Default: Story = {
+  render: () => <MarkdownElement content={sampleMarkdown} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};

package/src/elements/kitn-message-skills.stories.tsx

@@ -0,0 +1,74 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+
+// 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-message-skills': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+interface Skill {
+  id: string;
+  name: string;
+}
+
+const sampleSkills: Skill[] = [
+  { id: 's1', name: 'web-search' },
+  { id: 's2', name: 'code' },
+];
+
+/** Render the actual `<kitn-message-skills>` custom element with a `skills` property. */
+function MessageSkillsElement(props: { skills: Skill[] }) {
+  let el: (HTMLElement & { skills?: Skill[] }) | undefined;
+  onMount(() => {
+    if (el) el.skills = props.skills;
+  });
+  return (
+    <kitn-message-skills ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '16px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-message-skills id="skills"></kitn-message-skills>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const skills = document.getElementById('skills');
+  skills.skills = [
+    { id: 's1', name: 'web-search' },
+    { id: 's2', name: 'code' },
+  ];
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-message-skills',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-message-skills>` is the framework-agnostic **web component** that badges which skills were active for a message, isolated in **Shadow DOM**.',
+          '**When to use:** annotating a message row with the skills/tools it used, in a non-Solid app. In SolidJS, use the `MessageSkills` primitive directly.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, then set the `skills` **property** to an array of `{ id, name }`.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Two active-skill badges. */
+export const Default: Story = {
+  render: () => <MessageSkillsElement skills={sampleSkills} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};

package/src/elements/kitn-message.stories.tsx

@@ -0,0 +1,105 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+import type { ChatMessage } from './chat-types';
+
+// 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-message': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const assistantMessage: ChatMessage = {
+  id: 'm-a',
+  role: 'assistant',
+  content:
+    "Here's the plan, with a quick code sample:\n\n```js\nconst kit = useKitn();\n```\n\nThat wires the kit into your component.",
+  reasoning: { text: 'The user wants X, so I should do Y then Z.', label: 'Reasoning' },
+  tools: [{ type: 'search', state: 'output-available', input: { query: 'kitn docs' }, output: { hits: 3 } }],
+  attachments: [
+    {
+      id: '1',
+      type: 'file',
+      filename: 'architecture.png',
+      mediaType: 'image/png',
+      url:
+        'data:image/svg+xml;utf8,' +
+        encodeURIComponent(
+          '<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96"><rect width="96" height="96" rx="12" fill="#7c3aed"/><text x="48" y="60" font-size="42" text-anchor="middle" fill="white">◆</text></svg>',
+        ),
+    },
+  ],
+  actions: ['copy', 'like', 'dislike', 'regenerate'],
+};
+
+const userMessage: ChatMessage = {
+  id: 'm-u',
+  role: 'user',
+  content: 'How do I compose these myself?',
+};
+
+/** Render the actual `<kitn-message>` custom element with a `message` property. */
+function MessageElement(props: { message: ChatMessage }) {
+  let el: (HTMLElement & { message?: ChatMessage }) | undefined;
+  onMount(() => {
+    if (el) el.message = props.message;
+  });
+  return (
+    <kitn-message ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '16px', 'max-width': '720px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-message id="msg" style="display:block;"></kitn-message>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const msg = document.getElementById('msg');
+  msg.message = {
+    id: 'm-a', role: 'assistant',
+    content: "Here's the plan:\\n\\n\\\`\\\`\\\`js\\nconst kit = useKitn();\\n\\\`\\\`\\\`",
+    reasoning: { text: 'The user wants X, so I should do Y.' },
+    tools: [{ type: 'search', state: 'output-available', output: { hits: 3 } }],
+    actions: ['copy', 'like', 'dislike', 'regenerate'],
+  };
+
+  // events are CustomEvents on the element (they do not bubble)
+  msg.addEventListener('messageaction', (e) => console.log(e.detail.action, e.detail.messageId));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-message',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-message>` is the framework-agnostic **web component** for a single message row — markdown/plain content, an optional reasoning block, tool calls, attachments, and action buttons — all rendered from one `message` object (the same shape `<kitn-chat>` uses per message). It is the keystone of the "compose your own message list" pattern, isolated in **Shadow DOM**.',
+          "**When to use:** building a custom message thread in a non-Solid app, or anywhere you want to lay out the list yourself but keep the kit's rich message rendering. In SolidJS, compose the `Message` primitives for finer control.",
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the whole row via the `message` **property** (`el.message = {...}`), and listen for the `messageaction` **CustomEvent** for action-button clicks. For simple cases, set `role` + `content` attributes instead of a full object.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A rich assistant message: markdown, reasoning, a tool call, an attachment, and actions. */
+export const Assistant: Story = {
+  render: () => <MessageElement message={assistantMessage} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** A plain user message (markdown defaults off for the user role). */
+export const User: Story = {
+  render: () => <MessageElement message={userMessage} />,
+};