@kitn.ai/ui 0.25.2 → 0.26.0

package/src/elements/menu.tsx

@@ -51,6 +51,10 @@ interface Props extends Record<string, unknown> {
    *  and an accessible name has to contain the visible text. Then either drop
    *  `label` or make it contain the word you slotted. */
   label?: string;
+  /** Stretch the trigger to the full width of the menu's container (a block
+   *  row), e.g. a sidebar-footer account row. Same affordance as
+   *  `<kai-button full>`. Attribute: `full`. */
+  full?: boolean;
   /** 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`. */
@@ -105,6 +109,7 @@ defineWebComponent<Props, Events>('kai-menu', {
   triggerLabel: undefined,
   triggerIconTrailing: undefined,
   label: undefined,
+  full: false,
   open: undefined,
   defaultOpen: undefined,
   disabled: undefined,
@@ -187,6 +192,12 @@ defineWebComponent<Props, Events>('kai-menu', {
   }
 
   return (
+    <>
+      {/* The host shrinks to the trigger by default (UA inline); `full` makes it
+          a block whose trigger button fills the width — the kai-button pattern
+          (`:host([full])`), for sidebar-footer account rows and other stretched
+          placements. */}
+      <style>{':host([full]){display:block}'}</style>
     <Dropdown
       defaultOpen={flag('defaultOpen')}
       disabled={flag('disabled')}
@@ -198,6 +209,7 @@ defineWebComponent<Props, Events>('kai-menu', {
           props.triggerLabel
             ? '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',
+          flag('full') && 'w-full',
         )}
         // A visible `triggerLabel` IS the name (name-from-contents reaches the
         // slotted/shadow text), so `label` must not be layered over it: aria-label
@@ -224,5 +236,6 @@ defineWebComponent<Props, Events>('kai-menu', {
         {renderItems((props.items as KaiMenuItem[] | undefined) ?? [])}
       </DropdownContent>
     </Dropdown>
+    </>
   );
 });

package/src/elements/prompt-dock.tsx

@@ -23,7 +23,8 @@ type SlotName = (typeof SLOT_NAMES)[number];
 
 /**
  * `<kai-prompt-dock>` — a recessed tray that frames a prompt input and can extend
- * with optional "lip" regions above and/or below it. The input is the raised card
+ * with optional "lip" regions above and/or below it. It sits in the page flow and
+ * launches nothing; the floating corner launcher is `<kai-dock>`. The input is the raised card
  * that floats on the tray; the lips sit in a slightly darker recessed band sharing
  * the tray's rounding, so the whole thing reads as one cohesive control.
  *

package/src/elements/prompt-input.tsx

@@ -27,9 +27,9 @@ interface Props extends Record<string, unknown> {
   /** What clicking a suggestion does: `'submit'` (default) sends it immediately
    *  as if typed and submitted; `'fill'` just places it in the input. */
   suggestionMode?: 'submit' | 'fill';
-  /** Show a Search (Globe) button in the left toolbar; clicking it fires a
-   *  `search` event. */
-  search?: boolean;
+  /** Show a web-search (Globe) button in the left toolbar; clicking it fires a
+   *  `kai-web-search` event. Attribute: `web-search`. */
+  webSearch?: boolean;
   /** Show a Voice (Mic) button in the left toolbar; clicking it fires a `voice`
    *  event. */
   voice?: boolean;
@@ -75,8 +75,8 @@ interface Events {
   'kai-attachments-change': { attachments: AttachmentData[] };
   /** A suggestion was clicked while `suggestion-mode="fill"`. */
   'kai-suggestion-click': { value: string };
-  /** The Search (Globe) toolbar button was clicked. */
-  'kai-search': Record<string, never>;
+  /** The web-search (Globe) toolbar button was clicked. */
+  'kai-web-search': Record<string, never>;
   /** The Voice (Mic) toolbar button was clicked. */
   'kai-voice': Record<string, never>;
   /** The Stop button was clicked while `stoppable` and `loading` are both true. */
@@ -93,7 +93,7 @@ defineWebComponent<Props, Events>('kai-prompt-input', {
   loading: false,
   suggestions: undefined,
   suggestionMode: 'submit',
-  search: false,
+  webSearch: false,
   voice: false,
   stoppable: false,
   submit: 'always',
@@ -215,7 +215,7 @@ defineWebComponent<Props, Events>('kai-prompt-input', {
       attach={flag('attach')}
       suggestions={props.suggestions}
       attachments={attachments()}
-      search={flag('search')}
+      webSearch={flag('webSearch')}
       voice={flag('voice')}
       toolbarActions={toolbarActions()}
       triggers={props.triggers}
@@ -225,7 +225,7 @@ defineWebComponent<Props, Events>('kai-prompt-input', {
       onSubmit={handleSubmit}
       onSuggestionClick={handleSuggestionClick}
       onAttachmentsChange={(a) => { setAttachments(a); dispatch('kai-attachments-change', { attachments: a }); }}
-      onSearch={() => dispatch('kai-search')}
+      onWebSearch={() => dispatch('kai-web-search')}
       onVoice={() => dispatch('kai-voice')}
       onStop={() => dispatch('kai-stop')}
       onAction={(id) => dispatch('kai-toolbar-action', { action: id })}

package/src/elements/register-impl.ts

@@ -3,7 +3,10 @@
 // from ./register.ts so the elements entry is SSR-import-safe — see the comment
 // there. This file is hand-maintained (the generator gen-element-api.mjs SKIPs
 // register.ts AND this file); keep the component import list here in sync.
+import { installKaiDevtoolsHook } from '../diagnostics/hook';
+import { emitElementRegistry } from './element-diagnostics';
 import './conversation-list';
+import './conversation-item';
 import './prompt-input';
 import './chat';
 import './chat-workspace';
@@ -77,6 +80,10 @@ import './compare';
 import './composer';
 // W3 phase 2: cascading action menu from a JSON items-tree
 import './menu';
+// The same Dropdown surface with a consumer-owned body: you slot the rows
+// instead of handing over an items tree (the shape a framework consumer needs
+// when the rows are their own components).
+import './dropdown';
 // W4 phase 1: grouped filterable command/mention palette
 import './command';
 // Prompt dock + settings building blocks (graduated from SolidJS prototypes)
@@ -89,8 +96,47 @@ import './pane';
 import './pane-group';
 import './agent-card';
 import './dialog';
+import './dock';
 // Input & search field family
 import './input';
 import './search';
 import './kbd';
 import './editable-label';
+
+// The devtools recorder hook, installed HERE because this file is already the
+// browser-only half of the elements entry (register.ts gates it behind a window
+// check and a dynamic import). So an app that registers the kai-* elements gets
+// the hook with no work, while an SSR import of the entry still touches no
+// global.
+//
+// At the BOTTOM, and it makes no difference: `import` declarations are hoisted,
+// so every element module above has already evaluated by the time any statement
+// in this file runs. Written here anyway so the order you read is the order that
+// happens. Nothing above emits a diagnostic event, so there is nothing to miss.
+//
+// Idempotent and near-free: with no activation signal it allocates no buffer,
+// makes no subscription, and leaves emission a guarded no-op. An app importing
+// the SolidJS components directly never runs this file and must call
+// `installKaiDevtoolsHook()` itself -- see the docblock in ../diagnostics/index.
+installKaiDevtoolsHook();
+
+// One registry snapshot, right after the hook installs and therefore after every
+// element above has registered (import declarations are hoisted, so they all ran
+// before this line).
+//
+// WHY HERE AND NOT INSIDE THE HOOK. The hook lives in ../diagnostics, which is
+// its own rollup bundle and must stay free of any element import -- pulling the
+// manifest in there would drag element bytes into a consumer who only parses
+// streams. The dependency goes elements -> diagnostics, never back.
+//
+// WHY EMIT AT ALL WHEN A PANEL IS USUALLY NOT THERE YET. On the recording branch
+// the hook has already subscribed by this point, so this snapshot lands in the
+// history buffer and a panel attaching seconds later still sees the state at
+// load -- which is the state that answers the hydration question. On the dormant
+// branch `emitElementRegistry()` short-circuits on the active check and costs a
+// symbol read.
+//
+// A panel attaching mid-session with no history gets no snapshot from here and
+// should ask for a fresh one: `emitElementRegistry()` is exported from
+// @kitn.ai/ui/elements for exactly that.
+emitElementRegistry();

package/src/elements/register.ts

@@ -38,6 +38,34 @@ export type { CodeHighlightingOptions } from '../primitives/highlighter';
 export { classifyTool } from '../components/tool-classify';
 export type { ToolKind } from '../components/tool-classify';
 
+// Element-layer diagnostics. `emitElementRegistry()` re-emits the which-elements-
+// are-defined snapshot on demand, for a panel that attached mid-session and so
+// missed the one register-impl emits at load. SSR-safe and a no-op with no
+// subscriber, so calling it unconditionally is fine.
+//
+// WHY THIS ONE PRODUCER IS PUBLIC while `@kitn.ai/ui/diagnostics` deliberately
+// keeps `emitWireDiagnostic`, `nextStreamId` and `setWirePayloadCapture`
+// internal. That rule exists because a consumer able to forge events or reset
+// the stream counter can make a panel lie about a stream that never happened,
+// and one able to flip payload capture can start recording an app's users'
+// conversations without the app deciding to. This function takes no arguments
+// and reports nothing but `customElements.get()` over the manifest: there is no
+// value to forge, no counter to move and no capture to arm. It can only tell the
+// truth about the registry, which is the one thing a late-attaching panel cannot
+// find out for itself.
+//
+// The event TYPES are re-exported here as well as from @kitn.ai/ui/diagnostics:
+// a consumer already importing the elements entry should not have to add a
+// second specifier to name the events it is handed.
+export { emitElementRegistry } from './element-diagnostics';
+export type {
+  ElementDiagnosticBase,
+  ElementDiagnosticEvent,
+  ElementRegistryEvent,
+  ElementViolationEvent,
+  ElementViolationKind,
+} from './diagnostic-events';
+
 // Imperative toast API — usable directly from the elements entry so consumers
 // who only import the web-components bundle still get `toast()`. The store is
 // SSR-safe (no DOM touched until the first toast is raised on the client).

package/src/elements/resizable.tsx

@@ -129,9 +129,16 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
         min: el.getAttribute('min') ?? undefined,
         max: el.getAttribute('max') ?? undefined,
         locked: el.hasAttribute('locked') && el.getAttribute('locked') !== 'false',
-        // Honour both the `hidden` boolean attribute and the IDL property — Solid
-        // (and direct `el.hidden = true`) set the property, which doesn't reflect
-        // to the attribute on a custom element.
+        // Honour both the `hidden` attribute and the property, because on THIS element
+        // they are two independent halves of the state and either can be the only one
+        // set. Not a fact about custom elements in general — a custom element that does
+        // not declare a `hidden` prop keeps the native reflecting accessor. It is a fact
+        // about this one: `<kai-resizable-item>` declares `hidden: false`, so
+        // component-register owns the property and nothing reflects. Measured:
+        // `el.hidden = true` writes no attribute, and after maximize writes the
+        // attribute `el.hidden` reads `undefined`. This union is what absorbs that, and
+        // it is why `hidden` is exempt from the reflectFlag migration rather than broken
+        // by it — see reflectItemConfig's doc below.
         hidden: el.hidden || (el.hasAttribute('hidden') && el.getAttribute('hidden') !== 'false'),
         collapsed,
       };
@@ -543,10 +550,22 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
  * *properties* — `el.size = "280px"` — but component-register only mirrors
  * attribute→property, never the reverse, so a property-set size never becomes an
  * attribute and the parent silently falls back to a flexible split. This is the
- * exact class of bug the `collapsed` reflection already fixed; extended here to
- * `size`/`min`/`max` (strings) and `locked` (boolean). `hidden` is deliberately
- * NOT reflected — native `el.hidden` reflects to the attribute on its own and the
- * parent honours the `hidden` property directly (and maximize drives `hidden`).
+ * exact class of bug the `collapsed` reflection already fixed; handled here for
+ * `size`/`min`/`max` (the STRINGS). The booleans — `collapsed` and `locked` — go
+ * through `reflectFlag` in the facade body instead, which reflects AND keeps the
+ * property readable; see WebComponentContext.reflectFlag.
+ *
+ * `hidden` is deliberately NOT reflected, and NOT because it is already fine — it is
+ * split exactly like the others, and measurably so: `el.hidden = true` leaves no
+ * attribute (a plain `<div>` gets one), and after maximize writes the attribute
+ * `el.hidden` reads `undefined`. Declaring `hidden: false` is what does it — it makes
+ * `hidden` a component-register prop, whose non-reflecting accessor shadows the native
+ * reflecting one. What makes the split HARMLESS here is that both readers take the
+ * union, `el.hidden || el.hasAttribute('hidden')`, so neither half can be missed.
+ * Routing it through `reflectFlag` would put a second writer on an attribute the
+ * maximize/restore path already owns, so it is a behaviour decision of its own rather
+ * than part of the read-back fix. See the exemption in
+ * tests/elements/reflected-boolean-coverage.test.ts.
  *
  * Durability (don't fight drags): the parent WRITES `size` back to the live percent
  * during a drag (`persistSizes` → `setAttribute('size', …)`), and that attribute
@@ -568,7 +587,6 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
 export function reflectItemConfig(
   element: HTMLElement,
   props: { readonly size?: string; readonly min?: string; readonly max?: string },
-  flag: (name: string) => boolean,
 ) {
   const norm = (v: unknown): string | null => (v == null || v === '' ? null : String(v));
   const reflectString = (name: 'size' | 'min' | 'max') => {
@@ -591,11 +609,11 @@ export function reflectItemConfig(
   reflectString('size');
   reflectString('min');
   reflectString('max');
-  // Boolean: mirror the `collapsed`/`loading` precedent — a bare `locked` attribute
-  // and the IDL property are both honoured via `flag`. The parent also writes
-  // `locked` during maximize/restore; because `flag` re-derives from that same
-  // attribute state, the reflection stays self-consistent (no fight).
-  createEffect(() => { element.toggleAttribute('locked', flag('locked')); });
+  // `locked` used to be reflected here too. It is a BOOLEAN, so it now goes through
+  // `reflectFlag` in the facade body next to `collapsed` — a boolean reflected with a
+  // bare `toggleAttribute` reads back `undefined` (see WebComponentContext.reflectFlag),
+  // and `reflectFlag` is only reachable from the facade's context. What is left here is
+  // the string props, which is this helper's real subject: the drag-durability guard.
 }
 
 interface ItemProps extends Record<string, unknown> {
@@ -633,23 +651,32 @@ defineWebComponent<ItemProps>('kai-resizable-item', {
   locked: false,
   hidden: false,
   collapsed: false,
-}, (props, { element, flag }) => {
+}, (props, { element, reflectFlag }) => {
   // Reflect the reactive `collapsed` prop to the `collapsed` ATTRIBUTE the parent
   // <kai-resizable> reads (and observes). This is what makes a bare JSX boolean
   // collapse the panel at INITIAL render from any framework: component-register
   // parses `<kai-resizable-item collapsed>` to `undefined` (not `true`), and a JSX
-  // boolean sets neither `hidden` nor the IDL property — so `flag('collapsed')`
-  // (which also honours the attribute) is the reliable source, and toggleAttribute
-  // mirrors it back so the parent's readItems()/MutationObserver lay it out. Same
-  // pattern as <kai-chat>'s `loading` reflection. We touch only `collapsed`, never
-  // `hidden`, so the back-compat hidden path and maximize (which drive `hidden`)
-  // are untouched.
-  createEffect(() => { element.toggleAttribute('collapsed', flag('collapsed')); });
-  // Reflect the other config props (`size`/`min`/`max`/`locked`) property→attribute
-  // for the SAME reason — a framework that sets them as DOM properties (React et al.)
-  // would otherwise be invisible to the parent. See reflectItemConfig for the
+  // boolean sets neither `hidden` nor the IDL property — so the flag resolution
+  // (which also honours the attribute) is the reliable source, and the attribute is
+  // mirrored back so the parent's readItems()/MutationObserver lay it out. Same
+  // pattern as <kai-chat>'s `loading` reflection, and now literally the same code:
+  // `reflectFlag` also makes `el.collapsed` READ BACK, which a hand-rolled
+  // toggleAttribute effect does not (WebComponentContext.reflectFlag).
+  //
+  // We touch only `collapsed` and `locked`, never `hidden`, so the back-compat hidden
+  // path and maximize (which drive `hidden`) are untouched — see the named exemption
+  // in tests/elements/reflected-boolean-coverage.test.ts for why `hidden` is a
+  // separate decision rather than an oversight.
+  reflectFlag('collapsed');
+  // `locked` is the parent's other boolean input; the parent also writes it during
+  // maximize/restore, and because the flag resolution re-derives from that same
+  // attribute state the reflection stays self-consistent (no fight).
+  reflectFlag('locked');
+  // Reflect the STRING config props (`size`/`min`/`max`) property→attribute for the
+  // SAME reason — a framework that sets them as DOM properties (React et al.) would
+  // otherwise be invisible to the parent. See reflectItemConfig for the
   // drag-durability guard on `size`.
-  reflectItemConfig(element, props, flag);
+  reflectItemConfig(element, props);
   return (
   <>
     {/* The item host fills the panel's single grid cell (the panel stretches it on

package/src/elements/scroll-button.tsx

@@ -109,6 +109,11 @@ defineWebComponent<Props, Events>('kai-scroll-button', {
       variant={props.variant ?? 'outline'}
       size={props.size ?? 'icon'}
       aria-label="Scroll to bottom"
+      // While at the bottom this button is fully transparent and pointer-inert,
+      // but it stayed in the tab order — a keyboard user landed on a control
+      // they could not see. Mirrors ScrollButton in components/scroll-button.tsx.
+      tabindex={isAtBottom() ? -1 : 0}
+      aria-hidden={isAtBottom() ? 'true' : undefined}
       class={cn(
         'rounded-full transition-all duration-150 ease-out',
         !isAtBottom()

package/src/elements/slots.ts

@@ -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

@@ -40,12 +40,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;
@@ -87,6 +98,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`. */