@kitn.ai/ui 0.20.1 → 0.22.0

package/src/elements/attachments.tsx

@@ -17,8 +17,10 @@ import {
 } from '../components/attachments';
 
 interface Props extends Record<string, unknown> {
-  /** The attachments to render. Set as a JS property (array). */
-  items: AttachmentData[];
+  /** The attachments to render. Omit (or pass an empty array) for the empty
+   *  state, which shows `emptyText` if set and nothing otherwise. 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. */
@@ -67,11 +69,11 @@ defineWebComponent<Props, Events>('kai-attachments', {
 
   return (
     <Show
-      when={props.items.length}
+      when={props.items?.length}
       fallback={<Show when={props.emptyText}><AttachmentEmpty>{props.emptyText}</AttachmentEmpty></Show>}
     >
       <Attachments variant={variant()}>
-        <For each={props.items}>
+        <For each={props.items ?? []}>
           {(item) => (
             <Attachment
               data={item}

package/src/elements/avatar.tsx

@@ -6,7 +6,7 @@ interface Props extends Record<string, unknown> {
   src?: string;
   /** Alt text for the image. Defaults to `fallback`. */
   alt?: string;
-  /** Short text shown when there's no image — usually initials (e.g. "JD", "AI"). */
+  /** Short text shown when there's no image, usually initials (e.g. "JD", "AI"). */
   fallback?: string;
   /** Size token: `sm` | `md` (default) | `lg`. */
   size?: 'sm' | 'md' | 'lg';

package/src/elements/button.tsx

@@ -2,9 +2,10 @@ import { Show } from 'solid-js';
 import { Button } from '../ui/button';
 import { renderIcon } from '../ui/icon';
 import { defineWebComponent } from './define';
+import { createSlotText } from './slot-text';
 
 interface Props extends Record<string, unknown> {
-  /** Visual style. `default` (filled), `subtle` (muted text, hover tint — the
+  /** Visual style. `default` (filled), `subtle` (muted text, hover tint, the
    *  toolbar icon look), `ghost` (transparent, hover fill), `outline`, or
    *  `destructive`. Defaults to `default`. */
   variant?: 'default' | 'subtle' | 'ghost' | 'outline' | 'destructive';
@@ -17,11 +18,16 @@ interface Props extends Record<string, unknown> {
   /** Trailing icon, after the label (e.g. `"chevron-down"` for a menu affordance). */
   iconTrailing?: string;
   /** Accessible name. REQUIRED for icon-only buttons (no visible text); ignored
-   *  when you slot visible text, which already names the button. */
+   *  when you slot visible text, which already names the button. An `aria-label`
+   *  on top of visible text REPLACES that name rather than adding to it, so a
+   *  button reading "Save" that answers to "Submit" is unusable by speech input
+   *  (WCAG 2.5.3, Label in Name). The visible text wins. An `icon` / `icon-sm`
+   *  size hides the slot, which makes the button icon-only whatever you slotted,
+   *  so `label` is what names it there. */
   label?: string;
   /** Disable the button (non-interactive, dimmed). */
   disabled?: boolean;
-  /** Stretch the button to the full width of its container (a block button) —
+  /** Stretch the button to the full width of its container (a block button),
    *  e.g. a card CTA or a stacked action. Attribute: `full`. */
   full?: boolean;
   /** Justify the button's content: `start`, `center` (default), or `end`.
@@ -71,6 +77,23 @@ defineWebComponent<Props, Events>('kai-button', {
   // `label` prop still names it for assistive tech).
   const iconOnly = () => props.size === 'icon' || props.size === 'icon-sm';
 
+  // Slotted text names the button by itself (name-from-contents reaches through
+  // the slot), so `label` must NOT be emitted on top of it: aria-label REPLACES
+  // the computed name, and a name that disagrees with the visible text locks
+  // speech-input users out of the control (WCAG 2.5.3). This is what the `label`
+  // doc has always promised, and what `kai-checkpoint` already does.
+  //
+  // `flatten` so a consumer who wraps <kai-button> in their own component and
+  // forwards a <slot> still counts as having visible text. Safe here because the
+  // default slot has no fallback content — see createSlotText.
+  const slotted = createSlotText({ flatten: true });
+
+  // The name to emit, or nothing. An `icon`/`icon-sm` size does not render the
+  // default slot at all, so whatever was slotted is INVISIBLE and `label` is the
+  // only name available — dropping it there would leave icon buttons nameless,
+  // which is the worse bug.
+  const ariaLabel = () => (!iconOnly() && slotted.hasText() ? undefined : props.label);
+
   // ── Imperative API (instance methods on the host) ──────────────────────────
   // The real <button> lives in the shadow root, so native focus()/blur()/click()
   // on the host hit the wrapper, not the control. Forward to the inner button.
@@ -82,7 +105,7 @@ defineWebComponent<Props, Events>('kai-button', {
       element.shadowRoot?.querySelector('button')?.focus(options),
     /** Blur the inner `<button>`. */
     blur: () => element.shadowRoot?.querySelector('button')?.blur(),
-    /** Programmatically activate the button — runs the same path as a user
+    /** Programmatically activate the button. Runs the same path as a user
      *  click and fires kai-click. Forwarding to the inner button means
      *  `disabled` is respected automatically. */
     click: () => element.shadowRoot?.querySelector('button')?.click(),
@@ -104,7 +127,7 @@ defineWebComponent<Props, Events>('kai-button', {
       full={flag('full') || !iconOnly()}
       type={props.type ?? 'button'}
       disabled={flag('disabled')}
-      aria-label={props.label}
+      aria-label={ariaLabel()}
       onClick={() => dispatch('kai-click')}
     >
       {/* Leading icon: a slotted SVG (slot="icon") wins — drop in any icon
@@ -115,7 +138,7 @@ defineWebComponent<Props, Events>('kai-button', {
         </Show>
       </slot>
       <Show when={!iconOnly()}>
-        <slot />
+        <slot ref={slotted.ref} />
       </Show>
       <Show when={props.iconTrailing && !iconOnly()}>
         {renderIcon(props.iconTrailing, { class: 'size-4 shrink-0 opacity-60', imgClass: 'size-4 shrink-0', spanClass: 'inline-flex size-4 shrink-0 items-center justify-center', ariaHidden: true })}

package/src/elements/card.tsx

@@ -7,8 +7,8 @@ interface Props extends Record<string, unknown> {
    *  Attribute: `appearance`. */
   appearance?: CardAppearance;
   /** `vertical` (default, media on top) | `horizontal` (media at the start) |
-   *  `responsive` (horizontal when the card's container is wide enough, else
-   *  vertical — a container query on the card's own width). Attribute: `orientation`. */
+   *  `responsive` (horizontal when the card's container is wide enough, else vertical,
+   *  via a container query on the card's own width). Attribute: `orientation`. */
   orientation?: CardOrientation;
   /** The card width below which a `responsive` card collapses to vertical and the
    *  footer actions stack. A CSS length; default `28rem`. Attribute: `collapse`. */

package/src/elements/cards.tsx

@@ -4,12 +4,15 @@
 // `kai-card` events through an optional `policy`. The raw events keep bubbling past
 // <kai-cards> (composed) so document-level listeners still work. Unknown types render
 // the Solid CardFallback inline and emit a contract `error`.
-import { For, Show, createEffect, createSignal, on, onCleanup, onMount, type JSX } from 'solid-js';
+import { For, Show, createEffect, createMemo, createSignal, on, onCleanup, onMount, type JSX } from 'solid-js';
 import { Dynamic } from 'solid-js/web';
 import { defineWebComponent } from './define';
 import type { CardEnvelope, CardEvent, CardPolicy, CardResolution } from '../primitives/card-contract';
 import { CARD_EVENT_NAME, emitCardEvent, routeCardEvent } from '../primitives/card-routing';
-import { mergeCardTags } from '../primitives/card-registry';
+import { BUILTIN_CARD_TAGS, mergeCardTags } from '../primitives/card-registry';
+import type { JsonSchema } from '../primitives/card-validate';
+import { cardValidationMessage, validateCardData, type CardValidationReport } from '../primitives/card-validate-cards';
+import { hasConsumerSchema } from '../components/card-renderer';
 import { CardFallback } from '../components/card-fallback';
 // Register the built-in child card elements so that importing <kai-cards> is self-contained.
 import './form';
@@ -26,18 +29,45 @@ interface Props extends Record<string, unknown> {
    *  Typed as a plain string map (not the `CardTagMap` alias) so the generated React
    *  wrapper inlines it instead of emitting an unresolved named type. */
   types?: Record<string, string>;
+  /** JSON Schemas for the card types this app renders, keyed by envelope type. The
+   *  companion of `types`, which says what DRAWS a card while this says what a
+   *  VALID one looks like. An OBJECT, so it is a JS property only: `el.schemas = {
+   *  'pricing-table': pricingSchema }`, never an attribute.
+   *  `createCardRegistry(...).validationSchemas` is exactly this shape.
+   *
+   *  Without it the kit validates its own seven built-ins and leaves your own card
+   *  type, the one your app actually cares about, as the only unchecked thing on
+   *  screen. A schema here WINS over a built-in of the same name, matching
+   *  `mergeCardTags`, where your entry is spread over ours.
+   *
+   *  Typed `Record<string, object>` rather than `Record<string, JsonSchema>`
+   *  deliberately: an imported `.json` schema widens `"type"` to `string`, and an
+   *  authored one carries `$schema`/`title`/`description`/`additionalProperties`,
+   *  so the tighter type would reject both of the normal ways to supply one. See
+   *  `CardSchemaMap` in components/card-renderer.tsx. */
+  schemas?: Record<string, object>;
   /** Optional CardPolicy handling child events. Property: `el.policy`. */
   policy?: CardPolicy;
+  /** Validate each envelope's `data` against the schema for its type before
+   *  rendering it, using a built-in's own schema or yours from `schemas`. Default
+   *  `true`; set `validate-cards="false"` (or `el.validateCards = false`) to opt
+   *  out. A hard failure (wrong type, a missing required field) renders a
+   *  diagnostic naming the field instead of the card; a soft failure (bounds)
+   *  renders the card unchanged. Both emit a contract `error` event. On in
+   *  production too: a model emitting a bad shape is a production failure mode,
+   *  so stripping the check there would hide it from exactly the person who needs
+   *  to see it. */
+  validateCards?: boolean;
 }
 
 /** Events fired by `<kai-cards>`. */
 interface Events {
-  /** A child card transitioned to a resolved/deferred state (an action was chosen,
-   *  a form/tasks submission landed, or it was dismissed) — re-emitted off the host
-   *  as a non-bubbling convenience event so a consumer can observe resolution
-   *  centrally without diffing the cards array. `detail` = `{ cardId, resolution }`.
-   *  (A `reopen` un-resolves a card and has no `CardResolution`, so it does NOT fire
-   *  this — observe reopen via the underlying bubbling `kai-card` event.) */
+  /** A child card transitioned to a resolved/deferred state (an action was chosen, a
+   *  form/tasks submission landed, or it was dismissed). Re-emitted off the host as
+   *  a non-bubbling convenience event so a consumer can observe resolution centrally
+   *  without diffing the cards array. `detail` = `{ cardId, resolution }`. (A
+   *  `reopen` un-resolves a card and has no `CardResolution`, so it does NOT fire
+   *  this; observe reopen via the underlying bubbling `kai-card` event.) */
   'kai-card-resolved': { cardId: string; resolution: CardResolution };
 }
 
@@ -57,9 +87,47 @@ function resolutionFromEvent(e: CardEvent): CardResolution | undefined {
   }
 }
 
-/** A single resolved child: a known kai-* tag (props set imperatively) or the fallback. */
-function CardSlot(props: { envelope: CardEnvelope; tag?: string; theme: string; emit: (e: CardEvent) => void }): JSX.Element {
+/** A single resolved child: a known kai-* tag (props set imperatively), a diagnostic
+ *  for data that cannot render, or the unknown-type fallback. */
+function CardSlot(props: {
+  envelope: CardEnvelope;
+  tag?: string;
+  theme: string;
+  validate: boolean;
+  schemas?: Record<string, object>;
+  emit: (e: CardEvent) => void;
+}): JSX.Element {
   let ref: HTMLElement | undefined;
+
+  // MIRRORS src/remote/provider-runtime.ts:139-147, the same way
+  // components/card-renderer.tsx does. The remote (iframe) transport has validated
+  // every incoming envelope since the contract landed and this native one did not,
+  // so the same bad payload was caught in one transport and rendered silently in the
+  // other. Two tiers: `hard` (nothing to render) replaces the card with a diagnostic
+  // naming the field, `soft` (bounds) renders the card untouched. Both emit `error`.
+  //
+  // OUR schema applies only to OUR element: `types` lets a consumer point a built-in
+  // card type at their own element (`el.types = { confirm: 'my-confirm-el' }`), and
+  // our schema describes our element's data, not theirs.
+  //
+  // A schema the CONSUMER registered through `el.schemas` runs the other way: they
+  // wrote it about their own card, and it is the shape their model was told to
+  // emit, so it applies whichever element draws the type. That is what validates a
+  // `pricing-table` — nobody's built-in, and until this prop existed the one card in
+  // the app that nothing checked. Same rule as components/card-renderer.tsx, which
+  // compares component identity where this compares tag identity; `hasConsumerSchema`
+  // is shared with it so the gate is spelled once.
+  const report = createMemo<CardValidationReport | null>(() => {
+    if (!props.validate) return null;
+    if (!hasConsumerSchema(props.schemas, props.envelope.type) && props.tag !== BUILTIN_CARD_TAGS[props.envelope.type]) {
+      return null;
+    }
+    // `schemas` is passed even when the gate opened on tag identity, so a consumer
+    // schema for a built-in type wins over ours — `schemaFor`'s rule.
+    return validateCardData(props.envelope.type, props.envelope.data, props.schemas as Record<string, JsonSchema> | undefined);
+  });
+  const invalid = () => report()?.tier === 'hard';
+
   // Set object/string props as DOM properties on the custom element (reactive).
   createEffect(() => {
     if (!ref) return;
@@ -79,19 +147,44 @@ function CardSlot(props: { envelope: CardEnvelope; tag?: string; theme: string;
       props.emit({ kind: 'error', cardId: props.envelope.id, message: `Unsupported card type: ${props.envelope.type}` });
     }
   });
+  // One `error` per distinct problem, both tiers. Keyed on the message, not on
+  // mount: a consumer re-assigning `el.cards` per stream chunk hands this a new
+  // envelope object each time, so an identity-triggered emit would fire per chunk.
+  let lastEmitted: string | null = null;
+  createEffect(() => {
+    const r = report();
+    if (!props.tag) return; // an unknown TYPE already reported itself in onMount
+    if (!r || r.ok) {
+      lastEmitted = null;
+      return;
+    }
+    const message = cardValidationMessage(r);
+    if (message === lastEmitted) return;
+    lastEmitted = message;
+    props.emit({ kind: 'error', cardId: props.envelope.id, message });
+  });
+
   return (
     <Show
       when={props.tag}
       fallback={<CardFallback type={props.envelope.type} cardId={props.envelope.id} />}
     >
-      {(tag) => <Dynamic component={tag()} ref={ref} />}
+      {(tag) => (
+        <Show
+          when={invalid()}
+          // SOFT and valid both take this branch: the card renders as it does today.
+          fallback={<Dynamic component={tag()} ref={ref} />}
+        >
+          <CardFallback type={props.envelope.type} cardId={props.envelope.id} reason={report()!.summary} />
+        </Show>
+      )}
     </Show>
   );
 }
 
 defineWebComponent<Props, Events>(
   'kai-cards',
-  { cards: undefined, types: undefined, policy: undefined },
+  { cards: undefined, types: undefined, schemas: undefined, policy: undefined, validateCards: true },
   (props, { element, dispatch, expose }) => {
     // Local working copy of the card list. The `cards` PROP still drives rendering
     // (a new prop array re-seeds this), but holding a settable copy lets the
@@ -134,11 +227,11 @@ defineWebComponent<Props, Events>(
       );
     expose({
       /** Programmatically resolve a child card by id: set that envelope's
-       *  `resolution` so the child re-renders into its read-only/resolved view — the
+       *  `resolution` so the child re-renders into its read-only/resolved view. The
        *  imperative twin of the consumer mutating the cards array. No-op for an
        *  unknown id. */
       resolve: (cardId: string, resolution: CardResolution) => resolveCard(cardId, resolution),
-      /** Collapse a card to its re-openable stub from the host side — convenience for
+      /** Collapse a card to its re-openable stub from the host side. Convenience for
        *  `resolve(cardId, { kind: 'dismissed' })`. */
       dismiss: (cardId: string) => resolveCard(cardId, { kind: 'dismissed' }),
       /** Return the live child element node for a card id (or null) so consumers can
@@ -161,6 +254,8 @@ defineWebComponent<Props, Events>(
               envelope={env}
               tag={tags()[env.type]}
               theme={theme()}
+              validate={props.validateCards !== false}
+              schemas={props.schemas}
               emit={(e) => emitCardEvent(element, e)}
             />
           )}

package/src/elements/chain-of-thought.tsx

@@ -19,23 +19,25 @@ type Step = ChainOfThoughtStepData;
 
 interface Props extends Record<string, unknown> {
   /** The reasoning steps. Set as a JS property. Compound sub-parts collapse to
-   *  this one data model (Route 1). Each `{ label, content?, id? }`. */
-  steps: Step[];
-  /** Open mode: `'multiple'` (default — any number of steps open at once) or
+   *  this one data model (Route 1). Each `{ label, content?, id? }`. Omit to
+   *  supply the steps as `<kai-step>` light-DOM children instead; when both are
+   *  present the property's steps come first. */
+  steps?: Step[];
+  /** Open mode: `'multiple'` (default, any number of steps open at once) or
    *  `'single'` (at most one open; opening a step closes the others). */
   type?: ChainOfThoughtType;
   /** Controlled open step key(s). When set, it WINS over user interaction (the
    *  consumer owns the open set). String in `single` mode, string[] in
    *  `multiple` mode. Set as a JS property. */
   value?: string | string[];
-  /** Uncontrolled INITIAL open step key(s) — seeds which steps render expanded.
-   *  Ignored once `value` is provided. Set as a JS property. */
+  /** Uncontrolled INITIAL open step key(s), seeding which steps render
+   *  expanded. Ignored once `value` is provided. Set as a JS property. */
   defaultValue?: string | string[];
 }
 
 /** Events fired by `<kai-chain-of-thought>`. */
 interface Events {
-  /** The open set changed — by user click OR an expand()/collapse()/toggle()
+  /** The open set changed, by user click OR an expand()/collapse()/toggle()
    *  call. `value` is a string in `single` mode, a string[] in `multiple` mode.
    *  (Maps Radix Accordion's onValueChange.) */
   'kai-value-change': { value: string | string[] };
@@ -99,7 +101,7 @@ defineWebComponent<Props, Events>('kai-chain-of-thought', {
   });
 
   // Prop steps first; declarative children appended after.
-  const allSteps = () => [...props.steps, ...slottedSteps()];
+  const allSteps = () => [...(props.steps ?? []), ...slottedSteps()];
 
   // ── Imperative API (instance methods on the host) ──────────────────────────
   // Pattern C: the Accordion component owns the open-set; the facade captures its
@@ -109,10 +111,12 @@ defineWebComponent<Props, Events>('kai-chain-of-thought', {
   // the only props are steps/type/value/defaultValue.
   let controller: ChainOfThoughtController | undefined;
   expose({
-    /** Open one step's detail by index, or — with no arg — ALL steps. In `single`
-     *  mode opening one step closes the others (expand-all keeps the last). */
+    /** Open one step's detail by index, or ALL steps when called with no arg. In
+     *  `single` mode opening one step closes the others (expand-all keeps the
+     *  last). */
     expand: (index?: number) => controller?.expand(index),
-    /** Close one step's detail by index, or — with no arg — ALL steps. */
+    /** Close one step's detail by index, or ALL steps when called with no
+     *  arg. */
     collapse: (index?: number) => controller?.collapse(index),
     /** Flip one step's open state by index. */
     toggle: (index?: number) => controller?.toggle(index),

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

@@ -5,10 +5,12 @@ import type { DropdownController } from '../ui/dropdown';
 import type { SearchFilters } from '../types';
 
 interface Props extends Record<string, unknown> {
-  /** Authors to offer as scope filters. Set as a JS property. */
-  availableAuthors: string[];
-  /** Tags to offer as scope filters. Set as a JS property. */
-  availableTags: string[];
+  /** Authors to offer as scope filters. Omit to drop the Authors section (for a
+   *  tag-only picker). Set as a JS property. */
+  availableAuthors?: string[];
+  /** Tags to offer as scope filters. Omit to drop the Tags section (for an
+   *  author-only picker). Set as a JS property. */
+  availableTags?: string[];
   /** The label shown on the trigger for the active scope. */
   currentLabel?: string;
   /** Drive/observe the dropdown's open state (Shoelace-style: settable + reflected
@@ -17,7 +19,7 @@ interface Props extends Record<string, unknown> {
   open?: boolean;
   /** Initial open state on mount (uncontrolled seed). */
   defaultOpen?: boolean;
-  /** Disable the trigger — click/keyboard and `show()` no longer open the dropdown. */
+  /** Disable the trigger: click/keyboard and `show()` no longer open the dropdown. */
   disabled?: boolean;
 }
 
@@ -52,8 +54,8 @@ defineWebComponent<Props, Events>('kai-scope-picker', {
   return (
     <ChatScopePicker
       currentLabel={props.currentLabel ?? 'All Content'}
-      availableAuthors={props.availableAuthors}
-      availableTags={props.availableTags}
+      availableAuthors={props.availableAuthors ?? []}
+      availableTags={props.availableTags ?? []}
       onScopeChange={(filters) => dispatch('kai-scope-change', { filters })}
       defaultOpen={flag('defaultOpen')}
       disabled={flag('disabled')}

package/src/elements/chat-types.ts

@@ -1,5 +1,11 @@
-import type { ToolPart } from '../components/tool-types';
+import type { ToolPart, RawOrigin } from '../components/tool-types';
 import type { AttachmentData } from '../components/attachment-types';
+import type { CardEnvelope } from '../primitives/card-contract';
+
+/** Re-exported so consumers of chat-types (and MessagePart) can keep using
+ *  RawOrigin unqualified. It is defined in components/tool-types.ts, not here,
+ *  to keep the components -> elements import direction one-way. */
+export type { RawOrigin };
 
 /** The five built-in action buttons (each carries its own curated icon + label). */
 export type ChatMessageAction = 'copy' | 'like' | 'dislike' | 'regenerate' | 'edit';
@@ -31,14 +37,61 @@ export interface AvatarData {
   alt?: string;
 }
 
+/** A citation the model produced. */
+export interface Source {
+  id?: string;
+  url?: string;
+  title?: string;
+  snippet?: string;
+  /** Citation marker number, when the model numbers its citations. */
+  index?: number;
+}
+
+/** The public name for the citation carried by a `source` part, and the argument
+ *  type of `AssistantStream.addSource`. The bare `Source` name is already taken
+ *  on the public entry by the citation-chip COMPONENT (`./components/source`),
+ *  so exporting this interface unaliased would be a duplicate identifier and the
+ *  type would be unnameable from `@kitn.ai/ui`. */
+export type MessageSource = Source;
+
+/** One ordered piece of message content. Closed union: extension happens at the CARD
+ *  layer via the card registry, not by adding variants here. */
+export type MessagePart =
+  | { type: 'text'; text: string; raw?: RawOrigin }
+  | {
+      type: 'reasoning';
+      text: string;
+      label?: string;
+      /** Provider block index. Keeps parallel reasoning blocks distinct. */
+      index?: number;
+      /** Which provider RESPONSE STREAM `index` was counted in. Anthropic restarts
+       *  content-block indices at 0 for every message, and a multi-round tool loop
+       *  folds several of those messages into ONE assistant turn, so `index` alone
+       *  is not unique within `parts`. Set by the wire adapter, one value per
+       *  `consumeModelStream` call. See `appendReasoningPart`. */
+      streamId?: string;
+      /** Load-bearing on the OpenAI wire, informational on the Anthropic one.
+       *  `toOpenAIMessages({ reasoning: 'include' })` REBUILDS a signed
+       *  `reasoning_details` entry from `text` plus this, because `raw` after a
+       *  streamed turn is a textless fragment: only the final frame carries the
+       *  signature and it has no text, and `appendReasoningPart` resolves `raw`
+       *  last-write-wins. `toAnthropicMessages` ignores this field and echoes
+       *  `raw.payload` verbatim — a thinking block rebuilt from text plus
+       *  signature is a hard 400. */
+      signature?: string;
+      raw?: RawOrigin;
+    }
+  | { type: 'tool'; tool: ToolPart; raw?: RawOrigin }
+  | { type: 'card'; envelope: CardEnvelope; raw?: RawOrigin }
+  | { type: 'source'; source: Source; raw?: RawOrigin }
+  | { type: 'file'; attachment: AttachmentData; raw?: RawOrigin };
+
 export interface ChatMessage {
   id: string;
   role: 'user' | 'assistant';
-  content: string;
-  reasoning?: { text: string; label?: string };
-  tools?: ToolPart[];
-  attachments?: AttachmentData[];
-  /** Action buttons under the message — built-in names and/or custom descriptors. */
+  /** The ONLY content channel. Ordered. */
+  parts: MessagePart[];
+  /** Action buttons under the message. Chrome, not content. */
   actions?: (ChatMessageAction | CustomAction)[];
   /** Optional speaker avatar shown to the left of the message column. */
   avatar?: AvatarData;

package/src/elements/chat-workspace.tsx

@@ -5,6 +5,8 @@ import { readSlots, WORKSPACE_SLOTS } from './slots';
 import { ChatThread, type ChatThreadContextUsage, type ChatThreadController } from '../components/chat-thread';
 import { ConversationList, CollapsedRail } from '../components/conversation-list';
 import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '../ui/resizable';
+import { cardComponentsFromTags } from './message';
+import { createMessagesGuard } from './validate-messages';
 import type { AttachmentData } from '../components/attachments';
 import type { TriggerDef } from '../components/composer';
 import type { ChatMessage } from './chat-types';
@@ -12,14 +14,25 @@ import type { ProseSize } from '../primitives/chat-config';
 import type { ModelOption, ConversationGroup, ConversationSummary } from '../types';
 
 interface Props extends Record<string, unknown> {
-  /** Pre-bucketed conversation groups for the sidebar. Set as a JS property. */
-  groups: ConversationGroup[];
-  /** Flat conversation list (auto-bucketed if `groups` is empty). Set as a JS property. */
-  conversations: ConversationSummary[];
+  /** The sidebar's section headers, rendered in array order. A group carries no
+   *  conversations of its own; it is matched against `conversations` by id, so
+   *  the two props are complementary rather than alternatives. Omit for an
+   *  ungrouped sidebar. Set as a JS property. */
+  groups?: ConversationGroup[];
+  /** Every conversation in the sidebar, flat. Each one is filed under the group
+   *  whose `id` equals its `groupId`; one with no `groupId`, or with a `groupId`
+   *  matching no entry in `groups`, falls into a trailing ungrouped section
+   *  (headerless when `compact`), so nothing you pass in is ever dropped. There is
+   *  no recency bucketing. Set as a JS property. Omit for an empty sidebar, or
+   *  when `no-conversations` replaces the built-in list with your own
+   *  `sidebar-header` content. */
+  conversations?: ConversationSummary[];
   /** Id of the open conversation, highlighted in the sidebar. */
   activeId?: string;
-  /** The active conversation's message thread, newest last. Set as a JS property. */
-  messages: ChatMessage[];
+  /** The active conversation's message thread, newest last. Set as a JS property
+   *  (`el.messages = [...]`); a NEW array reference per streaming chunk
+   *  re-renders (mutating in place does not). Omit for an empty thread. */
+  messages?: ChatMessage[];
   value?: string;
   placeholder?: string;
   loading?: boolean;
@@ -63,6 +76,26 @@ interface Props extends Record<string, unknown> {
    *  whole rail flex region (for apps that supply their own rail nav). Default
    *  false. Attribute: `no-conversations`. */
   noConversations?: boolean;
+  /** Optional card type -> custom-element tag overrides/additions for `card`
+   *  parts (merged over the built-ins). Property: `el.cardTypes`. Typed as a
+   *  plain string map (not the `CardTagMap` alias) so the generated React
+   *  wrapper inlines it instead of emitting an unresolved named type. */
+  cardTypes?: Record<string, string>;
+  /** JSON Schemas for the card types this app renders, keyed by envelope type. The
+   *  companion of `cardTypes`, which says what DRAWS a card while this says what a
+   *  VALID one looks like. An OBJECT, so it is a JS property only: `el.cardSchemas
+   *  = { 'pricing-table': pricingSchema }`, never an attribute.
+   *  `createCardRegistry(...).validationSchemas` is exactly this shape.
+   *
+   *  Without it the kit validates its own seven built-ins and leaves your own card
+   *  type, the one your app actually cares about, as the only unchecked thing on
+   *  screen. A schema here WINS over a built-in of the same name.
+   *
+   *  Typed `Record<string, object>` rather than `Record<string, JsonSchema>`
+   *  deliberately: an imported `.json` schema widens `"type"` to `string`, and an
+   *  authored one carries `$schema`/`title`/`description`/`additionalProperties`,
+   *  so the tighter type would reject both of the normal ways to supply one. */
+  cardSchemas?: Record<string, object>;
 }
 
 interface Events {
@@ -99,8 +132,14 @@ defineWebComponent<Props, Events>('kai-workspace', {
   search: false, voice: false, triggers: undefined, kindIcons: undefined,
   sidebarWidth: 26, sidebarMinWidth: 240, sidebarMaxWidth: 420,
   sidebarCollapsed: undefined, defaultSidebarCollapsed: undefined, collapseBelow: undefined, compact: undefined,
-  noConversations: undefined,
+  noConversations: undefined, cardTypes: undefined, cardSchemas: undefined,
 }, (props, { dispatch, flag, expose, element }) => {
+  // `messages` is an untyped boundary: a consumer can hand it anything at
+  // runtime (a pre-0.20.0 `{ id, role, content }` array, in particular). Skip
+  // the invalid entries rather than let `groupMessageParts` throw deep inside a
+  // render pass, which would blank the whole workspace instead of one message.
+  const validMessages = createMessagesGuard('kai-workspace');
+
   // Which injection slots the consumer has filled. A bare <slot> is always a
   // truthy JSX node, so we render each region wrapper ONLY when readSlots reports
   // projected light-DOM content (re-read on childList mutation).
@@ -180,7 +219,7 @@ defineWebComponent<Props, Events>('kai-workspace', {
   // own state (e.g. an uncontrolled draft) survives the collapse/expand.
   const threadEl = (
     <ChatThread
-      messages={props.messages} value={props.value as string | undefined} placeholder={props.placeholder as string}
+      messages={validMessages(props.messages)} value={props.value as string | undefined} placeholder={props.placeholder as string}
       loading={flag('loading')} suggestions={props.suggestions as string[] | undefined}
       suggestionMode={props.suggestionMode as 'submit' | 'fill'} proseSize={props.proseSize as ProseSize}
       codeTheme={props.codeTheme as string} codeHighlight={flag('codeHighlight')}
@@ -189,6 +228,8 @@ defineWebComponent<Props, Events>('kai-workspace', {
       scrollButton={props.scrollButton !== false} search={flag('search')} voice={flag('voice')}
       triggers={props.triggers as TriggerDef[] | undefined}
       kindIcons={props.kindIcons as Record<string, string> | undefined}
+      cardTypes={cardComponentsFromTags(props.cardTypes as Record<string, string> | undefined, (props as { theme?: string }).theme)}
+      cardSchemas={props.cardSchemas as Record<string, object> | undefined}
       onValueChange={(value) => dispatch('kai-value-change', { value })}
       onSubmit={(detail) => dispatch('kai-submit', detail)}
       onSuggestionClick={(value) => dispatch('kai-suggestion-click', { value })}
@@ -253,7 +294,7 @@ defineWebComponent<Props, Events>('kai-workspace', {
                 <div class="min-h-0 flex-1">
                   <ConversationList
                     class="bg-transparent"
-                    groups={props.groups} conversations={props.conversations} activeId={props.activeId as string | undefined}
+                    groups={props.groups ?? []} conversations={props.conversations ?? []} activeId={props.activeId as string | undefined}
                     compact={flag('compact')}
                     onSelect={(id) => dispatch('kai-conversation-select', { id })}
                     onNewChat={() => dispatch('kai-new-chat', {})}