@kitn.ai/ui 0.16.0 → 0.18.0

package/dist/schemas/choice.schema.json

@@ -65,6 +65,11 @@
     "allowOther": {
       "description": "Optional free-text escape ('none of these / specify'). `true` appends a final 'Other…' option; an object customizes its `label`/`placeholder`. Selecting it reveals a text input; the shared Submit button then emits `{ kind:'action', action:'__other__', payload:{ text } }`.",
       "x-kai-control": "allow-other"
+    },
+    "dismissible": {
+      "type": "boolean",
+      "default": false,
+      "description": "Show a close affordance that emits the `dismiss` verb. The card collapses to a re-openable 'dismissed' stub; the host decides via `onReopen` whether it comes back live or `expired`."
     }
   }
 }

package/dist/schemas/tasks.schema.json

@@ -8,9 +8,9 @@
   "properties": {
     "mode": {
       "type": "string",
-      "enum": ["select"],
+      "enum": ["select", "progress"],
       "default": "select",
-      "description": "v1 supports only 'select' (toggle + confirm). 'progress' (live AG-UI status) is a future enum value; restricting it now keeps the wire forward-compatible.",
+      "description": "'select' (default) = toggle + a confirm button that emits `submit`. 'progress' = an onboarding-checklist look (header `done / total` count, circular indicators, per-item title/description, no confirm button, where checking a row IS the action). Both share the selection model.",
       "x-kai-mode": true
     },
     "heading": {
@@ -73,6 +73,11 @@
       "minimum": 1,
       "description": "Optional maximum selectable; further toggles are blocked once reached.",
       "x-kai-select-max": true
+    },
+    "dismissible": {
+      "type": "boolean",
+      "default": false,
+      "description": "Show a close affordance that emits the `dismiss` verb. The card collapses to a re-openable 'dismissed' stub; the host decides via `onReopen` whether it comes back live or `expired`."
     }
   }
 }

package/dist/state/index.d.ts

@@ -0,0 +1,4 @@
+export { appendMessage, upsertMessage, updateMessage, removeMessage, appendContent } from './messages';
+export { addSuggestion, removeSuggestion } from './suggestions';
+export { createAssistantStream, onStreamSettled } from './stream';
+export type { SetMessages, AssistantStream } from './stream';

package/dist/state/messages.d.ts

@@ -0,0 +1,11 @@
+import { ChatMessage } from '../elements/chat-types';
+/** Append a message; returns a new array. */
+export declare function appendMessage(messages: ChatMessage[], msg: ChatMessage): ChatMessage[];
+/** Replace a same-id message, or append when absent. */
+export declare function upsertMessage(messages: ChatMessage[], msg: ChatMessage): ChatMessage[];
+/** Patch the matched message (object patch or updater). Untouched items keep their reference. */
+export declare function updateMessage(messages: ChatMessage[], id: string, patch: Partial<ChatMessage> | ((m: ChatMessage) => ChatMessage)): ChatMessage[];
+/** Remove the matched message. */
+export declare function removeMessage(messages: ChatMessage[], id: string): ChatMessage[];
+/** Streaming primitive: concatenate `delta` onto the matched message's content. */
+export declare function appendContent(messages: ChatMessage[], id: string, delta: string): ChatMessage[];

package/dist/state/stream.d.ts

@@ -0,0 +1,22 @@
+import { ChatMessage } from '../elements/chat-types';
+import { ToolPart } from '../components/tool-types';
+/** The one universal contract: a functional-updater setter (React setState shape). */
+export type SetMessages = (updater: (prev: ChatMessage[]) => ChatMessage[]) => void;
+/** A fluent builder for one in-flight assistant message. Owns no state. */
+export interface AssistantStream {
+    readonly id: string;
+    appendText(delta: string): AssistantStream;
+    setText(content: string): AssistantStream;
+    appendReasoning(delta: string, label?: string): AssistantStream;
+    setReasoning(text: string, label?: string): AssistantStream;
+    upsertTool(tool: ToolPart): AssistantStream;
+    updateTool(toolCallId: string, patch: Partial<ToolPart>): AssistantStream;
+    patch(patch: Partial<ChatMessage>): AssistantStream;
+    done(final?: Partial<ChatMessage>): void;
+    abort(reason?: string): void;
+}
+/** Start an assistant message and drive it through `set`. New refs on every mutation. */
+export declare function createAssistantStream(set: SetMessages, init?: Partial<ChatMessage>): AssistantStream;
+/** Wrap a stream so `onSettle` fires on done/abort (used to toggle a `loading` flag).
+ *  Preserves the fluent chain by returning the wrapper from every mutator. */
+export declare function onStreamSettled(inner: AssistantStream, onSettle: () => void): AssistantStream;

package/dist/state/suggestions.d.ts

@@ -0,0 +1,4 @@
+/** Append a suggestion; no-op when already present. Returns a new array. */
+export declare function addSuggestion(suggestions: string[], s: string): string[];
+/** Remove a suggestion by value. */
+export declare function removeSuggestion(suggestions: string[], s: string): string[];

package/dist/state.js

@@ -0,0 +1,117 @@
+function c(t, u) {
+  return [...t, u];
+}
+function f(t, u) {
+  const o = t.findIndex((d) => d.id === u.id);
+  if (o === -1) return [...t, u];
+  const e = t.slice();
+  return e[o] = u, e;
+}
+function T(t, u, o) {
+  return t.map(
+    (e) => e.id === u ? typeof o == "function" ? o(e) : { ...e, ...o } : e
+  );
+}
+function g(t, u) {
+  return t.filter((o) => o.id !== u);
+}
+function I(t, u, o) {
+  return t.map((e) => e.id === u ? { ...e, content: e.content + o } : e);
+}
+function x(t, u) {
+  return t.includes(u) ? t.slice() : [...t, u];
+}
+function y(t, u) {
+  return t.filter((o) => o !== u);
+}
+function l() {
+  return typeof crypto < "u" && typeof crypto.randomUUID == "function" ? crypto.randomUUID() : "kai-" + Math.random().toString(36).slice(2);
+}
+function b(t, u = {}) {
+  const o = u.id ?? l(), e = { id: o, role: "assistant", content: "", ...u };
+  t((n) => [...n, e]);
+  const d = (n) => t((r) => r.map((a) => a.id === o ? n(a) : a)), i = {
+    id: o,
+    appendText(n) {
+      return d((r) => ({ ...r, content: r.content + n })), i;
+    },
+    setText(n) {
+      return d((r) => ({ ...r, content: n })), i;
+    },
+    appendReasoning(n, r) {
+      return d((a) => {
+        var s, p;
+        return { ...a, reasoning: { text: (((s = a.reasoning) == null ? void 0 : s.text) ?? "") + n, label: r ?? ((p = a.reasoning) == null ? void 0 : p.label) } };
+      }), i;
+    },
+    setReasoning(n, r) {
+      return d((a) => {
+        var s;
+        return { ...a, reasoning: { text: n, label: r ?? ((s = a.reasoning) == null ? void 0 : s.label) } };
+      }), i;
+    },
+    upsertTool(n) {
+      return d((r) => {
+        const a = r.tools ? r.tools.slice() : [], s = n.toolCallId != null ? a.findIndex((p) => p.toolCallId === n.toolCallId) : a.findIndex((p) => p.type === n.type);
+        return s === -1 ? a.push(n) : a[s] = n, { ...r, tools: a };
+      }), i;
+    },
+    updateTool(n, r) {
+      return d((a) => ({ ...a, tools: (a.tools ?? []).map((s) => s.toolCallId === n ? { ...s, ...r } : s) })), i;
+    },
+    patch(n) {
+      return d((r) => ({ ...r, ...n })), i;
+    },
+    done(n) {
+      n && d((r) => ({ ...r, ...n }));
+    },
+    abort(n) {
+      n ? d((r) => ({ ...r, tools: (r.tools ?? []).map((a) => ({ ...a, state: "output-error", errorText: n })) })) : t((r) => r.filter((a) => a.id !== o));
+    }
+  };
+  return i;
+}
+function R(t, u) {
+  const o = {
+    id: t.id,
+    appendText(e) {
+      return t.appendText(e), o;
+    },
+    setText(e) {
+      return t.setText(e), o;
+    },
+    appendReasoning(e, d) {
+      return t.appendReasoning(e, d), o;
+    },
+    setReasoning(e, d) {
+      return t.setReasoning(e, d), o;
+    },
+    upsertTool(e) {
+      return t.upsertTool(e), o;
+    },
+    updateTool(e, d) {
+      return t.updateTool(e, d), o;
+    },
+    patch(e) {
+      return t.patch(e), o;
+    },
+    done(e) {
+      t.done(e), u();
+    },
+    abort(e) {
+      t.abort(e), u();
+    }
+  };
+  return o;
+}
+export {
+  x as addSuggestion,
+  I as appendContent,
+  c as appendMessage,
+  b as createAssistantStream,
+  R as onStreamSettled,
+  g as removeMessage,
+  y as removeSuggestion,
+  T as updateMessage,
+  f as upsertMessage
+};

package/dist/theme.tokens.css

@@ -15,10 +15,57 @@
   --color-secondary-foreground: var(--kai-color-secondary-foreground, hsl(240 5.9% 10%));
   --color-muted: var(--kai-color-muted, hsl(240 4.8% 95.9%));
   --color-muted-foreground: var(--kai-color-muted-foreground, hsl(240 3.8% 43%));
+  /* Subtle SURFACE — an opaque "muted panel" for things that sit OVER content
+     (the prompt input, message bubbles, artifact/card headers, chips). CALCULATED
+     from existing tokens — `--color-muted` blended 40% onto `--color-background`
+     — so it tracks the theme (incl. dark) automatically and needs no hand-picked
+     value. SOLID (no alpha), so nothing behind it bleeds through. This replaces
+     ad-hoc `bg-muted/40` surfaces. Retint via the --kai-color-surface knob (or a
+     bare value); --color-surface-strong is the stronger step (hover/raised) and
+     --color-surface-sunken is recessed BELOW the base surface (wells, or a banner
+     that sits behind a card). Sunken is theme-specific: "darker than the card"
+     means a LOWER muted% in dark but a HIGHER one in light, so the two scopes
+     can't share a number — see the .dark block. */
+  --color-surface: var(--kai-color-surface, color-mix(in srgb, var(--color-muted) 40%, var(--color-background)));
+  --color-surface-strong: var(--kai-color-surface-strong, color-mix(in srgb, var(--color-muted) 60%, var(--color-background)));
+  --color-surface-sunken: var(--kai-color-surface-sunken, color-mix(in srgb, var(--color-muted) 85%, var(--color-background)));
   --color-accent: var(--kai-color-accent, hsl(240 4.8% 95.9%));
   --color-accent-foreground: var(--kai-color-accent-foreground, hsl(240 5.9% 10%));
   --color-destructive: var(--kai-color-destructive, hsl(0 72% 45%));
   --color-destructive-foreground: var(--kai-color-destructive-foreground, hsl(0 0% 98%));
+  /* Semantic status colors - solid fills with a legible foreground, matched to
+     the kit's tool-green / -amber / -blue hues so they read on-brand. Use
+     bg-success / bg-warning / bg-info with the matching -foreground for badges,
+     banners, and buttons; or text-success / -warning / -info on a soft tint
+     (below). destructive (above) is the danger/error member of the same family.
+     Light uses darker hues so the color carries a light foreground AND stays
+     legible as text on a pale tint; dark (see .dark) flips to brighter hues over
+     a near-black foreground. Override via --kai-color-success / -warning / -info
+     (+ -foreground). */
+  --color-success: var(--kai-color-success, hsl(142 71% 30%));
+  --color-success-foreground: var(--kai-color-success-foreground, hsl(0 0% 98%));
+  --color-warning: var(--kai-color-warning, hsl(38 92% 30%));
+  --color-warning-foreground: var(--kai-color-warning-foreground, hsl(0 0% 98%));
+  --color-info: var(--kai-color-info, hsl(217 91% 42%));
+  --color-info-foreground: var(--kai-color-info-foreground, hsl(0 0% 98%));
+  /* Soft tinted status surfaces - OPAQUE, theme-tracking fills derived as ~14% of
+     the status hue blended onto the background. Use these for subtle callouts /
+     banners instead of an eyeballed bg-success/10; pair with text-success /
+     -warning / -info / -destructive. Derived, so declared in BOTH light and dark
+     (a color-mix resolves where it's declared - see the surface tokens above). A
+     bare bg- utility for a color-mix token is added at the bottom (see bg-surface). */
+  --color-success-soft: var(--kai-color-success-soft, color-mix(in oklab, var(--color-success) 14%, var(--color-background)));
+  --color-warning-soft: var(--kai-color-warning-soft, color-mix(in oklab, var(--color-warning) 14%, var(--color-background)));
+  --color-info-soft: var(--kai-color-info-soft, color-mix(in oklab, var(--color-info) 14%, var(--color-background)));
+  --color-destructive-soft: var(--kai-color-destructive-soft, color-mix(in oklab, var(--color-destructive) 14%, var(--color-background)));
+  /* Interaction-state backgrounds - opaque, theme-tracking fills for row/control
+     states so consumers stop eyeballing /10 opacities. --color-hover is a subtle
+     neutral (a little --color-muted on the background); --color-selected is a
+     faint --color-primary tint so a selected row tracks the brand. Use bg-hover /
+     bg-selected. Derived, so declared in BOTH light and dark; bare bg- utilities
+     added at the bottom. */
+  --color-hover: var(--kai-color-hover, color-mix(in oklab, var(--color-muted) 60%, var(--color-background)));
+  --color-selected: var(--kai-color-selected, color-mix(in oklab, var(--color-primary) 8%, var(--color-background)));
   --color-border: var(--kai-color-border, hsl(240 5.9% 90%));
   --color-input: var(--kai-color-input, hsl(240 5.9% 90%));
   /* Focus ring — a deliberate blue (not a neutral) so keyboard focus is always
@@ -90,10 +137,36 @@
   --color-secondary-foreground: var(--kai-color-secondary-foreground, hsl(0 0% 98%));
   --color-muted: var(--kai-color-muted, hsl(45 4% 17%));
   --color-muted-foreground: var(--kai-color-muted-foreground, hsl(45 4% 64%));
+  /* Re-declared in the dark scope so the color-mix recomputes with the DARK
+     muted/background (a derived token is computed where it's declared, not where
+     it's used — see the light --color-surface for the full note). */
+  --color-surface: var(--kai-color-surface, color-mix(in srgb, var(--color-muted) 40%, var(--color-background)));
+  --color-surface-strong: var(--kai-color-surface-strong, color-mix(in srgb, var(--color-muted) 60%, var(--color-background)));
+  /* Sunken: in dark a LOWER muted% is darker (blends toward the dark background). */
+  --color-surface-sunken: var(--kai-color-surface-sunken, color-mix(in srgb, var(--color-muted) 18%, var(--color-background)));
   --color-accent: var(--kai-color-accent, hsl(45 4% 17%));
   --color-accent-foreground: var(--kai-color-accent-foreground, hsl(0 0% 98%));
   --color-destructive: var(--kai-color-destructive, hsl(0 62.8% 30.6%));
   --color-destructive-foreground: var(--kai-color-destructive-foreground, hsl(0 0% 98%));
+  /* Semantic status colors - dark mode flips to the brighter tool-* dark hues
+     (matching the chip values) carried over a near-black foreground, so the color
+     both reads as text on a dark soft tint AND backs a legible foreground. See
+     the light @theme note. */
+  --color-success: var(--kai-color-success, hsl(142 71% 45%));
+  --color-success-foreground: var(--kai-color-success-foreground, hsl(45 4% 11%));
+  --color-warning: var(--kai-color-warning, hsl(38 92% 50%));
+  --color-warning-foreground: var(--kai-color-warning-foreground, hsl(45 4% 11%));
+  --color-info: var(--kai-color-info, hsl(217 91% 70%));
+  --color-info-foreground: var(--kai-color-info-foreground, hsl(45 4% 11%));
+  /* Soft status surfaces + interaction states - re-declared so each color-mix
+     recomputes with the DARK hues/background (a derived token resolves where it's
+     declared; see the light block for the full note). */
+  --color-success-soft: var(--kai-color-success-soft, color-mix(in oklab, var(--color-success) 14%, var(--color-background)));
+  --color-warning-soft: var(--kai-color-warning-soft, color-mix(in oklab, var(--color-warning) 14%, var(--color-background)));
+  --color-info-soft: var(--kai-color-info-soft, color-mix(in oklab, var(--color-info) 14%, var(--color-background)));
+  --color-destructive-soft: var(--kai-color-destructive-soft, color-mix(in oklab, var(--color-destructive) 14%, var(--color-background)));
+  --color-hover: var(--kai-color-hover, color-mix(in oklab, var(--color-muted) 60%, var(--color-background)));
+  --color-selected: var(--kai-color-selected, color-mix(in oklab, var(--color-primary) 8%, var(--color-background)));
   --color-border: var(--kai-color-border, hsl(45 4% 17%));
   --color-input: var(--kai-color-input, hsl(45 4% 17%));
   --color-ring: var(--kai-color-ring, hsl(217 91% 68%));
@@ -174,3 +247,17 @@
 }
 .scrollbar-thin::-webkit-scrollbar-thumb:hover { background-color: var(--color-scrollbar-thumb-hover); }
 .scrollbar-thin::-webkit-scrollbar-corner { background: transparent; }
+
+/* Surface utilities — `bg-surface` / `bg-surface-strong` paint the opaque,
+   theme-derived surface tokens (see --color-surface above). Defined explicitly
+   because a color-mix-valued @theme token does NOT emit a bare `bg-` utility on
+   its own (only opacity variants). Use these for panels that sit OVER content
+   instead of `bg-muted/NN`. */
+
+/* Soft-status + interaction-state utilities. Same reason as bg-surface above: a
+   color-mix-valued @theme token does NOT emit a bare `bg-` utility on its own, so
+   bg-success-soft / bg-warning-soft / bg-info-soft / bg-destructive-soft and
+   bg-hover / bg-selected are declared here. (The SOLID tokens - success / warning
+   / info + their -foreground - are plain hsl values, so bg-success / text-success
+   etc. ARE auto-generated by @theme and need no explicit utility.) */
+

package/dist/types.d.ts

@@ -31,6 +31,10 @@ export interface ConversationSummary {
     messageCount: number;
     lastMessageAt: string;
     updatedAt: string;
+    /** Right-aligned trailing text on the row — a count, status, or "days ago".
+     *  When omitted, a short relative time is auto-derived from `updatedAt`
+     *  (fallback `lastMessageAt`). */
+    trailing?: string;
 }
 export interface ConversationGroup {
     id: string;

package/dist/ui/agent-card.d.ts

@@ -0,0 +1,61 @@
+import { JSX } from 'solid-js';
+/** The run state of an agent, mapped to the kit's tool / status hues.
+ *  - `working` (blue) the agent is actively running.
+ *  - `idle` (muted) waiting, no current activity.
+ *  - `done` (green) finished its turn.
+ *  - `error` (red) failed.
+ *  - `blocked` (amber) stalled, usually waiting on something. */
+export type AgentStatusTone = 'working' | 'idle' | 'done' | 'error' | 'blocked';
+export interface AgentStatus {
+    /** Which hue the status dot takes. */
+    tone: AgentStatusTone;
+    /** Optional short label rendered next to the dot (e.g. "Working", "Blocked on you"). */
+    label?: string;
+    /** Animate the dot with a ping ring (off under prefers-reduced-motion). */
+    pulse?: boolean;
+}
+export interface AgentCardProps {
+    /** @deprecated No longer rendered. Kept for back-compat with existing callers. */
+    leading?: JSX.Element;
+    /** The agent's name. The primary label. */
+    name: string;
+    /** @deprecated No longer rendered. Kept for back-compat with existing callers. */
+    subtitle?: string;
+    /** @deprecated No longer rendered. Kept for back-compat with existing callers. */
+    lastLine?: string;
+    /** Run status: a tone-colored dot, an optional small label, optionally pulsing. */
+    status: AgentStatus;
+    /** Raise a prominent "needs you" pill plus a glowing amber edge. The
+     *  attention-routing signal that pulls focus to this agent. */
+    needsAttention?: boolean;
+    /** Selected / focused state. Highlighted border and surface. */
+    active?: boolean;
+    /** Promote this agent to focus. Fires on click and on Enter / Space. */
+    onActivate?: () => void;
+    /** Alias for {@link AgentCardProps.onActivate}. Both fire if both are set. */
+    onClick?: () => void;
+    /** Show a trailing "..." overflow button and fire this on click. The consumer
+     *  wires the actual menu; the card only surfaces the affordance. Click is
+     *  stopped from also activating the card. */
+    onMenu?: (e: MouseEvent) => void;
+    /** Extra classes merged over the card. */
+    class?: string;
+}
+/**
+ * AgentCard - the compact representation of one agent in a multi-agent workspace.
+ *
+ * In a focus + periphery layout the agents you are not focused on collapse to these
+ * glanceable cards, arranged as a narrow side RAIL or a wide LIST. The card stays
+ * deliberately minimal: the agent name, a tone-colored status dot, a "needs you"
+ * affordance when the agent wants your attention, and a trailing "..." overflow
+ * button for per-agent actions. Clicking the card promotes the agent back to focus.
+ *
+ * It is `w-full` and lets the name truncate, so the same component works in both a
+ * narrow rail and a wide list without changes - the content adapts to the box.
+ *
+ * Status maps to the kit's tool hues so it reads in light and dark from tokens alone:
+ * working = blue, idle = muted, done = green, error = red, blocked = amber. Setting
+ * `needsAttention` raises an amber "Needs you" pill and a glowing amber ring so the
+ * card jumps out of the periphery - the attention-routing signal.
+ */
+export declare function AgentCard(props: AgentCardProps): JSX.Element;

package/dist/ui/button.d.ts

@@ -1,10 +1,13 @@
 import { JSX } from 'solid-js';
 import { VariantProps } from 'class-variance-authority';
 declare const buttonVariants: (props?: ({
-    variant?: "default" | "ghost" | "outline" | "destructive" | null | undefined;
-    size?: "sm" | "lg" | "md" | "icon" | "icon-sm" | null | undefined;
+    variant?: "default" | "ghost" | "subtle" | "outline" | "destructive" | null | undefined;
+    size?: "sm" | "md" | "lg" | "icon" | "icon-sm" | null | undefined;
+    align?: "end" | "start" | "center" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 export interface ButtonProps extends JSX.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
+    /** Stretch to the full width of the container (a block button). */
+    full?: boolean;
 }
 export declare function Button(props: ButtonProps): JSX.Element;
 export { buttonVariants };

package/dist/ui/card.d.ts

@@ -0,0 +1,61 @@
+import { JSX } from 'solid-js';
+export type CardAppearance = 'outlined' | 'filled' | 'plain' | 'accent';
+/** `vertical` (media on top), `horizontal` (media at the start), or `responsive`
+ *  (horizontal when the card's container is at least ~28rem wide, else vertical —
+ *  a CSS container query on the card's own width, NOT the viewport). */
+export type CardOrientation = 'vertical' | 'horizontal' | 'responsive';
+export interface CardProps extends JSX.HTMLAttributes<HTMLDivElement> {
+    /** Surface treatment: `outlined` | `filled` | `plain` | `accent`. */
+    appearance?: CardAppearance;
+    /** `vertical` (media on top) or `horizontal` (media at the start). */
+    orientation?: CardOrientation;
+    /** The card width below which a `responsive` card collapses to vertical and the
+     *  footer action cluster stacks. A CSS length (e.g. `'24rem'`); default `'28rem'`.
+     *  Container-query breakpoints can't be CSS variables, so this prop is baked into
+     *  a per-card `@container` rule. */
+    collapse?: string;
+    /** Tighter spacing for dense lists (shrinks `--kai-card-spacing`). */
+    dense?: boolean;
+    /** Full-bleed media region (image/video/illustration) at the top (vertical) or
+     *  start (horizontal). Clipped to the card's corners. */
+    media?: JSX.Element;
+    /** Header content (e.g. a title). Rendered above the body, padded. */
+    header?: JSX.Element;
+    /** An actions cluster pinned to the end of the header row. */
+    headerActions?: JSX.Element;
+    /** Footer content. Rendered below the body, padded. */
+    footer?: JSX.Element;
+    /** An actions cluster pinned to the end of the footer row. */
+    footerActions?: JSX.Element;
+    /** Whether the default slot (body) has content — the facade computes this so an
+     *  empty body region isn't rendered (an empty `<slot>` is always truthy). */
+    hasBody?: boolean;
+    /** Render a dismiss (×) that hides the card and calls `onDismiss`. Off by default. */
+    dismissible?: boolean;
+    onDismiss?: () => void;
+    /** Render the whole card as a link (`<a>`). Wins over `clickable`. */
+    href?: string;
+    target?: string;
+    rel?: string;
+    /** Make the whole card a `role="button"` with Enter/Space activation. A
+     *  clickable/href card must NOT also contain footer action buttons. */
+    clickable?: boolean;
+    onCardClick?: (event: MouseEvent | KeyboardEvent) => void;
+}
+/**
+ * `Card` — the kit's presentational card surface (the `<kai-card>` primitive),
+ * modeled on the WebAwesome card: ONE element whose flexibility comes from a few
+ * structural slots (`media`, `header` + actions, `footer` + actions; body is the
+ * default slot), `appearance` + `orientation` variants, `::part` styling, and a
+ * single `--kai-card-spacing` knob. The title/description are NOT slots — they are
+ * body/header content the consumer marks up, because a slot earns its place only
+ * where the shadow boundary blocks the consumer (a pinned media/footer region),
+ * not for a text node.
+ *
+ * Distinct from the generative-UI contract chrome in `../components/card.tsx`
+ * (which the Card Contract cards compose); this one is purely presentational.
+ *
+ * a11y: a `clickable`/`href` card MUST NOT also contain action buttons — that
+ * nests interactive controls inside a button/link.
+ */
+export declare function Card(props: CardProps): JSX.Element;

package/dist/ui/collapsible.d.ts

@@ -1,4 +1,4 @@
-import { JSX } from 'solid-js';
+import { JSX, Accessor } from 'solid-js';
 declare module 'solid-js' {
     namespace JSX {
         interface ExplicitBoolAttributes {
@@ -6,10 +6,24 @@ declare module 'solid-js' {
         }
     }
 }
+/** Imperative open controller, handed to a parent (e.g. the kai-tool facade)
+ *  via `controllerRef` so it can drive/observe open state — mirrors
+ *  HoverCardController. Only available when the Collapsible is UNCONTROLLED
+ *  (no `open` prop); in controlled mode the parent already owns the state. */
+export interface CollapsibleController {
+    open: Accessor<boolean>;
+    setOpen: (v: boolean) => void;
+}
 export declare function Collapsible(props: {
     open?: boolean;
     defaultOpen?: boolean;
     onOpenChange?: (open: boolean) => void;
+    /** When true, the trigger no longer toggles (programmatic show/hide still work
+     *  via the controller; this only gates the user-facing trigger). */
+    disabled?: boolean;
+    /** Receive the open controller (open accessor + setOpen) once mounted.
+     *  Only meaningful in uncontrolled mode (no `open` prop). */
+    controllerRef?: (api: CollapsibleController) => void;
     children: JSX.Element;
     class?: string;
 }): JSX.Element;

package/dist/ui/command.d.ts

@@ -0,0 +1,33 @@
+import { JSX } from 'solid-js';
+export interface CommandRow {
+    id: string;
+    label: string;
+    icon?: string;
+    description?: string;
+    /** Optional keyboard shortcut shown as right-aligned key caps; uses the
+     *  kai-kbd `keys` syntax (e.g. "Mod+K", "Alt+1"). */
+    shortcut?: string;
+}
+export interface CommandGroup {
+    group?: string;
+    items: CommandRow[];
+}
+export interface CommandListProps {
+    groups: CommandGroup[];
+    activeId?: string;
+    onSelect: (id: string) => void;
+    emptyLabel?: string;
+    /** Accessible label for the listbox container. Defaults to 'Command palette'. */
+    ariaLabel?: string;
+    /** id applied to the listbox container, for aria-controls wiring. */
+    id?: string;
+}
+/**
+ * `CommandList` — a presentational grouped listbox for command/mention palettes.
+ *
+ * Renders a `role="listbox"` container. Groups with a `group` name get a muted
+ * section header. Each row is a `role="option"` button with icon, label, and
+ * optional description. Clicking a row calls `onSelect(id)`. When there are no
+ * groups/items it renders `emptyLabel` (default "No results").
+ */
+export declare function CommandList(props: CommandListProps): JSX.Element;

package/dist/ui/dialog.d.ts

@@ -0,0 +1,42 @@
+import { Accessor, JSX } from 'solid-js';
+/** Imperative open controller, handed to a parent (e.g. the kai-dialog facade)
+ *  via `controllerRef` so it can drive/observe open state with `wireDisclosure`. */
+export interface DialogController {
+    open: Accessor<boolean>;
+    setOpen: (v: boolean) => void;
+}
+export interface DialogProps {
+    /** Dialog body — the default slot / main content. */
+    children?: JSX.Element;
+    /** Optional header region (e.g. a title). Rendered above the body with a divider. */
+    header?: JSX.Element;
+    /** Optional footer region (e.g. action buttons). Rendered below the body with a divider. */
+    footer?: JSX.Element;
+    /** 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 the dialog wants to open or close (Escape / backdrop / method). */
+    onOpenChange?: (open: boolean) => void;
+    /** Receive the open controller (open accessor + setOpen) once mounted. */
+    controllerRef?: (api: DialogController) => void;
+    /** Receive the focusable panel node so a facade's `focus()` can target it. */
+    panelRef?: (el: HTMLElement) => void;
+    /** Accessible name for the dialog when no `header` is provided. */
+    'aria-label'?: string;
+    /** Extra class applied to the panel (e.g. a wider `max-w-*`). */
+    class?: string;
+}
+/**
+ * Dialog is the presentational centered modal surface. It renders through a Portal
+ * (so it escapes any clipping/stacking ancestor), dims the page with a backdrop,
+ * and centers a panel with a sensible max width/height and internal scroll. It
+ * closes on Escape and on a backdrop click (never on a panel click), moves focus
+ * into the panel on open and restores it on close, and runs a basic Tab focus
+ * trap so keyboard focus cycles within the panel while open. The developer owns
+ * when it opens (drive `open` / `defaultOpen`); this owns being the modal.
+ *
+ * Styleable parts: `backdrop` · `panel` · `header` · `body` · `footer`.
+ */
+export declare function Dialog(props: DialogProps): JSX.Element;