@kitn.ai/ui 0.20.1 → 0.22.0

package/dist/components/chat-thread.d.ts

@@ -1,10 +1,14 @@
-import { ComposerDoc } from '../primitives/composer-model';
-import { AttachmentData } from './attachments';
-import { MessageActionDetail } from '../primitives/message-feedback';
-import { TriggerDef } from './composer';
-import { ChatMessage } from '../elements/chat-types';
-import { ProseSize } from '../primitives/chat-config';
-import { ModelOption } from '../types';
+import { ComposerDoc } from '../primitives/composer-model.js';
+import { AttachmentData } from './attachments.js';
+import { MessageActionDetail } from '../primitives/message-feedback.js';
+import { RejectedAttachment } from '../elements/default-input.js';
+import { MediaTypeFilter } from '../wire/media-types.js';
+import { TriggerDef } from './composer.js';
+import { ChatMessage } from '../elements/chat-types.js';
+import { ProseSize } from '../primitives/chat-config.js';
+import { ModelOption } from '../types.js';
+import { CardComponentMap } from '../primitives/card-registry.js';
+import { CardSchemaMap } from './card-renderer.js';
 export interface ChatThreadContextUsage {
     usedTokens: number;
     maxTokens: number;
@@ -16,9 +20,19 @@ export interface ChatThreadProps {
     /** Extra classes for the thread root (e.g. `h-full`). */
     class?: string;
     /** The full message thread to render, newest last. Each entry carries its role,
-     *  content, and optional reasoning/tools/attachments/actions. Set as a JS
-     *  property (`el.messages = [...]`). */
+     *  ordered `parts`, and optional actions/avatar/feedback. Set as a JS property
+     *  (`el.messages = [...]`). */
     messages: ChatMessage[];
+    /** Add/override card type -> component entries, forwarded to `CardRenderer`
+     *  for `card` parts. */
+    cardTypes?: CardComponentMap;
+    /** JSON Schemas for the card types this app renders, keyed by envelope type,
+     *  forwarded to `CardRenderer` for `card` parts. The companion of `cardTypes`:
+     *  that says what DRAWS a card, this says what a VALID one looks like.
+     *  `createCardRegistry(...).validationSchemas` is exactly this shape. Without it
+     *  the kit checks its own seven built-ins and leaves your own card type
+     *  unvalidated. A schema here WINS over a built-in of the same name. */
+    cardSchemas?: CardSchemaMap;
     /** Value of the input. A **string** is controlled (the host owns the text and
      *  updates it on `kai-value-change`). A **ComposerDoc** is a one-time seed that
      *  pre-populates pills; the user then edits freely. Leave unset for uncontrolled. */
@@ -59,29 +73,36 @@ export interface ChatThreadProps {
     context?: ChatThreadContextUsage;
     /** Show the scroll-to-bottom button inside the scroll area. Default true. */
     scrollButton?: boolean;
-    /** Whether the host has `slot="header-start"` content (left of the title) —
-     *  set by the `<kai-chat>` facade so a custom control forces the header open. */
+    /** Whether the host has `slot="header-start"` content (left of the title). Set
+     *  by the `<kai-chat>` facade so a custom control forces the header open. */
     headerStart?: boolean;
     /** Whether the host has `slot="header-end"` content (right of the controls). */
     headerEnd?: boolean;
-    /** REPLACE — full custom header in place of the built-in title/model/context bar. */
+    /** REPLACE: full custom header in place of the built-in title/model/context bar. */
     headerFull?: boolean;
-    /** INJECT — left sidebar column (e.g. a conversation list / your own nav). */
+    /** INJECT: left sidebar column (e.g. a conversation list / your own nav). */
     sidebar?: boolean;
-    /** REPLACE — custom zero-state rendered in the message area while the thread is empty (replaces the empty message list only; the composer and its suggestions still render). */
+    /** REPLACE: custom zero-state rendered in the message area while the thread is empty (replaces the empty message list only; the composer and its suggestions still render). */
     empty?: boolean;
-    /** REPLACE — full custom composer in place of the built-in prompt input. The
+    /** REPLACE: full custom composer in place of the built-in prompt input. The
      *  projected content wires its own submit (the data-flow boundary). */
     composer?: boolean;
-    /** INJECT — accessory row just above the composer (e.g. extra actions). */
+    /** INJECT: accessory row just above the composer (e.g. extra actions). */
     composerActions?: boolean;
-    /** INJECT — footer row below the composer (disclaimers, token meter, …). */
+    /** INJECT: footer row below the composer (disclaimers, token meter, …). */
     footer?: boolean;
+    /** Which attachment media types the user may stage, in HTML `accept` syntax
+     *  (`'image/*,application/pdf'`). Omitted means no filter. Narrowed by what the
+     *  encoders can actually send — the same string, and the same resolver, as
+     *  `toOpenAIMessages(msgs, { accept })`. */
+    accept?: MediaTypeFilter;
+    /** Files the composer refused because `accept` excluded them. */
+    onAttachmentsRejected?: (rejected: RejectedAttachment[]) => void;
     /** Show a Search (Globe) button in the input toolbar; fires a `search` event. */
     search?: boolean;
     /** Show a Voice (Mic) button in the input toolbar; fires a `voice` event. */
     voice?: boolean;
-    /** Rich entity triggers — each `{ char, kind, items }` opens a caret-anchored
+    /** Rich entity triggers. Each `{ char, kind, items }` opens a caret-anchored
      *  menu that inserts an atomic pill (`/` skills, `@` agents/plugins). Set as a
      *  JS property; forwarded to the input. */
     triggers?: TriggerDef[];
@@ -113,4 +134,42 @@ export interface ChatThreadController {
     send(): void;
     scrollToBottom(behavior?: ScrollBehavior): void;
 }
+/**
+ * THE MESSAGE LIST'S KEY, and the reason it is not the message object. This is
+ * the canonical note; `thread.tsx` keys its identical list the same way and
+ * points here.
+ *
+ *  `<For>` is REFERENCE-keyed, and a streaming assistant message gets a brand
+ *  new object identity on every delta — `createAssistantStream` rebuilds it as
+ *  `{ ...prev[i], parts: next }` because a new reference IS the re-render
+ *  signal. Keyed on the objects, every chunk therefore looks like an entirely
+ *  new list: the whole message row is torn down and rebuilt, and everything the
+ *  user did inside it dies with it. Expanding a tool or reasoning panel
+ *  mid-stream did nothing at all — the disclosure opened and was discarded
+ *  microseconds later by the next token. (`MessageBody` keys its PARTS by
+ *  position for exactly this reason; that fix was dead while its parent kept
+ *  destroying the subtree above it.)
+ *
+ *  So key on `message.id`, which is stable across the object churn: `<For>` over
+ *  the id array diffs by string value, a delta produces an identical id list,
+ *  and no row moves. The row then reads its message through `messages[i()]` —
+ *  `<For>`'s index accessor, which it keeps current across inserts, removals and
+ *  moves — so the CONTENT keeps updating through accessors while the DOM stays
+ *  put.
+ *
+ *  WHY NOT `<Index>`, the other way to survive the churn: `<Index>` keys by
+ *  POSITION, so a row's local state (an open panel, a half-filled form card)
+ *  belongs to the slot rather than to the message. Appends and tail truncations
+ *  (regenerate/edit) are fine, but prepending older turns — load-earlier-history,
+ *  which every real chat grows — shifts every row, and each open disclosure
+ *  stays behind with the wrong message. Position IS a valid key inside a
+ *  message, where the folds only ever append or patch a part in place; it is not
+ *  one for the message list, where the host owns the array and splices it.
+ *  Both approaches require the row to read through accessors — that is inherent
+ *  in keeping a row mounted while its object is replaced, not a cost unique to
+ *  either.
+ *
+ *  Contract: `id` must be unique per message. It already had to be — the
+ *  feedback/copy state above this list is keyed by it.
+ */
 export declare function ChatThread(props: ChatThreadProps): import("solid-js").JSX.Element;

package/dist/components/choice-card.d.ts

@@ -1,32 +1,7 @@
 import { JSX } from 'solid-js';
-import { CardEnvelope, CardHost, CardResolution } from '../primitives/card-contract';
-export interface ChoiceOptionMedia {
-    image?: string;
-    imageAlt?: string;
-    icon?: string;
-}
-export interface ChoiceOption {
-    id: string;
-    label: string;
-    description?: string;
-    media?: ChoiceOptionMedia;
-    meta?: string;
-    recommended?: boolean;
-    disabled?: boolean;
-    payload?: unknown;
-}
-export type ChoiceAllowOther = boolean | {
-    label?: string;
-    placeholder?: string;
-};
-export interface ChoiceCardData {
-    prompt?: string;
-    options: ChoiceOption[];
-    allowOther?: ChoiceAllowOther;
-    submitLabel?: string;
-    dismissible?: boolean;
-}
-export type ChoiceCardEnvelope = CardEnvelope<'choice', ChoiceCardData>;
+import { CardHost, CardResolution } from '../primitives/card-contract.js';
+import { ChoiceAllowOther, ChoiceCardData, ChoiceOption } from '../primitives/card-data-types.js';
+export type { ChoiceAllowOther, ChoiceCardData, ChoiceCardEnvelope, ChoiceOption, ChoiceOptionMedia, } from '../primitives/card-data-types.js';
 export declare const CHOICE_CARD_TYPE: "choice";
 /** The reserved action id emitted by the `allowOther` free-text submit. */
 export declare const OTHER_ACTION: "__other__";

package/dist/components/composer-dom.d.ts

@@ -1,4 +1,4 @@
-import { EntityRef, ComposerDoc } from '../primitives/composer-model';
+import { EntityRef, ComposerDoc } from '../primitives/composer-model.js';
 export declare const ZWSP = "\u200B";
 export declare const ENTITY_ATTR = "data-kai-entity";
 export declare const entityStore: WeakMap<HTMLElement, EntityRef>;

package/dist/components/composer-highlight.d.ts

@@ -1,4 +1,4 @@
-import { HighlightRule } from './composer';
+import { HighlightRule } from './composer.js';
 export interface HighlightMatch {
     start: number;
     end: number;

package/dist/components/composer-history.d.ts

@@ -1,4 +1,4 @@
-import { ComposerDoc } from '../primitives/composer-model';
+import { ComposerDoc } from '../primitives/composer-model.js';
 /**
  * Undo/redo history for the composer.
  *

package/dist/components/composer.d.ts

@@ -1,5 +1,5 @@
 import { JSX } from 'solid-js';
-import { ComposerDoc, EntityRef } from '../primitives/composer-model';
+import { ComposerDoc, EntityRef } from '../primitives/composer-model.js';
 export interface TriggerItem {
     id: string;
     label: string;

package/dist/components/confirm-card.d.ts

@@ -1,22 +1,7 @@
 import { JSX } from 'solid-js';
-import { CardEnvelope, CardHost, CardResolution } from '../primitives/card-contract';
-export type ConfirmActionStyle = 'primary' | 'default' | 'destructive';
-export type ConfirmTone = 'default' | 'warning' | 'danger';
-export interface ConfirmAction {
-    id: string;
-    label: string;
-    style?: ConfirmActionStyle;
-    payload?: unknown;
-    default?: boolean;
-}
-export interface ConfirmCardData {
-    heading?: string;
-    body?: string;
-    tone?: ConfirmTone;
-    actions: ConfirmAction[];
-    dismissible?: boolean;
-}
-export type ConfirmCardEnvelope = CardEnvelope<'confirm', ConfirmCardData>;
+import { CardHost, CardResolution } from '../primitives/card-contract.js';
+import { ConfirmAction, ConfirmActionStyle, ConfirmCardData } from '../primitives/card-data-types.js';
+export type { ConfirmAction, ConfirmActionStyle, ConfirmCardData, ConfirmCardEnvelope, ConfirmTone, } from '../primitives/card-data-types.js';
 export declare const CONFIRM_CARD_TYPE: "confirm";
 /** Map an action's `style` to a Button variant (falls back + warns on unknown). */
 export declare function buttonVariantForStyle(style: ConfirmActionStyle | undefined): 'default' | 'outline' | 'destructive';

package/dist/components/context.d.ts

@@ -59,7 +59,11 @@ export interface ContextUsageRowProps {
     class?: string;
     children?: JSX.Element;
 }
-export declare function ContextInputUsage(props: ContextUsageRowProps): JSX.Element;
-export declare function ContextOutputUsage(props: ContextUsageRowProps): JSX.Element;
-export declare function ContextReasoningUsage(props: ContextUsageRowProps): JSX.Element;
-export declare function ContextCacheUsage(props: ContextUsageRowProps): JSX.Element;
+export type ContextInputUsageProps = ContextUsageRowProps;
+export type ContextOutputUsageProps = ContextUsageRowProps;
+export type ContextReasoningUsageProps = ContextUsageRowProps;
+export type ContextCacheUsageProps = ContextUsageRowProps;
+export declare function ContextInputUsage(props: ContextInputUsageProps): JSX.Element;
+export declare function ContextOutputUsage(props: ContextOutputUsageProps): JSX.Element;
+export declare function ContextReasoningUsage(props: ContextReasoningUsageProps): JSX.Element;
+export declare function ContextCacheUsage(props: ContextCacheUsageProps): JSX.Element;

package/dist/components/conversation-item.d.ts

@@ -1,4 +1,4 @@
-import { ConversationSummary } from '../types';
+import { ConversationSummary } from '../types.js';
 export interface ConversationItemProps {
     conversation: ConversationSummary;
     isActive: boolean;

package/dist/components/conversation-list.d.ts

@@ -1,5 +1,5 @@
 import { JSX } from 'solid-js';
-import { ConversationSummary, ConversationGroup } from '../types';
+import { ConversationSummary, ConversationGroup } from '../types.js';
 /**
  * The collapsed-rail fallback: a floating reopen button shown when the
  * conversation sidebar is collapsed. Shared by `kai-workspace` (its collapsed
@@ -8,10 +8,11 @@ import { ConversationSummary, ConversationGroup } from '../types';
  * surrounding region (the workspace puts the thread beside it, the standalone
  * element stands alone). `onExpand` reopens the rail.
  */
-export declare function CollapsedRail(props: {
+export interface CollapsedRailProps {
     onExpand: () => void;
     class?: string;
-}): JSX.Element;
+}
+export declare function CollapsedRail(props: CollapsedRailProps): JSX.Element;
 export interface ConversationListProps {
     groups: ConversationGroup[];
     conversations: ConversationSummary[];

package/dist/components/embed.d.ts

@@ -1,6 +1,6 @@
 import { JSX } from 'solid-js';
-import { CardEvent } from '../primitives/card-contract';
-import { EmbedCardData } from '../primitives/embed-providers';
+import { CardEvent } from '../primitives/card-contract.js';
+import { EmbedCardData } from '../primitives/embed-providers.js';
 export interface EmbedProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, 'onError'> {
     /** The card id correlating every emitted event. */
     cardId: string;
@@ -18,4 +18,4 @@ export interface EmbedProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, 'on
  * emits are lifecycle `ready`, `open`, and failure `error`.
  */
 export declare function Embed(props: EmbedProps): JSX.Element;
-export type { EmbedCardData } from '../primitives/embed-providers';
+export type { EmbedCardData } from '../primitives/embed-providers.js';

package/dist/components/file-tree.d.ts

@@ -1,26 +1,15 @@
 import { JSX } from 'solid-js';
-/** A single artifact file the tree can show + the preview can load. */
-export interface FileTreeFile {
-    /** Tree label/key. Folders are built from `/`-delimited segments. */
-    path: string;
-    /** Where the preview loads it (CDN/S3/dev-server/API). */
-    url?: string;
-    /** Source for the Code tab. */
-    code?: string;
-    /** Language id for syntax highlighting (e.g. `html`, `css`, `tsx`). */
-    language?: string;
-    /** Kind — drives the icon + whether Code applies. */
-    type?: 'html' | 'pdf' | 'image' | 'other';
-    /** Lines added vs the base. Rendered as a trailing `+N` stat (success hue,
-     *  tabular-nums). Only shown when present; omit for a plain file row. */
-    additions?: number;
-    /** Lines removed vs the base. Rendered as a trailing `-N` stat (error hue). */
-    deletions?: number;
-    /** Change status vs the base. Drives a small trailing status letter in the
-     *  conventional VCS hue (added=green, modified=amber, deleted=red,
-     *  renamed=blue, untracked=muted). Only shown when present. */
-    status?: 'added' | 'modified' | 'deleted' | 'renamed' | 'untracked';
-}
+import { ArtifactCardFile as FileTreeFile } from '../primitives/card-data-types.js';
+/** A single artifact file the tree can show + the preview can load.
+ *
+ *  AUTHORED IN ../primitives/card-data-types.ts as `ArtifactCardFile`, and aliased
+ *  here rather than declared, so there is ONE shape and not a copy of one. It has
+ *  to live in that `.ts` because `ArtifactCardData.files` reaches it: a type import
+ *  still has to RESOLVE, and a Node/no-DOM project (tsconfig.mcp.json has no `jsx`
+ *  on purpose) cannot resolve a `.tsx` at all — so leaving this declaration here
+ *  would put TS6142 back on any backend that names an artifact card payload. See
+ *  that file's header. */
+export type { ArtifactCardFile as FileTreeFile } from '../primitives/card-data-types.js';
 /** A change status a file can carry. */
 export type FileStatus = NonNullable<FileTreeFile['status']>;
 /** A folder node in the built tree. */

package/dist/components/form-widgets.d.ts

@@ -1,5 +1,5 @@
 import { JSX } from 'solid-js';
-import { FormField } from './form';
+import { FormField } from './form.js';
 /** The shared prop shape every leaf widget receives from FieldRow. */
 export interface WidgetProps {
     id: string;

package/dist/components/form.d.ts

@@ -1,48 +1,7 @@
 import { JSX } from 'solid-js';
-import { CardEnvelope, CardHost, CardResolution } from '../primitives/card-contract';
-/** A field definition (the JSON Schema subset kai-form renders). */
-export interface FormField {
-    type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
-    title?: string;
-    description?: string;
-    default?: unknown;
-    enum?: unknown[];
-    format?: 'email' | 'uri' | 'url' | 'date' | 'date-time' | 'time';
-    minimum?: number;
-    maximum?: number;
-    minLength?: number;
-    maxLength?: number;
-    pattern?: string;
-    minItems?: number;
-    maxItems?: number;
-    items?: FormField | {
-        enum: unknown[];
-    };
-    properties?: Record<string, FormField>;
-    required?: string[];
-    readOnly?: boolean;
-    'x-kai-widget'?: 'textarea' | 'slider' | 'rating' | 'radio' | 'select' | 'checkbox' | 'password' | 'switch';
-    'x-kai-placeholder'?: string;
-    'x-kai-step'?: number;
-}
-/** The form definition = CardEnvelope.data for type:'form'. */
-export interface FormDefinition {
-    type: 'object';
-    title?: string;
-    description?: string;
-    required?: string[];
-    properties: Record<string, FormField>;
-    'x-kai-order'?: string[];
-    'x-kai-inlineMax'?: number;
-    'x-kai-submitLabel'?: string;
-    'x-kai-dismissible'?: boolean;
-    'x-kai-actions'?: {
-        id: string;
-        label: string;
-        variant?: 'default' | 'ghost' | 'outline';
-    }[];
-}
-export type FormCardEnvelope = CardEnvelope<'form', FormDefinition>;
+import { CardHost, CardResolution } from '../primitives/card-contract.js';
+import { FormDefinition, FormField } from '../primitives/card-data-types.js';
+export type { FormCardEnvelope, FormDefinition, FormField, } from '../primitives/card-data-types.js';
 /** The internal widget identifiers `widgetFor` resolves to. */
 export type WidgetKind = 'text' | 'textarea' | 'password' | 'email' | 'url' | 'date' | 'datetime' | 'time' | 'number' | 'slider' | 'rating' | 'switch' | 'checkbox' | 'radio' | 'select' | 'checkbox-group' | 'multiselect' | 'repeater' | 'taglist' | 'fieldset' | 'unsupported';
 export declare const DEFAULT_INLINE_MAX = 4;

package/dist/components/link-preview.d.ts

@@ -1,6 +1,6 @@
 import { JSX } from 'solid-js';
-import { CardEvent } from '../primitives/card-contract';
-import { LinkPreviewData } from '../primitives/link-preview';
+import { CardEvent } from '../primitives/card-contract.js';
+import { LinkPreviewData } from '../primitives/link-preview.js';
 export interface LinkPreviewProps {
     /** The card id correlating every emitted event. */
     cardId: string;
@@ -20,4 +20,4 @@ export interface LinkPreviewProps {
  * host policy performs the navigation so it can veto/redirect.
  */
 export declare function LinkPreview(props: LinkPreviewProps): JSX.Element;
-export type { LinkPreviewData } from '../primitives/link-preview';
+export type { LinkPreviewData } from '../primitives/link-preview.js';

package/dist/components/loader.d.ts

@@ -6,55 +6,37 @@ export interface LoaderProps {
     text?: string;
     class?: string;
 }
-export declare function CircularLoader(props: {
+/** Props of the shape-only loader variants (no label). */
+export interface LoaderShapeProps {
     class?: string;
     size?: LoaderSize;
-}): import("solid-js").JSX.Element;
-export declare function ClassicLoader(props: {
-    class?: string;
-    size?: LoaderSize;
-}): import("solid-js").JSX.Element;
-export declare function PulseLoader(props: {
-    class?: string;
-    size?: LoaderSize;
-}): import("solid-js").JSX.Element;
-export declare function PulseDotLoader(props: {
-    class?: string;
-    size?: LoaderSize;
-}): import("solid-js").JSX.Element;
-export declare function DotsLoader(props: {
-    class?: string;
-    size?: LoaderSize;
-}): import("solid-js").JSX.Element;
-export declare function TypingLoader(props: {
-    class?: string;
-    size?: LoaderSize;
-}): import("solid-js").JSX.Element;
-export declare function WaveLoader(props: {
-    class?: string;
-    size?: LoaderSize;
-}): import("solid-js").JSX.Element;
-export declare function BarsLoader(props: {
-    class?: string;
-    size?: LoaderSize;
-}): import("solid-js").JSX.Element;
-export declare function TerminalLoader(props: {
-    class?: string;
-    size?: LoaderSize;
-}): import("solid-js").JSX.Element;
-export declare function TextBlinkLoader(props: {
-    text?: string;
-    class?: string;
-    size?: LoaderSize;
-}): import("solid-js").JSX.Element;
-export declare function TextShimmerLoader(props: {
-    text?: string;
-    class?: string;
-    size?: LoaderSize;
-}): import("solid-js").JSX.Element;
-export declare function TextDotsLoader(props: {
+}
+/** Props of the text-based loader variants, which also take the label. */
+export interface LoaderTextProps extends LoaderShapeProps {
     text?: string;
-    class?: string;
-    size?: LoaderSize;
-}): import("solid-js").JSX.Element;
+}
+export type CircularLoaderProps = LoaderShapeProps;
+export type ClassicLoaderProps = LoaderShapeProps;
+export type PulseLoaderProps = LoaderShapeProps;
+export type PulseDotLoaderProps = LoaderShapeProps;
+export type DotsLoaderProps = LoaderShapeProps;
+export type TypingLoaderProps = LoaderShapeProps;
+export type WaveLoaderProps = LoaderShapeProps;
+export type BarsLoaderProps = LoaderShapeProps;
+export type TerminalLoaderProps = LoaderShapeProps;
+export type TextBlinkLoaderProps = LoaderTextProps;
+export type TextShimmerLoaderProps = LoaderTextProps;
+export type TextDotsLoaderProps = LoaderTextProps;
+export declare function CircularLoader(props: CircularLoaderProps): import("solid-js").JSX.Element;
+export declare function ClassicLoader(props: ClassicLoaderProps): import("solid-js").JSX.Element;
+export declare function PulseLoader(props: PulseLoaderProps): import("solid-js").JSX.Element;
+export declare function PulseDotLoader(props: PulseDotLoaderProps): import("solid-js").JSX.Element;
+export declare function DotsLoader(props: DotsLoaderProps): import("solid-js").JSX.Element;
+export declare function TypingLoader(props: TypingLoaderProps): import("solid-js").JSX.Element;
+export declare function WaveLoader(props: WaveLoaderProps): import("solid-js").JSX.Element;
+export declare function BarsLoader(props: BarsLoaderProps): import("solid-js").JSX.Element;
+export declare function TerminalLoader(props: TerminalLoaderProps): import("solid-js").JSX.Element;
+export declare function TextBlinkLoader(props: TextBlinkLoaderProps): import("solid-js").JSX.Element;
+export declare function TextShimmerLoader(props: TextShimmerLoaderProps): import("solid-js").JSX.Element;
+export declare function TextDotsLoader(props: TextDotsLoaderProps): import("solid-js").JSX.Element;
 export declare function Loader(props: LoaderProps): import("solid-js").JSX.Element;

package/dist/components/message-skills.d.ts

@@ -1,6 +1,10 @@
 import { JSX } from 'solid-js';
+/** One skill badge. Also the shape of `<kai-skills>`' `skills` property and of a
+ *  `<kai-skill>` light-DOM child. */
 export interface Skill {
+    /** Stable identifier for the skill. */
     id: string;
+    /** Human-readable skill name shown on the badge. */
     name: string;
 }
 export interface MessageSkillsProps {

package/dist/components/message.d.ts

@@ -1,14 +1,43 @@
 import { JSX } from 'solid-js';
-import { ChatMessageAction, CustomAction, FeedbackVote } from '../elements/chat-types';
-import { ToolPart } from './tool';
-import { AttachmentData } from './attachments';
-export interface MessageProps extends JSX.HTMLAttributes<HTMLDivElement> {
+import { ChatMessageAction, CustomAction, FeedbackVote, MessagePart } from '../elements/chat-types.js';
+import { CardSchemaMap } from './card-renderer.js';
+import { CardComponentMap } from '../primitives/card-registry.js';
+/** Who is speaking in a message row. This is the SEMANTIC role of the message,
+ *  not an ARIA role — see `MessageProps['role']`. */
+export type MessageRole = 'user' | 'assistant' | 'system';
+export interface MessageProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, 'role'> {
     children: JSX.Element;
+    /** Who is speaking: `'user'`, `'assistant'` or `'system'`.
+     *
+     *  This SHADOWS the inherited ARIA `role` attribute on purpose, and is the
+     *  reason `JSX.HTMLAttributes` is `Omit`ted above. Before this existed, `role`
+     *  resolved to ARIA and was spread straight onto the row, so `<Message
+     *  role="user">` shipped `role="user"` on a div — not a valid ARIA role, and a
+     *  critical axe `aria-roles` violation ("Role must be one of the valid ARIA
+     *  roles: user") on every message that used the prop. Chromium discards the
+     *  unknown token and computes `generic`, so the damage was a failed a11y audit
+     *  and a row with no accessible role or name at all, not a mis-announced one.
+     *
+     *  It is now consumed here and never reaches the DOM. What the row gets
+     *  instead is a VALID ARIA role that can carry a name — `role="article"` plus
+     *  an `aria-label` naming the speaker — and `data-role` for styling and
+     *  querying. Omit the prop and the row stays an unlabelled `<div>`, exactly as
+     *  before, so the many role-less call sites are untouched.
+     *
+     *  The trade-off: the row's ARIA role can no longer be set through this prop.
+     *  Pass `aria-label` (or any other ARIA attribute) to override the default
+     *  naming — the spread below still wins over what this computes. */
+    role?: MessageRole;
 }
 declare function Message(props: MessageProps): JSX.Element;
 export interface MessageAvatarProps {
-    src: string;
-    alt: string;
+    /** Avatar image URL. Optional: with no `src` the component renders `fallback`
+     *  (initials), which is the whole point of having a fallback — requiring `src`
+     *  forced `<MessageAvatar src="" …/>` at every initials-only call site. */
+    src?: string;
+    /** Alt text for the image. Only meaningful alongside `src`; defaults to `''`
+     *  so an avatar stays decorative rather than announcing a filename. */
+    alt?: string;
     fallback?: string;
     class?: string;
 }
@@ -60,21 +89,26 @@ export interface MessageActionBarProps {
  */
 declare function MessageActionBar(props: MessageActionBarProps): JSX.Element;
 export interface MessageBodyProps {
-    /** The message text/markdown. */
-    content: string;
-    /** Optional collapsible reasoning block, rendered above the content. */
-    reasoning?: {
-        text: string;
-        label?: string;
-    };
-    /** Tool-call parts, rendered above the content. */
-    tools?: ToolPart[];
-    /** Inline attachment previews, rendered above the content. */
-    attachments?: AttachmentData[];
+    /** The message's ordered parts (text, reasoning, tool, card, source, file),
+     *  rendered in a single pass in the order they appear. A run of consecutive
+     *  `source` parts renders as ONE citation row (`part="citations"`), placed
+     *  OUTSIDE the message bubble so a citation is never confused with a link the
+     *  model typed into its prose. */
+    parts: MessagePart[];
+    /** Add/override card type -> component entries, forwarded to `CardRenderer`
+     *  for `card` parts. */
+    cardTypes?: CardComponentMap;
+    /** JSON Schemas for the card types this app renders, keyed by envelope type,
+     *  forwarded to `CardRenderer` for `card` parts. The companion of `cardTypes`:
+     *  that says what DRAWS a card, this says what a VALID one looks like.
+     *  `createCardRegistry(...).validationSchemas` is exactly this shape. Without it
+     *  the kit checks its own seven built-ins and leaves your own card type
+     *  unvalidated. A schema here WINS over a built-in of the same name. */
+    cardSchemas?: CardSchemaMap;
     /** Whether this is a user message (right-aligned bubble) vs an assistant
      *  message (full-width transparent). */
     isUser: boolean;
-    /** Whether the content renders as markdown. */
+    /** Whether text parts render as markdown. */
     markdown: boolean;
     /** Action-bar entries — built-in names and/or custom descriptors. When empty
      *  the bar is not rendered. */
@@ -98,10 +132,39 @@ export interface MessageBodyProps {
      *  shadow this is `<slot name="after-body" />`. */
     afterBody?: JSX.Element;
 }
+/** One render group over an ordered `parts` array. Two part types collapse runs:
+ *  consecutive `file` parts become a single `'files'` group so they share one
+ *  `<Attachments>` row (matching the pre-parts layout) instead of each opening
+ *  its own, and consecutive `source` parts become a single `'sources'` group so
+ *  the N citations one search produced are ONE wrapped row rather than N stacked
+ *  rows. Every other part is its own `'single'` group. Pure and order-preserving:
+ *  it only decides where the wrapper boundaries fall, never reorders or drops
+ *  anything, so a group sits exactly where its parts sat in `parts`. */
+export type MessagePartGroup = {
+    kind: 'single';
+    part: Exclude<MessagePart, {
+        type: 'file';
+    } | {
+        type: 'source';
+    }>;
+} | {
+    kind: 'files';
+    parts: Extract<MessagePart, {
+        type: 'file';
+    }>[];
+} | {
+    kind: 'sources';
+    parts: Extract<MessagePart, {
+        type: 'source';
+    }>[];
+};
+export declare function groupMessageParts(parts: MessagePart[]): MessagePartGroup[];
 /**
- * The shared message body: an optional reasoning block, tool calls, inline
- * attachments, the content bubble, and the action bar — in that order. This is
- * the single source of truth for how a message renders, consumed by `ChatThread`
+ * The shared message body: the message's `parts` rendered in a single ordered
+ * pass (text, reasoning, tool calls, generative-UI cards, citations and file
+ * attachments interleaved exactly as they appear), followed by the action bar.
+ * Runs of `source` and `file` parts each collapse into one row. This is the
+ * single source of truth for how a message renders, consumed by `ChatThread`
  * (the `<For>` over `messages`), the standalone `<kai-message>` facade, and (in
  * future) `kai-compare` for each candidate. Pure/prop-driven: all interaction
  * state (copied, feedback vote) is owned above and passed in.