@kitn.ai/ui 0.20.1 → 0.22.0

package/src/components/response-compare-types.ts

@@ -6,6 +6,7 @@
 // isolation.
 import type { ToolPart } from './tool';
 import type { AttachmentData } from './attachments';
+import type { MessagePart } from '../elements/chat-types';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
@@ -125,3 +126,27 @@ export function isAnyStreaming(pair: ComparePair | null): boolean {
   if (!pair) return false;
   return pair.some((c) => c.streaming === true);
 }
+
+/** Map a `CompareCandidate`'s flat legacy fields (content/reasoning/tools/
+ *  attachments) into the ordered `MessagePart[]` `MessageBody` now renders.
+ *  `CompareCandidate` stays its own independent shape (it is `<kai-compare>`'s
+ *  public `data` JSON, not a `ChatMessage`). This is purely a render-time
+ *  adapter, applied at each `MessageBody` call site. Order: reasoning (the
+ *  thinking trace) → tool calls (the actions taken) → attachments (anything
+ *  produced) → the final text answer, mirroring how an assistant turn reads. */
+export function candidateToParts(candidate: CompareCandidate): MessagePart[] {
+  const parts: MessagePart[] = [];
+  if (candidate.reasoning) {
+    parts.push({ type: 'reasoning', text: candidate.reasoning.text, label: candidate.reasoning.label });
+  }
+  for (const tool of candidate.tools ?? []) {
+    parts.push({ type: 'tool', tool });
+  }
+  for (const attachment of candidate.attachments ?? []) {
+    parts.push({ type: 'file', attachment });
+  }
+  if (candidate.content) {
+    parts.push({ type: 'text', text: candidate.content });
+  }
+  return parts;
+}

package/src/components/response-compare.tsx

@@ -24,6 +24,7 @@ import {
   type CompareSelection,
   type ResponseCompareData,
   buildSelection,
+  candidateToParts,
   isAnyStreaming,
   normalizeCandidates,
 } from './response-compare-types';
@@ -37,7 +38,7 @@ export type {
   ResponseCompareData,
   CompareSelection,
 } from './response-compare-types';
-export { normalizeCandidates, buildSelection, isAnyStreaming } from './response-compare-types';
+export { normalizeCandidates, buildSelection, isAnyStreaming, candidateToParts } from './response-compare-types';
 
 export type CompareLayout = 'auto' | 'columns' | 'tabs';
 
@@ -386,10 +387,7 @@ function CompareColumn(props: ColumnProps): JSX.Element {
           when={props.candidate.streaming}
           fallback={
             <MessageBody
-              content={props.candidate.content}
-              reasoning={props.candidate.reasoning}
-              tools={props.candidate.tools}
-              attachments={props.candidate.attachments}
+              parts={candidateToParts(props.candidate)}
               isUser={false}
               markdown={true}
             />
@@ -445,10 +443,7 @@ function CollapsedWinner(props: {
         {(c) => (
           <div class="min-w-0">
             <MessageBody
-              content={c().content}
-              reasoning={c().reasoning}
-              tools={c().tools}
-              attachments={c().attachments}
+              parts={candidateToParts(c())}
               isUser={false}
               markdown={true}
             />

package/src/components/source.tsx

@@ -20,21 +20,29 @@ function useSourceContext() {
 // --- Source (Root) ---
 
 export interface SourceProps {
-  href: string;
+  /** The citation's URL. OPTIONAL: every field of a model-produced citation is,
+   *  so a source can arrive with a title and no url. In that case the chip
+   *  renders as a plain, inert `<a>` with NO `href` attribute — which is valid
+   *  HTML and simply not a link — rather than `<a href="">`, which would
+   *  navigate to the current page. */
+  href?: string;
   children: JSX.Element;
 }
 
 function Source(props: SourceProps) {
+  const href = () => props.href ?? '';
   const domain = () => {
+    const h = href();
+    if (!h) return '';
     try {
-      return new URL(props.href).hostname;
+      return new URL(h).hostname;
     } catch {
-      return props.href.split('/').pop() || props.href;
+      return h.split('/').pop() || h;
     }
   };
 
   return (
-    <SourceContext.Provider value={{ get href() { return props.href; }, get domain() { return domain(); } }}>
+    <SourceContext.Provider value={{ get href() { return href(); }, get domain() { return domain(); } }}>
       <HoverCardRoot openDelay={150}>
         {props.children}
       </HoverCardRoot>
@@ -57,7 +65,8 @@ function SourceTrigger(props: SourceTriggerProps) {
   return (
     <HoverCardTrigger>
       <a
-        href={ctx.href}
+        // `undefined` OMITS the attribute — see SourceProps.href.
+        href={ctx.href || undefined}
         target="_blank"
         rel="noopener noreferrer"
         class={cn(
@@ -66,7 +75,8 @@ function SourceTrigger(props: SourceTriggerProps) {
           props.class
         )}
       >
-        <Show when={props.showFavicon}>
+        {/* No url, no favicon to look up. */}
+        <Show when={props.showFavicon && ctx.href}>
           <img
             src={`https://www.google.com/s2/favicons?sz=64&domain_url=${encodeURIComponent(ctx.href)}`}
             alt="favicon"
@@ -94,27 +104,35 @@ function SourceContent(props: SourceContentProps) {
   return (
     <HoverCardContent class={cn('w-80 p-0 shadow-xs', props.class)}>
       <a
-        href={ctx.href}
+        // `undefined` OMITS the attribute — see SourceProps.href.
+        href={ctx.href || undefined}
         target="_blank"
         rel="noopener noreferrer"
         class="flex flex-col gap-2 p-3"
       >
-        <div class="flex items-center gap-1.5">
-          <img
-            src={`https://www.google.com/s2/favicons?sz=64&domain_url=${encodeURIComponent(ctx.href)}`}
-            alt="favicon"
-            class="size-4 rounded-full"
-            width={16}
-            height={16}
-          />
-          <div class="text-primary truncate text-sm">
-            {ctx.domain.replace('www.', '')}
+        {/* The domain header row only means anything when there IS a url. */}
+        <Show when={ctx.href}>
+          <div class="flex items-center gap-1.5">
+            <img
+              src={`https://www.google.com/s2/favicons?sz=64&domain_url=${encodeURIComponent(ctx.href)}`}
+              alt="favicon"
+              class="size-4 rounded-full"
+              width={16}
+              height={16}
+            />
+            <div class="text-primary truncate text-sm">
+              {ctx.domain.replace('www.', '')}
+            </div>
           </div>
-        </div>
-        <div class="line-clamp-2 text-sm font-medium">{props.title}</div>
-        <div class="text-muted-foreground line-clamp-2 text-sm">
-          {props.description}
-        </div>
+        </Show>
+        <Show when={props.title}>
+          <div class="line-clamp-2 text-sm font-medium">{props.title}</div>
+        </Show>
+        <Show when={props.description}>
+          <div class="text-muted-foreground line-clamp-2 text-sm">
+            {props.description}
+          </div>
+        </Show>
       </a>
     </HoverCardContent>
   );
@@ -122,8 +140,16 @@ function SourceContent(props: SourceContentProps) {
 
 // --- SourceList (convenience) ---
 
-function SourceList(props: { children: JSX.Element; class?: string }) {
-  return <div class={cn('flex flex-wrap gap-1.5 mt-3', props.class)}>{props.children}</div>;
+export interface SourceListProps {
+  children: JSX.Element;
+  class?: string;
+  /** `::part` name(s) exposed on the row. The message body passes `"citations"`
+   *  so consumers can target the citation row from outside the shadow boundary. */
+  part?: string;
+}
+
+function SourceList(props: SourceListProps) {
+  return <div part={props.part} class={cn('flex flex-wrap gap-1.5 mt-3', props.class)}>{props.children}</div>;
 }
 
 export { Source, SourceTrigger, SourceContent, SourceList };

package/src/components/tasks-card.tsx

@@ -24,42 +24,19 @@ import { useCardHost } from '../primitives/card-host';
 import { Check, Circle, CircleCheck, X } from 'lucide-solid';
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Types (tasks.schema.json) — see src/primitives/card-schemas/tasks.schema.json
+// Types (tasks.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 TasksTask {
-  id: string;
-  label: string;
-  description?: string;
-  checked?: boolean;
-  disabled?: boolean;
-}
-
-export interface TasksCardData {
-  /**
-   * `select` (default) = checkbox rows + a confirm button that emits the contract
-   * `submit`. `progress` = an onboarding/checklist look: a header `done / total`
-   * count, circular indicators, per-item title + muted description, and NO confirm
-   * button (checking a row is itself the terminal action). Both share the same
-   * selection model (toggle by id, the `max` gate, `kai-value-change`); `progress`
-   * is purely a presentational variant.
-   */
-  mode?: 'select' | 'progress';
-  heading?: string;
-  tasks: TasksTask[]; // >=1
-  selectAll?: boolean;
-  confirmLabel?: string;
-  allowEmpty?: boolean;
-  min?: number;
-  max?: number;
-  dismissible?: boolean; // show a close affordance that emits `dismiss`
-}
-
-export interface TasksCardResult {
-  selected: string[];
-}
+import type { TasksCardData, TasksCardResult, TasksTask } from '../primitives/card-data-types';
 
-export type TasksCardEnvelope = CardEnvelope<'tasks', TasksCardData>;
+export type {
+  TasksCardData,
+  TasksCardEnvelope,
+  TasksCardResult,
+  TasksTask,
+} from '../primitives/card-data-types';
 
 export const TASKS_CARD_TYPE = 'tasks' as const;
 

package/src/components/thread.tsx

@@ -1,4 +1,4 @@
-import { For, Show, onMount, type JSX } from 'solid-js';
+import { For, Show, createMemo, onMount, type JSX } from 'solid-js';
 import { ChatConfig, useChatConfig } from '../primitives/chat-config';
 import { ChatContainer, ChatContainerContent, ChatContainerScrollAnchor } from './chat-container';
 import { Message, MessageAvatar, MessageBody } from './message';
@@ -7,6 +7,8 @@ import { ScrollButton } from './scroll-button';
 import { Loader } from './loader';
 import type { ChatMessage } from '../elements/chat-types';
 import type { ProseSize } from '../primitives/chat-config';
+import type { CardComponentMap } from '../primitives/card-registry';
+import type { CardSchemaMap } from './card-renderer';
 
 /** Imperative handle exposed via `controllerRef` — the thread's scroll control,
  *  forwarded onto `<kai-thread>` as the `scrollToBottom()` instance method. */
@@ -19,9 +21,19 @@ export interface ThreadProps {
   /** Extra classes for the thread root (e.g. `rounded-xl`). */
   class?: string;
   /** The full message thread to render, newest last. Each entry carries its role,
-   *  content, and optional reasoning/tools/attachments/actions/avatar. A new array
-   *  reference per streaming chunk re-renders (mutating in place does not). */
+   *  ordered `parts`, and optional actions/avatar/feedback. A new array reference
+   *  per streaming chunk re-renders (mutating in place does not). */
   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;
   /** Show a typing indicator on the pending assistant turn — use while awaiting
    *  the assistant's reply. */
   loading?: boolean;
@@ -85,6 +97,11 @@ export function Thread(props: ThreadProps) {
   });
   const showScrollButton = () => props.scrollButton !== false;
   const showEmpty = () => props.messages.length === 0 && !props.loading;
+  // Keyed by message id, NOT by object reference: a streaming message is a new
+  // object every delta, and a reference-keyed <For> rebuilds the whole row for
+  // each one — which is why expanding a tool/reasoning panel mid-stream used to
+  // do nothing. Full rationale (and why not `<Index>`) in `chat-thread.tsx`.
+  const messageKeys = createMemo(() => props.messages.map((m) => m.id));
 
   // Hand the imperative controller to the facade once mounted (rootEl is set).
   onMount(() => {
@@ -116,46 +133,71 @@ export function Thread(props: ThreadProps) {
                 {props.empty}
               </Show>
             </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>
-                );
-              }}
+            <For each={messageKeys()}>
+              {(_id, i) => (
+                // Read the message through <For>'s index accessor, never through
+                // a captured value — the row outlives the delta that replaced its
+                // object. <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, and it has to be forwarded on BOTH
+                      // branches. `Message` turns it into `role="article"` + an
+                      // `aria-label` naming the speaker; without it the row is a
+                      // bare div that chromium prunes from the accessibility tree
+                      // as "uninteresting", so a screen reader gets no speaker at
+                      // all. Every other read of `m().role` here is cosmetic
+                      // (alignment, markdown), which is exactly how it went
+                      // missing: the value was in hand and used for styling while
+                      // being dropped for semantics.
+                      <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>
-            {/* Typing indicator on the pending assistant turn. */}
+            {/* Typing indicator on the pending assistant turn.
+                DELIBERATELY role-less, unlike the rows above — this is not an
+                oversight of the same kind. There is no message here yet, so
+                `role="assistant"` would announce an empty article named
+                "Assistant message". What a pending indicator needs instead is a
+                live region, so its ARRIVAL and departure are announced. The
+                Loader already carries an accessible name — an sr-only "Loading"
+                on all nine shape variants — and what it lacks is the
+                `role="status"` / aria-live wrapper around it. A real but
+                SEPARATE gap, and it lives in loader.tsx. Filed, not fixed here. */}
             <Show when={props.loading}>
               <Message class="flex-col items-start">
                 <div class="rounded-lg px-1 py-2">

package/src/components/toast.tsx

@@ -59,7 +59,7 @@ function usePrefersReducedMotion() {
 
 // ── Single toast pill ────────────────────────────────────────────────────────
 
-interface ToastProps {
+export interface ToastProps {
   item: ToastItem;
   onDismiss: (reason: ToastDismissReason) => void;
   onAction?: (label: string) => void;
@@ -214,7 +214,12 @@ export function Toast(props: ToastProps) {
     <Show when={presence.present()}>
       <div
         ref={presence.setRef}
-        role="status"
+        // `variant` already picks the error ICON; it has to pick the ROLE too, or
+        // a failure is announced with the same (polite, easily missed) urgency as
+        // a success. `alert` is implicitly assertive and interrupts, which is what
+        // the region's `aria-live="polite"` alone will not do for the toast that
+        // actually matters. Same expression as ui/notice.tsx.
+        role={variant() === 'error' ? 'alert' : 'status'}
         data-appearance={appearance()}
         data-inverse={inverse() ? '' : undefined}
         data-closed={presence.state() === 'closed' ? '' : undefined}
@@ -388,6 +393,12 @@ export function ToastRegion(props: ToastRegionProps) {
   createEffect(() => {
     const t = props.target;
     if (!t || typeof window === 'undefined') { setAnchor(null); return; }
+    // 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 `window` there throws.
+    // See tests/components/teardown-without-dom-globals.test.tsx.
+    const win = window;
     const update = () => {
       const r = t.getBoundingClientRect();
       setAnchor({ top: r.top, left: r.left, right: r.right, bottom: r.bottom, width: r.width });
@@ -395,12 +406,12 @@ export function ToastRegion(props: ToastRegionProps) {
     update();
     const ro = new ResizeObserver(update);
     ro.observe(t);
-    window.addEventListener('scroll', update, true);
-    window.addEventListener('resize', update);
+    win.addEventListener('scroll', update, true);
+    win.addEventListener('resize', update);
     onCleanup(() => {
       ro.disconnect();
-      window.removeEventListener('scroll', update, true);
-      window.removeEventListener('resize', update);
+      win.removeEventListener('scroll', update, true);
+      win.removeEventListener('resize', update);
     });
   });
 

package/src/components/tool-classify.ts

@@ -0,0 +1,26 @@
+/** Semantic classification of a tool call, used to pick a rendering. Derived from
+ *  the provider-chosen tool NAME, which is arbitrary, so this stays conservative and
+ *  prefers 'generic' over a confident wrong answer. */
+export type ToolKind =
+  | 'command'
+  | 'file-change'
+  | 'search'
+  | 'fetch'
+  | 'mcp'
+  | 'image'
+  | 'generic';
+
+/** Total, deterministic, side-effect free. ALWAYS terminates in 'generic' so an
+ *  unrecognized tool still renders a panel instead of a blank. Order matters:
+ *  'search' is tested before 'fetch' so `web_search` classifies as a search. */
+export function classifyTool(name: string): ToolKind {
+  const n = name.toLowerCase();
+  if (!n) return 'generic';
+  if (n.includes('bash') || n.includes('command') || n.includes('shell') || n.includes('terminal') || n.includes('exec')) return 'command';
+  if (n.includes('edit') || n.includes('write') || n.includes('patch') || n.includes('replace') || n.includes('delete')) return 'file-change';
+  if (n.includes('search') || n.includes('grep') || n.includes('glob') || n.includes('find')) return 'search';
+  if (n.includes('fetch') || n.includes('http') || n.includes('browse') || n.includes('crawl')) return 'fetch';
+  if (n.includes('mcp')) return 'mcp';
+  if (n.includes('image') || n.includes('screenshot') || n.includes('vision')) return 'image';
+  return 'generic';
+}

package/src/components/tool-types.ts

@@ -1,10 +1,40 @@
+import type { ToolKind } from './tool-classify';
+
+/** The untranslated provider payload a part was normalized from.
+ *
+ *  Optional in the type but REQUIRED in practice for round-trip fidelity. Anthropic
+ *  returns a 400 invalid_request_error if `thinking` blocks are modified, reordered,
+ *  filtered or RECONSTRUCTED, so an encoder must send `raw.payload` back verbatim
+ *  rather than rebuilding a block from `text` + `signature`. */
+export interface RawOrigin {
+  /** Tagged origin, e.g. 'anthropic.content_block', 'openai.delta', `custom.${string}`. */
+  source: string;
+  payload: unknown;
+}
+
 /** A tool-call part rendered by <Tool>. Pure type — kept JSX-free so it can be
- *  imported by the framework-neutral state core and the React typecheck pass. */
+ *  imported by the framework-neutral state core and the React typecheck pass.
+ *
+ *  Adding a field here also requires adding it to `TOOL_KEYS` (and a comparator
+ *  in `TOOL_COMPARATORS`) in `state/parts.ts`, or `tsc` fails to compile: those
+ *  drive `upsertToolPart`'s dedupe check, and a field missing from them would
+ *  silently make that check ignore the new field, keeping a stale array
+ *  reference alive when only that field changed. */
 export interface ToolPart {
+  /** The tool name exactly as the provider reported it. */
   type: string;
+  /** Semantic classification for rendering. Derive with classifyTool(type). */
+  kind?: ToolKind;
   state: 'input-streaming' | 'input-available' | 'output-available' | 'output-error';
+  /** Last VALID parsed snapshot, fingerprint-deduped. The primary channel: this is
+   *  what the kit renders. */
   input?: Record<string, unknown>;
+  /** Raw accumulated argument fragments, for consumers wanting character-level
+   *  streaming. Most consumers should read `input` instead. */
+  rawInput?: string;
   output?: Record<string, unknown>;
   toolCallId?: string;
   errorText?: string;
+  /** The untranslated provider payload this was normalized from. */
+  raw?: RawOrigin;
 }

package/src/elements/agent-card.tsx

@@ -2,26 +2,26 @@ import { defineWebComponent } from './define';
 import { AgentCard, type AgentStatus } from '../ui/agent-card';
 
 interface Props extends Record<string, unknown> {
-  /** The agent's name — the primary label. Attribute: `name`. */
+  /** The agent's name, the primary label. Attribute: `name`. */
   name?: string;
   /** Selected / focused state: highlighted border + surface. Attribute: `active`. */
   active?: boolean;
-  /** Raise a prominent "Needs you" pill plus a glowing amber edge — the
-   *  attention-routing signal that pulls focus to this agent. Attribute:
-   *  `needs-attention`. */
+  /** Raise a prominent "Needs you" pill plus a glowing amber edge. This
+   *  is the attention-routing signal that pulls focus to this agent.
+   *  Attribute: `needs-attention`. */
   needsAttention?: boolean;
-  /** Run status — a JS PROPERTY (object), not an attribute. Shape:
-   *  `{ tone, label?, pulse? }`, where `tone` is one of `working` | `idle` |
-   *  `done` | `error` | `blocked` (maps to the kit's tool hues), `label` is an
-   *  optional short string beside the dot, and `pulse` animates the dot. Set it
-   *  with `el.status = { tone: 'working', label: 'Working', pulse: true }`. */
+  /** Run status. A JS PROPERTY (object), not an attribute. Shape: `{ tone,
+   *  label?, pulse? }`, where `tone` is one of `working` | `idle` | `done` |
+   *  `error` | `blocked` (maps to the kit's tool hues), `label` is an optional
+   *  short string beside the dot, and `pulse` animates the dot. Set it with
+   *  `el.status = { tone: 'working', label: 'Working', pulse: true }`. */
   status?: AgentStatus;
 }
 
 /** Events fired by `<kai-agent-card>`. */
 interface Events {
-  /** The card was activated — clicked, or Enter / Space while focused. Promote
-   *  this agent back to focus. */
+  /** The card was activated by a click, or by Enter / Space while focused.
+   *  Promote this agent back to focus. */
   'kai-activate': void;
   /** The trailing "..." kebab was clicked. The consumer opens its own menu; the
    *  card only surfaces the affordance (the click does not also activate the card). */

package/src/elements/artifact.tsx

@@ -5,8 +5,10 @@ import { Artifact, type ArtifactController, type ArtifactFile, type ArtifactTab
 interface Props extends Record<string, unknown> {
   /** URL the preview iframe frames. Consumer-controlled. */
   src?: string;
-  /** Files for the Code tab tree + each file's preview `url`. Set as a JS property (array). */
-  files: ArtifactFile[];
+  /** Files for the Code tab tree + each file's preview `url`. Omit for a
+   *  preview-only artifact (the Code tab then has nothing to show; pair it with
+   *  `no-tabs` to hide the toggle). Set as a JS property (array). */
+  files?: ArtifactFile[];
   /** Controlled active tab: `preview` or `code`. When set, the artifact follows it
    *  (re-asserted on change). Leave unset for an uncontrolled tab (see `defaultTab`). */
   tab?: ArtifactTab;
@@ -14,7 +16,7 @@ interface Props extends Record<string, unknown> {
    *  Seeds the starting tab; the user can then switch freely without the consumer
    *  re-asserting a controlled `tab`. */
   defaultTab?: ArtifactTab;
-  /** Selected file path — syncs the tree highlight, Code source, and preview. */
+  /** Selected file path. Syncs the tree highlight, Code source, and preview. */
   activeFile?: string;
   /** iframe `sandbox` override. Secure default `allow-scripts allow-forms` (NOT `allow-same-origin`). */
   sandbox?: string;
@@ -56,6 +58,12 @@ interface Events extends Record<string, unknown> {
   'kai-file-select': { path: string };
   /** Artifact's own maximize button toggled (consumer-observable; non-bubbling). */
   'kai-maximize-change': { maximized: boolean };
+  /** The maximize PROTOCOL intent, raised as a raw bubbling + composed CustomEvent
+   *  (not through `dispatch`) so an enclosing `<kai-resizable>` can catch it and
+   *  maximize the containing panel. Declared here so it is typed and reaches the
+   *  generated API. Listen for it to drive maximize from your own chrome, or
+   *  re-emit it to trigger one. */
+  'kai-maximize-intent': { requested: boolean };
 }
 
 /**
@@ -106,17 +114,17 @@ defineWebComponent<Props, Events>('kai-artifact', {
     reload: () => controller?.reload(),
     /** Navigate to the `src` home url (no-op when there's no `src`). */
     home: () => controller?.home(),
-    /** Push + load a url in the preview — the path-field submit path (fires kai-navigate). */
+    /** Push + load a url in the preview, the path-field submit path (fires kai-navigate). */
     navigate: (url: string) => controller?.navigate(url),
     /** Select a file by path: highlights the tree, shows its source, navigates the
      *  preview (fires kai-file-select + kai-navigate). Named selectFile to avoid the
      *  `activeFile` prop. */
     selectFile: (path: string) => controller?.selectFile(path),
     /** Open the current url in a new browser tab (no-op when there's no concrete url).
-     *  Named openExternal, NOT openInTab — that's a prop (toolbar button visibility). */
+     *  Named openExternal, NOT openInTab, which is a prop (toolbar button visibility). */
     openExternal: () => controller?.openExternal(),
     /** Enter the maximized view-state (fires kai-maximize-change{maximized:true}).
-     *  Named maximize, NOT maximized — that's a prop. */
+     *  Named maximize, NOT maximized, which is a prop. */
     maximize: () => controller?.maximize(),
     /** Exit the maximized view-state (fires kai-maximize-change{maximized:false}). */
     restore: () => controller?.restore(),
@@ -157,7 +165,7 @@ defineWebComponent<Props, Events>('kai-artifact', {
       >
         <Artifact
           src={props.src}
-          files={props.files}
+          files={props.files ?? []}
           tab={props.tab}
           defaultTab={props.defaultTab}
           activeFile={props.activeFile}