@kitn.ai/ui 0.26.0 → 0.27.0

package/src/agent-tooling/recipes/index.ts

@@ -0,0 +1,22 @@
+import type { CodeRecipe } from './types';
+import { composedThread } from './composed-thread';
+
+export type { CodeRecipe, CodeRecipeFile } from './types';
+
+/**
+ * The code-recipe registry.
+ *
+ * Registered here → served by `component_reference({ name: "<id>" })` AND
+ * compiled by `verify:scaffold` (which loads this list through the registry
+ * bundle, so adding an entry moves that gate's printed cell count by itself —
+ * the same derive-don't-list contract as the integration and surface axes).
+ */
+export const codeRecipes: CodeRecipe[] = [composedThread];
+
+export function listCodeRecipes(): CodeRecipe[] {
+  return codeRecipes;
+}
+
+export function getCodeRecipe(id: string): CodeRecipe | undefined {
+  return codeRecipes.find((r) => r.id === id);
+}

package/src/agent-tooling/recipes/types.ts

@@ -0,0 +1,32 @@
+/**
+ * A CODE recipe: a complete, compiling composition the MCP serves as files.
+ *
+ * Distinct from a `TSurfaceRecipe` (../catalog/catalog-types.ts) on purpose:
+ * the catalog record is DATA — ingredients, wiring edges, invariants, each
+ * resolved and executed by its own guards — while a code recipe is the full
+ * host module a builder pastes. The two meet on `id`: a code recipe whose id
+ * also names a surface recipe is that record's body.
+ *
+ * `verify:scaffold` compiles every `lang: 'ts'` file of every registered code
+ * recipe with a stock consumer tsconfig, resolving `@kitn.ai/ui` through the
+ * shipped exports map — the same gate the scaffolder's emitted string literals
+ * go through, because this code is string literals with the same failure mode.
+ */
+export interface CodeRecipeFile {
+  /** Path inside the consumer's app, e.g. `src/main.ts`. */
+  path: string;
+  lang: 'ts' | 'html' | 'css';
+  code: string;
+}
+
+export interface CodeRecipe {
+  /** Kebab-case id, e.g. `composed-thread`. Also the component_reference topic name. */
+  id: string;
+  title: string;
+  intent: string;
+  /** The kai-* tags the composition places. */
+  ingredients: string[];
+  /** The teaching notes served above the files — the WHY a prop table cannot carry. */
+  notes: string[];
+  files: CodeRecipeFile[];
+}

package/src/agent-tooling/registry.ts

@@ -23,6 +23,11 @@ export {
   type SurfaceProbe,
 } from './archetypes';
 
+// The code-recipe axis, same contract as the two above: the gate loads it from
+// this registry bundle, so registering a recipe adds its compile cells without
+// touching the verify script.
+export { listCodeRecipes, getCodeRecipe, type CodeRecipe, type CodeRecipeFile } from './recipes';
+
 // Order is the order a scaffolding agent reads them in. `openai` and `anthropic`
 // lead because they are the two keys a developer is most likely to already hold.
 export const integrations: Integration[] = [

package/src/components/attachment-types.ts

@@ -5,6 +5,13 @@ export interface AttachmentData {
   type: 'file' | 'source-document';
   filename?: string;
   mediaType?: string;
+  /** A `data:` URI or an https URL — this is the field the wire encodes, so it
+   *  is what reaches the model. NEVER `URL.createObjectURL`: an object URL
+   *  resolves only inside the tab that minted it, so a `blob:` URL renders a
+   *  flawless preview and is meaningless to any provider —
+   *  `toOpenAIMessages`/`toAnthropicMessages` refuse it rather than send an
+   *  address the model cannot fetch. Read picked files with
+   *  `FileReader.readAsDataURL` instead (see `elements/default-input.tsx`). */
   url?: string;
   title?: string;
 }

package/src/components/audio-visualizer/fit-scale.ts

@@ -1,7 +1,7 @@
 import { createSignal, onCleanup, type Accessor } from 'solid-js';
 
 /**
- * Fit-to-container scaling (owner finding, rung 2): the size tiers are fixed
+ * Fit-to-container scaling: the size tiers are fixed
  * px by design (`sizes.ts`), so a container narrower than a tier's natural
  * footprint used to CLIP the picture at its edges. The dispatcher now scales
  * the WHOLE visualization down proportionally to fit, and renders byte-equal

package/src/components/card-renderer.tsx

@@ -5,8 +5,9 @@
 // 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 type { CardContext, CardEnvelope, CardHost } from '../primitives/card-contract';
 import { useCardHost } from '../primitives/card-host';
+import { emitCardEvent } from '../primitives/card-routing';
 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';
@@ -63,6 +64,35 @@ export interface CardRendererProps {
    * supplied through `schemas` — is never validated either way.
    */
   validateCards?: boolean;
+  /**
+   * The custom-element host node to emit off when no `CardProvider` is above this
+   * renderer: events leave as the bubbling, composed `kai-card` CustomEvent
+   * (`emitCardEvent`), so `listenForCardEvents(element)` — or a plain
+   * `addEventListener('kai-card', …)` on the element — receives them.
+   *
+   * This is what makes cards INSIDE `<kai-chat>`/`<kai-message>`/`<kai-thread>`
+   * interactive: those facades pass their own host element down here, and
+   * with neither this nor a `CardProvider` every emit — ready/action/submit/
+   * dismiss/reopen and the contract `error` — used to be silently discarded.
+   * An ambient `CardProvider` still wins when present.
+   */
+  hostElement?: HTMLElement;
+}
+
+/**
+ * The effective CardHost: an ambient `CardProvider` when present, otherwise a
+ * bubbling-`kai-card` host over `hostElement`, otherwise none (a truly bare card).
+ *
+ * The fallback's `context()` mirrors the remote transport's `defaultContext()`
+ * (`remote/provider-runtime.ts`): the contract return is non-optional, but no
+ * native card reads it today — the element facades own theme/locale through
+ * `ChatConfig`, not through card context.
+ */
+function resolveHost(ctxHost: CardHost | undefined, hostElement: HTMLElement | undefined): CardHost | undefined {
+  if (ctxHost) return ctxHost;
+  if (!hostElement) return undefined;
+  const context = (): CardContext => ({ theme: { mode: 'light' }, locale: 'en' });
+  return { context, emit: (event) => emitCardEvent(hostElement, event) };
 }
 
 /**
@@ -84,7 +114,8 @@ export function hasConsumerSchema(schemas: CardSchemaMap | undefined, type: stri
 }
 
 export function CardRenderer(props: CardRendererProps): JSX.Element {
-  const host = useCardHost();
+  const ctxHost = useCardHost();
+  const host = createMemo(() => resolveHost(ctxHost, props.hostElement));
   const map = createMemo(() => mergeCardComponents(props.types));
   const entry = createMemo(() => map()[props.envelope.type]);
 
@@ -139,18 +170,18 @@ export function CardRenderer(props: CardRendererProps): JSX.Element {
     const message = cardValidationMessage(r);
     if (message === lastEmitted) return;
     lastEmitted = message;
-    host?.emit({ kind: 'error', cardId: props.envelope.id, message });
+    host()?.emit({ kind: 'error', cardId: props.envelope.id, message });
   });
 
   return (
-    <Show when={entry()} fallback={<UnknownCard envelope={props.envelope} />}>
+    <Show when={entry()} fallback={<UnknownCard envelope={props.envelope} hostElement={props.hostElement} />}>
       {(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} />}
+          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} />
@@ -161,10 +192,10 @@ export function CardRenderer(props: CardRendererProps): JSX.Element {
 }
 
 /** Renders the fallback and emits exactly one `error` (untracked, on first render). */
-function UnknownCard(props: { envelope: CardEnvelope }): JSX.Element {
-  const host = useCardHost();
+function UnknownCard(props: { envelope: CardEnvelope; hostElement?: HTMLElement }): JSX.Element {
+  const ctxHost = useCardHost();
   untrack(() =>
-    host?.emit({
+    resolveHost(ctxHost, props.hostElement)?.emit({
       kind: 'error',
       cardId: props.envelope.id,
       message: `Unsupported card type: ${props.envelope.type}`,

package/src/components/card.tsx

@@ -20,6 +20,10 @@ export interface CardProps extends JSX.HTMLAttributes<HTMLDivElement> {
   /** Stable id for the heading (so composing cards can `aria-labelledby` it).
    *  Auto-generated when omitted. */
   headingId?: string;
+  /** Stable id for the description (so composing cards can `aria-describedby` it
+   *  — e.g. `kai-choice`'s radiogroup points at its prompt). Auto-generated when
+   *  omitted, mirroring `headingId`. */
+  descriptionId?: string;
   /** Render a dismiss (×) button that hides the card and calls `onDismiss`.
    *  Opt-in, OFF by default — the contract cards never set it, so they are
    *  unaffected. */
@@ -67,6 +71,7 @@ export function Card(props: CardProps): JSX.Element {
     'errorMessage',
     'dense',
     'headingId',
+    'descriptionId',
     'dismissible',
     'onDismiss',
     'href',
@@ -80,6 +85,7 @@ export function Card(props: CardProps): JSX.Element {
 
   const autoId = createUniqueId();
   const headingId = () => local.headingId ?? `kai-card-heading-${autoId}`;
+  const descriptionId = () => local.descriptionId ?? `kai-card-description-${autoId}`;
   const hasError = () => local.errorMessage !== undefined && local.errorMessage !== '';
   const hasHeader = () => Boolean(local.heading) || Boolean(local.description);
 
@@ -123,13 +129,15 @@ export function Card(props: CardProps): JSX.Element {
           <Show when={local.heading}>
             <h3
               id={headingId()}
-              class="text-[1.0625rem] font-semibold leading-snug tracking-tight text-foreground"
+              class="text-title font-semibold tracking-tight text-foreground"
             >
               {local.heading}
             </h3>
           </Show>
           <Show when={local.description}>
-            <p class="text-[0.8125rem] leading-relaxed text-muted-foreground">{local.description}</p>
+            <p id={descriptionId()} class="text-body text-muted-foreground">
+              {local.description}
+            </p>
           </Show>
         </div>
       </Show>

package/src/components/chat-scope-picker.tsx

@@ -36,7 +36,7 @@ export function ChatScopePicker(props: ChatScopePickerProps) {
       <DropdownContent class="min-w-[180px]">
         <DropdownItem onSelect={() => local.onScopeChange(undefined)}>All Content</DropdownItem>
         <Show when={local.availableAuthors?.length}>
-          <div class="px-2 py-1 text-[10px] uppercase tracking-wider text-muted-foreground">Authors</div>
+          <div class="px-2 py-1 text-micro uppercase tracking-wider text-muted-foreground">Authors</div>
           <For each={local.availableAuthors}>
             {(author) => (
               <DropdownItem onSelect={() => local.onScopeChange({ authors: [author] })}>{author}</DropdownItem>
@@ -44,7 +44,7 @@ export function ChatScopePicker(props: ChatScopePickerProps) {
           </For>
         </Show>
         <Show when={local.availableTags?.length}>
-          <div class="px-2 py-1 text-[10px] uppercase tracking-wider text-muted-foreground">Tags</div>
+          <div class="px-2 py-1 text-micro uppercase tracking-wider text-muted-foreground">Tags</div>
           <For each={local.availableTags}>
             {(tag) => (
               <DropdownItem onSelect={() => local.onScopeChange({ tags: [tag] })}>{tag}</DropdownItem>

package/src/components/chat-thread.tsx

@@ -19,6 +19,7 @@ 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';
+import type { JSX } from 'solid-js';
 
 export interface ChatThreadContextUsage {
   usedTokens: number;
@@ -45,6 +46,11 @@ export interface ChatThreadProps {
    *  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;
+  /** The custom-element host node to emit card events off when no `CardProvider`
+   *  is present, forwarded through `MessageBody` to `CardRenderer`. The
+   *  element facades pass their own host element so card events leave as the
+   *  bubbling `kai-card` CustomEvent. */
+  cardHostElement?: HTMLElement;
   /** 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. */
@@ -73,6 +79,19 @@ export interface ChatThreadProps {
   /** Enable Shiki syntax highlighting in code blocks. Turn off to render plain
    *  `<pre>` blocks (lighter, no highlighter load). Default true. */
   codeHighlight?: boolean;
+  /** How `reasoning` parts render across the thread. `'full'` (default) is the
+   *  current collapsible-disclosure behavior; `'compact'` shows only a shimmer
+   *  loader while a reasoning part streams and nothing once it settles (no
+   *  expandable detail); `'off'` renders reasoning parts not at all. Forwarded
+   *  to every `MessageBody` as `reasoningMode`. */
+  reasoning?: 'full' | 'compact' | 'off';
+  /** Seeds the reasoning disclosure open AND keeps it tracking the stream
+   *  (open while streaming, closes when it settles): the pre-Task-19f `full`
+   *  behavior. Default false/absent: the panel starts closed (just the
+   *  "Thinking" shimmer chip) and only opens on click, the current default
+   *  (owner ruling, 2026-08-26). Meaningless when `reasoning` is `'compact'`
+   *  or `'off'`. Forwarded to every `MessageBody` as `reasoningDefaultOpen`. */
+  reasoningOpen?: boolean;
   /** Optional header title shown on the left of the header. */
   chatTitle?: string;
   /** Optional model list. When set (>1 model) a ModelSwitcher is shown in the
@@ -90,6 +109,17 @@ export interface ChatThreadProps {
   headerStart?: boolean;
   /** Whether the host has `slot="header-end"` content (right of the controls). */
   headerEnd?: boolean;
+  /** Extra content rendered in the header-end region, AFTER `slot="header-end"`.
+   *  This is a JSX escape hatch for a caller composing `ChatThread` directly as a
+   *  Solid component (no shadow-DOM host, so there is no light-DOM node to slot) —
+   *  the `kai-dock`-docked construct widget is the motivating case: it needs its
+   *  own close affordance to sit IN the header row, sharing it with the title
+   *  instead of floating as a second control with no visible relationship to the
+   *  chat surface. Renders alongside the named slot rather than replacing it, so a
+   *  real `slot="header-end"` consumer and this prop can both be present. Counts
+   *  toward `showHeader()` the same as `headerEnd`, so a construct with no title
+   *  and only this content still gets a header row to sit in. */
+  headerEndContent?: JSX.Element;
   // ── Composition slots ─────────────────────────────────────────────────────
   // Each flag below is set by the `<kai-chat>` facade when matching light-DOM
   // `slot="…"` content is projected, and gates one composition slot. Two kinds:
@@ -106,6 +136,17 @@ export interface ChatThreadProps {
   sidebar?: boolean;
   /** REPLACE: custom zero-state rendered in the message area while the thread is empty (replaces the empty message list only; the composer and its suggestions still render). */
   empty?: boolean;
+  /** REPLACE, JSX form: the empty-state content itself, for a caller composing
+   *  `ChatThread` directly as a Solid component rather than through the `<kai-chat>`
+   *  shadow-DOM boundary that `empty`/`slot="empty"` targets. Renders INSIDE this
+   *  component's own tree — so a caller passing the kit's own `<Empty>` composition
+   *  (`components/empty.tsx`) gets it fully styled by the adopted stylesheet, unlike
+   *  `slot="empty"`: that slot only ever receives LIGHT-DOM children of the shadow
+   *  HOST, and light-DOM nodes are outside the shadow root's adopted stylesheets, so
+   *  Tailwind-utility-class content projected there renders bare. Takes priority
+   *  over `empty`/`slot="empty"` when both are set — the two are alternate delivery
+   *  mechanisms for the same region, not additive like `headerEndContent`. */
+  emptyContent?: JSX.Element;
   /** 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;
@@ -120,6 +161,10 @@ export interface ChatThreadProps {
   accept?: MediaTypeFilter;
   /** Files the composer refused because `accept` excluded them. */
   onAttachmentsRejected?: (rejected: RejectedAttachment[]) => void;
+  /** When `false`, hides the built-in paperclip attach button. Defaults to
+   *  `true` (undeclared keeps today's behavior: attach visible), matching
+   *  `DefaultPromptInput`'s own default: only an explicit `false` hides it. */
+  attach?: boolean;
   /** Show a web-search (Globe) button in the input toolbar; calls `onWebSearch`. */
   webSearch?: boolean;
   /** Show a Voice (Mic) button in the input toolbar; fires a `voice` event. */
@@ -252,7 +297,7 @@ export function ChatThread(props: ChatThreadProps) {
     if ((props.suggestionMode ?? 'submit') === 'fill') { handleChange(v); props.onSuggestionClick?.(v); }
     else { props.onSubmit?.({ value: v, attachments: attachments() }); afterSubmit(); }
   };
-  const showHeader = () => !!(props.chatTitle || props.models || props.context || props.headerStart || props.headerEnd);
+  const showHeader = () => !!(props.chatTitle || props.models || props.context || props.headerStart || props.headerEnd || props.headerEndContent);
   // Suggestions are conversation starters: show only on an empty thread unless
   // the host opts into persisting them.
   const visibleSuggestions = () =>
@@ -328,6 +373,11 @@ export function ChatThread(props: ChatThreadProps) {
                     {/* Consumer-injected trailing controls (share, settings, …).
                         Projects light-DOM `slot="header-end"` children of <kai-chat>. */}
                     <slot name="header-end" />
+                    {/* JSX escape hatch for a Solid-composed caller with no shadow-DOM
+                        host to slot into (see the prop doc) — a docked widget's own
+                        close affordance is the motivating case, sharing this row with
+                        the title instead of floating as an unrelated second control. */}
+                    {props.headerEndContent}
                   </div>
                 </header>
               </Show>
@@ -338,11 +388,15 @@ export function ChatThread(props: ChatThreadProps) {
           <div class="relative flex-1 overflow-hidden">
             <ChatContainer class="h-full px-4 py-3">
               <ChatContainerContent class="mx-auto w-full max-w-3xl space-y-4">
-                {/* REPLACE — custom empty-state slot, shown only while the thread is
+                {/* REPLACE — custom empty-state content, shown only while the thread is
                     empty. The component still owns WHEN it shows (data state); the
-                    consumer owns WHAT it looks like. */}
-                <Show when={props.empty && props.messages.length === 0}>
-                  <slot name="empty" />
+                    consumer owns WHAT it looks like. `emptyContent` (JSX, rendered
+                    in-tree and fully styled) wins over `empty`/`slot="empty"`
+                    (light-DOM projection) when both are set — see the prop doc. */}
+                <Show when={(props.empty || props.emptyContent) && props.messages.length === 0}>
+                  <Show when={props.emptyContent} fallback={<slot name="empty" />}>
+                    {props.emptyContent}
+                  </Show>
                 </Show>
                 {/* Keyed by message id (see the note above this component), so a
                     streaming delta updates the row instead of replacing it. */}
@@ -361,11 +415,17 @@ export function ChatThread(props: ChatThreadProps) {
                             parts={m().parts}
                             /* F-21: streaming-ness = the thread's ONE existing
                                loading signal + being the last message and an
-                               assistant turn. No second streaming source; the
-                               reasoning disclosure auto-opens on it. */
+                               assistant turn. No second streaming source. The
+                               reasoning disclosure no longer auto-opens on it
+                               by default (Task 19f, owner ruling 2026-08-26) —
+                               only the trigger's shimmer reflects streaming
+                               unless `reasoningOpen` opts back in. */
                             isStreaming={props.loading === true && m().role === 'assistant' && i() === props.messages.length - 1}
+                            reasoningMode={props.reasoning}
+                            reasoningDefaultOpen={props.reasoningOpen}
                             cardTypes={props.cardTypes}
                             cardSchemas={props.cardSchemas}
+                            cardHostElement={props.cardHostElement}
                             isUser={m().role === 'user'}
                             markdown={m().role === 'assistant'}
                             actions={m().actions}
@@ -408,7 +468,10 @@ export function ChatThread(props: ChatThreadProps) {
               </ChatContainerContent>
               <Show when={showScrollButton()}>
                 <div class="absolute bottom-4 left-1/2 flex w-full max-w-3xl -translate-x-1/2 justify-center px-5">
-                  <ScrollButton class="shadow-sm" />
+                  {/* The button now owns its elevation (kai-elevation); a `shadow-sm`
+                      here would set box-shadow a second time and the winner would
+                      be stylesheet order, not this call site. */}
+                  <ScrollButton />
                 </div>
               </Show>
             </ChatContainer>
@@ -430,7 +493,7 @@ export function ChatThread(props: ChatThreadProps) {
                     value={current()} placeholder={props.placeholder} loading={props.loading === true}
                     suggestions={visibleSuggestions()} attachments={attachments()}
                     accept={props.accept} onAttachmentsRejected={props.onAttachmentsRejected}
-                    webSearch={props.webSearch === true} voice={props.voice === true}
+                    attach={props.attach} webSearch={props.webSearch === true} voice={props.voice === true}
                     triggers={props.triggers} kindIcons={props.kindIcons}
                     onValueChange={handleChange} onSubmit={handleSubmit} onSuggestionClick={handleSuggestionClick}
                     onAttachmentsChange={(a) => { setAttachments(a); props.onAttachmentsChange?.(a); }}