@kitn.ai/ui 0.14.1

package/src/elements/artifact.tsx

@@ -0,0 +1,137 @@
+import { createSignal, onMount, onCleanup } from 'solid-js';
+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;
+  /** Reflects the artifact's own maximized view-state (usually driven by the protocol). */
+  maximized?: boolean;
+  /** Show the expand-to-fill button (OPT-IN). */
+  expandable?: boolean;
+  /** Show the open-in-new-tab button (OPT-IN). */
+  openInTab?: boolean;
+  /** Hide back/forward. */
+  noNav?: boolean;
+  /** Hide reload. */
+  noReload?: boolean;
+  /** Hide home. */
+  noHome?: boolean;
+  /** Hide the address field. */
+  noPathField?: boolean;
+  /** Hide the Preview|Code toggle. */
+  noTabs?: boolean;
+  /** Standalone chrome: rounded corners + border (else square, borderless in-panel). */
+  standalone?: boolean;
+  /** Show the address but make it read-only (visible, nav-tracking, non-editable). */
+  readonlyPath?: boolean;
+}
+
+interface Events extends Record<string, unknown> {
+  /** Fired when the preview navigates. `detail.url` = the new location. */
+  'kai-navigate': { url: string };
+  /** Fired when the Preview|Code tab changes. `detail.tab`. */
+  'kai-tab-change': { tab: ArtifactTab };
+  /** Fired when a file is selected. `detail.path`. */
+  'kai-file-select': { path: string };
+  /** Artifact's own maximize button toggled (consumer-observable; non-bubbling). */
+  'kai-maximize-change': { maximized: boolean };
+}
+
+/**
+ * `<kai-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
+ * (`<kai-file-tree>`) + the active file's source via `<kai-code-block>`. The
+ * component self-navigates the iframe and emits `kai-navigate` / `kai-tab-change` /
+ * `kai-file-select`. Designed to FILL its container (e.g. a `<kai-resizable>` panel).
+ */
+defineWebComponent<Props, Events>('kai-artifact', {
+  src: undefined,
+  files: [],
+  tab: 'preview',
+  activeFile: undefined,
+  sandbox: 'allow-scripts allow-forms',
+  iframeTitle: undefined,
+  maximized: false,
+  expandable: false,
+  openInTab: false,
+  noNav: false,
+  noReload: false,
+  noHome: false,
+  noPathField: false,
+  noTabs: false,
+  standalone: false,
+  readonlyPath: false,
+}, (props, { element, dispatch, flag }) => {
+  const [maximized, setMaximized] = createSignal(flag('maximized'));
+
+  const onMaximizeChange = (next: boolean) => {
+    setMaximized(next);
+    // 1) The PROTOCOL intent — raw, bubbling + composed (NOT via dispatch()).
+    element.dispatchEvent(
+      new CustomEvent('kai-maximize-intent', { detail: { requested: next }, bubbles: true, composed: true }),
+    );
+    // 2) The PUBLIC observable event (non-bubbling, on the host).
+    dispatch('kai-maximize-change', { maximized: next });
+  };
+
+  // Authoritative reconcile: the resizable tells us the effective state.
+  onMount(() => {
+    const onState = (e: Event) => setMaximized((e as CustomEvent<{ maximized: boolean }>).detail.maximized);
+    element.addEventListener('kai-maximize-state', onState);
+    onCleanup(() => element.removeEventListener('kai-maximize-state', onState));
+  });
+
+  return (
+    <>
+      {/* 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}
+          maximized={maximized()}
+          expandable={flag('expandable')}
+          openInTab={flag('openInTab')}
+          showNav={!flag('noNav')}
+          showReload={!flag('noReload')}
+          showHome={!flag('noHome')}
+          showPathField={!flag('noPathField')}
+          showTabs={!flag('noTabs')}
+          standalone={flag('standalone')}
+          readonlyPath={flag('readonlyPath')}
+          onMaximizeChange={onMaximizeChange}
+          onNavigate={(url) => dispatch('kai-navigate', { url })}
+          onTabChange={(tab) => dispatch('kai-tab-change', { tab })}
+          onFileSelect={(path) => dispatch('kai-file-select', { path })}
+        />
+      </div>
+    </>
+  );
+});

package/src/elements/attachments.stories.tsx

@@ -0,0 +1,190 @@
+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 { 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 {
+      'kai-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 `<kai-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('kai-remove', ((e: CustomEvent<{ id: string }>) => {
+        el!.items = (el!.items ?? []).filter((x) => x.id !== e.detail.id);
+      }) as EventListener);
+    }
+  });
+  return (
+    <kai-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 -->
+<kai-attachments id="att" variant="grid" removable></kai-attachments>
+
+<script type="module">
+  import '@kitn.ai/ui/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('kai-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 -->
+<kai-attachments id="att" variant="inline" hover-card></kai-attachments>
+
+<script type="module">
+  import '@kitn.ai/ui/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: 'Components/Attachments',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-attachments'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-attachments', [
+          '`<kai-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.',
+          '**Placement:** beneath message content (for received/sent files) or above the prompt input (for staged uploads); fills its container width.',
+          "**How to use:** register once with `import '@kitn.ai/ui/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 `kai-remove` **CustomEvent** with `{ id }`), and `hover-card` for inline/list previews (image attachments preview their thumbnail).",
+          'See the **Code** tab for HTML usage.',
+        ]),
+    },
+  },
+} 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' } } },
+};
+
+/** Grid tiles with a hover-card preview — the tile shows only the image; the
+ *  filename + media type surface in the hover card. (Grid previously skipped
+ *  the hover card entirely.) */
+export const GridWithHoverCard: Story = {
+  name: 'Grid With Hover Card',
+  render: () => <AttachmentsElement items={imageItems} variant="grid" hoverCard />,
+};

package/src/elements/attachments.tsx

@@ -0,0 +1,136 @@
+import { For, Show } from 'solid-js';
+import { defineWebComponent } from './define';
+import {
+  Attachments,
+  Attachment,
+  AttachmentPreview,
+  AttachmentInfo,
+  AttachmentRemove,
+  AttachmentHoverCard,
+  AttachmentHoverCardTrigger,
+  AttachmentHoverCardContent,
+  AttachmentEmpty,
+  getAttachmentLabel,
+  getMediaCategory,
+  type AttachmentData,
+  type AttachmentVariant,
+} from '../components/attachments';
+
+interface Props extends Record<string, unknown> {
+  /** The attachments to render. Set as a JS property (array). */
+  items: AttachmentData[];
+  /** Layout: `grid` = visual tiles, `inline` = icon + label chips, `list` = rows. */
+  variant?: AttachmentVariant;
+  /** Wrap each item in a hover card that previews its details. */
+  hoverCard?: boolean;
+  /** Show a remove button per item; clicking it fires a `kai-remove` event. */
+  removable?: boolean;
+  /** Also show the media type beneath the filename (non-grid variants). */
+  showMediaType?: boolean;
+  /** Text shown when `items` is empty. */
+  emptyText?: string;
+}
+
+/** Events fired by `<kai-attachments>`. */
+interface Events {
+  /** A remove button was clicked. */
+  'kai-remove': { id: string };
+}
+
+/**
+ * `<kai-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
+ * attributes/flags here:
+ *
+ *   - icon + label .......... `variant="inline"`
+ *   - visual + hover card .... `variant="grid" hover-card`
+ *   - removable chips ........ add `removable` (emits `kai-remove` → { id })
+ *
+ * Data in via the `items` property; the only interaction (`remove`) comes back
+ * 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).
+ */
+defineWebComponent<Props, Events>('kai-attachments', {
+  items: [],
+  variant: 'grid',
+  hoverCard: false,
+  removable: false,
+  showMediaType: false,
+  emptyText: undefined,
+}, (props, { dispatch, flag }) => {
+  const variant = () => props.variant ?? 'grid';
+  const hoverCard = () => flag('hoverCard');
+  const removable = () => flag('removable');
+  const showMediaType = () => flag('showMediaType');
+
+  return (
+    <Show
+      when={props.items.length}
+      fallback={<Show when={props.emptyText}><AttachmentEmpty>{props.emptyText}</AttachmentEmpty></Show>}
+    >
+      <Attachments variant={variant()}>
+        <For each={props.items}>
+          {(item) => (
+            <Attachment
+              data={item}
+              onRemove={removable() ? () => dispatch('kai-remove', { id: item.id }) : undefined}
+            >
+              <Show
+                when={hoverCard()}
+                fallback={
+                  <>
+                    <AttachmentPreview />
+                    {/* Info only for non-grid; grid is a self-contained visual tile. */}
+                    <Show when={variant() !== 'grid'}>
+                      <AttachmentInfo showMediaType={showMediaType()} />
+                    </Show>
+                  </>
+                }
+              >
+                {/* The trigger carries the layout itself — a bare inline <span>
+                    collapses inline/list rows. Grid wraps just the tile (the
+                    label/details surface in the hover card instead). */}
+                <AttachmentHoverCard>
+                  <AttachmentHoverCardTrigger
+                    class={variant() === 'grid'
+                      ? 'block size-full'
+                      : `flex items-center gap-1.5${variant() === 'list' ? ' w-full' : ''}`}
+                  >
+                    <AttachmentPreview />
+                    <Show when={variant() !== 'grid'}>
+                      <AttachmentInfo showMediaType={showMediaType()} />
+                    </Show>
+                  </AttachmentHoverCardTrigger>
+                  <AttachmentHoverCardContent>
+                    {/* For image attachments, preview the actual thumbnail;
+                        otherwise fall back to the label + media-type details. */}
+                    <Show
+                      when={getMediaCategory(item) === 'image' && item.type === 'file' && item.url}
+                      fallback={
+                        <>
+                          <div class="text-body font-medium">{getAttachmentLabel(item)}</div>
+                          <Show when={item.mediaType}>
+                            <div class="text-muted-foreground text-caption">{item.mediaType}</div>
+                          </Show>
+                        </>
+                      }
+                    >
+                      <img
+                        src={item.url}
+                        alt={getAttachmentLabel(item)}
+                        class="block max-h-64 max-w-xs rounded object-contain"
+                      />
+                    </Show>
+                  </AttachmentHoverCardContent>
+                </AttachmentHoverCard>
+              </Show>
+              <AttachmentRemove />
+            </Attachment>
+          )}
+        </For>
+      </Attachments>
+    </Show>
+  );
+});

package/src/elements/card.stories.tsx

@@ -0,0 +1,113 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import type { JSX } from 'solid-js';
+import './card';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kai-card': JSX.HTMLAttributes<HTMLElement> & {
+        heading?: string;
+        description?: string;
+        'error-message'?: string;
+        dense?: boolean | string;
+      };
+    }
+  }
+}
+
+/** A bordered box the card sits inside (gives it a sensible width). */
+function Frame(props: { children: JSX.Element }) {
+  return <div style={{ 'max-width': '420px' }}>{props.children}</div>;
+}
+
+const CONTENT_SNIPPET = `<!-- kai-card is the chrome/container. Slot in plain content — not interactive controls.
+     For data-driven interactive cards use the typed cards instead (see below). -->
+<kai-card heading="Workspace summary" description="Generated just now.">
+  <p>Your repository has 3 open pull requests and 12 passing checks.</p>
+</kai-card>
+
+<script type="module">
+  import '@kitn.ai/ui/elements'; // registers the custom elements
+</script>`;
+
+const MEDIA_SNIPPET = `<kai-card heading="Quarterly report" description="Generated just now.">
+  <img slot="media" src="/preview.png" alt="Report preview" />
+  <p>Your Q2 numbers are ready to review.</p>
+</kai-card>`;
+
+const ERROR_SNIPPET = `<!-- The one consistent inline error every card uses. -->
+<kai-card heading="Share your feedback" error-message="This card couldn't be displayed."></kai-card>`;
+
+const meta = {
+  title: 'Generative UI/Cards/kai-card',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-card'),
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: specDescription('kai-card', [
+        '`<kai-card>` is the shared, presentational **card chrome** every native generative-UI card composes from: an optional **media** region (`slot="media"`), a **heading** + **description**, a **body** (default slot), an **actions** footer (`slot="actions"`), and one consistent inline **error** state (`error-message`).',
+        '**Chrome only — it emits no events and reads no context.** Raw light-DOM content slotted into `kai-card` (such as plain `<button>` elements) is unstyled because light DOM cannot reach shadow CSS. The cards that compose it own the Card-contract interaction.',
+        '**For interactive, data-driven cards use the typed cards:** `<kai-confirm>` (approval actions — see that story for the canonical data-in → event-out example), `<kai-form>` (input/submit), `<kai-choice>` (single-select), `<kai-tasks>` (progress), `<kai-link-preview>` (rich link), `<kai-embed>` (media). Use `kai-card` only as a **plain themed surface** for presentational content.',
+        "**How to use as a surface:** register once with `import '@kitn.ai/ui/elements'`, set `heading`/`description` attributes, drop body markup in the default slot, and optionally a media region in `slot=\"media\"`. Set `error-message` to render the standard inline error (it replaces the body/actions).",
+        'See the **Code** tab for HTML usage.',
+      ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** `kai-card` as a plain themed surface: heading + description + slotted text content. This is the correct use of `kai-card` — presentational chrome around passive content. For interactive cards (actions, forms, choices) use the typed cards such as `kai-confirm`. */
+export const ContentSurface: Story = {
+  name: 'Content surface',
+  render: () => (
+    <Frame>
+      <kai-card heading="Workspace summary" description="Generated just now.">
+        <p style={{ margin: 0 }}>Your repository has 3 open pull requests and 12 passing checks.</p>
+      </kai-card>
+    </Frame>
+  ),
+  parameters: { docs: { source: { code: CONTENT_SNIPPET, language: 'html' } } },
+};
+
+/** An image media region above the heading. */
+export const WithMedia: Story = {
+  render: () => (
+    <Frame>
+      <kai-card heading="Quarterly report" description="Generated just now.">
+        <div
+          slot="media"
+          style={{
+            height: '120px',
+            display: 'grid',
+            'place-items': 'center',
+            background: 'var(--color-muted, #f4f4f5)',
+            color: 'var(--color-muted-foreground, #71717a)',
+            'font-size': '13px',
+          }}
+        >
+          media slot
+        </div>
+        <p style={{ margin: 0 }}>Your Q2 numbers are ready to review.</p>
+      </kai-card>
+    </Frame>
+  ),
+  parameters: { docs: { source: { code: MEDIA_SNIPPET, language: 'html' } } },
+};
+
+/** The standard inline error state (replaces the body/actions). */
+export const ErrorState: Story = {
+  render: () => (
+    <Frame>
+      <kai-card
+        heading="Share your feedback"
+        error-message="This card couldn't be displayed."
+      />
+    </Frame>
+  ),
+  parameters: { docs: { source: { code: ERROR_SNIPPET, language: 'html' } } },
+};

package/src/elements/card.tsx

@@ -0,0 +1,40 @@
+import { defineWebComponent } from './define';
+import { Card } from '../components/card';
+
+interface Props extends Record<string, unknown> {
+  /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
+  heading?: string;
+  /** Supporting text under the heading. Attribute: `description`. */
+  description?: string;
+  /** When set, the card renders its inline error state instead of the body.
+   *  Attribute: `error-message`. */
+  errorMessage?: string;
+  /** Compact spacing for dense lists. Attribute: `dense`. */
+  dense?: boolean;
+}
+
+/**
+ * `<kai-card>` — the shared, presentational card chrome every native card composes
+ * from: an optional media region (`slot="media"`), a heading + description, a body
+ * (default slot), an actions footer (`slot="actions"`), and one consistent inline
+ * **error** state (`error-message`). It emits **no** events and reads no context —
+ * it is chrome only; the cards that compose it (e.g. `<kai-form>`) own the contract
+ * interaction. Isolated in Shadow DOM; theme-aware via the shared kit tokens.
+ */
+defineWebComponent<Props>('kai-card', {
+  heading: undefined,
+  description: undefined,
+  errorMessage: undefined,
+  dense: false,
+}, (props, { flag }) => (
+  <Card
+    heading={props.heading}
+    description={props.description}
+    errorMessage={props.errorMessage}
+    dense={flag('dense')}
+    media={<slot name="media" />}
+    actions={<slot name="actions" />}
+  >
+    <slot />
+  </Card>
+));

package/src/elements/cards.stories.tsx

@@ -0,0 +1,59 @@
+// src/elements/cards.stories.tsx
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal, onMount } from 'solid-js';
+import './register'; // registers all kai-* incl. kai-cards
+import type { CardEnvelope, CardEvent } from '../primitives/card-contract';
+
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements { 'kai-cards': JSX.HTMLAttributes<HTMLElement>; }
+  }
+}
+
+const CARDS: CardEnvelope[] = [
+  { type: 'confirm', id: 'deploy', title: 'Deploy to production?',
+    data: { body: 'Apply 3 migrations and deploy?', tone: 'warning',
+      actions: [{ id: 'go', label: 'Deploy', style: 'primary', default: true }, { id: 'no', label: 'Cancel' }] } },
+  { type: 'tasks', id: 'plan', title: 'Pick the steps',
+    data: { tasks: [{ id: 'a', label: 'Run tests', checked: true }, { id: 'b', label: 'Tag release' }], confirmLabel: 'Run selected' } },
+  { type: 'choice', id: 'plan-pick', title: 'Choose a plan',
+    data: { prompt: 'Which plan fits your team?', options: [
+      { id: 'free', label: 'Free', meta: '$0' },
+      { id: 'pro', label: 'Pro', meta: '$12/seat', recommended: true, payload: { plan: 'pro' } },
+    ] } },
+  { type: 'link', id: 'doc', data: { url: 'https://kitn.dev', title: 'kitn.dev', description: 'Generative UI cards', domain: 'kitn.dev' } },
+];
+
+/** A host renders a stream of envelopes via <kai-cards> and handles events via `.policy`. */
+function Demo() {
+  let el: HTMLElement | undefined;
+  const [log, setLog] = createSignal<string[]>([]);
+  onMount(() => {
+    if (!el) return;
+    (el as unknown as { cards: CardEnvelope[] }).cards = CARDS;
+    (el as unknown as { policy: unknown }).policy = {
+      onAction: (id: string, action: string) => setLog((l) => [`action: ${id} → ${action}`, ...l]),
+      onSubmit: (id: string, data: unknown) => setLog((l) => [`submit: ${id} → ${JSON.stringify(data)}`, ...l]),
+      onOpen: (url: string) => setLog((l) => [`open: ${url}`, ...l]),
+      onError: (id: string, msg: string) => setLog((l) => [`error: ${id} → ${msg}`, ...l]),
+    };
+  });
+  return (
+    <div style={{ display: 'grid', 'grid-template-columns': '1fr 18rem', gap: '1rem', padding: '1rem' }}>
+      <kai-cards ref={(e) => (el = e as HTMLElement)} />
+      <pre style={{ 'font-size': '12px', background: '#f4f4f5', padding: '8px', 'border-radius': '6px', 'min-height': '6rem' }}>
+        {log().join('\n') || 'events appear here…'}
+      </pre>
+    </div>
+  );
+}
+
+const meta = {
+  title: 'Generative UI/SDK/kai-cards',
+  parameters: { layout: 'fullscreen' },
+} satisfies Meta;
+export default meta;
+type Story = StoryObj;
+
+export const CardStream: Story = { render: () => <Demo /> };