@kitn.ai/ui 0.21.0 → 0.22.0

package/src/agent-tooling/registry.ts

@@ -53,6 +53,63 @@ export function listIntegrations(): Integration[] {
   return integrations;
 }
 
+/** One heading in `create-kai`'s gateway prompt. */
+export interface GatewayGroup {
+  id: 'no-backend' | 'bring-a-key' | 'bring-a-server';
+  title: string;
+  integrations: Integration[];
+}
+
+/**
+ * The gateway prompt's three groups, DERIVED — the thing the spec described and
+ * the catalog could not answer.
+ *
+ * It is here, and not in the CLI, for the reason `deps` is not in the spec's
+ * prose: a grouping maintained next to the menu that renders it is a second copy
+ * of the catalog, and it goes stale the first time an integration lands. Adding
+ * one now moves these groups by itself, because the only inputs are declared
+ * fields.
+ *
+ * THE ORDER OF THE TESTS IS THE DESIGN, not an implementation detail:
+ *
+ *   1. No route at all -> **No backend**. Exactly `mock` today, and derived from
+ *      the absence rather than from `id === 'mock'` or `category === 'mock'`: a
+ *      second no-backend entry (a canned transcript player, say) should land in
+ *      this group without editing this function.
+ *   2. `outOfBand !== 'none'` -> **Bring a server or runtime**, and this is
+ *      checked BEFORE the key test on purpose. `pydantic-ai` needs both a python
+ *      runtime and OPENAI_API_KEY; the groups are not disjoint in reality, so
+ *      something has to win, and the prerequisite does — a key is useless until
+ *      the service it authenticates is running. The prompt still asks for the
+ *      key afterwards; only the HEADING is decided here.
+ *   3. Everything else -> **Bring a key**.
+ *
+ * WHERE THIS DIVERGES FROM THE SPEC, ON PURPOSE. The spec's third group reads
+ * "Ollama, LangGraph, Mastra, Pydantic AI, Pi". `langgraph` comes out of this
+ * function in **Bring a key** instead, because its emitted route compiles the
+ * graph in process and asks for nothing but `OPENAI_API_KEY` — see the comment on
+ * its `outOfBand`. The spec sentence was written before the field existed and is
+ * wrong about that one entry; this is the derivation, so this is the answer.
+ */
+export function listGatewayGroups(): GatewayGroup[] {
+  const hasRoute = (i: Integration) =>
+    i.webRoute !== undefined || Object.keys(i.routeTemplates).length > 0;
+
+  const groups: GatewayGroup[] = [
+    { id: 'no-backend', title: 'No backend', integrations: [] },
+    { id: 'bring-a-key', title: 'Bring a key', integrations: [] },
+    { id: 'bring-a-server', title: 'Bring a server or runtime', integrations: [] },
+  ];
+  const into = (id: GatewayGroup['id']) => groups.find((g) => g.id === id)!;
+
+  for (const integration of integrations) {
+    if (!hasRoute(integration)) into('no-backend').integrations.push(integration);
+    else if (integration.outOfBand !== 'none') into('bring-a-server').integrations.push(integration);
+    else into('bring-a-key').integrations.push(integration);
+  }
+  return groups;
+}
+
 export function listArchetypes(): Archetype[] {
   return archetypes;
 }

package/src/agent-tooling/types.ts

@@ -44,6 +44,50 @@ export const Placement = z.enum(['side', 'full-page', 'docked-widget', 'inline']
  */
 export const KeyExposure = z.enum(['frontend-safe', 'needs-proxy']);
 
+/**
+ * What this integration needs the developer to supply OUT OF BAND — beyond an
+ * install and a key.
+ *
+ * `create-kai` groups its gateway prompt three ways: **No backend**, **Bring a
+ * key**, **Bring a server or runtime**. The third group is defined by exactly
+ * this question, and until now the catalog could not answer it. Every derivation
+ * that reproduced the spec's split did so by accident and broke on inspection:
+ *   · `category` does not separate them at all — `provider` holds `openai` and
+ *     `ollama`, `framework` holds `vercel-ai-sdk` and `langgraph`.
+ *   · a non-empty `routeTemplates` picks out `cloudflare`/`pi`/`pydantic-ai`,
+ *     which is a fact about how a route is EXPRESSED, not about what it needs.
+ *   · "declares a secret env var" puts `langgraph` and `pydantic-ai` in the key
+ *     group, which is right for one and wrong for the other.
+ * So it is declared, for the reason `keyExposure`, `forwardsFromClient` and
+ * `clientToolFormat` are each declared: only the route knows.
+ *
+ * The four values, and what makes each its own case for the CLI rather than a
+ * boolean it could have been:
+ *
+ *   · `'none'` ......... `npm install` plus (maybe) a key is the whole story.
+ *     The upstream is a remote HTTPS endpoint, or the agent runs IN the route.
+ *     `langgraph` is the one worth reading twice: it is in the spec's "server or
+ *     runtime" group and does not belong there — its emitted route builds the
+ *     graph in process (`createReactAgent` + `new ChatOpenAI(...)`), so there is
+ *     no LangGraph server anywhere and its runNote asks only for a key.
+ *   · `'local-server'` . a separate process must already be LISTENING before the
+ *     app works. The CLI cannot create it and must say so: `ollama serve` on
+ *     11434, a `mastra dev` server behind `MASTRA_URL`.
+ *   · `'local-binary'` . an executable must be on PATH; the route spawns it on
+ *     demand rather than talking to a port. Nothing is listening beforehand, so
+ *     "start the server" is the wrong instruction — `pi` is the case.
+ *   · `'language-runtime'` the emitted backend runs on a runtime the JS toolchain
+ *     does not provide, and the user starts it themselves. `pydantic-ai` is a
+ *     FastAPI service: `deps.pip`, `uvicorn main:app`, a second port.
+ *
+ * A boolean would collapse the last three, and they are three different sentences
+ * to print next to a menu item. The refinement below REFUSES an integration that
+ * declares nothing, for the same reason `keyExposure` does: a missing value read
+ * as `'none'` is a scaffold that says "npm run dev" to someone who needs to start
+ * Ollama first, and then reports as a broken kit.
+ */
+export const OutOfBand = z.enum(['none', 'local-server', 'local-binary', 'language-runtime']);
+
 /**
  * The packages an app must install BEYOND `@kitn.ai/ui` to run this
  * integration's route.
@@ -93,6 +137,25 @@ export const SECRET_ENV_VAR = /(?:KEY|TOKEN|SECRET|PASSWORD)$/;
  */
 const AUTH_HEADER = /Authorization\s*:|['"]x-api-key['"]\s*:/i;
 
+/**
+ * A route that FETCHES a loopback address — so something local has to be
+ * listening. `ollama`'s `fetch('http://localhost:11434/v1/chat/completions')` is
+ * the case this catches.
+ *
+ * Anchored at the fetch/URL call, not matched anywhere in the source, and that
+ * precision is the whole point. Two other routes mention loopback in prose:
+ * mastra's `throw new Error('MASTRA_URL is not set… e.g. http://localhost:4111')`
+ * and pi's `console.log('chat api: http://localhost:3001/api/chat')`. A bare
+ * /localhost/ would flag both — mastra for the right answer by the wrong
+ * evidence, pi for a line about its OWN listening port, which says nothing about
+ * what it depends on. A net that is right by accident is the thing this field
+ * exists to replace, so it is narrowed until it only fires on a real dependency.
+ */
+const LOOPBACK_FETCH = /\b(?:fetch|URL)\s*\(\s*['"`]https?:\/\/(?:localhost|127\.0\.0\.1)/;
+
+/** A route that shells out. The program it names must exist on the host. */
+const SPAWNS_PROCESS = /\bfrom\s+['"]node:child_process['"]|\bspawn\s*\(/;
+
 export const IntegrationSchema = z.object({
   id: z.string(),
   title: z.string(),
@@ -178,6 +241,13 @@ export const IntegrationSchema = z.object({
    * the one field where the reader needs to be told what is at stake.
    */
   keyExposure: KeyExposure.optional(),
+  /**
+   * See {@link OutOfBand}. Optional in the TYPE only so the refinement below owns
+   * the error message — Zod skips refinements when the base object already
+   * failed, so a plain required field would report "Invalid input" and this is a
+   * field whose reader needs to be told what the four values mean.
+   */
+  outOfBand: OutOfBand.optional(),
 }).superRefine((integration, ctx) => {
   // Enforced against the real catalog by `registry.test.ts`, which parses every
   // integration through this schema. A new host that forwards tools therefore
@@ -245,6 +315,68 @@ export const IntegrationSchema = z.object({
       });
     }
   }
+
+  // ---- outOfBand ----
+  //
+  // Same two-check shape as keyExposure, and the same asymmetry. The first
+  // refuses SILENCE. The second refuses a specific LIE, and only in the direction
+  // that costs the developer something: it can turn a `'none'` claim into an
+  // error, never the reverse. Over-declaring prints a prerequisite that was not
+  // strictly needed; under-declaring ships a scaffold that cannot possibly run
+  // and blames the kit.
+
+  if (integration.outOfBand === undefined) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ['outOfBand'],
+      message:
+        `integration '${integration.id}' declares no outOfBand. State what the developer must supply ` +
+        `BEYOND an install and a key, because that is the group create-kai's gateway prompt puts it in: ` +
+        `'none' (a remote endpoint, or the agent runs inside the route), 'local-server' (a process must ` +
+        `already be listening, e.g. 'ollama serve'), 'local-binary' (an executable on PATH that the route ` +
+        `spawns), or 'language-runtime' (the emitted backend needs a runtime the JS toolchain does not ` +
+        `provide, e.g. python + uvicorn). Read the route and the runNote to decide, not the category: ` +
+        `'provider' holds both openai and ollama. There is no default on purpose — a missing value read ` +
+        `as 'none' is a scaffold that says "npm run dev" to someone who has nothing to connect to.`,
+    });
+  }
+
+  if (integration.outOfBand === 'none') {
+    const routeSources = [
+      ...Object.values(integration.routeTemplates),
+      ...(integration.webRoute ? [integration.webRoute] : []),
+    ];
+    if (integration.language === 'python') {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['outOfBand'],
+        message:
+          `integration '${integration.id}' claims outOfBand 'none' but its route is python, so a consumer ` +
+          `whose whole toolchain is node cannot run it without an interpreter and an ASGI server they ` +
+          `start themselves. Use 'language-runtime'.`,
+      });
+    }
+    if (routeSources.some((code) => SPAWNS_PROCESS.test(code))) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['outOfBand'],
+        message:
+          `integration '${integration.id}' claims outOfBand 'none' but its route spawns a child process, ` +
+          `so the program it spawns has to be installed on the host — nothing in package.json puts it ` +
+          `there. Use 'local-binary'.`,
+      });
+    }
+    if (routeSources.some((code) => LOOPBACK_FETCH.test(code))) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['outOfBand'],
+        message:
+          `integration '${integration.id}' claims outOfBand 'none' but its route fetches a loopback ` +
+          `address, so something local has to be listening before the first message works. ` +
+          `Use 'local-server'.`,
+      });
+    }
+  }
 });
 export type Integration = z.infer<typeof IntegrationSchema>;
 

package/src/components/chat-thread.tsx

@@ -11,7 +11,8 @@ import {
   Context, ContextTrigger, ContextContent, ContextContentHeader,
   ContextContentBody, ContextContentFooter, ContextInputUsage, ContextOutputUsage,
 } from './context';
-import { DefaultPromptInput } from '../elements/default-input';
+import { DefaultPromptInput, type RejectedAttachment } from '../elements/default-input';
+import type { MediaTypeFilter } from '../wire/media-types';
 import type { TriggerDef } from './composer';
 import type { ChatMessage } from '../elements/chat-types';
 import type { ProseSize } from '../primitives/chat-config';
@@ -112,6 +113,13 @@ export interface ChatThreadProps {
   composerActions?: boolean;
   /** 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. */
@@ -392,6 +400,7 @@ export function ChatThread(props: ChatThreadProps) {
                   <DefaultPromptInput
                     value={current()} placeholder={props.placeholder} loading={props.loading === true}
                     suggestions={visibleSuggestions()} attachments={attachments()}
+                    accept={props.accept} onAttachmentsRejected={props.onAttachmentsRejected}
                     search={props.search === true} voice={props.voice === true}
                     triggers={props.triggers} kindIcons={props.kindIcons}
                     onValueChange={handleChange} onSubmit={handleSubmit} onSuggestionClick={handleSuggestionClick}

package/src/components/context.tsx

@@ -2,12 +2,12 @@ import { type JSX, Show, createContext, createMemo, useContext } from 'solid-js'
 import { HoverCardRoot, HoverCardTrigger, HoverCardContent } from '../ui/hover-card';
 import { cn } from '../utils/cn';
 import { Button } from '../ui/button';
+import { ProgressBar, type ProgressTone } from '../ui/progress-bar';
 
 const ICON_RADIUS = 10;
 const ICON_VIEWBOX = 24;
 const ICON_CENTER = 12;
 const ICON_STROKE_WIDTH = 2;
-const PERCENT_MAX = 100;
 
 /** Default fraction (0–1) at which the meter transitions to the warning colour. */
 export const DEFAULT_WARN_THRESHOLD = 0.7;
@@ -206,7 +206,6 @@ export function ContextContentHeader(props: ContextContentHeaderProps) {
   const displayPct = createMemo(() => fmtPercent.format(usedPercent()));
   const used = createMemo(() => fmtCompact.format(ctx.usedTokens));
   const total = createMemo(() => fmtCompact.format(ctx.maxTokens));
-  const barWidth = createMemo(() => `${Math.min(usedPercent() * PERCENT_MAX, PERCENT_MAX)}%`);
 
   const severity = createMemo<ContextSeverity>(() => {
     const pct = usedPercent();
@@ -215,11 +214,16 @@ export function ContextContentHeader(props: ContextContentHeaderProps) {
     return 'ok';
   });
 
-  const colorClass = createMemo(() => {
+  // Severity used to pick a bare hue class and nothing else, so the meter was a
+  // pair of styled divs: no role, no value, invisible to assistive tech. Map it to
+  // the shared ProgressBar's semantic `tone` instead and let that primitive supply
+  // `role="progressbar"` + aria-valuenow/min/max, rather than hand-rolling those
+  // onto the divs.
+  const tone = createMemo<ProgressTone>(() => {
     const s = severity();
-    if (s === 'danger') return 'bg-red-400';
-    if (s === 'warn') return 'bg-yellow-400';
-    return 'bg-primary';
+    if (s === 'danger') return 'error';
+    if (s === 'warn') return 'warning';
+    return 'primary';
   });
 
   return (
@@ -232,12 +236,14 @@ export function ContextContentHeader(props: ContextContentHeaderProps) {
           </p>
         </div>
         <div class="space-y-2">
-          <div class="h-1.5 w-full rounded-full bg-muted overflow-hidden">
-            <div
-              class={cn('h-full rounded-full transition-all', colorClass())}
-              style={{ width: barWidth() }}
-            />
-          </div>
+          {/* Values are the raw token counts, so a screen reader announces
+              "190,000 of 200,000" rather than a bare percentage. */}
+          <ProgressBar
+            value={ctx.usedTokens}
+            max={ctx.maxTokens}
+            tone={tone()}
+            aria-label="Context usage"
+          />
         </div>
       </Show>
     </div>

package/src/components/conversation-item.tsx

@@ -43,6 +43,12 @@ export function ConversationItem(props: ConversationItemProps) {
   return (
     <button
       data-conversation-id={local.conversation.id}
+      // `isActive` drives the selected LOOK below; it has to reach assistive tech
+      // too, or the active conversation is visible only to sighted users. `true`
+      // rather than `page` because this selects a conversation within the app, it
+      // is not page navigation — same call as ui/agent-card.tsx and ui/pane-group.tsx
+      // (ui/nav.tsx uses `page` because its items really are nav links).
+      aria-current={local.isActive ? 'true' : undefined}
       onClick={() => local.onSelect(local.conversation.id)}
       class={cn(
         'w-full rounded-lg text-left transition-colors',

package/src/components/model-switcher.tsx

@@ -1,6 +1,6 @@
 import { splitProps, For, Show, createSignal } from 'solid-js';
 import { cn } from '../utils/cn';
-import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, type DropdownController } from '../ui/dropdown';
+import { Dropdown, DropdownTrigger, DropdownContent, DropdownRadioItem, type DropdownController } from '../ui/dropdown';
 import { Button } from '../ui/button';
 import type { ModelOption } from '../types';
 
@@ -23,15 +23,37 @@ const Chevron = (props: { class?: string }) => (
   </svg>
 );
 
-function ModelRow(props: { model: ModelOption; currentModelId: string; onModelChange: (id: string) => void }) {
+/**
+ * One selectable model.
+ *
+ * A single-select list of models IS a radio group, so this routes through
+ * `DropdownRadioItem` (`role="menuitemradio"` + `aria-checked`) rather than
+ * hand-rolling those attributes onto a plain `DropdownItem`. Being the current
+ * model used to render as `font-medium` and nothing else — invisible to a screen
+ * reader. `kai-menu` already renders its radio items this way.
+ *
+ * `DropdownRadioItem` deliberately does NOT close the menu on activation (it is
+ * built for groups the consumer keeps mutating), so `onSelect` closes it here to
+ * preserve the pick-and-close behaviour `DropdownItem` used to provide.
+ */
+function ModelRow(props: {
+  model: ModelOption;
+  currentModelId: string;
+  onModelChange: (id: string) => void;
+  onClose: () => void;
+}) {
   const subtitle = () => props.model.description ?? props.model.provider;
+  const checked = () => props.model.id === props.currentModelId;
   return (
-    <DropdownItem onSelect={() => props.onModelChange(props.model.id)}>
+    <DropdownRadioItem
+      checked={checked()}
+      onSelect={() => { props.onModelChange(props.model.id); props.onClose(); }}
+    >
       <div class="flex flex-col">
-        <span class={cn('text-body', props.model.id === props.currentModelId && 'font-medium text-foreground')}>{props.model.name}</span>
+        <span class={cn('text-body', checked() && 'font-medium text-foreground')}>{props.model.name}</span>
         <Show when={subtitle()}><span class="text-caption text-muted-foreground">{subtitle()}</span></Show>
       </div>
-    </DropdownItem>
+    </DropdownRadioItem>
   );
 }
 
@@ -39,6 +61,14 @@ export function ModelSwitcher(props: ModelSwitcherProps) {
   const [local] = splitProps(props, ['models', 'currentModelId', 'onModelChange', 'class', 'defaultOpen', 'disabled', 'controllerRef']);
   const currentModel = () => local.models.find((m) => m.id === local.currentModelId);
 
+  // The rows are DropdownRadioItems, which stay open by design, so the switcher
+  // needs its own handle on the dropdown to close after a pick. Tapping
+  // `controllerRef` keeps that inside this component — the dropdown's own context
+  // is module-private — and the consumer's `controllerRef` is still called, so
+  // this is invisible from the outside.
+  let controller: DropdownController | undefined;
+  const closeMenu = () => controller?.setOpen(false);
+
   // Ungrouped models list first; grouped models collect under their group name,
   // preserving first-seen group order.
   const ungrouped = () => local.models.filter((m) => !m.group);
@@ -58,7 +88,7 @@ export function ModelSwitcher(props: ModelSwitcherProps) {
       <Dropdown
         defaultOpen={local.defaultOpen}
         disabled={local.disabled}
-        controllerRef={local.controllerRef}
+        controllerRef={(api) => { controller = api; local.controllerRef?.(api); }}
       >
         <DropdownTrigger as={(triggerProps: any) => (
           <Button variant="ghost" size="sm" class={cn('gap-1 text-meta text-muted-foreground', local.class)} {...triggerProps}>
@@ -68,7 +98,7 @@ export function ModelSwitcher(props: ModelSwitcherProps) {
         )} />
         <DropdownContent>
           <For each={ungrouped()}>
-            {(model) => <ModelRow model={model} currentModelId={local.currentModelId} onModelChange={local.onModelChange} />}
+            {(model) => <ModelRow model={model} currentModelId={local.currentModelId} onModelChange={local.onModelChange} onClose={closeMenu} />}
           </For>
           <For each={groups()}>
             {(group) => {
@@ -87,7 +117,7 @@ export function ModelSwitcher(props: ModelSwitcherProps) {
                   <Show when={open()}>
                     <div class="pl-2">
                       <For each={group.models}>
-                        {(model) => <ModelRow model={model} currentModelId={local.currentModelId} onModelChange={local.onModelChange} />}
+                        {(model) => <ModelRow model={model} currentModelId={local.currentModelId} onModelChange={local.onModelChange} onClose={closeMenu} />}
                       </For>
                     </div>
                   </Show>

package/src/components/toast.tsx

@@ -214,7 +214,12 @@ export function Toast(props: ToastProps) {
     <Show when={presence.present()}>
       <div
         ref={presence.setRef}
-        role="status"
+        // `variant` already picks the error ICON; it has to pick the ROLE too, or
+        // a failure is announced with the same (polite, easily missed) urgency as
+        // a success. `alert` is implicitly assertive and interrupts, which is what
+        // the region's `aria-live="polite"` alone will not do for the toast that
+        // actually matters. Same expression as ui/notice.tsx.
+        role={variant() === 'error' ? 'alert' : 'status'}
         data-appearance={appearance()}
         data-inverse={inverse() ? '' : undefined}
         data-closed={presence.state() === 'closed' ? '' : undefined}

package/src/elements/button.tsx

@@ -2,6 +2,7 @@ import { Show } from 'solid-js';
 import { Button } from '../ui/button';
 import { renderIcon } from '../ui/icon';
 import { defineWebComponent } from './define';
+import { createSlotText } from './slot-text';
 
 interface Props extends Record<string, unknown> {
   /** Visual style. `default` (filled), `subtle` (muted text, hover tint, the
@@ -17,7 +18,12 @@ interface Props extends Record<string, unknown> {
   /** Trailing icon, after the label (e.g. `"chevron-down"` for a menu affordance). */
   iconTrailing?: string;
   /** Accessible name. REQUIRED for icon-only buttons (no visible text); ignored
-   *  when you slot visible text, which already names the button. */
+   *  when you slot visible text, which already names the button. An `aria-label`
+   *  on top of visible text REPLACES that name rather than adding to it, so a
+   *  button reading "Save" that answers to "Submit" is unusable by speech input
+   *  (WCAG 2.5.3, Label in Name). The visible text wins. An `icon` / `icon-sm`
+   *  size hides the slot, which makes the button icon-only whatever you slotted,
+   *  so `label` is what names it there. */
   label?: string;
   /** Disable the button (non-interactive, dimmed). */
   disabled?: boolean;
@@ -71,6 +77,23 @@ defineWebComponent<Props, Events>('kai-button', {
   // `label` prop still names it for assistive tech).
   const iconOnly = () => props.size === 'icon' || props.size === 'icon-sm';
 
+  // Slotted text names the button by itself (name-from-contents reaches through
+  // the slot), so `label` must NOT be emitted on top of it: aria-label REPLACES
+  // the computed name, and a name that disagrees with the visible text locks
+  // speech-input users out of the control (WCAG 2.5.3). This is what the `label`
+  // doc has always promised, and what `kai-checkpoint` already does.
+  //
+  // `flatten` so a consumer who wraps <kai-button> in their own component and
+  // forwards a <slot> still counts as having visible text. Safe here because the
+  // default slot has no fallback content — see createSlotText.
+  const slotted = createSlotText({ flatten: true });
+
+  // The name to emit, or nothing. An `icon`/`icon-sm` size does not render the
+  // default slot at all, so whatever was slotted is INVISIBLE and `label` is the
+  // only name available — dropping it there would leave icon buttons nameless,
+  // which is the worse bug.
+  const ariaLabel = () => (!iconOnly() && slotted.hasText() ? undefined : props.label);
+
   // ── Imperative API (instance methods on the host) ──────────────────────────
   // The real <button> lives in the shadow root, so native focus()/blur()/click()
   // on the host hit the wrapper, not the control. Forward to the inner button.
@@ -104,7 +127,7 @@ defineWebComponent<Props, Events>('kai-button', {
       full={flag('full') || !iconOnly()}
       type={props.type ?? 'button'}
       disabled={flag('disabled')}
-      aria-label={props.label}
+      aria-label={ariaLabel()}
       onClick={() => dispatch('kai-click')}
     >
       {/* Leading icon: a slotted SVG (slot="icon") wins — drop in any icon
@@ -115,7 +138,7 @@ defineWebComponent<Props, Events>('kai-button', {
         </Show>
       </slot>
       <Show when={!iconOnly()}>
-        <slot />
+        <slot ref={slotted.ref} />
       </Show>
       <Show when={props.iconTrailing && !iconOnly()}>
         {renderIcon(props.iconTrailing, { class: 'size-4 shrink-0 opacity-60', imgClass: 'size-4 shrink-0', spanClass: 'inline-flex size-4 shrink-0 items-center justify-center', ariaHidden: true })}

package/src/elements/chat.tsx

@@ -5,6 +5,7 @@ import { ChatThread, type ChatThreadProps, type ChatThreadContextUsage, type Cha
 import { cardComponentsFromTags } from './message';
 import { createMessagesGuard } from './validate-messages';
 import type { AttachmentData } from '../components/attachments';
+import type { RejectedAttachment } from './default-input';
 import type { ChatMessage } from './chat-types';
 import type { TriggerDef } from '../components/composer';
 import type { ComposerDoc } from '../primitives/composer-model';
@@ -13,7 +14,25 @@ import type { ModelOption } from '../types';
 
 type Props = Omit<ChatThreadProps,
   'class' | 'onValueChange' | 'onSubmit' | 'onAttachmentsChange' | 'onSuggestionClick' | 'onModelChange'
-  | 'onMessageAction' | 'onSearch' | 'onVoice' | 'controllerRef' | 'cardTypes' | 'cardSchemas' | 'messages'> & Record<string, unknown> & {
+  | 'onMessageAction' | 'onSearch' | 'onVoice' | 'controllerRef' | 'cardTypes' | 'cardSchemas' | 'messages'
+  | 'accept' | 'onAttachmentsRejected'> & Record<string, unknown> & {
+    /** Which attachment media types the user may stage, in HTML `accept` syntax:
+     *  `<kai-chat accept="image/*,application/pdf">`. A plain string, so unlike
+     *  `messages` it DOES work as an attribute. Omitted means no filter.
+     *
+     *  MEDIA TYPES ONLY -- exact (`image/png`) or subtype wildcard (`text/*`).
+     *  HTML allows a file extension here and this does not: `accept=".py"` THROWS
+     *  with the entry named, rather than silently resolving to a picker that
+     *  accepts nothing.
+     *
+     *  It can only NARROW what the kit can already encode: `accept="image/*"`
+     *  resolves to the four image formats both APIs take, not to every image type
+     *  the OS offers. Pass the SAME string to `toOpenAIMessages(msgs, { accept })`
+     *  and the picker and the wire cannot disagree -- both resolve it through
+     *  `resolveMediaPolicy` against one declaration. That declaration is readable
+     *  as `encodableMediaTypes()` from `@kitn.ai/ui/wire`, if you would rather
+     *  build your own picker than use this prop. */
+    accept?: string;
     /** The full message thread to render, newest last. Each entry carries its
      *  role, ordered `parts`, and optional actions/avatar/feedback. Set as a JS
      *  property (`el.messages = [...]`); a NEW array reference per streaming
@@ -54,6 +73,11 @@ interface Events {
   /** The staged attachments changed (file added or removed). Carries the full
    *  current list so a consumer can react in real time. */
   'kai-attachments-change': { attachments: AttachmentData[] };
+  /** One or more picked files were refused because `accept` excluded them. The
+   *  element renders NO message of its own: it reports the facts (name, media
+   *  type, whether the kit could have sent it) and what the user should see is
+   *  the application's call. Only ever fires when `accept` is set. */
+  'kai-attachments-rejected': { rejected: RejectedAttachment[] };
   /** A suggestion chip was clicked (only in `suggestion-mode="fill"`). */
   'kai-suggestion-click': { value: string };
   /** An action button on a message was clicked. `action` is the built-in name or
@@ -74,7 +98,7 @@ defineWebComponent<Props, Events>('kai-chat', {
   codeTheme: 'github-dark-dimmed', codeHighlight: true, chatTitle: undefined,
   models: undefined, currentModel: undefined, context: undefined, scrollButton: true,
   search: false, voice: false, triggers: undefined, kindIcons: undefined,
-  actionsReveal: 'always', cardTypes: undefined, cardSchemas: undefined,
+  actionsReveal: 'always', cardTypes: undefined, cardSchemas: undefined, accept: undefined,
 }, (props, { dispatch, flag, element, expose }) => {
   // `messages` is an untyped boundary: a consumer can hand it anything at
   // runtime (a pre-0.20.0 `{ id, role, content }` array, in particular). Skip
@@ -145,7 +169,9 @@ defineWebComponent<Props, Events>('kai-chat', {
     cardSchemas={props.cardSchemas as Record<string, object> | undefined}
     onValueChange={(value) => dispatch('kai-value-change', { value })}
     onSubmit={(detail) => dispatch('kai-submit', detail)}
+    accept={props.accept as string | undefined}
     onAttachmentsChange={(attachments) => dispatch('kai-attachments-change', { attachments })}
+    onAttachmentsRejected={(rejected) => dispatch('kai-attachments-rejected', { rejected })}
     onSuggestionClick={(value) => dispatch('kai-suggestion-click', { value })}
     onModelChange={(modelId) => dispatch('kai-model-change', { modelId })}
     onMessageAction={(detail) => dispatch('kai-message-action', detail)}