@kitnai/chat 0.3.1 → 0.4.0

package/frameworks/react/index.tsx

@@ -0,0 +1,530 @@
+// AUTO-GENERATED by scripts/gen-element-api.mjs — do not edit by hand.
+// Typed React wrappers for every kitn custom element. Usage:
+//   import { KitnMessage } from '@kitnai/chat/react';
+//   <KitnMessage message={msg} onMessageaction={(e) => …} />
+import { createKitnComponent, type KitnBaseProps } from './runtime';
+
+
+export interface KitnAttachmentsProps extends KitnBaseProps {
+  /** The attachments to render. Set as a JS property (array). */
+  items: { id: string; type: "file" | "source-document"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[];
+  /** Layout: `grid` = visual tiles, `inline` = icon + label chips, `list` = rows. */
+  variant?: "grid" | "inline" | "list";
+  /** Wrap each item in a hover card that previews its details. */
+  hoverCard?: boolean;
+  /** Show a remove button per item; clicking it fires a `remove` event. */
+  removable?: boolean;
+  /** Also show the media type beneath the filename (non-grid variants). */
+  showMediaType?: boolean;
+  /** Text shown when `items` is empty. */
+  emptyText?: string;
+  /** A remove button was clicked. */
+  onRemove?: (event: CustomEvent<{ id: string }>) => void;
+}
+
+export const KitnAttachments = createKitnComponent<KitnAttachmentsProps>(
+  'kitn-attachments',
+  ["theme","items","variant","hoverCard","removable","showMediaType","emptyText"],
+  { onRemove: 'remove' },
+);
+
+export interface KitnChainOfThoughtProps extends KitnBaseProps {
+  /** The reasoning steps. Set as a JS property. Compound sub-parts collapse to this one data model (Route 1). */
+  steps: { label: string; content?: undefined | string }[];
+}
+
+export const KitnChainOfThought = createKitnComponent<KitnChainOfThoughtProps>(
+  'kitn-chain-of-thought',
+  ["theme","steps"],
+  {  },
+);
+
+export interface KitnChatProps extends KitnBaseProps {
+  /** 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 = [...]`). */
+  messages: { id: string; role: "user" | "assistant"; content: string; reasoning?: undefined | { text: string; label?: undefined | string }; tools?: undefined | { type: string; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: undefined | Record<string, unknown>; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string }[]; attachments?: undefined | { id: string; type: "file" | "source-document"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]; actions?: undefined | ("copy" | "like" | "dislike" | "regenerate" | "edit")[] }[];
+  /** Controlled value of the input. When set, the host owns the input text and must update it on `valuechange`; leave unset for uncontrolled behavior. */
+  value?: string;
+  /** Placeholder text shown in the empty input. */
+  placeholder?: string;
+  /** When true, shows the loading/streaming state and disables submit (use while awaiting the assistant's reply). */
+  loading?: boolean;
+  /** Starter prompts shown above the input when the thread is empty. Clicking one follows `suggestionMode`. Set as a JS property. */
+  suggestions?: string[];
+  /** What clicking a suggestion does: `'submit'` (default) sends it immediately as if typed and submitted; `'fill'` just places it in the input. */
+  suggestionMode?: "submit" | "fill";
+  /** Body/prose font scale for rendered markdown (`'xs' | 'sm' | 'base' | 'lg'`). Defaults to `'sm'`. */
+  proseSize?: "xs" | "sm" | "base" | "lg";
+  /** Shiki theme name for syntax-highlighted code blocks (e.g. `'github-dark-dimmed'`). */
+  codeTheme?: string;
+  /** Enable Shiki syntax highlighting in code blocks. Turn off to render plain `<pre>` blocks (lighter, no highlighter load). Default true. */
+  codeHighlight?: boolean;
+  /** Optional header title shown on the left of the header. */
+  chatTitle?: string;
+  /** Optional model list. When set (>1 model) a ModelSwitcher is shown in the header and a `modelchange` event fires on selection. */
+  models?: { id: string; name: string; provider?: string }[];
+  /** The currently selected model id (pairs with `models`). */
+  currentModel?: string;
+  /** Optional context-window token usage. When set, a Context token meter is shown in the header. */
+  context?: { usedTokens: number; maxTokens: number; inputTokens?: number; outputTokens?: number; estimatedCost?: number };
+  /** Show the scroll-to-bottom button inside the scroll area. Default true. */
+  scrollButton?: boolean;
+  /** 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;
+  /** Slash commands — when set, typing `/` in the input opens the command palette and fires `slashselect`. Set as a JS property. */
+  slashCommands?: { id: string; label: string; description?: string; category?: string }[];
+  /** Command ids to highlight as active in the palette. */
+  slashActiveIds?: string[];
+  /** Single-line palette rows. */
+  slashCompact?: boolean;
+  onMessageaction?: (event: CustomEvent<unknown>) => void;
+  onModelchange?: (event: CustomEvent<unknown>) => void;
+  onSearch?: (event: CustomEvent<unknown>) => void;
+  onSlashselect?: (event: CustomEvent<unknown>) => void;
+  onSubmit?: (event: CustomEvent<unknown>) => void;
+  onSuggestionclick?: (event: CustomEvent<unknown>) => void;
+  onValuechange?: (event: CustomEvent<unknown>) => void;
+  onVoice?: (event: CustomEvent<unknown>) => void;
+}
+
+export const KitnChat = createKitnComponent<KitnChatProps>(
+  'kitn-chat',
+  ["theme","messages","value","placeholder","loading","suggestions","suggestionMode","proseSize","codeTheme","codeHighlight","chatTitle","models","currentModel","context","scrollButton","search","voice","slashCommands","slashActiveIds","slashCompact"],
+  { onMessageaction: 'messageaction', onModelchange: 'modelchange', onSearch: 'search', onSlashselect: 'slashselect', onSubmit: 'submit', onSuggestionclick: 'suggestionclick', onValuechange: 'valuechange', onVoice: 'voice' },
+);
+
+export interface KitnChatScopePickerProps extends KitnBaseProps {
+  /** Authors to offer as scope filters. Set as a JS property. */
+  availableAuthors: string[];
+  /** Tags to offer as scope filters. Set as a JS property. */
+  availableTags: string[];
+  /** The label shown on the trigger for the active scope. */
+  currentLabel?: string;
+  /** A scope was chosen (`undefined` filters = "All Content"). */
+  onScopechange?: (event: CustomEvent<{ filters: undefined | { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | "transcript" | "markdown"; dateRange?: undefined | { from: string; to: string } } }>) => void;
+}
+
+export const KitnChatScopePicker = createKitnComponent<KitnChatScopePickerProps>(
+  'kitn-chat-scope-picker',
+  ["theme","availableAuthors","availableTags","currentLabel"],
+  { onScopechange: 'scopechange' },
+);
+
+export interface KitnCheckpointProps extends KitnBaseProps {
+  /** Optional text beside the icon. */
+  label?: string;
+  /** Tooltip on hover. */
+  tooltip?: string;
+  /** Visual button style. */
+  variant?: "ghost" | "default" | "outline";
+  /** Button size (use an `icon*` size for an icon-only checkpoint). */
+  size?: "sm" | "lg" | "md" | "icon" | "icon-sm";
+  /** The checkpoint was clicked. */
+  onSelect?: (event: CustomEvent) => void;
+}
+
+export const KitnCheckpoint = createKitnComponent<KitnCheckpointProps>(
+  'kitn-checkpoint',
+  ["theme","label","tooltip","variant","size"],
+  { onSelect: 'select' },
+);
+
+export interface KitnCodeBlockProps extends KitnBaseProps {
+  /** The source code to render. */
+  code: string;
+  /** Language grammar (e.g. `js`, `python`). Defaults to `tsx`. */
+  language?: string;
+  /** Shiki theme name. */
+  codeTheme?: string;
+  /** Disable syntax highlighting (renders plain text, no Shiki). */
+  codeHighlight?: boolean;
+  /** Code text sizing. */
+  proseSize?: "xs" | "sm" | "base" | "lg";
+}
+
+export const KitnCodeBlock = createKitnComponent<KitnCodeBlockProps>(
+  'kitn-code-block',
+  ["theme","code","language","codeTheme","codeHighlight","proseSize"],
+  {  },
+);
+
+export interface KitnContextMeterProps extends KitnBaseProps {
+  /** Token-usage data. Set as a JS property. */
+  context?: { usedTokens: number; maxTokens: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; cacheTokens?: number; estimatedCost?: number };
+}
+
+export const KitnContextMeter = createKitnComponent<KitnContextMeterProps>(
+  'kitn-context-meter',
+  ["theme","context"],
+  {  },
+);
+
+export interface KitnConversationListProps extends KitnBaseProps {
+  /** 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: { id: string; userId?: undefined | string; teamId?: undefined | string; name: string; sortOrder: number; createdAt: string }[];
+  /** 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: { id: string; title: string; groupId?: undefined | string; scope: { type: "document" | "collection"; documentId?: undefined | string; filters?: undefined | { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | "transcript" | "markdown"; dateRange?: undefined | { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string }[];
+  /** The id of the currently-open conversation, highlighted in the list. */
+  activeId?: string;
+  onNewchat?: (event: CustomEvent<unknown>) => void;
+  onSelect?: (event: CustomEvent<unknown>) => void;
+  onTogglesidebar?: (event: CustomEvent<unknown>) => void;
+}
+
+export const KitnConversationList = createKitnComponent<KitnConversationListProps>(
+  'kitn-conversation-list',
+  ["theme","groups","conversations","activeId"],
+  { onNewchat: 'newchat', onSelect: 'select', onTogglesidebar: 'togglesidebar' },
+);
+
+export interface KitnEmptyProps extends KitnBaseProps {
+  /** Title text. Attribute: `empty-title` (`title` is a global HTML attribute). */
+  emptyTitle?: string;
+  /** Description text. */
+  description?: string;
+}
+
+export const KitnEmpty = createKitnComponent<KitnEmptyProps>(
+  'kitn-empty',
+  ["theme","emptyTitle","description"],
+  {  },
+);
+
+export interface KitnFeedbackBarProps extends KitnBaseProps {
+  /** The banner label (e.g. "Was this helpful?"). Attribute: `bar-title` (`title` is avoided — it's a global HTML attribute). */
+  barTitle?: string;
+  /** The user dismissed the banner. */
+  onClose?: (event: CustomEvent) => void;
+  /** The user clicked thumbs-up. */
+  onHelpful?: (event: CustomEvent) => void;
+  /** The user clicked thumbs-down. */
+  onNothelpful?: (event: CustomEvent) => void;
+}
+
+export const KitnFeedbackBar = createKitnComponent<KitnFeedbackBarProps>(
+  'kitn-feedback-bar',
+  ["theme","barTitle"],
+  { onClose: 'close', onHelpful: 'helpful', onNothelpful: 'nothelpful' },
+);
+
+export interface KitnFileUploadProps extends KitnBaseProps {
+  /** Allow selecting multiple files (default true). */
+  multiple?: boolean;
+  /** `accept` attribute for the file picker (e.g. `image/*`). */
+  accept?: string;
+  /** Disable the dropzone — no clicking, no drag-and-drop. */
+  disabled?: boolean;
+  /** Default dropzone label (overridable via the default slot). */
+  label?: string;
+  /** Files were picked or dropped. */
+  onFilesadded?: (event: CustomEvent<{ files: File[] }>) => void;
+}
+
+export const KitnFileUpload = createKitnComponent<KitnFileUploadProps>(
+  'kitn-file-upload',
+  ["theme","multiple","accept","disabled","label"],
+  { onFilesadded: 'filesadded' },
+);
+
+export interface KitnImageProps extends KitnBaseProps {
+  /** Base64-encoded image data (pair with `media-type`). */
+  base64?: string;
+  /** Raw image bytes (set as a JS property). */
+  bytes?: Uint8Array;
+  /** Alt text. */
+  alt?: string;
+  /** MIME type (default `image/png`). */
+  mediaType?: string;
+}
+
+export const KitnImage = createKitnComponent<KitnImageProps>(
+  'kitn-image',
+  ["theme","base64","bytes","alt","mediaType"],
+  {  },
+);
+
+export interface KitnLoaderProps extends KitnBaseProps {
+  /** The animation style: `'circular' | 'classic' | 'pulse' | 'pulse-dot' | 'dots' | 'typing' | 'wave' | 'bars' | 'terminal' | 'text-blink' | 'text-shimmer' | 'loading-dots'`. Defaults to `'circular'`. */
+  variant?: "circular" | "classic" | "pulse" | "pulse-dot" | "dots" | "typing" | "wave" | "bars" | "terminal" | "text-blink" | "text-shimmer" | "loading-dots";
+  /** Loader size: `'sm' | 'md' | 'lg'`. Defaults to `'md'`. */
+  size?: "sm" | "lg" | "md";
+  /** Label for the text-based variants. */
+  text?: string;
+}
+
+export const KitnLoader = createKitnComponent<KitnLoaderProps>(
+  'kitn-loader',
+  ["theme","variant","size","text"],
+  {  },
+);
+
+export interface KitnMarkdownProps extends KitnBaseProps {
+  /** The markdown source to render. */
+  content: string;
+  /** Text/markdown sizing. */
+  proseSize?: "xs" | "sm" | "base" | "lg";
+  /** Shiki theme for fenced code blocks. */
+  codeTheme?: string;
+  /** Disable syntax highlighting (no Shiki loads). */
+  codeHighlight?: boolean;
+}
+
+export const KitnMarkdown = createKitnComponent<KitnMarkdownProps>(
+  'kitn-markdown',
+  ["theme","content","proseSize","codeTheme","codeHighlight"],
+  {  },
+);
+
+export interface KitnMessageProps extends KitnBaseProps {
+  /** The full message object. Set as a JS property. */
+  message?: { id: string; role: "user" | "assistant"; content: string; reasoning?: { text: string; label?: string }; tools?: { type: string; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; output?: Record<string, unknown>; toolCallId?: string; errorText?: string }[]; attachments?: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }[]; actions?: ("copy" | "like" | "dislike" | "regenerate" | "edit")[] };
+  /** Convenience for simple cases when not passing a `message` object. */
+  role?: "user" | "assistant";
+  /** Convenience content (used when `message` is not set). */
+  content?: string;
+  /** Force markdown on/off. Defaults to on for assistant, off for user. */
+  markdown?: boolean;
+  /** Text/markdown sizing for the message body. */
+  proseSize?: "xs" | "sm" | "base" | "lg";
+  /** Shiki theme name used for fenced code blocks in the content. */
+  codeTheme?: string;
+  /** Disable syntax highlighting for code blocks (no Shiki loads). */
+  codeHighlight?: boolean;
+  /** An action button was clicked. */
+  onMessageaction?: (event: CustomEvent<{ messageId: string; action: "copy" | "like" | "dislike" | "regenerate" | "edit" }>) => void;
+}
+
+export const KitnMessage = createKitnComponent<KitnMessageProps>(
+  'kitn-message',
+  ["theme","message","role","content","markdown","proseSize","codeTheme","codeHighlight"],
+  { onMessageaction: 'messageaction' },
+);
+
+export interface KitnMessageSkillsProps extends KitnBaseProps {
+  /** The active skills to badge. Set as a JS property. */
+  skills: { id: string; name: string }[];
+}
+
+export const KitnMessageSkills = createKitnComponent<KitnMessageSkillsProps>(
+  'kitn-message-skills',
+  ["theme","skills"],
+  {  },
+);
+
+export interface KitnModelSwitcherProps extends KitnBaseProps {
+  /** The selectable models. Set as a JS property (array). */
+  models: { id: string; name: string; provider?: undefined | string }[];
+  /** The currently-selected model id. Defaults to the first model. */
+  currentModel?: string;
+  /** A model was selected. */
+  onModelchange?: (event: CustomEvent<{ modelId: string }>) => void;
+}
+
+export const KitnModelSwitcher = createKitnComponent<KitnModelSwitcherProps>(
+  'kitn-model-switcher',
+  ["theme","models","currentModel"],
+  { onModelchange: 'modelchange' },
+);
+
+export interface KitnPromptInputProps extends KitnBaseProps {
+  /** Controlled value of the input. When set, the host owns the text and must update it on `valuechange`; leave unset for uncontrolled behavior. */
+  value?: string;
+  /** Placeholder text shown in the empty input. */
+  placeholder?: string;
+  /** Disable the input and submit button entirely (non-interactive). */
+  disabled?: boolean;
+  /** Show the loading/streaming state and block submit (use while awaiting a reply). */
+  loading?: boolean;
+  /** Starter prompts shown above the input. Clicking one follows `suggestionMode`. Set as a JS property. */
+  suggestions?: string[];
+  /** What clicking a suggestion does: `'submit'` (default) sends it immediately as if typed and submitted; `'fill'` just places it in the input. */
+  suggestionMode?: "submit" | "fill";
+  /** Slash commands — when set, typing `/` opens the command palette. Set as a JS property. */
+  slashCommands?: { id: string; label: string; description?: string; category?: string }[];
+  /** Command ids to highlight as active. */
+  slashActiveIds?: string[];
+  /** Single-line palette rows. */
+  slashCompact?: boolean;
+  /** Show a Search (Globe) button in the left toolbar; clicking it fires a `search` event. */
+  search?: boolean;
+  /** Show a Voice (Mic) button in the left toolbar; clicking it fires a `voice` event. */
+  voice?: boolean;
+  /** Attachments to seed the input with (so a consumer can pre-populate staged files without an upload). Set as a JS property; the element then manages its own attachment state from there (add via the paperclip, remove per chip). */
+  attachments?: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }[];
+  /** The Search (Globe) toolbar button was clicked. */
+  onSearch?: (event: CustomEvent<undefined>) => void;
+  /** A slash command was chosen from the palette. */
+  onSlashselect?: (event: CustomEvent<{ command: { id: string; label: string; description?: undefined | string; category?: undefined | string } }>) => void;
+  /** The user submitted the prompt (Enter or send button) with its attachments. */
+  onSubmit?: (event: CustomEvent<{ value: string; attachments: { id: string; type: "file" | "source-document"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[] }>) => void;
+  /** A suggestion was clicked while `suggestion-mode="fill"`. */
+  onSuggestionclick?: (event: CustomEvent<{ value: string }>) => void;
+  /** The input text changed (fires on every keystroke). */
+  onValuechange?: (event: CustomEvent<{ value: string }>) => void;
+  /** The Voice (Mic) toolbar button was clicked. */
+  onVoice?: (event: CustomEvent<undefined>) => void;
+}
+
+export const KitnPromptInput = createKitnComponent<KitnPromptInputProps>(
+  'kitn-prompt-input',
+  ["theme","value","placeholder","disabled","loading","suggestions","suggestionMode","slashCommands","slashActiveIds","slashCompact","search","voice","attachments"],
+  { onSearch: 'search', onSlashselect: 'slashselect', onSubmit: 'submit', onSuggestionclick: 'suggestionclick', onValuechange: 'valuechange', onVoice: 'voice' },
+);
+
+export interface KitnPromptSuggestionsProps extends KitnBaseProps {
+  /** The suggestions. Strings, or `{ label, value }` when the displayed text and the emitted value differ. Set as a JS property. */
+  suggestions: (string | { label: string; value?: undefined | string })[];
+  /** Chip style: `'outline'` (default), `'ghost'`, or `'default'` (filled). */
+  variant?: "ghost" | "default" | "outline";
+  /** Size preset for each chip. Defaults to the pill default (`'lg'`); pass `'sm'` for smaller pills (or `'md'`). */
+  size?: "sm" | "lg" | "md" | "icon" | "icon-sm";
+  /** Full-width left-aligned rows instead of pills. */
+  block?: boolean;
+  /** Substring to highlight within each suggestion. */
+  highlight?: string;
+  /** A suggestion was clicked. */
+  onSelect?: (event: CustomEvent<{ value: string }>) => void;
+}
+
+export const KitnPromptSuggestions = createKitnComponent<KitnPromptSuggestionsProps>(
+  'kitn-prompt-suggestions',
+  ["theme","suggestions","variant","size","block","highlight"],
+  { onSelect: 'select' },
+);
+
+export interface KitnReasoningProps extends KitnBaseProps {
+  /** The reasoning text to display. */
+  text: string;
+  /** Trigger label. */
+  label?: string;
+  /** Controlled open state — set as a property (`el.open = true`). Omit for uncontrolled (the trigger toggles it). */
+  open?: boolean;
+  /** While true, auto-expands (and re-collapses when it flips false). */
+  streaming?: boolean;
+  /** Render `text` as markdown. */
+  markdown?: boolean;
+  /** Open state changed (via the trigger or streaming auto-open). */
+  onOpenchange?: (event: CustomEvent<{ open: boolean }>) => void;
+}
+
+export const KitnReasoning = createKitnComponent<KitnReasoningProps>(
+  'kitn-reasoning',
+  ["theme","text","label","open","streaming","markdown"],
+  { onOpenchange: 'openchange' },
+);
+
+export interface KitnResponseStreamProps extends KitnBaseProps {
+  /** Text to stream. A string, or an `AsyncIterable<string>` (set as a JS property — async iterables can't be HTML attributes). */
+  text?: string | AsyncIterable<string>;
+  /** Reveal animation. */
+  mode?: "typewriter" | "fade";
+  /** Characters/segments per tick. */
+  speed?: number;
+  /** Element tag to render as. */
+  as?: string;
+  /** Streaming finished. */
+  onComplete?: (event: CustomEvent) => void;
+}
+
+export const KitnResponseStream = createKitnComponent<KitnResponseStreamProps>(
+  'kitn-response-stream',
+  ["theme","text","mode","speed","as"],
+  { onComplete: 'complete' },
+);
+
+export interface KitnSourceProps extends KitnBaseProps {
+  /** The URL this citation links to (the domain also seeds the default label/favicon). */
+  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). */
+  headline?: string;
+  /** Hover-card body text describing the source. */
+  description?: string;
+  /** Show the source's favicon next to the trigger label. */
+  showFavicon?: boolean;
+}
+
+export const KitnSource = createKitnComponent<KitnSourceProps>(
+  'kitn-source',
+  ["theme","href","label","headline","description","showFavicon"],
+  {  },
+);
+
+export interface KitnSourceListProps extends KitnBaseProps {
+  /** The sources to render. Set as a JS property. */
+  sources: { href: string; title?: undefined | string; description?: undefined | string; label?: undefined | string; showFavicon?: undefined | boolean }[];
+  /** Show favicons on all items (per-item `showFavicon` overrides). */
+  showFavicon?: boolean;
+}
+
+export const KitnSourceList = createKitnComponent<KitnSourceListProps>(
+  'kitn-source-list',
+  ["theme","sources","showFavicon"],
+  {  },
+);
+
+export interface KitnTextShimmerProps extends KitnBaseProps {
+  /** The text to shimmer. */
+  text?: string;
+  /** Element tag to render as (default `span`). */
+  as?: string;
+  /** Animation duration in seconds. */
+  duration?: number;
+  /** Gradient spread (5–45). */
+  spread?: number;
+}
+
+export const KitnTextShimmer = createKitnComponent<KitnTextShimmerProps>(
+  'kitn-text-shimmer',
+  ["theme","text","as","duration","spread"],
+  {  },
+);
+
+export interface KitnThinkingBarProps extends KitnBaseProps {
+  /** The shimmering label, e.g. "Thinking…". */
+  text?: string;
+  /** When true, show a "stop" affordance that fires a `stop` event. */
+  stoppable?: boolean;
+  /** Label for the stop affordance. */
+  stopLabel?: string;
+  /** The "stop / answer now" affordance was clicked. */
+  onStop?: (event: CustomEvent) => void;
+}
+
+export const KitnThinkingBar = createKitnComponent<KitnThinkingBarProps>(
+  'kitn-thinking-bar',
+  ["theme","text","stoppable","stopLabel"],
+  { onStop: 'stop' },
+);
+
+export interface KitnToolProps extends KitnBaseProps {
+  /** The tool-call to display. Set as a JS property. */
+  tool?: { type: string; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; output?: Record<string, unknown>; toolCallId?: string; errorText?: string };
+  /** Start expanded. */
+  open?: boolean;
+}
+
+export const KitnTool = createKitnComponent<KitnToolProps>(
+  'kitn-tool',
+  ["theme","tool","open"],
+  {  },
+);
+
+export interface KitnVoiceInputProps extends KitnBaseProps {
+  /** Transcriber the host supplies — records audio, returns the text. This is a **function-valued property** (`el.transcribe = async blob => '...'`) because a value-returning callback can't be modelled as a fire-and-forget event. */
+  transcribe?: (audio: Blob) => Promise<string>;
+  /** Disable the mic button (non-interactive). */
+  disabled?: boolean;
+  /** Raw audio captured (before transcription) — for hosts that prefer to handle transcription themselves instead of via the `transcribe` property. */
+  onAudiocaptured?: (event: CustomEvent<{ blob: Blob }>) => void;
+  /** Transcription completed (the `transcribe` property resolved). */
+  onTranscription?: (event: CustomEvent<{ text: string }>) => void;
+}
+
+export const KitnVoiceInput = createKitnComponent<KitnVoiceInputProps>(
+  'kitn-voice-input',
+  ["theme","transcribe","disabled"],
+  { onAudiocaptured: 'audiocaptured', onTranscription: 'transcription' },
+);

package/frameworks/react/runtime.tsx

@@ -0,0 +1,94 @@
+// Runtime for the generated React wrappers (react/index.tsx). Renders the custom
+// element and bridges the React world to it: rich props are assigned as DOM
+// *properties* (via a ref, so arrays/objects pass through unstringified), and
+// `on<Event>` handlers are wired as `addEventListener` for the element's
+// CustomEvents. Layout props (className/style/id) pass straight through.
+import {
+  createElement,
+  forwardRef,
+  useImperativeHandle,
+  useLayoutEffect,
+  useRef,
+  type CSSProperties,
+  type ForwardRefExoticComponent,
+  type PropsWithoutRef,
+  type ReactNode,
+  type RefAttributes,
+} from 'react';
+
+export interface KitnBaseProps {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  className?: string;
+  style?: CSSProperties;
+  id?: string;
+  /** Light-DOM children passed through to the element (slots). */
+  children?: ReactNode;
+}
+
+export function createKitnComponent<P extends KitnBaseProps>(
+  tagName: string,
+  /** DOM-property names to assign from props (incl. `theme`). */
+  propNames: readonly string[],
+  /** Map of React handler prop → DOM event name, e.g. `{ onMessageaction: 'messageaction' }`. */
+  eventMap: Record<string, string>,
+): ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<HTMLElement>> {
+  const eventEntries = Object.entries(eventMap);
+
+  const Component = forwardRef<HTMLElement, P>((props, ref) => {
+    const elRef = useRef<HTMLElement | null>(null);
+    useImperativeHandle(ref, () => elRef.current as HTMLElement, []);
+    const p = props as Record<string, unknown>;
+
+    // Hold the latest handlers in a ref so the registered listeners always call
+    // the current handler (no stale closures) without re-binding on every render.
+    const handlersRef = useRef<Record<string, unknown>>({});
+    for (const reactName of Object.keys(eventMap)) handlersRef.current[reactName] = p[reactName];
+
+    // Assign rich props as DOM properties every render (idempotent). Arrays and
+    // objects pass through unstringified; booleans become real boolean
+    // properties so the element's `flag()` reads them. Updated props re-assign
+    // because this effect runs after every render.
+    useLayoutEffect(() => {
+      const el = elRef.current;
+      if (!el) return;
+      for (const name of propNames) {
+        if (name in p && p[name] !== undefined) (el as unknown as Record<string, unknown>)[name] = p[name];
+      }
+    });
+
+    // Wire CustomEvent listeners ONCE per element. Each stable listener reads the
+    // latest handler from handlersRef, so changing a handler's identity across
+    // renders takes effect without add/remove churn, and listeners are removed on
+    // unmount (no leaks).
+    useLayoutEffect(() => {
+      const el = elRef.current;
+      if (!el) return;
+      const added: Array<[string, EventListener]> = [];
+      for (const [reactName, domName] of eventEntries) {
+        const fn: EventListener = (e) => {
+          const handler = handlersRef.current[reactName];
+          if (typeof handler === 'function') (handler as (e: Event) => void)(e);
+        };
+        el.addEventListener(domName, fn);
+        added.push([domName, fn]);
+      }
+      return () => added.forEach(([n, fn]) => el.removeEventListener(n, fn));
+    }, []);
+
+    return createElement(
+      tagName,
+      {
+        ref: elRef,
+        className: p.className as string | undefined,
+        style: p.style as CSSProperties | undefined,
+        id: p.id as string | undefined,
+      },
+      // Light-DOM children pass straight through to the element (slots).
+      (p.children ?? null) as never,
+    );
+  });
+
+  Component.displayName = tagName;
+  return Component as ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<HTMLElement>>;
+}