@kitn.ai/ui 0.20.0 → 0.21.0

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', {})}

package/src/elements/chat.tsx

@@ -2,7 +2,10 @@ import { createEffect, createSignal, onCleanup, onMount } from 'solid-js';
 import { defineWebComponent } from './define';
 import { CHAT_SLOTS, readSlots } from './slots';
 import { ChatThread, type ChatThreadProps, type ChatThreadContextUsage, type ChatThreadController } from '../components/chat-thread';
+import { cardComponentsFromTags } from './message';
+import { createMessagesGuard } from './validate-messages';
 import type { AttachmentData } from '../components/attachments';
+import type { ChatMessage } from './chat-types';
 import type { TriggerDef } from '../components/composer';
 import type { ComposerDoc } from '../primitives/composer-model';
 import type { ProseSize } from '../primitives/chat-config';
@@ -10,7 +13,38 @@ import type { ModelOption } from '../types';
 
 type Props = Omit<ChatThreadProps,
   'class' | 'onValueChange' | 'onSubmit' | 'onAttachmentsChange' | 'onSuggestionClick' | 'onModelChange'
-  | 'onMessageAction' | 'onSearch' | 'onVoice' | 'controllerRef'> & Record<string, unknown>;
+  | 'onMessageAction' | 'onSearch' | 'onVoice' | 'controllerRef' | 'cardTypes' | 'cardSchemas' | 'messages'> & Record<string, unknown> & {
+    /** The full message thread to render, newest last. Each entry carries its
+     *  role, ordered `parts`, and optional actions/avatar/feedback. 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.
+     *
+     *  Re-declared here (rather than inherited from `ChatThreadProps`) because
+     *  the ELEMENT registers a `[]` default and renders the empty state without
+     *  it, while the SolidJS `<ChatThread>` component still requires it. The
+     *  facade hands it a validated array either way. Matches `<kai-thread>`. */
+    messages?: ChatMessage[];
+    /** 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 {
   /** User submitted a message. */
@@ -40,8 +74,14 @@ defineWebComponent<Props, Events>('kai-chat', {
   codeTheme: 'github-dark-dimmed', codeHighlight: true, chatTitle: undefined,
   models: undefined, currentModel: undefined, context: undefined, scrollButton: true,
   search: false, voice: false, triggers: undefined, kindIcons: undefined,
-  actionsReveal: 'always',
+  actionsReveal: 'always', cardTypes: undefined, cardSchemas: undefined,
 }, (props, { dispatch, flag, element, expose }) => {
+  // `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 chat instead of one message.
+  const validMessages = createMessagesGuard('kai-chat');
+
   // Slot detection is driven by the CHAT_SLOTS registry (single source of truth)
   // so slot names never drift between the view, the facade, and the docs.
   const [slots, setSlots] = createSignal<Record<string, boolean>>({});
@@ -62,16 +102,35 @@ defineWebComponent<Props, Events>('kai-chat', {
   // (focus the composer, clear it, send programmatically, scroll the thread).
   let controller: ChatThreadController | undefined;
   expose({
+    /** Focus the composer, meaning the contenteditable (or textarea) inside the
+     *  shadow root. A native `focus()` on the host lands on the host itself and
+     *  never reaches it, so this is the only way to focus the input
+     *  programmatically. */
     focus: (options?: FocusOptions) => controller?.focus(options),
+    /** Blur whatever currently holds focus inside the shadow root. The companion
+     *  to `focus()`, for the same reason: a native `blur()` on the host misses
+     *  the real focus target. */
     blur: () => (element.shadowRoot?.activeElement as HTMLElement | null)?.blur(),
+    /** Empty the COMPOSER: drops the draft text and every staged attachment, then
+     *  fires `kai-value-change` with `''`. It does NOT touch the thread. `messages`
+     *  is the consumer's own state, so clearing history stays the consumer's call. */
     clear: () => controller?.clear(),
+    /** Submit whatever the composer currently holds, on the same path as Enter or
+     *  the send button: fires `kai-submit` with that value plus the staged
+     *  attachments, then drops the attachments. It takes no argument, so to send
+     *  text the user never typed, set `el.value` first. There is no empty-check,
+     *  so an empty composer still fires. The draft is cleared afterwards only when
+     *  `value` is uncontrolled; a controlled host owns its value and clears it
+     *  itself. Named `send`, not `submit`, to match the shared vocabulary. */
     send: () => controller?.send(),
+    /** Scroll the message viewport to the newest message. Defaults to `'smooth'`;
+     *  pass `'instant'` to jump without animating. */
     scrollToBottom: (behavior?: ScrollBehavior) => controller?.scrollToBottom(behavior),
   });
 
   return (
   <ChatThread
-    messages={props.messages} value={props.value as string | ComposerDoc | undefined} placeholder={props.placeholder as string}
+    messages={validMessages(props.messages)} value={props.value as string | ComposerDoc | undefined} placeholder={props.placeholder as string}
     loading={flag('loading')} suggestions={props.suggestions as string[] | undefined}
     suggestionMode={props.suggestionMode as 'submit' | 'fill'} persistSuggestions={flag('persistSuggestions')}
     proseSize={props.proseSize as ProseSize}
@@ -82,6 +141,8 @@ defineWebComponent<Props, Events>('kai-chat', {
     triggers={props.triggers as TriggerDef[] | undefined}
     kindIcons={props.kindIcons as Record<string, string> | undefined}
     actionsReveal={props.actionsReveal as 'always' | 'hover'}
+    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)}
     onAttachmentsChange={(attachments) => dispatch('kai-attachments-change', { attachments })}

package/src/elements/choice.tsx

@@ -6,7 +6,7 @@ interface Props extends Record<string, unknown> {
   /** The choice definition (the CardEnvelope.data). Set as a JS PROPERTY:
    *  `el.data = { prompt, options:[…], allowOther?, submitLabel? }`. Import
    *  `ChoiceCardData` from `@kitn.ai/ui` for the full shape. */
-  data?: Record<string, unknown>;
+  data?: ChoiceCardData;
   /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
   cardId?: string;
   /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
@@ -14,7 +14,7 @@ interface Props extends Record<string, unknown> {
   /** Set when the user resolved this card; renders the read-only view. Property:
    *  `el.resolution = { kind:'action', action:'…' }`. */
   resolution?: Record<string, unknown>;
-  /** Controlled selection — the selected option id. When set, the consumer owns
+  /** Controlled selection: the selected option id. When set, the consumer owns
    *  the current pick (RadioGroup `value`). Attribute: `value`. */
   value?: string;
   /** Option id to pre-select on mount (uncontrolled seed). Attribute: `default-value`. */
@@ -68,23 +68,23 @@ defineWebComponent<Props, Events>(
     expose({
       /** Focus the radiogroup roving tab stop (or the Other input when selected). */
       focus: (options?: FocusOptions) => controller?.focus(options),
-      /** Select an option by id locally — no emit, fires kai-value-change (same as
-       *  a row click). Lets a consumer pre-highlight or drive selection externally. */
+      /** Select an option by id locally: no emit, fires kai-value-change (same as a
+       *  row click). Lets a consumer pre-highlight or drive selection externally. */
       select: (optionId: string) => controller?.select(optionId),
-      /** Submit the current selection — emits the `action` verb on kai-card and
+      /** Submit the current selection: emits the `action` verb on kai-card and
        *  resolves the card (single-shot). Named `send`, not `submit`, per the shared
        *  vocabulary. */
       send: () => controller?.send(),
-      /** Trigger the dismiss path — emits `dismiss` on kai-card and optimistically
+      /** Trigger the dismiss path: emits `dismiss` on kai-card and optimistically
        *  collapses the card to its re-openable stub. */
       dismiss: () => controller?.dismiss(),
-      /** Re-open a dismissed card from its stub — emits `reopen` on kai-card. */
+      /** Re-open a dismissed card from its stub: emits `reopen` on kai-card. */
       reopen: () => controller?.reopen(),
     });
 
     return (
       <ChoiceCard
-        data={props.data as ChoiceCardData | undefined}
+        data={props.data}
         cardId={props.cardId ?? (element.id || 'kai-choice')}
         heading={props.heading}
         resolution={props.resolution as CardResolution | undefined}

package/src/elements/coachmark.tsx

@@ -17,7 +17,7 @@ interface Props extends Record<string, unknown> {
   /** Floating placement relative to the anchor (default `bottom`). */
   placement?: string;
   /** Color tone: `primary` (default, theme accent), `info` (blue), `success`
-   *  (green), `warning` (amber), or `error` (red) — reusing the kit's tool hues. */
+   *  (green), `warning` (amber), or `error` (red), reusing the kit's tool hues. */
   tone?: 'primary' | 'info' | 'success' | 'warning' | 'error';
   /** Render the arrow that points at the anchor (default `true`). Set
    *  `arrow="false"` for a plain bubble with no pointer. */