@kitn.ai/ui 0.26.0 → 0.28.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>