@kitn.ai/ui 0.20.1 → 0.22.0

package/src/elements/feedback-bar.tsx

@@ -3,7 +3,7 @@ import { FeedbackBar, type FeedbackValue, type FeedbackDetail } from '../compone
 
 interface Props extends Record<string, unknown> {
   /** The banner label (e.g. "Was this helpful?"). Attribute: `bar-title`
-   *  (`title` is avoided — it's a global HTML attribute). */
+   *  (`title` is avoided because it is a global HTML attribute). */
   barTitle?: string;
   /** When set, a not-helpful vote opens an optional detail form before the
    *  thank-you confirmation. Attribute: `collect-detail`. */

package/src/elements/file-tree.tsx

@@ -4,7 +4,7 @@ import { FileTree, type FileTreeFile } from '../components/file-tree';
 interface Props extends Record<string, unknown> {
   /** The files to render. Set as a JS property (array of `{ path, url?, code?, language?, type?, additions?, deletions?, status? }`). */
   files: FileTreeFile[];
-  /** Selected file path — highlighted in the tree. */
+  /** Selected file path, highlighted in the tree. */
   activeFile?: string;
   /** Folder paths expanded initially. Omit to start with all folders open. */
   defaultExpanded?: string[];

package/src/elements/file-upload.tsx

@@ -7,7 +7,7 @@ interface Props extends Record<string, unknown> {
   multiple?: boolean;
   /** `accept` attribute for the file picker (e.g. `image/*`). */
   accept?: string;
-  /** Disable the dropzone — no clicking, no drag-and-drop. */
+  /** Disable the dropzone: no clicking, no drag-and-drop. */
   disabled?: boolean;
   /** Default dropzone label (overridable via the default slot). */
   label?: string;

package/src/elements/form.tsx

@@ -3,11 +3,18 @@ import { Form, type FormController, type FormDefinition } from '../components/fo
 import type { CardResolution } from '../primitives/card-contract';
 
 interface Props extends Record<string, unknown> {
-  /** The form definition — a JSON Schema (`type:'object'`) + `x-kai-*` UI hints
+  /** The form definition: a JSON Schema (`type:'object'`) + `x-kai-*` UI hints
    *  (the CardEnvelope.data). Set as a JS PROPERTY: `el.data = { type:'object',
    *  properties:{…} }`. Import the `FormDefinition` type from `@kitn.ai/ui` for
-   *  the full shape (it is self-referential, so the element types it loosely). */
-  data?: Record<string, unknown>;
+   *  the full shape.
+   *
+   *  It IS self-referential (`FormField.properties` is another `FormField` map),
+   *  and the generated `element-types.d.ts` inlines every named type, so the
+   *  shipped declaration bottoms out in a `Record<string, unknown>` placeholder
+   *  one level down rather than carrying the recursion. That is why
+   *  `FormDefinition` is a `type` alias: an interface gets no implicit index
+   *  signature, so it would not be assignable to that placeholder. */
+  data?: FormDefinition;
   /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
   cardId?: string;
   /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
@@ -27,7 +34,8 @@ interface Props extends Record<string, unknown> {
  *  contract event — `kai-values-change` is the live change signal, distinct from the
  *  terminal submit.) */
 interface Events {
-  /** The form's values changed on input — current coerced values + validity. */
+  /** The form's values changed on input. Carries the current coerced values +
+   *  validity. */
   'kai-values-change': { values: Record<string, unknown>; valid: boolean };
 }
 
@@ -56,7 +64,7 @@ defineWebComponent<Props, Events>('kai-form', {
   expose({
     /** Focus the first control, or the first INVALID control after a failed validation. */
     focus: (options?: FocusOptions) => controller?.focus(options),
-    /** Validate + submit programmatically — focus the first invalid field on failure,
+    /** Validate + submit programmatically: focus the first invalid field on failure,
      *  else emit the `submit` CardEvent and resolve. Named `send`, not `submit`. */
     send: () => controller?.send(),
     /** Run client-side validation now and return `{ valid, errors? }` WITHOUT submitting. */
@@ -71,7 +79,7 @@ defineWebComponent<Props, Events>('kai-form', {
 
   return (
     <Form
-      data={props.data as FormDefinition | undefined}
+      data={props.data}
       cardId={props.cardId ?? (element.id || 'kai-form')}
       heading={props.heading}
       resolution={props.resolution as CardResolution | undefined}

package/src/elements/input.tsx

@@ -6,7 +6,7 @@ interface Props extends Record<string, unknown> {
   /** Native input type: `text` (default) · `email` · `url` · `search` · `tel` ·
    *  `password` · `number`. Single-line only. */
   type?: string;
-  /** Controlled value — settable and reflected to the `value` attribute. `el.value
+  /** Controlled value. Settable and reflected to the `value` attribute. `el.value
    *  = 'hi'` drives it (no event); typing updates it and fires `kai-input`. Read
    *  `el.value` for live state. */
   value?: string;

package/src/elements/kbd.tsx

@@ -2,7 +2,7 @@ import { defineWebComponent } from './define';
 import { Kbd, type KbdPlatform } from '../ui/kbd';
 
 interface Props extends Record<string, unknown> {
-  /** Shortcut spec — tokens joined by `+` (e.g. `Mod+Shift+K`). Omit it to show
+  /** Shortcut spec: tokens joined by `+` (e.g. `Mod+Shift+K`). Omit it to show
    *  default-slot content instead. Display only; the element does not bind keys. */
   keys?: string;
   /** `mac` uses ⌘/⌥, `other` uses Ctrl. `auto` (default) sniffs the OS. */

package/src/elements/menu.tsx

@@ -11,47 +11,45 @@ import { Kbd } from '../ui/kbd';
 import { cn } from '../utils/cn';
 import { defineWebComponent } from './define';
 import { wireDisclosure } from './disclosure';
+import type { KaiMenuItem } from './element-data-types';
 
-export interface KaiMenuItem {
-  /** Emitted in `kai-select` for actionable items. */
-  id?: string;
-  label?: string;
-  /** Named icon (e.g. "paperclip"), image URL / data-URI, or plain text. */
-  icon?: string;
-  /** e.g. '⌘U' — shown right-aligned, muted. */
-  shortcut?: string;
-  /** Presence ⇒ a checkbox item (role=menuitemcheckbox). With `radioGroup` set,
-   *  marks the SELECTED radio item in that group instead. */
-  checked?: boolean;
-  /** Membership in a single-select group (role=menuitemradio). Items sharing a
-   *  `radioGroup` are mutually exclusive — the one with `checked: true` shows the
-   *  checkmark; selecting one emits `{ id, radioGroup }` so the consumer moves
-   *  the checkmark (the consumer owns state, like checkbox items). */
-  radioGroup?: string;
-  disabled?: boolean;
-  /** A divider (ignores other fields). */
-  separator?: boolean;
-  /** A non-interactive section label (uses `label`). */
-  heading?: boolean;
-  /** ⇒ a submenu. */
-  items?: KaiMenuItem[];
-}
+// The item shape lives in ./element-data-types so the ROOT entry can re-export it
+// (a per-element module's shipped .d.ts is `export {};`). Re-exported here so
+// `import type { KaiMenuItem } from './menu'` keeps working.
+export type { KaiMenuItem } from './element-data-types';
 
 interface Props extends Record<string, unknown> {
-  /** Tree of menu items. Set as a JS property — not an HTML attribute. */
+  /** Tree of menu items. Set as a JS property, not an HTML attribute. */
   items?: KaiMenuItem[];
   /** Optional placement hint (unused by the underlying Dropdown which always
    *  positions bottom-start, kept for future extension). */
   placement?: string;
   /** Built-in trigger: leading icon (a named icon like `"plus"`, an image
    *  URL/data-URI, or text). Use this instead of slotting `slot="trigger"` for
-   *  the common case — a slotted trigger overrides it. */
+   *  the common case; a slotted trigger overrides it. */
   triggerIcon?: string;
-  /** Built-in trigger: a text label (e.g. `"High"`). */
+  /** Built-in trigger: a text label (e.g. `"High"`). This is the trigger's
+   *  VISIBLE text, so it is also its accessible name, and `label` does not
+   *  override it: an accessible name that does not contain the visible text is
+   *  unreachable by speech input, which is what WCAG 2.5.3 (Label in Name)
+   *  exists for. A slotted `slot="trigger"` replaces this built-in trigger
+   *  entirely and is named differently; see `label`. */
   triggerLabel?: string;
   /** Built-in trigger: a trailing icon (e.g. `"chevron-down"` for a select look). */
   triggerIconTrailing?: string;
-  /** Accessible name for an icon-only trigger (no visible label). */
+  /** Accessible name for a trigger with no visible label. Ignored when
+   *  `triggerLabel` is set, which is already the visible name.
+   *
+   *  It DOES name a slotted `slot="trigger"`, and that is a difference in what
+   *  the two slots MEAN, not a limitation. `<kai-button>`'s slot IS the button's
+   *  label, so text slotted there is the name and `label` steps aside. This slot
+   *  is VISUAL content, a `+` or an `<svg>`, with the name supplied separately:
+   *  decoration beside a name, never a second name competing with one. So
+   *  `label` names the trigger here by design.
+   *
+   *  Slotting a real WORD rather than a glyph makes that word a visible label,
+   *  and an accessible name has to contain the visible text. Then either drop
+   *  `label` or make it contain the word you slotted. */
   label?: string;
   /** Drive/observe open state (Shoelace-style: settable + reflected to the `open`
    *  attribute, the menu still self-manages on click/keyboard). Set `el.open = true`,
@@ -59,7 +57,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 menu. */
+  /** Disable the trigger: click/keyboard and `show()` no longer open the menu. */
   disabled?: boolean;
 }
 
@@ -68,8 +66,8 @@ interface Events {
    * Fired when the user selects a leaf item.
    * - Plain items: `{ id }`.
    * - Checkbox items: `{ id, checked }` where `checked` is the NEW state.
-   * - Radio items: `{ id, radioGroup }` — the consumer marks `id` as the selected
-   *   one in `radioGroup` and clears the others.
+   * - Radio items: `{ id, radioGroup }`, where the consumer marks `id` as the
+   *   selected one in `radioGroup` and clears the others.
    */
   'kai-select': { id: string; checked?: boolean; radioGroup?: string };
   /** The menu opened or closed (by click, keyboard, Escape, outside-click, or a method). */
@@ -201,7 +199,17 @@ defineWebComponent<Props, Events>('kai-menu', {
             ? 'gap-1.5 px-2 py-1.5 text-sm font-medium text-muted-foreground hover:bg-accent hover:text-foreground'
             : 'justify-center p-1.5 text-foreground hover:bg-muted',
         )}
-        aria-label={props.label ?? (props.triggerLabel ? undefined : 'Open menu')}
+        // A visible `triggerLabel` IS the name (name-from-contents reaches the
+        // slotted/shadow text), so `label` must not be layered over it: aria-label
+        // REPLACES the computed name, and a trigger reading "High" that answers to
+        // "Reasoning effort" locks speech-input users out (WCAG 2.5.3). Same rule
+        // kai-checkpoint and kai-button follow.
+        //
+        // A SLOTTED trigger keeps `label`, and that is the contract rather than a
+        // gap: kai-button's slot IS the label, so text there is the name; this
+        // slot is visual content with the name supplied separately. Two slots,
+        // two meanings, so the same rule should not apply to both. See `label`.
+        aria-label={props.triggerLabel ? undefined : (props.label ?? 'Open menu')}
       >
         {/* Slotted trigger wins; otherwise build one from the trigger* props;
             otherwise fall back to a "more" glyph. */}

package/src/elements/message-skills.tsx

@@ -1,17 +1,15 @@
 import { createSignal, onCleanup, onMount } from 'solid-js';
 import { defineWebComponent } from './define';
-import { MessageSkills } from '../components/message-skills';
+// The badge shape is the Solid component's own `Skill` — one declaration, so the
+// element and `<MessageSkills>` cannot drift, and the ROOT entry re-exports it.
+import { MessageSkills, type Skill } from '../components/message-skills';
 
-interface Skill {
-  /** Stable identifier for the skill. */
-  id: string;
-  /** Human-readable skill name shown on the badge. */
-  name: string;
-}
 
 interface Props extends Record<string, unknown> {
-  /** The active skills to badge. Set as a JS property. */
-  skills: Skill[];
+  /** The active skills to badge. Set as a JS property. Omit to supply them as
+   *  `<kai-skill>` light-DOM children instead; when both are present the
+   *  property's skills come first. Nothing renders when there are none. */
+  skills?: Skill[];
 }
 
 /**

package/src/elements/message.tsx

@@ -1,18 +1,76 @@
-import { Show, createSignal, onMount, onCleanup } from 'solid-js';
+import { Show, createSignal, createEffect, onMount, onCleanup, type JSX } from 'solid-js';
+import { Dynamic } from 'solid-js/web';
 import { defineWebComponent } from './define';
 import { readSlots, MESSAGE_SLOTS } from './slots';
 import { ChatConfig, useChatConfig, type ProseSize } from '../primitives/chat-config';
 import { Message, MessageAvatar, MessageBody } from '../components/message';
 import { createMessageFeedback } from '../primitives/message-feedback';
+import {
+  mergeCardTags,
+  BUILTIN_CARD_TAGS,
+  BUILTIN_CARD_COMPONENTS,
+  type CardTagMap,
+  type CardComponentMap,
+} from '../primitives/card-registry';
+import type { CardEnvelope } from '../primitives/card-contract';
+import { hasParts } from './validate-messages';
 import type { ChatMessage } from './chat-types';
 
+/**
+ * Bridges the web-component-facing `cardTypes` (envelope type -> custom-element
+ * TAG name, e.g. `{ 'my-widget': 'my-widget-el' }`) into the `CardComponentMap`
+ * that `MessageBody`/`Thread` expect. A type the consumer did NOT override keeps
+ * rendering its built-in Solid component directly (no extra custom-element
+ * indirection); an overridden built-in or a brand-new consumer type renders as a
+ * dynamically-created custom element instead, mirroring `<kai-cards>`'s
+ * `CardSlot`. A type with no tag at all (unregistered) simply gets no entry, so
+ * `CardRenderer`'s own fallback (`CardFallback`) takes over.
+ */
+export function cardComponentsFromTags(types?: CardTagMap, theme = 'auto'): CardComponentMap {
+  const tags = mergeCardTags(types);
+  const map: CardComponentMap = {};
+  for (const type of Object.keys(tags)) {
+    const tag = tags[type];
+    map[type] = tag === BUILTIN_CARD_TAGS[type] && BUILTIN_CARD_COMPONENTS[type]
+      ? BUILTIN_CARD_COMPONENTS[type]
+      : (p) => <CardTagSlot tag={tag} envelope={p.envelope} theme={theme} />;
+  }
+  return map;
+}
+
+/** Renders one envelope as a dynamically-created custom element, setting the
+ *  envelope's data/id/title/resolution as DOM properties (reactive) plus the
+ *  `theme` + `data-card-id` chrome, mirroring `<kai-cards>`'s `CardSlot` so a
+ *  custom card behaves identically whether it arrives via `<kai-cards>` or a
+ *  `card` message part here. */
+function CardTagSlot(props: { tag: string; envelope: CardEnvelope; theme: string }): JSX.Element {
+  let ref: HTMLElement | undefined;
+  createEffect(() => {
+    if (!ref) return;
+    (ref as unknown as { data: unknown }).data = props.envelope.data;
+    (ref as unknown as { cardId: string }).cardId = props.envelope.id;
+    if (props.envelope.title != null) (ref as unknown as { heading: string }).heading = props.envelope.title;
+    (ref as unknown as { resolution: unknown }).resolution = props.envelope.resolution;
+    ref.setAttribute('theme', props.theme);
+    ref.setAttribute('data-card-id', props.envelope.id);
+  });
+  return <Dynamic component={props.tag} ref={ref} />;
+}
+
 interface Props extends Record<string, unknown> {
   /** The full message object. Set as a JS property. */
   message?: ChatMessage;
-  /** Convenience for simple cases when not passing a `message` object. */
+  /** Who is speaking: `'user'` or `'assistant'`. Convenience for simple cases when
+   *  not passing a `message` object.
+   *
+   *  This is the SEMANTIC role of the message, not an ARIA role. The name collides
+   *  with the global ARIA `role` attribute, which is why the facade lifts it off
+   *  the host (see `liftRoleOffHost`). Neither speaker is a valid ARIA role,
+   *  so a `role="user"` left on `<kai-message>` is a CRITICAL axe `aria-roles`
+   *  violation. The accessible role lives on the row inside the shadow root
+   *  instead: `role="article"` plus an `aria-label` naming the speaker, matching
+   *  the SolidJS `<Message>` component. */
   role?: 'user' | 'assistant';
-  /** Convenience content (used when `message` is not set). */
-  content?: string;
   /** Force markdown on/off. Defaults to on for assistant, off for user. */
   markdown?: boolean;
   /** Text/markdown sizing for the message body. */
@@ -33,6 +91,65 @@ interface Props extends Record<string, unknown> {
    *  value keeps the default behaviour: the built-in avatar when one resolves, or
    *  your `slot="avatar"` content when projected (which REPLACES the built-in). */
   avatar?: 'none' | string;
+  /** 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>;
+}
+
+/**
+ * Move a `role` the consumer put on the host into the element's own prop store,
+ * and off the DOM.
+ *
+ * `role` names the SPEAKER here (`'user'` / `'assistant'`) — the correct domain
+ * word, and the documented attribute — but it is also the global ARIA `role`
+ * attribute, and neither speaker is a valid ARIA role. Measured in a real chromium:
+ * a host left carrying `role="user"` is a CRITICAL axe `aria-roles` violation
+ * ("Role must be one of the valid ARIA roles: user"), and chromium discards the
+ * unknown token and computes `generic`, so the row is left with no accessible role
+ * and no accessible name rather than a mis-announced one.
+ *
+ * Capture the value, remove the attribute, then write it back as a PROPERTY.
+ * component-register's prop accessors do not reflect, so the write cannot put it
+ * back on the DOM, and it feeds the same reactive prop the facade already reads.
+ *
+ * The ORDER is load-bearing: `removeAttribute` fires component-register's
+ * `attributeChangedCallback` with `null`, which sets the property to `null`. The
+ * write-back has to come after that, or the scrub destroys the speaker it was
+ * meant to preserve.
+ *
+ * NOTE — this covers every path where the attribute is still on the host by the
+ * time the facade runs (`setAttribute` before or after connection, and any later
+ * change, via the observer below). It does NOT cover an element authored in HTML
+ * and upgraded at registration time: `defineWebComponent` installs its
+ * non-reflecting `role` accessor AFTER `customElements.define()`, so for elements
+ * already in the document the native ARIAMixin setter runs first in the constructor
+ * (`this[prop] = undefined` → `role` is a nullable reflected IDL attribute →
+ * `removeAttribute`) and the value is gone before any of this code executes. That
+ * is a separate defect in `src/elements/define.tsx`, not something the facade can
+ * reach; this function composes correctly with the fix once it lands.
+ */
+function liftRoleOffHost(element: HTMLElement): void {
+  const attr = element.getAttribute('role');
+  if (attr === null) return;
+  element.removeAttribute('role');
+  (element as unknown as { role?: string }).role = attr;
 }
 
 /** Events fired by `<kai-message>`. */
@@ -52,7 +169,6 @@ interface Events {
 defineWebComponent<Props, Events>('kai-message', {
   message: undefined,
   role: 'assistant',
-  content: undefined,
   markdown: undefined,
   proseSize: 'sm',
   codeTheme: 'github-dark-dimmed',
@@ -61,10 +177,39 @@ defineWebComponent<Props, Events>('kai-message', {
   avatarSrc: undefined,
   avatarFallback: undefined,
   avatar: undefined,
+  cardTypes: undefined,
+  cardSchemas: undefined,
 }, (props, { dispatch, flag, element, expose }) => {
   const outer = useChatConfig();
+  // Do this FIRST, before anything reads `props.role`: it rewrites that prop as a
+  // side effect of taking the invalid ARIA role off the host.
+  liftRoleOffHost(element);
   const msg = (): ChatMessage =>
-    props.message ?? { id: 'message', role: props.role ?? 'assistant', content: props.content ?? '' };
+    props.message ?? {
+      id: 'message',
+      role: props.role ?? 'assistant',
+      parts: [],
+    };
+  // `message` is an untyped boundary: a consumer can hand it anything at
+  // runtime (a pre-0.20.0 `{ id, role, content }` object, in particular).
+  // `parts` is a REQUIRED field, so validate it here rather than let
+  // `MessageBody`/`groupMessageParts` throw deep inside a Solid render pass;
+  // an uncaught exception there blanks the whole element instead of just this
+  // one message. Warn once per bad message (not on every unrelated re-render)
+  // and render nothing for it, matching the old pre-parts fallback behavior
+  // (an unusable message rendered an empty body, not a crash).
+  let lastWarnedMessage: unknown;
+  const hasValidParts = (): boolean => {
+    const m = msg();
+    if (hasParts(m)) return true;
+    if (m !== lastWarnedMessage) {
+      lastWarnedMessage = m;
+      console.error(
+        "<kai-message>: 'message' must have a 'parts' array. The 'content' string field was removed in 0.20.0.",
+      );
+    }
+    return false;
+  };
   // Copy + vote state lives here (above the rendered body) so it survives a
   // re-render when the host swaps in a fresh `message` object during streaming.
   const feedback = createMessageFeedback({
@@ -82,7 +227,7 @@ defineWebComponent<Props, Events>('kai-message', {
   // `kai-message-action{action:'copy'}`.
   expose({
     /** Copy the message content to the clipboard and show the copied check. */
-    copy: () => feedback.handleAction(msg(), 'copy'),
+    copy: () => { if (hasValidParts()) feedback.handleAction(msg(), 'copy'); },
   });
 
   // Read declarative <kai-action> children from light DOM.
@@ -106,6 +251,16 @@ defineWebComponent<Props, Events>('kai-message', {
     observer.observe(element, { childList: true, attributes: true, subtree: true });
     onCleanup(() => observer.disconnect());
   });
+  // A consumer can set `role` at any point after the element is live
+  // (`el.setAttribute('role', 'user')`), which puts the invalid ARIA role back on
+  // the host. Keep lifting it off. Scoped to the one attribute so this cannot be
+  // mistaken for general attribute handling; no loop, because the write-back is a
+  // property and the removal leaves nothing for the next callback to find.
+  onMount(() => {
+    const roleObserver = new MutationObserver(() => liftRoleOffHost(element));
+    roleObserver.observe(element, { attributes: true, attributeFilter: ['role'] });
+    onCleanup(() => roleObserver.disconnect());
+  });
   const isUser = () => msg().role === 'user';
   const avatar = () =>
     msg().avatar ??
@@ -127,10 +282,9 @@ defineWebComponent<Props, Events>('kai-message', {
   const mergedActions = () => [...(msg().actions ?? []), ...slottedActions()];
   const body = () => (
     <MessageBody
-      content={msg().content}
-      reasoning={msg().reasoning}
-      tools={msg().tools}
-      attachments={msg().attachments}
+      parts={msg().parts}
+      cardTypes={cardComponentsFromTags(props.cardTypes, (props as { theme?: string }).theme)}
+      cardSchemas={props.cardSchemas}
       isUser={isUser()}
       markdown={useMarkdown()}
       actions={mergedActions()}
@@ -165,27 +319,41 @@ defineWebComponent<Props, Events>('kai-message', {
   );
 
   return (
-    <ChatConfig
-      proseSize={props.proseSize}
-      codeTheme={props.codeTheme}
-      codeHighlight={flag('codeHighlight')}
-      portalMount={outer.portalMount()}
-    >
-      <Show
-        when={showRail()}
-        fallback={
-          <Message class={`${rowGroup()}${isUser() ? 'flex-col items-end' : 'flex-col items-start'}`}>
-            {body()}
-          </Message>
-        }
+    // No fallback: an invalid `message` (missing `parts`) renders nothing for
+    // this element rather than crashing. `hasValidParts()` already logged why.
+    <Show when={hasValidParts()}>
+      <ChatConfig
+        proseSize={props.proseSize}
+        codeTheme={props.codeTheme}
+        codeHighlight={flag('codeHighlight')}
+        portalMount={outer.portalMount()}
       >
-        <Message class={rowGroup()}>
-          {avatarRail()}
-          <div class={`flex min-w-0 flex-1 flex-col ${isUser() ? 'items-end' : 'items-start'}`}>
-            {body()}
-          </div>
-        </Message>
-      </Show>
-    </ChatConfig>
+        <Show
+          when={showRail()}
+          fallback={
+            // `role` here is `<Message>`'s SPEAKER prop, not an ARIA role: the
+            // component turns it into `role="article"` + an `aria-label` naming the
+            // speaker, so the row an assistive technology sees has a valid role and
+            // a name. This is the same treatment the SolidJS `<Message>` gets when
+            // used directly — the facade just always knows its speaker, so unlike
+            // the bare component (where `role` is optional and usually omitted) the
+            // row is never left unlabelled.
+            <Message
+              role={msg().role}
+              class={`${rowGroup()}${isUser() ? 'flex-col items-end' : 'flex-col items-start'}`}
+            >
+              {body()}
+            </Message>
+          }
+        >
+          <Message role={msg().role} class={rowGroup()}>
+            {avatarRail()}
+            <div class={`flex min-w-0 flex-1 flex-col ${isUser() ? 'items-end' : 'items-start'}`}>
+              {body()}
+            </div>
+          </Message>
+        </Show>
+      </ChatConfig>
+    </Show>
   );
 });

package/src/elements/model-switcher.tsx

@@ -6,8 +6,10 @@ import type { DropdownController } from '../ui/dropdown';
 import type { ModelOption } from '../types';
 
 interface Props extends Record<string, unknown> {
-  /** The selectable models. Set as a JS property (array). */
-  models: ModelOption[];
+  /** The selectable models. Set as a JS property (array). Omit to supply them as
+   *  `<kai-model>` light-DOM children instead; when both are present the
+   *  property's models come first. */
+  models?: ModelOption[];
   /** The currently-selected model id. Defaults to the first model. */
   currentModel?: string;
   /** Drive/observe the dropdown's open state (Shoelace-style: settable + reflected
@@ -16,7 +18,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;
 }
 

package/src/elements/pane.tsx

@@ -31,7 +31,7 @@ interface Props extends Record<string, unknown> {
 /** Events fired by `<kai-pane>`. All non-bubbling — listen on the element. */
 interface Events {
   /** The maximize/restore control was clicked. `detail.maximized` is the
-   *  intended NEXT state — drive the `maximized` prop yourself from it. */
+   *  intended NEXT state. Drive the `maximized` prop yourself from it. */
   'kai-maximize': { maximized: boolean };
   /** The close (×) control was clicked. */
   'kai-close': void;

package/src/elements/prompt-dock.tsx

@@ -3,15 +3,15 @@ import { defineWebComponent } from './define';
 import { PromptDock, type PromptDockAppearance, type PromptDockFrame } from '../ui/prompt-dock';
 
 interface Props extends Record<string, unknown> {
-  /** How the tray frames the input — the SPATIAL inset axis: `inset` (default,
-   *  the classic recessed frame on every side) | `edge` (top/bottom inset only;
-   *  the input sits flush left/right so the lips span the full width) | `none`
-   *  (no inset; the lips attach directly as a plain stack). Attribute: `frame`. */
+  /** How the tray frames the input, the SPATIAL inset axis: `inset` (default, the
+   *  classic recessed frame on every side) | `edge` (top/bottom inset only; the
+   *  input sits flush left/right so the lips span the full width) | `none` (no
+   *  inset; the lips attach directly as a plain stack). Attribute: `frame`. */
   frame?: PromptDockFrame;
-  /** How the tray surface looks — the VISUAL axis, orthogonal to `frame`:
-   *  `soft` (default, sunken surface + border + radius) | `outlined`
-   *  (transparent + border + radius) | `filled` (sunken, no border, + radius) |
-   *  `plain` (bare). Attribute: `appearance`. */
+  /** How the tray surface looks, the VISUAL axis orthogonal to `frame`: `soft`
+   *  (default, sunken surface + border + radius) | `outlined` (transparent +
+   *  border + radius) | `filled` (sunken, no border, + radius) | `plain`
+   *  (bare). Attribute: `appearance`. */
   appearance?: PromptDockAppearance;
 }
 

package/src/elements/prompt-input.tsx

@@ -37,9 +37,9 @@ interface Props extends Record<string, unknown> {
    *  button (square icon, "Stop" aria-label). Clicking it fires `kai-stop`. */
   stoppable?: boolean;
   /** Send-button visibility. `'always'` (default) always shows it; `'auto'` shows
-   *  it only when there's text/attachments (an empty composer hides it — Enter
-   *  still submits). To hide it entirely (Enter-only), it's pure CSS:
-   *  `::part(send){display:none}` — no prop needed. Restyle via `::part(send)`.
+   *  it only when there's text/attachments (an empty composer hides it, though
+   *  Enter still submits). To hide it entirely (Enter-only), it's pure CSS:
+   *  `::part(send){display:none}`, no prop needed. Restyle via `::part(send)`.
    *  The Stop button (`stoppable` + `loading`) is unaffected. */
   submit?: 'always' | 'auto';
   /** When `false`, hides the built-in paperclip attach button even though the
@@ -51,9 +51,9 @@ interface Props extends Record<string, unknown> {
    *  files without an upload). Set as a JS property; the element then manages its
    *  own attachment state from there (add via the paperclip, remove per chip). */
   attachments?: AttachmentData[];
-  /** Rich entity triggers — each `{ char, kind, items }` opens a caret-anchored
-   *  menu that inserts an atomic pill. Convention: `/` → skills, `@` → agents
-   *  (plugins are the grouping/provenance of those items). Set as a JS property. */
+  /** Rich entity triggers. Each `{ char, kind, items }` opens a caret-anchored menu
+   *  that inserts an atomic pill. Convention: `/` → skills, `@` → agents (plugins
+   *  are the grouping/provenance of those items). Set as a JS property. */
   triggers?: TriggerDef[];
   /** Default icon per entity kind (kind → image URL/data-URI) for pills/menu items
    *  without their own `icon`. Overrides the built-in agent/plugin glyphs. JS property. */
@@ -69,7 +69,7 @@ interface Events {
   /** The input changed (fires on every edit). Carries the flattened `value`
    *  plus the structured `doc` + `entities`. */
   'kai-value-change': { value: string; doc: ComposerDoc; entities: EntityRef[] };
-  /** The staged attachments changed — a file was added (via the paperclip) or
+  /** The staged attachments changed: a file was added (via the paperclip) or
    *  removed (per-chip ×). Carries the full current list so a consumer can react
    *  in real time (validate, show upload progress, toggle the send button). */
   'kai-attachments-change': { attachments: AttachmentData[] };
@@ -198,9 +198,9 @@ defineWebComponent<Props, Events>('kai-prompt-input', {
       handleChange('');
       if (attachments().length) { setAttachments([]); dispatch('kai-attachments-change', { attachments: [] }); }
     },
-    /** Send the current value programmatically — same path as Enter / the send
-     *  button (fires kai-submit, then clears staged attachments). Named `send`,
-     *  not `submit`, to avoid colliding with the `submit` prop. */
+    /** Send the current value programmatically, on the same path as Enter / the
+     *  send button (fires kai-submit, then clears staged attachments). Named
+     *  `send`, not `submit`, to avoid colliding with the `submit` prop. */
     send: () => handleSubmit(),
   });