@kitn.ai/ui 0.25.2 → 0.27.0

package/src/state/persistence.ts

@@ -0,0 +1,180 @@
+// src/state/persistence.ts — the mechanical halves of the persistence story.
+//
+// The boundary (spec §1, CLAUDE.md): persistence POLICY — what is stored,
+// where, for how long, under what quota — is the app's. What lives here is
+// only the mechanics every such app re-derives by hand: validating a stored
+// thread back into `ChatMessage[]` (F-18), and the debounce/flush shape that
+// keeps a per-token stream from hitting storage per token. No storage call,
+// no fetch, no DOM; the save fn, the delay, and the reaction to a drop are
+// all the consumer's.
+import type { ChatMessage, FeedbackVote, MessagePart } from '../elements/chat-types';
+
+/** One record the parse refused, and why. Deciding loudly is the caller's
+ *  verb (warn, reject the whole record, count it); this is the information
+ *  that a quiet version would withhold. */
+export interface DroppedStored {
+  at: 'thread' | 'message' | 'part';
+  reason: string;
+  value: unknown;
+}
+
+export interface ParsedThread {
+  messages: ChatMessage[];
+  /** Empty on a clean parse. Never silently shorter output than input. */
+  dropped: DroppedStored[];
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null;
+}
+
+/**
+ * One payload check per `MessagePart` variant. The key set is DERIVED from the
+ * union in `src/elements/chat-types.ts` at compile time: `satisfies
+ * Record<MessagePart['type'], …>` makes a missing key (a 7th variant landed)
+ * and a stale key (a variant renamed away) each a type error in THIS file —
+ * the same union `lint:silent-drops` and `verify:scaffold` read, so the lists
+ * cannot disagree. The behavioral cross-check lives in ./persistence.test.ts,
+ * which re-reads the union by a deliberately different method.
+ *
+ * These are shape checks, not a trust boundary for rendering: a rehydrated
+ * part is model output twice over (it was model output before it was
+ * hand-editable storage), and it stays safe to draw because the elements are
+ * what draw it. What this buys is that a truncated or half-written record
+ * reaches the element as a well-formed thread minus the broken piece, instead
+ * of as `parts: undefined` taking the whole app down on first render.
+ */
+const PART_VALIDATORS = {
+  text: (v) => typeof v.text === 'string',
+  reasoning: (v) => typeof v.text === 'string',
+  tool: (v) => isRecord(v.tool),
+  card: (v) => isRecord(v.envelope) && typeof v.envelope.type === 'string' && typeof v.envelope.id === 'string',
+  source: (v) => isRecord(v.source),
+  file: (v) => isRecord(v.attachment),
+} satisfies Record<MessagePart['type'], (v: Record<string, unknown>) => boolean>;
+
+function parsePart(v: unknown, dropped: DroppedStored[]): MessagePart | null {
+  if (!isRecord(v) || typeof v.type !== 'string') {
+    dropped.push({ at: 'part', reason: 'not a part record', value: v });
+    return null;
+  }
+  const validate = (PART_VALIDATORS as Record<string, (v: Record<string, unknown>) => boolean>)[v.type];
+  if (!validate) {
+    // An unknown `type` is dropped rather than passed on: every renderer and
+    // encoder switches on it and has no branch for a made-up one.
+    dropped.push({ at: 'part', reason: `unknown part type "${v.type}"`, value: v });
+    return null;
+  }
+  if (!validate(v)) {
+    dropped.push({ at: 'part', reason: `missing or invalid payload for "${v.type}" part`, value: v });
+    return null;
+  }
+  // Verbatim, not rebuilt: optional fields the variants carry (`raw`,
+  // `signature`, `index`, …) are load-bearing on the wire re-encode, so the
+  // validated record passes through whole.
+  return v as unknown as MessagePart;
+}
+
+function parseMessage(v: unknown, dropped: DroppedStored[]): ChatMessage | null {
+  if (!isRecord(v) || typeof v.id !== 'string' || (v.role !== 'user' && v.role !== 'assistant') || !Array.isArray(v.parts)) {
+    dropped.push({ at: 'message', reason: 'not a message record (id/role/parts)', value: v });
+    return null;
+  }
+  const parts = v.parts
+    .map((p) => parsePart(p, dropped))
+    .filter((p): p is MessagePart => p !== null);
+  if (parts.length === 0) {
+    // A message whose every part was unreadable is an empty bubble, and the
+    // per-part entries above already say what was lost.
+    dropped.push({ at: 'message', reason: 'no readable parts survived', value: v });
+    return null;
+  }
+  const message: ChatMessage = { id: v.id, role: v.role, parts };
+  if (v.feedback === 'like' || v.feedback === 'dislike') message.feedback = v.feedback as FeedbackVote;
+  if (isRecord(v.avatar)) message.avatar = v.avatar;
+  if (Array.isArray(v.actions)) message.actions = v.actions as ChatMessage['actions'];
+  return message;
+}
+
+/**
+ * Validate a stored thread — the JSON-parsed value of one thread's messages
+ * array — back into `ChatMessage[]`. Never throws: unreadable records are
+ * DROPPED and reported in `dropped`, so a truncated write loses one record,
+ * not every conversation. What to DO about a drop (warn, discard the whole
+ * record, telemetry) is the caller's policy.
+ */
+export function parseStoredThread(value: unknown): ParsedThread {
+  const dropped: DroppedStored[] = [];
+  if (!Array.isArray(value)) {
+    return { messages: [], dropped: [{ at: 'thread', reason: 'stored thread is not an array', value }] };
+  }
+  const messages = value
+    .map((m) => parseMessage(m, dropped))
+    .filter((m): m is ChatMessage => m !== null);
+  return { messages, dropped };
+}
+
+export interface SaveSchedulerOptions {
+  /** The quiet period before a scheduled snapshot is written. This is policy
+   *  and therefore REQUIRED — the kit ships no default debounce. */
+  delayMs: number;
+  /** The scheduler the seam runs on. Defaults to the global timers; inject
+   *  your own for tests or a non-timer scheduler. */
+  setTimeout?: (fn: () => void, ms: number) => unknown;
+  clearTimeout?: (handle: unknown) => void;
+}
+
+export interface SaveScheduler<T> {
+  /** Remember `snapshot` as the latest state and (re)start the quiet-period
+   *  timer. Call it on every state change; only the last snapshot inside the
+   *  quiet period is written. */
+  schedule(snapshot: T): void;
+  /** Write the pending snapshot NOW and disarm the timer — the
+   *  `beforeunload`/`visibilitychange` story, so a tab closed mid-stream still
+   *  persists. No-op when nothing is pending: the last write already happened. */
+  flush(): void;
+  /** Drop the pending write unsaved (e.g. unmount-without-persist). */
+  cancel(): void;
+  pending(): boolean;
+}
+
+/**
+ * The debounce/flush seam: a streaming reply lands a state update per token,
+ * and without this shape so would the consumer's storage backend. The kit owns
+ * only the timer dance; `save` (WHAT and WHERE, including its own try/catch
+ * policy for quota errors) and `delayMs` (HOW LONG) are the consumer's.
+ */
+export function createSaveScheduler<T>(save: (snapshot: T) => void, opts: SaveSchedulerOptions): SaveScheduler<T> {
+  const setTimer = opts.setTimeout ?? ((fn: () => void, ms: number) => setTimeout(fn, ms));
+  const clearTimer = opts.clearTimeout ?? ((handle: unknown) => clearTimeout(handle as ReturnType<typeof setTimeout>));
+
+  let latest: T | undefined;
+  let armed = false;
+  let handle: unknown;
+
+  const disarm = () => {
+    if (!armed) return;
+    clearTimer(handle);
+    armed = false;
+  };
+  const write = () => {
+    armed = false;
+    save(latest as T);
+  };
+
+  return {
+    schedule(snapshot) {
+      latest = snapshot;
+      disarm();
+      handle = setTimer(write, opts.delayMs);
+      armed = true;
+    },
+    flush() {
+      if (!armed) return;
+      disarm();
+      save(latest as T);
+    },
+    cancel: disarm,
+    pending: () => armed,
+  };
+}

package/src/state/stream.ts

@@ -116,6 +116,56 @@ export interface AssistantStream {
    * assignability already holds. Measurements and the trade: boundary point 2. */
   addFile(attachment: AttachmentData): AssistantStream;
   done(): void;
+  /** Settles the turn as FAILED and puts `reason` where the reader can find it.
+   *
+   *  WHERE THE REASON LANDS, in order:
+   *  1. every tool part that has NOT produced a result flips to `output-error`
+   *     with `errorText: reason`, so no panel spins forever. A tool ALREADY in
+   *     `output-error` with its own non-empty `errorText` is left exactly as it
+   *     is: "search index offline" is the answer to what went wrong and
+   *     "Connection lost." is the generic outer symptom, so overwriting the
+   *     specific with the generic loses the only actionable thing on the
+   *     message. It still counts as carrying the failure. A tool in
+   *     `output-error` with NO text does get filled in — an error panel with
+   *     nothing in it says no more than a blank bubble does.
+   *  2. if no part was able to carry it, the reason is APPENDED as its own text
+   *     part.
+   *
+   *  Never both — a turn does not report the same failure twice.
+   *
+   *  "Where the reader can FIND it" is deliberate, and rule 1 and rule 2 are not
+   *  equally loud. Rule 2 is text in the thread: read without any interaction.
+   *  Rule 1 is a tool panel, which renders COLLAPSED — the header shows an error
+   *  icon and a badge, so the failure is unmissable, but the `errorText` itself
+   *  is one click away. That is the right default for a failed tool inside an
+   *  otherwise readable answer, and it is why rule 2 exists rather than always
+   *  stamping the panel and calling it reported.
+   *
+   *  Rule 2 is the whole point and it used to be missing. `abort` only ever did
+   *  rule 1, so a TEXT-ONLY turn — every turn of a text-only support widget —
+   *  had nothing to stamp: the string was discarded and a failed request
+   *  rendered an EMPTY assistant bubble, while the consumer that passed a
+   *  perfectly good sentence believed it had reported the failure. That is the
+   *  repo's "decide loudly" rule broken on the one path where being quiet is
+   *  worst, and it shipped because the discard is invisible from the call site.
+   *
+   *  It is a NEW part, never a merge onto the trailing text: gluing "Connection
+   *  lost." onto the model's half-finished sentence reads as the model saying
+   *  it. Text that already streamed stays exactly where it is.
+   *
+   *  The reason is TRIMMED, and `abort()` with no reason — or one that is empty
+   *  or all whitespace — appends nothing: there is no reason to discard, and the
+   *  kit will not invent copy the consumer did not write. Rule 1 still runs,
+   *  with `errorText: undefined`. Whitespace is not a pedantic case here: the
+   *  scaffold hands over `err.message`, and an `Error` is free to carry `''`,
+   *  which would otherwise render an INVISIBLE text part — a blank bubble that
+   *  also claims to have said something.
+   *
+   *  Settled is settled: after `done()` or a first `abort()`, this is a no-op
+   *  like every other mutator, so the reason cannot be appended twice.
+   *
+   *  The reason is CONSUMER-facing text and is rendered as markdown like any
+   *  other text part. Pass a sentence a visitor can read, not a stack trace. */
   abort(reason?: string): void;
 }
 
@@ -151,10 +201,27 @@ export function createAssistantStream(
     addFile(attachment) { mutate((p) => [...p, { type: 'file', attachment }]); return stream; },
     done() { settled = true; },
     abort(reason) {
-      mutate((p) => p.map((part) =>
-        part.type === 'tool' && part.tool.state !== 'output-available'
-          ? { ...part, tool: { ...part.tool, state: 'output-error' as const, errorText: reason } }
-          : part));
+      // Whitespace-only is the same nothing as empty. `err.message` on a thrown
+      // Error is free to be either, and appending it would render an INVISIBLE
+      // text part -- a blank bubble that also claims to have said something.
+      const text = reason?.trim() || undefined;
+      mutate((p) => {
+        let carried = false;
+        const next = p.map((part) => {
+          if (part.type !== 'tool' || part.tool.state === 'output-available') return part;
+          // Already showing its own, more specific failure: keep it, and count
+          // it as carrying. See the note above `abort`.
+          if (part.tool.state === 'output-error' && part.tool.errorText?.trim()) {
+            carried = true;
+            return part;
+          }
+          carried = true;
+          return { ...part, tool: { ...part.tool, state: 'output-error' as const, errorText: text } };
+        });
+        // The reason has to land SOMEWHERE. See the note above `abort`.
+        if (carried || !text) return next;
+        return [...next, { type: 'text', text }];
+      });
       settled = true;
     },
   };

package/src/state/threads.ts

@@ -0,0 +1,142 @@
+// src/state/threads.ts — the thread-switching fold.
+//
+// The identity category from the workspace glue inventory (spec §1/§3b): an
+// id-bound `SetMessages`, per-thread loading state, the abort map, and
+// delete-under-stream safety. Pure folds + callbacks per the state charter —
+// no fetch, no DOM, no storage; the only state a helper here owns is the
+// irreducible kind (which turns are in flight), never the consumer's records.
+import type { ChatMessage } from '../elements/chat-types';
+import type { SetMessages } from './stream';
+
+/** The minimal thread record the fold needs. The consumer's own record type
+ *  (title, timestamps, whatever its storage keeps) extends this — those fields
+ *  are policy and stay outside the kit. */
+export interface ThreadLike {
+  id: string;
+  messages: ChatMessage[];
+}
+
+/** The functional-updater setter over the whole thread LIST — the same
+ *  React-setState shape `SetMessages` is, one level up. */
+export type SetThreads<T extends ThreadLike> = (updater: (prev: T[]) => T[]) => void;
+
+export interface BindThreadOptions<T extends ThreadLike> {
+  /** Stamp the changed record (e.g. `updatedAt`). Runs on a hit only. Kept a
+   *  callback because WHAT gets stamped — and with whose clock — is the
+   *  consumer's record shape, not ours. */
+  touch?: (thread: T) => T;
+  /** A delta arrived for a thread that is no longer in the list (deleted while
+   *  its reply was streaming). The delta is dropped either way — dropping is
+   *  the only correct fold — but the drop is reported, not silent. */
+  onDrop?: (threadId: string) => void;
+}
+
+/**
+ * Pure fold: apply `updater` to the messages of thread `id` within a list.
+ *
+ * reactivity-two-halves (CLAUDE.md): the hit gets a NEW containing array
+ * (which notifies) and a NEW record object (which makes the change visible);
+ * every other record keeps its reference. A MISS returns `threads` itself —
+ * the same reference — so a late delta for a deleted thread re-renders
+ * nothing and resurrects nothing.
+ */
+export function updateThreadMessages<T extends ThreadLike>(
+  threads: T[],
+  id: string,
+  updater: (prev: ChatMessage[]) => ChatMessage[],
+  opts: BindThreadOptions<T> = {},
+): T[] {
+  let hit = false;
+  const next = threads.map((t) => {
+    if (t.id !== id) return t;
+    hit = true;
+    const updated = { ...t, messages: updater(t.messages) };
+    return opts.touch ? opts.touch(updated) : updated;
+  });
+  if (!hit) {
+    opts.onDrop?.(id);
+    return threads;
+  }
+  return next;
+}
+
+/**
+ * A `SetMessages` bound to ONE thread. Capture the id when the user hits send
+ * and hand the result to `createAssistantStream`: the reply then lands in the
+ * thread that was open at send time, never whichever one is open when the
+ * tokens arrive — which is what makes switching away mid-reply (and coming
+ * back to a finished answer) safe.
+ */
+export function bindThreadMessages<T extends ThreadLike>(
+  setThreads: SetThreads<T>,
+  id: string,
+  opts: BindThreadOptions<T> = {},
+): SetMessages {
+  return (updater) => {
+    setThreads((prev) => updateThreadMessages(prev, id, updater, opts));
+  };
+}
+
+/** The in-flight-turn bookkeeping for a multi-thread app: which threads are
+ *  streaming, and the AbortController for each. See `createThreadSessions`. */
+export interface ThreadSessions {
+  /** Register a new in-flight turn. One turn per thread: a prior in-flight
+   *  turn for the SAME thread is aborted first. Pass the returned controller's
+   *  `signal` to your fetch — the fetch line itself stays yours. */
+  begin(threadId: string): AbortController;
+  /** The turn settled (done or failed) — call from your `finally`. `controller`
+   *  is required so a slow old turn's cleanup cannot clear a newer turn that
+   *  has since begun on the same thread: a stale controller is a no-op. */
+  end(threadId: string, controller: AbortController): void;
+  /** Cancel the in-flight turn (the delete-under-stream story): aborts the
+   *  controller and clears the streaming state. Returns whether anything was
+   *  actually in flight. Pair it with the id-bound sink above, which drops any
+   *  deltas that were already past the abort. */
+  abort(threadId: string): boolean;
+  isStreaming(threadId: string): boolean;
+  /** A fresh array snapshot each call — safe to hand straight to a setState. */
+  streamingIds(): string[];
+}
+
+/**
+ * Create the session tracker. `onChange` fires with a fresh `streamingIds()`
+ * snapshot after every transition — mirror it into your framework's state to
+ * derive `loading` (`sessions.isStreaming(activeId)` is the per-thread flag a
+ * single boolean cannot be, because a stream keeps running when you switch
+ * away).
+ *
+ * This is the one stateful object in the module, because an abort map is
+ * irreducibly stateful; it still does no I/O and owns no timer.
+ */
+export function createThreadSessions(onChange?: (streamingIds: string[]) => void): ThreadSessions {
+  const inFlight = new Map<string, AbortController>();
+  const snapshot = () => Array.from(inFlight.keys());
+  const notify = () => onChange?.(snapshot());
+
+  return {
+    begin(threadId) {
+      inFlight.get(threadId)?.abort();
+      const controller = new AbortController();
+      inFlight.set(threadId, controller);
+      notify();
+      return controller;
+    },
+    end(threadId, controller) {
+      if (inFlight.get(threadId) !== controller) return;
+      inFlight.delete(threadId);
+      notify();
+    },
+    abort(threadId) {
+      const controller = inFlight.get(threadId);
+      if (!controller) return false;
+      controller.abort();
+      inFlight.delete(threadId);
+      notify();
+      return true;
+    },
+    isStreaming(threadId) {
+      return inFlight.has(threadId);
+    },
+    streamingIds: snapshot,
+  };
+}

package/src/types.ts

@@ -31,9 +31,11 @@ export interface ConversationSummary {
   id: string;
   title: string;
   groupId?: string;
-  scope: ConversationScope;
+  /** Only meaningful to scope-aware consumers; the list never reads it. */
+  scope?: ConversationScope;
   messageCount: number;
-  lastMessageAt: string;
+  /** 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`

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>
+  );
+}

package/src/ui/checkbox.tsx

@@ -0,0 +1,63 @@
+import { type JSX, splitProps, createEffect } from 'solid-js';
+import { cn } from '../utils/cn';
+
+export interface CheckboxProps extends Omit<JSX.InputHTMLAttributes<HTMLInputElement>, 'type' | 'children'> {
+  /**
+   * The mixed / partially-checked state ("some of the things below are ticked").
+   *
+   * `indeterminate` is a DOM PROPERTY with no HTML attribute, so it cannot be set
+   * from markup — every caller that wanted it used to reach for a `ref` plus a
+   * `createEffect`. That effect now lives in here, once, and callers pass a prop.
+   *
+   * Note that the property is purely visual plus an accessibility hint: a checkbox
+   * whose `indeterminate` is true still reports `checked === false` and submits
+   * accordingly. A native indeterminate checkbox already announces as "mixed", so
+   * this component does not stamp `aria-checked="mixed"` on top of it — pass one
+   * yourself if you also want the attribute in the DOM.
+   */
+  indeterminate?: boolean;
+}
+
+/**
+ * A checkbox. A REAL `<input type="checkbox">` behind `appearance: none`, styled by
+ * the kit's `.kai-checkbox` rule, never a `<div>` wearing `role="checkbox"`.
+ *
+ * That is the whole design: the native control brings keyboard operation (Space),
+ * the `:focus-visible` ring, form participation via `name` / `value`, and correct
+ * screen-reader announcement — all of it for free and all of it correct. Every
+ * accessibility defect this kit's control audit found was in a control that had
+ * replaced the native element with something hand-rolled.
+ *
+ * Everything not listed in `CheckboxProps` is forwarded to the input, so `id`,
+ * `name`, `value`, `required`, `disabled`, `aria-*` and any `data-*` hook behave
+ * exactly as they do on a plain `<input>`.
+ *
+ * Validation is deliberately absent. `required` is passed through to the native
+ * attribute and nothing else — whether an unchecked box is an error is the
+ * consuming application's call, not the kit's.
+ *
+ * ```tsx
+ * <Checkbox name="notify" checked={on()} onChange={(e) => setOn(e.currentTarget.checked)} />
+ * ```
+ */
+export function Checkbox(props: CheckboxProps): JSX.Element {
+  const [local, rest] = splitProps(props, ['class', 'indeterminate', 'ref']);
+  return (
+    <input
+      {...rest}
+      type="checkbox"
+      class={cn('kai-checkbox', local.class)}
+      ref={(el) => {
+        // `ref` is split out and re-applied by hand because this component needs the
+        // element for `indeterminate` as well. Solid always hands a component a ref
+        // FUNCTION (a variable ref compiles into one), so the typeof guard is for the
+        // hand-written object case only.
+        const forward = local.ref;
+        if (typeof forward === 'function') (forward as (el: HTMLInputElement) => void)(el);
+        createEffect(() => {
+          el.indeterminate = !!local.indeterminate;
+        });
+      }}
+    />
+  );
+}