@kitn.ai/ui 0.17.0 → 0.18.0

package/src/components/file-tree.tsx

@@ -30,8 +30,30 @@ export interface FileTreeFile {
   language?: string;
   /** Kind — drives the icon + whether Code applies. */
   type?: 'html' | 'pdf' | 'image' | 'other';
+  /** Lines added vs the base. Rendered as a trailing `+N` stat (success hue,
+   *  tabular-nums). Only shown when present; omit for a plain file row. */
+  additions?: number;
+  /** Lines removed vs the base. Rendered as a trailing `-N` stat (error hue). */
+  deletions?: number;
+  /** Change status vs the base. Drives a small trailing status letter in the
+   *  conventional VCS hue (added=green, modified=amber, deleted=red,
+   *  renamed=blue, untracked=muted). Only shown when present. */
+  status?: 'added' | 'modified' | 'deleted' | 'renamed' | 'untracked';
 }
 
+/** A change status a file can carry. */
+export type FileStatus = NonNullable<FileTreeFile['status']>;
+
+/** Per-status letter, accessible word, and tool-hue text class. Conventional VCS
+ *  colors so a changed-files view reads at a glance. */
+const STATUS_META: Record<FileStatus, { letter: string; label: string; class: string }> = {
+  added: { letter: 'A', label: 'added', class: 'text-tool-green' },
+  modified: { letter: 'M', label: 'modified', class: 'text-tool-amber' },
+  deleted: { letter: 'D', label: 'deleted', class: 'text-tool-red' },
+  renamed: { letter: 'R', label: 'renamed', class: 'text-tool-blue' },
+  untracked: { letter: 'U', label: 'untracked', class: 'text-muted-foreground' },
+};
+
 /** A folder node in the built tree. */
 export interface FileTreeFolderNode {
   kind: 'folder';
@@ -134,6 +156,48 @@ function iconFor(type: FileTreeFile['type']) {
   }
 }
 
+/** Every folder path in the tree (render order) — drives collapse-all/expand-all. */
+function collectFolderPaths(nodes: FileTreeNode[], out: string[] = []): string[] {
+  for (const n of nodes) {
+    if (n.kind === 'folder') {
+      out.push(n.path);
+      collectFolderPaths(n.children, out);
+    }
+  }
+  return out;
+}
+
+/** Every leaf file in the tree — drives the summary header totals. */
+function collectFiles(nodes: FileTreeNode[], out: FileTreeFile[] = []): FileTreeFile[] {
+  for (const n of nodes) {
+    if (n.kind === 'folder') collectFiles(n.children, out);
+    else out.push(n.file);
+  }
+  return out;
+}
+
+/** Whether a file carries any diff metadata (status / additions / deletions). */
+function hasDiffMeta(file: FileTreeFile): boolean {
+  return file.status !== undefined || file.additions !== undefined || file.deletions !== undefined;
+}
+
+/**
+ * Accessible name for a changed-file row: the file name plus its status and diff
+ * stats, e.g. `App.tsx, modified, 3 additions, 1 deletion`. Returns `undefined`
+ * when the file has no diff metadata, so a plain row keeps its text content as
+ * the accessible name (unchanged behavior).
+ */
+function fileAccessibleName(name: string, file: FileTreeFile): string | undefined {
+  if (!hasDiffMeta(file)) return undefined;
+  const parts: string[] = [];
+  if (file.status) parts.push(STATUS_META[file.status].label);
+  if (file.additions !== undefined)
+    parts.push(`${file.additions} addition${file.additions === 1 ? '' : 's'}`);
+  if (file.deletions !== undefined)
+    parts.push(`${file.deletions} deletion${file.deletions === 1 ? '' : 's'}`);
+  return [name, ...parts].join(', ');
+}
+
 export interface FileTreeProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, 'onSelect'> {
   /** Flat file list; folders are derived from `/`-delimited paths. */
   files: FileTreeFile[];
@@ -143,6 +207,10 @@ export interface FileTreeProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>,
   onSelect?: (path: string, file: FileTreeFile) => void;
   /** Folder paths expanded by default. When omitted, all folders start open. */
   defaultExpanded?: string[];
+  /** Show a summary header above the tree: the changed-file count, the summed
+   *  `+additions / -deletions`, and a Collapse-all/Expand-all toggle wired to the
+   *  folder-expand state. Off by default (no header — unchanged behavior). */
+  summary?: boolean;
 }
 
 /**
@@ -157,6 +225,7 @@ export function FileTree(props: FileTreeProps): JSX.Element {
     'activeFile',
     'onSelect',
     'defaultExpanded',
+    'summary',
     'class',
   ]);
 
@@ -196,6 +265,23 @@ export function FileTree(props: FileTreeProps): JSX.Element {
     }
   };
 
+  // Summary header derivations (only read when `summary` is set).
+  const folderPaths = createMemo(() => collectFolderPaths(tree()));
+  const leafFiles = createMemo(() => collectFiles(tree()));
+  const fileCount = () => leafFiles().length;
+  const totalAdds = () => leafFiles().reduce((sum, f) => sum + (f.additions ?? 0), 0);
+  const totalDels = () => leafFiles().reduce((sum, f) => sum + (f.deletions ?? 0), 0);
+  const anyOpen = () => folderPaths().some((p) => isOpen(p));
+  const collapseAll = () => {
+    if (defaultAllOpen()) setClosedSet(new Set<string>(folderPaths()));
+    else setOpenSet(new Set<string>());
+  };
+  const expandAll = () => {
+    if (defaultAllOpen()) setClosedSet(new Set<string>());
+    else setOpenSet(new Set<string>(folderPaths()));
+  };
+  const toggleAll = () => (anyOpen() ? collapseAll() : expandAll());
+
   const [focusedPath, setFocusedPath] = createSignal<string | undefined>();
 
   const selectFile = (node: FileTreeFileNode) => {
@@ -247,27 +333,59 @@ export function FileTree(props: FileTreeProps): JSX.Element {
   };
 
   return (
-    <div
-      role="tree"
-      aria-label="Files"
-      class={cn('text-sm select-none', local.class)}
-      {...rest}
-    >
-      <For each={tree()}>
-        {(node) => (
-          <TreeNode
-            node={node}
-            depth={0}
-            isOpen={isOpen}
-            toggle={toggle}
-            activeFile={() => local.activeFile}
-            focusedPath={focusedPath}
-            onSelectFile={selectFile}
-            onKeyDown={onKeyDown}
-          />
-        )}
-      </For>
-    </div>
+    <>
+      <Show when={local.summary}>
+        <div
+          part="summary"
+          class="flex items-center gap-2 px-2 py-1.5 text-xs text-muted-foreground border-b border-border"
+        >
+          <span class="font-medium text-foreground">
+            {fileCount()} {fileCount() === 1 ? 'file' : 'files'} changed
+          </span>
+          <Show when={totalAdds() > 0}>
+            <span class="text-tool-green tabular-nums">+{totalAdds()}</span>
+          </Show>
+          <Show when={totalDels() > 0}>
+            <span class="text-tool-red tabular-nums">-{totalDels()}</span>
+          </Show>
+          <Show when={folderPaths().length > 0}>
+            <button
+              type="button"
+              class={cn(
+                'ml-auto rounded-md px-1.5 py-0.5 font-medium text-muted-foreground outline-none',
+                'hover:bg-muted hover:text-foreground',
+                'focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset',
+              )}
+              aria-label={anyOpen() ? 'Collapse all folders' : 'Expand all folders'}
+              onClick={toggleAll}
+            >
+              {anyOpen() ? 'Collapse all' : 'Expand all'}
+            </button>
+          </Show>
+        </div>
+      </Show>
+      <div
+        role="tree"
+        aria-label="Files"
+        class={cn('text-sm select-none', local.class)}
+        {...rest}
+      >
+        <For each={tree()}>
+          {(node) => (
+            <TreeNode
+              node={node}
+              depth={0}
+              isOpen={isOpen}
+              toggle={toggle}
+              activeFile={() => local.activeFile}
+              focusedPath={focusedPath}
+              onSelectFile={selectFile}
+              onKeyDown={onKeyDown}
+            />
+          )}
+        </For>
+      </div>
+    </>
   );
 }
 
@@ -300,32 +418,64 @@ function TreeNode(props: TreeNodeProps): JSX.Element {
   return (
     <Show
       when={props.node.kind === 'folder'}
-      fallback={
-        <div
-          role="treeitem"
-          aria-selected={isActive()}
-          data-tree-path={props.node.path}
-          data-tree-kind="file"
-          tabindex={tabIndex()}
-          class={cn(
-            'flex items-center gap-1.5 rounded-md py-1 pr-2 cursor-pointer outline-none',
-            'focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset',
-            isActive()
-              ? 'bg-primary/10 text-foreground font-medium'
-              : 'text-muted-foreground hover:bg-muted hover:text-foreground',
-          )}
-          style={indent()}
-          onClick={() => props.onSelectFile(props.node as FileTreeFileNode)}
-          onKeyDown={(e) => props.onKeyDown(e, props.node)}
-        >
-          <span class="w-3.5 shrink-0" />
-          {(() => {
-            const Icon = iconFor((props.node as FileTreeFileNode).file.type);
-            return <Icon size={14} class="shrink-0 opacity-70" aria-hidden="true" />;
-          })()}
-          <span class="truncate">{node().name}</span>
-        </div>
-      }
+      fallback={(() => {
+        const file = (props.node as FileTreeFileNode).file;
+        const ariaName = fileAccessibleName(node().name, file);
+        const hasMeta = ariaName !== undefined;
+        const status = file.status ? STATUS_META[file.status] : undefined;
+        return (
+          <div
+            role="treeitem"
+            aria-selected={isActive()}
+            aria-label={ariaName}
+            data-tree-path={props.node.path}
+            data-tree-kind="file"
+            tabindex={tabIndex()}
+            class={cn(
+              'flex items-center gap-1.5 rounded-md py-1 pr-2 cursor-pointer outline-none',
+              'focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset',
+              isActive()
+                ? 'bg-primary/10 text-foreground font-medium'
+                : 'text-muted-foreground hover:bg-muted hover:text-foreground',
+            )}
+            style={indent()}
+            onClick={() => props.onSelectFile(props.node as FileTreeFileNode)}
+            onKeyDown={(e) => props.onKeyDown(e, props.node)}
+          >
+            <span class="w-3.5 shrink-0" />
+            {(() => {
+              const Icon = iconFor(file.type);
+              return <Icon size={14} class="shrink-0 opacity-70" aria-hidden="true" />;
+            })()}
+            <span class={cn('truncate', hasMeta && 'min-w-0 flex-1')}>{node().name}</span>
+            <Show when={hasMeta}>
+              <span
+                class="ml-auto flex items-center gap-1.5 shrink-0 pl-2 text-xs"
+                aria-hidden="true"
+              >
+                <Show when={file.additions !== undefined}>
+                  <span part="stat-additions" class="text-tool-green tabular-nums">
+                    +{file.additions}
+                  </span>
+                </Show>
+                <Show when={file.deletions !== undefined}>
+                  <span part="stat-deletions" class="text-tool-red tabular-nums">
+                    -{file.deletions}
+                  </span>
+                </Show>
+                <Show when={status}>
+                  <span
+                    part="status"
+                    class={cn('w-3 text-center font-mono font-semibold', status!.class)}
+                  >
+                    {status!.letter}
+                  </span>
+                </Show>
+              </span>
+            </Show>
+          </div>
+        );
+      })()}
     >
       <div role="none">
         <div

package/src/components/form-widgets.tsx

@@ -1,6 +1,7 @@
 import { type JSX, For, Show, createSignal } from 'solid-js';
 import { cn } from '../utils/cn';
 import { Textarea } from '../ui/textarea';
+import { Input, FIELD_BASE as inputBase } from '../ui/input';
 import { Star } from 'lucide-solid';
 import type { FormField } from './form';
 
@@ -19,9 +20,6 @@ export interface WidgetProps {
   onBlur: () => void;
 }
 
-const inputBase =
-  'w-full rounded-md border border-input bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50 disabled:pointer-events-none';
-
 function ariaProps(p: WidgetProps) {
   return {
     'aria-required': p.required || undefined,
@@ -52,20 +50,24 @@ export function TextWidget(
         return 'text';
     }
   };
+  // Render the bare `Input` control (no label/hint/error): `kai-form`'s FieldRow
+  // already supplies the label, description, and inline error around the widget.
+  // `Input` owns the field styling (its `FIELD_BASE` is the former `inputBase`),
+  // so the rendered input is byte-identical to the old raw `<input>`.
   return (
-    <input
+    <Input
       id={props.id}
       data-control
       type={inputType()}
-      class={cn(inputBase, props.invalid && 'border-destructive dark:border-red-400/70')}
       value={(props.value as string) ?? ''}
       placeholder={props.placeholder}
+      invalid={props.invalid}
       disabled={props.disabled}
       minLength={props.field.minLength}
       maxLength={props.field.maxLength}
       {...ariaProps(props)}
-      onInput={(e) => props.onInput(e.currentTarget.value)}
-      onBlur={props.onBlur}
+      onValueInput={(value) => props.onInput(value)}
+      onValueChange={() => props.onBlur()}
     />
   );
 }

package/src/components/form.tsx

@@ -8,6 +8,7 @@ import {
   createMemo,
   createEffect,
   on,
+  onMount,
   ErrorBoundary,
 } from 'solid-js';
 import { createStore, produce, unwrap } from 'solid-js/store';
@@ -355,6 +356,25 @@ export function buildResult(
 // The <Form> component.
 // ─────────────────────────────────────────────────────────────────────────────
 
+/** Imperative handle exposed via `controllerRef` — surfaces the form's latent
+ *  capabilities (focus the first/first-invalid control, validate, programmatic
+ *  send, reset to defaults, dismiss/reopen) so the `<kai-form>` facade can forward
+ *  them as instance methods. */
+export interface FormController {
+  /** Focus the first control, or the first INVALID control after a failed validation. */
+  focus(options?: FocusOptions): void;
+  /** Run full validation + submit: focus the first invalid field on failure, else emit `submit`. */
+  send(): void;
+  /** Run client-side validation now and return per-field errors WITHOUT submitting. */
+  validate(): { valid: boolean; errors?: Record<string, string> };
+  /** Re-seed from each field's `default` and clear errors. */
+  reset(): void;
+  /** Trigger the dismiss path (emit `dismiss` + collapse to the re-openable stub). */
+  dismiss(): void;
+  /** Re-open a dismissed card from its stub (emit `reopen`). */
+  reopen(): void;
+}
+
 export interface FormProps {
   /** The form definition (CardEnvelope.data). */
   data?: FormDefinition;
@@ -370,6 +390,16 @@ export interface FormProps {
   class?: string;
   /** When set, render the chromed read-only view instead of the form inputs. */
   resolution?: CardResolution;
+  /** Controlled field values — when set, this wins over internal/uncontrolled state. */
+  values?: Record<string, unknown>;
+  /** Initial values overlaying the schema defaults (uncontrolled seed). */
+  defaultValues?: Record<string, unknown>;
+  /** Disable all fields + submit. */
+  disabled?: boolean;
+  /** Fires on input with the current coerced values + validity (distinct from submit). */
+  onValuesChange?: (payload: { values: Record<string, unknown>; valid: boolean }) => void;
+  /** Receive the imperative controller once mounted. */
+  controllerRef?: (controller: FormController) => void;
 }
 
 const DEFAULT_FORM: FormDefinition = { type: 'object', properties: {} };
@@ -383,7 +413,10 @@ const DEFAULT_FORM: FormDefinition = { type: 'object', properties: {} };
  */
 export function Form(props: FormProps): JSX.Element {
   const merged = mergeProps({ cardId: 'kai-form' }, props);
-  const [local] = splitProps(merged, ['data', 'cardId', 'heading', 'host', 'hostElement', 'class', 'resolution']);
+  const [local] = splitProps(merged, [
+    'data', 'cardId', 'heading', 'host', 'hostElement', 'class', 'resolution',
+    'values', 'defaultValues', 'disabled', 'onValuesChange', 'controllerRef',
+  ]);
 
   const ctxHost = useCardHost();
 
@@ -414,7 +447,34 @@ export function Form(props: FormProps): JSX.Element {
   const [values, setValues] = createStore<Record<string, unknown>>({});
   const [errors, setErrors] = createStore<Record<string, string>>({});
 
+  // Build the seed value map: schema `default`s, overlaid by `defaultValues`, then
+  // (when controlled) the live `values` prop. The controlled prop always wins.
+  const seedMap = (d: FormDefinition): Record<string, unknown> => {
+    const next: Record<string, unknown> = {};
+    for (const [key, field] of Object.entries(d.properties ?? {})) {
+      if (field.default !== undefined) next[key] = field.default;
+      else if (field.type === 'array') next[key] = [];
+    }
+    if (local.defaultValues) Object.assign(next, local.defaultValues);
+    if (local.values) Object.assign(next, local.values);
+    return next;
+  };
+
   const seed = (d: FormDefinition): void => {
+    const next = seedMap(d);
+    setValues(produce((s) => {
+      for (const k of Object.keys(s)) delete s[k];
+      Object.assign(s, next);
+    }));
+    setErrors(produce((s) => {
+      for (const k of Object.keys(s)) delete s[k];
+    }));
+  };
+
+  // Reset to defaults only (ignore the controlled `values`/`defaultValues` overlay):
+  // re-seed from each field's schema `default` and clear errors. Used by reset().
+  const seedDefaults = (): void => {
+    const d = def();
     const next: Record<string, unknown> = {};
     for (const [key, field] of Object.entries(d.properties ?? {})) {
       if (field.default !== undefined) next[key] = field.default;
@@ -432,6 +492,16 @@ export function Form(props: FormProps): JSX.Element {
   // Reseed whenever a NEW valid definition arrives.
   createEffect(on(() => local.data, () => { if (envelopeValid().ok) seed(def()); }));
 
+  // Controlled values: when the consumer drives `values`, mirror it into the store
+  // (the controlled prop wins over local edits). Deferred so mount's seed runs first.
+  createEffect(on(() => local.values, (v) => {
+    if (!v) return;
+    setValues(produce((s) => {
+      for (const k of Object.keys(s)) delete s[k];
+      Object.assign(s, v);
+    }));
+  }, { defer: true }));
+
   // ready + error lifecycle emits.
   createEffect(on(envelopeValid, (state) => {
     if (state.ok) emit({ kind: 'ready', cardId: local.cardId });
@@ -450,6 +520,12 @@ export function Form(props: FormProps): JSX.Element {
   const setField = (key: string, raw: unknown): void => {
     setValues(key, raw);
     if (errors[key]) setErrors(key, undefined as unknown as string);
+    // Fire the live change signal: current coerced values + validity (distinct from
+    // the terminal submit). Validation here is read-only — it doesn't surface errors.
+    const snapshot = unwrap(values) as Record<string, unknown>;
+    const out = buildResult(def(), snapshot);
+    const { valid } = validateForm(def(), snapshot);
+    local.onValuesChange?.({ values: out, valid });
   };
 
   const validateField = (key: string): void => {
@@ -462,12 +538,21 @@ export function Form(props: FormProps): JSX.Element {
     setErrors(key, single.fieldErrors[key]);
   };
 
-  const onSubmit = (e: Event): void => {
-    e.preventDefault();
-    if (res.isResolved()) return;
-    // Capture the <form> synchronously — `e.currentTarget` is nulled out once the
-    // event has finished dispatching (so it can't be read in a later microtask).
-    const formEl = e.currentTarget as HTMLElement | null;
+  // Resolve the root to query controls inside (the live <form> when called from the
+  // submit event, else the host element's shadow root for a programmatic call).
+  const queryRoot = (formEl?: HTMLElement | null): ParentNode =>
+    formEl?.closest('form') ?? formEl ?? local.hostElement?.shadowRoot ?? document;
+
+  // Focus the control for a field key (the `[data-control]` inside its `[data-field]`).
+  const focusControl = (key: string, root: ParentNode, options?: FocusOptions): void => {
+    root.querySelector<HTMLElement>(`[data-field="${cssEscape(key)}"] [data-control]`)?.focus(options);
+  };
+
+  // Run full validation; on failure surface the per-field errors + focus the first
+  // invalid control and return false; on success emit `submit` + resolve. Shared by
+  // the form's onSubmit handler and the controller's send().
+  const runSubmit = (formEl?: HTMLElement | null): boolean => {
+    if (res.isResolved()) return false;
     const snapshot = unwrap(values);
     const result = validateForm(def(), snapshot as Record<string, unknown>);
     setErrors(produce((s) => {
@@ -476,18 +561,23 @@ export function Form(props: FormProps): JSX.Element {
     }));
     if (!result.valid) {
       const firstBad = keys().find((k) => result.fieldErrors[k]);
-      if (firstBad && local.hostElement) {
-        // Focus the first invalid control (light-DOM query inside shadow root).
-        queueMicrotask(() => {
-          const root: ParentNode = formEl?.closest('form') ?? formEl ?? document;
-          root.querySelector<HTMLElement>(`[data-field="${cssEscape(firstBad)}"] [data-control]`)?.focus();
-        });
+      if (firstBad) {
+        const root = queryRoot(formEl);
+        queueMicrotask(() => focusControl(firstBad, root));
       }
-      return;
+      return false;
     }
     const out = buildResult(def(), snapshot as Record<string, unknown>);
     emit({ kind: 'submit', cardId: local.cardId, data: out });
     res.setLocal({ kind: 'submit', data: out });
+    return true;
+  };
+
+  const onSubmit = (e: Event): void => {
+    e.preventDefault();
+    // Capture the <form> synchronously — `e.currentTarget` is nulled out once the
+    // event has finished dispatching (so it can't be read in a later microtask).
+    runSubmit(e.currentTarget as HTMLElement | null);
   };
 
   // Dismiss: emit `dismiss` AND optimistically flip to a `dismissed` resolution so
@@ -499,6 +589,39 @@ export function Form(props: FormProps): JSX.Element {
   };
   const onReopen = (): void => emit({ kind: 'reopen', cardId: local.cardId });
 
+  const disabled = (): boolean => local.disabled === true;
+
+  // Imperative controller (Pattern C): hand the facade a handle over the form's
+  // latent capabilities. focus targets the first control (or the first INVALID one
+  // after a failed validation); validate runs the existing validateForm and surfaces
+  // the per-field errors WITHOUT submitting; send runs the same path as the Submit
+  // button; reset re-seeds from schema defaults; dismiss/reopen drive the stub.
+  onMount(() => {
+    local.controllerRef?.({
+      focus: (options) => {
+        const root = queryRoot();
+        const firstBad = keys().find((k) => errors[k]);
+        const target = firstBad ?? keys()[0];
+        if (target) focusControl(target, root, options);
+      },
+      send: () => { runSubmit(); },
+      validate: () => {
+        const snapshot = unwrap(values) as Record<string, unknown>;
+        const result = validateForm(def(), snapshot);
+        setErrors(produce((s) => {
+          for (const k of Object.keys(s)) delete s[k];
+          Object.assign(s, result.fieldErrors);
+        }));
+        return result.valid
+          ? { valid: true }
+          : { valid: false, errors: result.fieldErrors };
+      },
+      reset: () => seedDefaults(),
+      dismiss: () => onDismiss(),
+      reopen: () => onReopen(),
+    });
+  });
+
   const actions = createMemo(() => def()['x-kai-actions'] ?? []);
   const submitLabel = () => def()['x-kai-submitLabel'] ?? 'Submit';
   const dismissible = () => def()['x-kai-dismissible'] === true;
@@ -556,7 +679,7 @@ export function Form(props: FormProps): JSX.Element {
                       </Button>
                     )}
                   </For>
-                  <Button type="submit" form={formId()}>
+                  <Button type="submit" form={formId()} disabled={disabled()}>
                     {submitLabel()}
                   </Button>
                 </div>
@@ -583,7 +706,7 @@ export function Form(props: FormProps): JSX.Element {
                     inlineMax={inlineMax()}
                     value={() => values[key]}
                     error={() => errors[key]}
-                    disabled={false}
+                    disabled={disabled()}
                     onInput={(v) => setField(key, v)}
                     onBlur={() => validateField(key)}
                   />
@@ -678,7 +801,7 @@ function FieldRow(props: FieldRowProps): JSX.Element {
     ['fieldset', 'repeater', 'checkbox-group', 'multiselect', 'radio', 'taglist'].includes(widget());
 
   return (
-    <div class="flex flex-col gap-2 rounded-xl bg-muted/40 p-3.5" data-field={props.fieldKey}>
+    <div class="flex flex-col gap-2 rounded-xl bg-surface p-3.5" data-field={props.fieldKey}>
       <Show when={!isGrouped()}>
         <label for={id} class="text-sm font-medium text-foreground">
           {label()}

package/src/components/image.tsx

@@ -1,5 +1,6 @@
 import { type JSX, splitProps, createSignal, createEffect, onCleanup, Show } from 'solid-js';
 import { cn } from '../utils/cn';
+import { Skeleton } from '../ui/skeleton';
 
 export interface GeneratedImageLike {
   base64?: string;
@@ -44,13 +45,10 @@ function Image(props: ImageProps) {
     <Show
       when={src()}
       fallback={
-        <div
+        <Skeleton
           aria-label={local.alt}
           role="img"
-          class={cn(
-            'h-auto max-w-full animate-pulse overflow-hidden rounded-md bg-muted',
-            local.class
-          )}
+          class={cn('h-auto max-w-full overflow-hidden', local.class)}
         />
       }
     >

package/src/components/link-preview.tsx

@@ -10,6 +10,7 @@ import {
   Show,
 } from 'solid-js';
 import { cn } from '../utils/cn';
+import { Skeleton } from '../ui/skeleton';
 import { Link as LinkIcon } from 'lucide-solid';
 import type { CardEvent } from '../primitives/card-contract';
 import {
@@ -153,11 +154,11 @@ export function LinkPreview(props: LinkPreviewProps): JSX.Element {
       >
         <Show when={loading()}>
           {/* Skeleton while the bare-URL fetcher resolves. */}
-          <div class="aspect-[16/9] w-full animate-pulse bg-muted" />
+          <Skeleton class="aspect-[16/9] w-full rounded-none" />
           <div class="space-y-2 p-3">
-            <div class="h-3 w-1/3 animate-pulse rounded bg-muted" />
-            <div class="h-4 w-2/3 animate-pulse rounded bg-muted" />
-            <div class="h-3 w-full animate-pulse rounded bg-muted" />
+            <Skeleton class="h-3 w-1/3" />
+            <Skeleton class="h-4 w-2/3" />
+            <Skeleton class="h-3 w-full" />
           </div>
         </Show>
         <Show when={!loading()}>

package/src/components/markdown.tsx

@@ -11,6 +11,9 @@ export interface MarkdownProps {
   id?: string;
   class?: string;
   codeTheme?: string;
+  /** Optional `::part` name(s) to expose on the rendered root. Lets callers
+   *  (e.g. the message bubble) surface a styleable part through the shadow. */
+  part?: string;
 }
 
 interface ParsedBlock {
@@ -49,13 +52,13 @@ function MarkdownBlock(props: { content: string }) {
 }
 
 function Markdown(props: MarkdownProps) {
-  const [local] = splitProps(props, ['content', 'id', 'class', 'codeTheme']);
+  const [local] = splitProps(props, ['content', 'id', 'class', 'codeTheme', 'part']);
   const config = useChatConfig();
   const blockId = () => local.id ?? createUniqueId();
   const blocks = createMemo(() => parseMarkdownIntoBlocks(local.content));
 
   return (
-    <div class={cn('chat-markdown max-w-none break-words whitespace-normal [&>div:first-child>p:first-child]:mt-0 [&>div:last-child>p:last-child]:mb-0', textClass(config.proseSize()), local.class)}>
+    <div part={local.part} class={cn('chat-markdown max-w-none break-words whitespace-normal [&>div:first-child>p:first-child]:mt-0 [&>div:last-child>p:last-child]:mb-0', textClass(config.proseSize()), local.class)}>
       <For each={blocks()}>
         {(block) => (
           <Switch>