@kitn.ai/ui 0.25.2 → 0.27.0

package/src/components/audio-visualizer/index.tsx

@@ -7,6 +7,7 @@ import { useAudioAnalysis } from '../../primitives/use-audio-analysis';
 import { mirrorBandsCenterOut, mirrorBandsAroundRing } from '../../primitives/audio-bands';
 import { normalizeState, type VisualizerState } from '../../primitives/visualizer-sequences';
 import { BarVisualizer, type VariantProps } from './variant-bar';
+import { createFitScale } from './fit-scale';
 import { GridVisualizer } from './variant-grid';
 import { RadialVisualizer } from './variant-radial';
 import { defaultBarCount, defaultGridCount, defaultRadialBarCount, type VisualizerSize } from './sizes';
@@ -75,10 +76,24 @@ export interface AudioVisualizerProps {
   complexity?: number;
   /** Setting this makes the element an announced image instead of decorative. */
   label?: string;
+  /** Live audio to analyze. NOTE: amplitude renders only while
+   *  `state === 'speaking'` unless `listeningAmplitude` is set; every other
+   *  state plays its scripted animation and the analysis output is unused. */
   stream?: MediaStream;
+  /** Same speaking-only amplitude rule as `stream`: see `listeningAmplitude`. */
   audioElement?: HTMLMediaElement;
-  /** Pre-computed levels. Set this and no AudioContext is ever constructed. */
+  /** Pre-computed levels. Set this and no AudioContext is ever constructed.
+   *  Same speaking-only amplitude rule as `stream`: see `listeningAmplitude`. */
   bands?: number[];
+  /**
+   * Opt in to rendering live amplitude during `listening` as well, using the
+   * same presentation as `speaking`. Default off, which keeps LiveKit parity:
+   * amplitude (from `stream`, `audioElement` or `bands`) renders only while
+   * `state === 'speaking'`. Set this to show a real mic-level picture while
+   * the USER is the one talking. Forwarded to every variant; see
+   * `amplitudeRenderState` in variant-bar for the single mapping they share.
+   */
+  listeningAmplitude?: boolean;
   /**
    * Custom fragment shader for `variant="custom"`. See `ShaderSpec` for the
    * full contract -- most importantly, `fragment` MUST output premultiplied
@@ -371,11 +386,15 @@ export function AudioVisualizer(props: AudioVisualizerProps): JSX.Element {
   // `bands={bands()}`, at every call site below, exactly like `volume`,
   // `complexity`, etc. already are: an explicit prop gets its OWN getter,
   // entirely independent of this one.
+  // `listeningAmplitude` is safe inside this bundle (unlike `bands`): it is a
+  // boolean a caller sets once, not a signal driven at audio cadence, so
+  // reading it through the shared getters cannot drag in a hot subscription.
   const shared = (): Omit<VariantProps, 'bands'> => ({
     state: state(),
     size: size(),
     frozen: reduced(),
     color: props.color,
+    listeningAmplitude: props.listeningAmplitude,
   });
 
   // The three DOM variants (bar/grid/radial), including the bar fallback
@@ -390,9 +409,66 @@ export function AudioVisualizer(props: AudioVisualizerProps): JSX.Element {
       ? { role: 'img' as const, 'aria-label': props.label }
       : { 'aria-hidden': 'true' as const };
 
+  // Fit-to-container: measured by createFitScale (see fit-scale.ts for the
+  // full design rationale). At or above the natural width this contributes
+  // nothing but the `max-width` clamp, so the designed px metrics render
+  // exactly; below it, the inner wrapper scales the whole picture down and
+  // the outer adopts the scaled height so layout follows the visual.
+  const fit = createFitScale();
+
   return (
-    <div class={cn('inline-flex', props.class)} {...a11y()}>
-      <Switch
+    <div
+      class={cn('inline-flex', props.class)}
+      {...a11y()}
+      ref={fit.observeOuter}
+      style={{
+        // What lets a narrow container actually constrain this element: the
+        // content is fixed-px, so without the clamp the host box would just
+        // overflow (and clip at the viewport edge, the reported defect).
+        'max-width': '100%',
+        // While shrunk, the inner wrapper's LAYOUT box deliberately keeps its
+        // natural size (that is what keeps the measurement honest above), so
+        // it overhangs this box below/right of the scaled visual. `hidden`
+        // clips that overhang for BOTH painting and hit-testing -- without it
+        // the stale layout box covered a sibling button and ate its pointer
+        // events (W5 live finding, mechanism 2). Nothing visible is clipped:
+        // the scaled visual is exactly this box by construction.
+        // `vertical-align: top` rides along with `overflow: hidden`, which is
+        // what makes it necessary: hidden overflow moves an inline-flex box's
+        // baseline to its bottom border edge, so the surrounding line box
+        // grows by the font strut's descent below it and the host measures
+        // ~6px taller than the box (measured in headed Chromium: 107.2 vs
+        // 101.2). Top alignment opts out of baseline layout entirely. Scoped
+        // to the scaled state so default (unscaled) inline placement beside
+        // text keeps its original baseline behavior.
+        ...(fit.scaledHeight() !== undefined
+          ? { height: `${fit.scaledHeight()}px`, overflow: 'hidden', 'vertical-align': 'top' }
+          : {}),
+      }}
+    >
+      <div
+        ref={fit.observeInner}
+        style={{
+          // THE FEEDBACK-LOOP GUARD (W5 live finding, mechanism 1). The inner
+          // wrapper is a flex item of the outer, and a flex item's default
+          // `align-self: stretch` makes its LAYOUT height follow the outer's
+          // -- including the scaled height this component itself adopts below.
+          // The ResizeObserver measuring this element for its NATURAL size
+          // then reads back the adopted height, k multiplies in again, and
+          // the element spirals (measured in headed Chromium: 224px -> 45.7
+          // -> 0.85 -> 0.38). `flex-start` + `flex: none` pin this box to its
+          // intrinsic content size in BOTH axes, so the measurement can never
+          // see anything this component wrote. Unconditional: at scale 1 both
+          // are visually identical to the defaults for a single item that
+          // defines its container's size.
+          flex: '0 0 auto',
+          'align-self': 'flex-start',
+          ...(fit.scale() < 1
+            ? { transform: `scale(${fit.scale()})`, 'transform-origin': 'top left' }
+            : {}),
+        }}
+      >
+        <Switch
         fallback={<BarVisualizer {...domShared()} bands={bands()} barCount={props.barCount} />}
       >
         <Match when={variant() === 'grid'}>
@@ -446,6 +522,7 @@ export function AudioVisualizer(props: AudioVisualizerProps): JSX.Element {
           </Show>
         </Match>
       </Switch>
+      </div>
     </div>
   );
 }

package/src/components/audio-visualizer/variant-aurora.tsx

@@ -3,6 +3,7 @@ import { ShaderCanvas, hexToRgb, DEFAULT_SHADER_COLOR } from './shader-canvas';
 import { createTween } from '../../primitives/create-tween';
 import type { VisualizerState } from '../../primitives/visualizer-sequences';
 import { CONTAINER_HEIGHT } from './sizes';
+import { amplitudeRenderState } from './variant-bar';
 import type { ShaderVariantProps } from './index';
 import auroraShader from './aurora.glsl';
 
@@ -175,8 +176,13 @@ export default function AuroraVisualizer(props: ShaderVariantProps & { dark?: bo
   // nothing upstream resolved a theme at all (the standalone case).
   const resolvedDark = () => props.dark ?? systemDark();
 
+  // The state the rendering follows: `listeningAmplitude` folds `listening`
+  // into the speaking presentation (live-volume uScale). See
+  // amplitudeRenderState in variant-bar. `data-kai-state` keeps the real state.
+  const renderState = () => amplitudeRenderState(props.state, props.listeningAmplitude);
+
   createEffect(() => {
-    const t = auroraTargets(props.state);
+    const t = auroraTargets(renderState());
     // Fact sheet section 5: "0.5 s ease-out unless noted." Frozen (reduced
     // motion) settles on every target immediately instead.
     const landing = props.frozen ? { duration: 0 } : { duration: 0.5, ease: 'easeOut' as const };
@@ -198,7 +204,7 @@ export default function AuroraVisualizer(props: ShaderVariantProps & { dark?: bo
     // ease-out landing, and frozen collapses the spring like any tween.
     scale.to(
       t.scale,
-      props.state === 'listening' && !props.frozen
+      renderState() === 'listening' && !props.frozen
         ? { type: 'spring', duration: 1.0, bounce: 0.35 }
         : landing,
     );
@@ -231,7 +237,7 @@ export default function AuroraVisualizer(props: ShaderVariantProps & { dark?: bo
   // own value here would wire the self-retriggering effect loop
   // create-tween's doc warns about.
   createEffect(() => {
-    if (props.state !== 'speaking') return;
+    if (renderState() !== 'speaking') return;
     const volume = props.volume;
     if (!(volume > 0)) return;
     if (scale.animating()) return;
@@ -243,7 +249,7 @@ export default function AuroraVisualizer(props: ShaderVariantProps & { dark?: bo
   // absolute time in the shader, so a nonzero value would keep the figure
   // spinning through reduced motion.
   const rotationValue = () =>
-    props.frozen ? 0 : (auroraTargets(props.state).rotation * Math.PI) / 180;
+    props.frozen ? 0 : (auroraTargets(renderState()).rotation * Math.PI) / 180;
 
   // uTheme: 0 selects the shader's DARK colour pipeline, 1 selects LIGHT
   // (aurora.glsl.ts, fact sheet section 4 -- a real branch in the colour

package/src/components/audio-visualizer/variant-bar.tsx

@@ -9,8 +9,18 @@ import { CONTAINER_HEIGHT, GAP, BAR_WIDTH, defaultBarCount, type VisualizerSize
 export interface VariantProps {
   state: VisualizerState;
   size: VisualizerSize;
-  /** Multiband levels, 0..1. Only read while `state === 'speaking'`. */
+  /** Multiband levels, 0..1. Only read while `state === 'speaking'`, or also
+   *  while `'listening'` when `listeningAmplitude` is set. */
   bands: number[];
+  /**
+   * Opt in to rendering live amplitude during `listening` as well: the
+   * variant presents `listening` exactly as it presents `speaking` (live
+   * levels, lit geometry) while the host keeps reporting the real state via
+   * `data-kai-state`. Default off, which preserves LiveKit parity: amplitude
+   * renders only while `state === 'speaking'`, and every other state plays
+   * its scripted sequence. See `amplitudeRenderState`.
+   */
+  listeningAmplitude?: boolean;
   /** `prefers-reduced-motion`: pin the sequencer at its first frame. */
   frozen: boolean;
   /** Overrides the inherited `currentColor` the bars are painted with. */
@@ -42,20 +52,42 @@ export interface VariantProps {
  * `packages/shadcn/components/agents-ui/agent-audio-visualizer-bar.tsx`
  * (Apache License 2.0).
  */
+/**
+ * The state the RENDERING follows, as opposed to the state the consumer set.
+ *
+ * `listeningAmplitude` opts the `listening` state into the full speaking
+ * presentation: every variant routes its state-driven decisions (levels,
+ * highlight sequence, thresholds, volume overrides) through this ONE mapping
+ * rather than each patching its own `=== 'speaking'` gates, so the opt-in
+ * cannot half-apply within a variant. The host's `data-kai-state` deliberately
+ * keeps the REAL state, so CSS hooks and consumers observing the element are
+ * never lied to. With the flag absent or false this is the identity mapping,
+ * which is what keeps the default byte-identical to LiveKit parity.
+ */
+export function amplitudeRenderState(
+  state: VisualizerState,
+  listeningAmplitude: boolean | undefined,
+): VisualizerState {
+  return listeningAmplitude === true && state === 'listening' ? 'speaking' : state;
+}
+
 export function BarVisualizer(props: VariantProps & { barCount?: number }): JSX.Element {
   const count = () => props.barCount ?? defaultBarCount(props.size);
+  const renderState = () => amplitudeRenderState(props.state, props.listeningAmplitude);
 
   // Frozen (reduced motion) parks the sequence on frame 0 rather than stopping
   // the component: the shape still reads, it just does not move.
-  const tick = useSequencer(() => (props.frozen ? Infinity : barInterval(props.state, count())));
+  const tick = useSequencer(() => (props.frozen ? Infinity : barInterval(renderState(), count())));
 
-  const sequence = () => barSequence(props.state, count());
+  const sequence = () => barSequence(renderState(), count());
   const highlighted = () => sequence()[tick() % sequence().length] ?? [];
 
-  // Bands only mean anything while speaking. Everywhere else the sequence is
-  // the whole story, so a stale level never leaks into a scripted state.
+  // Bands only mean anything while speaking (or listening under the
+  // `listeningAmplitude` opt-in, which renderState folds into 'speaking').
+  // Everywhere else the sequence is the whole story, so a stale level never
+  // leaks into a scripted state.
   const levels = () =>
-    props.state === 'speaking'
+    renderState() === 'speaking'
       ? normalizeVolumeBands(props.bands, count())
       : new Array(count()).fill(0);
 

package/src/components/audio-visualizer/variant-custom.tsx

@@ -3,6 +3,7 @@ import { ShaderCanvas, hexToRgb, DEFAULT_SHADER_COLOR, type UniformSpec, type Un
 import { createTween } from '../../primitives/create-tween';
 import { shaderTargets } from '../../primitives/visualizer-sequences';
 import { CONTAINER_HEIGHT } from './sizes';
+import { amplitudeRenderState } from './variant-bar';
 import type { ShaderVariantProps } from './index';
 
 /**
@@ -203,6 +204,11 @@ export default function CustomVisualizer(props: ShaderVariantProps): JSX.Element
   const intensity = createTween(0.3);
   const speed = createTween(1);
 
+  // The state the rendering follows: `listeningAmplitude` folds `listening`
+  // into the speaking presentation (live-volume intensity). See
+  // amplitudeRenderState in variant-bar. `data-kai-state` keeps the real state.
+  const renderState = () => amplitudeRenderState(props.state, props.listeningAmplitude);
+
   // Intensity has exactly ONE writer -- this effect -- on purpose. The
   // volume override used to live in a second effect ("if speaking,
   // intensity.to(0.3 + 0.7v, instant)") alongside this one's 0.5s tween
@@ -217,8 +223,8 @@ export default function CustomVisualizer(props: ShaderVariantProps): JSX.Element
   // the Task 12 review accepted -- these two wrote the SAME tween. See the
   // wave variant's twin comment; same effect-race class as b5795ac.
   createEffect(() => {
-    const t = shaderTargets(props.state);
-    if (props.state === 'speaking') {
+    const t = shaderTargets(renderState());
+    if (renderState() === 'speaking') {
       // Live volume takes over intensity while speaking, with no easing so
       // the picture tracks the audio exactly -- and lands immediately on
       // re-entry regardless of effect ordering. `volume` is only tracked

package/src/components/audio-visualizer/variant-grid.tsx

@@ -4,7 +4,7 @@ import { normalizeVolumeBands } from '../../primitives/audio-bands';
 import { useSequencer } from '../../primitives/use-sequencer';
 import { gridSequence } from '../../primitives/visualizer-sequences';
 import { GRID_CELL, GRID_GAP, defaultGridCount } from './sizes';
-import type { VariantProps } from './variant-bar';
+import { amplitudeRenderState, type VariantProps } from './variant-bar';
 
 /*
  * NOTE: The speaking thresholds below DIVERGE from upstream's GridCell math,
@@ -64,20 +64,25 @@ export function GridVisualizer(
   const interval = () => props.interval ?? 100;
   const items = () => Array.from({ length: rows() * cols() }, (_, i) => i);
 
+  // The state the rendering follows: `listeningAmplitude` folds `listening`
+  // into the speaking presentation. See amplitudeRenderState in variant-bar.
+  const renderState = () => amplitudeRenderState(props.state, props.listeningAmplitude);
+
   const tick = useSequencer(() =>
     // Speaking is driven by audio, not the clock; freezing also parks it.
-    props.frozen || props.state === 'speaking' ? Infinity : interval(),
+    props.frozen || renderState() === 'speaking' ? Infinity : interval(),
   );
 
-  const sequence = () => gridSequence(props.state, rows(), cols(), props.spread);
+  const sequence = () => gridSequence(renderState(), rows(), cols(), props.spread);
   const active = () => sequence()[tick() % sequence().length] ?? { x: -1, y: -1 };
 
-  // Bands only mean anything while speaking. Everywhere else the sequence is
-  // the whole story, so a stale level never leaks into a scripted state (same
-  // guard as BarVisualizer, so the render-prop's `value` means one thing
-  // across every variant).
+  // Bands only mean anything while speaking (or listening under the
+  // `listeningAmplitude` opt-in, folded in by renderState). Everywhere else
+  // the sequence is the whole story, so a stale level never leaks into a
+  // scripted state (same guard as BarVisualizer, so the render-prop's `value`
+  // means one thing across every variant).
   const levels = () =>
-    props.state === 'speaking' ? normalizeVolumeBands(props.bands, cols()) : new Array(cols()).fill(0);
+    renderState() === 'speaking' ? normalizeVolumeBands(props.bands, cols()) : new Array(cols()).fill(0);
 
   /**
    * While speaking, a cell lights when its column's level clears a threshold
@@ -87,7 +92,7 @@ export function GridVisualizer(
    * both per the divergence note at the top of this file.
    */
   function isLit(index: number): boolean {
-    if (props.state === 'speaking') {
+    if (renderState() === 'speaking') {
       const y = Math.floor(index / cols());
       const mid = Math.floor(rows() / 2);
       const scaled = (Math.abs(mid - y) / (mid + 1)) * SPEECH_LEVEL_CEILING;
@@ -100,13 +105,13 @@ export function GridVisualizer(
     // upstream rests one stationary centre cell here. 'disconnected' (first-
     // class 2026-08-10) mirrors idle's dark grid for now, pending the LiveKit
     // disconnected-state measurement.
-    if (props.state === 'idle' || props.state === 'disconnected') return false;
+    if (renderState() === 'idle' || renderState() === 'disconnected') return false;
     return active().x === index % cols() && active().y === Math.floor(index / cols());
   }
 
   /** Snap on, fade off: highlighted cells transition 10x faster than they decay. */
   function transition(index: number): string {
-    if (props.state === 'speaking') return '150ms';
+    if (renderState() === 'speaking') return '150ms';
     return `${interval() / (isLit(index) ? 1000 : 100)}s`;
   }
 

package/src/components/audio-visualizer/variant-radial.tsx

@@ -4,7 +4,7 @@ import { normalizeVolumeBands } from '../../primitives/audio-bands';
 import { useSequencer } from '../../primitives/use-sequencer';
 import { radialSequence, radialInterval } from '../../primitives/visualizer-sequences';
 import { CONTAINER_HEIGHT, RADIAL_RADIUS, defaultRadialBarCount } from './sizes';
-import type { VariantProps } from './variant-bar';
+import { amplitudeRenderState, type VariantProps } from './variant-bar';
 
 /**
  * Bars arranged around a circle, growing outward with the audio.
@@ -40,10 +40,14 @@ export function RadialVisualizer(
   // many bars are on the ring.
   const dotSize = () => (radius() * Math.PI) / count();
 
+  // The state the rendering follows: `listeningAmplitude` folds `listening`
+  // into the speaking presentation. See amplitudeRenderState in variant-bar.
+  const renderState = () => amplitudeRenderState(props.state, props.listeningAmplitude);
+
   // Frozen (reduced motion) parks the sequence on frame 0 rather than stopping
   // the component: the shape still reads, it just does not move.
-  const tick = useSequencer(() => (props.frozen ? Infinity : radialInterval(props.state)));
-  const sequence = () => radialSequence(props.state, count());
+  const tick = useSequencer(() => (props.frozen ? Infinity : radialInterval(renderState())));
+  const sequence = () => radialSequence(renderState(), count());
 
   // `thinking` parks the sequencer itself (radialInterval returns Infinity)
   // and spins the whole ring in CSS instead, so every bar reads as lit rather
@@ -52,20 +56,21 @@ export function RadialVisualizer(
   // purpose: they interleave the ring so it still looks even while rotating,
   // not so a subset blinks).
   const highlighted = () =>
-    props.state === 'thinking'
+    renderState() === 'thinking'
       ? Array.from({ length: count() }, (_, i) => i)
       : (sequence()[tick() % sequence().length] ?? []);
 
-  // Bands only mean anything while speaking. Everywhere else the sequence is
-  // the whole story, so a stale level never leaks into a scripted state (same
-  // guard as the other two variants, so the render-prop's `value` means one
-  // thing across every variant).
+  // Bands only mean anything while speaking (or listening under the
+  // `listeningAmplitude` opt-in, folded in by renderState). Everywhere else
+  // the sequence is the whole story, so a stale level never leaks into a
+  // scripted state (same guard as the other two variants, so the
+  // render-prop's `value` means one thing across every variant).
   const levels = () =>
-    props.state === 'speaking'
+    renderState() === 'speaking'
       ? normalizeVolumeBands(props.bands, count())
       : new Array(count()).fill(0);
 
-  const spinning = () => props.state === 'thinking' && !props.frozen;
+  const spinning = () => renderState() === 'thinking' && !props.frozen;
 
   return (
     <div

package/src/components/audio-visualizer/variant-wave.tsx

@@ -3,6 +3,7 @@ import { ShaderCanvas, hexToRgb, DEFAULT_SHADER_COLOR } from './shader-canvas';
 import { createTween } from '../../primitives/create-tween';
 import { waveTargets } from '../../primitives/visualizer-sequences';
 import { CONTAINER_HEIGHT } from './sizes';
+import { amplitudeRenderState } from './variant-bar';
 import type { ShaderVariantProps } from './index';
 import waveShader from './wave.glsl';
 
@@ -26,7 +27,11 @@ export default function WaveVisualizer(props: ShaderVariantProps): JSX.Element {
   const frequency = createTween(0);
   const opacity = createTween(1);
 
-  const targets = () => waveTargets(props.state);
+  // The state the rendering follows: `listeningAmplitude` folds `listening`
+  // into the speaking presentation (live-volume amplitude/frequency). See
+  // amplitudeRenderState in variant-bar. `data-kai-state` keeps the real state.
+  const renderState = () => amplitudeRenderState(props.state, props.listeningAmplitude);
+  const targets = () => waveTargets(renderState());
 
   // Reduced motion: land on the target immediately and skip every pulse.
   const transition = () =>
@@ -61,7 +66,7 @@ export default function WaveVisualizer(props: ShaderVariantProps): JSX.Element {
   // effect, one writer, ordering can no longer matter. Same effect-race
   // class as b5795ac's shared() finding.
   createEffect(() => {
-    if (props.state === 'speaking') {
+    if (renderState() === 'speaking') {
       // Live volume drives amplitude and frequency instantly while
       // speaking, so the line never lags the audio -- and lands at the
       // override immediately on re-entry, matching upstream's same-commit

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-container.tsx

@@ -28,7 +28,10 @@ function ChatContainerRoot(props: ChatContainerRootProps) {
     <ChatContainerContext.Provider value={{ isAtBottom, scrollToBottom }}>
       <div
         ref={ref}
-        class={cn('flex flex-col overflow-y-auto', local.class)}
+        // `kai-focus-inset`: the log fills a clipping container, so the default
+        // focus outline (drawn outside the border box) was clipped away
+        // entirely — this region was tabbable with no visible indicator.
+        class={cn('flex flex-col overflow-y-auto kai-focus-inset', local.class)}
         role="log"
         // Keyboard users must be able to scroll the conversation even when no
         // message contains a focusable control (WCAG 2.1.1 — axe

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>