@kitn.ai/ui 0.20.0 → 0.21.0

package/src/components/card-renderer.tsx

@@ -2,17 +2,85 @@
 // The Solid single-envelope dispatcher: pick the card for envelope.type and render it
 // with the envelope spread onto its props. Routing uses the ambient CardProvider
 // (useCardHost). Unknown type → CardFallback + a one-shot contract `error` emit.
-import { createMemo, untrack, Show, type JSX } from 'solid-js';
+// Invalid data → two-tier validation, mirroring the remote transport; see below.
+import { createEffect, createMemo, untrack, Show, type JSX } from 'solid-js';
 import { Dynamic } from 'solid-js/web';
 import type { CardEnvelope } from '../primitives/card-contract';
 import { useCardHost } from '../primitives/card-host';
-import { mergeCardComponents, type CardComponentMap } from '../primitives/card-registry';
+import { BUILTIN_CARD_COMPONENTS, mergeCardComponents, type CardComponentMap } from '../primitives/card-registry';
+import type { JsonSchema } from '../primitives/card-validate';
+import { cardValidationMessage, validateCardData, type CardValidationReport } from '../primitives/card-validate-cards';
 import { CardFallback } from './card-fallback';
 
+/**
+ * Consumer card schemas by envelope type: `{ 'pricing-table': pricingSchema }`.
+ *
+ * `object`, NOT `JsonSchema`, and that is measured rather than lazy. A real schema
+ * is either imported from a `.json` file — where TypeScript widens `"type": "object"`
+ * to `string`, which `JsonSchema`'s literal union rejects — or written out with the
+ * `$schema` / `title` / `description` / `additionalProperties` keywords that
+ * `JsonSchema` does not describe at all, which excess-property checking rejects.
+ * Both are the ordinary case, so the tighter type would make the normal way of
+ * supplying a schema a compile error. `src/schemas/index.ts` widens `CardSchema`
+ * for exactly this reason and says so at length (lines 92-110 there).
+ *
+ * The value is handed straight to `validateCardData`, which reads only the keywords
+ * `validateAgainstSchema` implements and ignores the rest.
+ */
+export type CardSchemaMap = Record<string, object>;
+
 export interface CardRendererProps {
   envelope: CardEnvelope;
   /** Add/override type→component entries (merged over the built-ins). */
   types?: CardComponentMap;
+  /**
+   * JSON Schemas for the card types this app renders, keyed by `envelope.type`.
+   * `createCardRegistry(...).validationSchemas` is exactly this shape.
+   *
+   * The companion of `types`, and the half that was missing: `types` says WHAT
+   * draws a `pricing-table`, `schemas` says what a VALID one looks like. Without it
+   * the kit checks its own seven built-ins and leaves the developer's own card —
+   * the one the app actually cares about — as the only unvalidated thing on screen.
+   *
+   * A schema given here WINS over a built-in of the same name, matching
+   * `mergeCardComponents`, where the consumer's entry is spread over ours.
+   */
+  schemas?: CardSchemaMap;
+  /**
+   * Validate `envelope.data` against the built-in schema for `envelope.type` before
+   * rendering. Default `true`.
+   *
+   * ON IN PRODUCTION TOO, DELIBERATELY. The obvious alternative, stripping the check
+   * from production builds, inverts the point: a model emitting a bad shape is a
+   * production failure mode, so stripping it means the developer's USERS get the
+   * broken card while the developer's laptop looks fine. The cost is the projected
+   * schema data for all seven card types, measured by building this package twice
+   * (once with the projection stubbed to `{}`) rather than estimated: +834 B gzip on
+   * `dist/index.js` and +775 B gzip on the elements register bundle. That is below
+   * the noise floor of a package that already ships a Solid runtime and `marked`.
+   *
+   * Set `false` to opt out. A type with no schema at all — no built-in, and none
+   * supplied through `schemas` — is never validated either way.
+   */
+  validateCards?: boolean;
+}
+
+/**
+ * True when the consumer registered a schema for this type.
+ *
+ * Spelled out rather than left to `validateCardData` because it is a GATE, not a
+ * lookup: a consumer schema is the one thing that authorises validating a renderer
+ * that is not ours. `hasOwnProperty` (not `in`) so a type named `toString` cannot
+ * pick up `Object.prototype`, and the `typeof` check so a `{ 'x': null }` entry
+ * reads as "not registered" instead of matching and then validating against
+ * nothing. The same predicate lives in elements/cards.tsx for `<kai-cards>`; the
+ * two dispatchers already duplicate this rule (they compare component identity vs
+ * tag identity), so keep them in step.
+ */
+export function hasConsumerSchema(schemas: CardSchemaMap | undefined, type: string): boolean {
+  if (!schemas || !Object.prototype.hasOwnProperty.call(schemas, type)) return false;
+  const s = schemas[type];
+  return typeof s === 'object' && s !== null;
 }
 
 export function CardRenderer(props: CardRendererProps): JSX.Element {
@@ -20,12 +88,74 @@ export function CardRenderer(props: CardRendererProps): JSX.Element {
   const map = createMemo(() => mergeCardComponents(props.types));
   const entry = createMemo(() => map()[props.envelope.type]);
 
+  // MIRRORS src/remote/provider-runtime.ts:139-147. That transport runs
+  // `validateAgainstSchema(renderer.schema, envelope.data)` and, on failure, renders
+  // a placeholder and emits `{ kind: 'error', cardId, message }`. This is the same
+  // behaviour on the native path, split into two tiers so a card that renders
+  // acceptably today is reported without being replaced. Keep the two in step.
+  //
+  // WHAT AUTHORISES A CHECK IS A SCHEMA THAT DESCRIBES WHAT IS ON SCREEN.
+  //
+  // `types` lets a consumer replace a built-in type's renderer with their own
+  // (`types={{ confirm: MyConfirm }}`), and `confirm.schema.json` describes OUR
+  // ConfirmCard's data, not theirs. Validating a replaced renderer's payload against
+  // our schema would reject shapes that are correct for the component actually on
+  // screen. So OUR schema applies only to OUR component: the identity check is
+  // against BUILTIN_CARD_COMPONENTS, the same object `mergeCardComponents` puts in
+  // the map when nothing overrode the type, and the same one elements/message.tsx
+  // reuses for a non-overridden built-in.
+  //
+  // A schema the CONSUMER registered is the other way round: they wrote it about
+  // their own card, and it is the shape their model was told to emit, so it applies
+  // whichever component draws the type. That covers the case the identity check can
+  // never reach — a `pricing-table` that is nobody's built-in — and it re-enables
+  // the check on an overridden built-in, where the objection was our schema and not
+  // the checking.
+  const report = createMemo<CardValidationReport | null>(() => {
+    if (props.validateCards === false) return null;
+    if (
+      !hasConsumerSchema(props.schemas, props.envelope.type) &&
+      entry() !== BUILTIN_CARD_COMPONENTS[props.envelope.type]
+    ) {
+      return null;
+    }
+    // `schemas` is passed even when the gate opened on renderer identity, so a
+    // consumer schema for a built-in type wins over ours — `schemaFor`'s rule.
+    return validateCardData(props.envelope.type, props.envelope.data, props.schemas as Record<string, JsonSchema> | undefined);
+  });
+
+  // One `error` per distinct problem, both tiers. Keyed on the message rather than
+  // on mount because streaming hands this component a NEW envelope object per chunk
+  // (that is the documented way to re-render), so an identity-triggered emit would
+  // fire once per chunk for one bad card.
+  let lastEmitted: string | null = null;
+  createEffect(() => {
+    const r = report();
+    if (!entry()) return; // an unknown TYPE reports itself, once, in UnknownCard
+    if (!r || r.ok) {
+      lastEmitted = null;
+      return;
+    }
+    const message = cardValidationMessage(r);
+    if (message === lastEmitted) return;
+    lastEmitted = message;
+    host?.emit({ kind: 'error', cardId: props.envelope.id, message });
+  });
+
   return (
-    <Show
-      when={entry()}
-      fallback={<UnknownCard envelope={props.envelope} />}
-    >
-      {(comp) => <Dynamic component={comp()} envelope={props.envelope} host={host} />}
+    <Show when={entry()} fallback={<UnknownCard envelope={props.envelope} />}>
+      {(comp) => (
+        <Show
+          when={report()?.tier === 'hard'}
+          // SOFT and valid both take this branch: the card renders exactly as it
+          // does today. The soft failure is reported through the effect above and
+          // changes nothing on screen, which is the whole point of the tiering.
+          fallback={<Dynamic component={comp()} envelope={props.envelope} host={host} />}
+        >
+          {/* HARD: there is nothing to draw, so name the field instead. */}
+          <CardFallback type={props.envelope.type} cardId={props.envelope.id} reason={report()!.summary} />
+        </Show>
+      )}
     </Show>
   );
 }
@@ -46,7 +176,14 @@ function UnknownCard(props: { envelope: CardEnvelope }): JSX.Element {
 /** Function sugar: renderCard(env) ≡ <CardRenderer envelope={env} />. */
 export function renderCard(
   envelope: CardEnvelope,
-  opts?: { types?: CardComponentMap },
+  opts?: { types?: CardComponentMap; schemas?: CardSchemaMap; validateCards?: boolean },
 ): JSX.Element {
-  return <CardRenderer envelope={envelope} types={opts?.types} />;
+  return (
+    <CardRenderer
+      envelope={envelope}
+      types={opts?.types}
+      schemas={opts?.schemas}
+      validateCards={opts?.validateCards}
+    />
+  );
 }

package/src/components/chat-container.tsx

@@ -74,6 +74,10 @@ function ChatContainerScrollAnchor(props: ChatContainerScrollAnchorProps) {
   );
 }
 
+/** `ChatContainer` is the exported alias of `ChatContainerRoot`; its props type
+ *  is aliased too, so the name a consumer imports always has a matching Props. */
+export type ChatContainerProps = ChatContainerRootProps;
+
 export {
   ChatContainerRoot as ChatContainer,
   ChatContainerRoot,

package/src/components/chat-thread.tsx

@@ -1,4 +1,4 @@
-import { createSignal, createEffect, For, Show, onMount } from 'solid-js';
+import { createSignal, createEffect, createMemo, For, Show, onMount } from 'solid-js';
 import { ChatConfig, useChatConfig } from '../primitives/chat-config';
 import { type ComposerDoc, normalizeValue, serializeToText } from '../primitives/composer-model';
 import { ChatContainer, ChatContainerContent, ChatContainerScrollAnchor } from './chat-container';
@@ -16,6 +16,8 @@ import type { TriggerDef } from './composer';
 import type { ChatMessage } from '../elements/chat-types';
 import type { ProseSize } from '../primitives/chat-config';
 import type { ModelOption } from '../types';
+import type { CardComponentMap } from '../primitives/card-registry';
+import type { CardSchemaMap } from './card-renderer';
 
 export interface ChatThreadContextUsage {
   usedTokens: number;
@@ -29,9 +31,19 @@ export interface ChatThreadProps {
   /** Extra classes for the thread root (e.g. `h-full`). */
   class?: string;
   /** The full message thread to render, newest last. Each entry carries its role,
-   *  content, and optional reasoning/tools/attachments/actions. Set as a JS
-   *  property (`el.messages = [...]`). */
+   *  ordered `parts`, and optional actions/avatar/feedback. Set as a JS property
+   *  (`el.messages = [...]`). */
   messages: ChatMessage[];
+  /** Add/override card type -> component entries, forwarded to `CardRenderer`
+   *  for `card` parts. */
+  cardTypes?: CardComponentMap;
+  /** JSON Schemas for the card types this app renders, keyed by envelope type,
+   *  forwarded to `CardRenderer` for `card` parts. The companion of `cardTypes`:
+   *  that says what DRAWS a card, this says what a VALID one looks like.
+   *  `createCardRegistry(...).validationSchemas` is exactly this shape. Without it
+   *  the kit checks its own seven built-ins and leaves your own card type
+   *  unvalidated. A schema here WINS over a built-in of the same name. */
+  cardSchemas?: CardSchemaMap;
   /** Value of the input. A **string** is controlled (the host owns the text and
    *  updates it on `kai-value-change`). A **ComposerDoc** is a one-time seed that
    *  pre-populates pills; the user then edits freely. Leave unset for uncontrolled. */
@@ -72,8 +84,8 @@ export interface ChatThreadProps {
   context?: ChatThreadContextUsage;
   /** Show the scroll-to-bottom button inside the scroll area. Default true. */
   scrollButton?: boolean;
-  /** Whether the host has `slot="header-start"` content (left of the title) —
-   *  set by the `<kai-chat>` facade so a custom control forces the header open. */
+  /** Whether the host has `slot="header-start"` content (left of the title). Set
+   *  by the `<kai-chat>` facade so a custom control forces the header open. */
   headerStart?: boolean;
   /** Whether the host has `slot="header-end"` content (right of the controls). */
   headerEnd?: boolean;
@@ -87,24 +99,24 @@ export interface ChatThreadProps {
   //               content owns its own data/events — a slotted (light-DOM) node
   //               can't read this component's reactive state. That boundary is
   //               the whole reason `messages` stays a data prop, not a slot.
-  /** REPLACE — full custom header in place of the built-in title/model/context bar. */
+  /** REPLACE: full custom header in place of the built-in title/model/context bar. */
   headerFull?: boolean;
-  /** INJECT — left sidebar column (e.g. a conversation list / your own nav). */
+  /** INJECT: left sidebar column (e.g. a conversation list / your own nav). */
   sidebar?: boolean;
-  /** REPLACE — custom zero-state rendered in the message area while the thread is empty (replaces the empty message list only; the composer and its suggestions still render). */
+  /** REPLACE: custom zero-state rendered in the message area while the thread is empty (replaces the empty message list only; the composer and its suggestions still render). */
   empty?: boolean;
-  /** REPLACE — full custom composer in place of the built-in prompt input. The
+  /** REPLACE: full custom composer in place of the built-in prompt input. The
    *  projected content wires its own submit (the data-flow boundary). */
   composer?: boolean;
-  /** INJECT — accessory row just above the composer (e.g. extra actions). */
+  /** INJECT: accessory row just above the composer (e.g. extra actions). */
   composerActions?: boolean;
-  /** INJECT — footer row below the composer (disclaimers, token meter, …). */
+  /** INJECT: footer row below the composer (disclaimers, token meter, …). */
   footer?: boolean;
   /** Show a Search (Globe) button in the input toolbar; fires a `search` event. */
   search?: boolean;
   /** Show a Voice (Mic) button in the input toolbar; fires a `voice` event. */
   voice?: boolean;
-  /** Rich entity triggers — each `{ char, kind, items }` opens a caret-anchored
+  /** Rich entity triggers. Each `{ char, kind, items }` opens a caret-anchored
    *  menu that inserts an atomic pill (`/` skills, `@` agents/plugins). Set as a
    *  JS property; forwarded to the input. */
   triggers?: TriggerDef[];
@@ -136,9 +148,48 @@ export interface ChatThreadController {
   scrollToBottom(behavior?: ScrollBehavior): void;
 }
 
+/**
+ * THE MESSAGE LIST'S KEY, and the reason it is not the message object. This is
+ * the canonical note; `thread.tsx` keys its identical list the same way and
+ * points here.
+ *
+ *  `<For>` is REFERENCE-keyed, and a streaming assistant message gets a brand
+ *  new object identity on every delta — `createAssistantStream` rebuilds it as
+ *  `{ ...prev[i], parts: next }` because a new reference IS the re-render
+ *  signal. Keyed on the objects, every chunk therefore looks like an entirely
+ *  new list: the whole message row is torn down and rebuilt, and everything the
+ *  user did inside it dies with it. Expanding a tool or reasoning panel
+ *  mid-stream did nothing at all — the disclosure opened and was discarded
+ *  microseconds later by the next token. (`MessageBody` keys its PARTS by
+ *  position for exactly this reason; that fix was dead while its parent kept
+ *  destroying the subtree above it.)
+ *
+ *  So key on `message.id`, which is stable across the object churn: `<For>` over
+ *  the id array diffs by string value, a delta produces an identical id list,
+ *  and no row moves. The row then reads its message through `messages[i()]` —
+ *  `<For>`'s index accessor, which it keeps current across inserts, removals and
+ *  moves — so the CONTENT keeps updating through accessors while the DOM stays
+ *  put.
+ *
+ *  WHY NOT `<Index>`, the other way to survive the churn: `<Index>` keys by
+ *  POSITION, so a row's local state (an open panel, a half-filled form card)
+ *  belongs to the slot rather than to the message. Appends and tail truncations
+ *  (regenerate/edit) are fine, but prepending older turns — load-earlier-history,
+ *  which every real chat grows — shifts every row, and each open disclosure
+ *  stays behind with the wrong message. Position IS a valid key inside a
+ *  message, where the folds only ever append or patch a part in place; it is not
+ *  one for the message list, where the host owns the array and splices it.
+ *  Both approaches require the row to read through accessors — that is inherent
+ *  in keeping a row mounted while its object is replaced, not a cost unique to
+ *  either.
+ *
+ *  Contract: `id` must be unique per message. It already had to be — the
+ *  feedback/copy state above this list is keyed by it.
+ */
 export function ChatThread(props: ChatThreadProps) {
   const outer = useChatConfig();
   const reveal = () => (props.actionsReveal === 'hover' ? 'hover' : 'always');
+  const messageKeys = createMemo(() => props.messages.map((m) => m.id));
   // Feedback (copy + vote) state lives ABOVE the per-message <For>, so streaming
   // re-renders (a fresh `messages` array ref per chunk) don't wipe it.
   // The copy/feedback toasts scope to the chat (this thread's root) so they appear
@@ -261,44 +312,60 @@ export function ChatThread(props: ChatThreadProps) {
                 <Show when={props.empty && props.messages.length === 0}>
                   <slot name="empty" />
                 </Show>
-                <For each={props.messages}>
-                  {(m) => {
-                    const body = (
-                      <MessageBody
-                        content={m.content}
-                        reasoning={m.reasoning}
-                        tools={m.tools}
-                        attachments={m.attachments}
-                        isUser={m.role === 'user'}
-                        markdown={m.role === 'assistant'}
-                        actions={m.actions}
-                        actionsReveal={reveal()}
-                        activeFeedback={feedback.resolveFeedback(m)}
-                        copied={feedback.isCopied(m.id)}
-                        onAction={(action) => feedback.handleAction(m, action)}
-                      />
-                    );
-                    const rowGroup = reveal() === 'hover' ? 'group ' : '';
-                    return (
-                      <Show
-                        when={m.avatar}
-                        fallback={
-                          <Message class={`${rowGroup}${m.role === 'user' ? 'flex-col items-end' : 'flex-col items-start'}`}>
-                            {body}
-                          </Message>
-                        }
-                      >
-                        {(av) => (
-                          <Message class={rowGroup}>
-                            <MessageAvatar src={av().src ?? ''} alt={av().alt ?? ''} fallback={av().fallback} />
-                            <div class={`flex min-w-0 flex-1 flex-col ${m.role === 'user' ? 'items-end' : 'items-start'}`}>
-                              {body}
-                            </div>
-                          </Message>
-                        )}
-                      </Show>
-                    );
-                  }}
+                {/* Keyed by message id (see the note above this component), so a
+                    streaming delta updates the row instead of replacing it. */}
+                <For each={messageKeys()}>
+                  {(_id, i) => (
+                    // The row reads its message through <For>'s index accessor,
+                    // never through a captured value: the row outlives the delta
+                    // that replaced its object, so every read below has to go
+                    // through `m()` for the new content to land. <Show> supplies
+                    // the non-null accessor and covers the frame where a removal
+                    // has shortened the array.
+                    <Show when={props.messages[i()]}>
+                      {(m) => {
+                        const body = (
+                          <MessageBody
+                            parts={m().parts}
+                            cardTypes={props.cardTypes}
+                            cardSchemas={props.cardSchemas}
+                            isUser={m().role === 'user'}
+                            markdown={m().role === 'assistant'}
+                            actions={m().actions}
+                            actionsReveal={reveal()}
+                            activeFeedback={feedback.resolveFeedback(m())}
+                            copied={feedback.isCopied(m().id)}
+                            onAction={(action) => feedback.handleAction(m(), action)}
+                          />
+                        );
+                        const rowGroup = () => (reveal() === 'hover' ? 'group ' : '');
+                        return (
+                          // `role` is the SPEAKER, forwarded on BOTH branches —
+                          // see the same note in thread.tsx. `Message` turns it
+                          // into `role="article"` + an `aria-label`; without it the
+                          // row is a bare div chromium prunes from the
+                          // accessibility tree as "uninteresting".
+                          <Show
+                            when={m().avatar}
+                            fallback={
+                              <Message role={m().role} class={`${rowGroup()}${m().role === 'user' ? 'flex-col items-end' : 'flex-col items-start'}`}>
+                                {body}
+                              </Message>
+                            }
+                          >
+                            {(av) => (
+                              <Message role={m().role} class={rowGroup()}>
+                                <MessageAvatar src={av().src ?? ''} alt={av().alt ?? ''} fallback={av().fallback} />
+                                <div class={`flex min-w-0 flex-1 flex-col ${m().role === 'user' ? 'items-end' : 'items-start'}`}>
+                                  {body}
+                                </div>
+                              </Message>
+                            )}
+                          </Show>
+                        );
+                      }}
+                    </Show>
+                  )}
                 </For>
                 <ChatContainerScrollAnchor />
               </ChatContainerContent>
@@ -337,7 +404,7 @@ export function ChatThread(props: ChatThreadProps) {
               </Show>
             </div>
           </div>
-          {/* INJECT — footer row below the composer. */}
+          {/* INJECT: footer row below the composer. */}
           <Show when={props.footer}>
             <div part="footer" class="shrink-0 px-4 pb-3">
               <div class="mx-auto max-w-3xl text-center text-xs text-muted-foreground"><slot name="footer" /></div>

package/src/components/choice-card.tsx

@@ -24,37 +24,25 @@ import { useCardHost } from '../primitives/card-host';
 import { Check, X } from 'lucide-solid';
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Types (choice.schema.json) — see src/primitives/card-schemas/choice.schema.json
+// Types (choice.schema.json) — AUTHORED IN ../primitives/card-data-types.ts.
+// See the note in confirm-card.tsx, or that file's header, for why they left a
+// `.tsx` and why they are `type` aliases. Re-exported here unchanged.
 // ─────────────────────────────────────────────────────────────────────────────
 
-export interface ChoiceOptionMedia {
-  image?: string;
-  imageAlt?: string;
-  icon?: string;
-}
-
-export interface ChoiceOption {
-  id: string; // required, unique within the card
-  label: string; // required
-  description?: string;
-  media?: ChoiceOptionMedia;
-  meta?: string; // trailing freeform text (e.g. price/badge)
-  recommended?: boolean; // renders a "Recommended" pill
-  disabled?: boolean; // not selectable; skipped in keyboard nav
-  payload?: unknown; // echoed back in the emitted action
-}
-
-export type ChoiceAllowOther = boolean | { label?: string; placeholder?: string };
-
-export interface ChoiceCardData {
-  prompt?: string; // optional question/body above the options
-  options: ChoiceOption[]; // 1..N
-  allowOther?: ChoiceAllowOther; // free-text escape
-  submitLabel?: string; // label for the Submit button (default 'Submit')
-  dismissible?: boolean; // show a close affordance that emits `dismiss`
-}
-
-export type ChoiceCardEnvelope = CardEnvelope<'choice', ChoiceCardData>;
+import type {
+  ChoiceAllowOther,
+  ChoiceCardData,
+  ChoiceOption,
+  ChoiceOptionMedia,
+} from '../primitives/card-data-types';
+
+export type {
+  ChoiceAllowOther,
+  ChoiceCardData,
+  ChoiceCardEnvelope,
+  ChoiceOption,
+  ChoiceOptionMedia,
+} from '../primitives/card-data-types';
 
 export const CHOICE_CARD_TYPE = 'choice' as const;
 

package/src/components/composer.tsx

@@ -469,11 +469,21 @@ export function Composer(props: ComposerProps): JSX.Element {
   const handleBlur = (e: FocusEvent) => { focused = false; clearPillSelection(); props.onBlur?.(e); };
 
   onMount(() => {
+    // Captured at SETUP and closed over, never re-resolved as a global inside
+    // `onCleanup`: cleanup can run after the host removed the DOM globals (a
+    // `kai-*` release is deferred one microtask past detachment, so an
+    // environment teardown gets in between), and a bare `document` there throws
+    // -- from a promise nobody holds, so it lands as an unhandled rejection that
+    // fails the run while every test passes. That is how this was found.
+    // See tests/components/teardown-without-dom-globals.test.tsx.
+    // `ownerDocument` rather than a captured `document`, matching the rest of
+    // this file and staying correct for a composer inside an iframe.
+    const doc = editable.ownerDocument;
     const onSelectionChange = () => {
       if (focused) updateTriggerState();
     };
-    document.addEventListener('selectionchange', onSelectionChange);
-    onCleanup(() => document.removeEventListener('selectionchange', onSelectionChange));
+    doc.addEventListener('selectionchange', onSelectionChange);
+    onCleanup(() => doc.removeEventListener('selectionchange', onSelectionChange));
   });
 
   // --- Imperative controller (Pattern C): hand the facade a handle over the

package/src/components/confirm-card.tsx

@@ -21,29 +21,33 @@ import { useCardHost } from '../primitives/card-host';
 import { AlertTriangle, Check, X } from 'lucide-solid';
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Types (confirm.schema.json) — see src/primitives/card-schemas/confirm.schema.json
+// Types (confirm.schema.json) — AUTHORED IN ../primitives/card-data-types.ts.
+//
+// They used to be declared here, and moving them is the fourth instance of the
+// split card-tags.ts and card-component-types.ts already made twice: a type
+// import still has to RESOLVE, so while these lived in a `.tsx` no Node/no-DOM
+// project could name them (TS6142), which meant `@kitn.ai/ui/schemas` could not
+// re-export them and a TypeScript backend building a card envelope got
+// `data: unknown` while Python and Go read the full shape out of the published
+// JSON Schemas. They are also `type` aliases rather than `interface`s now, which
+// is what makes `el.data = myConfirmCardData` compile — see that file's header
+// for both measurements. Re-exported here, so this module's surface is unchanged.
 // ─────────────────────────────────────────────────────────────────────────────
 
-export type ConfirmActionStyle = 'primary' | 'default' | 'destructive';
-export type ConfirmTone = 'default' | 'warning' | 'danger';
+import type {
+  ConfirmAction,
+  ConfirmActionStyle,
+  ConfirmCardData,
+  ConfirmTone,
+} from '../primitives/card-data-types';
 
-export interface ConfirmAction {
-  id: string;
-  label: string;
-  style?: ConfirmActionStyle;
-  payload?: unknown;
-  default?: boolean;
-}
-
-export interface ConfirmCardData {
-  heading?: string;
-  body?: string;
-  tone?: ConfirmTone;
-  actions: ConfirmAction[]; // 1..4
-  dismissible?: boolean;
-}
-
-export type ConfirmCardEnvelope = CardEnvelope<'confirm', ConfirmCardData>;
+export type {
+  ConfirmAction,
+  ConfirmActionStyle,
+  ConfirmCardData,
+  ConfirmCardEnvelope,
+  ConfirmTone,
+} from '../primitives/card-data-types';
 
 export const CONFIRM_CARD_TYPE = 'confirm' as const;
 

package/src/components/context.tsx

@@ -306,7 +306,15 @@ export interface ContextUsageRowProps {
   children?: JSX.Element;
 }
 
-export function ContextInputUsage(props: ContextUsageRowProps) {
+// The four rows share one shape, but each still ships a `<Name>Props` alias: a
+// consumer typing a wrapper around one of them should not have to discover that
+// the shared name exists.
+export type ContextInputUsageProps = ContextUsageRowProps;
+export type ContextOutputUsageProps = ContextUsageRowProps;
+export type ContextReasoningUsageProps = ContextUsageRowProps;
+export type ContextCacheUsageProps = ContextUsageRowProps;
+
+export function ContextInputUsage(props: ContextInputUsageProps) {
   const ctx = useContextValue();
   return (
     <Show when={props.children || ctx.inputTokens}>
@@ -320,7 +328,7 @@ export function ContextInputUsage(props: ContextUsageRowProps) {
   );
 }
 
-export function ContextOutputUsage(props: ContextUsageRowProps) {
+export function ContextOutputUsage(props: ContextOutputUsageProps) {
   const ctx = useContextValue();
   return (
     <Show when={props.children || ctx.outputTokens}>
@@ -334,7 +342,7 @@ export function ContextOutputUsage(props: ContextUsageRowProps) {
   );
 }
 
-export function ContextReasoningUsage(props: ContextUsageRowProps) {
+export function ContextReasoningUsage(props: ContextReasoningUsageProps) {
   const ctx = useContextValue();
   return (
     <Show when={props.children || ctx.reasoningTokens}>
@@ -348,7 +356,7 @@ export function ContextReasoningUsage(props: ContextUsageRowProps) {
   );
 }
 
-export function ContextCacheUsage(props: ContextUsageRowProps) {
+export function ContextCacheUsage(props: ContextCacheUsageProps) {
   const ctx = useContextValue();
   return (
     <Show when={props.children || ctx.cacheTokens}>

package/src/components/conversation-list.tsx

@@ -16,7 +16,9 @@ import type { ConversationSummary, ConversationGroup } from '../types';
  * surrounding region (the workspace puts the thread beside it, the standalone
  * element stands alone). `onExpand` reopens the rail.
  */
-export function CollapsedRail(props: { onExpand: () => void; class?: string }) {
+export interface CollapsedRailProps { onExpand: () => void; class?: string }
+
+export function CollapsedRail(props: CollapsedRailProps) {
   return (
     <Button
       variant="ghost" size="icon-sm" aria-label="Open sidebar"
@@ -94,7 +96,21 @@ export function ConversationList(props: ConversationListProps) {
     return grouped;
   });
 
-  const ungrouped = createMemo(() => groupedConversations().get(undefined) ?? []);
+  /**
+   * Everything that is NOT filed under a rendered group heading: no `groupId` at
+   * all, OR a `groupId` that matches no entry in `groups`.
+   *
+   * The second half used to be dropped on the floor. `groups` drives the render
+   * loop, so a conversation pointing at a group the consumer had not declared
+   * (a stale id, a group removed from the array, a filtered/paginated `groups`
+   * response) vanished from the sidebar with no error and no empty state — the
+   * list just silently held fewer rows than the data it was given. Falling through
+   * to "Ungrouped" keeps every conversation the consumer passed in reachable.
+   */
+  const ungrouped = createMemo(() => {
+    const known = new Set((local.groups ?? []).map((g) => g.id));
+    return filteredConversations().filter((c) => c.groupId == null || !known.has(c.groupId));
+  });
 
   return (
     <div class={cn('flex flex-col h-full bg-sidebar', local.class)}>