@kitn.ai/ui 0.17.0 → 0.18.1

package/src/state/stream.ts

@@ -0,0 +1,92 @@
+// src/state/stream.ts
+import type { ChatMessage } from '../elements/chat-types';
+import type { ToolPart } from '../components/tool-types';
+
+/** The one universal contract: a functional-updater setter (React setState shape). */
+export type SetMessages = (updater: (prev: ChatMessage[]) => ChatMessage[]) => void;
+
+/** A fluent builder for one in-flight assistant message. Owns no state. */
+export interface AssistantStream {
+  readonly id: string;
+  appendText(delta: string): AssistantStream;
+  setText(content: string): AssistantStream;
+  appendReasoning(delta: string, label?: string): AssistantStream;
+  setReasoning(text: string, label?: string): AssistantStream;
+  upsertTool(tool: ToolPart): AssistantStream;
+  updateTool(toolCallId: string, patch: Partial<ToolPart>): AssistantStream;
+  patch(patch: Partial<ChatMessage>): AssistantStream;
+  done(final?: Partial<ChatMessage>): void;
+  abort(reason?: string): void;
+}
+
+function newId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') return crypto.randomUUID();
+  return 'kai-' + Math.random().toString(36).slice(2);
+}
+
+/** Start an assistant message and drive it through `set`. New refs on every mutation. */
+export function createAssistantStream(set: SetMessages, init: Partial<ChatMessage> = {}): AssistantStream {
+  const id = init.id ?? newId();
+  const seed: ChatMessage = { id, role: 'assistant', content: '', ...init };
+  set((prev) => [...prev, seed]);
+
+  const mutate = (fn: (m: ChatMessage) => ChatMessage) =>
+    set((prev) => prev.map((m) => (m.id === id ? fn(m) : m)));
+
+  const stream: AssistantStream = {
+    id,
+    appendText(delta) { mutate((m) => ({ ...m, content: m.content + delta })); return stream; },
+    setText(content) { mutate((m) => ({ ...m, content })); return stream; },
+    appendReasoning(delta, label) {
+      mutate((m) => ({ ...m, reasoning: { text: (m.reasoning?.text ?? '') + delta, label: label ?? m.reasoning?.label } }));
+      return stream;
+    },
+    setReasoning(text, label) {
+      mutate((m) => ({ ...m, reasoning: { text, label: label ?? m.reasoning?.label } }));
+      return stream;
+    },
+    upsertTool(tool) {
+      mutate((m) => {
+        const tools = m.tools ? m.tools.slice() : [];
+        const i = tool.toolCallId != null
+          ? tools.findIndex((t) => t.toolCallId === tool.toolCallId)
+          : tools.findIndex((t) => t.type === tool.type);
+        if (i === -1) tools.push(tool); else tools[i] = tool;
+        return { ...m, tools };
+      });
+      return stream;
+    },
+    updateTool(toolCallId, patch) {
+      mutate((m) => ({ ...m, tools: (m.tools ?? []).map((t) => (t.toolCallId === toolCallId ? { ...t, ...patch } : t)) }));
+      return stream;
+    },
+    patch(patch) { mutate((m) => ({ ...m, ...patch })); return stream; },
+    done(final) { if (final) mutate((m) => ({ ...m, ...final })); },
+    abort(reason) {
+      if (reason) {
+        mutate((m) => ({ ...m, tools: (m.tools ?? []).map((t) => ({ ...t, state: 'output-error' as const, errorText: reason })) }));
+      } else {
+        set((prev) => prev.filter((m) => m.id !== id));
+      }
+    },
+  };
+  return stream;
+}
+
+/** Wrap a stream so `onSettle` fires on done/abort (used to toggle a `loading` flag).
+ *  Preserves the fluent chain by returning the wrapper from every mutator. */
+export function onStreamSettled(inner: AssistantStream, onSettle: () => void): AssistantStream {
+  const wrapper: AssistantStream = {
+    id: inner.id,
+    appendText(d) { inner.appendText(d); return wrapper; },
+    setText(c) { inner.setText(c); return wrapper; },
+    appendReasoning(d, l) { inner.appendReasoning(d, l); return wrapper; },
+    setReasoning(t, l) { inner.setReasoning(t, l); return wrapper; },
+    upsertTool(t) { inner.upsertTool(t); return wrapper; },
+    updateTool(tcId, p) { inner.updateTool(tcId, p); return wrapper; },
+    patch(p) { inner.patch(p); return wrapper; },
+    done(final) { inner.done(final); onSettle(); },
+    abort(reason) { inner.abort(reason); onSettle(); },
+  };
+  return wrapper;
+}

package/src/state/suggestions.ts

@@ -0,0 +1,9 @@
+/** Append a suggestion; no-op when already present. Returns a new array. */
+export function addSuggestion(suggestions: string[], s: string): string[] {
+  return suggestions.includes(s) ? suggestions.slice() : [...suggestions, s];
+}
+
+/** Remove a suggestion by value. */
+export function removeSuggestion(suggestions: string[], s: string): string[] {
+  return suggestions.filter((x) => x !== s);
+}

package/src/types.ts

@@ -35,6 +35,10 @@ export interface ConversationSummary {
   messageCount: number;
   lastMessageAt: string;
   updatedAt: string;
+  /** Right-aligned trailing text on the row — a count, status, or "days ago".
+   *  When omitted, a short relative time is auto-derived from `updatedAt`
+   *  (fallback `lastMessageAt`). */
+  trailing?: string;
 }
 
 export interface ConversationGroup {

package/src/ui/agent-card.tsx

@@ -0,0 +1,218 @@
+import { type JSX, Show, splitProps } from 'solid-js';
+import { Bell, MoreHorizontal } from 'lucide-solid';
+import { cn } from '../utils/cn';
+
+/** The run state of an agent, mapped to the kit's tool / status hues.
+ *  - `working` (blue) the agent is actively running.
+ *  - `idle` (muted) waiting, no current activity.
+ *  - `done` (green) finished its turn.
+ *  - `error` (red) failed.
+ *  - `blocked` (amber) stalled, usually waiting on something. */
+export type AgentStatusTone = 'working' | 'idle' | 'done' | 'error' | 'blocked';
+
+export interface AgentStatus {
+  /** Which hue the status dot takes. */
+  tone: AgentStatusTone;
+  /** Optional short label rendered next to the dot (e.g. "Working", "Blocked on you"). */
+  label?: string;
+  /** Animate the dot with a ping ring (off under prefers-reduced-motion). */
+  pulse?: boolean;
+}
+
+export interface AgentCardProps {
+  /** @deprecated No longer rendered. Kept for back-compat with existing callers. */
+  leading?: JSX.Element;
+  /** The agent's name. The primary label. */
+  name: string;
+  /** @deprecated No longer rendered. Kept for back-compat with existing callers. */
+  subtitle?: string;
+  /** @deprecated No longer rendered. Kept for back-compat with existing callers. */
+  lastLine?: string;
+  /** Run status: a tone-colored dot, an optional small label, optionally pulsing. */
+  status: AgentStatus;
+  /** Raise a prominent "needs you" pill plus a glowing amber edge. The
+   *  attention-routing signal that pulls focus to this agent. */
+  needsAttention?: boolean;
+  /** Selected / focused state. Highlighted border and surface. */
+  active?: boolean;
+  /** Promote this agent to focus. Fires on click and on Enter / Space. */
+  onActivate?: () => void;
+  /** Alias for {@link AgentCardProps.onActivate}. Both fire if both are set. */
+  onClick?: () => void;
+  /** Show a trailing "..." overflow button and fire this on click. The consumer
+   *  wires the actual menu; the card only surfaces the affordance. Click is
+   *  stopped from also activating the card. */
+  onMenu?: (e: MouseEvent) => void;
+  /** Extra classes merged over the card. */
+  class?: string;
+}
+
+/** tone -> dot background utility (the kit's tool hues + muted for idle). */
+const TONE_DOT: Record<AgentStatusTone, string> = {
+  working: 'bg-tool-blue',
+  idle: 'bg-muted-foreground',
+  done: 'bg-tool-green',
+  error: 'bg-tool-red',
+  blocked: 'bg-tool-amber',
+};
+
+/** tone -> matching text color for the inline status label. */
+const TONE_TEXT: Record<AgentStatusTone, string> = {
+  working: 'text-tool-blue',
+  idle: 'text-muted-foreground',
+  done: 'text-tool-green',
+  error: 'text-tool-red',
+  blocked: 'text-tool-amber',
+};
+
+/** Default accessible name per tone, used when no `status.label` is given so the
+ *  state is still announced even when the dot reads as decorative. */
+const TONE_LABEL: Record<AgentStatusTone, string> = {
+  working: 'Working',
+  idle: 'Idle',
+  done: 'Done',
+  error: 'Error',
+  blocked: 'Blocked',
+};
+
+/**
+ * AgentCard - the compact representation of one agent in a multi-agent workspace.
+ *
+ * In a focus + periphery layout the agents you are not focused on collapse to these
+ * glanceable cards, arranged as a narrow side RAIL or a wide LIST. The card stays
+ * deliberately minimal: the agent name, a tone-colored status dot, a "needs you"
+ * affordance when the agent wants your attention, and a trailing "..." overflow
+ * button for per-agent actions. Clicking the card promotes the agent back to focus.
+ *
+ * It is `w-full` and lets the name truncate, so the same component works in both a
+ * narrow rail and a wide list without changes - the content adapts to the box.
+ *
+ * Status maps to the kit's tool hues so it reads in light and dark from tokens alone:
+ * working = blue, idle = muted, done = green, error = red, blocked = amber. Setting
+ * `needsAttention` raises an amber "Needs you" pill and a glowing amber ring so the
+ * card jumps out of the periphery - the attention-routing signal.
+ */
+export function AgentCard(props: AgentCardProps) {
+  const [local] = splitProps(props, [
+    'name',
+    'status',
+    'needsAttention',
+    'active',
+    'onActivate',
+    'onClick',
+    'onMenu',
+    'class',
+    // leading/subtitle/lastLine are accepted but no longer rendered (back-compat).
+    'leading',
+    'subtitle',
+    'lastLine',
+  ]);
+
+  const tone = (): AgentStatusTone => local.status.tone;
+  const activate = () => {
+    local.onActivate?.();
+    local.onClick?.();
+  };
+
+  return (
+    // A plain container (no interactive role): the agent name below is the real
+    // <button> activator, and the kebab is a separate sibling <button>, so neither
+    // interactive control is nested inside the other.
+    <div
+      data-active={local.active ? '' : undefined}
+      data-needs-attention={local.needsAttention ? '' : undefined}
+      class={cn(
+        'group relative flex w-full cursor-pointer items-center gap-3 rounded-lg border px-3 py-2.5 text-left',
+        'transition-[background-color,border-color,box-shadow]',
+        local.active
+          ? 'border-primary bg-accent'
+          : 'border-border bg-surface hover:bg-accent',
+        // The attention edge: a glowing amber ring + tinted border. Stacks over the
+        // active/idle surface so a focused agent can still flag that it needs you.
+        local.needsAttention && 'border-tool-amber/50 ring-2 ring-inset ring-tool-amber/60',
+        local.class,
+      )}
+    >
+      {/* Status indicator leads, immediately before the name: [● label?] Name. */}
+      <span
+        class="inline-flex shrink-0 items-center gap-1.5"
+        role="status"
+        aria-label={local.status.label ?? TONE_LABEL[tone()]}
+      >
+        <span class="relative inline-flex">
+          <Show when={local.status.pulse}>
+            <span
+              aria-hidden="true"
+              class={cn(
+                'absolute inline-flex h-full w-full animate-ping rounded-full opacity-75 motion-reduce:hidden',
+                TONE_DOT[tone()],
+              )}
+            />
+          </Show>
+          <span
+            aria-hidden="true"
+            part="status"
+            class={cn('relative inline-block size-2 rounded-full', TONE_DOT[tone()])}
+          />
+        </span>
+        <Show when={local.status.label}>
+          <span class={cn('text-[11px] font-medium leading-none', TONE_TEXT[tone()])}>
+            {local.status.label}
+          </span>
+        </Show>
+      </span>
+
+      {/* The agent name is the card's primary action: a real <button> whose inset
+          ::before overlay stretches the click target over the whole card, so a click
+          anywhere promotes the agent. Being a real button it is natively focusable and
+          activates on Enter / Space, so no manual key handling is needed. The overlay
+          also carries the card's focus ring (rounded to match), keeping the focused
+          card visually identical to before. */}
+      <button
+        type="button"
+        onClick={activate}
+        aria-current={local.active ? 'true' : undefined}
+        class={cn(
+          'min-w-0 flex-1 text-left outline-none',
+          "before:absolute before:inset-0 before:rounded-lg before:content-['']",
+          'focus-visible:before:ring-2 focus-visible:before:ring-inset focus-visible:before:ring-ring',
+        )}
+      >
+        <span class="block truncate text-sm font-medium leading-tight text-foreground">
+          {local.name}
+        </span>
+      </button>
+
+      <span class="flex shrink-0 items-center gap-2">
+        <Show when={local.needsAttention}>
+          <span class="inline-flex items-center gap-1 rounded-full bg-tool-amber/15 px-2 py-0.5 text-[11px] font-medium text-tool-amber">
+            <Bell class="size-3" aria-hidden="true" />
+            Needs you
+          </span>
+        </Show>
+
+        <Show when={local.onMenu}>
+          <button
+            type="button"
+            part="menu"
+            aria-label="More"
+            onClick={(e) => {
+              // The kebab sits above the name button's stretch overlay (relative z-10),
+              // so it opens its menu without activating the card; stop propagation too.
+              e.stopPropagation();
+              local.onMenu?.(e);
+            }}
+            class={cn(
+              'relative z-10 inline-flex size-7 shrink-0 items-center justify-center rounded-md',
+              'text-muted-foreground outline-none transition-colors',
+              'hover:bg-surface-sunken hover:text-foreground',
+              'focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring',
+            )}
+          >
+            <MoreHorizontal class="size-4" aria-hidden="true" />
+          </button>
+        </Show>
+      </span>
+    </div>
+  );
+}

package/src/ui/button.tsx

@@ -3,12 +3,15 @@ import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '../utils/cn';
 
 const buttonVariants = cva(
-  'inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50',
+  // No justify-* here — the `align` variant owns content justification so it can
+  // be overridden (e.g. a full-width, left-aligned block button).
+  'inline-flex items-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50',
   {
     variants: {
       variant: {
         default: 'bg-primary text-primary-foreground hover:bg-primary/90',
         ghost: 'hover:bg-muted text-foreground',
+        subtle: 'text-muted-foreground hover:bg-accent hover:text-foreground',
         outline: 'bg-muted/50 text-foreground hover:bg-muted',
         destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
       },
@@ -19,17 +22,25 @@ const buttonVariants = cva(
         icon: 'h-9 w-9',
         'icon-sm': 'h-7 w-7',
       },
+      align: {
+        start: 'justify-start',
+        center: 'justify-center',
+        end: 'justify-end',
+      },
     },
-    defaultVariants: { variant: 'default', size: 'md' },
+    defaultVariants: { variant: 'default', size: 'md', align: 'center' },
   }
 );
 
-export interface ButtonProps extends JSX.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {}
+export interface ButtonProps extends JSX.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
+  /** Stretch to the full width of the container (a block button). */
+  full?: boolean;
+}
 
 export function Button(props: ButtonProps) {
-  const [local, rest] = splitProps(props, ['variant', 'size', 'class', 'children']);
+  const [local, rest] = splitProps(props, ['variant', 'size', 'align', 'full', 'class', 'children']);
   return (
-    <button class={cn(buttonVariants({ variant: local.variant, size: local.size }), local.class)} {...rest}>
+    <button class={cn(buttonVariants({ variant: local.variant, size: local.size, align: local.align }), local.full && 'w-full', local.class)} {...rest}>
       {local.children}
     </button>
   );

package/src/ui/card.tsx

@@ -0,0 +1,245 @@
+import { type JSX, Show, splitProps, mergeProps, createSignal, createUniqueId } from 'solid-js';
+import { Dynamic } from 'solid-js/web';
+import { cn } from '../utils/cn';
+import { X } from 'lucide-solid';
+
+export type CardAppearance = 'outlined' | 'filled' | 'plain' | 'accent';
+/** `vertical` (media on top), `horizontal` (media at the start), or `responsive`
+ *  (horizontal when the card's container is at least ~28rem wide, else vertical —
+ *  a CSS container query on the card's own width, NOT the viewport). */
+export type CardOrientation = 'vertical' | 'horizontal' | 'responsive';
+
+/** Surface treatment. `outlined` (default) = bordered card; `filled` = a raised
+ *  opaque surface; `plain` = no border/background (a padded region); `accent` =
+ *  the bold primary fill (announcements). */
+const APPEARANCE: Record<CardAppearance, string> = {
+  outlined: 'border border-border bg-card text-card-foreground kai-elevation-sm',
+  filled: 'border border-transparent bg-surface-strong text-card-foreground',
+  plain: 'border border-transparent bg-transparent',
+  accent: 'border border-transparent bg-primary text-primary-foreground',
+};
+
+export interface CardProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  /** Surface treatment: `outlined` | `filled` | `plain` | `accent`. */
+  appearance?: CardAppearance;
+  /** `vertical` (media on top) or `horizontal` (media at the start). */
+  orientation?: CardOrientation;
+  /** The card width below which a `responsive` card collapses to vertical and the
+   *  footer action cluster stacks. A CSS length (e.g. `'24rem'`); default `'28rem'`.
+   *  Container-query breakpoints can't be CSS variables, so this prop is baked into
+   *  a per-card `@container` rule. */
+  collapse?: string;
+  /** Tighter spacing for dense lists (shrinks `--kai-card-spacing`). */
+  dense?: boolean;
+
+  /** Full-bleed media region (image/video/illustration) at the top (vertical) or
+   *  start (horizontal). Clipped to the card's corners. */
+  media?: JSX.Element;
+  /** Header content (e.g. a title). Rendered above the body, padded. */
+  header?: JSX.Element;
+  /** An actions cluster pinned to the end of the header row. */
+  headerActions?: JSX.Element;
+  /** Footer content. Rendered below the body, padded. */
+  footer?: JSX.Element;
+  /** An actions cluster pinned to the end of the footer row. */
+  footerActions?: JSX.Element;
+  /** Whether the default slot (body) has content — the facade computes this so an
+   *  empty body region isn't rendered (an empty `<slot>` is always truthy). */
+  hasBody?: boolean;
+
+  /** Render a dismiss (×) that hides the card and calls `onDismiss`. Off by default. */
+  dismissible?: boolean;
+  onDismiss?: () => void;
+  /** Render the whole card as a link (`<a>`). Wins over `clickable`. */
+  href?: string;
+  target?: string;
+  rel?: string;
+  /** Make the whole card a `role="button"` with Enter/Space activation. A
+   *  clickable/href card must NOT also contain footer action buttons. */
+  clickable?: boolean;
+  onCardClick?: (event: MouseEvent | KeyboardEvent) => void;
+}
+
+/**
+ * `Card` — the kit's presentational card surface (the `<kai-card>` primitive),
+ * modeled on the WebAwesome card: ONE element whose flexibility comes from a few
+ * structural slots (`media`, `header` + actions, `footer` + actions; body is the
+ * default slot), `appearance` + `orientation` variants, `::part` styling, and a
+ * single `--kai-card-spacing` knob. The title/description are NOT slots — they are
+ * body/header content the consumer marks up, because a slot earns its place only
+ * where the shadow boundary blocks the consumer (a pinned media/footer region),
+ * not for a text node.
+ *
+ * Distinct from the generative-UI contract chrome in `../components/card.tsx`
+ * (which the Card Contract cards compose); this one is purely presentational.
+ *
+ * a11y: a `clickable`/`href` card MUST NOT also contain action buttons — that
+ * nests interactive controls inside a button/link.
+ */
+export function Card(props: CardProps): JSX.Element {
+  const merged = mergeProps(
+    { appearance: 'outlined' as CardAppearance, orientation: 'vertical' as CardOrientation, collapse: '28rem', dense: false },
+    props,
+  );
+  const [local, rest] = splitProps(merged, [
+    'appearance',
+    'orientation',
+    'collapse',
+    'dense',
+    'media',
+    'header',
+    'headerActions',
+    'footer',
+    'footerActions',
+    'hasBody',
+    'dismissible',
+    'onDismiss',
+    'href',
+    'target',
+    'rel',
+    'clickable',
+    'onCardClick',
+    'class',
+    'children',
+  ]);
+
+  const [open, setOpen] = createSignal(true);
+  const dismiss = (event: MouseEvent) => {
+    event.stopPropagation();
+    setOpen(false);
+    local.onDismiss?.();
+  };
+
+  const isLink = () => Boolean(local.href);
+  const isButton = () => !isLink() && Boolean(local.clickable);
+  const isInteractive = () => isLink() || isButton();
+
+  // The responsive layout is driven by a per-instance @container rule (a query on
+  // the card's OWN width, not the viewport) rather than fixed Tailwind classes, so
+  // the breakpoint is the configurable `collapse` prop. Base + query rules share a
+  // selector; the query (later) wins above the breakpoint. The card collapses to
+  // vertical (responsive orientation) and stacks its footer actions below `collapse`.
+  const COLLAPSE_RE = /^[\d.]+(px|rem|em|ch|vw|vh|%)$/;
+  const collapseAt = () => (COLLAPSE_RE.test(local.collapse) ? local.collapse : '28rem');
+  // Scope the injected <style> to THIS instance. The SolidJS Card renders in light
+  // DOM (the primitive story + autodocs page), where unscoped selectors are global
+  // and collide across instances (a horizontal card's `.kc-layout{flex-direction:row}`
+  // overrides a vertical one's, etc.). Prefixing every rule with a per-card class
+  // isolates each instance. Harmless inside the kai-card shadow root, where the
+  // boundary already scopes styles.
+  const scope = `kc-i-${createUniqueId()}`;
+  const styleText = () => {
+    const bp = collapseAt();
+    const horizontal = local.orientation === 'horizontal';
+    const responsive = local.orientation === 'responsive';
+    const s = `.${scope}`;
+    const base =
+      `${s} .kc-layout{display:flex;flex-direction:${horizontal ? 'row' : 'column'}}` +
+      `${s} .kc-media{overflow:hidden;${horizontal ? 'flex-shrink:0;align-self:stretch' : 'width:100%'}}` +
+      `${s} [part="footer"]{display:flex;flex-direction:column;gap:0.75rem}` +
+      `${s} .kc-actions{display:flex;flex-direction:column-reverse;align-items:stretch;gap:0.5rem}`;
+    const query =
+      `${s} [part="footer"]{flex-direction:row;align-items:center}` +
+      `${s} .kc-actions{flex-direction:row;align-items:center;margin-left:auto}` +
+      (responsive ? `${s} .kc-layout{flex-direction:row}${s} .kc-media{width:auto;flex-shrink:0;align-self:stretch}` : '');
+    return `${base}@container (min-width:${bp}){${query}}`;
+  };
+
+  const activate = (event: MouseEvent | KeyboardEvent) => local.onCardClick?.(event);
+  const onKeyDown = (event: KeyboardEvent) => {
+    if (!isButton()) return;
+    if (event.key === 'Enter' || event.key === ' ' || event.key === 'Spacebar') {
+      event.preventDefault();
+      activate(event);
+    }
+  };
+  const rel = () => local.rel ?? (local.target === '_blank' ? 'noopener noreferrer' : undefined);
+
+  const hasHeaderRow = () => Boolean(local.header) || Boolean(local.headerActions);
+  const hasFooterRow = () => Boolean(local.footer) || Boolean(local.footerActions);
+  const hasSections = () => hasHeaderRow() || local.hasBody || hasFooterRow();
+
+  // The padded header/body/footer column. Media sits outside it so it stays
+  // full-bleed (clipped to the card's corners by the root's overflow-hidden).
+  const sections = (
+    <div class="flex min-w-0 flex-1 flex-col" style={{ padding: 'var(--kai-card-spacing)', gap: 'var(--kai-card-spacing)' }}>
+      <Show when={hasHeaderRow()}>
+        <div part="header" class="flex items-start justify-between gap-3">
+          <Show when={local.header}>
+            <div class="min-w-0 flex-1">{local.header}</div>
+          </Show>
+          <Show when={local.headerActions}>
+            <div class="-mt-1 shrink-0">{local.headerActions}</div>
+          </Show>
+        </div>
+      </Show>
+      <Show when={local.hasBody}>
+        <div part="body" class="min-w-0 text-sm">{local.children}</div>
+      </Show>
+      <Show when={hasFooterRow()}>
+        {/* Footer + action cluster collapse to a stack below `collapse` (the injected
+            @container rule). The cluster is flex-col-REVERSE when stacked, so the
+            primary action (authored last → the row's right) rises to the TOP, and
+            items-stretch makes the buttons fill the width. No consumer work either way. */}
+        <div part="footer">
+          <Show when={local.footer}>
+            <div class="min-w-0 flex-1">{local.footer}</div>
+          </Show>
+          <Show when={local.footerActions}>
+            <div class="kc-actions">{local.footerActions}</div>
+          </Show>
+        </div>
+      </Show>
+    </div>
+  );
+
+  return (
+    <Show when={open()}>
+      <Dynamic
+        component={isLink() ? 'a' : 'div'}
+        part="card"
+        href={isLink() ? local.href : undefined}
+        target={isLink() ? local.target : undefined}
+        rel={isLink() ? rel() : undefined}
+        role={isButton() ? 'button' : undefined}
+        tabindex={isButton() ? 0 : undefined}
+        onClick={isInteractive() ? activate : undefined}
+        onKeyDown={isButton() ? onKeyDown : undefined}
+        style={{ '--kai-card-spacing': local.dense ? '0.875rem' : '1.25rem' }}
+        class={cn(
+          // @container: the card is a query container for its sections (responsive
+          // orientation + the footer action cluster collapse) keyed to its own width.
+          'relative block overflow-hidden rounded-xl no-underline @container',
+          // Per-instance scope so the injected <style> can't bleed across cards.
+          scope,
+          APPEARANCE[local.appearance],
+          isInteractive() &&
+            'cursor-pointer transition-colors hover:border-ring focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+          local.class,
+        )}
+        {...rest}
+      >
+        <Show when={local.dismissible}>
+          <button
+            type="button"
+            part="dismiss"
+            aria-label="Dismiss"
+            onClick={dismiss}
+            class="absolute right-2 top-2 z-10 shrink-0 rounded p-1 opacity-60 transition-opacity hover:opacity-100"
+          >
+            <X class="size-3.5" aria-hidden="true" />
+          </button>
+        </Show>
+
+        {/* Per-instance responsive rules; the breakpoint is the `collapse` prop. */}
+        <style>{styleText()}</style>
+        <div class="kc-layout">
+          <Show when={local.media}>
+            <div part="media" class="kc-media">{local.media}</div>
+          </Show>
+          <Show when={hasSections()}>{sections}</Show>
+        </div>
+      </Dynamic>
+    </Show>
+  );
+}