@kitn.ai/ui 0.25.2 → 0.27.0

package/src/elements/slots.ts

@@ -2,7 +2,7 @@
  * Composition slots for `kai-*` elements. A slot is a named region a consumer
  * fills with their own markup. This registry is the SINGLE SOURCE OF TRUTH:
  * the facade derives its detection from it (and, later, docs are generated
- * from it). See docs/superpowers/specs/2026-06-23-kai-chat-composition-seams-design.md.
+ * from it).
  */
 
 /** `inject` = additive (the built-in region still renders, your markup is added
@@ -62,6 +62,39 @@ export const CONVERSATIONS_PARTS: PartDef[] = [
     doc: 'The right-aligned trailing text on each conversation row (a count, status, or relative time). Set it per item via the `trailing` field; otherwise a short auto relative time is derived from `updatedAt`. Recolor or resize it from outside.',
     recipe: 'kai-conversations::part(trailing) { color: var(--color-primary); font-variant-numeric: tabular-nums }',
   },
+  {
+    name: 'items',
+    doc: 'The item-mode listbox region wrapping your slotted `<kai-conversation-item>` children.',
+    recipe: 'kai-conversations::part(items) { gap: 2px }',
+  },
+];
+
+/** Slots of `<kai-conversation-item>` — one composed row of a consumer-owned
+ *  conversation loop (the default slot is the title). */
+export const CONVERSATION_ITEM_SLOTS: SlotDef[] = [
+  { name: 'leading', mode: 'inject', part: true, doc: 'Leading region before the title (an icon or avatar).' },
+  { name: 'meta', mode: 'inject', part: true, doc: 'Meta region under the title (a timestamp or status line).' },
+  { name: 'menu', mode: 'inject', part: true, doc: 'Your own row menu (a popover trigger). Never selects the row.' },
+];
+
+/** Styleable `::part`s of `<kai-conversation-item>`. (`leading`/`meta`/`menu`
+ *  are covered by their slot defs' `part: true` flags.) */
+export const CONVERSATION_ITEM_PARTS: PartDef[] = [
+  {
+    name: 'body',
+    doc: 'The activation surface inside the row (button role; carries aria-current and the roving tabindex). The focus ring paints here.',
+    recipe: 'kai-conversation-item::part(body) { outline-offset: 2px }',
+  },
+  {
+    name: 'row',
+    doc: 'The whole row surface. Carries `data-active` while selected.',
+    recipe: 'kai-conversation-item::part(row) { border-radius: 0.5rem }',
+  },
+  {
+    name: 'title',
+    doc: 'The title line (the default slot renders inside it).',
+    recipe: 'kai-conversation-item::part(title) { font-weight: 600 }',
+  },
 ];
 
 /** Slots of `<kai-message>` — per-message composition seams. `before-body` and
@@ -183,6 +216,33 @@ export const SKELETON_PARTS: PartDef[] = [
   },
 ];
 
+/**
+ * The parts of ONE attachment item, declared by `components/attachments.tsx`
+ * and therefore surfaced by every element that renders an attachment — the
+ * standalone `<kai-attachments>` AND the thread inside `<kai-message>` /
+ * `<kai-chat>`. Shared rather than duplicated so the two can never document
+ * different names for the same node.
+ *
+ * These are a styling seam and a TESTING seam, and the second is why they exist
+ * at all. `examples/internal/openrouter-spike` proves "a user can see which file
+ * was attached" by locating these; before they existed it pinned the chip by
+ * `span.truncate` and broke the day the thread moved to the grid tile, while the
+ * filename was still plainly on screen. A published part is what lets an
+ * assertion name the thing rather than its current markup.
+ */
+export const ATTACHMENT_ITEM_PARTS: PartDef[] = [
+  {
+    name: 'attachment',
+    doc: 'One attachment item: the chip, row or tile, whichever variant is rendering. Restyle its background, radius or border from outside without caring which layout it is.',
+    recipe: 'kai-chat::part(attachment) { border-radius: 0.25rem }',
+  },
+  {
+    name: 'attachment-name',
+    doc: 'The attachment’s filename label. Present in every variant that shows one (a grid tile omits it for an image, which is its own label). Retune its type or hide it entirely.',
+    recipe: 'kai-chat::part(attachment-name) { font-size: 0.75rem }',
+  },
+];
+
 /** Styleable `::part`s of `<kai-message>`. (The `avatar` part is contributed by
  *  the `avatar` slot's `part: true` flag, so it is not repeated here.) */
 export const MESSAGE_PARTS: PartDef[] = [
@@ -211,6 +271,10 @@ export const MESSAGE_PARTS: PartDef[] = [
     doc: 'The citation row rendered from the message’s `source` parts: a wrapped row of chips below the bubble, never inside it. Restyle its spacing or hide it entirely from outside.',
     recipe: 'kai-message::part(citations) { gap: 0.5rem }',
   },
+  // A message renders its `file` parts through the same Attachment chrome
+  // `<kai-attachments>` uses, so it exposes the same handles. Shared, not
+  // restated — see ATTACHMENT_ITEM_PARTS.
+  ...ATTACHMENT_ITEM_PARTS,
 ];
 
 /** Styleable `::part`s of `<kai-attachments>`. */
@@ -220,6 +284,7 @@ export const ATTACHMENTS_PARTS: PartDef[] = [
     doc: 'The image shown in an attachment’s hover-card preview. Bounded by default (max ~320×256, aspect preserved) so a large image never blows up the card. Raise or lower the cap from outside.',
     recipe: 'kai-attachments::part(preview) { max-width: 32rem; max-height: 24rem }',
   },
+  ...ATTACHMENT_ITEM_PARTS,
 ];
 
 /** Styleable `::part`s of `<kai-status>`. */
@@ -323,21 +388,21 @@ export const CARD_PARTS: PartDef[] = [
   },
 ];
 
-/** Injection slots of `<kai-workspace>` (the carrier regions the consumer drops
- *  content into: brand/tabs, the upgrade/Design/user-menu cluster, a top banner). */
+/** Slots of `<kai-workspace>` (the five shell regions; main also takes the default slot). */
 export const WORKSPACE_SLOTS: SlotDef[] = [
-  { name: 'sidebar-header', mode: 'inject', doc: 'Top of the conversation rail (brand, a kai-tabs strip).' },
-  { name: 'sidebar-footer', mode: 'inject', doc: 'Bottom of the rail: an upgrade card, a Design trigger, a user-menu cluster.' },
-  { name: 'main-header', mode: 'inject', doc: 'Top of the main region (a top-placed banner or a corner action).' },
-  { name: 'main', mode: 'replace', doc: 'Replace the built-in chat thread with your own main view (a home or dashboard screen). Omit to keep the thread.' },
+  { name: 'header', mode: 'inject', part: true, doc: 'The top band across the full shell width (app bar, tabs, breadcrumbs).' },
+  { name: 'start', mode: 'inject', part: true, doc: 'The inline-start aside column (a conversation rail, a nav, a file tree). Resizable and collapsible.' },
+  { name: 'main', mode: 'inject', part: true, doc: 'The main region. Unnamed children project here too, via the default slot.' },
+  { name: 'end', mode: 'inject', part: true, doc: 'The inline-end aside column (inspector, notes, preview). Resizable and collapsible.' },
+  { name: 'footer', mode: 'inject', part: true, doc: 'The bottom band across the full shell width (status bar, disclaimers).' },
 ];
 
-/** Styleable `::part`s of `<kai-workspace>`. */
+/** Styleable `::part`s of `<kai-workspace>` (beyond the slot-backed header/start/main/end/footer parts). */
 export const WORKSPACE_PARTS: PartDef[] = [
   {
-    name: 'sidebar',
-    doc: 'The conversation rail. Carries a subtle, theme-aware default background (bg-surface); override its background, border, or width from outside. `sidebar-min-width` sets its min px width and `collapse-below` auto-collapses it under a width.',
-    recipe: 'kai-workspace::part(sidebar) { background: var(--color-card); border-right: 1px solid var(--color-border) }',
+    name: 'aside',
+    doc: 'Both aside columns match this part (each also matches its own start/end part). Restyle the shared aside surface or border from outside; the --kai-workspace-start-* and --kai-workspace-end-* custom properties set the widths.',
+    recipe: 'kai-workspace::part(aside) { background: var(--color-card) }',
   },
 ];
 
@@ -474,6 +539,18 @@ export const PROMPT_DOCK_PARTS: PartDef[] = [
   },
 ];
 
+/** Slots + styleable `::part`s of `<kai-dock>` (the floating corner launcher — not
+ *  `<kai-prompt-dock>`, which is an in-flow tray around a prompt input). */
+export const DOCK_SLOTS: SlotDef[] = [
+  { name: 'panel',         mode: 'replace', part: true, doc: 'The panel body. ANY element: a `<kai-chat>`, a form, your own component. The dock never reads or types it, and the default slot is the same region.' },
+  { name: 'launcher',      mode: 'inject',  doc: 'Content inside the built-in button while CLOSED; defaults to a chat glyph. Text works as well as an icon: the button keeps its height and grows sideways into a pill, so a label like "Support" is not clipped. The BUTTON is never slotted away, because it owns aria-expanded, aria-controls, the toggle wiring and the focus return.' },
+  { name: 'launcher-open', mode: 'inject',  doc: 'Content inside the button while OPEN; defaults to a ✕. Fill only `launcher` and that glyph stays while open rather than morphing into a built-in that clashes with it.' },
+];
+export const DOCK_PARTS: PartDef[] = [
+  { name: 'launcher', doc: 'The launcher button pinned to the corner: a disc by default, a pill once you slot a text label. Restyle its surface or shadow; --kai-dock-launcher-size sets its height and its minimum width.', recipe: 'kai-dock::part(launcher) { background: var(--color-info) }' },
+  { name: 'badge', doc: 'The unread dot on the launcher, rendered only while closed and only when `unread` is set. Restyle its color or size.', recipe: 'kai-dock::part(badge) { background: var(--color-success) }' },
+];
+
 /** Styleable `::part`s of `<kai-segmented>`. */
 export const SEGMENTED_PARTS: PartDef[] = [
   { name: 'track', doc: 'The segmented track (the pill container holding the segments). Restyle its background, radius, or padding.', recipe: 'kai-segmented::part(track) { border-radius: 9999px }' },
@@ -512,6 +589,13 @@ export const AGENT_CARD_PARTS: PartDef[] = [
   { name: 'menu', doc: 'The trailing overflow ("...") menu button.', recipe: 'kai-agent-card::part(menu) { opacity: 1 }' },
 ];
 
+/** Styleable `::part`s of `<kai-code-block>` (one syntax-highlighted code block).
+ *  The code region itself is not a part — it is rebuilt when the highlight lands,
+ *  and its look is owned by the Shiki theme (`code-theme`). */
+export const CODE_BLOCK_PARTS: PartDef[] = [
+  { name: 'copy', doc: 'The copy-to-clipboard button in the header row. Hide it with `copy="false"` rather than CSS.', recipe: 'kai-code-block::part(copy) { color: var(--color-primary) }' },
+];
+
 /** Slots + styleable `::part`s of `<kai-dialog>` (the centered modal). */
 export const DIALOG_SLOTS: SlotDef[] = [
   { name: 'header', mode: 'inject', part: true, doc: 'Optional title region at the top of the panel.' },
@@ -594,6 +678,13 @@ export const POPOVER_SLOTS: SlotDef[] = [
   { name: 'trigger', mode: 'replace', doc: 'The control that opens the popover (a button, an avatar, …). The panel anchors to it.' },
 ];
 
+/** Slots of `<kai-dropdown>`. The menu body is the default slot; `trigger` is the
+ *  VISUAL content of the built-in trigger button (never your own `<button>`/`<a>`,
+ *  which would nest interactive elements — the `kai-menu` rule). */
+export const DROPDOWN_SLOTS: SlotDef[] = [
+  { name: 'trigger', mode: 'replace', doc: 'Visual content of the trigger button (an icon, text, an `<svg>`). Replaces the built-in trigger* content; name it with `label`.' },
+];
+
 /** Styleable `::part`s of `<kai-audio-visualizer>`. Every DOM variant (`bar`,
  *  `grid`, `radial`) shares the `bar`/`cell` markup pattern; the shader variants
  *  (`wave`, `aurora`) share the `canvas` part. Lit items ALSO carry the
@@ -631,7 +722,8 @@ export const AUDIO_VISUALIZER_PARTS: PartDef[] = [
 export const ELEMENT_COMPOSITION: Record<string, ElementComposition> = {
   'kai-chat': { slots: CHAT_SLOTS, parts: CHAT_PARTS },
   'kai-command': { parts: COMMAND_PARTS },
-  'kai-conversations': { slots: CONVERSATIONS_SLOTS, parts: CONVERSATIONS_PARTS },
+  'kai-conversations': { slots: CONVERSATIONS_SLOTS, parts: CONVERSATIONS_PARTS, children: 'Your own `<kai-conversation-item>` rows (item mode: the consumer-owned loop). Data rows do not render while any are present.' },
+  'kai-conversation-item': { slots: CONVERSATION_ITEM_SLOTS, parts: CONVERSATION_ITEM_PARTS, children: 'The row title. `leading`, `meta` and `menu` are the named regions around it.' },
   'kai-message': { slots: MESSAGE_SLOTS, parts: MESSAGE_PARTS },
   'kai-thread': { slots: THREAD_SLOTS },
   'kai-prompt-input': { slots: PROMPT_INPUT_SLOTS, parts: PROMPT_INPUT_PARTS },
@@ -650,7 +742,7 @@ export const ELEMENT_COMPOSITION: Record<string, ElementComposition> = {
   'kai-voice-output': { parts: VOICE_OUTPUT_PARTS },
   'kai-screen': { slots: SCREEN_SLOTS, parts: SCREEN_PARTS, children: 'The screen body, below the title bar.' },
   'kai-card': { slots: CARD_SLOTS, parts: CARD_PARTS, children: 'The card body, below the header/media regions.' },
-  'kai-workspace': { slots: WORKSPACE_SLOTS, parts: WORKSPACE_PARTS },
+  'kai-workspace': { slots: WORKSPACE_SLOTS, parts: WORKSPACE_PARTS, children: 'The main region content (same region as the `main` slot): your `<kai-chat>`, or any app view.' },
   '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 },
@@ -664,6 +756,7 @@ export const ELEMENT_COMPOSITION: Record<string, ElementComposition> = {
   'kai-pane-group': { parts: PANE_GROUP_PARTS, children: 'Content shown for every tab. Use it INSTEAD of the per-tab `slot="<tab id>"` seams when you swap the content yourself.' },
   'kai-agent-card': { parts: AGENT_CARD_PARTS },
   'kai-dialog': { slots: DIALOG_SLOTS, parts: DIALOG_PARTS, children: 'The dialog body, between the `header` and `footer` slots.' },
+  'kai-dock': { slots: DOCK_SLOTS, parts: DOCK_PARTS, children: 'The panel body, the same region as `slot="panel"`.' },
   'kai-input': { slots: INPUT_SLOTS, parts: INPUT_PARTS },
   'kai-search': { parts: SEARCH_PARTS },
   'kai-kbd': { parts: KBD_PARTS, children: 'Literal key text, when you are not using the `keys` prop to render key caps.' },
@@ -671,9 +764,11 @@ export const ELEMENT_COMPOSITION: Record<string, ElementComposition> = {
   'kai-empty': { slots: EMPTY_SLOTS, children: 'The empty-state body below the title/description, usually the call to action.' },
   'kai-file-upload': { children: 'Custom dropzone content, replacing the default label (the `label` prop is the fallback).' },
   'kai-popover': { slots: POPOVER_SLOTS, children: 'The popover panel body. The control that opens it is the `trigger` slot.' },
+  'kai-dropdown': { slots: DROPDOWN_SLOTS, children: 'The menu body: your own rows. Give each `role="menuitem"`. The control that opens it is the `trigger` slot.' },
   'kai-resizable': { children: 'The `<kai-resizable-item>` panels, in order. Dividers are inserted between them.' },
   'kai-resizable-item': { children: 'This panel\'s content.' },
   'kai-tooltip': { children: 'The TRIGGER the tooltip describes. The tip text is the `text` prop.' },
+  'kai-code-block': { parts: CODE_BLOCK_PARTS },
   'kai-audio-visualizer': { parts: AUDIO_VISUALIZER_PARTS },
 };
 

package/src/elements/styles.css

@@ -1,5 +1,18 @@
-/* Element-bundle stylesheet. Compiled to compiled.css and injected into each
-   custom element's shadow root. Mirrors .storybook/styles.css but scans src/. */
+/* Element-bundle stylesheet, and the SOURCE OF TRUTH for element CSS. Compiled to
+   compiled.css and injected into each custom element's shadow root;
+   .storybook/styles.css @imports this file rather than restating it, so a rule
+   added here reaches the shadow roots AND the light-DOM Solid stories at once.
+
+   It used to be the other way round — Storybook hand-copied a few of these rules
+   under "Mirror the shipped ..." comments. Nothing enforced the copy, so
+   .kai-radio, .kai-checkbox, .kai-range and .kai-focus-inset were simply missing
+   there: three form controls rendered as raw OS chrome in every story while the
+   shipped element rendered them fully designed, and an agent and the owner each
+   concluded the kit had unstyled controls. Never copy a rule from here into the
+   Storybook sheet; add it here.
+
+   The one thing that cannot cross is :host, which selects nothing in the light
+   DOM. Its defaults are re-stated on `body` in the Storybook sheet's shim. */
 @import "tailwindcss";
 /* tw-animate-css supplies the animate-in/animate-out + slide/fade/zoom utilities
    the kit uses for every overlay enter/exit (toast, popover, tooltip, dropdown,
@@ -16,10 +29,19 @@
   /* Base typography is token-driven so a theme can restyle it. --kai-font-base is
      the family for ALL text/UI (named "base", not "sans", so a serif body works);
      --kai-tracking is global letter-spacing. Both pierce the Shadow DOM via the
-     var() fallback, exactly like the --kai-color-* tokens. */
+     var() fallback, exactly like the --kai-color-* tokens.
+
+     font-size is the third: without it every shadow root inherited the DOCUMENT's
+     size (16px in a stock page), so any surface that never set an explicit text-*
+     class rendered a step larger than the rest of the kit and looked like a bug in
+     that one component. --text-body is the scale's primary reading size and itself
+     resolves through --kai-text-body, so overriding that one token still moves the
+     default. The literal fallback matches theme.css's --text-body so the rule is
+     still correct if this sheet is ever used without the @theme block. */
   :host {
     display: block;
     font-family: var(--kai-font-base, ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);
+    font-size: var(--text-body, var(--kai-text-body, 0.875rem));
     letter-spacing: var(--kai-tracking, normal);
   }
   /* Code/monospace surfaces use --kai-font-code (named for its ROLE — code — not
@@ -40,12 +62,23 @@
   /* One token-driven focus ring for EVERY focusable element in the shadow root.
      Blue by default (via --color-ring), consistent in light + dark, and
      overridable through --kai-color-ring. Uses `outline` (not a box-shadow
-     ring) so it never clips on overflow and follows the element's radius;
-     `:focus-visible` so it only appears for keyboard navigation, never on a
-     mouse click. Components that render their own ring set
-     `focus-visible:outline-none` (a utility in a later cascade layer) and win
-     over this — so there's no double ring, just a guaranteed blue fallback for
-     the many controls that have no explicit focus style. */
+     ring) because it follows the element's radius and — unlike a `ring-*`
+     utility — is written in literal values, so it does not depend on any
+     `--tw-*` custom property. That matters more than it looks: `@property`
+     registration is document-global and is ignored inside a shadow root, so
+     every `--tw-*` here is unset and every `ring-*` utility computes to
+     nothing. This literal rule is the only reason most of the kit had a focus
+     indicator at all. `:focus-visible` so it only appears for keyboard
+     navigation, never on a mouse click. Components that render their own ring
+     set `focus-visible:outline-none` (a utility in a later cascade layer) and
+     win over this — so there's no double ring, just a guaranteed blue fallback
+     for the many controls that have no explicit focus style.
+
+     CAVEAT, learned the hard way: an outline is NOT immune to clipping. It is
+     unaffected by the element's OWN overflow, but `outline-offset: 2px` draws
+     it entirely outside the border box, where an ANCESTOR with
+     `overflow: clip`/`hidden` erases it completely. Controls that sit flush
+     inside such a container need `.kai-focus-inset` below. */
   :focus-visible {
     outline: 2px solid var(--color-ring);
     outline-offset: 2px;
@@ -72,6 +105,40 @@
   *::-webkit-scrollbar-thumb:hover { background-color: var(--color-scrollbar-thumb-hover); }
   *::-webkit-scrollbar-corner { background: transparent; }
 
+  /* SELECTED text, kit-owned. Scoped to the shadow root — deliberately, and this
+     is the whole design decision, so read it before "simplifying" it into
+     theme.css.
+
+     WHY THE KIT OWNS IT AT ALL: left to the UA, the browser's blue selection was
+     visually stronger than the kit's OWN deliberate emphasis (the composer's
+     --color-highlight mark), so an incidental drag-select outranked a keyword the
+     app had flagged on purpose. How selected text reads is a fact about the
+     medium, which is the kit's call.
+
+     WHY ONLY HERE, AND NOT IN theme.css: theme.css is imported into a CONSUMER's
+     Tailwind build, so a bare ::selection there would restyle every paragraph on
+     their page — the kit deciding for the app's own content, which is not ours to
+     decide. The shadow root IS the kit's DOM, so the same rule is unambiguous
+     here. Identical reasoning to the scrollbar and :focus-visible rules above,
+     which are scoped the same way and for the same reason. theme.css therefore
+     carries the TOKENS only, and a Solid-layer consumer rendering our components
+     into their own light DOM opts in with one rule of their own:
+     `.my-chat ::selection { background-color: var(--color-selection); … }`.
+
+     WHY THE RULE MUST BE IN THIS SHEET AND NOT INHERITED: ::selection does NOT
+     cross the shadow boundary the way ordinary inherited properties do — a
+     document-level ::selection leaves shadow content on the UA default. The
+     --kai-color-selection TOKEN does pierce (custom properties inherit normally),
+     which is what keeps a consumer override working.
+
+     Both background AND color are set; see the theme.css note for why the
+     foreground is load-bearing rather than cosmetic (coloured text falls under
+     WCAG AA on this fill if it keeps its own colour). */
+  ::selection {
+    background-color: var(--color-selection);
+    color: var(--color-selection-foreground);
+  }
+
   /* Respect a user's reduced-motion preference: disable the tw-animate-css
      enter/exit keyframe animations (toasts, overlays, cards) so they appear and
      disappear instantly instead of sliding/fading. Targets the utility classes
@@ -87,6 +154,19 @@
 }
 
 @layer components {
+  /* Focus ring drawn INSIDE the element's border box, for focusable regions
+     that sit flush against a clipping ancestor. The scrollable code-block body
+     and the message log are both `overflow-*` regions filling a rounded
+     `overflow: clip` container, so the default `outline-offset: 2px` put the
+     whole ring outside the clip and it never painted — the outline computed
+     correctly, matched `:focus-visible`, and was erased before it reached the
+     screen. A negative offset keeps it clear of the boundary. Same token and
+     width as the base ring, so it reads identically. */
+  .kai-focus-inset:focus-visible {
+    outline: 2px solid var(--color-ring);
+    outline-offset: -2px;
+  }
+
   /* Designed radio + checkbox (appearance-none) so the form controls read as
      intentional, theme correctly in light/dark, and have comfortable targets —
      replacing the weak native defaults. Used via `.kai-radio` / `.kai-checkbox`. */
@@ -145,6 +225,36 @@
   .kai-checkbox:checked {
     box-shadow: 0 1px 4px color-mix(in srgb, var(--color-primary) 26%, transparent);
   }
+  /* The mixed state ("some of the children below are ticked"). `indeterminate` is a
+     DOM property with no HTML attribute, so a rule is the ONLY way it can be seen —
+     without one a mixed box paints pixel-identically to an unchecked one and lies
+     about its state. That was live: `<kai-tasks>` in `select` mode puts an
+     indeterminate select-all above a partial selection, and it read as "none
+     selected".
+
+     Same fill and the same masked `::after` as `:checked`, with the tick mask
+     swapped for a bar, so the two states are siblings of one technique rather than
+     two: the bar is `--color-primary-foreground` on `--color-primary`, exactly the
+     pair the tick already uses, so it themes and contrasts identically in both
+     themes and stays consumer-themable through the same tokens.
+
+     Ordered AFTER the `:checked` rules on purpose. `indeterminate` is independent of
+     `checked`, so a box can be both; specificity is equal, so source order decides,
+     and mixed-wins is what the browser's own native rendering does.
+
+     Scoped to `.kai-checkbox` on purpose: `:indeterminate` also matches every radio
+     in a group with nothing selected, and an empty radio group must go on reading as
+     empty rather than sprouting a third state. */
+  .kai-checkbox:indeterminate {
+    background-color: var(--color-primary);
+    border-color: var(--color-primary);
+    box-shadow: 0 1px 4px color-mix(in srgb, var(--color-primary) 26%, transparent);
+  }
+  .kai-checkbox:indeterminate::after {
+    transform: scale(1);
+    -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='3.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M5 12h14'/%3E%3C/svg%3E") center / contain no-repeat;
+    mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='3.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M5 12h14'/%3E%3C/svg%3E") center / contain no-repeat;
+  }
   .kai-radio:disabled,
   .kai-checkbox:disabled { opacity: 0.5; cursor: not-allowed; }
 

package/src/elements/thinking-bar.tsx

@@ -25,10 +25,19 @@ defineWebComponent<Props, Events>('kai-thinking-bar', {
   text: 'Thinking',
   stoppable: false,
   stopLabel: 'Answer now',
-}, (props, { dispatch, flag }) => (
-  <ThinkingBar
-    text={props.text}
-    stopLabel={props.stopLabel}
-    onStop={flag('stoppable') ? () => dispatch('kai-stop') : undefined}
-  />
-));
+}, (props, { dispatch, flag, reflectFlag }) => {
+  // `stoppable` reflects, following kai-tool's `disabled` (its FIX1). Without it the
+  // remove direction is dead: `el.removeAttribute('stoppable')` parses to `undefined`,
+  // the prop was already `undefined` after a bare-attribute add, so no prop change
+  // fires and `flag()`'s non-reactive hasAttribute fallback is never re-read — the
+  // stop affordance stays rendered forever. reflectFlag's coercing read-back resolves
+  // every write through the same `flag()` policy, making both directions reactive.
+  reflectFlag('stoppable');
+  return (
+    <ThinkingBar
+      text={props.text}
+      stopLabel={props.stopLabel}
+      onStop={flag('stoppable') ? () => dispatch('kai-stop') : undefined}
+    />
+  );
+});

package/src/elements/thread.tsx

@@ -128,6 +128,8 @@ defineWebComponent<Props, Events>('kai-thread', {
         scrollButton={props.scrollButton !== false}
         cardTypes={cardComponentsFromTags(props.cardTypes as Record<string, string> | undefined, (props as { theme?: string }).theme)}
         cardSchemas={props.cardSchemas as Record<string, object> | undefined}
+        /* F-26: card parts emit off THIS element as the bubbling `kai-card` event. */
+        cardHostElement={element}
         empty={slots()['empty'] ? <slot name="empty" /> : undefined}
         onMessageAction={(detail) => dispatch('kai-message-action', detail)}
         controllerRef={(c) => (controller = c)}

package/src/elements/toast.tsx

@@ -5,7 +5,11 @@ import { toast as toastStore, type ToastItem } from '../primitives/toast-store';
 interface Props extends Record<string, unknown> {
   /** The toasts to render. Newest is shown on top. Set as a JS property (array);
    *  pass a new array reference to update. Omit for an empty region, which is
-   *  the normal resting state and how the imperative `toast()` API starts. */
+   *  the normal resting state and how the imperative `toast()` API starts.
+   *  Note the handover: the first `toast()` call ADOPTS a region you placed in
+   *  markup (no second region mounts) and binds the imperative store to this
+   *  property, replacing any array you set. Drive a region as data OR via
+   *  `toast()`, not both at once. */
   toasts?: ToastItem[];
   /** Stack anchor: `'top-center'` (default), `'top-right'`, `'bottom-center'`, … */
   position?: ToastPosition;
@@ -41,12 +45,24 @@ interface Events {
  * also usable declaratively — set `el.toasts = [...]` (a JS property, never an
  * attribute) and listen for `kai-dismiss` / `kai-action`.
  *
+ * The two modes meet gracefully: `toast()` ADOPTS the first connected
+ * `<kai-toast-region>` already in the document instead of mounting a second
+ * one, and creates its own on `document.body` only when none exists. Adoption
+ * keeps your authored attributes (position/stack/appearance) but binds the
+ * imperative store to `toasts`, replacing an array you were driving as data —
+ * so within one app, either own the array or call `toast()`, not both. With
+ * two or more regions placed, the first in document order is adopted and a
+ * one-time console.warn flags the ambiguity.
+ *
  * Because it is a real `kai-*` element it carries its own shadow root + the
  * shared kit stylesheet, so it is viewport-positioned AND kit-styled.
  *
  * Stack-level defaults are also declarative: `<kai-toast-region appearance="card"
  * inverse>` makes every toast that doesn't set its own `appearance`/`inverse`
  * render as an inverted card. A per-toast value always wins.
+ *
+ * Your app chrome must stay below the toast layer; set `--kai-toast-z`
+ * (default 100) on the host to move the layer.
  */
 defineWebComponent<Props, Events>('kai-toast-region', {
   toasts: [],

package/src/elements/tool.tsx

@@ -1,4 +1,4 @@
-import { Show } from 'solid-js';
+import { createSignal, Show } from 'solid-js';
 import { defineWebComponent } from './define';
 import { Tool, type ToolPart } from '../components/tool';
 import { wireDisclosure } from './disclosure';
@@ -36,13 +36,34 @@ defineWebComponent<Props, Events>('kai-tool', {
   defaultOpen: undefined,
   disabled: undefined,
 }, (props, ctx) => {
-  const { flag } = ctx;
-  let api: CollapsibleController | undefined;
+  const { flag, reflectFlag } = ctx;
+
+  // A SIGNAL, not a `let`. This facade gates its whole subtree on `<Show when={props.tool}>`,
+  // and `tool` is an object prop, so the only sequence a consumer of the HTML spelling
+  // has is markup-then-assign: the element connects with no tool, renders nothing, and
+  // the Collapsible — and therefore the controller — arrives a tick later.
+  //
+  // With a plain `let`, wireDisclosure's effects ran once against `undefined` and never
+  // again, because the getter they were handed was not reactive and a bare `open`
+  // attribute never changes `props.open` to re-trigger them. Net result: `<kai-tool open>`
+  // silently stayed shut while `el.open` read back `true` — the property and the
+  // rendering disagreed. Making the controller reactive is the whole fix: the effects
+  // re-run the moment it lands. `Tool` already tracks its own copy this way internally.
+  // Pinned by the ordering rows in tests/elements/tool.test.tsx.
+  const [api, setApi] = createSignal<CollapsibleController>();
 
   // The standard disclosure surface: settable+reflecting `open`, kai-open-change,
   // show/hide/toggle, disabled-gating. See ./disclosure. This is the SOLE emitter
   // of kai-open-change — the Tool/Collapsible no longer wires its own.
-  wireDisclosure(ctx, () => api, () => props.open);
+  wireDisclosure(ctx, api, () => props.open);
+
+  // `disabled` reflects too, following kai-dock. Without it the prop is write-only in
+  // the read direction AND deaf in the write one: `el.setAttribute('disabled', '')`
+  // after mount is parsed by component-register to `undefined`, so the prop never
+  // changes and nothing re-renders. reflectFlag's coercing setter resolves that
+  // `undefined` back through the same `flag()` policy, which is what makes the plain
+  // HTML gesture work at runtime and not only at parse time (findings G-05).
+  reflectFlag('disabled');
 
   return (
     <Show when={props.tool}>
@@ -50,7 +71,7 @@ defineWebComponent<Props, Events>('kai-tool', {
         toolPart={props.tool!}
         defaultOpen={flag('defaultOpen')}
         disabled={flag('disabled')}
-        controllerRef={(a) => (api = a)}
+        controllerRef={(a) => setApi(a)}
       />
     </Show>
   );

package/src/elements/voice-input.tsx

@@ -39,6 +39,13 @@ interface Events {
    *  push-to-talk indicator) in sync with the mic. Fires on real transitions
    *  only (manual click and programmatic start()/stop()), never on mount. */
   'kai-recording-change': { recording: boolean };
+  /** A voice session failed, so no failure is ever silent. `detail.source` names
+   *  the failing side (`recognition` on `<kai-voice-input>`, `synthesis` on
+   *  `<kai-voice-output>`), `detail.error` carries the platform error code, the
+   *  thrown exception's name, or `no-result` when recognition ended with no error
+   *  and no text (the user said nothing), and `detail.message` is human-readable.
+   *  Deliberate cancellation does not fire. */
+  'kai-voice-error': { source: 'recognition'; error: string; message: string };
 }
 
 /**
@@ -47,8 +54,9 @@ interface Events {
  * `SpeechRecognition` (Chrome/Safari; no Firefox — and cloud-based in Chrome).
  * Set `el.transcribe` to route audio through your own async transcriber instead.
  * Where neither is available it records the blob and emits `kai-audio-captured`
- * with no text. Also emits `kai-transcription` (final text) and, with `interim`,
- * `kai-transcript-interim` (live partials).
+ * with no text. Also emits `kai-transcription` (final text), `kai-voice-error`
+ * (a failed or empty session) and, with `interim`, `kai-transcript-interim`
+ * (live partials).
  */
 defineWebComponent<Props, Events>('kai-voice-input', {
   transcribe: undefined,
@@ -85,6 +93,7 @@ defineWebComponent<Props, Events>('kai-voice-input', {
       onTranscription={(text) => dispatch('kai-transcription', { text })}
       onInterim={(text) => dispatch('kai-transcript-interim', { text })}
       onRecordingChange={(recording) => dispatch('kai-recording-change', { recording })}
+      onError={(detail) => dispatch('kai-voice-error', detail)}
       controllerRef={(c) => (controller = c)}
     />
   );

package/src/elements/voice-output.tsx

@@ -20,18 +20,30 @@ interface Props extends Record<string, unknown> {
 
 /** Events fired by `<kai-voice-output>`. */
 interface Events {
-  /** Playback started or stopped. Drive your own UI in sync. Fires on real transitions
-   *  only (manual click and programmatic speak()/stop()), never on mount. */
+  /** Playback started or stopped. Drive your own UI in sync. `speaking: true`
+   *  fires when audio actually starts (utterance.onstart natively; audio playback
+   *  beginning on the `synthesize` path), not when speak() is called; earlier
+   *  releases fired it optimistically inside speak() itself. Fires on real
+   *  transitions only (manual click and programmatic speak()/stop()), never on
+   *  mount. */
   'kai-speaking-change': { speaking: boolean };
   /** The model path (`synthesize`) resolved audio: the raw `Blob` before playback. */
   'kai-synthesized': { blob: Blob };
+  /** A voice session failed, so no failure is ever silent. `detail.source` names
+   *  the failing side (`recognition` on `<kai-voice-input>`, `synthesis` on
+   *  `<kai-voice-output>`), `detail.error` carries the platform error code, the
+   *  thrown exception's name, or `no-result` when recognition ended with no error
+   *  and no text (the user said nothing), and `detail.message` is human-readable.
+   *  Deliberate cancellation does not fire. */
+  'kai-voice-error': { source: 'synthesis'; error: string; message: string };
 }
 
 /**
  * `<kai-voice-output>` — a speaker button that reads `text` aloud. Native by
  * default (`speechSynthesis`); set `el.synthesize` to route through your TTS
  * model instead. The output sibling of `<kai-voice-input>`. Emits
- * `kai-speaking-change` and (model path) `kai-synthesized`.
+ * `kai-speaking-change`, `kai-voice-error` (a failed synthesis) and (model
+ * path) `kai-synthesized`.
  */
 defineWebComponent<Props, Events>('kai-voice-output', {
   text: '',
@@ -63,6 +75,7 @@ defineWebComponent<Props, Events>('kai-voice-output', {
       onSynthesize={props.synthesize ? (text) => props.synthesize!(text) : undefined}
       onSpeakingChange={(speaking) => dispatch('kai-speaking-change', { speaking })}
       onSynthesized={(blob) => dispatch('kai-synthesized', { blob })}
+      onError={(detail) => dispatch('kai-voice-error', detail)}
       controllerRef={(c) => (controller = c)}
     />
   );

package/src/index.ts

@@ -339,6 +339,8 @@ export type { VoiceInputProps, VoiceInputController } from './components/voice-i
 export { ConversationList } from './components/conversation-list';
 export type { ConversationListProps, ConversationListController } from './components/conversation-list';
 export { ConversationItem } from './components/conversation-item';
+export { SlottedConversationItem } from './components/conversation-item';
+export type { SlottedConversationItemProps } from './components/conversation-item';
 export type { ConversationItemProps } from './components/conversation-item';
 export { ModelSwitcher } from './components/model-switcher';
 export type { ModelSwitcherProps } from './components/model-switcher';
@@ -417,7 +419,8 @@ export type { KaiTabItem } from './ui/tabs';
 export type { PaneStatus } from './ui/pane';
 export type { PaneTab } from './ui/pane-group';
 export type {
-  KaiCommandItem, KaiContextUsage, KaiMenuItem, KaiSegmentedOption, KaiSourceItem,
+  KaiCheckboxOption, KaiCommandItem, KaiContextUsage, KaiMenuItem, KaiRadioOption, KaiSegmentedOption, KaiSelectOption,
+  KaiSourceItem,
 } from './elements/element-data-types';
 // `kai-audio-visualizer.shader` takes a ShaderSpec. The element arrived from main
 // after this block was written, and prop-types-exported.test.ts caught it, which