@kitnai/chat 0.6.0 → 0.8.0

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

@@ -1,12 +1,13 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import './register'; // side effect: registers the custom elements
+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-file-upload': JSX.HTMLAttributes<HTMLElement> & {
+      'kc-file-upload': JSX.HTMLAttributes<HTMLElement> & {
         multiple?: boolean | string;
         accept?: string;
         disabled?: boolean | string;
@@ -18,30 +19,29 @@ declare module 'solid-js' {
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-file-upload accept="image/*" label="Drop images here"></kitn-file-upload>
+<kc-file-upload accept="image/*" label="Drop images here"></kc-file-upload>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
 
-  document.querySelector('kitn-file-upload')
+  document.querySelector('kc-file-upload')
     .addEventListener('filesadded', (e) =>
       console.log(e.detail.files.map((f) => f.name)));
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-file-upload',
+  title: 'Web Components/kc-file-upload',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kc-file-upload'),
   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**.',
+      description: specDescription('kc-file-upload', [
+          '`<kc-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;
@@ -53,7 +53,7 @@ type Story = StoryObj;
 export const Default: Story = {
   render: () => (
     <div style={{ padding: '24px', 'max-width': '480px' }}>
-      <kitn-file-upload
+      <kc-file-upload
         on:filesadded={(e: CustomEvent<{ files: File[] }>) =>
           console.log(e.detail.files.map((f) => f.name))}
       />
@@ -66,7 +66,7 @@ export const Default: Story = {
 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" />
+      <kc-file-upload accept="image/*" multiple={false} label="Click or drop an image" />
     </div>
   ),
 };
@@ -75,7 +75,7 @@ export const ImagesOnly: Story = {
 export const Disabled: Story = {
   render: () => (
     <div style={{ padding: '24px', 'max-width': '480px' }}>
-      <kitn-file-upload disabled label="Uploads are disabled" />
+      <kc-file-upload disabled label="Uploads are disabled" />
     </div>
   ),
 };

package/src/elements/file-upload.tsx

@@ -1,4 +1,4 @@
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { FileUpload, FileUploadTrigger } from '../components/file-upload';
 import { Upload } from 'lucide-solid';
 
@@ -13,18 +13,18 @@ interface Props extends Record<string, unknown> {
   label?: string;
 }
 
-/** Events fired by `<kitn-file-upload>`. */
+/** Events fired by `<kc-file-upload>`. */
 interface Events {
   /** Files were picked or dropped. */
   filesadded: { files: File[] };
 }
 
 /**
- * `<kitn-file-upload>` — a click/drag-drop dropzone. Emits `filesadded`. The
+ * `<kc-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', {
+defineWebComponent<Props, Events>('kc-file-upload', {
   multiple: true,
   accept: undefined,
   disabled: false,

package/src/elements/form.stories.tsx

@@ -0,0 +1,204 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal, onMount, type JSX } from 'solid-js';
+import './form';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+import type { FormDefinition } from '../components/form';
+import type { CardEvent } from '../primitives/card-contract';
+
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kc-form': JSX.HTMLAttributes<HTMLElement> & {
+        heading?: string;
+        'card-id'?: string;
+        ref?: (el: HTMLElement) => void;
+      };
+    }
+  }
+}
+
+type FormEl = HTMLElement & { data?: FormDefinition };
+
+/** A bordered box the form sits inside. */
+function Frame(props: { children: JSX.Element }) {
+  return <div style={{ 'max-width': '460px' }}>{props.children}</div>;
+}
+
+/** Mounts a <kc-form>, sets `.data`, logs the emitted CardEvent under the render. */
+function FormDemo(props: { def: FormDefinition; cardId: string }) {
+  const [log, setLog] = createSignal<CardEvent[]>([]);
+  let el: FormEl | undefined;
+  onMount(() => {
+    if (!el) return;
+    el.data = props.def;
+    el.addEventListener('kc-card', (e) => {
+      const detail = (e as CustomEvent<CardEvent>).detail;
+      setLog((prev) => [...prev, detail]);
+    });
+  });
+  return (
+    <Frame>
+      <div style={{ display: 'flex', 'flex-direction': 'column', gap: '12px' }}>
+        <kc-form ref={(e) => (el = e as FormEl)} card-id={props.cardId} />
+        <pre
+          style={{
+            margin: 0,
+            'max-height': '180px',
+            overflow: 'auto',
+            background: 'var(--color-muted, #f4f4f5)',
+            'border-radius': '8px',
+            padding: '8px',
+            'font-size': '12px',
+          }}
+        >
+          {log().length === 0 ? '// emitted CardEvents appear here' : JSON.stringify(log(), null, 2)}
+        </pre>
+      </div>
+    </Frame>
+  );
+}
+
+const FEEDBACK: FormDefinition = {
+  type: 'object',
+  title: 'How did we do?',
+  description: 'Two quick questions.',
+  required: ['rating', 'contactOk'],
+  'x-kc-order': ['rating', 'comments', 'plan', 'contactOk'],
+  'x-kc-submitLabel': 'Send feedback',
+  'x-kc-actions': [{ id: 'skip', label: 'Skip', variant: 'ghost' }],
+  properties: {
+    rating: { type: 'integer', title: 'Overall rating', minimum: 1, maximum: 5, 'x-kc-widget': 'rating' },
+    comments: {
+      type: 'string',
+      title: 'Comments',
+      maxLength: 500,
+      'x-kc-widget': 'textarea',
+      'x-kc-placeholder': "What worked, what didn't…",
+    },
+    plan: { type: 'string', title: 'Your plan', enum: ['free', 'pro', 'team'], default: 'free' },
+    contactOk: { type: 'boolean', title: 'OK to contact me about this', default: false },
+  },
+};
+
+const ALL_WIDGETS: FormDefinition = {
+  type: 'object',
+  title: 'Every widget',
+  'x-kc-submitLabel': 'Submit all',
+  properties: {
+    name: { type: 'string', title: 'Name' },
+    bio: { type: 'string', title: 'Bio', maxLength: 300 },
+    email: { type: 'string', title: 'Email', format: 'email' },
+    website: { type: 'string', title: 'Website', format: 'uri' },
+    birthday: { type: 'string', title: 'Birthday', format: 'date' },
+    secret: { type: 'string', title: 'Password', 'x-kc-widget': 'password' },
+    size: { type: 'string', title: 'Size', enum: ['S', 'M', 'L'] },
+    country: { type: 'string', title: 'Country', enum: ['US', 'UK', 'DE', 'FR', 'JP'] },
+    age: { type: 'integer', title: 'Age', minimum: 0, maximum: 120 },
+    volume: { type: 'integer', title: 'Volume', minimum: 0, maximum: 11, 'x-kc-widget': 'slider' },
+    stars: { type: 'integer', title: 'Stars', minimum: 1, maximum: 5, 'x-kc-widget': 'rating' },
+    notify: { type: 'boolean', title: 'Email me updates' },
+    agree: { type: 'boolean', title: 'I agree', 'x-kc-widget': 'checkbox' },
+    tags: { type: 'array', title: 'Tags', items: { type: 'string' } },
+    topics: { type: 'array', title: 'Topics', items: { enum: ['news', 'sports', 'tech'] } },
+    contacts: {
+      type: 'array',
+      title: 'Contacts',
+      items: {
+        type: 'object',
+        properties: { label: { type: 'string', title: 'Label' }, phone: { type: 'string', title: 'Phone' } },
+      },
+    },
+    address: {
+      type: 'object',
+      title: 'Address',
+      properties: { street: { type: 'string', title: 'Street' }, city: { type: 'string', title: 'City' } },
+    },
+  },
+};
+
+const VALIDATION: FormDefinition = {
+  type: 'object',
+  title: 'Create account',
+  required: ['username', 'email', 'age'],
+  properties: {
+    username: { type: 'string', title: 'Username', minLength: 3, maxLength: 12 },
+    email: { type: 'string', title: 'Email', format: 'email' },
+    age: { type: 'integer', title: 'Age', minimum: 13, maximum: 120 },
+  },
+};
+
+const HTML_SNIPPET = (def: FormDefinition) => `<kc-form></kc-form>
+<script type="module">
+  import '@kitnai/chat/elements'; // registers the custom elements
+
+  const form = document.querySelector('kc-form');
+  // \`data\` is the CardEnvelope.data — a JSON Schema + x-kc-* UI hints (set as a property).
+  form.data = ${JSON.stringify(def, null, 2)};
+
+  // Cards bubble ONE \`kc-card\` CustomEvent carrying a typed CardEvent.
+  form.addEventListener('kc-card', (e) => {
+    const ev = e.detail; // { kind:'submit-data', cardId, data } | { kind:'action', ... } | ...
+    if (ev.kind === 'submit-data') console.log('submission', ev.data);
+  });
+</script>`;
+
+const meta = {
+  title: 'Generative UI/Cards/kc-form',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kc-form'),
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: specDescription('kc-form', [
+        '`<kc-form>` turns an agent\'s **JSON Schema** "shape" (set via the `data` **property**) into a themed, accessible, validated form inside `<kc-card>` chrome. A valid submission is emitted **up the Card contract** as a bubbling **`kc-card`** CustomEvent of `{ kind: \'submit-data\', cardId, data }`.',
+        '**The mapping is deterministic:** `string`→text, `string`+`enum`→radio/select, `string`+`format`→typed inputs, `number`/`integer`→number (or `slider`/`rating` via `x-kc-widget`), `boolean`→switch, `array`→checkbox-group / multi-select / repeater / tag-list, nested `object`→fieldset. `x-kc-*` hints (`x-kc-widget`, `x-kc-order`, `x-kc-submitLabel`, `x-kc-actions`, `x-kc-dismissible`, …) refine the UI and live **inside** the schema, so one source of truth drives both the form and validation.',
+        "**Events** (all frozen Card-contract verbs): `ready` on mount, `submit-data` on a valid submit, `action` for secondary buttons (`x-kc-actions`), `dismiss` when dismissible, `error` for a malformed definition (renders the inline `kc-card` error). It **never invents events**.",
+        '**The same `CardEnvelope`/`CardEvent` shapes flow over the remote iframe transport unchanged** — this is the *native* card. See the **Code** tab for the full envelope JSON + the HTML wiring.',
+      ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** The worked example: a rating + textarea + enum radio + switch, with a Skip action. */
+export const Feedback: Story = {
+  render: () => <FormDemo def={FEEDBACK} cardId="card-feedback-7f3" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET(FEEDBACK), language: 'html' } } },
+};
+
+/** One form exercising every row of the mapping table. */
+export const AllWidgets: Story = {
+  render: () => <FormDemo def={ALL_WIDGETS} cardId="card-all" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET(ALL_WIDGETS), language: 'html' } } },
+};
+
+/** Required + min/max + format: try submitting empty (inline errors), then fill it in. */
+export const Validation: Story = {
+  render: () => <FormDemo def={VALIDATION} cardId="card-signup" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET(VALIDATION), language: 'html' } } },
+};
+
+/** A malformed `data` → the inline error state + an `error` event (no form rendered). */
+export const InvalidEnvelope: Story = {
+  render: () => <FormDemo def={{ type: 'array' } as unknown as FormDefinition} cardId="card-bad" />,
+  parameters: {
+    docs: {
+      source: {
+        code: `<kc-form></kc-form>
+<script type="module">
+  import '@kitnai/chat/elements';
+  const form = document.querySelector('kc-form');
+  // A definition that isn't a JSON-Schema object → inline error + an \`error\` event.
+  form.data = { type: 'array' };
+  form.addEventListener('kc-card', (e) => {
+    if (e.detail.kind === 'error') console.warn('form error:', e.detail.message);
+  });
+</script>`,
+        language: 'html',
+      },
+    },
+  },
+};

package/src/elements/form.tsx

@@ -0,0 +1,37 @@
+import { defineWebComponent } from './define';
+import { Form, type FormDefinition } from '../components/form';
+
+interface Props extends Record<string, unknown> {
+  /** The form definition — a JSON Schema (`type:'object'`) + `x-kc-*` UI hints
+   *  (the CardEnvelope.data). Set as a JS PROPERTY: `el.data = { type:'object',
+   *  properties:{…} }`. Import the `FormDefinition` type from `@kitnai/chat` for
+   *  the full shape (it is self-referential, so the element types it loosely). */
+  data?: Record<string, unknown>;
+  /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
+  cardId?: string;
+  /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
+  heading?: string;
+}
+
+/**
+ * `<kc-form>` — renders a JSON-Schema **form definition** (set via the `data`
+ * property) into themed, accessible widgets inside `<kc-card>` chrome, validates
+ * input client-side, and emits the collected, coerced, validated object up the
+ * Card contract as a bubbling **`kc-card`** CustomEvent of `{ kind:'submit-data' }`.
+ * It also emits `ready` on mount, `action`/`dismiss` for secondary affordances, and
+ * `error` for a malformed definition. Routes through a `CardProvider` when present,
+ * else the bubbling `kc-card` event (so a bare `<kc-form>` works without a host).
+ * Isolated in Shadow DOM; theme-aware via the shared kit tokens.
+ */
+defineWebComponent<Props>('kc-form', {
+  data: undefined,
+  cardId: undefined,
+  heading: undefined,
+}, (props, { element }) => (
+  <Form
+    data={props.data as FormDefinition | undefined}
+    cardId={props.cardId ?? (element.id || 'kc-form')}
+    heading={props.heading}
+    hostElement={element}
+  />
+));

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

@@ -1,13 +1,14 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
 import './register'; // side effect: registers the custom elements
+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-image': JSX.HTMLAttributes<HTMLElement>;
+      'kc-image': JSX.HTMLAttributes<HTMLElement>;
     }
   }
 }
@@ -17,7 +18,7 @@ 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. */
+/** Render the actual `<kc-image>` custom element with base64 + media-type. */
 function ImageElement() {
   let el: (HTMLElement & { base64?: string; alt?: string }) | undefined;
   onMount(() => {
@@ -27,11 +28,11 @@ function ImageElement() {
       el.setAttribute('media-type', 'image/svg+xml');
     }
   });
-  return <kitn-image ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '16px' }} />;
+  return <kc-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>
+<kc-image id="img" media-type="image/png" alt="A chart"></kc-image>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -43,19 +44,18 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-image',
+  title: 'Web Components/kc-image',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kc-image'),
   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**.',
+      description: specDescription('kc-image', [
+          '`<kc-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;

package/src/elements/image.tsx

@@ -1,4 +1,4 @@
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { Image } from '../components/image';
 
 interface Props extends Record<string, unknown> {
@@ -13,11 +13,11 @@ interface Props extends Record<string, unknown> {
 }
 
 /**
- * `<kitn-image>` — renders a base64 or byte-array image with a skeleton
+ * `<kc-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', {
+defineWebComponent<Props>('kc-image', {
   base64: undefined,
   bytes: undefined,
   alt: '',

package/src/elements/link-card.stories.tsx

@@ -0,0 +1,193 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount, onCleanup, type JSX } from 'solid-js';
+import './link-card'; // side effect: registers <kc-link-card>
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+import type { LinkCardData } from '../primitives/link-preview';
+import { configureLinkPreview } from '../primitives/link-preview';
+
+// Custom DOM element — declare the tag for JSX.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kc-link-card': JSX.HTMLAttributes<HTMLElement> & {
+        'card-id'?: string;
+        ref?: (el: HTMLElement) => void;
+      };
+    }
+  }
+}
+
+/** A sized box the card sits in (cards expand to their container width). */
+function Frame(props: { children: JSX.Element }) {
+  return <div style={{ width: '100%', 'max-width': '420px' }}>{props.children}</div>;
+}
+
+/** Mount a kc-link-card, set its `data` property, and route `open` to a console log. */
+function Card(props: { cardId: string; data: LinkCardData }) {
+  let el: HTMLElement & { cardId?: string; data?: LinkCardData };
+  const onCard = (e: Event) => {
+    const ev = (e as CustomEvent).detail;
+    // eslint-disable-next-line no-console
+    console.log('[kc-card]', ev);
+    if (ev.kind === 'open' && ev.target === 'tab') {
+      window.open(ev.url, '_blank', 'noopener,noreferrer');
+    }
+  };
+  onMount(() => {
+    if (el) {
+      el.cardId = props.cardId;
+      el.data = props.data;
+    }
+    document.addEventListener('kc-card', onCard);
+    onCleanup(() => document.removeEventListener('kc-card', onCard));
+  });
+  return (
+    <Frame>
+      <kc-link-card ref={(e) => (el = e as HTMLElement & { cardId?: string; data?: LinkCardData })} />
+    </Frame>
+  );
+}
+
+const FULL_ENVELOPE = {
+  type: 'link',
+  id: 'card-link-1',
+  title: 'Shared link',
+  data: {
+    url: 'https://example.com/blog/generative-ui',
+    title: 'Generative UI, explained',
+    description:
+      'How agents render typed, themed cards in the chat — across native components and provider iframes.',
+    image: 'https://placehold.co/1200x630/6366f1/ffffff/png?text=Generative+UI',
+    imageAlt: 'Diagram of the card contract',
+    favicon: 'https://example.com/favicon.ico',
+    siteName: 'Example Blog',
+    domain: 'example.com',
+  },
+} satisfies { type: string; id: string; title: string; data: LinkCardData };
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kc-link-card id="lc"></kc-link-card>
+
+<script type="module">
+  import '@kitnai/chat/elements'; // registers the custom elements
+
+  const lc = document.getElementById('lc');
+  lc.cardId = 'card-link-1';
+  // \`data\` is a JS property (the CardEnvelope \`data\`):
+  lc.data = ${JSON.stringify(FULL_ENVELOPE.data, null, 2).replace(/\n/g, '\n  ')};
+
+  // Route the card's \`open\` verb (it bubbles as the composed \`kc-card\` event):
+  document.addEventListener('kc-card', (e) => {
+    const ev = e.detail; // CardEvent
+    if (ev.kind === 'open' && ev.target === 'tab') {
+      window.open(ev.url, '_blank', 'noopener,noreferrer');
+    }
+  });
+</script>`;
+
+const meta = {
+  title: 'Generative UI/Cards/kc-link-card',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kc-link-card'),
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: specDescription('kc-link-card', [
+        '`<kc-link-card>` is a themed, accessible **rich link / Open-Graph preview** card for the generative-UI feature. It speaks the **Card Contract**: data down (a `link` `CardEnvelope`), events up (only the `open` verb, plus lifecycle `ready` / failure `error`).',
+        '**Pure by default:** the card renders from the metadata you supply (`title`, `description`, `image`, `favicon`, `siteName`, `domain`) — it **never fetches**. For the bare-`{ url }` case, an app may opt in to a resolver with `configureLinkPreview({ fetchMetadata })` (CORS means OG scraping needs YOUR backend; there is no built-in network call).',
+        '**Interaction:** the whole card is one link target. Activating it (click / Enter / Space) dispatches the bubbling, composed **`kc-card`** event with `{ kind: \'open\', url, target: \'tab\' }` so a host-level listener routes it through `CardPolicy` (which performs the navigation, after scheme validation).',
+        '**Graceful degradation:** a missing/broken image drops the image region (not an error); an invalid url renders a non-clickable "Invalid link" chip and emits one `error`.',
+        'See the **Code** tab for the `CardEnvelope` JSON + HTML wiring.',
+      ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Full OG metadata — image, site name, title, description. */
+export const FullPreview: Story = {
+  name: 'Full preview',
+  render: () => <Card cardId={FULL_ENVELOPE.id} data={FULL_ENVELOPE.data} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** No image — the card degrades gracefully to the text + domain layout. */
+export const NoImage: Story = {
+  name: 'No image',
+  render: () => (
+    <Card
+      cardId="card-link-2"
+      data={{
+        url: 'https://docs.example.com/guide',
+        title: 'API Guide',
+        description: 'Reference for the public endpoints, auth, and rate limits.',
+        siteName: 'Example Docs',
+      }}
+    />
+  ),
+  parameters: {
+    docs: {
+      source: {
+        code: JSON.stringify(
+          {
+            type: 'link',
+            id: 'card-link-2',
+            data: {
+              url: 'https://docs.example.com/guide',
+              title: 'API Guide',
+              description: 'Reference for the public endpoints, auth, and rate limits.',
+              siteName: 'Example Docs',
+            },
+          },
+          null,
+          2,
+        ),
+        language: 'json',
+      },
+    },
+  },
+};
+
+/** Bare URL + a configured fetcher — shows the skeleton → merged render path. */
+export const BareUrlWithFetcher: Story = {
+  name: 'Bare URL + fetcher',
+  render: () => {
+    // Demo only: an app would point this at its own backend/proxy.
+    configureLinkPreview({
+      fetchMetadata: async (url) => {
+        await new Promise((r) => setTimeout(r, 900)); // show the skeleton
+        return {
+          title: 'Resolved by your backend',
+          description: `Metadata for ${url} fetched via configureLinkPreview.`,
+          siteName: 'example.com',
+        };
+      },
+    });
+    return <Card cardId="card-link-3" data={{ url: 'https://example.com/bare' }} />;
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `import { configureLinkPreview } from '@kitnai/chat';
+
+// Opt in once (points at YOUR backend/proxy — there is no built-in network call):
+configureLinkPreview({
+  fetchMetadata: (url) => fetch('/api/og?url=' + encodeURIComponent(url)).then((r) => r.json()),
+});
+
+// Then a bare { url } envelope resolves to a full preview:
+lc.data = { url: 'https://example.com/bare' };`,
+        language: 'ts',
+      },
+    },
+  },
+};
+
+/** Invalid link — a non-clickable error chip; one \`error\` event is emitted. */
+export const InvalidLink: Story = {
+  name: 'Invalid link',
+  render: () => <Card cardId="card-link-4" data={{ url: 'not-a-valid-url' }} />,
+};

package/src/elements/link-card.tsx

@@ -0,0 +1,34 @@
+import { defineWebComponent } from './define';
+import { LinkCard } from '../components/link-card';
+import type { LinkCardData } from '../primitives/link-preview';
+import { emitCardEvent } from '../primitives/card-routing';
+
+interface Props extends Record<string, unknown> {
+  /** Stable card id correlating every emitted event. Set as an attribute or property. */
+  cardId?: string;
+  /** The link payload (OG metadata). Set as a JS **property** (object). */
+  data?: LinkCardData;
+}
+
+/**
+ * `<kc-link-card>` — a themed, accessible rich link / Open-Graph preview card. It
+ * renders from the supplied `data` (it never fetches; an app may register a
+ * `configureLinkPreview` fetcher for the bare-`{ url }` path). Activating the card
+ * dispatches the bubbling, composed **`kc-card`** CustomEvent with the contract
+ * `open` verb (`{ kind:'open', url, target:'tab' }`) so a host-level listener
+ * routes it through CardPolicy. Set `data` as a JS property; `card-id` via attribute.
+ */
+defineWebComponent<Props>(
+  'kc-link-card',
+  {
+    cardId: undefined,
+    data: undefined,
+  },
+  (props, { element }) => (
+    <LinkCard
+      cardId={props.cardId ?? ''}
+      data={props.data ?? ({ url: '' } as LinkCardData)}
+      onEmit={(event) => emitCardEvent(element, event)}
+    />
+  ),
+);