@kitn.ai/ui 0.17.0 → 0.18.1

package/src/elements/pane.tsx

@@ -0,0 +1,129 @@
+import { createSignal, onCleanup, onMount } from 'solid-js';
+import { defineWebComponent } from './define';
+import { Pane, type PaneStatus } from '../ui/pane';
+
+interface Props extends Record<string, unknown> {
+  /** The pane title (the agent / window name). Named `headline` because `title`
+   *  collides with the global `HTMLElement.title` attribute (it throws at
+   *  registration). Attribute: `headline`. */
+  headline?: string;
+  /** A role / label shown under the title (e.g. "Reviewer", "claude-sonnet").
+   *  Attribute: `subtitle`. */
+  subtitle?: string;
+  /** Show the restore glyph instead of maximize, and signal the maximized
+   *  view-state. Drive it yourself in response to `kai-maximize`. Attribute:
+   *  `maximized`. */
+  maximized?: boolean;
+  /** Highlight the frame with a ring/border to mark the ACTIVE pane. Attribute:
+   *  `focused`. */
+  focused?: boolean;
+  /** Show a split-pane window control that fires `kai-split`. Off by default.
+   *  Attribute: `show-split`. */
+  showSplit?: boolean;
+  /** Show a dock-to-side window control that fires `kai-dock`. Off by default.
+   *  Attribute: `show-dock`. */
+  showDock?: boolean;
+  /** A tone-colored status dot (+ optional label) in the header. An object
+   *  `{ tone, label?, pulse? }` set as a JS PROPERTY (not an attribute). */
+  status?: PaneStatus;
+}
+
+/** Events fired by `<kai-pane>`. All non-bubbling — listen on the element. */
+interface Events {
+  /** The maximize/restore control was clicked. `detail.maximized` is the
+   *  intended NEXT state — drive the `maximized` prop yourself from it. */
+  'kai-maximize': { maximized: boolean };
+  /** The close (×) control was clicked. */
+  'kai-close': void;
+  /** The split control was clicked (only present when `show-split`). */
+  'kai-split': void;
+  /** The dock control was clicked (only present when `show-dock`). */
+  'kai-dock': void;
+}
+
+/** Named slots whose occupancy gates a header/footer region. An empty `<slot>`
+ *  is always a truthy node, so the facade tracks which are actually filled and
+ *  only passes those regions to the primitive (no stray glyph slot / footer
+ *  divider when unfilled). */
+const SLOT_NAMES = ['leading', 'actions', 'footer'] as const;
+type SlotName = (typeof SLOT_NAMES)[number];
+
+/**
+ * `<kai-pane>` — a framed panel for a multi-agent workspace: a header (leading
+ * glyph + title/subtitle + status dot + extra actions + window controls), a
+ * scrolling body, and an optional pinned footer (e.g. a composer). Composable:
+ * slots + parts + events, not a config blob.
+ *
+ * Slots: `leading` (header glyph/avatar), `actions` (extra header controls,
+ * placed before the window controls), the DEFAULT slot (body), `footer`.
+ *
+ * Window controls (right of the header): maximize/restore and close are always
+ * present; split and dock appear only with `show-split` / `show-dock`. Each
+ * fires a `kai-*` event so the consumer drives state itself (uncontrolled-
+ * friendly): listen for `kai-maximize` and set `maximized` from
+ * `event.detail.maximized`.
+ *
+ * Parts: `::part(header|body|footer|controls)`.
+ *
+ * ```html
+ * <kai-pane headline="Reviewer" subtitle="claude-sonnet" focused show-split
+ *           onkai-maximize="this.maximized = event.detail.maximized">
+ *   <img slot="leading" src="…" alt="" />
+ *   <kai-button slot="actions" variant="ghost">Retry</kai-button>
+ *   <kai-message-thread>…</kai-message-thread>
+ *   <kai-prompt-input slot="footer"></kai-prompt-input>
+ * </kai-pane>
+ * <script>
+ *   const pane = document.querySelector('kai-pane');
+ *   pane.status = { tone: 'working', label: 'Running tests…', pulse: true };
+ * </script>
+ * ```
+ */
+defineWebComponent<Props, Events>('kai-pane', {
+  headline: '',
+  subtitle: undefined,
+  maximized: false,
+  focused: false,
+  showSplit: false,
+  showDock: false,
+  status: undefined,
+}, (props, { element, dispatch, flag }) => {
+  // Track which named slots are filled. Re-read on child mutations so streamed/
+  // late content lights up its region. An unfilled region is never rendered.
+  const [filled, setFilled] = createSignal<Record<SlotName, boolean>>({
+    leading: false, actions: false, footer: false,
+  });
+
+  onMount(() => {
+    const read = () => {
+      const next = {} as Record<SlotName, boolean>;
+      for (const name of SLOT_NAMES) next[name] = !!element.querySelector(`:scope > [slot="${name}"]`);
+      setFilled(next);
+    };
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(element, { childList: true, subtree: true, attributes: true, attributeFilter: ['slot'] });
+    onCleanup(() => observer.disconnect());
+  });
+
+  const region = (name: SlotName) => (filled()[name] ? <slot name={name} /> : undefined);
+
+  return (
+    <Pane
+      title={props.headline as string}
+      subtitle={props.subtitle as string | undefined}
+      status={props.status as PaneStatus | undefined}
+      focused={flag('focused')}
+      maximized={flag('maximized')}
+      leading={region('leading')}
+      actions={region('actions')}
+      footer={region('footer')}
+      onMaximize={() => dispatch('kai-maximize', { maximized: !flag('maximized') })}
+      onClose={() => dispatch('kai-close')}
+      onSplit={flag('showSplit') ? () => dispatch('kai-split') : undefined}
+      onDock={flag('showDock') ? () => dispatch('kai-dock') : undefined}
+    >
+      <slot />
+    </Pane>
+  );
+});

package/src/elements/popover.tsx

@@ -1,5 +1,6 @@
 import { defineWebComponent } from './define';
-import { Popover } from '../ui/popover';
+import { Popover, type PopoverController } from '../ui/popover';
+import { wireDisclosure } from './disclosure';
 import type { Placement } from '@floating-ui/dom';
 
 interface Props extends Record<string, unknown> {
@@ -7,14 +8,20 @@ interface Props extends Record<string, unknown> {
   placement?: Placement;
   /** Gap in px between the trigger and the panel. */
   gutter?: number;
-  /** Controlled open state. Set as a JS property (`el.open = true`) to drive the
-   *  popover from your app; omit for the default click-to-toggle behaviour. */
+  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open`
+   *  attribute, the element still self-manages on click). Set `el.open = true`,
+   *  or `<kai-popover open>`; listen for `kai-open-change`. */
   open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** Turn the popover off while keeping the trigger mounted (clicks and `show()`
+   *  no longer open it). */
+  disabled?: boolean;
 }
 
 /** Events fired by `<kai-popover>`. */
 interface Events {
-  /** The popover wants to open or close (click, Escape, or outside-click). */
+  /** The popover opened or closed (click, Escape, outside-click, or a method). */
   'kai-open-change': { open: boolean };
 }
 
@@ -39,21 +46,36 @@ interface Events {
  * The default slot is the panel; the `trigger` slot is the control. Clicking the
  * trigger toggles the panel; Escape or an outside click closes it (clicks inside
  * the panel do not). It fires `kai-open-change` with `{ open }` on every change,
- * and accepts an `open` JS property for controlled use.
+ * accepts an `open`/`defaultOpen` JS property, can be `disabled`, and exposes
+ * `show()`/`hide()`/`toggle()` instance methods.
  */
 defineWebComponent<Props, Events>('kai-popover', {
   placement: 'bottom-start',
   gutter: 6,
   open: undefined,
-}, (props, { dispatch, element }) => (
-  <Popover
-    trigger={<slot name="trigger" />}
-    placement={props.placement as Placement}
-    gutter={props.gutter}
-    open={props.open}
-    boundary={() => element}
-    onOpenChange={(open) => dispatch('kai-open-change', { open })}
-  >
-    <slot />
-  </Popover>
-));
+  defaultOpen: undefined,
+  disabled: undefined,
+}, (props, ctx) => {
+  const { flag, element } = ctx;
+  let api: PopoverController | undefined;
+
+  // The standard overlay surface: settable+reflecting `open`, kai-open-change,
+  // show/hide/toggle, disabled-gating. The sole source of kai-open-change — the
+  // primitive's onOpenChange is intentionally NOT wired here to avoid a double
+  // dispatch. See ./disclosure.
+  wireDisclosure(ctx, () => api, () => props.open);
+
+  return (
+    <Popover
+      trigger={<slot name="trigger" />}
+      placement={props.placement as Placement}
+      gutter={props.gutter}
+      defaultOpen={flag('defaultOpen')}
+      disabled={flag('disabled')}
+      controllerRef={(a) => (api = a)}
+      boundary={() => element}
+    >
+      <slot />
+    </Popover>
+  );
+});

package/src/elements/progress-bar.tsx

@@ -0,0 +1,39 @@
+import { ProgressBar, type ProgressTone } from '../ui/progress-bar';
+import { defineWebComponent } from './define';
+
+interface Props extends Record<string, unknown> {
+  /** Current progress value (0..max). Attribute: `value`. */
+  value?: number;
+  /** The value `value` runs to (default 100). Attribute: `max`. */
+  max?: number;
+  /** Optional caption above the track. Attribute: `label`. */
+  label?: string;
+  /** Fill color: `primary` (default), `success`, `warning`, `error`, `info`. Attribute: `tone`. */
+  tone?: string;
+}
+
+/**
+ * `<kai-progress-bar>` — a thin determinate progress bar: a rounded track with a
+ * `bg-primary` fill whose width is `value / max` (clamped to 0..100%). Set `tone`
+ * for a semantic fill hue. Scalar attributes only.
+ *
+ * ```html
+ * <kai-progress-bar value="66"></kai-progress-bar>
+ * <kai-progress-bar value="3" max="5" label="Setup"></kai-progress-bar>
+ * <kai-progress-bar value="60" tone="success"></kai-progress-bar>
+ * ```
+ * Restyle via `::part(track)` / `::part(fill)`.
+ */
+defineWebComponent<Props>('kai-progress-bar', {
+  value: undefined,
+  max: undefined,
+  label: undefined,
+  tone: 'primary',
+}, (props) => (
+  <ProgressBar
+    value={props.value != null ? Number(props.value) : 0}
+    max={props.max != null ? Number(props.max) : undefined}
+    label={props.label as string | undefined}
+    tone={props.tone as ProgressTone | undefined}
+  />
+));

package/src/elements/prompt-dock.tsx

@@ -0,0 +1,81 @@
+import { createSignal, onCleanup, onMount } from 'solid-js';
+import { defineWebComponent } from './define';
+import { PromptDock, type PromptDockAppearance, type PromptDockFrame } from '../ui/prompt-dock';
+
+interface Props extends Record<string, unknown> {
+  /** How the tray frames the input — the SPATIAL inset axis: `inset` (default,
+   *  the classic recessed frame on every side) | `edge` (top/bottom inset only;
+   *  the input sits flush left/right so the lips span the full width) | `none`
+   *  (no inset; the lips attach directly as a plain stack). Attribute: `frame`. */
+  frame?: PromptDockFrame;
+  /** How the tray surface looks — the VISUAL axis, orthogonal to `frame`:
+   *  `soft` (default, sunken surface + border + radius) | `outlined`
+   *  (transparent + border + radius) | `filled` (sunken, no border, + radius) |
+   *  `plain` (bare). Attribute: `appearance`. */
+  appearance?: PromptDockAppearance;
+}
+
+/** The named slots whose occupancy gates a dock lip. An empty `<slot>` is always
+ *  a truthy node, so the facade tracks which are actually filled and only passes
+ *  those regions to the primitive (which renders top/bottom only when truthy). */
+const SLOT_NAMES = ['top', 'bottom'] as const;
+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
+ * 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.
+ *
+ * Slots: the DEFAULT slot is the prompt input (the raised card). `slot="top"` is a
+ * recessed band ABOVE the input (a notice, a hint); `slot="bottom"` is a band BELOW
+ * it (a mode / control row). A lip renders only when its slot is filled — an empty
+ * dock shows just the input, no stray band.
+ *
+ * Styling splits into two orthogonal variant attributes: `frame` (the spatial inset)
+ * and `appearance` (the surface). `::part(tray)` / `::part(top)` / `::part(bottom)`
+ * expose the three regions for outside styling; four `--kai-prompt-dock-*` tokens
+ * tune the chrome (surface / border / radius / inset).
+ *
+ * ```html
+ * <kai-prompt-dock frame="edge" appearance="soft">
+ *   <div slot="top">Working in the docs branch</div>
+ *   <kai-prompt-input></kai-prompt-input>
+ *   <div slot="bottom">Claude Opus 4.8 · 200k context</div>
+ * </kai-prompt-dock>
+ * ```
+ */
+defineWebComponent<Props>('kai-prompt-dock', {
+  frame: 'inset',
+  appearance: 'soft',
+}, (props, { element }) => {
+  // Track which named lip slots are filled. Re-read on child mutations so streamed
+  // / late content lights up its band. An unfilled lip is never rendered (the
+  // primitive gates on a truthy top/bottom, and a bare <slot> is always truthy).
+  const [filled, setFilled] = createSignal<Record<SlotName, boolean>>({ top: false, bottom: false });
+
+  onMount(() => {
+    const read = () => {
+      const next = {} as Record<SlotName, boolean>;
+      for (const name of SLOT_NAMES) next[name] = !!element.querySelector(`:scope > [slot="${name}"]`);
+      setFilled(next);
+    };
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(element, { childList: true });
+    onCleanup(() => observer.disconnect());
+  });
+
+  const lip = (name: SlotName) => (filled()[name] ? <slot name={name} /> : undefined);
+
+  return (
+    <PromptDock
+      frame={props.frame as PromptDockFrame}
+      appearance={props.appearance as PromptDockAppearance}
+      top={lip('top')}
+      bottom={lip('bottom')}
+    >
+      <slot />
+    </PromptDock>
+  );
+});

package/src/elements/prompt-input.tsx

@@ -2,29 +2,18 @@ import { createEffect, createSignal, onMount, onCleanup } from 'solid-js';
 import { defineWebComponent } from './define';
 import { DefaultPromptInput } from './default-input';
 import type { AttachmentData } from '../components/attachments';
-import type { SlashCommandItem } from '../components/slash-command';
 import type { CustomAction } from './chat-types';
-
-/** Parse a single light-DOM `<kai-slash-command>` element into a SlashCommandItem.
- *  Attribute mapping:
- *   - `command`     → SlashCommandItem.id       (required; empty string fallback)
- *   - textContent   → SlashCommandItem.label    (primary); `label` attr as fallback
- *   - `description` → SlashCommandItem.description
- *   - `category`    → SlashCommandItem.category
- */
-export function parseKaiSlashCommandElement(n: Element): SlashCommandItem {
-  return {
-    id: n.getAttribute('command') ?? '',
-    label: n.textContent?.trim() || n.getAttribute('label') || n.getAttribute('command') || '',
-    description: n.getAttribute('description') ?? undefined,
-    category: n.getAttribute('category') ?? undefined,
-  };
-}
+import type { TriggerDef, ComposerChange } from '../components/composer';
+import { type ComposerDoc, type EntityRef, normalizeValue, serializeToText, entitiesOf } from '../primitives/composer-model';
 
 interface Props extends Record<string, unknown> {
-  /** Controlled value of the input. When set, the host owns the text and must
-   *  update it on `kai-value-change`; leave unset for uncontrolled behavior. */
-  value?: string;
+  /** Value of the input, as a JS property. A **string** is the controlled text
+   *  mirror (the host owns it and updates on `kai-value-change`). A **ComposerDoc**
+   *  (array of text/entity segments) is a one-time **seed** that pre-populates
+   *  pills (skills/agents/plugins); the user then edits freely. Leave unset for
+   *  uncontrolled behavior. `kai-submit`/`kai-value-change` always emit `value`
+   *  as the flattened string (back-compat) plus the structured `doc` + `entities`. */
+  value?: string | ComposerDoc;
   /** Placeholder text shown in the empty input. */
   placeholder?: string;
   /** Disable the input and submit button entirely (non-interactive). */
@@ -38,13 +27,6 @@ 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';
-  /** Slash commands — when set, typing `/` opens the command palette. Set as a
-   *  JS property. */
-  slashCommands?: SlashCommandItem[];
-  /** Command ids to highlight as active. */
-  slashActiveIds?: string[];
-  /** Single-line palette rows. */
-  slashCompact?: boolean;
   /** Show a Search (Globe) button in the left toolbar; clicking it fires a
    *  `search` event. */
   search?: boolean;
@@ -54,22 +36,45 @@ interface Props extends Record<string, unknown> {
   /** When set and `loading` is true, the send button is replaced by a Stop
    *  button (square icon, "Stop" aria-label). Clicking it fires `kai-stop`. */
   stoppable?: 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';
+  /** When `false`, hides the built-in paperclip attach button even though the
+   *  element otherwise supports attachments. Use this when a `+` menu in
+   *  `toolbar-start` already exposes "Add files", to avoid a duplicate control.
+   *  Defaults to `true`. */
+  attach?: boolean;
   /** Attachments to seed the input with (so a consumer can pre-populate staged
    *  files without an upload). Set as a JS property; the element then manages its
    *  own attachment state from there (add via the paperclip, remove per chip). */
   attachments?: AttachmentData[];
+  /** Rich entity triggers — each `{ char, kind, items }` opens a caret-anchored
+   *  menu that inserts an atomic pill. Convention: `/` → skills, `@` → agents
+   *  (plugins are the grouping/provenance of those items). Set as a JS property. */
+  triggers?: TriggerDef[];
+  /** Default icon per entity kind (kind → image URL/data-URI) for pills/menu items
+   *  without their own `icon`. Overrides the built-in agent/plugin glyphs. JS property. */
+  kindIcons?: Record<string, string>;
 }
 
 /** Events fired by `<kai-prompt-input>`. */
 interface Events {
-  /** The user submitted the prompt (Enter or send button) with its attachments. */
-  'kai-submit': { value: string; attachments: AttachmentData[] };
-  /** The input text changed (fires on every keystroke). */
-  'kai-value-change': { value: string };
+  /** The user submitted the prompt (Enter or send button). `value` is the
+   *  flattened text (back-compat); `doc` is the structured document and
+   *  `entities` the inserted pills (skills/agents) for downstream expansion. */
+  'kai-submit': { value: string; doc: ComposerDoc; entities: EntityRef[]; attachments: AttachmentData[] };
+  /** The input changed (fires on every edit). Carries the flattened `value`
+   *  plus the structured `doc` + `entities`. */
+  'kai-value-change': { value: string; doc: ComposerDoc; entities: EntityRef[] };
+  /** The staged attachments changed — a file was added (via the paperclip) or
+   *  removed (per-chip ×). Carries the full current list so a consumer can react
+   *  in real time (validate, show upload progress, toggle the send button). */
+  'kai-attachments-change': { attachments: AttachmentData[] };
   /** A suggestion was clicked while `suggestion-mode="fill"`. */
   'kai-suggestion-click': { value: string };
-  /** A slash command was chosen from the palette. */
-  'kai-slash-select': { command: SlashCommandItem };
   /** The Search (Globe) toolbar button was clicked. */
   'kai-search': Record<string, never>;
   /** The Voice (Mic) toolbar button was clicked. */
@@ -88,15 +93,16 @@ defineWebComponent<Props, Events>('kai-prompt-input', {
   loading: false,
   suggestions: undefined,
   suggestionMode: 'submit',
-  slashCommands: undefined,
-  slashActiveIds: undefined,
-  slashCompact: false,
   search: false,
   voice: false,
   stoppable: false,
+  submit: 'always',
+  attach: true,
   attachments: undefined,
-}, (props, { dispatch, flag, element }) => {
-  const [internal, setInternal] = createSignal(props.value ?? '');
+  triggers: undefined,
+  kindIcons: undefined,
+}, (props, { dispatch, flag, element, expose }) => {
+  const [internal, setInternal] = createSignal<string | ComposerDoc>(props.value ?? '');
   // Seed staged attachments from the `attachments` property; the element manages
   // its own state from there (paperclip adds, per-chip remove deletes).
   const [attachments, setAttachments] = createSignal<AttachmentData[]>(props.attachments ?? []);
@@ -106,11 +112,10 @@ defineWebComponent<Props, Events>('kai-prompt-input', {
     if (props.attachments) setAttachments(props.attachments);
   });
 
-  // Read declarative <kai-action> and <kai-slash-command> children from light DOM —
-  // same pattern as kai-message. Shadow DOM with no <slot> suppresses them visually;
-  // they are invisible data carriers. One MutationObserver covers both element types.
+  // Read declarative <kai-action> children from light DOM — same pattern as
+  // kai-message. Shadow DOM with no <slot> suppresses them visually; they are
+  // invisible data carriers.
   const [toolbarActions, setToolbarActions] = createSignal<CustomAction[]>([]);
-  const [slottedSlashCommands, setSlottedSlashCommands] = createSignal<SlashCommandItem[]>([]);
   onMount(() => {
     const readActions = () => {
       const nodes = [...element.querySelectorAll('kai-action')];
@@ -121,22 +126,45 @@ defineWebComponent<Props, Events>('kai-prompt-input', {
         tooltip: n.getAttribute('tooltip') ?? undefined,
       })));
     };
-    const readSlashCommands = () => {
-      const nodes = [...element.querySelectorAll('kai-slash-command')];
-      setSlottedSlashCommands(nodes.map(parseKaiSlashCommandElement));
-    };
-    const readAll = () => { readActions(); readSlashCommands(); };
-    readAll();
-    const observer = new MutationObserver(readAll);
+    readActions();
+    const observer = new MutationObserver(readActions);
     observer.observe(element, { childList: true, attributes: true, subtree: true });
     onCleanup(() => observer.disconnect());
   });
 
-  const current = () => props.value ?? internal();
+  // A string `value` is controlled (the host owns it). A ComposerDoc `value` is a
+  // one-time seed: it lives in `internal` and the user's edits (which arrive as
+  // strings) replace it there, so the seed never fights the edits.
+  const current = (): string | ComposerDoc =>
+    typeof props.value === 'string' ? props.value : internal();
+
+  // Latest structured change from the composer (doc + entities). Captured before
+  // the string value-change fires (the bridge calls onComposerChange first), so
+  // the dispatched events can carry the doc. Reset to a text-only doc when a value
+  // is set that didn't come from the composer (e.g. a suggestion fill).
+  let lastChange: ComposerChange = { doc: [], text: '', entities: [] };
 
-  const handleChange = (v: string) => { setInternal(v); dispatch('kai-value-change', { value: v }); };
+  // Seed from a ComposerDoc `value`: push it into `internal` (so `current()`
+  // reflects the seed) and into `lastChange` (so a submit-WITHOUT-edit still
+  // carries the seeded doc + entities). Re-runs only when `value` is reassigned.
+  createEffect(() => {
+    const v = props.value;
+    if (v != null && typeof v !== 'string') {
+      const doc = normalizeValue(v);
+      setInternal(doc);
+      lastChange = { doc, text: serializeToText(doc), entities: entitiesOf(doc) };
+    }
+  });
+
+  const handleChange = (v: string) => {
+    setInternal(v);
+    if (v !== lastChange.text) lastChange = { doc: normalizeValue(v), text: v, entities: [] };
+    dispatch('kai-value-change', { value: v, doc: lastChange.doc, entities: lastChange.entities });
+  };
   const handleSubmit = () => {
-    dispatch('kai-submit', { value: current(), attachments: attachments() });
+    // `value` is always the flattened string (back-compat); a seeded doc is
+    // serialized. The structured `doc`/`entities` carry the pills.
+    dispatch('kai-submit', { value: serializeToText(normalizeValue(current())), doc: lastChange.doc, entities: lastChange.entities, attachments: attachments() });
     setAttachments([]);
   };
   const handleSuggestionClick = (v: string) => {
@@ -145,16 +173,36 @@ defineWebComponent<Props, Events>('kai-prompt-input', {
       dispatch('kai-suggestion-click', { value: v });
     } else {
       // Default: behave as if the user typed the suggestion and pressed submit.
-      dispatch('kai-submit', { value: v, attachments: attachments() });
+      dispatch('kai-submit', { value: v, doc: normalizeValue(v), entities: [], attachments: attachments() });
       setAttachments([]);
     }
   };
 
-  // Prop slash commands take precedence; slotted children are appended after.
-  const allSlashCommands = () => [
-    ...(props.slashCommands ?? []),
-    ...slottedSlashCommands(),
-  ];
+  // ── Imperative API (instance methods on the host) ──────────────────────────
+  // The input half of the interaction surface; counterpart to the kai-* events.
+  expose({
+    /** Focus the text editor inside the shadow root (not the hidden file input). */
+    focus: (options?: FocusOptions) => {
+      const root = element.shadowRoot;
+      const target =
+        root?.querySelector<HTMLElement>('[contenteditable]:not([contenteditable="false"]), textarea') ??
+        root?.querySelector<HTMLElement>('input:not([type="file"])');
+      target?.focus(options);
+    },
+    /** Blur the focused input control. */
+    blur: () =>
+      (element.shadowRoot?.activeElement as HTMLElement | null)?.blur(),
+    /** Clear the text and any staged attachments (fires kai-value-change /
+     *  kai-attachments-change so a controlled consumer can react). */
+    clear: () => {
+      handleChange('');
+      if (attachments().length) { setAttachments([]); dispatch('kai-attachments-change', { attachments: [] }); }
+    },
+    /** Send the current value programmatically — same path as Enter / the send
+     *  button (fires kai-submit, then clears staged attachments). Named `send`,
+     *  not `submit`, to avoid colliding with the `submit` prop. */
+    send: () => handleSubmit(),
+  });
 
   return (
     <DefaultPromptInput
@@ -163,22 +211,23 @@ defineWebComponent<Props, Events>('kai-prompt-input', {
       disabled={flag('disabled')}
       loading={flag('loading')}
       stoppable={flag('stoppable')}
+      submit={props.submit as 'always' | 'auto'}
+      attach={flag('attach')}
       suggestions={props.suggestions}
       attachments={attachments()}
-      slashCommands={allSlashCommands().length ? allSlashCommands() : undefined}
-      slashActiveIds={props.slashActiveIds}
-      slashCompact={flag('slashCompact')}
       search={flag('search')}
       voice={flag('voice')}
       toolbarActions={toolbarActions()}
+      triggers={props.triggers}
+      kindIcons={props.kindIcons as Record<string, string> | undefined}
+      onComposerChange={(c) => { lastChange = c; }}
       onValueChange={handleChange}
       onSubmit={handleSubmit}
       onSuggestionClick={handleSuggestionClick}
-      onAttachmentsChange={setAttachments}
+      onAttachmentsChange={(a) => { setAttachments(a); dispatch('kai-attachments-change', { attachments: a }); }}
       onSearch={() => dispatch('kai-search')}
       onVoice={() => dispatch('kai-voice')}
       onStop={() => dispatch('kai-stop')}
-      onSlashSelect={(command) => dispatch('kai-slash-select', { command })}
       onAction={(id) => dispatch('kai-toolbar-action', { action: id })}
     />
   );