@kitn.ai/ui 0.20.0 → 0.21.0

package/src/elements/composer.tsx

@@ -31,7 +31,7 @@ export function parseKaiTriggerItemElement(n: Element, char: string, kind: strin
 }
 
 interface Props extends Record<string, unknown> {
-  /** Controlled value — string or a full ComposerDoc (set as JS property). */
+  /** Controlled value: a string or a full ComposerDoc (set as JS property). */
   value?: string | ComposerDoc;
   /** Placeholder text shown when the composer is empty. */
   placeholder?: string;
@@ -43,9 +43,9 @@ interface Props extends Record<string, unknown> {
   maxHeight?: number | string;
   /** Whether pressing Enter (without Shift) submits. Default true. */
   submitOnEnter?: boolean;
-  /** Trigger definitions — set as a JS property. */
+  /** Trigger definitions. Set as a JS property. */
   triggers?: TriggerDef[];
-  /** Keyword highlight rules — set as a JS property. */
+  /** Keyword highlight rules. Set as a JS property. */
   highlights?: HighlightRule[];
   /** Default icon per entity kind (kind → image URL/data-URI) for items without
    *  their own `icon`. Overrides the built-in agent/plugin glyphs. JS property. */
@@ -67,7 +67,7 @@ interface Events {
   /** The active trigger was dismissed (Escape, space, or outside click). */
   'kai-trigger-close': Record<string, never>;
   /** The composer gained focus. `focus`/`blur` are NOT composed natively, so they
-   *  don't escape the shadow root — these re-expose them on the host. (For
+   *  don't escape the shadow root; these re-expose them on the host. (For
    *  `keydown`/`paste`/`focusin`/`focusout`, listen NATIVELY on `<kai-composer>`:
    *  they're composed and already cross the shadow boundary.) */
   'kai-focus': { originalEvent: FocusEvent };
@@ -100,7 +100,7 @@ defineWebComponent<Props, Events>('kai-composer', {
   let controller: ComposerController | undefined;
   expose({
     /** Focus the editable element. `focus`/`blur` are NOT composed natively, so a
-     *  host-level focus() can't reach the editable inside the shadow root — this is
+     *  host-level focus() can't reach the editable inside the shadow root. This is
      *  the only way to focus the composer programmatically. */
     focus: (options?: FocusOptions) => controller?.focus(options),
     /** Blur the editable element. */
@@ -108,9 +108,9 @@ defineWebComponent<Props, Events>('kai-composer', {
     /** Empty the composer to a blank doc (resets the internal value + history
      *  baseline; fires kai-value-change). */
     clear: () => controller?.clear(),
-    /** Submit the current content programmatically — same path as Enter (fires
-     *  kai-submit). Named `send`, not `submit`, to match the shared vocabulary and
-     *  avoid any submit collision. */
+    /** Submit the current content programmatically, on the same path as Enter
+     *  (fires kai-submit). Named `send`, not `submit`, to match the shared
+     *  vocabulary and avoid any submit collision. */
     send: () => controller?.send(),
     /** Insert an atomic entity pill (skill/agent/plugin) at the caret without
      *  typing a trigger (fires kai-entity-add). */

package/src/elements/confirm-card.tsx

@@ -6,13 +6,13 @@ interface Props extends Record<string, unknown> {
   /** The confirm definition (the CardEnvelope.data). Set as a JS PROPERTY:
    *  `el.data = { body, tone, actions:[…] }`. Import `ConfirmCardData` from
    *  `@kitn.ai/ui` for the full shape. */
-  data?: Record<string, unknown>;
+  data?: ConfirmCardData;
   /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
   cardId?: string;
   /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
   heading?: string;
-  /** Focus the default action on mount (off by default — no focus-stealing).
-   *  Attribute: `autofocus`. */
+  /** Focus the default action on mount (off by default, so nothing steals
+   *  focus). Attribute: `autofocus`. */
   autofocus?: boolean;
   /** Set when the user resolved this card; renders the read-only view. Property:
    *  `el.resolution = { kind:'action', action:'…' }`. */
@@ -48,22 +48,22 @@ defineWebComponent<Props>(
     // `dismiss`/`reopen`).
     let controller: ConfirmController | undefined;
     expose({
-      /** Focus the default action button (or the first action if none is default) —
-       *  the same target `autofocus` focuses on mount, but on demand. */
+      /** Focus the default action button (or the first action if none is default).
+       *  The same target `autofocus` focuses on mount, but on demand. */
       focus: (options?: FocusOptions) => controller?.focus(options),
-      /** Activate an action by id — emits the `action` verb on kai-card and resolves
+      /** Activate an action by id: emits the `action` verb on kai-card and resolves
        *  the card (single-shot). With no id, invokes the default action. */
       confirm: (actionId?: string) => controller?.confirm(actionId),
-      /** Trigger the dismiss path — emits `dismiss` on kai-card and optimistically
+      /** Trigger the dismiss path: emits `dismiss` on kai-card and optimistically
        *  collapses the card to its re-openable stub. */
       dismiss: () => controller?.dismiss(),
-      /** Re-open a dismissed card from its stub — emits `reopen` on kai-card. */
+      /** Re-open a dismissed card from its stub: emits `reopen` on kai-card. */
       reopen: () => controller?.reopen(),
     });
 
     return (
       <ConfirmCard
-        data={props.data as ConfirmCardData | undefined}
+        data={props.data}
         cardId={props.cardId ?? (element.id || 'kai-confirm')}
         heading={props.heading}
         autofocus={flag('autofocus')}

package/src/elements/context-meter.tsx

@@ -16,27 +16,13 @@ import {
   DEFAULT_DANGER_THRESHOLD,
   type ContextSeverity,
 } from '../components/context';
-
-interface ContextUsage {
-  /** Tokens consumed so far in the context window (drives the meter fill). */
-  usedTokens: number;
-  /** The model's total context-window size in tokens. */
-  maxTokens: number;
-  /** Tokens attributed to the prompt/input, shown in the breakdown. */
-  inputTokens?: number;
-  /** Tokens attributed to the generated output, shown in the breakdown. */
-  outputTokens?: number;
-  /** Tokens attributed to reasoning/thinking, shown when present. */
-  reasoningTokens?: number;
-  /** Tokens served from prompt cache, shown when present. */
-  cacheTokens?: number;
-  /** Estimated cost in dollars for this usage, shown in the footer. */
-  estimatedCost?: number;
-}
+// Public shape of the `context` prop; lives in ./element-data-types so the ROOT
+// entry can re-export it (see that file's header).
+import type { KaiContextUsage } from './element-data-types';
 
 interface Props extends Record<string, unknown> {
   /** Token-usage data. Set as a JS property. */
-  context?: ContextUsage;
+  context?: KaiContextUsage;
   /**
    * Fraction (0–1) above which the meter turns yellow.
    * Defaults to `0.7` (70%).

package/src/elements/conversation-list.tsx

@@ -6,13 +6,18 @@ import { ConversationList, CollapsedRail, type ConversationListController } from
 import type { ConversationGroup, ConversationSummary, ConversationScope } from '../types';
 
 interface Props extends Record<string, unknown> {
-  /** Pre-bucketed conversation groups (e.g. "Today", "Yesterday"), each with its
-   *  own conversations. Use this when you want to control the grouping/headers
-   *  yourself; otherwise pass a flat `conversations` array. Set as a JS property. */
-  groups: ConversationGroup[];
-  /** A flat list of conversation summaries; the component buckets them by recency
-   *  for you. Ignored when `groups` is provided. Set as a JS property. */
-  conversations: ConversationSummary[];
+  /** The list's section headers (`{ id, name, sortOrder, createdAt }`), rendered
+   *  in array order. A group carries no conversations of its own; it is matched
+   *  against `conversations` by id, so the two props are complementary rather
+   *  than alternatives. Omit for an ungrouped list. Set as a JS property. */
+  groups?: ConversationGroup[];
+  /** Every conversation the list renders, flat. Each one is filed under the group
+   *  whose `id` equals its `groupId`; one with no `groupId`, or with a `groupId`
+   *  matching no entry in `groups`, falls into a trailing "Ungrouped" section, so
+   *  nothing you pass in is ever dropped. There is no recency bucketing. Set as a
+   *  JS property. Omit to supply them as `<kai-conversation>` light-DOM children
+   *  instead, or for the empty state. */
+  conversations?: ConversationSummary[];
   /** The id of the currently-open conversation, highlighted in the list. */
   activeId?: string;
   /** Controlled collapsed state. Set as a JS property (`el.collapsed = true`) to
@@ -115,7 +120,7 @@ defineWebComponent<Props, Events>('kai-conversations', {
     /** Clear the internal search query (resets the list filter) and fire
      *  kai-search with an empty string. */
     clear: () => controller?.clearSearch(),
-    /** Programmatically select a conversation by id — mirror of the
+    /** Programmatically select a conversation by id. The mirror of the
      *  kai-conversation-select event (a convenience over driving `activeId`). */
     select: (id: string) => dispatch('kai-conversation-select', { id }),
     /** Collapse the rail to its floating reopen button (fires `kai-collapse-toggle`). */
@@ -132,7 +137,7 @@ defineWebComponent<Props, Events>('kai-conversations', {
       fallback={<CollapsedRail onExpand={() => setCollapsedTo(false)} />}
     >
       <ConversationList
-        groups={props.groups}
+        groups={props.groups ?? []}
         conversations={allConversations()}
         activeId={props.activeId}
         onSelect={(id) => dispatch('kai-conversation-select', { id })}

package/src/elements/default-input.tsx

@@ -36,9 +36,9 @@ export interface DefaultPromptInputProps {
   /** Show a Voice (Mic) button in the left toolbar; calls `onVoice`. */
   voice?: 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';
   onValueChange: (v: string) => void;

package/src/elements/define.tsx

@@ -96,6 +96,147 @@ function toAttr(name: string): string {
   return name.replace(/([A-Z])/g, '-$1').toLowerCase();
 }
 
+/**
+ * Every property name the built-in element prototype chain exposes as an ACCESSOR
+ * — `role`, `hidden`, `autofocus`, `dir`, `title`, `className`, … — i.e. the
+ * reflected IDL attributes plus the handful of read-only accessors. Methods
+ * (`focus`, `append`) are plain data properties and are deliberately not included:
+ * assigning over one shadows it on the instance but destroys nothing on the DOM.
+ *
+ * DERIVED, not listed. A hand-written list is a list someone has to remember to
+ * extend: the collision set is (this element's prop names) × (whatever the browser
+ * reflects), and both sides move — the kit adds props, and the platform keeps
+ * adding globals (`inert`, `popover`, `writingSuggestions` are all recent). Reading
+ * it off the live prototype chain means a prop that starts colliding tomorrow is
+ * protected the day it lands, in whichever engines have shipped the accessor,
+ * without a code change. It also self-limits: in an engine that has NOT shipped a
+ * given accessor (jsdom has no `autofocus`) the name is simply not a collision
+ * there, which is exactly right.
+ *
+ * Computed once — the chain does not change at runtime.
+ */
+let globalAccessorNames: Set<string> | undefined;
+export function reflectedGlobalPropNames(): Set<string> {
+  if (globalAccessorNames) return globalAccessorNames;
+  const names = new Set<string>();
+  let proto: object | null =
+    typeof HTMLElement === 'undefined' ? null : (HTMLElement.prototype as object);
+  while (proto && proto !== Object.prototype) {
+    for (const [name, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(proto))) {
+      if (descriptor.get || descriptor.set) names.add(name);
+    }
+    proto = Object.getPrototypeOf(proto) as object | null;
+  }
+  globalAccessorNames = names;
+  return names;
+}
+
+/**
+ * Replace inherited reflected accessors with plain, non-reflecting per-instance
+ * stores on this element class's prototype. Setting the property then only STORES
+ * the value — component-register still reads it back to seed the styling prop, and
+ * later shadows this with its own (also non-reflecting) instance accessor — and it
+ * can never touch a host attribute.
+ */
+function installNonReflectingProps(proto: object, keys: readonly string[]): void {
+  for (const key of keys) {
+    const store = Symbol(`kai-prop:${key}`);
+    Object.defineProperty(proto, key, {
+      get(this: Record<symbol, unknown>) {
+        return this[store];
+      },
+      set(this: Record<symbol, unknown>, value: unknown) {
+        this[store] = value;
+      },
+      enumerable: true,
+      configurable: true,
+    });
+  }
+}
+
+/**
+ * Run `define` (solid-element's `customElement`, which calls
+ * `customElements.define` internally) with `keys` already shadowed on the element
+ * class — BEFORE the registry ever sees it.
+ *
+ * THE ORDER IS THE WHOLE POINT. `customElements.define()` synchronously upgrades
+ * every matching element the parser has already produced, and component-register's
+ * constructor runs `this[prop] = undefined` for every declared prop. If the
+ * non-reflecting accessor is installed AFTER the define call, that assignment lands
+ * on the NATIVE setter, which for a reflected IDL attribute means the author's
+ * markup is destroyed before a line of facade code runs — `undefined` coerces to
+ * `null`/`false` and the setter removes the attribute. Measured in chromium from
+ * parsed HTML (`node scripts/probe-upgrade-attribute-loss.mjs`):
+ *
+ *   <kai-message role="user">        → role attr gone, el.role "assistant",
+ *                                      the row renders as "Assistant message"
+ *   <kai-resizable-item hidden>      → hidden attr gone, el.hidden false, the
+ *                                      panel is slotted and RENDERS VISIBLE
+ *   <kai-confirm autofocus>          → autofocus attr gone, nothing focused
+ *
+ * Two of those are silent: `hidden` and `autofocus` are legitimate global
+ * attributes, so no a11y rule and no console warning fires — the value simply
+ * evaporates. Only `role` was loud enough to get noticed.
+ *
+ * WHY A TRANSIENT REGISTRY WRAP and not something tidier: the class does not exist
+ * until `register()` builds it, and `register()` defines it in the same statement.
+ * component-register can take a `BaseElement` (a prototype we control) or a
+ * `customElements`-alike (a registry we control) via its third argument — either
+ * would be cleaner — but solid-element's `customElement()` calls `register(tag,
+ * props)` with no options and forwards nothing, and `component-register` is not a
+ * declared dependency of this package, so reaching past solid-element to call
+ * `register` ourselves would ship an undeclared import to consumers. Intercepting
+ * the one `define` call is the smallest seam that exists.
+ *
+ * The wrap is synchronous, restored in a `finally`, delegates to whatever was
+ * installed (so a polyfilled or consumer-wrapped registry keeps working), acts only
+ * on OUR tag, and is re-entrancy safe: a facade that defines another element during
+ * its upgrade nests a second wrap and unwinds it in order.
+ */
+function defineWithNonReflectingProps<T>(
+  tag: string,
+  keys: readonly string[],
+  define: () => T,
+): { result: T; handled: boolean } {
+  // `handled` = nothing more for the caller to do. With no colliding props there is
+  // nothing to install at all, so that case is trivially handled.
+  if (keys.length === 0) return { result: define(), handled: true };
+  const registry = customElements;
+  const hadOwnDefine = Object.prototype.hasOwnProperty.call(registry, 'define');
+  const inner = registry.define;
+  let handled = false;
+  let restore: (() => void) | undefined;
+  try {
+    registry.define = function (
+      this: CustomElementRegistry,
+      name: string,
+      constructor: CustomElementConstructor,
+      options?: ElementDefinitionOptions,
+    ) {
+      if (name === tag) {
+        installNonReflectingProps(constructor.prototype, keys);
+        handled = true;
+      }
+      return inner.call(this, name, constructor, options);
+    };
+    restore = () => {
+      if (hadOwnDefine) registry.define = inner;
+      else delete (registry as unknown as Record<string, unknown>).define;
+    };
+  } catch {
+    // A frozen registry (SES lockdown, a sealed polyfill, a hardened extension
+    // page): we cannot get ahead of define() there. Leave `handled` false so the
+    // caller installs on the returned class instead — the OLD, too-late timing, but
+    // registration itself still succeeds. Getting this wrong the other way would
+    // take all 80 elements down in that environment to fix three props in it.
+  }
+  try {
+    return { result: define(), handled };
+  } finally {
+    restore?.();
+  }
+}
+
 /** Underlying flag resolution; see `WebComponentContext.flag`. */
 function resolveFlag(element: HTMLElement, value: unknown, attribute: string): boolean {
   if (value === true) return true;
@@ -148,27 +289,33 @@ export function defineWebComponent<P extends Record<string, unknown>, E = Record
     }
   }
 
-  // Props that NAME a reflected global IDL accessor (today: only `role`, from
-  // ARIAMixin's Element.prototype.role). Unlike RESERVED (which throws), these are
-  // allowed as plain styling props, but they must NEVER reach the host as an
-  // attribute: kai-message uses role='user'|'assistant' to pick its layout, and
-  // those are not valid ARIA roles, so a reflected role="user" / role="assistant"
-  // fails axe's aria-roles rule. The native IDL setter reflects to an attribute
-  // whenever the property is set BEFORE connectedCallback (e.g. in a framework
-  // `ref`: `el.role = 'user'`), which is the window before component-register
-  // installs its own (non-reflecting) per-instance accessor in initializeProps. We
-  // shadow the native accessor on the element prototype with a plain non-reflecting
-  // one, so setting the property only STORES the value (component-register still
-  // reads it back for styling) and never touches a host attribute.
-  const NON_REFLECTING = ['role'];
+  // Every element gets a `theme` property/attribute. It drives a `.dark` class on
+  // an inner wrapper, which the injected kit CSS already styles — so dark mode
+  // works in standalone Shadow-DOM usage with no token duplication.
+  //
+  // The `as` annotation is load-bearing, not decoration: scripts/gen-element-api.mjs
+  // reads THIS object literal to learn which props every element gets for free, and
+  // takes each one's type and doc comment off the checker. Without it the inferred
+  // type is the literal `"auto"`. Add a universal prop here and it appears in
+  // element-meta.json, the generated .d.ts, custom-elements.json and llms-full.txt
+  // for all 79 elements, with no second list to update.
+  const defaults = {
+    /** Color mode (`auto` follows prefers-color-scheme). */
+    theme: 'auto' as 'light' | 'dark' | 'auto',
+    ...propDefaults,
+  };
 
-  // Every element gets a `theme` property/attribute: 'light' | 'dark' | 'auto'
-  // (default 'auto' = follow the OS `prefers-color-scheme`). It drives a `.dark`
-  // class on an inner wrapper, which the injected kit CSS already styles — so dark
-  // mode works in standalone Shadow-DOM usage with no token duplication.
-  const defaults = { theme: 'auto', ...propDefaults };
+  // Props that NAME a reflected global IDL accessor (today, across all 80 elements:
+  // `role` on kai-message, `hidden` on kai-resizable-item, `autofocus` on
+  // kai-confirm). Unlike RESERVED (which throws), these are legitimate domain props
+  // — `role` is the SPEAKER, `hidden` and `autofocus` mean what they say — and they
+  // stay usable, but the native accessor must not be the one that receives them.
+  // See defineWithNonReflectingProps for what the native setter does to the author's
+  // markup if it is, and why the shadowing has to be in place before the registry
+  // sees the class. RESERVED names never get here; they already threw above.
+  const shadowedProps = Object.keys(defaults).filter((key) => reflectedGlobalPropNames().has(key));
 
-  const Ctor = customElement(tag, defaults, (props: typeof defaults, options: { element: object }) => {
+  const renderFacade = (props: typeof defaults, options: { element: object }) => {
     const element = options.element as HTMLElement;
     let portalNode!: HTMLDivElement;
 
@@ -239,30 +386,18 @@ export function defineWebComponent<P extends Record<string, unknown>, E = Record
         </div>
       </>
     );
-  });
+  };
+
+  const { result: Ctor, handled } = defineWithNonReflectingProps(tag, shadowedProps, () =>
+    customElement(tag, defaults, renderFacade),
+  );
 
-  // Shadow any reflected native IDL accessor this element re-uses as a prop (see
-  // NON_REFLECTING) with a plain, non-reflecting store on the element prototype.
-  // This must live on the prototype (not the instance) so it is already in place
-  // when the value is set before connectedCallback, the window in which the native
-  // setter would otherwise reflect it to a host attribute. component-register reads
-  // the property back during initializeProps to seed the styling prop, and later
-  // shadows this with its own (also non-reflecting) per-instance accessor.
+  // Belt and braces for the one path the wrap cannot see: if `customElements.define`
+  // was never reached for this tag (a registry that defines lazily, or a future
+  // solid-element that stops calling it synchronously), install on the returned class
+  // instead. That is the OLD, too-late timing — it still protects every element
+  // constructed from here on, it just cannot rescue an already-upgraded one. Skipped
+  // in the normal case, where the accessors are already on this same prototype.
   const proto = (Ctor as unknown as { prototype?: object } | undefined)?.prototype;
-  if (proto) {
-    for (const key of NON_REFLECTING) {
-      if (!(key in defaults)) continue;
-      const store = Symbol(`kai-prop:${key}`);
-      Object.defineProperty(proto, key, {
-        get(this: Record<symbol, unknown>) {
-          return this[store];
-        },
-        set(this: Record<symbol, unknown>, value: unknown) {
-          this[store] = value;
-        },
-        enumerable: true,
-        configurable: true,
-      });
-    }
-  }
+  if (!handled && proto) installNonReflectingProps(proto, shadowedProps);
 }

package/src/elements/editable-label.tsx

@@ -3,7 +3,7 @@ import { defineWebComponent } from './define';
 import { EditableLabel } from '../ui/editable-label';
 
 interface Props extends Record<string, unknown> {
-  /** The label text — settable and reflected to the `value` attribute. Read
+  /** The label text. Settable and reflected to the `value` attribute. Read
    *  `el.value` for live state. */
   value?: string;
   /** Controlled edit state. `el.editing = true` opens the field; reflected to the
@@ -104,7 +104,22 @@ defineWebComponent<Props, Events>('kai-editable-label', {
     }
   };
 
-  expose({ edit: enter, commit, cancel });
+  expose({
+    /** Switch the label into its editing field, which autofocuses and selects the
+     *  current text. Same entry point as a user double-click, and a no-op while
+     *  `disabled`. Commit with `commit()` or by blurring, abandon with `cancel()`
+     *  or Escape. */
+    edit: enter,
+    /** Close the field and keep what was typed, exactly as blurring it does.
+     *  `kai-rename` fires only when the text actually changed, so committing an
+     *  untouched field is silent. A no-op while the field is closed. */
+    commit,
+    /** Abandon the edit, exactly as Escape does: the original text is restored,
+     *  the field closes and `kai-cancel` fires. `kai-rename` never fires, even if
+     *  the field was edited. Also works when `editing` was set programmatically
+     *  and the field has not rendered yet. */
+    cancel,
+  });
 
   return (
     <>

package/src/elements/element-data-types.ts

@@ -0,0 +1,112 @@
+/**
+ * The data shapes a consumer assigns to a `kai-*` element's array/object
+ * properties, when that shape has no Solid-layer twin they could import instead.
+ *
+ * WHY THIS FILE EXISTS. The generated `.d.ts` for `./elements` and the React
+ * wrappers expand every prop type STRUCTURALLY (see the `IMPORTS = {}` note in
+ * scripts/gen-element-api.mjs — self-contained declarations are what keeps a
+ * consumer's tsc from resolving library `.ts` source). That is right for the
+ * generated files, but it means a consumer who wants to name the shape — a
+ * `const items: … = [...]` in their own code, a helper that builds one — has no
+ * type to import and ends up writing
+ * `NonNullable<KaiCommandElementProps['items']>`. Every named element-prop type
+ * must therefore be reachable from the ROOT entry (`@kitn.ai/ui`), which is what
+ * a React / Vue / Svelte / vanilla consumer imports. Enforced by
+ * tests/elements/prop-types-exported.test.ts.
+ *
+ * These live in their own module (not in the facades that use them) because the
+ * facades compile to per-element side-effect entry points whose shipped
+ * declarations are `export {};` — a type re-exported from one of those would not
+ * resolve for a consumer. Types with a Solid twin (`TriggerDef`, `KaiNavItem`,
+ * `ChatThreadContextUsage`, …) stay in their own layer's module and are
+ * re-exported from `src/index.ts` directly.
+ *
+ * Type-only: fully erased by the build, so the root barrel pays nothing.
+ */
+
+/** A single segment of `<kai-segmented>`.
+ *
+ *  Distinct from the Solid `SegmentedOption`, whose `icon` is a JSX node: on the
+ *  element, `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). */
+export interface KaiSegmentedOption {
+  value: string;
+  label: string;
+  icon?: string;
+}
+
+/** A single citation in `<kai-sources>`' `sources` property. Also the shape
+ *  `<kai-source>` light-DOM children are parsed into. */
+export interface KaiSourceItem {
+  href: string;
+  title?: string;
+  description?: string;
+  label?: string;
+  showFavicon?: boolean;
+}
+
+/** Token-usage data for `<kai-context>`' `context` property. */
+export interface KaiContextUsage {
+  /** Tokens consumed so far in the context window (drives the meter fill). */
+  usedTokens: number;
+  /** The model's total context-window size in tokens. */
+  maxTokens: number;
+  /** Tokens attributed to the prompt/input, shown in the breakdown. */
+  inputTokens?: number;
+  /** Tokens attributed to the generated output, shown in the breakdown. */
+  outputTokens?: number;
+  /** Tokens attributed to reasoning/thinking, shown when present. */
+  reasoningTokens?: number;
+  /** Tokens served from prompt cache, shown when present. */
+  cacheTokens?: number;
+  /** Estimated cost in dollars for this usage, shown in the footer. */
+  estimatedCost?: number;
+}
+
+/** One item in `<kai-menu>`'s `items` tree. */
+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[];
+}
+
+/**
+ * A single command/mention item for `<kai-command>`.
+ *
+ * Set `items` as a JS property (array ref) — not an HTML attribute.
+ */
+export interface KaiCommandItem {
+  /** Unique identifier emitted in `kai-select`. */
+  id: string;
+  /** Display name shown in the list row. */
+  label: string;
+  /** Named icon (e.g. "search"), image URL / data-URI, or plain text. */
+  icon?: string;
+  /** Muted supplementary text (e.g. a file path or a short description). */
+  description?: string;
+  /** Optional keyboard shortcut shown as right-aligned key caps; uses the
+   *  kai-kbd `keys` syntax (e.g. "Mod+K", "Alt+1"). */
+  shortcut?: string;
+  /** Group name that buckets this item under a section header. */
+  group?: string;
+}