@kitn.ai/ui 0.19.0 → 0.20.0

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

@@ -0,0 +1,338 @@
+import { createEffect, createMemo, Show, type JSX } from 'solid-js';
+import { ShaderCanvas, hexToRgb, DEFAULT_SHADER_COLOR, type UniformSpec, type UniformType } from './shader-canvas';
+import { createTween } from '../../primitives/create-tween';
+import { shaderTargets } from '../../primitives/visualizer-sequences';
+import { CONTAINER_HEIGHT } from './sizes';
+import type { ShaderVariantProps } from './index';
+
+/**
+ * Every `UniformType` shader-canvas.tsx knows how to declare and push to the
+ * GPU, duplicated here because that module does not export its `GLSL_TYPE`
+ * map. `ShaderSpec.uniforms` narrows `type` to `UniformType` at the TS level
+ * (see `index.tsx`), but a consumer can still reach this component through
+ * the `<kai-audio-visualizer>` custom element with a plain JS object cast
+ * past that check (`el.shader = {...}`), or any attribute-driven wrapper
+ * that never touches TypeScript at all -- so an unrecognized `type` string
+ * is checked again here, at runtime, against genuinely untrusted input.
+ *
+ * A `Record<UniformType, true>` literal, not a `Set`: if `UniformType` ever
+ * grows a member, this object literal fails to typecheck until a matching
+ * key is added here too, so the two cannot silently drift apart. Same
+ * compiler-enforced-completeness technique as `effectiveArraySize` in
+ * shader-canvas.tsx. Membership is checked with a strict `=== true` value
+ * comparison (`uniformProblem` below), not `in` or `.hasOwnProperty`: a
+ * bracket lookup with an untrusted key can resolve to an INHERITED
+ * `Object.prototype` member (e.g. `spec.type === 'toString'`), and `in`
+ * would treat that as present. Comparing the looked-up VALUE to `true`
+ * rejects that case too, since `Object.prototype.toString` is a function,
+ * never `true`.
+ */
+const KNOWN_UNIFORM_TYPES: Record<UniformType, true> = {
+  '1f': true, '1i': true, '1fv': true, '2f': true, '3f': true, '3fv': true,
+  '4f': true, '4fv': true, Matrix2fv: true, Matrix3fv: true, Matrix4fv: true,
+};
+
+/** `1f` and `1i` take a plain number. Every other type takes an array. */
+const SCALAR_UNIFORM_TYPES = new Set<UniformType>(['1f', '1i']);
+
+/**
+ * Exact element count for the uniform types whose arity is a fixed constant
+ * of the type name -- `2f` a vec2 (2), `3f` a vec3 (3), `4f` a vec4 (4), and
+ * `Matrix2fv`/`Matrix3fv`/`Matrix4fv` a 2x2/3x3/4x4 matrix (4/9/16) -- and
+ * needs no import from shader-canvas.tsx's private unit-size table to know.
+ *
+ * Deliberately excludes `1fv`/`3fv`/`4fv`: shader-canvas.tsx's own
+ * `inferArraySize` treats THOSE three as a legitimate multi-instance array
+ * whenever `value.length` is a multiple of their unit greater than one, with
+ * no explicit `arraySize` required to opt in -- `uBands` below is exactly
+ * that pattern (`1fv`, an unbounded length). A fixed-length check on them
+ * would reject a consumer's genuinely valid array uniform, not just a
+ * mistake. A matrix ARRAY is technically eligible for the same inference in
+ * shader-canvas.tsx, but has no legitimate use in this component's
+ * single-pass ShaderToy-style shader model, and `ShaderSpec.uniforms`
+ * exposes no `arraySize` a consumer could use to request one deliberately --
+ * so treating a matrix uniform as always-one-instance here is a reasonable,
+ * simpler default. A consumer who genuinely needs an array of matrices is
+ * not served by this check; see the task report for that tradeoff.
+ */
+const FIXED_ARITY: Partial<Record<UniformType, number>> = {
+  '2f': 2, '3f': 3, '4f': 4,
+  Matrix2fv: 4, Matrix3fv: 9, Matrix4fv: 16,
+};
+
+/**
+ * Checks one consumer-declared uniform's `value` against its `type`,
+ * returning a problem description, or `undefined` if it is safe to hand to
+ * WebGL.
+ *
+ * The scalar-vs-array check is what matters most for safety: a `1f` handed
+ * an array, or a `3fv` handed a bare number, is what makes WebGL's
+ * `uniform*` setters throw a `TypeError` -- the WebIDL binding fails to
+ * convert the argument at all. The fixed-arity check below it is a
+ * correctness improvement on top of that, not a safety one: an array of the
+ * wrong length for a type WebGL treats as fixed-size is a GL-level
+ * `INVALID_OPERATION` recorded on the context, not a JS exception -- it
+ * degrades the picture rather than crashing the render loop -- but it is
+ * cheap to catch here with a clear message instead of a silent blank patch
+ * on screen.
+ */
+function uniformProblem(name: string, spec: UniformSpec): string | undefined {
+  if (spec == null || typeof spec !== 'object') {
+    return `uniform "${name}" is not a valid declaration (expected an object with "type" and "value").`;
+  }
+  if (KNOWN_UNIFORM_TYPES[spec.type] !== true) {
+    return `uniform "${name}" has an unrecognized type "${String(spec.type)}".`;
+  }
+  if (SCALAR_UNIFORM_TYPES.has(spec.type)) {
+    if (typeof spec.value !== 'number' || !Number.isFinite(spec.value)) {
+      return `uniform "${name}" is declared "${spec.type}" (a number) but its value is not a finite number.`;
+    }
+    return undefined;
+  }
+  if (
+    !Array.isArray(spec.value) ||
+    spec.value.some((v) => typeof v !== 'number' || !Number.isFinite(v))
+  ) {
+    return `uniform "${name}" is declared "${spec.type}" (an array) but its value is not an array of finite numbers.`;
+  }
+  const arity = FIXED_ARITY[spec.type];
+  if (arity !== undefined && spec.value.length !== arity) {
+    return `uniform "${name}" is declared "${spec.type}", which takes exactly ${arity} numbers, but its value has ${spec.value.length}.`;
+  }
+  return undefined;
+}
+
+/**
+ * Uniforms every custom shader receives without asking: the standard set
+ * (`uColor`, `uIntensity`, `uSpeed`, `uComplexity`) plus the audio pair that
+ * ONLY this variant gets. Upstream's shader path only ever hands a shader a
+ * scalar volume; `uBands` -- a per-band `float` array -- has no equivalent
+ * there, so a spectrum-reactive custom shader is possible here and not
+ * there. `iTime`/`iResolution`/`iMouse`/`iFrame`/`iDate` are declared by
+ * `ShaderCanvas` itself for every shader, custom or not, so they are not
+ * repeated here.
+ *
+ * `extra` is a consumer's `ShaderSpec.uniforms` -- untrusted input. Every
+ * entry is checked with `uniformProblem` before being merged in; a bad
+ * `type`/`value` pairing throws rather than being handed to `ShaderCanvas`,
+ * where the mismatch would otherwise throw a `TypeError` inside WebGL's
+ * `uniform*` setters, called from `ShaderCanvas`'s OWN
+ * `requestAnimationFrame` loop, where nothing catches it and the canvas
+ * silently stops animating. `CustomVisualizer` below is what turns that
+ * throw into the same `onUnavailable` seam every other shader failure uses
+ * -- see its own doc for how.
+ *
+ * Pure and synchronous: reads no signals, schedules nothing. Task 15 reuses
+ * it as-is.
+ */
+export function customUniforms(
+  values: {
+    color: string;
+    intensity: number;
+    speed: number;
+    complexity: number;
+    volume: number;
+    bands: number[];
+  },
+  extra?: Record<string, UniformSpec>,
+): Record<string, UniformSpec> {
+  // GLSL has no zero-length arrays, so an empty band list still declares
+  // one -- and the declared length always comes from THIS array's own
+  // length (`arraySize: bands.length`), never a separately tracked count,
+  // so the declaration and the value pushed to the GPU can never disagree.
+  const bands = values.bands.length ? values.bands : [0];
+
+  const standard: Record<string, UniformSpec> = {
+    uColor: { type: '3fv', value: hexToRgb(values.color) },
+    uIntensity: { type: '1f', value: values.intensity },
+    uSpeed: { type: '1f', value: values.speed },
+    uComplexity: { type: '1f', value: values.complexity },
+    uVolume: { type: '1f', value: values.volume },
+    uBands: { type: '1fv', value: bands, arraySize: bands.length },
+  };
+
+  if (!extra) return standard;
+
+  for (const [name, spec] of Object.entries(extra)) {
+    const problem = uniformProblem(name, spec);
+    if (problem) throw new Error(problem);
+  }
+
+  return { ...standard, ...extra };
+}
+
+/**
+ * Renders a consumer-supplied fragment shader.
+ *
+ * The shader must define `mainImage(out vec4 fragColor, in vec2 fragCoord)`
+ * and gets the five ShaderToy built-ins (`iTime`, `iResolution`, `iMouse`,
+ * `iFrame`, `iDate`) plus every uniform `customUniforms` above declares.
+ * `ShaderCanvas` DECLARES all of them for you -- declaring the SAME name
+ * again inside the shader body is a GLSL redefinition and fails to compile.
+ *
+ * `fragColor` MUST be premultiplied: `vec4(rgb * alpha, alpha)`, never
+ * `vec4(rgb, alpha)`. The canvas composites using the browser's default
+ * `premultipliedAlpha: true`; a translucent edge written the natural
+ * (straight-alpha) way gets a dark fringe where it meets a light page. For
+ * example, a shader painting a soft circle that fades to transparent at its
+ * edge:
+ *
+ * ```glsl
+ * void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+ *   vec2 uv = fragCoord / iResolution.xy;
+ *   float alpha = smoothstep(1.0, 0.0, length(uv - 0.5) * 2.0) * uIntensity;
+ *   fragColor = vec4(uColor * alpha, alpha); // premultiplied -- NOT vec4(uColor, alpha)
+ * }
+ * ```
+ *
+ * `uVolume` (scalar) and `uBands` (a `float[N]` array, `N` tracking the
+ * visualizer's actual band count) are this task's differentiating feature:
+ * upstream's shader path only ever hands a shader a scalar, so a
+ * spectrum-reactive custom shader is only possible here.
+ *
+ * A bad `props.shader.uniforms` entry (an unrecognized `type`, or a `value`
+ * that does not match it) is logged loudly via `console.error` -- it is a
+ * bug in the consumer's shader spec they need to see -- and routed through
+ * `props.onUnavailable`, same as a shader compile or link failure. A
+ * missing WebGL context logs quietly via `console.warn`: that is an
+ * expected environment limitation, not a bug. `props.shader` being absent
+ * entirely is neither: it renders an empty placeholder and does not call
+ * `onUnavailable` at all, since nothing was ever asked to render.
+ */
+export default function CustomVisualizer(props: ShaderVariantProps): JSX.Element {
+  const intensity = createTween(0.3);
+  const speed = createTween(1);
+
+  // 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
+  // toward the state base; both re-ran on a state flip, and Solid re-runs
+  // sibling effects in the order they sit in the signal's observer list,
+  // which reorders as effects re-subscribe over their lifetimes. Under the
+  // adverse ordering the base tween landed AFTER the override and parked a
+  // speaking shader at the 0.3 base until the next volume change -- which
+  // never comes under static `bands`/`volume` prop drive. The same
+  // two-writer race variant-wave.tsx carried (measured there on the parity
+  // harness; latent here). NOT the benign disjoint-writer two-effect shape
+  // 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') {
+      // 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
+      // in this branch, so volume ticks skip the base-target path below.
+      intensity.to(0.3 + 0.7 * props.volume, { duration: 0 });
+    } else {
+      const transition = props.frozen ? { duration: 0 } : { duration: 0.5, ease: 'easeOut' as const };
+      intensity.to(Array.isArray(t.intensity) && props.frozen ? t.intensity[0] : t.intensity, transition);
+    }
+    // `iTime` is never frozen by ShaderCanvas itself -- it is the raw clock,
+    // always advancing. A custom shader written the conventional way
+    // (`iTime * uSpeed`) is the ONLY thing that can honour reduced motion,
+    // and only if `uSpeed` is actually pinned at 0 here. Matches
+    // variant-aurora.tsx's `speed.to(props.frozen ? 0 : t.speed, ...)`.
+    speed.to(props.frozen ? 0 : t.speed, { duration: 0 });
+  });
+
+  // Recomputed whenever a dependency changes -- same as every other shader
+  // variant's uniforms object; see ShaderCanvas's reactivity note on why
+  // that is fine (only STRUCTURE triggers a recompile, not a value change).
+  // The try/catch is what keeps a bad `props.shader.uniforms` entry from
+  // ever reaching ShaderCanvas: without it, `customUniforms`'s throw (see
+  // its own doc) would happen wherever THIS expression gets evaluated,
+  // which includes ShaderCanvas's own requestAnimationFrame loop -- a raw
+  // browser callback nothing else catches.
+  //
+  // Deliberately kept a PURE derivation (no console/onUnavailable calls
+  // here): those are side effects, and belong in the createEffect below,
+  // not in a memo whose body should be safe to (re)run purely for its
+  // return value.
+  const result = createMemo<{ uniforms?: Record<string, UniformSpec>; error?: string }>(() => {
+    try {
+      const uniforms = customUniforms(
+        {
+          color: props.color ?? DEFAULT_SHADER_COLOR,
+          intensity: intensity.value(),
+          speed: speed.value(),
+          complexity: props.complexity ?? 0.5,
+          volume: props.volume,
+          bands: props.bands,
+        },
+        props.shader?.uniforms,
+      );
+      return { uniforms };
+    } catch (err) {
+      return { error: err instanceof Error ? err.message : String(err) };
+    }
+  });
+
+  // Guards against reporting the SAME failure more than once: ShaderCanvas
+  // reads `uniforms` fresh every animation frame (see its own reactivity
+  // note), so `result` above can keep re-evaluating to the same error more
+  // than once before the `Show` below actually unmounts it. Reset on a
+  // successful `result` (not left permanently `true` once tripped): the
+  // dispatcher's own `unavailable` flag is permanent for a mount, but this
+  // component is a public default export usable standalone (e.g. a shader
+  // editor or a Storybook control surface) where `props.shader` can change
+  // after mount -- a consumer who fixes one bad uniform and then introduces
+  // a DIFFERENT one in the same mount must still see and hear about the
+  // second mistake, not silence because the first one already fired.
+  let reported = false;
+  createEffect(() => {
+    const { error } = result();
+    if (!error) {
+      reported = false;
+      return;
+    }
+    if (reported) return;
+    reported = true;
+    console.error(`<kai-audio-visualizer variant="custom">: ${error}`);
+    props.onUnavailable();
+  });
+
+  const containerStyle = (): JSX.CSSProperties => ({
+    height: `${CONTAINER_HEIGHT[props.size]}px`,
+    'aspect-ratio': '1',
+  });
+
+  return (
+    <Show
+      when={props.shader?.fragment}
+      fallback={<div data-kai-state={props.state} class={props.class} style={containerStyle()} />}
+    >
+      {(fragment) => (
+        <Show
+          when={result().uniforms}
+          fallback={<div data-kai-state={props.state} class={props.class} style={containerStyle()} />}
+        >
+          {(u) => (
+            <div data-kai-state={props.state} class={props.class} style={containerStyle()}>
+              <ShaderCanvas
+                fragment={fragment()}
+                precision={props.size === 'icon' || props.size === 'sm' ? 'mediump' : 'highp'}
+                uniforms={u()}
+                animateWhenNotVisible={props.animateWhenNotVisible}
+                onError={(message) => {
+                  // "not available" is ShaderCanvas's literal wording for a
+                  // missing WebGL context (see its own doc) -- an expected
+                  // environment limitation, not a bug, so it logs quietly.
+                  // Anything else is a compile or link failure IN THE
+                  // CONSUMER'S SHADER, which they need to see, so it is loud.
+                  const missingContext = /not available/i.test(message);
+                  if (missingContext) {
+                    console.warn('<kai-audio-visualizer variant="custom">: shader unavailable', message);
+                  } else {
+                    console.error('<kai-audio-visualizer variant="custom">: shader error', message);
+                  }
+                  props.onUnavailable();
+                }}
+              />
+            </div>
+          )}
+        </Show>
+      )}
+    </Show>
+  );
+}

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

@@ -0,0 +1,170 @@
+import { Index, type JSX } from 'solid-js';
+import { cn } from '../../utils/cn';
+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';
+
+/*
+ * NOTE: The speaking thresholds below DIVERGE from upstream's GridCell math,
+ * deliberately (Rob, 2026-08-09). Upstream computes
+ * `threshold = |mid - y| * 1/(mid + 1)`, spreading the row thresholds evenly
+ * across 0..1 (5 rows: 0, 1/3, 2/3). Two blind spots our element actually
+ * exposes:
+ *
+ * (1) Real speech through the aligned analysis pipeline peaks at 0.51-0.54
+ *     (0.68 on the recorded fixture), so distance-2 rows (top/bottom of a
+ *     5-row grid) NEVER light — measured zero times across 139 speech
+ *     samples, on upstream's own grid as well as ours.
+ * (2) The middle row's threshold is 0, so it stays lit in the speaking state
+ *     even on a silent mic.
+ *
+ * Rob asked for both fixed: outer rows reachable by real speech (the grid
+ * fills centre-outward as a cross) and an empty grid when the mic is silent.
+ * So the ramp is scaled to the realistic speech ceiling, and the would-be-0
+ * centre threshold becomes a small silence floor. 5 rows now: 0.02, ~0.217,
+ * ~0.433 (3 rows: 0.02, 0.325; 7 rows: 0.02, ~0.163, 0.325, ~0.488).
+ *
+ * (3) A third divergence, also Rob's request (2026-08-09): at IDLE the grid
+ *     highlights nothing. Upstream (and we, until now — audit-verified on
+ *     both) rested one stationary centre cell there, gridSequence's default
+ *     frame. Grid only: bar and radial already idle dark (their idle
+ *     sequences are empty), so this also makes the family consistent.
+ */
+/** Realistic top of the aligned pipeline's speech range (measured 0.51-0.54 live, 0.68 fixture). */
+const SPEECH_LEVEL_CEILING = 0.65;
+/** Real speech bands sit at ~0.1 and up; true silence idles at ~0, so this splits them cleanly. */
+const SILENCE_FLOOR = 0.02;
+
+/**
+ * A grid of dots that pulses with the audio.
+ *
+ * Ported from livekit/components-js
+ * `packages/shadcn/components/agents-ui/agent-audio-visualizer-grid.tsx`
+ * (Apache License 2.0), except the speaking threshold remap — see the
+ * divergence note above.
+ */
+export function GridVisualizer(
+  props: VariantProps & {
+    /** Rows AND columns of the (always square) grid. Default from the size
+     *  preset. Replaced the former independent rowCount/columnCount pre-1.0:
+     *  columns alone carry the audio signal, so a non-square grid only ever
+     *  changed threshold-ring resolution — never expression (Rob, 2026-08-09;
+     *  upstream is square-by-default via `rowCount ?? columnCount` too). */
+    count?: number;
+    /** Ring distance from center for the connecting animation, in cells. */
+    spread?: number;
+    /** Ms between scripted frames. Default 100. */
+    interval?: number;
+  },
+): JSX.Element {
+  const rows = () => props.count ?? defaultGridCount(props.size);
+  const cols = () => rows();
+  const interval = () => props.interval ?? 100;
+  const items = () => Array.from({ length: rows() * cols() }, (_, i) => i);
+
+  const tick = useSequencer(() =>
+    // Speaking is driven by audio, not the clock; freezing also parks it.
+    props.frozen || props.state === 'speaking' ? Infinity : interval(),
+  );
+
+  const sequence = () => gridSequence(props.state, 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).
+  const levels = () =>
+    props.state === 'speaking' ? normalizeVolumeBands(props.bands, cols()) : new Array(cols()).fill(0);
+
+  /**
+   * While speaking, a cell lights when its column's level clears a threshold
+   * that grows with distance from the middle row: the column fills
+   * centre-outward, so the grid reads as a spectrum. A silent column shows
+   * nothing (the floor), a loud one reaches the edges (the scaled ramp) —
+   * both per the divergence note at the top of this file.
+   */
+  function isLit(index: number): boolean {
+    if (props.state === 'speaking') {
+      const y = Math.floor(index / cols());
+      const mid = Math.floor(rows() / 2);
+      const scaled = (Math.abs(mid - y) / (mid + 1)) * SPEECH_LEVEL_CEILING;
+      // max() applies the floor exactly where the ramp would be 0 (the middle
+      // row); every other threshold already clears it.
+      const threshold = Math.max(scaled, SILENCE_FLOOR);
+      return (levels()[index % cols()] ?? 0) >= threshold;
+    }
+    // Idle shows a fully dark grid (Rob, 2026-08-09) — divergence (3) above;
+    // 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;
+    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';
+    return `${interval() / (isLit(index) ? 1000 : 100)}s`;
+  }
+
+  return (
+    <div
+      data-kai-state={props.state}
+      class={cn('grid', props.class)}
+      style={{
+        'grid-template-columns': `repeat(${cols()}, 1fr)`,
+        gap: `${GRID_GAP[props.size]}px`,
+        ...(props.color ? { color: props.color } : {}),
+      }}
+    >
+      {/*
+        <Index>, not <For>, matching BarVisualizer: `items()` positions are
+        stable, but mapping by POSITION (rather than by `===` on the array
+        value) is the correct primitive here too, and it keeps the render-prop
+        contract identical across variants. See the note in variant-bar.tsx.
+      */}
+      <Index each={items()}>
+        {(_value, index) => {
+          // Every column repeats down every row, so a cell's level comes from
+          // its column band, not its flat position: index % cols(), not index.
+          // `highlighted`/`value` are live accessors: the callback below runs
+          // once per position, so a consumer's render-prop must call them
+          // itself to stay current rather than close over a one-time snapshot.
+          const item = {
+            index,
+            highlighted: () => isLit(index),
+            value: () => levels()[index % cols()] ?? 0,
+          };
+          return (
+            props.children?.(item) ?? (
+              // The lit state is a SECOND part TOKEN (`part(cell highlighted)`),
+              // not a `data-*` attribute selector on `::part(cell)`: a CSS
+              // attribute selector cannot follow a pseudo-element, so
+              // `::part(cell)[data-kai-highlighted="true"]` never matches
+              // anything from outside the shadow root. `data-kai-highlighted`
+              // stays on the element for the render-prop and for styling from
+              // inside the shadow root; `part` is the external seam.
+              <div
+                part={item.highlighted() ? 'cell highlighted' : 'cell'}
+                data-kai-index={item.index}
+                data-kai-highlighted={item.highlighted()}
+                class={cn(
+                  'place-self-center rounded-full bg-current/10 transition-all ease-out',
+                  'data-[kai-highlighted=true]:bg-current',
+                )}
+                style={{
+                  width: `${GRID_CELL[props.size]}px`,
+                  height: `${GRID_CELL[props.size]}px`,
+                  'transition-duration': transition(index),
+                }}
+              />
+            )
+          );
+        }}
+      </Index>
+    </div>
+  );
+}

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

@@ -0,0 +1,158 @@
+import { Index, type JSX } from 'solid-js';
+import { cn } from '../../utils/cn';
+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';
+
+/**
+ * Bars arranged around a circle, growing outward with the audio.
+ *
+ * Ported from livekit/components-js
+ * `packages/shadcn/components/agents-ui/agent-audio-visualizer-radial.tsx`
+ * (Apache License 2.0).
+ */
+export function RadialVisualizer(
+  props: VariantProps & { barCount?: number; radius?: number },
+): JSX.Element {
+  // Floored at 1: at barCount 0, dotSize below divides by zero (Infinity),
+  // and 0 % 4 === 0 slips past the divisibility warning silently. The
+  // dispatcher only ever passes positive counts today, but the element
+  // facade exposes `bar-count` as a consumer-facing attribute next.
+  const count = () => Math.max(1, props.barCount ?? defaultRadialBarCount(props.size));
+  const radius = () => props.radius ?? RADIAL_RADIUS[props.size];
+
+  // Upstream warns when the ring cannot split into four even quadrants -- not
+  // a hard requirement (any count still renders), just a symmetry hint. This
+  // is a plain statement, not inside a `createEffect`: a Solid component body
+  // runs once per mount (unlike React, there is no re-render to guard
+  // against), so it already fires exactly once for this instance and never
+  // again, including across unrelated reactive updates to other props.
+  if (count() % 4 !== 0) {
+    console.warn(
+      `<kai-audio-visualizer variant="radial">: barCount ${count()} is not divisible by 4. ` +
+        `The ring will look asymmetric.`,
+    );
+  }
+
+  // Chord length at this radius: keeps neighbouring dots from touching however
+  // many bars are on the ring.
+  const dotSize = () => (radius() * Math.PI) / count();
+
+  // 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());
+
+  // `thinking` parks the sequencer itself (radialInterval returns Infinity)
+  // and spins the whole ring in CSS instead, so every bar reads as lit rather
+  // than following the scripted highlight groups meant for `listening`
+  // (radialSequence's `thinking` case reuses those groups for a different
+  // purpose: they interleave the ring so it still looks even while rotating,
+  // not so a subset blinks).
+  const highlighted = () =>
+    props.state === '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).
+  const levels = () =>
+    props.state === 'speaking'
+      ? normalizeVolumeBands(props.bands, count())
+      : new Array(count()).fill(0);
+
+  const spinning = () => props.state === 'thinking' && !props.frozen;
+
+  return (
+    <div
+      data-kai-state={props.state}
+      class={cn('relative flex items-center justify-center', spinning() && 'animate-spin', props.class)}
+      style={{
+        height: `${CONTAINER_HEIGHT[props.size]}px`,
+        'aspect-ratio': '1',
+        ...(spinning() ? { 'animation-duration': '5s' } : {}),
+        ...(props.color ? { color: props.color } : {}),
+      }}
+    >
+      {/*
+        <Index>, not <For>, matching the other two variants: Solid's <For>
+        keys nodes by `===` on the array VALUE, and `levels()` is an array of
+        plain numbers that changes on nearly every frame while speaking. That
+        would tear down and recreate every spoke each frame instead of
+        patching it in place, defeating the height/colour transition below
+        right at the listening -> speaking boundary. <Index> maps by POSITION
+        instead, so each spoke's DOM node is created once and its `level`
+        accessor updates in place. See the note in variant-bar.tsx.
+      */}
+      <Index each={levels()}>
+        {(level, i) => {
+          // `i` is a plain number here (stable per position under <Index>),
+          // not an accessor -- do not call it as `i()`. `highlighted`/`value`
+          // ARE live accessors: this callback runs once per position, so
+          // anything a consumer's render-prop wants to stay current must call
+          // these itself rather than close over a one-time snapshot.
+          const item = {
+            index: i,
+            highlighted: () => highlighted().includes(i),
+            value: () => level(),
+          };
+          return (
+            <div
+              data-kai-spoke
+              class="absolute top-1/2 left-1/2 h-1 w-1 -translate-x-1/2 -translate-y-1/2"
+              style={{
+                'transform-origin': 'center',
+                transform: `rotate(${(i / count()) * Math.PI * 2}rad) translateY(${radius()}px)`,
+              }}
+            >
+              {/*
+                Unlike bar/grid, the render-prop's output does NOT become the
+                positioned element itself: it renders INSIDE this wrapper's
+                rotate+translateY placement, since something has to place the
+                spoke on the ring even when the caller owns its markup. See
+                the `children` doc on VariantProps in variant-bar.tsx.
+              */}
+              {props.children?.(item) ?? (
+                // The lit state is a SECOND part TOKEN (`part(bar highlighted)`),
+                // not a `data-*` attribute selector on `::part(bar)`: a CSS
+                // attribute selector cannot follow a pseudo-element, so
+                // `::part(bar)[data-kai-highlighted="true"]` never matches
+                // anything from outside the shadow root. `data-kai-highlighted`
+                // stays on the element for the render-prop and for styling
+                // from inside the shadow root; `part` is the external seam.
+                <div
+                  part={item.highlighted() ? 'bar highlighted' : 'bar'}
+                  data-kai-index={item.index}
+                  data-kai-highlighted={item.highlighted()}
+                  class={cn(
+                    'origin-bottom rounded-full bg-current/10',
+                    'data-[kai-highlighted=true]:bg-current',
+                  )}
+                  style={{
+                    width: `${dotSize()}px`,
+                    'min-height': `${dotSize()}px`,
+                    // x10 so a mid-level band reaches a readable length; upstream's factor.
+                    height: `${dotSize() * 10 * level()}px`,
+                    // Deliberate, approved divergence from upstream: see the
+                    // matching comment in variant-bar.tsx. `150ms` for
+                    // colour is unchanged from upstream's constant; only the
+                    // new `100ms` height transition is our addition, and
+                    // `frozen` disables both together rather than leaving
+                    // colour still animating for a reduced-motion user.
+                    transition: props.frozen
+                      ? 'none'
+                      : 'height 100ms ease-linear, background-color 150ms ease-linear',
+                  }}
+                />
+              )}
+            </div>
+          );
+        }}
+      </Index>
+    </div>
+  );
+}