@kitn.ai/ui 0.26.0 → 0.28.0

package/src/primitives/toast-store.ts

@@ -9,6 +9,14 @@
 // element, so it carries its own shadow root + the shared kit stylesheet — it's
 // viewport-positioned AND fully kit-styled, never a raw div.
 //
+// ADOPTS, else creates: `ensureMounted` first
+// looks for a connected `<kai-toast-region>` already in the document and binds
+// the store to it, so an app that placed its own region and also calls
+// `toast()` gets ONE region, not two overlapping ones. It creates a region only
+// when none exists. With two or more candidate regions the choice is genuinely
+// ambiguous — the first in document order wins, and a one-time console.warn
+// says so (decide loudly).
+//
 // SSR-safe: every DOM touch is guarded by `typeof document`. On the server,
 // raising a toast is an inert no-op (the store updates, nothing mounts).
 
@@ -156,21 +164,75 @@ function resolveDuration(item: Pick<ToastItem, 'duration' | 'action'>): number {
 }
 
 /**
- * Lazily create the single `<kai-toast-region>` host on `document.body` and
- * bind the store to its `toasts` property. Idempotent + SSR-safe. The element
- * upgrade (its `defineWebComponent` registration) happens when the elements
- * bundle loads; setting the property before/after upgrade both work because
+ * Lazily resolve the single `<kai-toast-region>` host for a target and bind the
+ * store to its `toasts` property. Idempotent + SSR-safe. The element upgrade
+ * (its `defineWebComponent` registration) happens when the elements bundle
+ * loads; setting the property before/after upgrade both work because
  * `customElement` reflects late-set properties.
+ *
+ * ADOPT-IF-PRESENT: a connected
+ * `<kai-toast-region>` already in the document (same `target`, not already
+ * claimed for another target) is adopted — the store binds to IT, and no
+ * second region mounts. Adoption respects the region's authored attributes
+ * (position/stack/…): config from `configureToasts()` is not stamped onto an
+ * adopted region here, though an explicit `configureToasts()` call still
+ * updates every region, adopted included. Binding the store REPLACES a
+ * `toasts` array the app set as data — after the first `toast()` call the
+ * imperative store owns the adopted region's list. Only when no candidate
+ * exists is a fresh region created on `document.body`. Two or more candidates
+ * for the same target are genuinely ambiguous: the first in document order
+ * wins, with a one-time console.warn (decide loudly).
+ *
+ * If an adopted (or created) region later leaves the DOM, the cache entry is
+ * dropped and the next call resolves fresh — adopt again if a region exists,
+ * else create — so a removed region never becomes a dead cache entry that
+ * swallows toasts.
  */
 // One region per distinct target (the `null` key = the global / viewport region).
 // Every region binds the SAME store proxy and filters to its own target, so a
 // toast routes to the region for its `target`.
 const regions = new Map<HTMLElement | null, HTMLElement>();
 
+// Decide-loudly, once: ambiguity between 2+ candidate regions is warned about a
+// single time per page, not on every toast.
+let warnedAmbiguousRegions = false;
+
+/** Read a region element's `target` property (undefined pre-upgrade → null =
+ *  the global region). */
+function regionTarget(el: HTMLElement): HTMLElement | null {
+  return (el as unknown as { target?: HTMLElement }).target ?? null;
+}
+
 export function ensureMounted(target: HTMLElement | null = null): HTMLElement | undefined {
   if (typeof document === 'undefined') return undefined;
   const cached = regions.get(target);
   if (cached && cached.isConnected) return cached;
+  // The region this key resolved to left the DOM — drop the dead entry so it
+  // can never swallow toasts, and resolve fresh below.
+  if (cached) regions.delete(target);
+
+  // Adopt a region the app already placed. Regions this store already
+  // claimed for OTHER targets are not candidates.
+  const claimed = new Set(regions.values());
+  const candidates = Array.from(
+    document.querySelectorAll<HTMLElement>('kai-toast-region'),
+  ).filter((el) => el.isConnected && !claimed.has(el) && regionTarget(el) === target);
+  if (candidates.length > 1 && !warnedAmbiguousRegions) {
+    warnedAmbiguousRegions = true;
+    console.warn(
+      `[kitn] toast(): ${candidates.length} candidate <kai-toast-region> elements are in the ` +
+        'document; adopting the first in document order. Keep one region per target so the ' +
+        'imperative toast() API has an unambiguous home.',
+    );
+  }
+  const adopted = candidates[0];
+  if (adopted) {
+    (adopted as unknown as { toasts: ToastItem[] }).toasts = toasts as ToastItem[];
+    regions.set(target, adopted);
+    setMounted(true);
+    return adopted;
+  }
+
   const el = document.createElement('kai-toast-region') as HTMLElement;
   // Append FIRST so the element upgrades, THEN bind. Setting a property before
   // upgrade loses it: component-register resets every prop in the constructor on

package/src/primitives/url-scheme-policy.ts

@@ -0,0 +1,70 @@
+// src/primitives/url-scheme-policy.ts
+// The kit's one URL-scheme allow/deny policy, split out of card-routing.ts so it
+// has NO DOM dependency (`URL` is a global in both the browser and Node — the
+// rest of card-routing.ts uses HTMLElement/window/CustomEvent, which aren't).
+// That split matters beyond tidiness: this schema.ts (agent-tooling/construct)
+// runs under tsconfig.mcp.json's Node-only, no-DOM-lib pass (it's imported
+// transitively via mcp/tools/construct.ts), and importing anything from
+// card-routing.ts there drags its HTMLElement/window/Document/CustomEvent
+// references into that compile and breaks it — even though only isSafeUrl is
+// used. card-routing.ts re-exports everything here so its own public surface
+// (isSafeUrl/isScriptUrl, used by markdown.tsx/artifact.tsx/source.tsx) is
+// unchanged; this is a location split, not a second policy.
+
+const SAFE_SCHEMES = ['http:', 'https:', 'mailto:'];
+const SCRIPT_SCHEMES = ['javascript:', 'vbscript:'];
+
+/** The scheme the WHATWG parser reads out of `url`, resolved against a base so a
+ *  relative input inherits `http:`. `undefined` when it will not parse at all.
+ *
+ *  ONE parser for the two questions below, deliberately: the parsing is where
+ *  the subtlety lives (it strips embedded tabs/newlines and trims surrounding
+ *  whitespace before reading the scheme, so `java\nscript:` and
+ *  `  javascript:...  ` are both read as `javascript:` -- which a regex over the
+ *  raw string would miss). Two predicates over one parse cannot drift on that;
+ *  two hand-rolled parsers would. */
+function schemeOf(url: string): string | undefined {
+  try { return new URL(url, 'http://_invalid_base').protocol; } catch { return undefined; }
+}
+
+/** True when `url` is safe to put in an href / hand to `window.open` / an `<img src>`.
+ *
+ *  Exported so the MARKDOWN renderer, the ARTIFACT viewer and the construct
+ *  format's `widget.launcherIcon` reuse this exact guard rather than growing a
+ *  second scheme list that can drift from this one.
+ *
+ *  Resolving against a base is deliberate and is what makes it correct for
+ *  markdown: a relative or fragment link (`/docs`, `#section`, `./rel`) is
+ *  ordinary markdown, and resolving it inherits the base's `http:` so it
+ *  passes, while `javascript:`/`data:`/`vbscript:` keep their own protocol and
+ *  fail. It is correct for the artifact viewer for the same reason: a file with
+ *  no `src` to resolve against yields a bare relative path (`docs/report.pdf`),
+ *  which is a legitimate artifact address. Contrast `isRenderableLink` in
+ *  `primitives/link-preview.ts`, which takes NO base and so demands an absolute
+ *  http(s) URL: that is the right guard for a model-supplied citation -- a
+ *  reference to a page on the public web -- this one for markdown body links,
+ *  artifact file addresses, and a construct's launcher icon. */
+export function isSafeUrl(url: string): boolean {
+  const scheme = schemeOf(url);
+  return scheme !== undefined && SAFE_SCHEMES.includes(scheme);
+}
+
+/** True when navigating to `url` would EXECUTE it as script in the initiating
+ *  document's origin.
+ *
+ *  Strictly narrower than `!isSafeUrl(url)`, and not a competing policy: it
+ *  answers a different question, for the one sink where the allowlist is the
+ *  wrong tool. An `<iframe src>` legitimately takes `data:` and `blob:` (a
+ *  `data:` blob artifact is a documented `<kai-artifact>` use -- it is what
+ *  `displayUrl` exists for) and both get an OPAQUE origin in every modern
+ *  browser, so neither can reach the host page. `javascript:`/`vbscript:` are
+ *  the schemes that run in the EMBEDDER's origin, and they are the whole risk:
+ *  the default sandbox (no `allow-same-origin`) already makes the browser refuse
+ *  them, but a consumer who sets `allow-same-origin` turns a model-supplied
+ *  `src` into host-origin script execution. The artifact viewer used to suggest
+ *  that setting for "an artifact you trust"; it no longer does, and this guard
+ *  is what protects the consumers who took the old advice. */
+export function isScriptUrl(url: string): boolean {
+  const scheme = schemeOf(url);
+  return scheme !== undefined && SCRIPT_SCHEMES.includes(scheme);
+}

package/src/primitives/use-resize-observer.ts

@@ -14,8 +14,8 @@ export function observeContentHeight(el: Element, onHeight: (height: number) =>
 /** Observe an element's resizes but report the FULL rendered document height (not the
  *  observed element's own content-box) — `document.body.scrollHeight`.
  *
- *  Used by the remote-card provider runtime to size the host iframe (D1, rung 5 IVP
- *  task-10-report.md): `observeContentHeight` reports the ResizeObserver content-box of
+ *  Used by the remote-card provider runtime to size the host iframe:
+ *  `observeContentHeight` reports the ResizeObserver content-box of
  *  the observed root, which drops that root's OWN padding/border and any ancestor
  *  (e.g. `<body>`) padding above it — the host then clips the bottom of the card by
  *  exactly those lost pixels. `scrollHeight` is the full padding-box height as actually

package/src/schemas/tool-defs.ts

@@ -132,7 +132,7 @@ export interface CardToolOptions<P extends ToolProvider = ToolProvider> {
    */
   readonly strict?: boolean;
   /**
-   * Narrow the DERIVED tool schema per card type, after projection (F-23).
+   * Narrow the DERIVED tool schema per card type, after projection.
    *
    * A card's authored schema is deliberately permissive — `files` is optional on an
    * artifact, its items need only a `path` — because the card CONTRACT must accept
@@ -147,6 +147,16 @@ export interface CardToolOptions<P extends ToolProvider = ToolProvider> {
    * unknown path or a required name the node has no property for is a TypeError
    * naming the card, the path and the field, because a tool that can never be
    * satisfied must not ship quietly.
+   *
+   * IT CANNOT REACH A FORM CARD'S FIELDS, and that is a known limitation rather
+   * than an oversight. The form
+   * card's payload IS a JSON Schema, so `form.schema.json` describes `properties`
+   * as a map of field definitions and there is no node at `properties.ticketId`
+   * for a rule to land on — `require: { form: [{ path: 'properties.ticketId' }] }`
+   * raises the TypeError above, correctly. So an app cannot pin
+   * `x-kai-format: 'custom'` onto one field of a form the model authors. The
+   * enum on that hint is what makes a small model pick a valid token; an app that
+   * needs a guarantee checks the envelope when it arrives.
    */
   readonly require?: Readonly<Record<string, readonly CardRequireRule[]>>;
 }
@@ -442,7 +452,7 @@ function relaxRootCombinators(parameters: Record<string, unknown>, cardType: str
 }
 
 /**
- * Apply one card's `require` rules to its PROJECTED parameters (F-23).
+ * Apply one card's `require` rules to its PROJECTED parameters.
  *
  * Runs after `project()` and `relaxRootCombinators()`, on the copy the projection
  * built — never on the authored schema, which `registry.validate()` keeps reading.

package/src/solid.ts

@@ -53,8 +53,18 @@ export { Input } from './ui/input';
 export type { InputProps } from './ui/input';
 export { Kbd } from './ui/kbd';
 export type { KbdProps, KbdPlatform } from './ui/kbd';
+export { Checkbox } from './ui/checkbox';
+export type { CheckboxProps } from './ui/checkbox';
+export { Radio, RadioGroup } from './ui/radio';
+export type { RadioProps, RadioGroupProps, RadioOption } from './ui/radio';
+export { CheckboxGroup } from './ui/checkbox-group';
+export type { CheckboxGroupProps, CheckboxOption } from './ui/checkbox-group';
 export { Switch } from './ui/switch';
 export type { SwitchProps } from './ui/switch';
+export { Slider } from './ui/slider';
+export type { SliderProps } from './ui/slider';
+export { Select } from './ui/select';
+export type { SelectProps, SelectOption } from './ui/select';
 export { Tabs } from './ui/tabs';
 export type { TabsProps, TabsVariant, KaiTabItem } from './ui/tabs';
 export { Segmented } from './ui/segmented';
@@ -69,8 +79,8 @@ export { EditableLabel } from './ui/editable-label';
 export type { EditableLabelProps } from './ui/editable-label';
 export { Dialog } from './ui/dialog';
 export type { DialogProps, DialogController } from './ui/dialog';
-export { Dock, DockLauncherGlyph, DockCloseGlyph } from './ui/dock';
-export type { DockProps, DockController, DockPosition, DockFocusOnOpen } from './ui/dock';
+export { Dock, DockLauncherGlyph, DockCloseGlyph, DockLauncherImage } from './ui/dock';
+export type { DockProps, DockController, DockPosition, DockFocusOnOpen, DockLauncherImageProps } from './ui/dock';
 export { Popover } from './ui/popover';
 export type { PopoverProps, PopoverController } from './ui/popover';
 export { Nav } from './ui/nav';
@@ -136,6 +146,14 @@ export { ChatThread } from './components/chat-thread';
 export type { ChatThreadProps, ChatThreadController, ChatThreadContextUsage } from './components/chat-thread';
 export { Screen } from './components/screen';
 export type { ScreenProps, ScreenController } from './components/screen';
+// HomePanel / WidgetTabBar — the widget home screen (Intercom-pattern).
+// Wired into ChatThread itself behind the `home` prop (and from there into
+// `<kai-chat>`'s own `home`/`onHomeLink`); exported here too for a Solid
+// consumer composing either piece directly.
+export { HomePanel } from './components/home-panel';
+export type { HomePanelProps } from './components/home-panel';
+export { WidgetTabBar } from './components/widget-tab-bar';
+export type { WidgetTabBarProps } from './components/widget-tab-bar';
 export { Coachmark } from './components/coachmark';
 export type { CoachmarkProps, CoachmarkController } from './components/coachmark';
 export { Composer } from './components/composer';

package/src/state/index.ts

@@ -23,7 +23,7 @@ export type { ParsedThread, DroppedStored, SaveScheduler, SaveSchedulerOptions }
 // so the no-backend preview runs through the SAME parser a real provider does —
 // and is deliberately impossible to mistake for one. See ./mock.
 export { createMockResponder, DEFAULT_MOCK_REPLIES, MOCK_BANNER, MOCK_MARKER, MOCK_MARKER_KEY, MOCK_MODEL_ID } from './mock';
-export type { MockResponder, MockResponderOptions } from './mock';
+export type { MockReply, MockResponder, MockResponderOptions, MockToolCall, MockTurn } from './mock';
 
 // The content-model types every signature above mentions. Without these a
 // consumer importing only from '@kitn.ai/ui/state' cannot annotate the very

package/src/state/mock.ts

@@ -96,9 +96,42 @@ export const DEFAULT_MOCK_REPLIES: readonly string[] = [
   'Mock again. Every frame I send is tagged `_kai_mock` and my usage reports zero tokens, so nothing here can be mistaken for a real turn.',
 ];
 
+/** One scripted tool call for a mock turn. Framed exactly the way the OpenAI
+ *  chat-completions wire frames a real one — an announce fragment carrying
+ *  `id`/`function.name`, then the argument JSON streamed in fragments — so the
+ *  kit's own reader (`readOpenAIStream`) reassembles it through the same path a
+ *  real provider's call takes. */
+export interface MockToolCall {
+  /** The tool name, e.g. `'get_weather'` or a card tool like `'kai_confirm'`. */
+  name: string;
+  /** The call's arguments. Serialized with `JSON.stringify` and streamed as
+   *  fragments, like a real provider. Defaults to `{}`. */
+  arguments?: unknown;
+  /** Explicit tool-call id. Defaults to `call_kai-mock-<turn>-<n>`, which keeps
+   *  the mock's naming tell (see tell 3): no provider issues ids in that shape. */
+  id?: string;
+}
+
+/** A scripted mock turn: optional text, then optional tool calls. A turn with
+ *  tool calls finishes `finish_reason: 'tool_calls'`, exactly as a real
+ *  tool-calling turn does; a turn without them finishes `'stop'`. */
+export interface MockTurn {
+  /** Text streamed (token by token) before the tool calls. */
+  text?: string;
+  /** Tool calls announced this turn, in order. */
+  toolCalls?: readonly MockToolCall[];
+}
+
+/** A canned reply: plain text, or a scripted turn. A string is exactly
+ *  `{ text }` — the pre-tool-call API unchanged. */
+export type MockReply = string | MockTurn;
+
 export interface MockResponderOptions {
-  /** Canned replies, cycled one per turn. Defaults to `DEFAULT_MOCK_REPLIES`. */
-  replies?: readonly string[];
+  /** Canned replies, cycled one per turn. Plain strings stream as text; a
+   *  `MockTurn` can also script tool calls (`{ text, toolCalls }`), which is
+   *  what lets the zero-config mock exercise the kit's tool/card path without
+   *  hand-rolled SSE framing. Defaults to `DEFAULT_MOCK_REPLIES`. */
+  replies?: readonly MockReply[];
   /** Delay between chunks, in ms. Defaults to 24 — fast enough to feel alive,
    *  slow enough that the streaming is visible. `0` streams as fast as the
    *  event loop allows, which is what tests want. */
@@ -144,6 +177,27 @@ function frame(id: string, body: Record<string, unknown>): string {
 const delay = (ms: number): Promise<void> =>
   ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve();
 
+/** Normalize a canned reply: a plain string is exactly `{ text }`. */
+const asTurn = (reply: MockReply): MockTurn => (typeof reply === 'string' ? { text: reply } : reply);
+
+/** How many characters of argument JSON ride in each tool-call fragment. Small
+ *  enough that any realistic argument object spans several frames, so the
+ *  reader's fragment-reassembly path — the one a real provider exercises — is
+ *  exercised here too, rather than a single-frame shortcut it would never see
+ *  in production. */
+const TOOL_ARG_FRAGMENT_CHARS = 16;
+
+/** Split argument JSON into the fragments a provider streams. Never empty: an
+ *  empty-object call still sends its `'{}'` so the reader has arguments to
+ *  parse. */
+function argumentFragments(json: string): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < json.length; i += TOOL_ARG_FRAGMENT_CHARS) {
+    out.push(json.slice(i, i + TOOL_ARG_FRAGMENT_CHARS));
+  }
+  return out.length > 0 ? out : [''];
+}
+
 /**
  * Build a mock responder.
  *
@@ -170,8 +224,9 @@ export function createMockResponder(options: MockResponderOptions = {}): MockRes
   let announced = false;
 
   return function respond(_prompt?: string): AsyncIterable<string> {
-    const reply = pool[turn % pool.length];
+    const scripted = asTurn(pool[turn % pool.length]);
     const id = `kai-mock-${turn + 1}`;
+    const turnNumber = turn + 1;
     turn += 1;
 
     return {
@@ -193,15 +248,46 @@ export function createMockResponder(options: MockResponderOptions = {}): MockRes
         // exercises the reader's empty-delta path.
         yield frame(id, { choices: [{ index: 0, delta: { role: 'assistant' }, finish_reason: null }] });
 
-        for (const token of tokenize(reply, chunkSize)) {
+        for (const token of tokenize(scripted.text ?? '', chunkSize)) {
           await delay(delayMs);
           yield frame(id, { choices: [{ index: 0, delta: { content: token }, finish_reason: null }] });
         }
 
+        // Scripted tool calls, framed the way the OpenAI wire frames real ones:
+        // one announce fragment per call (`index`/`id`/`function.name` + empty
+        // arguments), then the argument JSON in fragments. The kit's reader
+        // reassembles them through the exact path a real provider's call takes.
+        const toolCalls = scripted.toolCalls ?? [];
+        for (let index = 0; index < toolCalls.length; index += 1) {
+          const call = toolCalls[index];
+          // Tell 3's shape, extended to call ids: no provider issues these.
+          const callId = call.id ?? `call_${MOCK_MODEL_ID}-${turnNumber}-${index + 1}`;
+          await delay(delayMs);
+          yield frame(id, {
+            choices: [{
+              index: 0,
+              delta: { tool_calls: [{ index, id: callId, function: { name: call.name, arguments: '' } }] },
+              finish_reason: null,
+            }],
+          });
+          for (const fragment of argumentFragments(JSON.stringify(call.arguments ?? {}))) {
+            await delay(delayMs);
+            yield frame(id, {
+              choices: [{
+                index: 0,
+                delta: { tool_calls: [{ index, function: { arguments: fragment } }] },
+                finish_reason: null,
+              }],
+            });
+          }
+        }
+
         // Tell 4: zero usage. A real turn that produced this much text cannot
-        // report zero completion tokens.
+        // report zero completion tokens. A turn that announced tool calls ends
+        // `tool_calls`, exactly as a real one does, so the consumer's tool loop
+        // branches the same way it would against a provider.
         yield frame(id, {
-          choices: [{ index: 0, delta: {}, finish_reason: 'stop' }],
+          choices: [{ index: 0, delta: {}, finish_reason: toolCalls.length > 0 ? 'tool_calls' : 'stop' }],
           usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
         });
         yield 'data: [DONE]\n\n';

package/src/types.ts

@@ -37,10 +37,29 @@ export interface ConversationSummary {
   /** Fallback for the auto relative time when updatedAt is absent. */
   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 text describing the row's content, read differently by the two
+   *  built-in list surfaces (both optional, same field — no widened shape):
+   *  the desktop `ConversationList`/`ConversationItem` renders it right-aligned
+   *  as a count/status/"days ago" and auto-derives a short relative time from
+   *  `updatedAt` (fallback `lastMessageAt`) when it's absent; the widget-box
+   *  `ConversationPanel` list view (owner rework, 2026-08-26) renders it as the
+   *  one-line last-message preview under the title instead — that view always
+   *  computes its own right-aligned relative time from `updatedAt` separately,
+   *  since a box that size has no room for a third line. `localStorageStore`
+   *  writes it as the ~80-char truncated last-message preview on every save
+   *  (`primitives/conversation-store.ts`). */
   trailing?: string;
+  /** ISO timestamp of when this conversation was last SEEN by the visitor
+   *  (widened additively, 2026-08-26 — unread indicators; no existing field
+   *  fit, since `trailing`/`lastMessageAt`/`updatedAt` are all content-timing
+   *  facts, not viewing-state). Unread = `updatedAt` is later than this.
+   *  Written by `ConversationStore.markRead` (see that doc for exactly when
+   *  and for the decide-loudly default when a store never implements it —
+   *  an absent `lastReadAt` reads as "not unread," never as "definitely
+   *  unread," so a store that doesn't support the concept at all simply
+   *  never shows an indicator rather than guessing). Round-tripped through
+   *  `list()`/`save()`; never author this by hand. */
+  lastReadAt?: string;
 }
 
 export interface ConversationGroup {
@@ -51,3 +70,26 @@ export interface ConversationGroup {
   sortOrder: number;
   createdAt: string;
 }
+
+/** One row in a `HomeConfig.links` list — a "docs" / "talk to sales" style
+ *  entry. `href` is optional: with it, the row renders as a link (subject to
+ *  `isSafeUrl`); without it, the row is a button that emits itself via
+ *  `HomePanelProps.onLink`. `icon` is either a `renderIcon` name or a safe
+ *  URL, same resolution `renderIcon` already does for every other icon prop
+ *  in the kit. */
+export interface HomeLinkEntry {
+  label: string;
+  href?: string;
+  description?: string;
+  icon?: string;
+}
+
+/** The widget home screen's JSON-shaped config (Intercom-pattern home tab).
+ *  Consumed by `ChatThread`'s `home` prop, which wires it into `HomePanel`/
+ *  `WidgetTabBar` and, from there, into `<kai-chat>`'s own `home` property. */
+export interface HomeConfig {
+  greeting?: { title?: string; subtitle?: string };
+  recentConversation?: boolean;
+  newConversation?: { label?: string };
+  links?: HomeLinkEntry[];
+}

package/src/ui/agent-card.tsx

@@ -156,7 +156,7 @@ export function AgentCard(props: AgentCardProps) {
           />
         </span>
         <Show when={local.status.label}>
-          <span class={cn('text-[11px] font-medium leading-none', TONE_TEXT[tone()])}>
+          <span class={cn('text-caption font-medium leading-none', TONE_TEXT[tone()])}>
             {local.status.label}
           </span>
         </Show>
@@ -185,7 +185,7 @@ export function AgentCard(props: AgentCardProps) {
 
       <span class="flex shrink-0 items-center gap-2">
         <Show when={local.needsAttention}>
-          <span class="inline-flex items-center gap-1 rounded-full bg-tool-amber/15 px-2 py-0.5 text-[11px] font-medium text-tool-amber">
+          <span class="inline-flex items-center gap-1 rounded-full bg-tool-amber/15 px-2 py-0.5 text-caption font-medium leading-none text-tool-amber">
             <Bell class="size-3" aria-hidden="true" />
             Needs you
           </span>

package/src/ui/avatar.tsx

@@ -8,7 +8,7 @@ export interface AvatarProps extends JSX.HTMLAttributes<HTMLDivElement> {
   size?: 'sm' | 'md' | 'lg';
 }
 
-const sizeClasses = { sm: 'h-6 w-6 text-[10px]', md: 'h-8 w-8 text-xs', lg: 'h-10 w-10 text-sm' };
+const sizeClasses = { sm: 'h-6 w-6 text-micro', md: 'h-8 w-8 text-xs', lg: 'h-10 w-10 text-sm' };
 
 export function Avatar(props: AvatarProps) {
   const [local, rest] = splitProps(props, ['src', 'alt', 'fallback', 'size', 'class']);

package/src/ui/checkbox-group.tsx

@@ -0,0 +1,153 @@
+import { type JSX, For, Show, splitProps } from 'solid-js';
+import { cn } from '../utils/cn';
+import { Checkbox } from './checkbox';
+
+/** One choice in a {@link CheckboxGroup}. */
+export interface CheckboxOption<T = string> {
+  /** The value this row selects. Compared to the group's `value` by identity. */
+  value: T;
+  /** The row's visible label. */
+  label: JSX.Element;
+  /** Optional second line under the label. */
+  description?: JSX.Element;
+  /** Disable this row alone (the group's `disabled` disables all of them). */
+  disabled?: boolean;
+}
+
+export interface CheckboxGroupProps<T = string>
+  extends Omit<JSX.HTMLAttributes<HTMLDivElement>, 'onChange' | 'children'> {
+  /**
+   * The choices, in display order. Rendered in full: the kit never truncates,
+   * re-orders or de-duplicates a consumer's option list.
+   */
+  options: readonly CheckboxOption<T>[];
+  /** The selected values. Each option is checked when its `value` is in here (by identity). */
+  value?: readonly T[];
+  /**
+   * The shared form-control name every box in the group carries, so a native form
+   * submits the whole selection under one key and `FormData.getAll(name)` reads it back.
+   *
+   * UNLIKE {@link RadioGroup}, this has no default. A radio group needs a shared `name`
+   * for the browser to make the set exclusive and arrow-navigable, so one is generated
+   * when none is given; checkboxes are independent controls and need nothing to behave
+   * correctly. Generating a name here would submit the selection under a random key,
+   * which is worse than submitting nothing.
+   */
+  name?: string;
+  /** Disable every row. */
+  disabled?: boolean;
+  /** Accessible name for the group. Rendered as `aria-label` on the `group`. */
+  label?: string;
+  /**
+   * Fires on every toggle with the NEXT selection, plus the option that moved and
+   * which way it went. The next selection is a fresh array — the group holds no state
+   * of its own, so `value` is yours to own.
+   */
+  onChange?: (value: T[], option: CheckboxOption<T>, checked: boolean) => void;
+  /** Fires when a box loses focus — the commit point for a form field. */
+  onOptionBlur?: () => void;
+  /** Extra classes for each row. */
+  itemClass?: string;
+  /**
+   * Presentation slot. Replaces the default label/description column with whatever
+   * you return, so a row can carry media, a badge or a price without a second
+   * checkbox component existing. The control, the row chrome and the group semantics
+   * stay ours.
+   */
+  children?: (option: CheckboxOption<T>, state: { checked: boolean; disabled: boolean }) => JSX.Element;
+}
+
+/**
+ * A vertical set of checkbox rows in a bordered, divided list — the kit's standard
+ * "pick any number" control, and {@link RadioGroup}'s sibling: same options shape,
+ * same row chrome, same presentation slot, multi-value instead of single.
+ *
+ * Every row is a real `<input type="checkbox">` inside a `<label>`, so clicking
+ * anywhere on the row toggles it and the keyboard behaviour (a tab stop per box,
+ * Space to toggle) is the browser's rather than a reimplementation. The wrapper is
+ * `role="group"`, not `role="listbox"`: the boxes are independent controls and
+ * nothing here overrides what they already announce.
+ *
+ * Everything not listed in `CheckboxGroupProps` is forwarded to the group element, so
+ * `id`, `aria-labelledby`, any other `aria-*` and any `data-*` hook land where a form
+ * expects them. No validation is applied — "at least one" is your application's rule,
+ * not the kit's.
+ *
+ * ```tsx
+ * <CheckboxGroup
+ *   label="Environments"
+ *   name="env"
+ *   options={[{ value: 'prod', label: 'Production' }, { value: 'staging', label: 'Staging' }]}
+ *   value={envs()}
+ *   onChange={setEnvs}
+ * />
+ * ```
+ */
+export function CheckboxGroup<T = string>(props: CheckboxGroupProps<T>): JSX.Element {
+  const [local, rest] = splitProps(props, [
+    'options', 'value', 'name', 'disabled', 'label', 'onChange', 'onOptionBlur', 'itemClass', 'children', 'class',
+  ]);
+  const selected = (): readonly T[] => local.value ?? [];
+  return (
+    <div
+      {...rest}
+      role="group"
+      aria-label={local.label}
+      class={cn('divide-y divide-border overflow-hidden rounded-lg border border-border', local.class)}
+    >
+      <For each={local.options}>
+        {(opt) => {
+          const checked = () => selected().includes(opt.value);
+          const rowDisabled = () => !!(local.disabled || opt.disabled);
+          return (
+            <label
+              class={cn(
+                'flex cursor-pointer items-center gap-3 px-3 py-2.5 text-sm transition-colors',
+                opt.description !== undefined && 'items-start',
+                checked()
+                  ? 'bg-accent font-medium text-accent-foreground'
+                  : 'text-foreground hover:bg-muted/50',
+                local.itemClass,
+              )}
+            >
+              <Checkbox
+                name={local.name}
+                value={String(opt.value)}
+                checked={checked()}
+                disabled={rowDisabled()}
+                class={opt.description === undefined ? undefined : 'mt-0.5'}
+                onChange={(e) => {
+                  const on = e.currentTarget.checked;
+                  const now = selected();
+                  // Filter-or-append rather than a toggle on the previous array, so the
+                  // emitted selection follows the CONTROL's state. They diverge when the
+                  // caller re-renders mid-interaction, and following the box is what a
+                  // native form would report.
+                  const next = on ? [...now.filter((v) => v !== opt.value), opt.value] : now.filter((v) => v !== opt.value);
+                  local.onChange?.(next, opt, on);
+                }}
+                onBlur={() => local.onOptionBlur?.()}
+              />
+              <Show
+                when={local.children}
+                fallback={
+                  // No description, a bare <span> — byte for byte what the form's
+                  // hand-rolled checkbox list rendered before this component existed.
+                  // The two-line column only appears when there is a second line.
+                  <Show when={opt.description !== undefined} fallback={<span>{opt.label}</span>}>
+                    <span class="flex flex-col gap-0.5">
+                      <span>{opt.label}</span>
+                      <span class="text-xs font-normal text-muted-foreground">{opt.description}</span>
+                    </span>
+                  </Show>
+                }
+              >
+                {(render) => render()(opt, { checked: checked(), disabled: rowDisabled() })}
+              </Show>
+            </label>
+          );
+        }}
+      </For>
+    </div>
+  );
+}