@kitn.ai/ui 0.17.0 → 0.18.1

package/README.md

@@ -33,7 +33,7 @@ npm install solid-js
 Build the bundle, then import it as a side-effect (it registers the custom elements):
 
 ```bash
-npm run build   # emits dist/kitn-chat.es.js
+npm run build   # emits dist/kai.es.js
 ```
 
 ```html
@@ -70,14 +70,14 @@ The element bundle is a self-contained ES module — load it directly from [jsDe
 
 ```html
 <script type="module">
-  import 'https://cdn.jsdelivr.net/npm/@kitn.ai/ui/dist/kitn-chat.es.js';
-  // …or unpkg: import 'https://unpkg.com/@kitn.ai/ui/dist/kitn-chat.es.js';
+  import 'https://cdn.jsdelivr.net/npm/@kitn.ai/ui/dist/kai.es.js';
+  // …or unpkg: import 'https://unpkg.com/@kitn.ai/ui/dist/kai.es.js';
 </script>
 
 <kai-chat></kai-chat>
 ```
 
-The URLs above track the **latest** release — handy for trying things out. **For production, pin an exact version** (e.g. `@kitn.ai/ui@0.16.0/dist/kitn-chat.es.js`): pinned URLs are immutable and cached far more aggressively, and — since this package is pre-1.0 — pinning shields you from breaking changes in a future minor release. SolidJS and the kit's CSS are bundled in, and the lazy code-highlighting chunks load from the same CDN on demand. To override design tokens, also include `theme.css`:
+The URLs above track the **latest** release — handy for trying things out. **For production, pin an exact version** (e.g. `@kitn.ai/ui@0.16.0/dist/kai.es.js`): pinned URLs are immutable and cached far more aggressively, and — since this package is pre-1.0 — pinning shields you from breaking changes in a future minor release. SolidJS and the kit's CSS are bundled in, and the lazy code-highlighting chunks load from the same CDN on demand. To override design tokens, also include `theme.css`:
 
 ```html
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@kitn.ai/ui/theme.css">
@@ -266,6 +266,29 @@ You can trigger either option from the streaming completion (auto-read replies)
 
 > **Speech-to-text** (the other direction) is already built in — the kit ships a `VoiceInput` component for capturing microphone input. See Storybook (`npm run dev`).
 
+## State helpers & hooks
+
+`@kitn.ai/ui/state` ships immutable helpers (`appendMessage`, `upsertMessage`, `updateMessage`, `removeMessage`, `appendContent`) and a streaming handle (`createAssistantStream`) so you don't hand-roll array mutations. React apps get `useKaiChat` (from `@kitn.ai/ui/react`); SolidJS apps get `createKaiChat` (from `@kitn.ai/ui`). Both return a `bind` object to spread directly onto the element:
+
+```tsx
+import { Chat, useKaiChat } from '@kitn.ai/ui/react';
+import { createAssistantStream } from '@kitn.ai/ui/state';
+
+function App() {
+  const chat = useKaiChat({
+    async onSubmit({ value }) {
+      chat.append({ id: crypto.randomUUID(), role: 'user', content: value });
+      const s = chat.streamAssistant();
+      for await (const part of backend(value)) s.appendText(part);
+      s.done();
+    },
+  });
+  return <Chat {...chat.bind} />;
+}
+```
+
+Each hook instance owns its own message list — instantiate multiple times for multiple independent chats on one page. Full API: [ui.kitn.ai/guides/state-and-hooks/](https://ui.kitn.ai/guides/state-and-hooks/).
+
 ## Code highlighting (optional, on-demand)
 
 Syntax highlighting uses [Shiki](https://shiki.style) and is wired to be as light as possible:
@@ -358,7 +381,7 @@ A set of runnable examples and a hosted component playground are included in the
 The composable showcase demonstrates every individual element in one page. Build the package first, then serve from the repo root:
 
 ```bash
-npm run build     # produces dist/kitn-chat.es.js
+npm run build     # produces dist/kai.es.js
 npm run examples  # static server at http://localhost:8000
 ```
 

package/dist/components/artifact.d.ts

@@ -3,13 +3,42 @@ import { FileTreeFile } from './file-tree';
 export type ArtifactTab = 'preview' | 'code';
 /** A file the artifact can preview + show source for. */
 export type ArtifactFile = FileTreeFile;
+/** Imperative handle exposed via `controllerRef` — surfaces the artifact's latent
+ *  toolbar capabilities (history back/forward/reload/home, programmatic navigate,
+ *  file selection, open-in-new-tab, maximize/restore) so the `<kai-artifact>`
+ *  facade can forward them as instance methods. Each delegates to the SAME internal
+ *  handler the toolbar buttons use, so every existing event still fires. */
+export interface ArtifactController {
+    /** Go back in the artifact's own history stack (no-op when there's no prior entry). */
+    back(): void;
+    /** Go forward in the history stack (no-op when there's no forward entry). */
+    forward(): void;
+    /** Force-reload the current preview url (also re-renders an inline PDF). */
+    reload(): void;
+    /** Navigate to the `src` home url (no-op when there's no `src`). */
+    home(): void;
+    /** Push + load a url in the preview (the path-field submit path). */
+    navigate(url: string): void;
+    /** Select a file by path: highlights the tree, shows its source, navigates the preview. */
+    selectFile(path: string): void;
+    /** Open the current url in a new browser tab (no-op when there's no concrete url). */
+    openExternal(): void;
+    /** Enter the maximized view-state (fires onMaximizeChange/kai-maximize-change). */
+    maximize(): void;
+    /** Exit the maximized view-state. */
+    restore(): void;
+}
 export interface ArtifactProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, 'onSelect'> {
     /** URL the preview iframe frames. */
     src?: string;
     /** Files for the Code tab's tree (+ each file's preview `url`). */
     files?: ArtifactFile[];
-    /** Active tab. Default `preview`. */
+    /** Controlled active tab — when set, the artifact follows it (re-asserted on
+     *  every change). When undefined the tab is uncontrolled (see `defaultTab`). */
     tab?: ArtifactTab;
+    /** Uncontrolled INITIAL tab (used only when `tab` is undefined). The user can
+     *  then freely switch tabs; defaults to `preview`. */
+    defaultTab?: ArtifactTab;
     /** Selected file path (syncs tree highlight + Code source + preview). */
     activeFile?: string;
     /** iframe `sandbox` override. Default `allow-scripts allow-forms`. */
@@ -44,6 +73,15 @@ export interface ArtifactProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>,
     standalone?: boolean;
     /** Make the path field read-only (visible, nav-tracking, non-editable). */
     readonlyPath?: boolean;
+    /** Friendly address shown in the path field INSTEAD of the real current url
+     *  (read-only, non-navigable). Use when the framed url is not consumer-facing
+     *  (e.g. a `data:` blob) so a clean address is shown instead of leaking it.
+     *  Unset = show the real url (editable per `readonlyPath`). */
+    displayUrl?: string;
+    /** Receive the imperative controller once mounted. The `<kai-artifact>` facade
+     *  forwards these as element methods (back/forward/reload/home/navigate/
+     *  selectFile/openExternal/maximize/restore). */
+    controllerRef?: (controller: ArtifactController) => void;
 }
 /** True when `url` should render as a PDF: a matching `files` entry is typed
  *  `'pdf'`, or the URL path (query/hash stripped) ends in `.pdf`. */

package/dist/components/attachment-types.d.ts

@@ -0,0 +1,12 @@
+/** A message attachment descriptor. Pure type — kept JSX-free for the
+ *  framework-neutral consumers (state core, React hook typecheck). */
+export interface AttachmentData {
+    id: string;
+    type: 'file' | 'source-document';
+    filename?: string;
+    mediaType?: string;
+    url?: string;
+    title?: string;
+}
+export type AttachmentMediaCategory = 'image' | 'video' | 'audio' | 'document' | 'source' | 'unknown';
+export type AttachmentVariant = 'grid' | 'inline' | 'list';

package/dist/components/attachments.d.ts

@@ -1,14 +1,6 @@
 import { JSX } from 'solid-js';
-export interface AttachmentData {
-    id: string;
-    type: 'file' | 'source-document';
-    filename?: string;
-    mediaType?: string;
-    url?: string;
-    title?: string;
-}
-export type AttachmentMediaCategory = 'image' | 'video' | 'audio' | 'document' | 'source' | 'unknown';
-export type AttachmentVariant = 'grid' | 'inline' | 'list';
+import { AttachmentData, AttachmentMediaCategory, AttachmentVariant } from './attachment-types';
+export type { AttachmentData, AttachmentMediaCategory, AttachmentVariant } from './attachment-types';
 export declare const getMediaCategory: (data: AttachmentData) => AttachmentMediaCategory;
 export declare const getAttachmentLabel: (data: AttachmentData) => string;
 interface AttachmentsContextValue {

package/dist/components/card.d.ts

@@ -16,6 +16,25 @@ export interface CardProps extends JSX.HTMLAttributes<HTMLDivElement> {
     /** Stable id for the heading (so composing cards can `aria-labelledby` it).
      *  Auto-generated when omitted. */
     headingId?: string;
+    /** Render a dismiss (×) button that hides the card and calls `onDismiss`.
+     *  Opt-in, OFF by default — the contract cards never set it, so they are
+     *  unaffected. */
+    dismissible?: boolean;
+    /** Called after the card is dismissed via its ×. */
+    onDismiss?: () => void;
+    /** Render the whole card as a link (`<a>`). Wins over `clickable`. */
+    href?: string;
+    /** `target` for the `href` anchor. */
+    target?: string;
+    /** `rel` for the `href` anchor (default `noopener noreferrer` when `target="_blank"`). */
+    rel?: string;
+    /** Make the whole card behave like a button: `role="button"`, a tabindex, and
+     *  Enter/Space activation, firing `onCardClick`. Ignored when `href` is set.
+     *  A clickable/href card must NOT also contain footer action buttons — that
+     *  nests interactive elements. Use `actions` OR clickable, never both. */
+    clickable?: boolean;
+    /** Called when a `clickable` (or `href`) card is activated (click, or Enter/Space). */
+    onCardClick?: (event: MouseEvent | KeyboardEvent) => void;
 }
 /**
  * `Card` — the shared presentational chrome every native card composes from:
@@ -24,5 +43,13 @@ export interface CardProps extends JSX.HTMLAttributes<HTMLDivElement> {
  * "never a broken/partial card" rule). It is intentionally chrome-only: it reads
  * no `CardContext` and emits no `CardEvent` — the cards that compose it (e.g.
  * `kai-form`) own the contract interaction.
+ *
+ * The optional `dismissible` / `href` / `clickable` behaviors are all OFF by
+ * default, so the contract cards (which set none of them) keep their original
+ * presentational behavior unchanged.
+ *
+ * a11y: a `clickable` or `href` card MUST NOT also contain footer action buttons
+ * — that nests interactive controls inside a button/link. Use `actions` OR
+ * make the card clickable, never both.
  */
 export declare function Card(props: CardProps): JSX.Element;

package/dist/components/chain-of-thought.d.ts

@@ -1,4 +1,4 @@
-import { JSX } from 'solid-js';
+import { JSX, Accessor } from 'solid-js';
 export interface ChainOfThoughtItemProps extends JSX.HTMLAttributes<HTMLDivElement> {
     children: JSX.Element;
 }
@@ -24,6 +24,82 @@ export interface ChainOfThoughtStepProps {
     children: JSX.Element;
     class?: string;
     isLast?: boolean;
+    /** Controlled open state. When provided, the step's Collapsible is driven by
+     *  this value (the parent owns it — used by the Accordion model below). When
+     *  OMITTED the step stays uncontrolled, preserving the original behaviour
+     *  (every step independently toggleable, starting closed). */
+    open?: boolean;
+    /** Called with the desired next open state when the user clicks the trigger.
+     *  Only meaningful when `open` is also provided (controlled mode); the parent
+     *  Accordion routes this through its open-set handler. */
+    onOpenChange?: (open: boolean) => void;
 }
 declare function ChainOfThoughtStep(props: ChainOfThoughtStepProps): JSX.Element;
-export { ChainOfThought, ChainOfThoughtStep, ChainOfThoughtTrigger, ChainOfThoughtContent, ChainOfThoughtItem, };
+/** Open-mode: `multiple` (any number of steps open at once — the historical
+ *  default) or `single` (at most one open; opening a step closes the others). */
+export type ChainOfThoughtType = 'single' | 'multiple';
+/**
+ * A reasoning step descriptor. `id` is an OPTIONAL stable key — the Accordion's
+ * open-set keys use `step.id` when present, else `String(index)`. So a consumer
+ * who wants to drive `value`/`defaultValue` (or read `kai-value-change`) by a
+ * meaningful key should set `id`; otherwise the step's position is its key.
+ */
+export interface ChainOfThoughtStepData {
+    /** The step's heading (the always-visible trigger). */
+    label: string;
+    /** Optional expandable detail. */
+    content?: string;
+    /** Optional stable key for the open-set/value model (defaults to the index). */
+    id?: string;
+}
+/**
+ * Imperative handle exposed via `controllerRef` so the `<kai-chain-of-thought>`
+ * facade can drive/observe the Accordion's open set. Index-based to match the
+ * `expand(index?)`/`collapse(index?)`/`toggle(index?)` method signatures; the
+ * controller resolves the index → step key internally. All setters flow through
+ * the same open-set mutate path as user clicks, so they all emit
+ * `kai-value-change` via `onValueChange`.
+ */
+export interface ChainOfThoughtController {
+    /** Current open keys, normalised per `type` (string in single, string[] in multiple). */
+    value: Accessor<string | string[]>;
+    /** Open one step by index, or ALL steps when `index` is omitted. */
+    expand: (index?: number) => void;
+    /** Close one step by index, or ALL steps when `index` is omitted. */
+    collapse: (index?: number) => void;
+    /** Flip one step's open state by index. */
+    toggle: (index?: number) => void;
+}
+export interface ChainOfThoughtAccordionProps {
+    /** The reasoning steps to render. */
+    steps: ChainOfThoughtStepData[];
+    /** Open mode. Default `multiple` (the historical behaviour). */
+    type?: ChainOfThoughtType;
+    /** Controlled open step key(s). When provided it WINS over internal state. */
+    value?: string | string[];
+    /** Uncontrolled initial open step key(s). Seeds the internal open-set. */
+    defaultValue?: string | string[];
+    /** Fired whenever the open set changes (user click OR a controller method).
+     *  The single emit point — the facade turns this into `kai-value-change`. The
+     *  payload is a string in `single` mode, a string[] in `multiple` mode. */
+    onValueChange?: (value: string | string[]) => void;
+    /** Receive the imperative controller once set up (Pattern C). */
+    controllerRef?: (api: ChainOfThoughtController) => void;
+    class?: string;
+}
+/**
+ * The full Accordion-model root used by `<kai-chain-of-thought>`. Lifts each
+ * step's open state into a controlled/uncontrolled open-set:
+ *  - seeded from `defaultValue` (normalised string|string[] → Set);
+ *  - when `value` is provided it WINS (controlled);
+ *  - a trigger click updates the set respecting `single` vs `multiple` and emits
+ *    via `onValueChange` — in single mode opening a step closes the others;
+ *  - each step's Collapsible is driven (controlled) by its membership in the set.
+ *
+ * With NO new props (type defaults to `multiple`, no value/defaultValue), every
+ * step starts closed and is independently toggleable — identical to the old
+ * behaviour, just with the open state lifted here so methods/events can observe
+ * and drive it.
+ */
+declare function ChainOfThoughtAccordion(props: ChainOfThoughtAccordionProps): JSX.Element;
+export { ChainOfThought, ChainOfThoughtStep, ChainOfThoughtTrigger, ChainOfThoughtContent, ChainOfThoughtItem, ChainOfThoughtAccordion, };

package/dist/components/chat-scope-picker.d.ts

@@ -1,3 +1,4 @@
+import { DropdownController } from '../ui/dropdown';
 import { SearchFilters } from '../types';
 export interface ChatScopePickerProps {
     currentLabel: string;
@@ -5,5 +6,11 @@ export interface ChatScopePickerProps {
     availableAuthors?: string[];
     availableTags?: string[];
     class?: string;
+    /** Initial open state of the dropdown (uncontrolled seed). */
+    defaultOpen?: boolean;
+    /** Disable the trigger — click/keyboard no longer open the dropdown. */
+    disabled?: boolean;
+    /** Receive the dropdown's open controller (forwarded from the inner Dropdown). */
+    controllerRef?: (api: DropdownController) => void;
 }
 export declare function ChatScopePicker(props: ChatScopePickerProps): import("solid-js").JSX.Element;

package/dist/components/chat-thread.d.ts

@@ -1,6 +1,7 @@
+import { ComposerDoc } from '../primitives/composer-model';
 import { AttachmentData } from './attachments';
 import { MessageActionDetail } from '../primitives/message-feedback';
-import { SlashCommandItem } from './slash-command';
+import { TriggerDef } from './composer';
 import { ChatMessage } from '../elements/chat-types';
 import { ProseSize } from '../primitives/chat-config';
 import { ModelOption } from '../types';
@@ -18,9 +19,10 @@ export interface ChatThreadProps {
      *  content, and optional reasoning/tools/attachments/actions. Set as a JS
      *  property (`el.messages = [...]`). */
     messages: ChatMessage[];
-    /** Controlled value of the input. When set, the host owns the input text and
-     *  must update it on `kai-value-change`; leave unset for uncontrolled behavior. */
-    value?: string;
+    /** Value of the input. A **string** is controlled (the host owns the text and
+     *  updates it on `kai-value-change`). A **ComposerDoc** is a one-time seed that
+     *  pre-populates pills; the user then edits freely. Leave unset for uncontrolled. */
+    value?: string | ComposerDoc;
     /** Placeholder text shown in the empty input. */
     placeholder?: string;
     /** When true, shows the loading/streaming state and disables submit (use while
@@ -62,17 +64,29 @@ export interface ChatThreadProps {
     headerStart?: boolean;
     /** Whether the host has `slot="header-end"` content (right of the controls). */
     headerEnd?: boolean;
+    /** REPLACE — full custom header in place of the built-in title/model/context bar. */
+    headerFull?: boolean;
+    /** INJECT — left sidebar column (e.g. a conversation list / your own nav). */
+    sidebar?: boolean;
+    /** REPLACE — custom zero-state rendered in the message area while the thread is empty (replaces the empty message list only; the composer and its suggestions still render). */
+    empty?: boolean;
+    /** REPLACE — full custom composer in place of the built-in prompt input. The
+     *  projected content wires its own submit (the data-flow boundary). */
+    composer?: boolean;
+    /** INJECT — accessory row just above the composer (e.g. extra actions). */
+    composerActions?: boolean;
+    /** INJECT — footer row below the composer (disclaimers, token meter, …). */
+    footer?: boolean;
     /** Show a Search (Globe) button in the input toolbar; fires a `search` event. */
     search?: boolean;
     /** Show a Voice (Mic) button in the input toolbar; fires a `voice` event. */
     voice?: boolean;
-    /** Slash commands — when set, typing `/` in the input opens the command
-     *  palette and fires `kai-slash-select`. Set as a JS property. */
-    slashCommands?: SlashCommandItem[];
-    /** Command ids to highlight as active in the palette. */
-    slashActiveIds?: string[];
-    /** Single-line palette rows. */
-    slashCompact?: boolean;
+    /** Rich entity triggers — each `{ char, kind, items }` opens a caret-anchored
+     *  menu that inserts an atomic pill (`/` skills, `@` agents/plugins). Set as a
+     *  JS property; forwarded to the input. */
+    triggers?: TriggerDef[];
+    /** Default icon per entity kind (kind → image src) for pills/menu items. */
+    kindIcons?: Record<string, string>;
     /** Whether each message's action bar is always visible (`'always'`, default)
      *  or only revealed on hover of that message row (`'hover'`). */
     actionsReveal?: 'always' | 'hover';
@@ -81,11 +95,22 @@ export interface ChatThreadProps {
         value: string;
         attachments: AttachmentData[];
     }) => void;
+    onAttachmentsChange?: (attachments: AttachmentData[]) => void;
     onSuggestionClick?: (value: string) => void;
     onModelChange?: (modelId: string) => void;
     onMessageAction?: (detail: MessageActionDetail) => void;
     onSearch?: () => void;
     onVoice?: () => void;
-    onSlashSelect?: (command: SlashCommandItem) => void;
+    /** Receive the imperative controller once mounted. The kai-chat facade forwards
+     *  these as element methods (focus/clear/send/scrollToBottom). */
+    controllerRef?: (controller: ChatThreadController) => void;
+}
+/** Imperative handle exposed via `controllerRef` — the input half of the chat's
+ *  interaction surface, forwarded onto `<kai-chat>` as instance methods. */
+export interface ChatThreadController {
+    focus(options?: FocusOptions): void;
+    clear(): void;
+    send(): void;
+    scrollToBottom(behavior?: ScrollBehavior): void;
 }
 export declare function ChatThread(props: ChatThreadProps): import("solid-js").JSX.Element;

package/dist/components/choice-card.d.ts

@@ -47,6 +47,21 @@ export declare function resolveOtherConfig(allowOther: ChoiceAllowOther | undefi
 export declare function nextEnabledIndex(options: ChoiceOption[], from: number, dir: 1 | -1): number;
 /** The first non-disabled option index (the initial roving tab stop), or -1. */
 export declare function firstEnabledIndex(options: ChoiceOption[]): number;
+/** Imperative handle exposed via `controllerRef` — surfaces the choice card's
+ *  latent selection/submit/dismiss capabilities so the `<kai-choice>` facade can
+ *  forward them as instance methods (focus/select/send/dismiss/reopen). */
+export interface ChoiceController {
+    /** Focus the radiogroup roving tab stop (or the Other input when selected). */
+    focus(options?: FocusOptions): void;
+    /** Select an option by id locally (no emit) — same as a row click. */
+    select(optionId: string): void;
+    /** Submit the current selection — emits the `action` verb + resolves single-shot. */
+    send(): void;
+    /** Dismiss the card — emits `dismiss` + optimistically collapses to the stub. */
+    dismiss(): void;
+    /** Re-open a dismissed card from its stub — emits `reopen`. */
+    reopen(): void;
+}
 export interface ChoiceCardProps {
     /** The choice definition (CardEnvelope.data). */
     data?: ChoiceCardData;
@@ -62,6 +77,17 @@ export interface ChoiceCardProps {
     class?: string;
     /** When set, render the chromed read-only view instead of the interactive radiogroup. */
     resolution?: CardResolution;
+    /** Controlled selection (option id). When set, the consumer owns the current pick. */
+    value?: string;
+    /** Option id to pre-select on mount (uncontrolled seed). */
+    defaultValue?: string;
+    /** Disable the whole radiogroup + Submit (e.g. while the agent is busy). */
+    disabled?: boolean;
+    /** Fires when the selection changes BEFORE submit (row click or select()). */
+    onValueChange?: (value: string) => void;
+    /** Receive the imperative controller once mounted. The `<kai-choice>` facade
+     *  forwards these as element methods (focus/select/send/dismiss/reopen). */
+    controllerRef?: (controller: ChoiceController) => void;
 }
 /**
  * `ChoiceCard` — a single-select "pick one of N rich options" card (plans, products,

package/dist/components/coachmark.d.ts

@@ -0,0 +1,49 @@
+import { Accessor, JSX } from 'solid-js';
+import { Placement } from '@floating-ui/dom';
+/** Imperative open controller, handed to the kai-coachmark facade via
+ *  `controllerRef` so it can drive/observe open state with `wireDisclosure`. */
+export interface CoachmarkController {
+    open: Accessor<boolean>;
+    setOpen: (v: boolean) => void;
+}
+export interface CoachmarkProps {
+    /** The anchor/trigger (the default slot). The bubble is positioned against it. */
+    children?: JSX.Element;
+    /** The bubble body text (the `content` slot). */
+    content?: JSX.Element;
+    /** The bold title. NOT `title` — that is a reserved IDL attr (see define.tsx). */
+    headline?: JSX.Element;
+    /** A small badge pill (e.g. "New"). */
+    badge?: JSX.Element;
+    /** Floating placement relative to the anchor. Defaults to `'bottom'`. */
+    placement?: Placement;
+    /** Color tone: `primary` (default, theme accent), `info` (blue), `success`
+     *  (green), `warning` (amber), or `error` (red) — reusing the kit's tool hues. */
+    tone?: 'primary' | 'info' | 'success' | 'warning' | 'error';
+    /** Controlled open state. When set, the component never changes it itself;
+     *  drive it from `onOpenChange`. Omit for uncontrolled (internal) state. */
+    open?: boolean;
+    /** Initial open state when uncontrolled. */
+    defaultOpen?: boolean;
+    /** Fires whenever open wants to change (the × button / a method). */
+    onOpenChange?: (open: boolean) => void;
+    /** Dismiss intent: the × button. */
+    onDismiss?: () => void;
+    /** Render the arrow that points at the anchor. Defaults to `true`; set `false`
+     *  for a plain bubble with no pointer. */
+    arrow?: boolean;
+    /** Receive the open controller once mounted. */
+    controllerRef?: (api: CoachmarkController) => void;
+}
+/**
+ * Coachmark is the presentational onboarding hint: a tinted bubble with an arrow,
+ * anchored to a trigger. It wraps the anchor (the default slot) and positions the
+ * bubble against it with `usePosition` (the shared Floating UI primitive) so the
+ * arrow tracks the anchor on scroll/resize AND when a sibling reflows it,
+ * flipping/shifting to stay on screen. The developer owns when it shows
+ * (`open`/`default-open`); the ×, Escape, OR clicking the trigger fires
+ * `onDismiss`. Color comes from `--kai-coachmark-bg` / `--kai-coachmark-fg` (each
+ * defaulting to the `tone` palette), so a consumer can recolor purely in CSS; the
+ * arrow reads the same bg var so it always continues the bubble.
+ */
+export declare function Coachmark(props: CoachmarkProps): JSX.Element;

package/dist/components/composer-dom.d.ts

@@ -0,0 +1,35 @@
+import { EntityRef, ComposerDoc } from '../primitives/composer-model';
+export declare const ZWSP = "\u200B";
+export declare const ENTITY_ATTR = "data-kai-entity";
+export declare const entityStore: WeakMap<HTMLElement, EntityRef>;
+export declare function isEntityEl(node: Node | null): node is HTMLElement;
+/**
+ * A TreeWalker over the editable's text nodes that SKIPS text inside entity
+ * pills. Pills are atomic and contribute nothing to the text model — their inner
+ * label text must not pollute caret offsets, trigger detection, or highlight
+ * ranges. (Without this, the text seen at a caret right after a pill is the
+ * pill's label, so `/` reads as glued to the label instead of starting a token.)
+ */
+export declare function createTextWalker(root: HTMLElement): TreeWalker;
+/**
+ * The leading sigil shown on a "light" pill, by kind: skills `/`, agents `@`.
+ * Skills and agents render as decorated inline text led by their sigil; this is
+ * what makes them read like `/my-skill` / `@my-agent` rather than a chip.
+ * Returns '' for kinds rendered as a richer CHIP (plugins, and any other/unknown
+ * kind) — those carry an icon instead of a sigil. The sigil is visual only: it
+ * never enters the text model (the entity is read from `entityStore`, and the
+ * text walker skips pill-internal nodes).
+ */
+export declare function kindSigil(kind: string): string;
+/**
+ * Default monochrome (currentColor) glyph per entity kind, for the richer CHIP
+ * kinds shown in the trigger menu / on plugin pills: plugin = plug. (Skills and
+ * agents are light sigil-text pills — see `kindSigil` — so they take no glyph on
+ * the pill, though the menu may still show one.) Returns inline SVG markup
+ * (trusted — no user input), or '' for kinds without a default. An item's own
+ * `icon` always takes precedence over this.
+ */
+export declare function kindGlyph(kind: string): string;
+export declare function createEntityEl(doc: Document, entity: EntityRef, kindIcons?: Record<string, string>): HTMLElement;
+export declare function parseDom(root: HTMLElement): ComposerDoc;
+export declare function renderDoc(root: HTMLElement, doc: ComposerDoc, ownerDoc?: Document, kindIcons?: Record<string, string>): void;

package/dist/components/composer-highlight.d.ts

@@ -0,0 +1,48 @@
+import { HighlightRule } from './composer';
+export interface HighlightMatch {
+    start: number;
+    end: number;
+    class: string | undefined;
+}
+/**
+ * Find all non-overlapping highlight ranges in `text` for the given rules.
+ *
+ * - A string rule is matched as a case-insensitive literal (regex metachars are escaped).
+ * - An object rule uses `new RegExp(pattern, flags ?? 'gi')`.
+ * - Overlapping ranges are resolved in earliest-start order; later ranges that
+ *   overlap an already-claimed span are dropped.
+ * - Zero-width matches are skipped to avoid infinite loops.
+ * - Returns `[]` when nothing matches.
+ */
+export declare function findHighlightMatches(text: string, rules: HighlightRule[]): HighlightMatch[];
+declare global {
+    interface CSSNamespace {
+        highlights?: HighlightRegistry;
+    }
+    interface HighlightRegistry {
+        set(name: string, highlight: CSSHighlight): void;
+        delete(name: string): boolean;
+        has(name: string): boolean;
+    }
+    class CSSHighlight {
+        constructor(...ranges: Range[]);
+    }
+}
+/**
+ * Feature-detect whether the CSS Custom Highlight API is available in the
+ * current environment.  Returns false in jsdom (decoration no-op).
+ */
+export declare function supportsHighlightAPI(): boolean;
+/**
+ * Apply highlight matches to a contenteditable element using the CSS Custom
+ * Highlight API.  Maps text offsets (ZWSP-stripped concatenated text) to DOM
+ * Ranges spanning across text nodes, builds a `Highlight`, and registers it.
+ *
+ * If the API is unavailable (jsdom, older browsers), this is a strict no-op.
+ *
+ * @param root     The contenteditable element.
+ * @param matches  Pre-computed non-overlapping `{start, end}` ranges.
+ * @param zwsp     The ZWSP character used in the editable (passed to avoid
+ *                 a circular import; callers pass ZWSP from composer-dom).
+ */
+export declare function applyHighlights(root: HTMLElement, matches: HighlightMatch[], zwsp: string, name?: string): void;

package/dist/components/composer-history.d.ts

@@ -0,0 +1,34 @@
+import { ComposerDoc } from '../primitives/composer-model';
+/**
+ * Undo/redo history for the composer.
+ *
+ * The browser's native contenteditable undo stack can't track our programmatic
+ * pill insertion/deletion — it leaves pills stuck and replays text edits against
+ * a DOM we changed underneath it, corrupting the content. So we own the history:
+ * a stack of document-model snapshots. Restoring a snapshot re-renders the doc
+ * (pills included, since each snapshot holds full EntityRefs) and the caret.
+ *
+ * Pure module — no DOM. The caller computes `coalesce` (true to merge a run of
+ * consecutive typing into one undo step; false for a structural edit like a pill
+ * insert/delete, which gets its own step).
+ */
+export interface Snapshot {
+    doc: ComposerDoc;
+    caret: number;
+}
+export interface ComposerHistory {
+    /** Record a new state. `coalesce` merges it into the current entry instead of
+     *  pushing a new one (used for consecutive typing). */
+    record(snap: Snapshot, coalesce: boolean): void;
+    /** Step back; returns the snapshot to restore, or null if nothing to undo. */
+    undo(): Snapshot | null;
+    /** Step forward; returns the snapshot to restore, or null if nothing to redo. */
+    redo(): Snapshot | null;
+    /** Replace all history with a single baseline entry (e.g. external value set). */
+    reset(snap: Snapshot): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** Current entry count (for tests/debugging). */
+    size(): number;
+}
+export declare function createHistory(initial: Snapshot, limit?: number): ComposerHistory;