@kitnai/chat 0.3.1 → 0.4.0

package/src/elements/file-upload.tsx

@@ -0,0 +1,44 @@
+import { defineKitnElement } from './define';
+import { FileUpload, FileUploadTrigger } from '../components/file-upload';
+import { Upload } from 'lucide-solid';
+
+interface Props extends Record<string, unknown> {
+  /** Allow selecting multiple files (default true). */
+  multiple?: boolean;
+  /** `accept` attribute for the file picker (e.g. `image/*`). */
+  accept?: string;
+  /** Disable the dropzone — no clicking, no drag-and-drop. */
+  disabled?: boolean;
+  /** Default dropzone label (overridable via the default slot). */
+  label?: string;
+}
+
+/** Events fired by `<kitn-file-upload>`. */
+interface Events {
+  /** Files were picked or dropped. */
+  filesadded: { files: File[] };
+}
+
+/**
+ * `<kitn-file-upload>` — a click/drag-drop dropzone. Emits `filesadded`. The
+ * default dropzone label can be replaced with your own markup via the default
+ * `<slot>` (a "Route 2" custom-content slot).
+ */
+defineKitnElement<Props, Events>('kitn-file-upload', {
+  multiple: true,
+  accept: undefined,
+  disabled: false,
+  label: 'Click or drop files to upload',
+}, (props, { dispatch, flag }) => (
+  <FileUpload
+    multiple={flag('multiple')}
+    accept={props.accept}
+    disabled={flag('disabled')}
+    onFilesAdded={(files) => dispatch('filesadded', { files })}
+  >
+    <FileUploadTrigger class="border-border bg-muted/30 hover:bg-muted/60 text-muted-foreground flex w-full cursor-pointer flex-col items-center justify-center gap-2 rounded-xl border border-dashed px-6 py-8 text-sm transition-colors">
+      <Upload class="size-5" />
+      <slot>{props.label}</slot>
+    </FileUploadTrigger>
+  </FileUpload>
+));

package/src/elements/image.tsx

@@ -0,0 +1,32 @@
+import { defineKitnElement } from './define';
+import { Image } from '../components/image';
+
+interface Props extends Record<string, unknown> {
+  /** Base64-encoded image data (pair with `media-type`). */
+  base64?: string;
+  /** Raw image bytes (set as a JS property). */
+  bytes?: Uint8Array;
+  /** Alt text. */
+  alt?: string;
+  /** MIME type (default `image/png`). */
+  mediaType?: string;
+}
+
+/**
+ * `<kitn-image>` — renders a base64 or byte-array image with a skeleton
+ * fallback while it resolves. `base64`/`alt`/`media-type` via attributes;
+ * `bytes` via property.
+ */
+defineKitnElement<Props>('kitn-image', {
+  base64: undefined,
+  bytes: undefined,
+  alt: '',
+  mediaType: undefined,
+}, (props) => (
+  <Image
+    alt={props.alt ?? ''}
+    base64={props.base64}
+    uint8Array={props.bytes}
+    mediaType={props.mediaType}
+  />
+));

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

@@ -0,0 +1,181 @@
+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';
+
+// 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> & {
+        variant?: string;
+        'hover-card'?: boolean | string;
+        removable?: boolean | string;
+        'show-media-type'?: boolean | string;
+      };
+    }
+  }
+}
+
+// Mixed file/source items (icons + labels) — mirrors Components/Attachments.
+const sampleItems: AttachmentData[] = [
+  {
+    id: '1',
+    type: 'file',
+    filename: 'mountain-landscape.jpg',
+    mediaType: 'image/jpeg',
+    url: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=400&h=400&fit=crop',
+  },
+  {
+    id: '2',
+    type: 'file',
+    filename: 'sunset-beach.png',
+    mediaType: 'image/png',
+    url: 'https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=400&h=400&fit=crop',
+  },
+  { id: '3', type: 'file', filename: 'architecture-report.pdf', mediaType: 'application/pdf' },
+  { id: '4', type: 'file', filename: 'demo-recording.mp4', mediaType: 'video/mp4' },
+  { id: '5', type: 'file', filename: 'podcast-episode.mp3', mediaType: 'audio/mpeg' },
+  { id: '6', type: 'source-document', filename: 'SolidJS Documentation', title: 'SolidJS Reactivity Guide', url: 'https://solidjs.com/docs' },
+];
+
+// Image-only items — used for the grid thumbnails + hover-card preview stories.
+const imageItems: AttachmentData[] = [
+  {
+    id: 'img-1',
+    type: 'file',
+    filename: 'mountain-landscape.jpg',
+    mediaType: 'image/jpeg',
+    url: 'https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=400&h=400&fit=crop',
+  },
+  {
+    id: 'img-2',
+    type: 'file',
+    filename: 'sunset-beach.png',
+    mediaType: 'image/png',
+    url: 'https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=400&h=400&fit=crop',
+  },
+];
+
+/** Render `<kitn-attachments>` with an `items` property and the given flags. */
+function AttachmentsElement(props: {
+  items: AttachmentData[];
+  variant?: string;
+  removable?: boolean;
+  hoverCard?: boolean;
+  showMediaType?: boolean;
+}) {
+  let el: (HTMLElement & { items?: AttachmentData[] }) | undefined;
+  onMount(() => {
+    if (!el) return;
+    el.items = props.items;
+    if (props.variant) el.setAttribute('variant', props.variant);
+    if (props.hoverCard) el.setAttribute('hover-card', '');
+    if (props.showMediaType) el.setAttribute('show-media-type', '');
+    if (props.removable) {
+      el.setAttribute('removable', '');
+      el.addEventListener('remove', ((e: CustomEvent<{ id: string }>) => {
+        el!.items = (el!.items ?? []).filter((x) => x.id !== e.detail.id);
+      }) as EventListener);
+    }
+  });
+  return (
+    <kitn-attachments
+      ref={(e) => (el = e as HTMLElement)}
+      style={{ display: 'block', padding: '24px', 'max-width': '720px' }}
+    />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-attachments id="att" variant="grid" removable></kitn-attachments>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const att = document.getElementById('att');
+  att.items = [
+    { id: '1', type: 'file', filename: 'mountain-landscape.jpg',
+      mediaType: 'image/jpeg', url: 'https://.../mountain.jpg' },
+    { id: '2', type: 'file', filename: 'spec.pdf', mediaType: 'application/pdf' },
+  ];
+
+  // events are CustomEvents on the element (they do not bubble)
+  att.addEventListener('remove', (e) => {
+    att.items = att.items.filter((x) => x.id !== e.detail.id);
+  });
+</script>`;
+
+const HOVER_SNIPPET = `<!-- inline/list chips with a hover-card image preview -->
+<kitn-attachments id="att" variant="inline" hover-card></kitn-attachments>
+
+<script type="module">
+  import '@kitnai/chat/elements';
+
+  const att = document.getElementById('att');
+  // image attachments show their thumbnail in the hover card on hover;
+  // non-image attachments show their label + media type instead.
+  att.items = [
+    { id: '1', type: 'file', filename: 'mountain-landscape.jpg',
+      mediaType: 'image/jpeg', url: 'https://.../mountain.jpg' },
+  ];
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-attachments',
+  tags: ['autodocs'],
+  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**.',
+          '**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;
+
+export default meta;
+type Story = StoryObj;
+
+/** 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 = {
+  render: () => <AttachmentsElement items={sampleItems} variant="grid" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Icon + label chips (`inline`) — files shown as a small preview + filename. */
+export const Inline: Story = {
+  render: () => <AttachmentsElement items={sampleItems} variant="inline" />,
+};
+
+/** Detailed rows (`list`) with the media type beneath each filename. */
+export const List: Story = {
+  render: () => <AttachmentsElement items={sampleItems} variant="list" showMediaType />,
+};
+
+/** Removable rows — clicking the remove button fires a `remove` event. */
+export const RemovableList: Story = {
+  name: 'Removable List',
+  render: () => <AttachmentsElement items={sampleItems} variant="list" removable />,
+};
+
+/** Image thumbnails in a grid (real `<img>` previews). */
+export const ImageGrid: Story = {
+  name: 'Image Grid',
+  render: () => <AttachmentsElement items={imageItems} variant="grid" />,
+};
+
+/** Inline chips with a hover-card preview — hover an image chip to see its
+ *  thumbnail enlarge in the hover card. */
+export const WithHoverCard: Story = {
+  name: 'With Hover Card',
+  render: () => <AttachmentsElement items={imageItems} variant="inline" hoverCard />,
+  parameters: { docs: { source: { code: HOVER_SNIPPET, language: 'html' } } },
+};

package/src/elements/kitn-chain-of-thought.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
+
+interface Step {
+  label: string;
+  content?: string;
+}
+
+// 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-chain-of-thought': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const steps: Step[] = [
+  { label: 'Understand the request', content: 'The user wants a composable set of web components.' },
+  { label: 'Design the API', content: 'Route 1: variant + flags + events; rich data via properties.' },
+  { label: 'Build & verify' },
+];
+
+/** Render `<kitn-chain-of-thought>` with the `steps` set as a JS property. */
+function CotElement(props: { steps: Step[] }) {
+  let el: (HTMLElement & { steps?: Step[] }) | undefined;
+  onMount(() => {
+    if (el) el.steps = props.steps;
+  });
+  return (
+    <kitn-chain-of-thought ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '24px', 'max-width': '560px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-chain-of-thought id="cot"></kitn-chain-of-thought>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  document.getElementById('cot').steps = [
+    { label: 'Understand the request', content: 'The user wants a composable set.' },
+    { label: 'Design the API', content: 'Route 1: variant + flags + events.' },
+    { label: 'Build & verify' },
+  ];
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-chain-of-thought',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-chain-of-thought>` is the framework-agnostic **web component** for step-by-step reasoning — a connected list of steps, each with optional collapsible detail — isolated in **Shadow DOM**. The compound primitive collapses to a single `steps` data model (Route 1).',
+          '**When to use:** surfacing an agent\'s plan or reasoning trace in a non-Solid app. In SolidJS, compose the `ChainOfThought` primitives for finer control.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, then set the `steps` **property** — an array of `{ label, content? }`. Steps with `content` become expandable.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A three-step reasoning trace; the last step has no detail. */
+export const Default: Story = {
+  render: () => <CotElement steps={steps} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};

package/src/elements/kitn-chat-scope-picker.stories.tsx

@@ -0,0 +1,72 @@
+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-chat-scope-picker': JSX.HTMLAttributes<HTMLElement> & {
+        'current-label'?: string;
+      };
+    }
+  }
+}
+
+/** Render `<kitn-chat-scope-picker>` with author/tag options set as properties. */
+function ScopePickerElement(props: { authors: string[]; tags: string[] }) {
+  let el: (HTMLElement & { availableAuthors?: string[]; availableTags?: string[] }) | undefined;
+  onMount(() => {
+    if (!el) return;
+    el.availableAuthors = props.authors;
+    el.availableTags = props.tags;
+    el.addEventListener('scopechange', (e) => {
+      const ev = e as CustomEvent<{ filters: unknown }>;
+      console.log('scopechange', ev.detail.filters ?? 'all');
+    });
+  });
+  return (
+    <kitn-chat-scope-picker ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '40px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-chat-scope-picker id="scope"></kitn-chat-scope-picker>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const scope = document.getElementById('scope');
+  scope.availableAuthors = ['Rob', 'Alex'];
+  scope.availableTags = ['design', 'api'];
+  // undefined filters means "All Content"
+  scope.addEventListener('scopechange', (e) => console.log(e.detail.filters ?? 'all'));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-chat-scope-picker',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-chat-scope-picker>` is the framework-agnostic **web component** for scoping a chat by author or tag — a dropdown that emits the chosen filters — isolated in **Shadow DOM**.',
+          '**When to use:** letting users narrow a conversation/search to a subset of content. In SolidJS, use the `ChatScopePicker` primitive.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the `availableAuthors` / `availableTags` **properties** (and optionally `current-label`), and listen for the `scopechange` **CustomEvent** (`undefined` filters = \"All Content\").",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Authors and tags available as scope filters. */
+export const Default: Story = {
+  render: () => <ScopePickerElement authors={['Rob', 'Alex']} tags={['design', 'api']} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};

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

@@ -0,0 +1,71 @@
+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-checkpoint': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+/** Render the actual `<kitn-checkpoint>` custom element configured by attributes. */
+function CheckpointElement(props: { label?: string; tooltip?: string; variant?: string; size?: string }) {
+  let el: HTMLElement | undefined;
+  onMount(() => {
+    if (!el) return;
+    if (props.label) el.setAttribute('label', props.label);
+    if (props.tooltip) el.setAttribute('tooltip', props.tooltip);
+    if (props.variant) el.setAttribute('variant', props.variant);
+    if (props.size) el.setAttribute('size', props.size);
+    el.addEventListener('select', () => console.log('checkpoint selected'));
+  });
+  return <kitn-checkpoint ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '16px' }} />;
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-checkpoint label="Restore" tooltip="Restore this checkpoint" variant="outline" size="sm"></kitn-checkpoint>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const cp = document.querySelector('kitn-checkpoint');
+  // events are CustomEvents on the element (they do not bubble)
+  cp.addEventListener('select', () => console.log('restore checkpoint'));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-checkpoint',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-checkpoint>` is the framework-agnostic **web component** for a bookmark/checkpoint button (with an optional tooltip and label), isolated in **Shadow DOM**.',
+          '**When to use:** marking a restore point in a conversation in a non-Solid app. In SolidJS, compose the `Checkpoint` primitives.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set `label`, `tooltip`, `variant` (`ghost` | `default` | `outline`), and `size` via attributes, and listen for the `select` **CustomEvent** on click.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A labeled checkpoint button. (Add a `tooltip` attribute for a hover hint — see the Code tab.) */
+export const Labeled: Story = {
+  render: () => <CheckpointElement label="Restore" variant="outline" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Icon-only (no label), using an `icon` size. */
+export const IconOnly: Story = {
+  name: 'Icon Only',
+  render: () => <CheckpointElement size="icon-sm" />,
+};

package/src/elements/kitn-code-block.stories.tsx

@@ -0,0 +1,82 @@
+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-code-block': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const sampleCode = `export function add(a: number, b: number): number {
+  return a + b;
+}`;
+
+const pythonCode = `def fib(n):
+    a, b = 0, 1
+    for _ in range(n):
+        a, b = b, a + b
+    return a`;
+
+/** Render the actual `<kitn-code-block>` custom element with a `code` property. */
+function CodeBlockElement(props: { code: string; language?: string }) {
+  let el: (HTMLElement & { code?: string }) | undefined;
+  onMount(() => {
+    if (el) {
+      el.code = props.code;
+      if (props.language) el.setAttribute('language', props.language);
+    }
+  });
+  return (
+    <kitn-code-block
+      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-code-block id="code" language="ts" code-theme="github-dark-dimmed"></kitn-code-block>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const code = document.getElementById('code');
+  code.code = 'export function add(a, b) {\\n  return a + b;\\n}';
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-code-block',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-code-block>` is the framework-agnostic **web component** for a single syntax-highlighted code block, complete with a copy button, isolated in **Shadow DOM**.',
+          '**When to use:** dropping a highlighted snippet into a non-Solid app. In SolidJS, compose `CodeBlock` + `CodeBlockCode` directly.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the source via the `code` **property** (`el.code = '...'`), and pick a grammar with the `language` attribute (defaults to `tsx`). Tune highlighting with `code-theme` / `code-highlight`.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A TypeScript snippet (the default `tsx` grammar). */
+export const TypeScript: Story = {
+  render: () => <CodeBlockElement code={sampleCode} language="ts" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** A different grammar via the `language` attribute. */
+export const Python: Story = {
+  render: () => <CodeBlockElement code={pythonCode} language="python" />,
+};

package/src/elements/kitn-context-meter.stories.tsx

@@ -0,0 +1,85 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+
+interface ContextUsage {
+  usedTokens: number;
+  maxTokens: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  reasoningTokens?: number;
+  cacheTokens?: number;
+  estimatedCost?: number;
+}
+
+// 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-context-meter': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const usage: ContextUsage = {
+  usedTokens: 48200,
+  maxTokens: 200000,
+  inputTokens: 31000,
+  outputTokens: 17200,
+  reasoningTokens: 4200,
+  cacheTokens: 8000,
+  estimatedCost: 0.42,
+};
+
+/** Render `<kitn-context-meter>` with the `context` set as a JS property. */
+function MeterElement(props: { context: ContextUsage }) {
+  let el: (HTMLElement & { context?: ContextUsage }) | undefined;
+  onMount(() => {
+    if (el) el.context = props.context;
+  });
+  return (
+    <kitn-context-meter ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '40px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-context-meter id="ctx"></kitn-context-meter>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  document.getElementById('ctx').context = {
+    usedTokens: 48200, maxTokens: 200000,
+    inputTokens: 31000, outputTokens: 17200,
+    reasoningTokens: 4200, cacheTokens: 8000,
+    estimatedCost: 0.42,
+  };
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-context-meter',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-context-meter>` is the framework-agnostic **web component** for a token/context-window usage meter — a compact gauge with a hover-card breakdown (input / output / reasoning / cache + estimated cost) — isolated in **Shadow DOM**.',
+          '**When to use:** showing how much of the context window a conversation is using, typically in a chat header. In SolidJS, compose the `Context` primitives.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, then set the `context` **property** with the usage object. Hover the meter to reveal the breakdown.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A meter at ~24% usage; hover to reveal the full breakdown. */
+export const Default: Story = {
+  render: () => <MeterElement context={usage} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};