@kitn.ai/ui 0.16.0 → 0.18.0

package/src/elements/composer.tsx

@@ -0,0 +1,151 @@
+import { createSignal } from 'solid-js';
+import { defineWebComponent } from './define';
+import type { ComposerDoc, EntityRef } from '../primitives/composer-model';
+import type { TriggerDef, TriggerItem, HighlightRule, ComposerChange, ComposerController } from '../components/composer';
+import { Composer } from '../components/composer';
+
+/**
+ * Parse a single light-DOM `<kai-trigger-item>` element into a TriggerItem.
+ * Attribute mapping:
+ *  - `item-id`     → TriggerItem.id       (required; empty string fallback)
+ *  - textContent   → TriggerItem.label    (primary); `label` attr as fallback
+ *  - `icon`        → TriggerItem.icon
+ *  - `prompt-text` → TriggerItem.promptText
+ *  - `data`        is left undefined (complex object, not representable as an attribute)
+ *
+ * @param n    The `<kai-trigger-item>` element to parse.
+ * @param char The trigger character this item belongs to (e.g. `/` or `@`).
+ * @param kind The entity kind for this trigger (e.g. `'skill'` or `'mention'`).
+ */
+export function parseKaiTriggerItemElement(n: Element, char: string, kind: string): TriggerItem {
+  // char and kind inform the consumer but are not stored on TriggerItem itself.
+  void char;
+  void kind;
+  return {
+    id: n.getAttribute('item-id') ?? '',
+    label: n.textContent?.trim() || n.getAttribute('label') || n.getAttribute('item-id') || '',
+    icon: n.getAttribute('icon') ?? undefined,
+    promptText: n.getAttribute('prompt-text') ?? undefined,
+    data: undefined,
+  };
+}
+
+interface Props extends Record<string, unknown> {
+  /** Controlled value — string or a full ComposerDoc (set as JS property). */
+  value?: string | ComposerDoc;
+  /** Placeholder text shown when the composer is empty. */
+  placeholder?: string;
+  /** Disable the composer entirely (non-interactive). */
+  disabled?: boolean;
+  /** Show a loading/streaming state and block submit. */
+  loading?: boolean;
+  /** Maximum height in px before the content scrolls. Default 240. */
+  maxHeight?: number | string;
+  /** Whether pressing Enter (without Shift) submits. Default true. */
+  submitOnEnter?: boolean;
+  /** Trigger definitions — set as a JS property. */
+  triggers?: TriggerDef[];
+  /** Keyword highlight rules — set as a JS property. */
+  highlights?: HighlightRule[];
+  /** Default icon per entity kind (kind → image URL/data-URI) for items without
+   *  their own `icon`. Overrides the built-in agent/plugin glyphs. JS property. */
+  kindIcons?: Record<string, string>;
+}
+
+/** Events fired by `<kai-composer>`. */
+interface Events {
+  /** The user submitted the composer (Enter or programmatic submit). */
+  'kai-submit': { doc: ComposerDoc; text: string; entities: EntityRef[] };
+  /** The content changed (fires on every input event). */
+  'kai-value-change': { doc: ComposerDoc; text: string; entities: EntityRef[] };
+  /** An entity pill was inserted into the composer. */
+  'kai-entity-add': { entity: EntityRef };
+  /** An entity pill was deleted from the composer. */
+  'kai-entity-remove': { entity: EntityRef };
+  /** A trigger character was detected at the caret (e.g. `/` or `@`). */
+  'kai-trigger': { char: string; query: string; rect: DOMRect };
+  /** The active trigger was dismissed (Escape, space, or outside click). */
+  'kai-trigger-close': Record<string, never>;
+  /** The composer gained focus. `focus`/`blur` are NOT composed natively, so they
+   *  don't escape the shadow root — these re-expose them on the host. (For
+   *  `keydown`/`paste`/`focusin`/`focusout`, listen NATIVELY on `<kai-composer>`:
+   *  they're composed and already cross the shadow boundary.) */
+  'kai-focus': { originalEvent: FocusEvent };
+  /** The composer lost focus. */
+  'kai-blur': { originalEvent: FocusEvent };
+}
+
+defineWebComponent<Props, Events>('kai-composer', {
+  value: undefined,
+  placeholder: undefined,
+  disabled: false,
+  loading: false,
+  maxHeight: 240,
+  submitOnEnter: true,
+  triggers: undefined,
+  highlights: undefined,
+  kindIcons: undefined,
+}, (props, { dispatch, flag, expose }) => {
+  // Internal signal for uncontrolled value; when the consumer sets `value` as a
+  // JS property the controlled path takes precedence (same pattern as prompt-input).
+  const [internal, setInternal] = createSignal<string | ComposerDoc | undefined>(props.value);
+
+  const current = () => props.value ?? internal();
+
+  // ── Imperative API (instance methods on the host) ──────────────────────────
+  // Pattern C: the Composer component owns the editable + doc state and hands up
+  // a controller; the facade captures it and exposes delegating methods. The
+  // composer's own callbacks still fire (clear → onChange → kai-value-change;
+  // send → onSubmit → kai-submit; insertEntity → onEntityAdd → kai-entity-add).
+  let controller: ComposerController | undefined;
+  expose({
+    /** Focus the editable element. `focus`/`blur` are NOT composed natively, so a
+     *  host-level focus() can't reach the editable inside the shadow root — this is
+     *  the only way to focus the composer programmatically. */
+    focus: (options?: FocusOptions) => controller?.focus(options),
+    /** Blur the editable element. */
+    blur: () => controller?.blur(),
+    /** Empty the composer to a blank doc (resets the internal value + history
+     *  baseline; fires kai-value-change). */
+    clear: () => controller?.clear(),
+    /** Submit the current content programmatically — same path as Enter (fires
+     *  kai-submit). Named `send`, not `submit`, to match the shared vocabulary and
+     *  avoid any submit collision. */
+    send: () => controller?.send(),
+    /** Insert an atomic entity pill (skill/agent/plugin) at the caret without
+     *  typing a trigger (fires kai-entity-add). */
+    insertEntity: (entity: EntityRef) => controller?.insertEntity(entity),
+  });
+
+  const handleChange = (change: ComposerChange) => {
+    setInternal(change.doc);
+    dispatch('kai-value-change', { doc: change.doc, text: change.text, entities: change.entities });
+  };
+
+  const handleSubmit = (change: ComposerChange) => {
+    dispatch('kai-submit', { doc: change.doc, text: change.text, entities: change.entities });
+  };
+
+  return (
+    <Composer
+      value={current()}
+      placeholder={props.placeholder}
+      disabled={flag('disabled')}
+      loading={flag('loading')}
+      maxHeight={props.maxHeight as number | string | undefined}
+      submitOnEnter={flag('submitOnEnter')}
+      triggers={props.triggers}
+      highlights={props.highlights}
+      kindIcons={props.kindIcons as Record<string, string> | undefined}
+      onChange={handleChange}
+      onSubmit={handleSubmit}
+      onEntityAdd={(entity) => dispatch('kai-entity-add', { entity })}
+      onEntityRemove={(entity) => dispatch('kai-entity-remove', { entity })}
+      onTrigger={(info) => dispatch('kai-trigger', info)}
+      onTriggerClose={() => dispatch('kai-trigger-close', {})}
+      onFocus={(e) => dispatch('kai-focus', { originalEvent: e })}
+      onBlur={(e) => dispatch('kai-blur', { originalEvent: e })}
+      controllerRef={(c) => (controller = c)}
+    />
+  );
+});

package/src/elements/confirm-card.tsx

@@ -1,5 +1,5 @@
 import { defineWebComponent } from './define';
-import { ConfirmCard, type ConfirmCardData } from '../components/confirm-card';
+import { ConfirmCard, type ConfirmCardData, type ConfirmController } from '../components/confirm-card';
 import type { CardResolution } from '../primitives/card-contract';
 
 interface Props extends Record<string, unknown> {
@@ -28,6 +28,9 @@ interface Props extends Record<string, unknown> {
  * optional close affordance, and `error` for a malformed definition (inline error).
  * Routes through a `CardProvider` when present, else the bubbling `kai-card` event.
  * Isolated in Shadow DOM; theme-aware via the shared kit tokens.
+ *
+ * Exposes instance methods `focus()`/`confirm(actionId?)`/`dismiss()`/`reopen()`
+ * that drive the same internal paths as the buttons.
  */
 defineWebComponent<Props>(
   'kai-confirm',
@@ -38,14 +41,36 @@ defineWebComponent<Props>(
     autofocus: false,
     resolution: undefined,
   },
-  (props, { element, flag }) => (
-    <ConfirmCard
-      data={props.data as ConfirmCardData | undefined}
-      cardId={props.cardId ?? (element.id || 'kai-confirm')}
-      heading={props.heading}
-      autofocus={flag('autofocus')}
-      resolution={props.resolution as CardResolution | undefined}
-      hostElement={element}
-    />
-  ),
+  (props, { element, flag, expose }) => {
+    // Pattern C: the ConfirmCard owns the action/dismiss state and hands up a
+    // controller; the facade captures it and exposes delegating methods. The card's
+    // own paths still fire (confirm → kai-card `action`; dismiss/reopen → kai-card
+    // `dismiss`/`reopen`).
+    let controller: ConfirmController | undefined;
+    expose({
+      /** Focus the default action button (or the first action if none is default) —
+       *  the same target `autofocus` focuses on mount, but on demand. */
+      focus: (options?: FocusOptions) => controller?.focus(options),
+      /** Activate an action by id — emits the `action` verb on kai-card and resolves
+       *  the card (single-shot). With no id, invokes the default action. */
+      confirm: (actionId?: string) => controller?.confirm(actionId),
+      /** Trigger the dismiss path — emits `dismiss` on kai-card and optimistically
+       *  collapses the card to its re-openable stub. */
+      dismiss: () => controller?.dismiss(),
+      /** Re-open a dismissed card from its stub — emits `reopen` on kai-card. */
+      reopen: () => controller?.reopen(),
+    });
+
+    return (
+      <ConfirmCard
+        data={props.data as ConfirmCardData | undefined}
+        cardId={props.cardId ?? (element.id || 'kai-confirm')}
+        heading={props.heading}
+        autofocus={flag('autofocus')}
+        resolution={props.resolution as CardResolution | undefined}
+        controllerRef={(c) => (controller = c)}
+        hostElement={element}
+      />
+    );
+  },
 );

package/src/elements/conversation-list.tsx

@@ -1,6 +1,8 @@
-import { createSignal, onMount, onCleanup } from 'solid-js';
+import { createSignal, onMount, onCleanup, Show } from 'solid-js';
 import { defineWebComponent } from './define';
-import { ConversationList } from '../components/conversation-list';
+import { createControllableSignal } from '../primitives/controllable';
+import { readSlots, CONVERSATIONS_SLOTS } from './slots';
+import { ConversationList, CollapsedRail, type ConversationListController } from '../components/conversation-list';
 import type { ConversationGroup, ConversationSummary, ConversationScope } from '../types';
 
 interface Props extends Record<string, unknown> {
@@ -13,6 +15,14 @@ interface Props extends Record<string, unknown> {
   conversations: ConversationSummary[];
   /** The id of the currently-open conversation, highlighted in the list. */
   activeId?: string;
+  /** Controlled collapsed state. Set as a JS property (`el.collapsed = true`) to
+   *  drive the rail from your app, updating it in response to `kai-collapse-toggle`.
+   *  Omit for uncontrolled (the element manages it). Collapsed shrinks the rail to
+   *  a floating reopen button. */
+  collapsed?: boolean;
+  /** Initial collapsed state when uncontrolled (default false). Use the
+   *  `default-collapsed` attribute to start collapsed in plain HTML. */
+  defaultCollapsed?: boolean;
 }
 
 interface Events {
@@ -22,6 +32,12 @@ interface Events {
   'kai-new-chat': Record<string, never>;
   /** The sidebar toggle was clicked. */
   'kai-toggle-sidebar': Record<string, never>;
+  /** The rail was collapsed or expanded (via the toggle, the reopen button, or a
+   *  `collapse()`/`expand()`/`toggle()` call). */
+  'kai-collapse-toggle': { collapsed: boolean };
+  /** The built-in search box query changed (typing, or a programmatic `clear()`
+   *  which fires it with `''`). Lets a consumer mirror or server-side the filter. */
+  'kai-search': { query: string };
 }
 
 /** Parse a single light-DOM `<kai-conversation>` element into a `ConversationSummary`.
@@ -49,14 +65,19 @@ defineWebComponent<Props, Events>('kai-conversations', {
   groups: [],
   conversations: [],
   activeId: undefined,
-}, (props, { dispatch, element }) => {
+  collapsed: undefined,
+  defaultCollapsed: undefined,
+}, (props, { dispatch, element, expose, flag }) => {
   // Read declarative <kai-conversation> children from light DOM.
   // Shadow DOM with no <slot> suppresses them visually — they're invisible data carriers.
   const [slottedConversations, setSlottedConversations] = createSignal<ConversationSummary[]>([]);
+  // Which composition slots (header/empty/footer) the consumer has filled.
+  const [slots, setSlots] = createSignal<Record<string, boolean>>({});
   onMount(() => {
     const read = () => {
       const nodes = [...element.querySelectorAll('kai-conversation')];
       setSlottedConversations(nodes.map(parseKaiConversationElement));
+      setSlots(readSlots(element, CONVERSATIONS_SLOTS));
     };
     read();
     const observer = new MutationObserver(read);
@@ -67,14 +88,62 @@ defineWebComponent<Props, Events>('kai-conversations', {
   // Prop conversations take precedence; slotted children are appended after.
   const allConversations = () => [...(props.conversations ?? []), ...slottedConversations()];
 
+  // ── Rail collapse (controlled/uncontrolled, same pattern as kai-workspace) ──
+  // `collapsed` (when set) wins; otherwise the element manages its own state,
+  // seeded from `defaultCollapsed`. `setCollapsedTo` always writes the internal
+  // value (a no-op visually while controlled) and emits `kai-collapse-toggle` so
+  // a controlling app can update its own state. Collapsed → the shared
+  // CollapsedRail (the same floating reopen button kai-workspace renders).
+  const [collapsed, setCollapsed] = createControllableSignal(
+    () => props.collapsed as boolean | undefined,
+    flag('defaultCollapsed'),
+  );
+  const setCollapsedTo = (next: boolean) => { setCollapsed(next); dispatch('kai-collapse-toggle', { collapsed: next }); };
+
+  // ── Imperative API (instance methods on the host) ──────────────────────────
+  // The search box's query lives inside ConversationList; we capture its
+  // controller (Pattern C) to focus / clear it from the facade.
+  let controller: ConversationListController | undefined;
+  expose({
+    /** Focus the built-in search input inside the shadow root. */
+    focus: (options?: FocusOptions) => {
+      // Prefer the captured controller; fall back to a shadow query (the search
+      // box only renders when there are conversations).
+      if (controller) controller.focus(options);
+      else element.shadowRoot?.querySelector<HTMLInputElement>('input')?.focus(options);
+    },
+    /** Clear the internal search query (resets the list filter) and fire
+     *  kai-search with an empty string. */
+    clear: () => controller?.clearSearch(),
+    /** Programmatically select a conversation by id — mirror of the
+     *  kai-conversation-select event (a convenience over driving `activeId`). */
+    select: (id: string) => dispatch('kai-conversation-select', { id }),
+    /** Collapse the rail to its floating reopen button (fires `kai-collapse-toggle`). */
+    collapse: () => setCollapsedTo(true),
+    /** Expand the rail back to the full list (fires `kai-collapse-toggle`). */
+    expand: () => setCollapsedTo(false),
+    /** Toggle the rail collapsed/expanded (fires `kai-collapse-toggle`). */
+    toggle: () => setCollapsedTo(!collapsed()),
+  });
+
   return (
-    <ConversationList
-      groups={props.groups}
-      conversations={allConversations()}
-      activeId={props.activeId}
-      onSelect={(id) => dispatch('kai-conversation-select', { id })}
-      onNewChat={() => dispatch('kai-new-chat')}
-      onToggleSidebar={() => dispatch('kai-toggle-sidebar')}
-    />
+    <Show
+      when={!collapsed()}
+      fallback={<CollapsedRail onExpand={() => setCollapsedTo(false)} />}
+    >
+      <ConversationList
+        groups={props.groups}
+        conversations={allConversations()}
+        activeId={props.activeId}
+        onSelect={(id) => dispatch('kai-conversation-select', { id })}
+        onNewChat={() => dispatch('kai-new-chat')}
+        onToggleSidebar={() => { dispatch('kai-toggle-sidebar'); setCollapsedTo(true); }}
+        onSearchChange={(query) => dispatch('kai-search', { query })}
+        controllerRef={(c) => (controller = c)}
+        header={slots().header ? <slot name="header" /> : undefined}
+        footer={slots().footer ? <slot name="footer" /> : undefined}
+        empty={slots().empty ? <slot name="empty" /> : undefined}
+      />
+    </Show>
   );
 });

package/src/elements/default-input.tsx

@@ -1,7 +1,8 @@
 import { For, Show } from 'solid-js';
 import { PromptInput, PromptInputTextarea, PromptInputActions } from '../components/prompt-input';
+import type { TriggerDef, ComposerChange } from '../components/composer';
+import { type ComposerDoc, normalizeValue, serializeToText } from '../primitives/composer-model';
 import { PromptSuggestion } from '../components/prompt-suggestion';
-import { SlashCommand, type SlashCommandItem } from '../components/slash-command';
 import { Button } from '../ui/button';
 import { Tooltip } from '../ui/tooltip';
 import { Paperclip, Globe, Mic, Square } from 'lucide-solid';
@@ -17,7 +18,8 @@ import { actionIcon } from '../ui/action-icons';
 import type { CustomAction } from './chat-types';
 
 export interface DefaultPromptInputProps {
-  value: string;
+  /** String = controlled text mirror; ComposerDoc = a seed that pre-populates pills. */
+  value: string | ComposerDoc;
   placeholder?: string;
   disabled?: boolean;
   loading?: boolean;
@@ -25,23 +27,26 @@ export interface DefaultPromptInputProps {
   /** Attachments staged in the input. Provide `onAttachmentsChange` to enable
    *  the attach button + removable previews. */
   attachments?: AttachmentData[];
+  /** When `false`, the built-in paperclip attach button is hidden even if
+   *  `onAttachmentsChange` is provided (e.g. when a `+` menu already covers
+   *  file-attach). Defaults to `true`. */
+  attach?: boolean;
   /** Show a Search (Globe) button in the left toolbar; calls `onSearch`. */
   search?: boolean;
   /** Show a Voice (Mic) button in the left toolbar; calls `onVoice`. */
   voice?: boolean;
-  /** Slash commands — when set, typing `/` opens the command palette. */
-  slashCommands?: SlashCommandItem[];
-  /** Currently-active command ids (highlighted in the palette). */
-  slashActiveIds?: string[];
-  /** Single-line palette rows. */
-  slashCompact?: boolean;
+  /** Send-button visibility. `'always'` (default) always shows it; `'auto'` shows
+   *  it only when there's text/attachments (an empty composer hides it — Enter
+   *  still submits). To hide it entirely (Enter-only), it's pure CSS:
+   *  `::part(send){display:none}` — no prop needed. Restyle via `::part(send)`.
+   *  The Stop button (stoppable + loading) is unaffected. */
+  submit?: 'always' | 'auto';
   onValueChange: (v: string) => void;
   onSubmit: () => void;
   onSuggestionClick: (v: string) => void;
   onAttachmentsChange?: (attachments: AttachmentData[]) => void;
   onSearch?: () => void;
   onVoice?: () => void;
-  onSlashSelect?: (command: SlashCommandItem) => void;
   /** When `true` and `loading` is also `true`, the send button is replaced by
    *  a Stop button that calls `onStop`. */
   stoppable?: boolean;
@@ -51,6 +56,12 @@ export interface DefaultPromptInputProps {
   toolbarActions?: CustomAction[];
   /** Called when a custom toolbar action button is clicked, with the action id. */
   onAction?: (id: string) => void;
+  /** Rich entity triggers (`/` skills, `@` agents) passed to the composer. */
+  triggers?: TriggerDef[];
+  /** Default icon per entity kind (kind → image src) passed to the composer. */
+  kindIcons?: Record<string, string>;
+  /** Structured change (doc + entities) from the composer, on every edit. */
+  onComposerChange?: (change: ComposerChange) => void;
 }
 
 function fileToAttachment(file: File): AttachmentData {
@@ -79,10 +90,20 @@ export function DefaultPromptInput(props: DefaultPromptInputProps) {
   const removeAttachment = (id: string) =>
     props.onAttachmentsChange?.(attachments().filter((a) => a.id !== id));
 
+  // `value` may be a string or a seeded ComposerDoc — compute emptiness from the
+  // flattened text so a pill-only seed still enables Send.
+  const valueText = () => serializeToText(normalizeValue(props.value));
   const sendDisabled = () =>
-    props.disabled || props.loading || (!props.value.trim() && attachments().length === 0);
+    props.disabled || props.loading || (!valueText().trim() && attachments().length === 0);
 
   const showStop = () => !!props.loading && !!props.stoppable;
+  const hasContent = () => !!valueText().trim() || attachments().length > 0;
+  // Send-button visibility: 'always' (default) or 'auto' (only with content).
+  // Full-hide (Enter-only) is CSS: `::part(send){display:none}`.
+  const showSend = () => {
+    const mode = props.submit ?? 'always';
+    return mode === 'always' || (mode === 'auto' && hasContent());
+  };
 
   return (
     <>
@@ -103,17 +124,6 @@ export function DefaultPromptInput(props: DefaultPromptInputProps) {
         disabled={props.disabled}
         class="relative"
       >
-        <Show when={props.slashCommands?.length}>
-          {/* Rendered inside PromptInput so SlashCommand's usePromptInput()
-              context (input value + textarea ref) resolves; the `relative` root
-              anchors its `absolute bottom-full` palette above the input. */}
-          <SlashCommand
-            commands={props.slashCommands!}
-            activeIds={props.slashActiveIds}
-            compact={props.slashCompact}
-            onSelect={(command) => props.onSlashSelect?.(command)}
-          />
-        </Show>
         <Show when={canAttach() && attachments().length}>
           <div class="px-3 pt-3">
             <Attachments variant="inline">
@@ -129,13 +139,18 @@ export function DefaultPromptInput(props: DefaultPromptInputProps) {
             </Attachments>
           </div>
         </Show>
-        {/* Consumer-injected controls rendered before the input area. Native
-            slot; inert outside a shadow root, projected by the custom element. */}
-        <slot name="leading" />
-        <PromptInputTextarea placeholder={props.placeholder} aria-label={props.placeholder || 'Message'} class="min-h-[44px] pt-3 pl-4" />
-        <PromptInputActions class="mt-2 flex w-full items-center justify-between gap-2 px-3 pb-3">
+        {/* Consumer-injected content inside the card, above the textarea (e.g. an
+            inline status strip). A shadow-internal hole — unreachable from outside.
+            Native slot; inert outside a shadow root, projected by the custom element. */}
+        <slot name="input-top" />
+        <PromptInputTextarea placeholder={props.placeholder} aria-label={props.placeholder || 'Message'} class="min-h-[44px] pt-3 pl-4" triggers={props.triggers} kindIcons={props.kindIcons} onComposerChange={props.onComposerChange} />
+        <PromptInputActions class="mt-2 flex w-full items-center justify-between gap-2 px-3 pb-0">
           <div class="flex items-center gap-2">
-            <Show when={canAttach()}>
+            {/* Consumer-injected leading toolbar controls (e.g. a + menu). display:contents
+                ensures an empty slot adds no stray gap; projected nodes lay out as toolbar
+                items. Native slot; projected by the custom element. */}
+            <slot name="toolbar-start" style={{ display: 'contents' }} />
+            <Show when={canAttach() && props.attach !== false}>
               <input
                 ref={fileInput}
                 type="file"
@@ -209,37 +224,44 @@ export function DefaultPromptInput(props: DefaultPromptInputProps) {
               }}
             </For>
           </div>
-          {/* Consumer-injected controls rendered after the input area, beside
-              the send button. Native slot; projected by the custom element. */}
-          <slot name="trailing" />
-          <Show
-            when={showStop()}
-            fallback={
+          {/* Right cluster — consumer trailing controls (model/effort/voice…)
+              hug the send button, right-aligned. The `toolbar-end` slot and the send
+              button live together so justify-between pins them to the right edge
+              (left group stays left). Native slot; projected by the element. */}
+          <div class="flex items-center gap-2">
+            <slot name="toolbar-end" />
+            <Show
+              when={showStop()}
+              fallback={
+                <Show when={showSend()}>
+                  <Button
+                    size="icon-sm"
+                    class="rounded-full"
+                    part="send"
+                    data-testid="send"
+                    aria-label="Send message"
+                    disabled={sendDisabled()}
+                    onClick={props.onSubmit}
+                  >
+                    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                      <line x1="12" y1="19" x2="12" y2="5" /><polyline points="5 12 12 5 19 12" />
+                    </svg>
+                  </Button>
+                </Show>
+              }
+            >
               <Button
                 size="icon-sm"
+                variant="outline"
                 class="rounded-full"
-                data-testid="send"
-                aria-label="Send message"
-                disabled={sendDisabled()}
-                onClick={props.onSubmit}
+                data-testid="stop"
+                aria-label="Stop"
+                onClick={props.onStop}
               >
-                <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
-                  <line x1="12" y1="19" x2="12" y2="5" /><polyline points="5 12 12 5 19 12" />
-                </svg>
+                <Square class="size-3" />
               </Button>
-            }
-          >
-            <Button
-              size="icon-sm"
-              variant="outline"
-              class="rounded-full"
-              data-testid="stop"
-              aria-label="Stop"
-              onClick={props.onStop}
-            >
-              <Square class="size-3" />
-            </Button>
-          </Show>
+            </Show>
+          </div>
         </PromptInputActions>
       </PromptInput>
     </>

package/src/elements/define.tsx

@@ -1,7 +1,7 @@
 import { customElement } from 'solid-element';
 import { ChatConfig } from '../primitives/chat-config';
 import { ELEMENT_CSS } from './css';
-import { createSignal, onCleanup, onMount, Show, type JSX } from 'solid-js';
+import { createSignal, onCleanup, Show, type JSX } from 'solid-js';
 
 /**
  * Shared constructable stylesheet, built once and adopted by every element's
@@ -67,6 +67,17 @@ export interface WebComponentContext<E = Record<string, unknown>> {
    * `name` is the camelCase prop name; the matching kebab attribute is derived.
    */
   flag: (name: string) => boolean;
+  /**
+   * Expose imperative methods on the host element instance — the input half of a
+   * component's interaction surface (`el.focus()`, `el.clear()`, `el.scrollToBottom()`,
+   * …), the counterpart to the events `dispatch` fires. Call once from the facade
+   * with closures over its internal state/refs; each entry is assigned to the host,
+   * so a consumer calls it directly: `document.querySelector('kai-prompt-input').focus()`.
+   * Overriding a native method name (e.g. `focus`) shadows it on the instance so it
+   * can target the right control inside the shadow root (the WebAwesome/Shoelace
+   * convention). Methods are attached when the facade renders (on element upgrade).
+   */
+  expose: (methods: Record<string, (...args: never[]) => unknown>) => void;
 }
 
 /** camelCase prop name → kebab-case attribute (`hoverCard` → `hover-card`). */
@@ -77,6 +88,8 @@ function toAttr(name: string): string {
 /** Underlying flag resolution; see `WebComponentContext.flag`. */
 function resolveFlag(element: HTMLElement, value: unknown, attribute: string): boolean {
   if (value === true) return true;
+  // An explicit JS false wins over a present attribute (see WebComponentContext.flag); this also prevents a feedback loop when an effect writes the attribute it reads.
+  if (value === false) return false;
   return element.hasAttribute(attribute) && element.getAttribute(attribute) !== 'false';
 }
 
@@ -144,17 +157,45 @@ export function defineWebComponent<P extends Record<string, unknown>, E = Record
     const flag = (name: string) =>
       resolveFlag(element, (props as Record<string, unknown>)[name], toAttr(name));
 
+    // Attach imperative methods onto the host instance. See WebComponentContext.expose.
+    // Uses defineProperty so a method can shadow an inherited getter-only accessor
+    // (e.g. `focus`/`blur`) which a plain assignment would throw on. A method name
+    // must NOT collide with a declared prop (the prop's accessor would be clobbered)
+    // — pick a distinct verb (e.g. `send()` next to a `submit` prop). Failures warn
+    // and skip rather than breaking the element's render.
+    const expose: WebComponentContext<E>['expose'] = (methods) => {
+      for (const [name, fn] of Object.entries(methods)) {
+        try {
+          Object.defineProperty(element, name, { value: fn, writable: true, configurable: true });
+        } catch (err) {
+          console.warn(`defineWebComponent(${tag}): could not expose method "${name}"`, err);
+        }
+      }
+    };
+
     const isDark = createDarkMode(() => props.theme as string | undefined);
 
     // Prefer a single shared stylesheet adopted into this shadow root; only emit
     // an inline <style> when Constructable Stylesheets aren't supported.
+    //
+    // Adopt SYNCHRONOUSLY, before solid-element inserts the rendered content into
+    // the shadow root. component-register attaches the shadow root lazily on first
+    // `renderRoot` access — which happens during that insert, AFTER this facade
+    // function returns. So we pre-attach the shadow root here (with the same
+    // `mode: 'open'` the renderRoot getter would use, making it a no-op for
+    // solid-element) and adopt the sheet now. If we deferred to onMount instead,
+    // the content would paint UNSTYLED and then animate from that bare state to
+    // its resting style once the sheet landed — every `transition-colors` button
+    // and menu/dropdown trigger flashing as if hovered-then-un-hovered on first
+    // render. Adopting first means the very first computed style of every node is
+    // already the resting style, so no transition can fire on load.
     const sheet = getSharedSheet();
-    onMount(() => {
-      const root = element.shadowRoot;
-      if (sheet && root && 'adoptedStyleSheets' in root) {
+    if (sheet) {
+      const root = element.shadowRoot ?? element.attachShadow({ mode: 'open' });
+      if ('adoptedStyleSheets' in root && !root.adoptedStyleSheets.includes(sheet)) {
         root.adoptedStyleSheets = [...root.adoptedStyleSheets, sheet];
       }
-    });
+    }
 
     return (
       <>
@@ -168,7 +209,7 @@ export function defineWebComponent<P extends Record<string, unknown>, E = Record
         <div classList={{ dark: isDark() }} style={{ display: 'contents', color: 'var(--color-foreground)' }}>
           <div ref={portalNode} />
           <ChatConfig portalMount={portalNode}>
-            {Facade(props as unknown as P, { element, dispatch, flag })}
+            {Facade(props as unknown as P, { element, dispatch, flag, expose })}
           </ChatConfig>
         </div>
       </>