@kitn.ai/ui 0.20.1 → 0.22.0

package/src/elements/prompt-suggestions.tsx

@@ -6,16 +6,19 @@ type Item = string | { label: string; value?: string; icon?: string };
 
 interface Props extends Record<string, unknown> {
   /** The suggestions. Strings, or `{ label, value }` when the displayed text
-   *  and the emitted value differ. Set as a JS property. */
-  suggestions: Item[];
+   *  and the emitted value differ. Set as a JS property. Omit to supply them as
+   *  `<kai-suggestion>` light-DOM children instead; when both are present the
+   *  property's suggestions come first. */
+  suggestions?: Item[];
   /** Chip style: `'outline'` (default), `'ghost'`, or `'default'` (filled). */
   variant?: 'outline' | 'ghost' | 'default';
   /** Row height for `layout="list"`: `'md'` (default) or `'lg'` for taller rows.
    *  Chips are unaffected. */
   size?: 'md' | 'lg';
   /** Layout: `'chips'` (default) renders a wrapping row of rounded pills;
-   *  `'list'` renders a vertical, full-width "Ideas for you" list — each row
-   *  is left-aligned with a leading `icon`, a label, and a hover background. */
+   *  `'list'` renders a vertical, full-width "Ideas for you" list where each
+   *  row is left-aligned with a leading `icon`, a label, and a hover
+   *  background. */
   layout?: 'chips' | 'list';
   /** Full-width left-aligned rows instead of pills. */
   block?: boolean;

package/src/elements/reasoning.tsx

@@ -18,7 +18,7 @@ interface Props extends Record<string, unknown> {
   streaming?: boolean;
   /** Render `text` as markdown. */
   markdown?: 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;
 }

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/slot-text.ts

@@ -0,0 +1,73 @@
+import { createSignal, type Accessor } from 'solid-js';
+
+/**
+ * Track whether a `<slot>` is projecting VISIBLE TEXT, so a facade can tell
+ * "this control shows its own name" from "this control is icon-only and needs
+ * one".
+ *
+ * WHY IT EXISTS. Slotted light-DOM text is part of the flattened tree, so it
+ * names the shadow `<button>` all by itself — measured, not assumed:
+ * `scripts/probe-button-accessible-name.mjs` reads chromium's AX tree and
+ * `<kai-button>Save</kai-button>` computes the name "Save" from `contents`,
+ * with no `aria-label` anywhere. An `aria-label` on top of that does not add a
+ * name, it REPLACES one, and a replacement that disagrees with the visible text
+ * is a WCAG 2.5.3 (Label in Name) failure: speech-input users say what they
+ * see, so a button reading "Save" whose accessible name is "Submit" cannot be
+ * activated by voice at all. `kai-checkpoint` already resolved this the same
+ * way; this is the reusable form of that decision.
+ *
+ * WHY A SIGNAL AND NOT A ONE-OFF READ. The facade renders while the HTML parser
+ * is still inside the element's own tag, so the light DOM is usually EMPTY at
+ * that moment and any synchronous read of `element.childNodes` reports "no text"
+ * for the most common case there is. `slotchange` is the event that tells the
+ * truth, and it fires on the initial assignment too.
+ *
+ * The initial value is therefore `false`, meaning "assume icon-only", which
+ * makes the pre-`slotchange` frame emit the `aria-label`. That direction is
+ * deliberate: an overridden name is a defect, an ABSENT name is a worse one, so
+ * the transient state is the named one. `slotchange` is queued as a mutation
+ * observer microtask, so it lands before paint and no assistive technology
+ * observes the transient.
+ */
+export function createSlotText(options: {
+  /**
+   * Follow `assignedNodes({ flatten: true })`, which descends into nested
+   * light-DOM `<slot>` elements (a consumer wrapping the element in their OWN
+   * component and forwarding a slot) — and, when nothing is assigned, returns
+   * the slot's FALLBACK content.
+   *
+   * Only safe on a slot whose fallback is exactly the visible label. Do NOT set
+   * it on a slot whose fallback can render a non-name (an icon that happens to
+   * be plain text, say): the fallback would count as visible text and suppress
+   * the very `aria-label` that names the control. `kai-button`'s default slot
+   * has no fallback at all, so flatten there only buys the nested case;
+   * `kai-menu`'s trigger slot falls back to an icon, so it must not use it.
+   */
+  flatten?: boolean;
+} = {}): {
+  /** Whether the slot is currently showing text. */
+  hasText: Accessor<boolean>;
+  /** `ref` for the `<slot>`. Re-reads on every `slotchange`. */
+  ref: (slot: HTMLSlotElement) => void;
+} {
+  const [hasText, setHasText] = createSignal(false);
+
+  const read = (slot: HTMLSlotElement) => {
+    const nodes = slot.assignedNodes({ flatten: options.flatten ?? false });
+    setHasText(nodes.some((node) => (node.textContent ?? '').trim() !== ''));
+  };
+
+  return {
+    hasText,
+    ref: (slot: HTMLSlotElement) => {
+      // A slot outside a shadow root assigns nothing, and this ref runs before
+      // solid inserts it — so this first read is normally `false` and the
+      // slotchange below is what carries the answer. It is here for the case
+      // where the element is created with its children already in place
+      // (`el.textContent = 'Save'` then appended), where no assignment CHANGE
+      // happens after insertion and slotchange may never fire.
+      read(slot);
+      slot.addEventListener('slotchange', () => read(slot));
+    },
+  };
+}

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 }',
   },
 ];
@@ -395,6 +400,15 @@ export const PROGRESS_BAR_PARTS: PartDef[] = [
   { name: 'fill', doc: 'The filled portion; its width follows value/max. Recolor it from outside.', recipe: 'kai-progress-bar::part(fill) { background: var(--color-tool-green) }' },
 ];
 
+/** Styleable `::part`s of `<kai-context>`. The usage meter is the same shared
+ *  ProgressBar `<kai-progress-bar>` renders, mounted inside this element's own
+ *  shadow root, so `kai-context` exposes the same two names. Both sit inside the
+ *  hover-card breakdown and are in the DOM only while that card is open. */
+export const CONTEXT_PARTS: PartDef[] = [
+  { name: 'track', doc: 'The usage meter track inside the hover-card breakdown. Carries `role="progressbar"` and is in the DOM only while the card is open. Restyle its height, radius, or background from outside.', recipe: 'kai-context::part(track) { height: 0.5rem }' },
+  { name: 'fill', doc: 'The used-tokens portion of that meter. Its width follows `usedTokens / maxTokens`; its default color is the severity hue picked by `warnThreshold` / `dangerThreshold`, so recoloring it from outside replaces that signal.', recipe: 'kai-context::part(fill) { background: var(--color-tool-blue) }' },
+];
+
 /** Styleable `::part`s of `<kai-file-tree>` — the changed-files / diff bits, shown
  *  only when a file carries diff metadata (or the `summary` attribute is set). */
 export const FILE_TREE_PARTS: PartDef[] = [
@@ -434,6 +448,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 +583,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 +635,45 @@ 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-context': { parts: CONTEXT_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. */