@kitn.ai/ui 0.20.0 → 0.21.0

package/src/elements/register.ts

@@ -29,6 +29,15 @@ export type { ChatMessage, ChatMessageAction } from './chat-types';
 export { configureCodeHighlighting, isCodeHighlightingEnabled } from '../primitives/highlighter';
 export type { CodeHighlightingOptions } from '../primitives/highlighter';
 
+// ToolPart.kind's doc comment in the shipped dist/elements.d.ts says "Derive with
+// `classifyTool(type)`", but the function was exported from NO public entry, so a
+// consumer following our own docs hit an unresolvable import. Total, deterministic
+// and always terminating in 'generic' — safe to expose, and needed by anyone
+// rendering tool calls themselves. tool-classify.ts imports nothing, so this stays
+// SSR-safe and adds no weight to the register-all bundle.
+export { classifyTool } from '../components/tool-classify';
+export type { ToolKind } from '../components/tool-classify';
+
 // Imperative toast API — usable directly from the elements entry so consumers
 // who only import the web-components bundle still get `toast()`. The store is
 // SSR-safe (no DOM touched until the first toast is raised on the client).

package/src/elements/resizable.globals.d.ts

@@ -0,0 +1,36 @@
+// src/elements/resizable.globals.d.ts
+// Hand-authored ambient types for the cross-element maximize PROTOCOL — the two
+// raw composed CustomEvents `<kai-artifact>` and `<kai-resizable>`/`<kai-resizable-item>`
+// exchange. The generated element-types.d.ts emits no HTMLElementEventMap entries,
+// so without this `el.addEventListener('kai-maximize-intent', e => e.detail)` is
+// TS2339 on `Event`. NOT regenerated by `npm run build`.
+//
+// THE FILENAME IS LOAD-BEARING and must not go back to `resizable.d.ts`.
+// TypeScript drops a .d.ts when a same-named .ts/.tsx sits beside it, and
+// `resizable.tsx` does. Under the old name this whole file was in NO tsc
+// program, so every augmentation below was inert. Measured on the same probe,
+// `el.addEventListener('kai-maximize-intent', e => e.detail)`:
+//   resizable.d.ts         TS2339: Property 'detail' does not exist on 'Event'
+//   resizable.globals.d.ts clean -- narrowed to CustomEvent<KaiMaximizeIntentDetail>
+//
+// This file used to ALSO declare a global `KaiResizableElement` carrying
+// `maximize`/`restore` plus an HTMLElementTagNameMap entry pointing at it. That
+// half never worked: element-types.d.ts declares its own module-scoped
+// `KaiResizableElement` and maps the tag to THAT, so the two entries collided
+// (TS2717, invisible under the `skipLibCheck: true` every pass sets) and the
+// generated one won — `document.querySelector('kai-resizable').maximize(0)` stayed
+// TS2339. The methods now come from the GENERATOR (resizable.tsx routes them
+// through `ctx.expose`, gen-element-types.mjs emits them onto the element
+// interface), so the duplicate is gone and there is exactly one declaration of
+// each name. Do not reintroduce it: a hand-written interface cannot win against
+// the generated one, and generated files are regenerated.
+import type { KaiMaximizeIntentDetail, KaiMaximizeStateDetail } from './resizable';
+
+declare global {
+  interface HTMLElementEventMap {
+    'kai-maximize-intent': CustomEvent<KaiMaximizeIntentDetail>;
+    'kai-maximize-state': CustomEvent<KaiMaximizeStateDetail>;
+  }
+}
+
+export {};

package/src/elements/resizable.tsx

@@ -57,9 +57,9 @@ interface GroupProps extends Record<string, unknown> {
   maximizedIndex?: number | null;
   /**
    * Divider affordance drawn inside each draggable handle's 8px grab zone:
-   * - `line` (default) — a 1px hairline, transparent at rest, tinting on hover/drag.
-   * - `grip` — a dotted grip handle.
-   * - `none` — no visible divider, just the invisible hit-area.
+   * - `line` (default): a 1px hairline, transparent at rest, tinting on hover/drag.
+   * - `grip`: a dotted grip handle.
+   * - `none`: no visible divider, just the invisible hit-area.
    * The full grab zone and keyboard/ARIA behavior are identical for all three.
    */
   handle?: 'line' | 'grip' | 'none';
@@ -70,6 +70,11 @@ interface GroupEvents extends Record<string, unknown> {
   'kai-change': { sizes: number[] };
   /** Observe layout maximize state. */
   'kai-maximize-change': { maximized: boolean; index: number | null };
+  /** Authoritative maximize state, dispatched as a raw composed CustomEvent (not
+   *  through `dispatch`) onto the affected `<kai-resizable-item>` and, on restore,
+   *  onto the group host. A nested element (e.g. `<kai-artifact>`) listens for it
+   *  to reconcile its own toggle. */
+  'kai-maximize-state': { maximized: boolean };
 }
 
 /**
@@ -84,7 +89,7 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
   orientation: 'horizontal',
   maximizedIndex: null,
   handle: 'line',
-}, (props, { element, dispatch }) => {
+}, (props, { element, dispatch, expose }) => {
   const [items, setItems] = createSignal<ItemInfo[]>([]);
   const orientation = (): Orientation => (props.orientation === 'vertical' ? 'vertical' : 'horizontal');
 
@@ -405,13 +410,19 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
 
     // --- Task 3: imperative host methods + declarative maximizedIndex prop ---
 
-    // Imperative host API (assigned onto the element; typed by resizable.d.ts).
-    const host = element as unknown as { maximize(i: number): void; restore(): void };
-    host.maximize = (i: number) => {
-      const it = items()[i]?.el;
-      if (it) maximizeItem(it);
-    };
-    host.restore = () => restore();
+    // Imperative host API. Routed through `expose()` like every other element's,
+    // so gen-element-api.mjs sees it and the generated element interface carries
+    // `maximize`/`restore` — a direct assignment onto `element` was invisible to
+    // the extractor and needed an `as unknown as` cast to type-check here.
+    expose({
+      /** Imperatively maximize the item at `index` (thin wrapper over `maximizedIndex`). */
+      maximize: (index: number) => {
+        const it = items()[index]?.el;
+        if (it) maximizeItem(it);
+      },
+      /** Imperatively restore from the maximized layout. */
+      restore: () => restore(),
+    });
 
     // Declarative maximizedIndex → maximize/restore. Skip the initial null run.
     createEffect(
@@ -599,8 +610,8 @@ interface ItemProps extends Record<string, unknown> {
   /** Hide this panel; its divider is dropped and the rest reflow. */
   hidden?: boolean;
   /**
-   * Collapse this panel — same layout effect as `hidden` (divider dropped, the
-   * rest reflow), but it WORKS as a bare boolean from framework JSX. A plain
+   * Collapse this panel. Same layout effect as `hidden` (divider dropped, the rest
+   * reflow), but it WORKS as a bare boolean from framework JSX. A plain
    * `<kai-resizable-item collapsed>` in React/Solid/Vue/Svelte collapses the panel
    * at the first render; `hidden` does not, because a JSX boolean sets neither the
    * `hidden` attribute nor the IDL property on a custom element, so the parent never

package/src/elements/response-stream.tsx

@@ -3,7 +3,7 @@ import { ResponseStream, type Mode } from '../components/response-stream';
 
 interface Props extends Record<string, unknown> {
   /** Text to stream. A string, or an `AsyncIterable<string>` (set as a JS
-   *  property — async iterables can't be HTML attributes). */
+   *  property, since async iterables can't be HTML attributes). */
   text?: string | AsyncIterable<string>;
   /** Reveal animation. */
   mode?: Mode;

package/src/elements/scroll-button.tsx

@@ -19,7 +19,7 @@ interface Props extends Record<string, unknown> {
 /** Events fired by `<kai-scroll-button>`. */
 interface Events {
   /** Emitted when the user clicks the button and `scrollToBottom()` is
-   *  called. Carries no detail — consumers use it to know a manual scroll
+   *  called. Carries no detail; consumers use it to know a manual scroll
    *  occurred. */
   'kai-scroll': void;
 }

package/src/elements/search.tsx

@@ -6,7 +6,7 @@ import { Loader } from '../components/loader';
 import { renderIcon } from '../ui/icon';
 
 interface Props extends Record<string, unknown> {
-  /** Controlled query — settable and reflected to the `value` attribute. Read
+  /** Controlled query. Settable and reflected to the `value` attribute. Read
    *  `el.value` for live state. */
   value?: string;
   /** Placeholder. Defaults to `Search…`. */
@@ -123,7 +123,12 @@ defineWebComponent<Props, Events>('kai-search', {
   };
 
   expose({
+    /** Focus the search input inside the shadow root. A native `focus()` on the
+     *  host lands on the host itself and never reaches it. */
     focus: () => getInput()?.focus(),
+    /** Empty the field and fire `kai-search` with an empty value immediately,
+     *  cancelling any debounced search still in flight, then return focus to the
+     *  input. Same path as the trailing clear button. */
     clear,
   });
 

package/src/elements/segmented.tsx

@@ -2,20 +2,14 @@ import { createEffect, createSignal, untrack } from 'solid-js';
 import { defineWebComponent } from './define';
 import { Segmented, type SegmentedOption } from '../ui/segmented';
 import { renderIcon } from '../ui/icon';
-
-/** A single segment. `icon` is an icon-NAME string (web-component-friendly) —
- *  a curated name (e.g. `"code"`), a URL/data-URI, or plain text — resolved to a
- *  glyph via the kit's icon renderer (the same path `kai-button`'s `icon` uses). */
-interface Option {
-  value: string;
-  label: string;
-  icon?: string;
-}
+// Public shape of the `options` prop; lives in ./element-data-types so the ROOT
+// entry can re-export it (see that file's header).
+import type { KaiSegmentedOption } from './element-data-types';
 
 interface Props extends Record<string, unknown> {
   /** The selectable segments, left to right. Set as a JS property (array). */
-  options: Option[];
-  /** Controlled selected `value` — settable and reflected to the `value`
+  options: KaiSegmentedOption[];
+  /** Controlled selected `value`. Settable and reflected to the `value`
    *  attribute. `el.value = 'preview'` drives it; choosing a segment updates it
    *  and fires `kai-change`. Read `el.value` for live state. */
   value?: string;

package/src/elements/separator.tsx

@@ -3,7 +3,7 @@ import { defineWebComponent } from './define';
 
 interface Props extends Record<string, unknown> {
   /** `horizontal` (default, block + full-width) or `vertical` (a rule inside a
-   *  flex/grid row — it stretches to the row height). */
+   *  flex/grid row, stretching to the row height). */
   orientation?: 'horizontal' | 'vertical';
 }
 

package/src/elements/slots.ts

@@ -27,7 +27,7 @@ export const CHAT_SLOTS: SlotDef[] = [
   { name: 'header-end',       mode: 'inject',  doc: 'Trailing header controls.' },
   { name: 'header',           mode: 'replace', part: true, doc: 'Full custom header; replaces the built-in title/model/context bar.' },
   { name: 'sidebar',          mode: 'inject',  part: true, doc: 'Left column (your nav / conversation list). Fixed width; use compose-your-own for resizable.' },
-  { name: 'empty',            mode: 'replace', doc: 'Custom zero-state rendered in the message area while the thread is empty. Replaces the empty message list only — the composer and any suggestions still render.' },
+  { name: 'empty',            mode: 'replace', doc: 'Custom zero-state rendered in the message area while the thread is empty. Replaces the empty message list only; the composer and any suggestions still render.' },
   { name: 'composer',         mode: 'replace', doc: 'Full custom composer; you own submit + loading, drive the thread via messages.' },
   { name: 'composer-actions', mode: 'inject',  doc: 'Accessory row above the composer.' },
   { name: 'footer',           mode: 'inject',  part: true, doc: 'Row below the composer (disclaimers, token meter).' },
@@ -42,8 +42,8 @@ export const CHAT_SLOTS: SlotDef[] = [
  *  no outer block slot here. (When the input is nested inside `<kai-chat>`'s shadow,
  *  that surrounding hole belongs to `kai-chat` — see `composer-actions`/`footer`.) */
 export const PROMPT_INPUT_SLOTS: SlotDef[] = [
-  { name: 'input-top',     mode: 'inject', doc: 'Inside the card, above the textarea (e.g. an inline status strip). For content above/below the whole card, use your own layout — that is light DOM you control.' },
-  { name: 'toolbar-start', mode: 'inject', doc: 'Leading controls in the input toolbar — where a + menu goes.' },
+  { name: 'input-top',     mode: 'inject', doc: 'Inside the card, above the textarea (e.g. an inline status strip). For content above/below the whole card, use your own layout; that is light DOM you control.' },
+  { name: 'toolbar-start', mode: 'inject', doc: 'Leading controls in the input toolbar, where a + menu goes.' },
   { name: 'toolbar-end',   mode: 'inject', doc: 'Trailing controls in the toolbar, before the Send button.' },
 ];
 
@@ -52,7 +52,7 @@ export const PROMPT_INPUT_SLOTS: SlotDef[] = [
 export const CONVERSATIONS_SLOTS: SlotDef[] = [
   { name: 'header', mode: 'replace', doc: 'Full custom title bar; replaces the built-in toggle / "Chats" / New-chat row.' },
   { name: 'empty',  mode: 'replace', doc: 'Custom zero-state shown when there are no conversations; replaces the built-in "No conversations yet".' },
-  { name: 'footer', mode: 'inject',  doc: 'A row below the list — account, settings, or usage.' },
+  { name: 'footer', mode: 'inject',  doc: 'A row below the list: account, settings, or usage.' },
 ];
 
 /** Styleable `::part`s of `<kai-conversations>`. */
@@ -69,15 +69,15 @@ export const CONVERSATIONS_PARTS: PartDef[] = [
  *  REPLACES the built-in avatar rail (pair it with `avatar="none"` to omit the
  *  rail entirely). These are the keystone of compose-your-own message lists. */
 export const MESSAGE_SLOTS: SlotDef[] = [
-  { name: 'before-body', mode: 'inject',  doc: 'A per-message header at the TOP of the body, above reasoning/tools/content — a model-name label, a role + timestamp line.' },
-  { name: 'after-body',  mode: 'inject',  doc: 'A row at the BOTTOM of the body, below the action bar — a citation/sources row, a token-cost/latency line.' },
+  { name: 'before-body', mode: 'inject',  doc: 'A per-message header at the TOP of the body, above reasoning/tools/content: a model-name label, a role + timestamp line.' },
+  { name: 'after-body',  mode: 'inject',  doc: 'A row at the BOTTOM of the body, below the action bar: a citation/sources row, a token-cost/latency line.' },
   { name: 'avatar',      mode: 'replace', part: true, doc: 'Replaces the built-in avatar rail with your own node. Use `avatar="none"` to omit the rail and let the body span the full row.' },
 ];
 
 /** Slots of `<kai-notice>`. The message is the default slot; these are the named seams. */
 export const NOTICE_SLOTS: SlotDef[] = [
-  { name: 'action', mode: 'inject',  doc: 'A trailing action beside the message — a link or button.' },
-  { name: 'icon',   mode: 'replace', doc: 'A custom leading icon (any inline SVG, inherits `currentColor`). Overrides the severity default and the `icon` prop — the same escape hatch as `kai-button`.' },
+  { name: 'action', mode: 'inject',  doc: 'A trailing action beside the message: a link or button.' },
+  { name: 'icon',   mode: 'replace', doc: 'A custom leading icon (any inline SVG, inherits `currentColor`). Overrides the severity default and the `icon` prop, the same escape hatch as `kai-button`.' },
 ];
 
 /** Slots of `<kai-button>` (the label is the default slot). */
@@ -124,7 +124,7 @@ export const CHAT_PARTS: PartDef[] = [
 export const PROMPT_INPUT_PARTS: PartDef[] = [
   {
     name: 'send',
-    doc: 'The send button. Restyle from outside, or hide it entirely (Enter-only) — hiding is pure CSS, which is why there is no `submit="never"`.',
+    doc: 'The send button. Restyle from outside, or hide it entirely (Enter-only). Hiding is pure CSS, which is why there is no `submit="never"`.',
     recipe: 'kai-prompt-input::part(send) { display: none } /* Enter-only; or restyle: background, border-radius, … */',
   },
 ];
@@ -206,13 +206,18 @@ export const MESSAGE_PARTS: PartDef[] = [
     doc: 'The action-bar row (copy / like / regenerate …). Restyle its spacing or hide it entirely from outside.',
     recipe: 'kai-message::part(actions) { gap: 0.25rem }',
   },
+  {
+    name: 'citations',
+    doc: 'The citation row rendered from the message’s `source` parts: a wrapped row of chips below the bubble, never inside it. Restyle its spacing or hide it entirely from outside.',
+    recipe: 'kai-message::part(citations) { gap: 0.5rem }',
+  },
 ];
 
 /** Styleable `::part`s of `<kai-attachments>`. */
 export const ATTACHMENTS_PARTS: PartDef[] = [
   {
     name: 'preview',
-    doc: 'The image shown in an attachment’s hover-card preview. Bounded by default (max ~320×256, aspect preserved) so a large image never blows up the card — raise or lower the cap from outside.',
+    doc: 'The image shown in an attachment’s hover-card preview. Bounded by default (max ~320×256, aspect preserved) so a large image never blows up the card. Raise or lower the cap from outside.',
     recipe: 'kai-attachments::part(preview) { max-width: 32rem; max-height: 24rem }',
   },
 ];
@@ -434,6 +439,17 @@ export const FILE_TREE_PARTS: PartDef[] = [
 export interface ElementComposition {
   slots?: SlotDef[];
   parts?: PartDef[];
+  /**
+   * What the element's DEFAULT (unnamed) `<slot>` projects — i.e. what a consumer
+   * puts between the tags. Kept OUT of `slots` on purpose: those arrays are also
+   * read at runtime by `readSlots()`, which would query a meaningless `[slot=""]`.
+   * scripts/gen-element-api.mjs merges it back in as a slot with the empty name,
+   * which is how the Custom Elements Manifest spells the default slot.
+   *
+   * Every facade that renders a bare `<slot />` needs one; guarded by
+   * tests/elements/slot-registry-coverage.test.ts.
+   */
+  children?: string;
 }
 
 /** Slots + styleable `::part`s of `<kai-prompt-dock>`. */
@@ -558,6 +574,17 @@ export const THREAD_SLOTS: SlotDef[] = [
   { name: 'empty', mode: 'replace', doc: 'Custom zero-state rendered in the message area while the thread is empty; replaces the built-in default.' },
 ];
 
+/** Slots of `<kai-empty>`. The body is the default slot; `media` is the named seam. */
+export const EMPTY_SLOTS: SlotDef[] = [
+  { name: 'media', mode: 'replace', doc: 'The leading illustration or icon above the title (any inline SVG or <img>). Replaces the built-in media box.' },
+];
+
+/** Slots of `<kai-popover>`. The panel body is the default slot; `trigger` is the
+ *  control the panel anchors to and opens from. */
+export const POPOVER_SLOTS: SlotDef[] = [
+  { name: 'trigger', mode: 'replace', doc: 'The control that opens the popover (a button, an avatar, …). The panel anchors to it.' },
+];
+
 /** Styleable `::part`s of `<kai-audio-visualizer>`. Every DOM variant (`bar`,
  *  `grid`, `radial`) shares the `bar`/`cell` markup pattern; the shader variants
  *  (`wave`, `aurora`) share the `canvas` part. Lit items ALSO carry the
@@ -599,38 +626,44 @@ export const ELEMENT_COMPOSITION: Record<string, ElementComposition> = {
   'kai-message': { slots: MESSAGE_SLOTS, parts: MESSAGE_PARTS },
   'kai-thread': { slots: THREAD_SLOTS },
   'kai-prompt-input': { slots: PROMPT_INPUT_SLOTS, parts: PROMPT_INPUT_PARTS },
-  'kai-button': { slots: BUTTON_SLOTS, parts: BUTTON_PARTS },
-  'kai-badge': { parts: BADGE_PARTS },
+  'kai-button': { slots: BUTTON_SLOTS, parts: BUTTON_PARTS, children: 'The button\'s label. Omit it for an icon-only button (pair with `aria-label`).' },
+  'kai-badge': { parts: BADGE_PARTS, children: 'The badge\'s label: text, or a small inline icon plus text.' },
   'kai-icon': { parts: ICON_PARTS },
   'kai-separator': { parts: SEPARATOR_PARTS },
-  'kai-scroll-area': { parts: SCROLL_AREA_PARTS },
-  'kai-notice': { slots: NOTICE_SLOTS },
-  'kai-hover-card': { slots: HOVER_CARD_SLOTS },
+  'kai-scroll-area': { parts: SCROLL_AREA_PARTS, children: 'The scrollable content.' },
+  'kai-notice': { slots: NOTICE_SLOTS, children: 'The notice message. `icon` and `action` are the named seams around it.' },
+  'kai-hover-card': { slots: HOVER_CARD_SLOTS, children: 'The TRIGGER the card hovers off. The card body is the `card` slot.' },
   'kai-menu': { slots: MENU_SLOTS, parts: MENU_PARTS },
   'kai-skeleton': { parts: SKELETON_PARTS },
   'kai-attachments': { parts: ATTACHMENTS_PARTS },
   'kai-status': { parts: STATUS_PARTS },
   'kai-tabs': { parts: TABS_PARTS },
   'kai-voice-output': { parts: VOICE_OUTPUT_PARTS },
-  'kai-screen': { slots: SCREEN_SLOTS, parts: SCREEN_PARTS },
-  'kai-card': { slots: CARD_SLOTS, parts: CARD_PARTS },
+  'kai-screen': { slots: SCREEN_SLOTS, parts: SCREEN_PARTS, children: 'The screen body, below the title bar.' },
+  'kai-card': { slots: CARD_SLOTS, parts: CARD_PARTS, children: 'The card body, below the header/media regions.' },
   'kai-workspace': { slots: WORKSPACE_SLOTS, parts: WORKSPACE_PARTS },
   'kai-nav': { parts: NAV_PARTS },
-  'kai-coachmark': { slots: COACHMARK_SLOTS, parts: COACHMARK_PARTS },
+  'kai-coachmark': { slots: COACHMARK_SLOTS, parts: COACHMARK_PARTS, children: 'The ANCHOR the coachmark points at: the element it attaches to and positions against. The bubble body is the `content` slot.' },
   'kai-progress-bar': { parts: PROGRESS_BAR_PARTS },
   'kai-file-tree': { parts: FILE_TREE_PARTS },
-  'kai-prompt-dock': { slots: PROMPT_DOCK_SLOTS, parts: PROMPT_DOCK_PARTS },
+  'kai-prompt-dock': { slots: PROMPT_DOCK_SLOTS, parts: PROMPT_DOCK_PARTS, children: 'The input the dock wraps, typically a `<kai-prompt-input>`. The `top`/`bottom` slots are the lips around it.' },
   'kai-segmented': { parts: SEGMENTED_PARTS },
-  'kai-settings-group': { parts: SETTINGS_GROUP_PARTS },
+  'kai-settings-group': { parts: SETTINGS_GROUP_PARTS, children: 'The `<kai-setting-item>` rows in this group.' },
   'kai-setting-item': { slots: SETTING_ITEM_SLOTS, parts: SETTING_ITEM_PARTS },
-  'kai-pane': { slots: PANE_SLOTS, parts: PANE_PARTS },
-  'kai-pane-group': { parts: PANE_GROUP_PARTS },
+  'kai-pane': { slots: PANE_SLOTS, parts: PANE_PARTS, children: 'The pane body, below the header row.' },
+  'kai-pane-group': { parts: PANE_GROUP_PARTS, children: 'Content shown for every tab. Use it INSTEAD of the per-tab `slot="<tab id>"` seams when you swap the content yourself.' },
   'kai-agent-card': { parts: AGENT_CARD_PARTS },
-  'kai-dialog': { slots: DIALOG_SLOTS, parts: DIALOG_PARTS },
+  'kai-dialog': { slots: DIALOG_SLOTS, parts: DIALOG_PARTS, children: 'The dialog body, between the `header` and `footer` slots.' },
   'kai-input': { slots: INPUT_SLOTS, parts: INPUT_PARTS },
   'kai-search': { parts: SEARCH_PARTS },
-  'kai-kbd': { parts: KBD_PARTS },
+  'kai-kbd': { parts: KBD_PARTS, children: 'Literal key text, when you are not using the `keys` prop to render key caps.' },
   'kai-editable-label': { parts: EDITABLE_LABEL_PARTS },
+  'kai-empty': { slots: EMPTY_SLOTS, children: 'The empty-state body below the title/description, usually the call to action.' },
+  'kai-file-upload': { children: 'Custom dropzone content, replacing the default label (the `label` prop is the fallback).' },
+  'kai-popover': { slots: POPOVER_SLOTS, children: 'The popover panel body. The control that opens it is the `trigger` slot.' },
+  'kai-resizable': { children: 'The `<kai-resizable-item>` panels, in order. Dividers are inserted between them.' },
+  'kai-resizable-item': { children: 'This panel\'s content.' },
+  'kai-tooltip': { children: 'The TRIGGER the tooltip describes. The tip text is the `text` prop.' },
   'kai-audio-visualizer': { parts: AUDIO_VISUALIZER_PARTS },
 };
 

package/src/elements/source.tsx

@@ -1,6 +1,9 @@
 import { createSignal, For, onCleanup, onMount, Show } from 'solid-js';
 import { defineWebComponent } from './define';
 import { Source, SourceTrigger, SourceContent, SourceList } from '../components/source';
+// Public shape of the `sources` prop; lives in ./element-data-types so the ROOT
+// entry can re-export it (see that file's header).
+import type { KaiSourceItem } from './element-data-types';
 
 // --- <kai-source> — a single citation link with hover preview ---
 
@@ -9,8 +12,9 @@ interface SourceProps extends Record<string, unknown> {
   href?: string;
   /** Trigger label (defaults to the domain). */
   label?: string;
-  /** Hover-card headline. Attribute: `headline` (`title` is avoided — it's a
-   *  global HTML attribute that reflects in a CE constructor and breaks it). */
+  /** Hover-card headline. Attribute: `headline` (`title` is avoided because it
+   *  is a global HTML attribute that reflects in a CE constructor and breaks
+   *  it). */
   headline?: string;
   /** Hover-card body text describing the source. */
   description?: string;
@@ -42,17 +46,12 @@ defineWebComponent<SourceProps>('kai-source', {
 
 // --- <kai-sources> — a wrapped list of citation links ---
 
-interface SourceItem {
-  href: string;
-  title?: string;
-  description?: string;
-  label?: string;
-  showFavicon?: boolean;
-}
 
 interface SourceListProps extends Record<string, unknown> {
-  /** The sources to render. Set as a JS property. */
-  sources: SourceItem[];
+  /** The sources to render. Set as a JS property. Omit to supply them as
+   *  `<kai-source>` light-DOM children instead; when both are present the
+   *  property's sources come first. */
+  sources?: KaiSourceItem[];
   /** Show favicons on all items (per-item `showFavicon` overrides). */
   showFavicon?: boolean;
   /**
@@ -60,22 +59,22 @@ interface SourceListProps extends Record<string, unknown> {
    * merged (prop + declarative-children) list (`[1]`, `[2]`, …) instead of the
    * per-item `label` or domain fallback.
    *
-   * HTML attribute: `numbered` (boolean — bare attribute or `numbered="true"`).
-   * JS property:   `el.numbered = true`.
+   * HTML attribute: `numbered` (boolean: a bare attribute or
+   * `numbered="true"`). JS property:   `el.numbered = true`.
    */
   numbered?: boolean;
 }
 
-/** Parse a single light-DOM `<kai-source>` element into a `SourceItem` descriptor.
+/** Parse a single light-DOM `<kai-source>` element into a `KaiSourceItem` descriptor.
  *  Attribute mapping:
- *   - `href`        → SourceItem.href
- *   - `label`       → SourceItem.label
- *   - `headline`    → SourceItem.title  (matches kai-source's prop name; "title" is a
+ *   - `href`        → KaiSourceItem.href
+ *   - `label`       → KaiSourceItem.label
+ *   - `headline`    → KaiSourceItem.title  (matches kai-source's prop name; "title" is a
  *                       reserved HTMLElement attribute so kai-source uses "headline")
- *   - `description` → SourceItem.description
- *   - `show-favicon`→ SourceItem.showFavicon (bare boolean attribute)
+ *   - `description` → KaiSourceItem.description
+ *   - `show-favicon`→ KaiSourceItem.showFavicon (bare boolean attribute)
  */
-export function parseKaiSourceElement(n: Element): SourceItem {
+export function parseKaiSourceElement(n: Element): KaiSourceItem {
   return {
     href: n.getAttribute('href') ?? '',
     label: n.getAttribute('label') ?? undefined,
@@ -92,7 +91,7 @@ defineWebComponent<SourceListProps>('kai-sources', {
 }, (props, { element, flag }) => {
   // Read declarative <kai-source> children from light DOM.
   // The shadow root has no <slot> for them, so they are invisible — pure data carriers.
-  const [slottedSources, setSlottedSources] = createSignal<SourceItem[]>([]);
+  const [slottedSources, setSlottedSources] = createSignal<KaiSourceItem[]>([]);
   onMount(() => {
     const read = () => {
       const nodes = [...element.querySelectorAll('kai-source')];
@@ -105,7 +104,7 @@ defineWebComponent<SourceListProps>('kai-sources', {
   });
 
   // Prop sources take precedence; slotted children are appended after.
-  const allSources = () => [...props.sources, ...slottedSources()];
+  const allSources = () => [...(props.sources ?? []), ...slottedSources()];
 
   const isNumbered = () => flag('numbered');
 

package/src/elements/switch.tsx

@@ -3,9 +3,9 @@ import { defineWebComponent } from './define';
 import { Switch } from '../ui/switch';
 
 interface Props extends Record<string, unknown> {
-  /** Controlled checked state — settable and reflected to the `checked`
-   *  attribute. `el.checked = true` (or `<kai-switch checked>`) drives it; the
-   *  toggle UI updates it and fires `kai-change`. Read `el.checked` for live state. */
+  /** Controlled checked state. Settable and reflected to the `checked` attribute.
+   *  `el.checked = true` (or `<kai-switch checked>`) drives it; the toggle UI updates
+   *  it and fires `kai-change`. Read `el.checked` for live state. */
   checked?: boolean;
   /** Initial checked state on mount (uncontrolled seed). Bare attribute
    *  (`<kai-switch default-checked>`) turns it on. */

package/src/elements/tasks.tsx

@@ -6,7 +6,7 @@ interface Props extends Record<string, unknown> {
   /** The tasks definition (the CardEnvelope.data). Set as a JS PROPERTY:
    *  `el.data = { tasks:[…], selectAll, confirmLabel, … }`. Import
    *  `TasksCardData` from `@kitn.ai/ui` for the full shape. */
-  data?: Record<string, unknown>;
+  data?: TasksCardData;
   /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
   cardId?: string;
   /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
@@ -29,7 +29,8 @@ interface Props extends Record<string, unknown> {
  *  contract event — `kai-value-change` is the live selection signal, distinct from
  *  the terminal submit.) */
 interface Events {
-  /** The selection changed on a toggle — the selected ids in input order. */
+  /** The selection changed on a toggle. Carries the selected ids in input
+   *  order. */
   'kai-value-change': { value: string[] };
 }
 
@@ -72,7 +73,7 @@ defineWebComponent<Props, Events>(
       select: (taskIds?: string[]) => controller?.select(taskIds),
       /** Toggle one task by id, honoring the max gate (no `checked` = flip). */
       toggle: (taskId: string, checked?: boolean) => controller?.toggle(taskId, checked),
-      /** Confirm the current selection — emits the `submit` CardEvent + resolves
+      /** Confirm the current selection: emits the `submit` CardEvent + resolves
        *  (only when the min/max gate passes). Named `send`, not `submit`. */
       send: () => controller?.send(),
       /** Focus the task group (select-all checkbox if shown, else the first row). */
@@ -85,7 +86,7 @@ defineWebComponent<Props, Events>(
 
     return (
       <TasksCard
-        data={props.data as TasksCardData | undefined}
+        data={props.data}
         cardId={props.cardId ?? (element.id || 'kai-tasks')}
         heading={props.heading}
         resolution={props.resolution as CardResolution | undefined}

package/src/elements/thread.tsx

@@ -2,17 +2,19 @@ import { createSignal, onMount, onCleanup } from 'solid-js';
 import { defineWebComponent } from './define';
 import { readSlots, THREAD_SLOTS } from './slots';
 import { Thread, type ThreadController } from '../components/thread';
+import { cardComponentsFromTags } from './message';
+import { createMessagesGuard } from './validate-messages';
 import type { ChatMessage } from './chat-types';
 import type { ProseSize } from '../primitives/chat-config';
 
 interface Props extends Record<string, unknown> {
   /** The full message thread to render, newest last. Each entry carries its role,
-   *  content, and optional reasoning/tools/attachments/actions/avatar. Set as a JS
+   *  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). */
   messages?: ChatMessage[];
-  /** Show a typing indicator on the pending assistant turn — set while awaiting
-   *  the assistant's reply. */
+  /** Show a typing indicator on the pending assistant turn. Set it while
+   *  awaiting the assistant's reply. */
   loading?: boolean;
   /** Body/prose font scale for rendered markdown (`'xs' | 'sm' | 'base' | 'lg'`).
    *  Defaults to `'sm'`. */
@@ -30,6 +32,26 @@ interface Props extends Record<string, unknown> {
   scrollButton?: boolean;
   /** Extra classes applied to the thread's inner root. */
   class?: 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>;
 }
 
 /** Events fired by `<kai-thread>`. */
@@ -61,9 +83,17 @@ defineWebComponent<Props, Events>('kai-thread', {
   actionsReveal: 'always',
   scrollButton: true,
   class: undefined,
+  cardTypes: undefined,
+  cardSchemas: undefined,
 }, (props, { element, dispatch, flag, expose }) => {
   let controller: ThreadController | undefined;
 
+  // `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 element instead of one message.
+  const validMessages = createMessagesGuard('kai-thread');
+
   // Detect whether the consumer projected `slot="empty"` content, so the built-in
   // default only renders when they did NOT.
   const [slots, setSlots] = createSignal<Record<string, boolean>>({});
@@ -89,13 +119,15 @@ defineWebComponent<Props, Events>('kai-thread', {
       <style>{':host{display:block;height:100%}'}</style>
       <Thread
         class={props.class as string | undefined}
-        messages={(props.messages as ChatMessage[] | undefined) ?? []}
+        messages={validMessages(props.messages)}
         loading={flag('loading')}
         proseSize={props.proseSize as ProseSize}
         codeTheme={props.codeTheme as string}
         codeHighlight={flag('codeHighlight')}
         actionsReveal={props.actionsReveal as 'always' | 'hover'}
         scrollButton={props.scrollButton !== false}
+        cardTypes={cardComponentsFromTags(props.cardTypes as Record<string, string> | undefined, (props as { theme?: string }).theme)}
+        cardSchemas={props.cardSchemas as Record<string, object> | undefined}
         empty={slots()['empty'] ? <slot name="empty" /> : undefined}
         onMessageAction={(detail) => dispatch('kai-message-action', detail)}
         controllerRef={(c) => (controller = c)}

package/src/elements/toast.tsx

@@ -4,8 +4,9 @@ import { toast as toastStore, type ToastItem } from '../primitives/toast-store';
 
 interface Props extends Record<string, unknown> {
   /** The toasts to render. Newest is shown on top. Set as a JS property (array);
-   *  pass a new array reference to update. */
-  toasts: ToastItem[];
+   *  pass a new array reference to update. Omit for an empty region, which is
+   *  the normal resting state and how the imperative `toast()` API starts. */
+  toasts?: ToastItem[];
   /** Stack anchor: `'top-center'` (default), `'top-right'`, `'bottom-center'`, … */
   position?: ToastPosition;
   /** Max simultaneously-visible toasts; the rest queue. Defaults to `3`. */

package/src/elements/tool.tsx

@@ -13,7 +13,7 @@ interface Props extends Record<string, unknown> {
   open?: boolean;
   /** Initial open state on mount (uncontrolled seed). */
   defaultOpen?: boolean;
-  /** Gate the disclosure trigger — programmatic `show()/hide()/toggle()` still
+  /** Gate the disclosure trigger: programmatic `show()/hide()/toggle()` still
    *  work, but the trigger click no longer toggles. */
   disabled?: boolean;
 }