@kitn.ai/ui 0.25.2 → 0.26.0

package/src/components/attachments.tsx

@@ -3,14 +3,15 @@ import { cn } from '../utils/cn';
 import { Button } from '../ui/button';
 import { HoverCardRoot, HoverCardTrigger, HoverCardContent } from '../ui/hover-card';
 import {
+  FileCode,
   FileText,
+  FileX,
   Globe,
   Image as ImageIcon,
-  Music2,
   Paperclip,
-  Video,
   X,
 } from 'lucide-solid';
+import { DEFAULT_MEDIA_POLICY } from '../wire/media-types';
 import type { AttachmentData, AttachmentMediaCategory, AttachmentVariant } from './attachment-types';
 export type { AttachmentData, AttachmentMediaCategory, AttachmentVariant } from './attachment-types';
 
@@ -18,32 +19,86 @@ export type { AttachmentData, AttachmentMediaCategory, AttachmentVariant } from
 // Types
 // ============================================================================
 
+/** One icon per category, and the categories are the wire's own kinds — so the
+ *  set is exhaustive by construction and a kind added to `EncodableKind` is a
+ *  compile error HERE rather than an `undefined` icon at runtime.
+ *
+ *  PDF and text get different glyphs deliberately. They are the two formats the
+ *  wire handles best and they used to share the anonymous fallback icon with a
+ *  `.zip`, which is the inversion this whole change is about. */
 const mediaCategoryIcons: Record<AttachmentMediaCategory, typeof ImageIcon> = {
-  audio: Music2,
   document: FileText,
   image: ImageIcon,
   source: Globe,
+  text: FileCode,
   unknown: Paperclip,
-  video: Video,
+  unsendable: FileX,
 };
 
 // ============================================================================
 // Utility Functions
 // ============================================================================
 
+/**
+ * What to DRAW for this attachment, asked of the one module that knows.
+ *
+ * ★ NO MEDIA TYPES APPEAR BELOW, and that is the fix. This function used to be
+ * a prefix switch — `image/` → image, `video/` → video, `application/` or
+ * `text/` → document — a second list of media types in a repo whose media-type
+ * declaration says, at its own definition, "if you find yourself writing a
+ * second list of media types anywhere in this repo, delete it and read this".
+ * It had drifted in both directions: `image/svg+xml` came back `image` and drew
+ * a real thumbnail for a format the encoder refuses outright, while
+ * `application/json` came back `document` when the wire carries it as text.
+ *
+ * `DEFAULT_MEDIA_POLICY` and not a narrowed one, on purpose. A developer's
+ * `accept` filter says what a user may STAGE; it says nothing about what an
+ * already-staged attachment IS, and narrowing here would redraw a message
+ * retroactively when a host changed a prop. The default policy is the kit's
+ * full capability set, so `unsupported` against it means exactly "no wire
+ * format this kit ships can carry this" — which is the only claim about
+ * sendability the renderer can honestly make without knowing the provider.
+ */
 export const getMediaCategory = (data: AttachmentData): AttachmentMediaCategory => {
+  // A citation chip is not an upload and never reaches an encoder — see the
+  // `kit-side` classification in `wire/files.ts`. Asking the policy about it
+  // would be asking the wrong question.
   if (data.type === 'source-document') {
     return 'source';
   }
 
-  const mediaType = data.mediaType ?? '';
-
-  if (mediaType.startsWith('image/')) return 'image';
-  if (mediaType.startsWith('video/')) return 'video';
-  if (mediaType.startsWith('audio/')) return 'audio';
-  if (mediaType.startsWith('application/') || mediaType.startsWith('text/')) return 'document';
+  const decision = DEFAULT_MEDIA_POLICY.decide(data.mediaType);
+  switch (decision.status) {
+    // The wire's kind IS the rendering category. Not mapped, not translated.
+    case 'allowed':
+      return decision.kind;
+    case 'unsupported':
+      return 'unsendable';
+    // Nobody named the file, so its bytes decide it and they have not been read
+    // here. `filtered` cannot occur against the unnarrowed default policy, but
+    // it means "the kit could have sent this" — also not unsendable. Both are
+    // honestly `unknown`, and no `default:` branch exists so a new
+    // `MediaDecision` variant is a compile error rather than a silent guess.
+    case 'undetermined':
+    case 'filtered':
+      return 'unknown';
+  }
+};
 
-  return 'unknown';
+/**
+ * The fact, written out, for the one category where the kit knows something the
+ * user needs to know.
+ *
+ * A FACT ABOUT THE FORMATS, NOT A PREDICTION ABOUT THIS REQUEST. At render time
+ * the kit does not know which provider the thread is bound for, so "this will
+ * fail" is not its to say. What it does know is that no wire format it ships
+ * has any representation for the type at all, which is true of every provider
+ * and is what this sentence claims.
+ */
+export const getUnsendableNote = (data: AttachmentData): string | undefined => {
+  if (getMediaCategory(data) !== 'unsendable') return undefined;
+  const type = data.mediaType?.trim() || 'This file type';
+  return `${type} is not one of the attachment formats a model request can carry.`;
 };
 
 export const getAttachmentLabel = (data: AttachmentData): string => {
@@ -133,6 +188,7 @@ function Attachment(props: AttachmentProps) {
   // once and the item never re-lays-out when the container variant changes.
   const ctx = useAttachmentsContext();
   const mediaCategory = () => getMediaCategory(local.data);
+  const unsendable = () => getUnsendableNote(local.data);
 
   return (
     <AttachmentContext.Provider
@@ -159,8 +215,35 @@ function Attachment(props: AttachmentProps) {
           ],
           local.class,
         )}
+        // ★ A STABLE HANDLE ON "THIS IS AN ATTACHMENT", published the way this
+        // kit publishes them (`part="row"`, `part="bubble content"`,
+        // `part="citations"`). Consumers get a `::part(attachment)` styling seam
+        // — and, just as importantly, anything asserting on the rendering gets
+        // something to key on that is not a class name or a position.
+        //
+        // That is not a hypothetical convenience. The conformance harness pinned
+        // this component by `span.truncate` and broke the day the thread moved
+        // from the inline chip to the grid tile; the obvious repair — "the
+        // innermost div holding both the media icon and the filename" — was
+        // measured to be WORSE, because when the filename is missing `.last()`
+        // slides silently up to the assistant's message row, which contains the
+        // tool panel echoing the same filename in its JSON. The assertion then
+        // passes while the user sees an anonymous grey box. A position that
+        // still resolves, to the wrong node, is the failure that stays green.
+        part="attachment"
+        // The mark lives on the ITEM rather than on `<AttachmentPreview>`,
+        // because the sub-parts are optional in composition — a consumer who
+        // renders only an `<AttachmentInfo>` still has to be told. `title` is
+        // the mouse affordance; the `sr-only` line inside is what actually
+        // carries the fact to assistive tech and to a test. `rest` is spread
+        // after both, so a consumer's own `title` still wins.
+        data-unsendable={unsendable() === undefined ? undefined : ''}
+        title={unsendable()}
         {...rest}
       >
+        <Show when={unsendable()}>
+          {(note) => <span class="sr-only">{note()}</span>}
+        </Show>
         {local.children}
       </div>
     </AttachmentContext.Provider>
@@ -182,10 +265,24 @@ function AttachmentPreview(props: AttachmentPreviewProps) {
   const iconSize = () => ctx.variant === 'inline' ? 'size-3' : 'size-4';
 
   const renderIcon = (Icon: typeof ImageIcon) => (
-    <Icon class={cn(iconSize(), 'text-muted-foreground')} />
+    <Icon
+      class={cn(
+        iconSize(),
+        // The one visible half of the mark. `warning` is an existing theme
+        // token, not a new colour for this state.
+        ctx.mediaCategory === 'unsendable' ? 'text-warning' : 'text-muted-foreground',
+      )}
+    />
   );
 
   const renderContent = () => {
+    // ★ ONLY `image` GETS A REAL PREVIEW, and `image` now means "a raster format
+    // some wire can actually carry" because the category comes from the media
+    // policy. There used to be a `video` branch here that mounted a real
+    // <video> for a file no encoder in this kit can represent: a preview that
+    // looks like it worked, in front of a send that throws. An SVG reached the
+    // <img> branch for the same reason. Both are `unsendable` now and fall
+    // through to the marked icon below.
     if (ctx.mediaCategory === 'image' && ctx.data.type === 'file' && ctx.data.url) {
       return ctx.variant === 'grid' ? (
         <img
@@ -206,10 +303,6 @@ function AttachmentPreview(props: AttachmentPreviewProps) {
       );
     }
 
-    if (ctx.mediaCategory === 'video' && ctx.data.type === 'file' && ctx.data.url) {
-      return <video class="size-full object-cover" muted src={ctx.data.url} />;
-    }
-
     const Icon = mediaCategoryIcons[ctx.mediaCategory];
     return local.fallbackIcon ?? renderIcon(Icon);
   };
@@ -244,14 +337,68 @@ function AttachmentInfo(props: AttachmentInfoProps) {
   const label = () => getAttachmentLabel(ctx.data);
 
   return (
-    <Show when={ctx.variant !== 'grid'}>
-      <div class={cn('min-w-0 flex-1', local.class)} {...rest}>
+    <Show
+      when={ctx.variant !== 'grid'}
+      fallback={
+        /*
+         * ★ A GRID TILE IS SELF-DESCRIBING ONLY WHEN IT IS AN IMAGE.
+         *
+         * A tile used to render no label at all, on the theory that it is "a
+         * self-contained visual". True of a photo; false of a PDF, a zip or a
+         * text file, which draw a 16px glyph on a grey square and are otherwise
+         * anonymous. The name was reachable by hover (pointer only) and by an
+         * `sr-only` line (assistive tech only), which between them serve
+         * everyone EXCEPT a sighted keyboard user and a sighted touch user —
+         * measured in a real browser as `visibleText: ""` on every non-image
+         * tile, with no focusable element inside any of them.
+         *
+         * So a non-image tile carries a visible, truncated caption and needs no
+         * interaction of any kind. An image tile still carries none: the image
+         * is the content, and stamping a filename over it is noise. That is
+         * also why the `sr-only` label was REMOVED from `<AttachmentPreview>`
+         * rather than kept alongside this — an image has `alt`, everything else
+         * now has this, and keeping both would announce the name twice.
+         */
+        <Show when={ctx.mediaCategory !== 'image'}>
+          {/* A `div`, not a `span` — `AttachmentInfoProps` extends
+              `JSX.HTMLAttributes<HTMLDivElement>`, so `rest` carries a
+              div-typed `ref` and the other branch below is a div too. */}
+          <div
+            class={cn(
+              'absolute inset-x-0 bottom-0 truncate px-1.5 py-1 text-caption',
+              'bg-background/85 backdrop-blur-sm',
+              ctx.mediaCategory === 'unsendable' ? 'text-warning' : 'text-foreground',
+              local.class,
+            )}
+            part="attachment-name"
+            {...rest}
+          >
+            {label()}
+          </div>
+        </Show>
+      }
+    >
+      {/* Same `part` in both branches: an assertion (or a consumer's CSS) that
+          asks for the attachment's name must not have to know which variant is
+          rendering. That is the whole point of publishing it. */}
+      <div class={cn('min-w-0 flex-1', local.class)} part="attachment-name" {...rest}>
         <span class="block truncate">{label()}</span>
         {/* The media-type subtitle is a two-line affordance — only the `list`
-            variant has room for it; `inline` chips are a fixed single-line height. */}
-        <Show when={local.showMediaType && ctx.variant === 'list' && ctx.data.mediaType}>
-          <span class="text-muted-foreground text-caption block truncate">
-            {ctx.data.mediaType}
+            variant has room for it; `inline` chips are a fixed single-line height.
+            The unsendable line rides in the same slot and WINS it, because "no
+            wire can carry this" is the more useful half of the same sentence. */}
+        <Show
+          when={ctx.mediaCategory === 'unsendable' && ctx.variant === 'list'}
+          fallback={
+            <Show when={local.showMediaType && ctx.variant === 'list' && ctx.data.mediaType}>
+              <span class="text-muted-foreground text-caption block truncate">
+                {ctx.data.mediaType}
+              </span>
+            </Show>
+          }
+        >
+          <span class="text-warning text-caption block truncate">
+            {ctx.data.mediaType ? `${ctx.data.mediaType} · ` : ''}unsupported attachment format
           </span>
         </Show>
       </div>

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

@@ -0,0 +1,112 @@
+import { createSignal, onCleanup, type Accessor } from 'solid-js';
+
+/**
+ * Fit-to-container scaling (owner finding, rung 2): 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
+ * to the designed px metrics whenever the container is at least natural size.
+ *
+ * Why a transform-scale wrapper rather than relative units or reflow:
+ * - The px tiers ARE the design (LiveKit parity); switching the geometry to
+ *   relative units would change rendering at every container size, not just
+ *   the overflowing ones.
+ * - Reflowing (fewer bars, smaller gaps) changes what the animation MEANS;
+ *   proportional scale keeps the exact picture, just smaller.
+ * - A transform also covers the shader variants for free: their canvases size
+ *   their backing store from layout size (`clientWidth`), which a transform
+ *   does not change, so the bitmap stays at full natural resolution and only
+ *   the composited output shrinks. No variant needs an exception.
+ *
+ * Both sizes are MEASURED (one ResizeObserver watching both wrappers), never
+ * restated from `sizes.ts`: the natural footprint depends on variant, size
+ * tier, barCount/count/radius and the consumer's own part styling, and a
+ * hand-derived width table would rot the day any of those moved.
+ *
+ * Where ResizeObserver does not exist (SSR, jsdom) this is inert: scale stays
+ * 1 and nothing is written, which is exactly the pre-fix rendering.
+ */
+export function computeFitScale(
+  available: number | undefined,
+  natural: number | undefined,
+): number {
+  if (
+    available === undefined || natural === undefined ||
+    !Number.isFinite(available) || !Number.isFinite(natural) ||
+    available <= 0 || natural <= 0
+  ) {
+    return 1;
+  }
+  return Math.min(1, available / natural);
+}
+
+export interface FitScale {
+  /** Ref for the outer wrapper (the host box, clamped by `max-width: 100%`). */
+  observeOuter: (el: HTMLElement) => void;
+  /** Ref for the inner wrapper (the natural-size content that gets scaled). */
+  observeInner: (el: HTMLElement) => void;
+  /** 1 when the content fits; the proportional shrink factor when it does not. */
+  scale: Accessor<number>;
+  /** The scaled content height in px while shrunk, else undefined: the outer
+   *  wrapper adopts it so the page never reserves the unscaled height. */
+  scaledHeight: Accessor<number | undefined>;
+}
+
+/**
+ * One ResizeObserver over both wrappers. ResizeObserver reports layout
+ * (border-box/content-box) sizes, which CSS transforms do not affect, so the
+ * inner wrapper keeps reporting its NATURAL size even while scaled, and the
+ * outer wrapper (whose `max-width: 100%` is what lets a narrow parent
+ * actually constrain it) reports the width the container is offering. The
+ * ratio of the two is the scale, with `computeFitScale` guarding the
+ * unmeasured/degenerate cases to 1 so a bad reading can never blank the
+ * element.
+ */
+export function createFitScale(): FitScale {
+  const [availableWidth, setAvailableWidth] = createSignal<number>();
+  const [naturalWidth, setNaturalWidth] = createSignal<number>();
+  const [naturalHeight, setNaturalHeight] = createSignal<number>();
+
+  let outerEl: HTMLElement | undefined;
+  let innerEl: HTMLElement | undefined;
+  let observer: ResizeObserver | undefined;
+
+  const ensureObserver = (): ResizeObserver | undefined => {
+    if (observer) return observer;
+    if (typeof ResizeObserver === 'undefined') return undefined;
+    observer = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        // contentRect, not borderBoxSize: identical for these padding-less
+        // wrappers and present everywhere this runs.
+        if (entry.target === outerEl) setAvailableWidth(entry.contentRect.width);
+        if (entry.target === innerEl) {
+          setNaturalWidth(entry.contentRect.width);
+          setNaturalHeight(entry.contentRect.height);
+        }
+      }
+    });
+    return observer;
+  };
+
+  onCleanup(() => observer?.disconnect());
+
+  const scale = () => computeFitScale(availableWidth(), naturalWidth());
+  const scaledHeight = () => {
+    const k = scale();
+    const h = naturalHeight();
+    return k < 1 && h !== undefined && h > 0 ? h * k : undefined;
+  };
+
+  return {
+    observeOuter: (el) => {
+      outerEl = el;
+      ensureObserver()?.observe(el);
+    },
+    observeInner: (el) => {
+      innerEl = el;
+      ensureObserver()?.observe(el);
+    },
+    scale,
+    scaledHeight,
+  };
+}

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