@kitn.ai/ui 0.19.0 → 0.20.0

package/src/primitives/visualizer-sequences.ts

@@ -0,0 +1,350 @@
+/**
+ * Pure `state -> highlight set` mappers for the audio visualizer variants.
+ *
+ * Ported from livekit/components-js `packages/shadcn/hooks/agents-ui/`
+ * (Apache License 2.0). Upstream runs four separate animator hooks, each with
+ * its own requestAnimationFrame loop. We keep the sequences (verbatim) but move
+ * the timing into one shared driver, `use-sequencer.ts`.
+ *
+ * Every generator returns a NON-EMPTY array so callers can index with
+ * `sequence[tick % sequence.length]` without a guard.
+ */
+
+export type VisualizerState =
+  | 'idle'
+  | 'connecting'
+  | 'listening'
+  | 'thinking'
+  | 'speaking'
+  | 'disconnected';
+
+export interface Coordinate {
+  x: number;
+  y: number;
+}
+
+const KNOWN: readonly VisualizerState[] = [
+  'idle',
+  'connecting',
+  'listening',
+  'thinking',
+  'speaking',
+  // First-class since 2026-08-10 (Rob): the dead-connection look (flat wave,
+  // nothing lit) upstream renders for its 'disconnected' state. It was an
+  // alias for 'idle' until idle adopted upstream's gentle wave, which left
+  // the flat line unreachable.
+  'disconnected',
+];
+
+/**
+ * LiveKit's AgentState carries room-lifecycle values that mean nothing here.
+ * Accept them so markup ported from LiveKit works unchanged.
+ */
+const ALIASES: Record<string, VisualizerState> = {
+  // Both are dead-connection looks upstream, so 'failed' rides with
+  // 'disconnected' rather than 'idle'.
+  failed: 'disconnected',
+  initializing: 'connecting',
+  'pre-connect-buffering': 'connecting',
+};
+
+export function normalizeState(input: string | undefined): VisualizerState {
+  if (!input) return 'idle';
+  if ((KNOWN as readonly string[]).includes(input)) return input as VisualizerState;
+  return ALIASES[input] ?? 'idle';
+}
+
+// ---------------------------------------------------------------- bar
+
+export function barSequence(state: VisualizerState, barCount: number): number[][] {
+  switch (state) {
+    case 'connecting': {
+      // A mirrored pair sweeping outward: [0, n-1], [1, n-2], ...
+      const seq: number[][] = [];
+      for (let x = 0; x < barCount; x++) seq.push([x, barCount - 1 - x]);
+      return seq.length ? seq : [[]];
+    }
+    case 'listening':
+    case 'thinking': {
+      // Blink the center bar. -1 is a deliberate no-index frame (the "off" beat).
+      return [[Math.floor(barCount / 2)], [-1]];
+    }
+    case 'speaking':
+      return [Array.from({ length: barCount }, (_, i) => i)];
+    // Dead-connection look: mirrors idle (nothing lit) for now. A dedicated
+    // arm so the pending LiveKit disconnected-state measurement can adjust
+    // it in one line.
+    case 'disconnected':
+      return [[]];
+    case 'idle':
+    default:
+      return [[]];
+  }
+}
+
+export function barInterval(state: VisualizerState, barCount: number): number {
+  switch (state) {
+    // The whole sweep should take 2s regardless of how many bars it crosses.
+    case 'connecting':
+      return 2000 / Math.max(1, barCount);
+    case 'listening':
+      return 500;
+    case 'thinking':
+      return 150;
+    default:
+      return 1000;
+  }
+}
+
+// ---------------------------------------------------------------- grid
+
+/**
+ * Walk the perimeter of a ring `spread` cells out from center, clockwise.
+ *
+ * NOTE: This diverges from upstream use-agent-audio-visualizer-grid.ts in two ways:
+ * (1) We use separate centerX and centerY (upstream uses row-center for both axes).
+ *     Upstream never ships non-square grids, so the bug never manifested. Our public
+ *     API is square-only too now (the grid's single `count` prop, 2026-08-09), but
+ *     this function keeps taking rows/columns as plain params, so the correct
+ *     arbitrary-shape handling stays -- it costs nothing and guards any future caller.
+ * (2) We distinguish spread === 0 from spread === undefined (upstream treats 0 as falsy).
+ *     Again, upstream never ships spread=0 explicitly; we do for API completeness.
+ */
+function gridRing(rows: number, columns: number, spread: number): Coordinate[] {
+  const seq: Coordinate[] = [];
+  const centerX = Math.floor(columns / 2);
+  const centerY = Math.floor(rows / 2);
+  const topLeft = { x: Math.max(0, centerX - spread), y: Math.max(0, centerY - spread) };
+  const bottomRight = {
+    x: Math.min(columns - 1, centerX + spread),
+    y: Math.min(rows - 1, centerY + spread),
+  };
+
+  for (let x = topLeft.x; x <= bottomRight.x; x++) seq.push({ x, y: topLeft.y });
+  for (let y = topLeft.y + 1; y <= bottomRight.y; y++) seq.push({ x: bottomRight.x, y });
+  for (let x = bottomRight.x - 1; x >= topLeft.x; x--) seq.push({ x, y: bottomRight.y });
+  for (let y = bottomRight.y - 1; y > topLeft.y; y--) seq.push({ x: topLeft.x, y });
+
+  return seq;
+}
+
+export function gridSequence(
+  state: VisualizerState,
+  rows: number,
+  columns: number,
+  spread?: number,
+): Coordinate[] {
+  const center = { x: Math.floor(columns / 2), y: Math.floor(rows / 2) };
+
+  switch (state) {
+    case 'connecting': {
+      const maxSpread = Math.floor(Math.max(rows, columns) / 2);
+      const clamped = spread !== undefined ? Math.min(spread, maxSpread) : maxSpread;
+      const ring = gridRing(rows, columns, clamped);
+      return ring.length ? ring : [center];
+    }
+    case 'listening': {
+      // One lit frame followed by eight dark ones: a slow heartbeat.
+      const off = { x: -1, y: -1 };
+      return [center, off, off, off, off, off, off, off, off];
+    }
+    case 'thinking': {
+      // Sweep the middle row left to right, then back.
+      const y = Math.floor(rows / 2);
+      const seq: Coordinate[] = [];
+      for (let x = 0; x < columns; x++) seq.push({ x, y });
+      for (let x = columns - 1; x >= 0; x--) seq.push({ x, y });
+      return seq.length ? seq : [center];
+    }
+    // Dead-connection look: the same centre resting frame as idle
+    // (variant-grid suppresses the highlight for both, so nothing lights).
+    // A dedicated arm so the pending LiveKit measurement can adjust it in
+    // one line.
+    case 'disconnected':
+      return [center];
+    default:
+      return [center];
+  }
+}
+
+// ---------------------------------------------------------------- radial
+
+/** Largest divisor of `n` that is at most `max`. Always at least 1. */
+function largestDivisorAtMost(n: number, max: number): number {
+  const gcd = (a: number, b: number): number => {
+    while (b !== 0) {
+      const t = b;
+      b = a % b;
+      a = t;
+    }
+    return a;
+  };
+  for (let i = max; i >= 1; i--) if (gcd(n, i) === i) return i;
+  return 1;
+}
+
+/**
+ * Partition the ring into interleaved groups. Lighting one group per tick reads
+ * as a rotating pattern rather than a single travelling dot. Every index appears
+ * in exactly one group.
+ */
+function radialGroups(barCount: number): number[][] {
+  const divisor =
+    barCount > 8
+      ? barCount / largestDivisorAtMost(barCount, 4)
+      : largestDivisorAtMost(barCount, 2);
+  const safe = Math.max(1, Math.floor(divisor));
+  const perGroup = Math.floor(barCount / safe);
+  return Array.from({ length: safe }, (_, i) =>
+    Array.from({ length: perGroup }, (_, j) => j * safe + i),
+  );
+}
+
+export function radialSequence(state: VisualizerState, barCount: number): number[][] {
+  switch (state) {
+    case 'connecting': {
+      // Pair each bar with the one opposite it, sweeping around the circle.
+      const center = Math.floor(barCount / 2);
+      const seq: number[][] = [];
+      for (let x = 0; x < barCount; x++) seq.push([x, (x + center) % barCount]);
+      return seq.length ? seq : [[]];
+    }
+    case 'listening':
+    case 'thinking': {
+      const groups = radialGroups(barCount);
+      return groups.length ? groups : [[]];
+    }
+    case 'speaking':
+      return [Array.from({ length: barCount }, (_, i) => i)];
+    // Dead-connection look: mirrors idle (nothing lit) for now, one-line
+    // adjustable once the LiveKit measurement lands.
+    case 'disconnected':
+      return [[]];
+    case 'idle':
+    default:
+      return [[]];
+  }
+}
+
+export function radialInterval(state: VisualizerState): number {
+  switch (state) {
+    case 'connecting':
+    case 'listening':
+      return 500;
+    // Infinity parks the sequencer: `thinking` spins the whole container in CSS
+    // with every bar lit, so ticking would fight the animation.
+    case 'thinking':
+      return Infinity;
+    default:
+      return 1000;
+  }
+}
+
+// ---------------------------------------------------------------- shader
+
+/**
+ * Uniform targets for the aura and custom shaders. An array intensity means
+ * "ping-pong between these two" (see create-tween). `speaking` intensity is
+ * omitted from the pulse because live volume drives it instantly instead.
+ */
+export function shaderTargets(
+  state: VisualizerState,
+): { intensity: number | [number, number]; speed: number } {
+  switch (state) {
+    case 'listening':
+      return { intensity: [0.5, 0.8], speed: 2.5 };
+    case 'thinking':
+      return { intensity: [0.25, 0.5], speed: 4.0 };
+    // Same pulse as thinking, its own speed: uSpeed is the only
+    // state-correlated scalar besides intensity that reaches a custom
+    // shader's GLSL (see customUniforms in variant-custom.tsx), so the two
+    // transitional states sharing 4.0 made them indistinguishable to any
+    // consumer shader keying off the kit's uniforms -- the Custom story's
+    // per-state looks are the concrete consumer. Every state now maps to a
+    // distinct speed: idle 1, listening/speaking 2.5 (told apart by band
+    // energy), thinking 4, connecting 6.
+    case 'connecting':
+      return { intensity: [0.25, 0.5], speed: 6.0 };
+    case 'speaking':
+      return { intensity: 0.3, speed: 2.5 };
+    // Dead-connection look: idle's dim intensity but its OWN speed, so a
+    // shader keying off uSpeed can draw a dead line distinct from idle's
+    // calm ridge (see the connecting arm's comment: uSpeed is the only
+    // other state-correlated scalar reaching consumer GLSL). Still
+    // one-line adjustable once the LiveKit measurement lands.
+    case 'disconnected':
+      return { intensity: 0.3, speed: 0.5 };
+    case 'idle':
+    default:
+      return { intensity: 0.3, speed: 1 };
+  }
+}
+
+const WAVE_SPEED = 5;
+const WAVE_AMPLITUDE = 0.025;
+const WAVE_FREQUENCY = 10;
+
+/** Uniform targets for the wave shader. Same shape, different curve. */
+export function waveTargets(state: VisualizerState): {
+  speed: number;
+  amplitude: number;
+  frequency: number;
+  opacity: number | [number, number];
+  pulseDuration: number;
+} {
+  switch (state) {
+    case 'listening':
+      return {
+        speed: WAVE_SPEED,
+        amplitude: WAVE_AMPLITUDE,
+        frequency: WAVE_FREQUENCY,
+        opacity: [1.0, 0.3],
+        pulseDuration: 0.75,
+      };
+    case 'thinking':
+    case 'connecting':
+      return {
+        speed: WAVE_SPEED * 4,
+        amplitude: WAVE_AMPLITUDE / 4,
+        frequency: WAVE_FREQUENCY * 4,
+        opacity: [1.0, 0.3],
+        pulseDuration: 0.4,
+      };
+    case 'speaking':
+    // Upstream's wave switch has NO 'idle' arm: idle falls through to this
+    // same speaking/default arm (speed 10, amplitude 0.025, frequency 10,
+    // opacity 1), a gentle undulation (~1.05px centreline waviness, ~1.5px/s
+    // phase drift, measured on the md tile). Upstream's explicitly FLAT
+    // state is 'disconnected' -- the dedicated arm below. We had flattened
+    // idle instead; Rob wants upstream's look (2026-08-09).
+    case 'idle':
+      return {
+        speed: WAVE_SPEED * 2,
+        amplitude: WAVE_AMPLITUDE,
+        frequency: WAVE_FREQUENCY,
+        opacity: 1.0,
+        pulseDuration: 0,
+      };
+    // Upstream's EXPLICIT flat state, measured: 'disconnected' is the one
+    // arm of their wave switch that zeroes the line. First-class here since
+    // 2026-08-10 (Rob: 'the disconnected wave needs to be that kind of flat
+    // line'). `default` keeps the same flat targets for out-of-union
+    // strings, which normalizeState prevents real callers from reaching.
+    case 'disconnected':
+      return {
+        speed: WAVE_SPEED,
+        amplitude: 0,
+        frequency: 0,
+        opacity: 1.0,
+        pulseDuration: 0,
+      };
+    default:
+      return {
+        speed: WAVE_SPEED,
+        amplitude: 0,
+        frequency: 0,
+        opacity: 1.0,
+        pulseDuration: 0,
+      };
+  }
+}

package/src/test-utils/fake-clock.ts

@@ -0,0 +1,88 @@
+import { vi, beforeEach, afterEach } from 'vitest';
+
+/**
+ * Shared fake `requestAnimationFrame` + `performance.now()` clock for tests
+ * that need to drive time deterministically instead of racing real timers.
+ *
+ * requestAnimationFrame's timestamp and performance.now() share a time origin
+ * per spec, so production code can read either. Stubbing them off the same
+ * fake `now` keeps the two from silently disagreeing.
+ *
+ * The stub holds a REAL per-registration queue, matching a real browser: a
+ * single frame fires every callback that was pending BEFORE that frame, all
+ * with the SAME advanced `now`, in registration order -- so two
+ * independently-animating things under test (e.g. a `createTween`'s own step
+ * loop and `ShaderCanvas`'s separate `draw` loop, both requestAnimationFrame
+ * consumers, both mounted at once) tick together on one `advance()` call
+ * instead of the second silently stealing the first's slot.
+ *
+ * This used to be a single PENDING-callback slot, not a queue: a second
+ * consumer scheduling a new frame before `advance()` ran overwrote the
+ * first rather than queueing behind it. That was fine for anything that only
+ * ever has ONE thing pending at a time (the common case, e.g. bar/grid/radial's
+ * single sequencer tick, or a lone `createTween`), which is why switching to a
+ * queue does not change any of those. It was NOT fine for a mounted shader
+ * variant, where a tween and ShaderCanvas's `draw` are both independently
+ * pending at once: `draw` always registers last and re-arms itself every
+ * `advance()`, so it permanently "won" the single slot and the tween's step
+ * never fired -- silently defeating any test trying to prove something holds
+ * while UNIFORM VALUES genuinely change every frame (see
+ * `variant-custom.test.tsx`'s recompile-guard test for the concrete case this
+ * was fixed for).
+ *
+ * `cancelAnimationFrame` cancels by id now (each `requestAnimationFrame` call
+ * gets its own), not by clearing whatever happens to be in the single slot --
+ * required once more than one callback can be pending at a time, so a
+ * `cancelAnimationFrame(idA)` cannot accidentally drop a DIFFERENT pending
+ * callback `idB`.
+ *
+ * Call once per `describe` block (or at file scope for the whole file); it
+ * registers `beforeEach`/`afterEach` hooks scoped to wherever it is called,
+ * exactly like inlining the hooks would, and returns the driver bound to
+ * that scope's fake clock.
+ */
+export function installFakeClock() {
+  let now = 0;
+  let nextId = 1;
+  let pending = new Map<number, (t: number) => void>();
+
+  beforeEach(() => {
+    now = 0;
+    nextId = 1;
+    pending = new Map();
+    vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
+      const id = nextId++;
+      pending.set(id, cb as (t: number) => void);
+      return id;
+    });
+    vi.stubGlobal('cancelAnimationFrame', (id: number) => {
+      pending.delete(id);
+    });
+    vi.stubGlobal('performance', { now: () => now });
+  });
+
+  afterEach(() => vi.unstubAllGlobals());
+
+  /**
+   * Advance the fake clock and run every callback pending BEFORE this call,
+   * all at the new `now` -- one simulated frame. A callback that reschedules
+   * itself (the normal RAF-loop pattern) lands in a FRESH pending set for the
+   * NEXT `advance()`, not this one: snapshotting the callback list before
+   * invoking any of them is what keeps a self-rescheduling loop from looping
+   * forever inside a single `advance()` call, matching how a real browser
+   * frame never re-enters itself either.
+   */
+  function advance(ms: number) {
+    now += ms;
+    const callbacks = Array.from(pending.values());
+    pending = new Map();
+    for (const cb of callbacks) cb(now);
+  }
+
+  /** Whether at least one requestAnimationFrame callback is currently pending. */
+  function isFramePending(): boolean {
+    return pending.size > 0;
+  }
+
+  return { advance, isFramePending };
+}

package/dist/elements/chunks/arrow-left-CifsGq8x.js

@@ -1 +0,0 @@
-import{I as o}from"./Icon-11SRdjJ4.js";import{c as m,m as r}from"./define-DfTe4zwZ.js";var e=[["path",{d:"m12 19-7-7 7-7",key:"1l729n"}],["path",{d:"M19 12H5",key:"x3x0zl"}]],t=a=>m(o,r(a,{name:"ArrowLeft",iconNode:e})),p=t;export{p as a};

package/dist/elements/chunks/check-CUKS495w.js

@@ -1 +0,0 @@
-import{I as m}from"./Icon-11SRdjJ4.js";import{c as o,m as r}from"./define-DfTe4zwZ.js";var c=[["path",{d:"M20 6 9 17l-5-5",key:"1gmf2c"}]],e=a=>o(m,r(a,{name:"Check",iconNode:c})),f=e;export{f as c};

package/dist/elements/chunks/chevron-down-AELmYT1j.js

@@ -1 +0,0 @@
-import{I as r}from"./Icon-11SRdjJ4.js";import{c as a,m}from"./define-DfTe4zwZ.js";var e=[["path",{d:"m6 9 6 6 6-6",key:"qrunsl"}]],n=o=>a(r,m(o,{name:"ChevronDown",iconNode:e})),p=n;export{p as c};

package/dist/elements/chunks/chevron-right-C8g26oKh.js

@@ -1 +0,0 @@
-import{I as o}from"./Icon-11SRdjJ4.js";import{c as a,m as r}from"./define-DfTe4zwZ.js";var t=[["path",{d:"m9 18 6-6-6-6",key:"mthhwq"}]],e=m=>a(o,r(m,{name:"ChevronRight",iconNode:t})),h=e;export{h as c};

package/dist/elements/chunks/circle-DGcI8Cft.js

@@ -1 +0,0 @@
-import{I as c}from"./Icon-11SRdjJ4.js";import{c as m,m as o}from"./define-DfTe4zwZ.js";var a=[["circle",{cx:"12",cy:"12",r:"10",key:"1mglay"}]],e=r=>m(c,o(r,{name:"Circle",iconNode:a})),i=e;export{i as c};

package/dist/elements/chunks/circle-check-DuU0IcBQ.js

@@ -1 +0,0 @@
-import{I as c}from"./Icon-11SRdjJ4.js";import{c as r,m as a}from"./define-DfTe4zwZ.js";var e=[["circle",{cx:"12",cy:"12",r:"10",key:"1mglay"}],["path",{d:"m9 12 2 2 4-4",key:"dzmm74"}]],o=m=>r(c,a(m,{name:"CircleCheck",iconNode:e})),i=o;export{i as c};

package/dist/elements/chunks/collapsible-DGjADCN6.js

@@ -1 +0,0 @@
-import{s as c,g as k,r as y,c as I,l as p,m as u,i as v,n as h,a as R,N as E,b as N,t as g,y as P,z as q}from"./define-DfTe4zwZ.js";import{c as C}from"./cn-CU7UAWzk.js";var z=g("<div>"),B=g("<button>"),S=g("<div><div>");const m=P(),w=()=>{const o=q(m);if(!o)throw new Error("Collapsible parts must be used within <Collapsible>");return o};function T(o){var n;const[e,l]=c(o,["open","defaultOpen","onOpenChange","disabled","controllerRef","children","class"]),[t,a]=k(e.defaultOpen??!1),s=()=>e.open!==void 0,r=()=>s()?!!e.open:t(),i=()=>!!e.disabled,f=d=>{var b;r()!==d&&(s()||a(d),(b=e.onOpenChange)==null||b.call(e,d))},x=()=>{i()||f(!r())};(n=e.controllerRef)==null||n.call(e,{open:r,setOpen:f});const O=y();return I(m.Provider,{value:{open:r,toggle:x,contentId:O,disabled:i},get children(){var d=z();return p(d,u({get class(){return e.class}},l,{get"data-expanded"(){return r()?"":void 0},get"data-closed"(){return r()?void 0:""},get"data-state"(){return r()?"open":"closed"}}),!1,!0),v(d,()=>e.children),d}})}function U(o){const n=w(),[e,l]=c(o,["children","class","as","onClick"]),t=()=>({type:"button","aria-expanded":n.open(),"aria-controls":n.contentId,disabled:n.disabled()||void 0,"data-expanded":n.open()?"":void 0,"data-closed":n.open()?void 0:"","data-state":n.open()?"open":"closed",onClick:a=>{n.disabled()||(typeof e.onClick=="function"&&e.onClick(a),n.toggle())},class:e.class,...l});return h(()=>h(()=>!!e.as)()?e.as(t()):(()=>{var a=B();return p(a,u(t),!1,!0),v(a,()=>e.children),a})())}function _(o){const n=w(),[e,l]=c(o,["children","class"]);return(()=>{var t=S(),a=t.firstChild;return p(t,u(l,{get id(){return n.contentId},get"data-expanded"(){return n.open()?"":void 0},get"data-closed"(){return n.open()?void 0:""},get class(){return C("grid transition-[grid-template-rows] duration-200 ease-out",n.open()?"grid-rows-[1fr]":"grid-rows-[0fr]")}}),!1,!0),v(a,()=>e.children),R(s=>{var r=!n.open(),i=C("overflow-hidden",e.class);return r!==s.e&&E(t,"inert",s.e=r),i!==s.t&&N(a,s.t=i),s},{e:void 0,t:void 0}),t})()}export{T as C,U as a,_ as b};