@kitn.ai/ui 0.21.0 → 0.22.0

package/src/elements/default-input.tsx

@@ -16,6 +16,32 @@ import {
 } from '../components/attachments';
 import { actionIcon } from '../ui/action-icons';
 import type { CustomAction } from './chat-types';
+// The LEAF module, deliberately not the `../wire` barrel: this needs the media
+// declaration, and importing the barrel would pull the whole stream adapter into
+// the elements bundle for a table of strings. Sharing the module itself (rather
+// than copying the list into the composer) is the entire point -- a second list
+// here is the drift this design exists to prevent.
+import { resolveMediaPolicy, type MediaTypeFilter } from '../wire/media-types';
+// Also a leaf, and imported for the same reason: when the browser cannot name a
+// file, the question "can this be sent?" is answered by decoding its bytes, and
+// this module is where that decode already lives. Asking IT rather than growing
+// a second decoder here is what keeps the composer's answer and the encoder's
+// answer the same answer, byte for byte, instead of two that agree today.
+import { classifyAttachment } from '../wire/files';
+
+/** One file the composer refused, as facts rather than as a message. The kit
+ *  says what happened; the application decides what the user reads. */
+export interface RejectedAttachment {
+  filename: string;
+  /** The browser's media type for the file, or `''` when it could not tell. An
+   *  empty one is not by itself why a file was rejected: an unnamed file is
+   *  decided by decoding its bytes, so `''` here means the decode is what said
+   *  no (binary), or that your `accept` left no text type for it to land in. */
+  mediaType: string;
+  /** `'filtered'` = this kit could have sent it, your `accept` excluded it.
+   *  `'unsupported'` = no API takes this as message content at all. */
+  reason: 'filtered' | 'unsupported';
+}
 
 export interface DefaultPromptInputProps {
   /** String = controlled text mirror; ComposerDoc = a seed that pre-populates pills. */
@@ -31,6 +57,19 @@ export interface DefaultPromptInputProps {
    *  `onAttachmentsChange` is provided (e.g. when a `+` menu already covers
    *  file-attach). Defaults to `true`. */
   attach?: boolean;
+  /** Which attachment media types the user may stage, in HTML `accept` syntax
+   *  (`'image/*,application/pdf'`). Omitted means no filter, exactly as before.
+   *
+   *  NARROWED BY WHAT THE ENCODERS CAN SEND: `'image/*'` here resolves to the
+   *  four image formats both APIs actually accept, not to every image type the
+   *  OS will offer. It is the same string, resolved by the same function against
+   *  the same declaration, as `toOpenAIMessages(msgs, { accept })` -- so a file
+   *  the picker allows is a file the wire can carry. */
+  accept?: MediaTypeFilter;
+  /** Files that were dropped because `accept` excluded them. Carries the facts
+   *  (name, media type, reason) and renders nothing itself: what the user should
+   *  see is the application's call, not the kit's. */
+  onAttachmentsRejected?: (rejected: RejectedAttachment[]) => void;
   /** Show a Search (Globe) button in the left toolbar; calls `onSearch`. */
   search?: boolean;
   /** Show a Voice (Mic) button in the left toolbar; calls `onVoice`. */
@@ -64,7 +103,23 @@ export interface DefaultPromptInputProps {
   onComposerChange?: (change: ComposerChange) => void;
 }
 
-function fileToAttachment(file: File): AttachmentData {
+/** The staged file as a `data:` URI.
+ *
+ *  NOT `URL.createObjectURL`. An object URL resolves only inside the tab that
+ *  minted it, so it renders a perfect thumbnail here and is meaningless to
+ *  anything downstream — `toOpenAIMessages` / `toAnthropicMessages` refuse it,
+ *  and before they refused it the attachment reached the model as nothing at
+ *  all. A data URI previews identically and is the one form both providers
+ *  actually take. */
+const readAsDataUrl = (file: File): Promise<string> =>
+  new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(String(reader.result));
+    reader.onerror = () => reject(reader.error ?? new Error(`Could not read ${file.name}`));
+    reader.readAsDataURL(file);
+  });
+
+async function fileToAttachment(file: File): Promise<AttachmentData> {
   const id =
     typeof crypto !== 'undefined' && crypto.randomUUID
       ? crypto.randomUUID()
@@ -74,7 +129,9 @@ function fileToAttachment(file: File): AttachmentData {
     type: 'file',
     filename: file.name,
     mediaType: file.type || undefined,
-    url: file.type.startsWith('image/') ? URL.createObjectURL(file) : undefined,
+    // EVERY file, not just images. A document used to get no `url` at all,
+    // which left it unencodable for exactly the same reason a blob: URL is.
+    url: await readAsDataUrl(file),
   };
 }
 
@@ -83,9 +140,67 @@ export function DefaultPromptInput(props: DefaultPromptInputProps) {
   const attachments = () => props.attachments ?? [];
   const canAttach = () => !!props.onAttachmentsChange;
 
-  const addFiles = (files: FileList | null) => {
+  // The SAME resolver the encoders call, on the same declaration. Recomputed
+  // reactively so a host that swaps `accept` at runtime moves the picker hint
+  // and the filter together.
+  const mediaPolicy = () => resolveMediaPolicy({ accept: props.accept });
+
+  const addFiles = async (files: FileList | null) => {
     if (!files?.length || !props.onAttachmentsChange) return;
-    props.onAttachmentsChange([...attachments(), ...Array.from(files).map(fileToAttachment)]);
+
+    // The `accept` ATTRIBUTE below is only a hint — every OS dialog offers an
+    // "All Files" escape, and it does not apply to drag-and-drop at all. So the
+    // filter that actually holds is this one, in JS, on the files as staged.
+    const policy = mediaPolicy();
+    const picked = Array.from(files);
+    // No `accept` means no filtering, which is what every existing consumer gets
+    // today. Opting in is what turns the picker into a guarantee.
+    const decisions = picked.map((file) =>
+      props.accept === undefined ? undefined : policy.decide(file.type),
+    );
+    // Read a file when its media type says yes, and ALSO when its media type
+    // says nothing at all: `undetermined` means the browser could not name it,
+    // and the only honest way to answer is to look at the bytes. Reading is the
+    // cost of that answer, so it is spent only on files that could still be
+    // staged — a file the filter already rejected is never read.
+    const needsBytes = (d: (typeof decisions)[number]): boolean =>
+      d === undefined || d.status === 'allowed' || d.status === 'undetermined';
+    // One parallel pass, index-aligned with `picked`, so the staged order is the
+    // PICK order rather than whichever file finished reading first.
+    const read = await Promise.all(
+      picked.map((file, i) => (needsBytes(decisions[i]) ? fileToAttachment(file) : undefined)),
+    );
+
+    const staged: AttachmentData[] = [];
+    const rejected: RejectedAttachment[] = [];
+    picked.forEach((file, i) => {
+      const decision = decisions[i];
+      const attachment = read[i];
+      if (decision === undefined || decision.status === 'allowed') {
+        if (attachment) staged.push(attachment);
+        return;
+      }
+      if (decision.status === 'undetermined') {
+        // The bytes are in hand now, so the encoder can answer for real. Its
+        // verdict IS the composer's verdict: staging anything it would refuse is
+        // the exact defect (#186) this whole design exists to prevent.
+        if (attachment && classifyAttachment(attachment, policy).status === 'encodable') {
+          staged.push(attachment);
+        } else {
+          // Not `filtered`: the kit could not encode this either, so pointing
+          // the developer at their own `accept` would send them the wrong way.
+          rejected.push({ filename: file.name, mediaType: file.type, reason: 'unsupported' });
+        }
+        return;
+      }
+      rejected.push({ filename: file.name, mediaType: file.type, reason: decision.status });
+    });
+
+    if (rejected.length > 0) props.onAttachmentsRejected?.(rejected);
+    if (staged.length === 0) return;
+    // Re-read `attachments()` AFTER the await — a second drop while these were
+    // being read would otherwise be overwritten by this call's stale snapshot.
+    props.onAttachmentsChange?.([...attachments(), ...staged]);
   };
   const removeAttachment = (id: string) =>
     props.onAttachmentsChange?.(attachments().filter((a) => a.id !== id));
@@ -156,8 +271,16 @@ export function DefaultPromptInput(props: DefaultPromptInputProps) {
                 type="file"
                 multiple
                 class="hidden"
+                // Derived from the same policy as the filter above, never spelled
+                // out again. `accept="image/*"` narrows to the image formats the
+                // wire can actually carry, so the OS dialog greys out the SVG
+                // that would otherwise 400 at request time.
+                accept={props.accept === undefined ? undefined : mediaPolicy().accept}
                 onChange={(e) => {
-                  addFiles(e.currentTarget.files);
+                  // Reading is async now, so this is deliberately not awaited.
+                  // `addFiles` captures the FileList synchronously, before its
+                  // first await, so clearing the input below cannot race it.
+                  void addFiles(e.currentTarget.files);
                   e.currentTarget.value = ''; // allow re-picking the same file
                 }}
               />

package/src/elements/element-meta.json

@@ -843,7 +843,7 @@
         "type": "undefined | string",
         "optional": true,
         "scalar": true,
-        "description": "Accessible name. REQUIRED for icon-only buttons (no visible text); ignored when you slot visible text, which already names the button.",
+        "description": "Accessible name. REQUIRED for icon-only buttons (no visible text); ignored 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.",
         "displayType": "undefined | string"
       },
       {
@@ -1572,6 +1572,14 @@
         "default": "'always'",
         "displayType": "undefined | \"always\" | \"hover\""
       },
+      {
+        "name": "accept",
+        "type": "undefined | string",
+        "optional": true,
+        "scalar": true,
+        "description": "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.",
+        "displayType": "undefined | string"
+      },
       {
         "name": "messages",
         "type": "undefined | { id: string; role: \"user\" | \"assistant\"; parts: ({ type: \"text\"; text: string; raw?: undefined | { source: string; payload: unknown } } | { type: \"reasoning\"; text: string; label?: undefined | string; index?: undefined | number; streamId?: undefined | string; signature?: undefined | string; raw?: undefined | { source: string; payload: unknown } } | { type: \"tool\"; tool: { type: string; kind?: undefined | \"command\" | \"file-change\" | \"search\" | \"fetch\" | \"mcp\" | \"image\" | \"generic\"; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; rawInput?: undefined | string; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string; raw?: undefined | { source: string; payload: unknown } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"card\"; envelope: { type: string; id: string; data: unknown; title?: undefined | string; resolution?: undefined | { kind: \"action\"; action: string; payload?: unknown; at?: undefined | string } | { kind: \"submit\"; data: unknown; at?: undefined | string } | { kind: \"dismissed\"; at?: undefined | string } | { kind: \"expired\"; reason?: undefined | string; at?: undefined | string } }; raw?: undefined | { source: string; payload: unknown } } | { type: \"source\"; source: { id?: undefined | string; url?: undefined | string; title?: undefined | string; snippet?: undefined | string; index?: undefined | number }; raw?: undefined | { source: string; payload: unknown } } | { type: \"file\"; attachment: { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }; raw?: undefined | { source: string; payload: unknown } })[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\" | { id: string; label: string; icon?: undefined | string; tooltip?: undefined | string })[]; avatar?: undefined | { src?: undefined | string; fallback?: undefined | string; alt?: undefined | string }; feedback?: undefined | \"like\" | \"dislike\" }[]",
@@ -1608,6 +1616,12 @@
         "description": "The staged attachments changed (file added or removed). Carries the full current list so a consumer can react in real time.",
         "displayDetail": "{ attachments: { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[] }"
       },
+      {
+        "name": "kai-attachments-rejected",
+        "detail": "{ rejected: { filename: string; mediaType: string; reason: \"filtered\" | \"unsupported\" }[] }",
+        "description": "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.",
+        "displayDetail": "{ rejected: { filename: string; mediaType: string; reason: \"filtered\" | \"unsupported\" }[] }"
+      },
       {
         "name": "kai-message-action",
         "detail": "{ messageId: string; action: string; state?: undefined | \"on\" | \"off\" }",
@@ -2792,7 +2806,19 @@
         "storyId": "solid-advanced-elements-contextcacheusage--docs"
       }
     ],
-    "tokens": []
+    "tokens": [],
+    "parts": [
+      {
+        "name": "track",
+        "doc": "The usage meter track inside the hover-card breakdown. Carries `role=\"progressbar\"` and is in the DOM only while the card is open. Restyle its height, radius, or background from outside.",
+        "recipe": "kai-context::part(track) { height: 0.5rem }"
+      },
+      {
+        "name": "fill",
+        "doc": "The used-tokens portion of that meter. Its width follows `usedTokens / maxTokens`; its default color is the severity hue picked by `warnThreshold` / `dangerThreshold`, so recoloring it from outside replaces that signal.",
+        "recipe": "kai-context::part(fill) { background: var(--color-tool-blue) }"
+      }
+    ]
   },
   {
     "tag": "kai-conversations",
@@ -4457,7 +4483,7 @@
         "type": "undefined | string",
         "optional": true,
         "scalar": true,
-        "description": "Built-in trigger: a text label (e.g. `\"High\"`).",
+        "description": "Built-in trigger: a text label (e.g. `\"High\"`). This is the trigger's VISIBLE text, so it is also its accessible name, and `label` does not override it: an accessible name that does not contain the visible text is unreachable by speech input, which is what WCAG 2.5.3 (Label in Name) exists for. A slotted `slot=\"trigger\"` replaces this built-in trigger entirely and is named differently; see `label`.",
         "displayType": "undefined | string"
       },
       {
@@ -4473,7 +4499,7 @@
         "type": "undefined | string",
         "optional": true,
         "scalar": true,
-        "description": "Accessible name for an icon-only trigger (no visible label).",
+        "description": "Accessible name for a trigger with no visible label. Ignored when `triggerLabel` is set, which is already the visible name. It DOES name a slotted `slot=\"trigger\"`, and that is a difference in what the two slots MEAN, not a limitation. `<kai-button>`'s slot IS the button's label, so text slotted there is the name and `label` steps aside. This slot is VISUAL content, a `+` or an `<svg>`, with the name supplied separately: decoration beside a name, never a second name competing with one. So `label` names the trigger here by design. Slotting a real WORD rather than a glyph makes that word a visible label, and an accessible name has to contain the visible text. Then either drop `label` or make it contain the word you slotted.",
         "displayType": "undefined | string"
       },
       {

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

@@ -280,7 +280,7 @@ export interface KaiButtonElement extends HTMLElement {
   icon?: string;
   /** 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. */
+  /** Accessible name. REQUIRED for icon-only buttons (no visible text); ignored 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;
@@ -418,6 +418,8 @@ export interface KaiChatElement extends HTMLElement {
   kindIcons?: Record<string, string>;
   /** Whether each message's action bar is always visible (`'always'`, default) or only revealed on hover of that message row (`'hover'`). */
   actionsReveal?: "always" | "hover";
+  /** 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 chunk re-renders (mutating in place does not). Omit for an empty thread. Re-declared here (rather than inherited from `ChatThreadProps`) because the ELEMENT registers a `[]` default and renders the empty state without it, while the SolidJS `<ChatThread>` component still requires it. The facade hands it a validated array either way. Matches `<kai-thread>`. */
   messages: { id: string; role: "user" | "assistant"; parts: ({ type: "text"; text: string; raw?: { source: string; payload: unknown } } | { type: "reasoning"; text: string; label?: string; index?: number; streamId?: string; signature?: string; raw?: { source: string; payload: unknown } } | { type: "tool"; tool: { type: string; kind?: "command" | "file-change" | "search" | "fetch" | "mcp" | "image" | "generic"; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; rawInput?: string; output?: Record<string, unknown>; toolCallId?: string; errorText?: string; raw?: { source: string; payload: unknown } }; raw?: { source: string; payload: unknown } } | { type: "card"; envelope: { type: string; id: string; data: unknown; title?: string; resolution?: { kind: "action"; action: string; payload?: unknown; at?: string } | { kind: "submit"; data: unknown; at?: string } | { kind: "dismissed"; at?: string } | { kind: "expired"; reason?: string; at?: string } }; raw?: { source: string; payload: unknown } } | { type: "source"; source: { id?: string; url?: string; title?: string; snippet?: string; index?: number }; raw?: { source: string; payload: unknown } } | { type: "file"; attachment: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }; raw?: { source: string; payload: unknown } })[]; actions?: ("copy" | "like" | "dislike" | "regenerate" | "edit" | { id: string; label: string; icon?: string; tooltip?: string })[]; avatar?: { src?: string; fallback?: string; alt?: string }; feedback?: "like" | "dislike" }[];
   /** Optional card type -> custom-element tag overrides/additions for `card` parts (merged over the built-ins). Property: `el.cardTypes`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type. */
@@ -919,11 +921,11 @@ export interface KaiMenuElement extends HTMLElement {
   placement?: string;
   /** Built-in trigger: leading icon (a named icon like `"plus"`, an image URL/data-URI, or text). Use this instead of slotting `slot="trigger"` for the common case; a slotted trigger overrides it. */
   triggerIcon?: string;
-  /** Built-in trigger: a text label (e.g. `"High"`). */
+  /** Built-in trigger: a text label (e.g. `"High"`). This is the trigger's VISIBLE text, so it is also its accessible name, and `label` does not override it: an accessible name that does not contain the visible text is unreachable by speech input, which is what WCAG 2.5.3 (Label in Name) exists for. A slotted `slot="trigger"` replaces this built-in trigger entirely and is named differently; see `label`. */
   triggerLabel?: string;
   /** Built-in trigger: a trailing icon (e.g. `"chevron-down"` for a select look). */
   triggerIconTrailing?: string;
-  /** Accessible name for an icon-only trigger (no visible label). */
+  /** Accessible name for a trigger with no visible label. Ignored when `triggerLabel` is set, which is already the visible name. It DOES name a slotted `slot="trigger"`, and that is a difference in what the two slots MEAN, not a limitation. `<kai-button>`'s slot IS the button's label, so text slotted there is the name and `label` steps aside. This slot is VISUAL content, a `+` or an `<svg>`, with the name supplied separately: decoration beside a name, never a second name competing with one. So `label` names the trigger here by design. Slotting a real WORD rather than a glyph makes that word a visible label, and an accessible name has to contain the visible text. Then either drop `label` or make it contain the word you slotted. */
   label?: string;
   /** Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute, the menu still self-manages on click/keyboard). Set `el.open = true`, or `<kai-menu open>`; listen for `kai-open-change`. */
   open?: boolean;
@@ -2031,7 +2033,7 @@ export interface KaiButtonElementProps {
   icon?: string;
   /** 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. */
+  /** Accessible name. REQUIRED for icon-only buttons (no visible text); ignored 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;
@@ -2151,6 +2153,8 @@ export interface KaiChatElementProps {
   kindIcons?: Record<string, string>;
   /** Whether each message's action bar is always visible (`'always'`, default) or only revealed on hover of that message row (`'hover'`). */
   actionsReveal?: "always" | "hover";
+  /** 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 chunk re-renders (mutating in place does not). Omit for an empty thread. Re-declared here (rather than inherited from `ChatThreadProps`) because the ELEMENT registers a `[]` default and renders the empty state without it, while the SolidJS `<ChatThread>` component still requires it. The facade hands it a validated array either way. Matches `<kai-thread>`. */
   messages?: { id: string; role: "user" | "assistant"; parts: ({ type: "text"; text: string; raw?: { source: string; payload: unknown } } | { type: "reasoning"; text: string; label?: string; index?: number; streamId?: string; signature?: string; raw?: { source: string; payload: unknown } } | { type: "tool"; tool: { type: string; kind?: "command" | "file-change" | "search" | "fetch" | "mcp" | "image" | "generic"; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; rawInput?: string; output?: Record<string, unknown>; toolCallId?: string; errorText?: string; raw?: { source: string; payload: unknown } }; raw?: { source: string; payload: unknown } } | { type: "card"; envelope: { type: string; id: string; data: unknown; title?: string; resolution?: { kind: "action"; action: string; payload?: unknown; at?: string } | { kind: "submit"; data: unknown; at?: string } | { kind: "dismissed"; at?: string } | { kind: "expired"; reason?: string; at?: string } }; raw?: { source: string; payload: unknown } } | { type: "source"; source: { id?: string; url?: string; title?: string; snippet?: string; index?: number }; raw?: { source: string; payload: unknown } } | { type: "file"; attachment: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }; raw?: { source: string; payload: unknown } })[]; actions?: ("copy" | "like" | "dislike" | "regenerate" | "edit" | { id: string; label: string; icon?: string; tooltip?: string })[]; avatar?: { src?: string; fallback?: string; alt?: string }; feedback?: "like" | "dislike" }[];
   /** Optional card type -> custom-element tag overrides/additions for `card` parts (merged over the built-ins). Property: `el.cardTypes`. Typed as a plain string map (not the `CardTagMap` alias) so the generated React wrapper inlines it instead of emitting an unresolved named type. */
@@ -2548,11 +2552,11 @@ export interface KaiMenuElementProps {
   placement?: string;
   /** Built-in trigger: leading icon (a named icon like `"plus"`, an image URL/data-URI, or text). Use this instead of slotting `slot="trigger"` for the common case; a slotted trigger overrides it. */
   triggerIcon?: string;
-  /** Built-in trigger: a text label (e.g. `"High"`). */
+  /** Built-in trigger: a text label (e.g. `"High"`). This is the trigger's VISIBLE text, so it is also its accessible name, and `label` does not override it: an accessible name that does not contain the visible text is unreachable by speech input, which is what WCAG 2.5.3 (Label in Name) exists for. A slotted `slot="trigger"` replaces this built-in trigger entirely and is named differently; see `label`. */
   triggerLabel?: string;
   /** Built-in trigger: a trailing icon (e.g. `"chevron-down"` for a select look). */
   triggerIconTrailing?: string;
-  /** Accessible name for an icon-only trigger (no visible label). */
+  /** Accessible name for a trigger with no visible label. Ignored when `triggerLabel` is set, which is already the visible name. It DOES name a slotted `slot="trigger"`, and that is a difference in what the two slots MEAN, not a limitation. `<kai-button>`'s slot IS the button's label, so text slotted there is the name and `label` steps aside. This slot is VISUAL content, a `+` or an `<svg>`, with the name supplied separately: decoration beside a name, never a second name competing with one. So `label` names the trigger here by design. Slotting a real WORD rather than a glyph makes that word a visible label, and an accessible name has to contain the visible text. Then either drop `label` or make it contain the word you slotted. */
   label?: string;
   /** Drive/observe open state (Shoelace-style: settable + reflected to the `open` attribute, the menu still self-manages on click/keyboard). Set `el.open = true`, or `<kai-menu open>`; listen for `kai-open-change`. */
   open?: boolean;
@@ -3277,6 +3281,8 @@ export interface KaiChainOfThoughtElementEvents {
 export interface KaiChatElementEvents {
   /** The staged attachments changed (file added or removed). Carries the full current list so a consumer can react in real time. */
   onKaiAttachmentsChange?: (event: CustomEvent<{ attachments: { id: string; type: "file" | "source-document"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[] }>) => void;
+  /** 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. */
+  onKaiAttachmentsRejected?: (event: CustomEvent<{ rejected: { filename: string; mediaType: string; reason: "filtered" | "unsupported" }[] }>) => void;
   /** An action button on a message was clicked. `action` is the built-in name or custom id. `state` is present only for the toggleable feedback votes: `'on'` when a like/dislike is set, `'off'` when re-tapped to clear. */
   onKaiMessageAction?: (event: CustomEvent<{ messageId: string; action: string; state?: undefined | "on" | "off" }>) => void;
   /** The header model switcher changed. */

package/src/elements/menu.tsx

@@ -28,11 +28,28 @@ interface Props extends Record<string, unknown> {
    *  URL/data-URI, or text). Use this instead of slotting `slot="trigger"` for
    *  the common case; a slotted trigger overrides it. */
   triggerIcon?: string;
-  /** Built-in trigger: a text label (e.g. `"High"`). */
+  /** Built-in trigger: a text label (e.g. `"High"`). This is the trigger's
+   *  VISIBLE text, so it is also its accessible name, and `label` does not
+   *  override it: an accessible name that does not contain the visible text is
+   *  unreachable by speech input, which is what WCAG 2.5.3 (Label in Name)
+   *  exists for. A slotted `slot="trigger"` replaces this built-in trigger
+   *  entirely and is named differently; see `label`. */
   triggerLabel?: string;
   /** Built-in trigger: a trailing icon (e.g. `"chevron-down"` for a select look). */
   triggerIconTrailing?: string;
-  /** Accessible name for an icon-only trigger (no visible label). */
+  /** Accessible name for a trigger with no visible label. Ignored when
+   *  `triggerLabel` is set, which is already the visible name.
+   *
+   *  It DOES name a slotted `slot="trigger"`, and that is a difference in what
+   *  the two slots MEAN, not a limitation. `<kai-button>`'s slot IS the button's
+   *  label, so text slotted there is the name and `label` steps aside. This slot
+   *  is VISUAL content, a `+` or an `<svg>`, with the name supplied separately:
+   *  decoration beside a name, never a second name competing with one. So
+   *  `label` names the trigger here by design.
+   *
+   *  Slotting a real WORD rather than a glyph makes that word a visible label,
+   *  and an accessible name has to contain the visible text. Then either drop
+   *  `label` or make it contain the word you slotted. */
   label?: string;
   /** Drive/observe open state (Shoelace-style: settable + reflected to the `open`
    *  attribute, the menu still self-manages on click/keyboard). Set `el.open = true`,
@@ -182,7 +199,17 @@ defineWebComponent<Props, Events>('kai-menu', {
             ? 'gap-1.5 px-2 py-1.5 text-sm font-medium text-muted-foreground hover:bg-accent hover:text-foreground'
             : 'justify-center p-1.5 text-foreground hover:bg-muted',
         )}
-        aria-label={props.label ?? (props.triggerLabel ? undefined : 'Open menu')}
+        // A visible `triggerLabel` IS the name (name-from-contents reaches the
+        // slotted/shadow text), so `label` must not be layered over it: aria-label
+        // REPLACES the computed name, and a trigger reading "High" that answers to
+        // "Reasoning effort" locks speech-input users out (WCAG 2.5.3). Same rule
+        // kai-checkpoint and kai-button follow.
+        //
+        // A SLOTTED trigger keeps `label`, and that is the contract rather than a
+        // gap: kai-button's slot IS the label, so text there is the name; this
+        // slot is visual content with the name supplied separately. Two slots,
+        // two meanings, so the same rule should not apply to both. See `label`.
+        aria-label={props.triggerLabel ? undefined : (props.label ?? 'Open menu')}
       >
         {/* Slotted trigger wins; otherwise build one from the trigger* props;
             otherwise fall back to a "more" glyph. */}

package/src/elements/slot-text.ts

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

package/src/elements/slots.ts

@@ -400,6 +400,15 @@ export const PROGRESS_BAR_PARTS: PartDef[] = [
   { name: 'fill', doc: 'The filled portion; its width follows value/max. Recolor it from outside.', recipe: 'kai-progress-bar::part(fill) { background: var(--color-tool-green) }' },
 ];
 
+/** Styleable `::part`s of `<kai-context>`. The usage meter is the same shared
+ *  ProgressBar `<kai-progress-bar>` renders, mounted inside this element's own
+ *  shadow root, so `kai-context` exposes the same two names. Both sit inside the
+ *  hover-card breakdown and are in the DOM only while that card is open. */
+export const CONTEXT_PARTS: PartDef[] = [
+  { name: 'track', doc: 'The usage meter track inside the hover-card breakdown. Carries `role="progressbar"` and is in the DOM only while the card is open. Restyle its height, radius, or background from outside.', recipe: 'kai-context::part(track) { height: 0.5rem }' },
+  { name: 'fill', doc: 'The used-tokens portion of that meter. Its width follows `usedTokens / maxTokens`; its default color is the severity hue picked by `warnThreshold` / `dangerThreshold`, so recoloring it from outside replaces that signal.', recipe: 'kai-context::part(fill) { background: var(--color-tool-blue) }' },
+];
+
 /** Styleable `::part`s of `<kai-file-tree>` — the changed-files / diff bits, shown
  *  only when a file carries diff metadata (or the `summary` attribute is set). */
 export const FILE_TREE_PARTS: PartDef[] = [
@@ -645,6 +654,7 @@ export const ELEMENT_COMPOSITION: Record<string, ElementComposition> = {
   'kai-nav': { parts: NAV_PARTS },
   'kai-coachmark': { slots: COACHMARK_SLOTS, parts: COACHMARK_PARTS, children: 'The ANCHOR the coachmark points at: the element it attaches to and positions against. The bubble body is the `content` slot.' },
   'kai-progress-bar': { parts: PROGRESS_BAR_PARTS },
+  'kai-context': { parts: CONTEXT_PARTS },
   'kai-file-tree': { parts: FILE_TREE_PARTS },
   'kai-prompt-dock': { slots: PROMPT_DOCK_SLOTS, parts: PROMPT_DOCK_PARTS, children: 'The input the dock wraps, typically a `<kai-prompt-input>`. The `top`/`bottom` slots are the lips around it.' },
   'kai-segmented': { parts: SEGMENTED_PARTS },

package/src/index.ts

@@ -5,12 +5,16 @@
 // Every consumer of `@kitn.ai/ui` pays for this barrel, INCLUDING React/Vue/
 // Svelte consumers who never render a Solid component. It is therefore frozen at
 // the surface that shipped: adding a Solid component here taxes four frameworks
-// to serve one. Closing the 79/79 element coverage gaps on this file grew it
-// 591,359 -> 705,031 bytes (+19.2%), which is what motivated the split.
+// to serve one. Closing the element coverage gaps on this file grew it
+// 591,359 -> 705,031 bytes (+19.2%), which is what motivated the split. (That
+// measurement was taken at the then-79 elements; the catalog grows, the bytes
+// quoted do not — they are a record of the split, not a current reading.)
 //
-// The COMPLETE SolidJS surface — all 79 elements' components plus a `<Name>Props`
-// type for every public component — lives on `@kitn.ai/ui/solid` (src/solid.ts),
-// which is its own build target so only Solid consumers pay for it. `./solid`
+// The COMPLETE SolidJS surface — a component for EVERY registered element plus a
+// `<Name>Props` type for every public component — lives on `@kitn.ai/ui/solid`
+// (src/solid.ts), which is its own build target so only Solid consumers pay for
+// it. `npm run verify:solid-coverage` prints the element count and proves that
+// surface n/n on every run, which is why no count is restated here. `./solid`
 // re-exports this file, so it is a strict superset: anything here is reachable
 // there too, and a Solid consumer only ever needs the one import.
 //