@yewdiel21/motion-kit 0.10.0 → 0.15.0

package/src/components/virtual-list/react.tsx

@@ -0,0 +1,101 @@
+'use client';
+import { forwardRef, useImperativeHandle, useRef, useState, type HTMLAttributes, type ReactElement, type ReactNode, type Ref } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import type { VirtualRange } from '../../core/virtual';
+import { createVirtualList, type VirtualKey, type VirtualListInstance, type VirtualListOptions, type VirtualScrollOptions } from './engine';
+
+export interface VirtualListProps<T> extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect' | 'children'>, Omit<VirtualListOptions<T>, 'items' | 'renderItem' | 'onRange'> {
+  items: T[];
+  /** A row's content; without it, its text. */
+  renderItem?: (item: T, index: number) => ReactNode;
+}
+
+export interface VirtualListHandle {
+  scrollToIndex(index: number, options?: VirtualScrollOptions): void;
+}
+
+const keyFor = <T,>(getKey: VirtualListOptions<T>['getKey'], item: T, index: number): VirtualKey => {
+  if (getKey) return getKey(item, index);
+  const id = item && typeof item === 'object' ? (item as { id?: unknown }).id : undefined;
+  return typeof id === 'string' || typeof id === 'number' ? id : index;
+};
+
+/**
+ * <VirtualList items={rows} itemHeight={44} renderItem={(row) => <Row {...row} />} selectable="multiple" />.
+ * React renders only the rows in view; the engine adopts its viewport, and places, measures and picks the rows.
+ */
+function VirtualListInner<T>(
+  { items, renderItem, itemHeight, estimatedHeight, overscan, itemText, getKey, selectable, selected, label, emptyLabel, locale, onSelect, onActivate, onEndReached, className, ...props }: VirtualListProps<T>,
+  handle: Ref<VirtualListHandle>,
+) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<VirtualListInstance<T> | null>(null);
+  const [range, setRange] = useState<VirtualRange>({ start: 0, end: 0 });
+  const shown = useRef(items);
+  const select = useLatest(onSelect);
+  const activate = useLatest(onActivate);
+  const more = useLatest(onEndReached);
+  const text = useLatest(itemText);
+  const key = useLatest(getKey);
+  useImperativeHandle(handle, () => ({ scrollToIndex: (index, options) => instance.current?.scrollToIndex(index, options) }), []);
+  const custom = Boolean(renderItem);
+  useIsomorphicLayoutEffect(() => {
+    const created = createVirtualList<T>(ref.current, {
+      items: shown.current,
+      itemHeight,
+      estimatedHeight,
+      overscan,
+      selectable,
+      selected,
+      label,
+      emptyLabel,
+      locale,
+      itemText: itemText ? (item) => text.current?.(item) ?? '' : undefined,
+      getKey: (item, index) => keyFor(key.current, item, index),
+      onSelect: (keys, chosen) => select.current?.(keys, chosen),
+      onActivate: (item, index) => activate.current?.(item, index),
+      onEndReached: onEndReached ? () => more.current?.() : undefined,
+      onRange: custom ? setRange : undefined,
+    });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [itemHeight, estimatedHeight, overscan, String(selectable), label, emptyLabel, locale, custom, Boolean(onEndReached), Boolean(itemText)]);
+  useIsomorphicLayoutEffect(() => {
+    if (shown.current === items) return;
+    shown.current = items;
+    instance.current?.setItems(items);
+  }, [items]);
+  const selectedKey = JSON.stringify(selected ?? null);
+  useIsomorphicLayoutEffect(() => {
+    if (selected && instance.current && JSON.stringify(instance.current.selected) !== JSON.stringify(selected)) instance.current.select(selected);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [selectedKey]);
+  // After React drew the window: place and measure it.
+  useIsomorphicLayoutEffect(() => {
+    if (custom) instance.current?.refresh();
+  });
+  return (
+    <div {...props} ref={ref} className={['mk-virtual-list', className].filter(Boolean).join(' ')}>
+      <div data-mk-vl-viewport="">
+        <div data-mk-vl-spacer="">
+          {renderItem
+            ? items.slice(range.start, Math.min(range.end, items.length)).map((item, i) => {
+                const index = range.start + i;
+                return (
+                  <div key={keyFor(getKey, item, index)} data-mk-vl-item="" data-index={index}>
+                    {renderItem(item, index)}
+                  </div>
+                );
+              })
+            : null}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export const VirtualList = forwardRef(VirtualListInner) as <T>(props: VirtualListProps<T> & { ref?: Ref<VirtualListHandle> }) => ReactElement;

package/src/components/virtual-list/virtual-list.css

@@ -0,0 +1,194 @@
+/* virtual-list — a 12 px box on surface-1 that scrolls inside (--mk-vl-height, 24rem); the rows sit on a spacer as tall
+   as all of them. Chosen rows take accent-soft and a check that pops; a 2 px accent ring glides between rows for the
+   keyboard; a row reached with scrollToIndex() flashes; the position pill (8 px, inverse glass) rides the right edge
+   while scrolling. */
+.mk-virtual-list,
+mk-virtual-list {
+  --mk-vl-height: 24rem;
+  position: relative;
+  display: block;
+  min-width: 0;
+  color: var(--mk-text);
+}
+
+[data-mk-vl-viewport] {
+  position: relative;
+  box-sizing: border-box;
+  height: var(--mk-vl-height);
+  overflow-y: auto;
+  border: 1px solid var(--mk-outline-soft);
+  border-radius: 12px;
+  outline: none;
+  background: var(--mk-surface-1);
+  overscroll-behavior: contain;
+}
+
+[data-mk-vl-viewport]:focus-visible {
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--mk-accent) 35%, transparent);
+}
+
+[data-mk-vl-spacer] {
+  position: relative;
+  width: 100%;
+}
+
+[data-mk-vl-item] {
+  position: absolute;
+  top: 0;
+  right: 0;
+  left: 0;
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  min-width: 0;
+  padding: 0.75rem 1rem;
+  border-bottom: 1px solid var(--mk-outline-soft);
+}
+
+[role='listbox'] > [data-mk-vl-spacer] > [data-mk-vl-item] {
+  cursor: pointer;
+  -webkit-user-select: none;
+  user-select: none;
+  transition:
+    background-color 0.15s,
+    color 0.15s;
+}
+
+[role='listbox'] > [data-mk-vl-spacer] > [data-mk-vl-item]:hover {
+  background: color-mix(in srgb, var(--mk-text) 5%, transparent);
+}
+
+[data-mk-vl-item][aria-selected='true'],
+[role='listbox'] > [data-mk-vl-spacer] > [data-mk-vl-item][aria-selected='true']:hover {
+  background: var(--mk-accent-soft);
+  color: var(--mk-on-accent-soft, var(--mk-text));
+}
+
+/* The check of a chosen row; it pops only on the row just chosen, not on rows scrolled into view. */
+[role='listbox'] > [data-mk-vl-spacer] > [data-mk-vl-item]::after {
+  content: '';
+  flex: none;
+  width: 1.125rem;
+  height: 1.125rem;
+  margin-left: auto;
+  background: var(--mk-accent);
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='3' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M5 12.5l4.5 4.5L19 7.5'/%3E%3C/svg%3E") center / contain no-repeat;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='3' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M5 12.5l4.5 4.5L19 7.5'/%3E%3C/svg%3E") center / contain no-repeat;
+  opacity: 0;
+}
+
+[role='listbox'] > [data-mk-vl-spacer] > [data-mk-vl-item][aria-selected='true']::after {
+  opacity: 1;
+}
+
+[data-mk-vl-item][data-mk-vl-just]::after {
+  animation: mk-vl-check 0.4s cubic-bezier(0.38, 0.49, 0, 1.5);
+}
+
+@keyframes mk-vl-check {
+  from {
+    opacity: 0;
+    transform: scale(0.3) rotate(-20deg);
+  }
+}
+
+[data-mk-vl-cursor] {
+  position: absolute;
+  top: 0;
+  right: 4px;
+  left: 4px;
+  z-index: 1;
+  border-radius: 8px;
+  box-shadow: inset 0 0 0 2px var(--mk-accent);
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.15s;
+}
+
+[data-mk-vl-viewport]:focus-visible [data-mk-vl-cursor] {
+  opacity: 1;
+}
+
+[data-mk-vl-flash] {
+  animation: mk-vl-flash 1.2s cubic-bezier(0.38, 0.49, 0, 1);
+}
+
+@keyframes mk-vl-flash {
+  0%,
+  30% {
+    background-color: color-mix(in srgb, var(--mk-accent) 24%, var(--mk-surface-1));
+  }
+}
+
+[data-mk-vl-foot] {
+  position: absolute;
+  top: 0;
+  right: 0;
+  left: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  height: 48px;
+  color: var(--mk-muted);
+  font-size: 0.875rem;
+}
+
+[data-mk-vl-foot][hidden],
+[data-mk-vl-empty][hidden],
+[data-mk-vl-pill][hidden] {
+  display: none;
+}
+
+[data-mk-vl-foot][aria-busy='true']::before {
+  content: '';
+  width: 0.875rem;
+  height: 0.875rem;
+  border: 2px solid currentColor;
+  border-right-color: transparent;
+  border-radius: 50%;
+  animation: mk-vl-spin 0.8s linear infinite;
+}
+
+@keyframes mk-vl-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+[data-mk-vl-empty] {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  margin: 0;
+  color: var(--mk-muted);
+  font-size: 0.875rem;
+  pointer-events: none;
+}
+
+[data-mk-vl-pill] {
+  position: absolute;
+  top: 0.5rem;
+  right: 0.875rem;
+  z-index: 2;
+  padding: 0.3rem 0.625rem;
+  border-radius: 8px;
+  background: var(--mk-glass-inverse, var(--mk-text));
+  box-shadow: 0 6px 18px -8px color-mix(in srgb, var(--mk-shadow-color, #000) 45%, transparent);
+  color: var(--mk-on-glass-inverse, var(--mk-surface-1));
+  font-size: 0.75rem;
+  font-variant-numeric: tabular-nums;
+  font-weight: 600;
+  white-space: nowrap;
+  pointer-events: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-vl-item][data-mk-vl-just]::after,
+  [data-mk-vl-flash],
+  [data-mk-vl-foot][aria-busy='true']::before {
+    animation: none;
+  }
+}

package/src/components/voice-dots/README.md

@@ -0,0 +1,48 @@
+# voice-dots
+
+Puntos que respiran, escuchan, piensan y hablan; pueden seguir el nivel real de una fuente de audio.
+
+## Instalación
+
+```tsx
+import '@yewdiel21/motion-kit/css';
+import { VoiceDots } from '@yewdiel21/motion-kit/react';
+```
+
+```sh
+npx @yewdiel21/motion-kit add voice-dots --react --elements
+```
+
+## React
+
+```tsx
+<VoiceDots state="listening" source={stream} level={level} />
+```
+
+Los callbacks del ejemplo (`ask`, `run`, `setTool`, `setVolume`) pertenecen a tu aplicación. React acepta `className`, `style` y atributos HTML. Los componentes con estado exponen `instanceRef` (excepto PillButton).
+
+## HTML / Astro
+
+```html
+<mk-voice-dots state="listening" size="12"></mk-voice-dots>
+<script type="module">
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-voice-dots']);
+</script>
+```
+
+En Astro usa un `<script>` procesado por Astro. En HTML directo el import requiere bundler o import map. También puedes usar `import { createVoiceDots } from '@yewdiel21/motion-kit'` y llamar a la factory con el contenedor y las mismas opciones. Al desmontar, llama a `instance.destroy()`.
+
+## Opciones
+
+state: idle, listening, thinking o speaking. count: 4 (3 a 6). size: 12 px. colorful: false. labels: textos de estado. En React source acepta MediaStream o HTMLMediaElement; level acepta 0…1 o un array. Instancia: setState(), setLevel(), listen(source), stop(), state.
+
+El componente no solicita acceso al micrófono por sí solo. Obtén el stream tras una acción del usuario con `navigator.mediaDevices.getUserMedia({audio:true})`. `await instance.listen(stream)` devuelve una función para desconectar el análisis; la aplicación debe detener sus tracks al terminar. La fuente se analiza localmente. `stop()` desconecta la fuente. Sin audio, listening acepta `setLevel()` y speaking usa una onda de demostración.
+
+Los nombres camelCase se escriben como atributos kebab-case. Los arrays y objetos se pasan como JSON. Los booleanos aceptan atributo vacío o `"false"`.
+
+## Estilos y accesibilidad
+
+Variables: --mk-voice-size; colores semánticos del tema..
+
+Respeta los colores del tema, foco visible y `prefers-reduced-motion`. Los gráficos incluyen una tabla accesible y selección con flechas, Home, End y Escape. Heatmap usa arriba/abajo para un día e izquierda/derecha para una semana. Toolbar usa flechas y Home/End; OrbitMenu cierra con Escape y devuelve el foco. Los controles conservan nombres accesibles; VoiceDots anuncia los estados sin leer cada fotograma.

package/src/components/voice-dots/element.ts

@@ -0,0 +1,45 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createVoiceDots, type VoiceDotsInstance, type VoiceState } from './engine';
+
+/**
+ * <mk-voice-dots class="mk-voice-dots" state="listening"></mk-voice-dots>
+ * Dots that move with a voice. element.listen(stream) follows a microphone; emits mk:state ({state}).
+ */
+export class MkVoiceDotsElement extends MkElement<VoiceDotsInstance> {
+  static options: Record<string, OptionType> = { state: 'string', count: 'number', colorful: 'boolean', size: 'number' };
+
+  protected create(options: Record<string, unknown>) {
+    return createVoiceDots(this, options);
+  }
+
+  /** A new state flows from where the dots are (the engine, and the audio it follows, stay). */
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (name === 'state' && this.instance) {
+      this.instance.setState((next ?? 'idle') as VoiceState);
+      return;
+    }
+    super.attributeChangedCallback(name, previous, next);
+  }
+
+  get state() {
+    return this.instance?.state ?? 'idle';
+  }
+
+  set state(next: VoiceState) {
+    this.setAttribute('state', next);
+  }
+
+  setLevel(level: number | number[]) {
+    this.instance?.setLevel(level);
+  }
+
+  listen(source: MediaStream | HTMLMediaElement) {
+    return this.instance?.listen(source) ?? Promise.resolve(() => {});
+  }
+
+  stop() {
+    this.instance?.stop();
+  }
+}
+
+export const defineVoiceDots = () => defineElement('mk-voice-dots', MkVoiceDotsElement);

package/src/components/voice-dots/engine.ts

@@ -0,0 +1,243 @@
+import { registerMotion } from '../../core/gsap';
+import { whileVisible } from '../../core/loop';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+
+/*
+ * Voice dots: four dots that show a voice conversation, like an assistant's.
+ * Idle, they breathe one after another. Listening, each dot stretches into a
+ * pill with its band of the voice (from a microphone or a playing element
+ * through an AnalyserNode, or levels the app gives), springing up fast and
+ * settling slower so syllables read as a bounce. Thinking, they gather into a
+ * ring and orbit. Speaking, they ride a travelling wave (with the playing
+ * audio's level when there is one). Every change of state flows from where the
+ * dots are, so nothing jumps; the frame loop only runs while the dots are on
+ * screen. Monochrome (the text colour) by default, or the chart colours. A
+ * status line says the state to assistive tech; with reduced motion the dots
+ * stay still and only their colour and the status change.
+ */
+
+export type VoiceState = 'idle' | 'listening' | 'thinking' | 'speaking';
+
+export interface VoiceDotsOptions {
+  /** Default 'idle'. */
+  state?: VoiceState;
+  /** Dots (default 4, 3…6). */
+  count?: number;
+  /** The chart colours instead of the text colour. */
+  colorful?: boolean;
+  /** Dot size in px (default 12). */
+  size?: number;
+  /** The status text for each state. */
+  labels?: Partial<Record<VoiceState, string>>;
+}
+
+export interface VoiceDotsInstance extends Instance {
+  setState(state: VoiceState): void;
+  readonly state: VoiceState;
+  /** The voice's level, 0…1: one for all dots or one per dot (from your own analysis). */
+  setLevel(level: number | number[]): void;
+  /** Follow a microphone stream or a playing <audio>/<video>; resolves to a function that stops following. */
+  listen(source: MediaStream | HTMLMediaElement): Promise<() => void>;
+  /** Stop following the audio (the state stays). */
+  stop(): void;
+}
+
+const LABELS: Record<VoiceState, string> = { idle: 'Asistente en espera', listening: 'Escuchando…', thinking: 'Pensando…', speaking: 'Hablando…' };
+const STATES: VoiceState[] = ['idle', 'listening', 'thinking', 'speaking'];
+/** One AudioContext source per media element: the platform allows only one. */
+const mediaSources = new WeakMap<HTMLMediaElement, MediaElementAudioSourceNode>();
+let audio: AudioContext | null = null;
+
+export function createVoiceDots(root: HTMLElement | null, options: VoiceDotsOptions = {}): VoiceDotsInstance {
+  if (!root) return inert({ setState() {}, state: 'idle' as VoiceState, setLevel() {}, listen: async () => () => {}, stop() {} });
+  registerMotion();
+  const scope = createScope();
+  const count = Math.max(3, Math.min(6, Math.round(options.count ?? 4)));
+  const size = Math.max(4, options.size ?? 12);
+  const labels = { ...LABELS, ...options.labels };
+  let state: VoiceState = STATES.includes(options.state as VoiceState) ? options.state! : 'idle';
+
+  const row = document.createElement('span');
+  row.dataset.mkVoiceRow = '';
+  row.setAttribute('aria-hidden', 'true');
+  const dots = Array.from({ length: count }, (_, i) => {
+    const dot = document.createElement('span');
+    dot.dataset.mkVoiceDot = String(i + 1);
+    row.append(dot);
+    return dot;
+  });
+  const status = document.createElement('span');
+  status.className = 'mk-sr-only';
+  status.setAttribute('role', 'status');
+  root.append(row, status);
+  scope.add(() => {
+    row.remove();
+    status.remove();
+  });
+  scope.attr(root, 'data-mk-ready', '');
+  scope.attr(root, 'data-mk-state', state);
+  if (options.colorful) scope.attr(root, 'data-mk-colorful', '');
+  root.style.setProperty('--mk-voice-size', `${size}px`);
+  scope.add(() => {
+    root.style.removeProperty('--mk-voice-size');
+    if (!root.getAttribute('style')) root.removeAttribute('style');
+  });
+
+  // Per dot: what is drawn (height, x, y) and the level it follows.
+  const drawn = dots.map(() => ({ h: size, x: 0, y: 0, vh: 0 }));
+  const levels = dots.map(() => 0);
+  let time = 0;
+  const gap = size * 0.9;
+  const home = (i: number) => (i - (count - 1) / 2) * (size + gap);
+
+  const draw = () => {
+    dots.forEach((dot, i) => {
+      const d = drawn[i]!;
+      dot.style.height = `${d.h.toFixed(2)}px`;
+      dot.style.transform = `translate(${d.x.toFixed(2)}px, ${d.y.toFixed(2)}px)`;
+    });
+  };
+  const still = () => {
+    dots.forEach((_, i) => Object.assign(drawn[i]!, { h: size, x: 0, y: 0, vh: 0 }));
+    draw();
+  };
+
+  let analyser: AnalyserNode | null = null;
+  let bins: Uint8Array<ArrayBuffer> | null = null;
+  let release: (() => void) | null = null;
+  let listening = 0;
+  /** The voice's bands (about 120 Hz – 3 kHz) into one level per dot. */
+  const sample = () => {
+    if (!analyser || !bins) return;
+    analyser.getByteFrequencyData(bins);
+    const hz = (audio?.sampleRate ?? 48000) / 2 / bins.length;
+    const low = Math.max(1, Math.floor(120 / hz));
+    const high = Math.min(bins.length - 1, Math.ceil(3000 / hz));
+    const span = (high - low) / count;
+    for (let i = 0; i < count; i++) {
+      let sum = 0;
+      const from = Math.floor(low + span * i);
+      const to = Math.max(from + 1, Math.floor(low + span * (i + 1)));
+      for (let k = from; k < to; k++) sum += bins[k]!;
+      // Higher bands are quieter in a voice: they get a lift.
+      levels[i] = Math.min(1, (sum / (to - from) / 255) * (1.4 + i * 0.35));
+    }
+  };
+
+  const tick = (dt: number) => {
+    if (reduced()) return;
+    time += dt / 60;
+    sample();
+    const k = 1 - Math.exp(-dt * 0.35);
+    dots.forEach((_, i) => {
+      const d = drawn[i]!;
+      let h = size;
+      let x = 0;
+      let y = 0;
+      if (state === 'idle') {
+        h = size * (1 + 0.18 * Math.max(0, Math.sin(time * 3.2 - i * 0.7)));
+        y = -2 * Math.max(0, Math.sin(time * 3.2 - i * 0.7));
+      } else if (state === 'listening') {
+        h = size + levels[i]! * size * 3.2;
+      } else if (state === 'thinking') {
+        // A ring around the middle, turning.
+        const angle = time * 4 + (i / count) * Math.PI * 2;
+        const ring = size * 1.2;
+        x = Math.cos(angle) * ring - home(i);
+        y = Math.sin(angle) * ring;
+      } else {
+        const wave = 0.5 + 0.5 * Math.sin(time * 9 - i * 0.9);
+        const voice = analyser ? levels[i]! : 0.55;
+        h = size + wave * voice * size * 2.4;
+      }
+      // Height on a spring that rises fast and falls slower (a bounce per syllable); position eases.
+      const stiffness = h > d.h ? 0.5 : 0.18;
+      d.vh = (d.vh + (h - d.h) * stiffness) * 0.6;
+      d.h = Math.max(size * 0.8, d.h + d.vh * dt);
+      d.x += (x - d.x) * k;
+      d.y += (y - d.y) * k;
+    });
+    draw();
+  };
+  const stopLoop = whileVisible(root, tick);
+  scope.add(stopLoop);
+
+  const stop = () => {
+    listening++;
+    release?.();
+    release = null;
+    analyser = null;
+    bins = null;
+    levels.fill(0);
+  };
+  scope.add(stop);
+
+  const setState = (next: VoiceState) => {
+    if (!STATES.includes(next)) return;
+    state = next;
+    root.setAttribute('data-mk-state', next);
+    status.textContent = next === 'idle' ? '' : labels[next];
+    if (reduced()) still();
+    root.dispatchEvent(new CustomEvent('mk:state', { bubbles: true, detail: { state: next } }));
+  };
+
+  draw();
+  if (state !== 'idle') status.textContent = labels[state];
+
+  return {
+    setState,
+    get state() {
+      return state;
+    },
+    setLevel(level) {
+      const list = Array.isArray(level) ? level : dots.map(() => level);
+      dots.forEach((_, i) => {
+        const value = Number(list[i % Math.max(1, list.length)]);
+        levels[i] = Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : 0;
+      });
+    },
+    async listen(source) {
+      stop();
+      const request = listening;
+      const Context = globalThis.AudioContext ?? (globalThis as unknown as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext;
+      if (!Context || scope.disposed) return () => {};
+      audio ??= new Context();
+      if (audio.state === 'suspended') await audio.resume().catch(() => {});
+      if (scope.disposed || request !== listening) return () => {};
+      const node = audio.createAnalyser();
+      node.fftSize = 256;
+      node.smoothingTimeConstant = 0.55;
+      let input: AudioNode;
+      if (source instanceof HTMLMediaElement) {
+        const existing = mediaSources.get(source) ?? audio.createMediaElementSource(source);
+        mediaSources.set(source, existing);
+        // Followed before: its direct line to the speakers goes, the analyser's takes over.
+        existing.disconnect();
+        input = existing;
+        // A playing element must still be heard.
+        node.connect(audio.destination);
+      } else input = audio.createMediaStreamSource(source);
+      input.connect(node);
+      analyser = node;
+      bins = new Uint8Array(new ArrayBuffer(node.frequencyBinCount));
+      const mine = () => {
+        try {
+          input.disconnect(node);
+          node.disconnect();
+        } catch {
+          // Already disconnected.
+        }
+        // The element keeps playing through the speakers.
+        if (source instanceof HTMLMediaElement && audio) input.connect(audio.destination);
+      };
+      release = mine;
+      return () => {
+        if (release === mine) stop();
+      };
+    },
+    stop,
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/voice-dots/react.tsx

@@ -0,0 +1,52 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect } from '../../react/use-recipe';
+import { createVoiceDots, type VoiceDotsInstance, type VoiceDotsOptions } from './engine';
+
+export interface VoiceDotsProps extends HTMLAttributes<HTMLDivElement>, VoiceDotsOptions {
+  /** A microphone stream or a playing <audio>/<video> to follow. */
+  source?: MediaStream | HTMLMediaElement | null;
+  /** The voice's level, 0…1 (one or one per dot), when the app measures it. */
+  level?: number | number[];
+  instanceRef?: MutableRefObject<VoiceDotsInstance | null>;
+}
+
+/** <VoiceDots state={listening ? 'listening' : 'idle'} source={micStream} /> */
+export function VoiceDots({ state = 'idle', count, colorful, size, labels, source, level, instanceRef, className, ...props }: VoiceDotsProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<VoiceDotsInstance | null>(null);
+  useIsomorphicLayoutEffect(() => {
+    const created = createVoiceDots(ref.current, { state, count, colorful, size, labels });
+    instance.current = created;
+    if (instanceRef) instanceRef.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+      if (instanceRef) instanceRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [count, colorful, size]);
+  useIsomorphicLayoutEffect(() => {
+    if (instance.current && instance.current.state !== state) instance.current.setState(state);
+  }, [state]);
+  useIsomorphicLayoutEffect(() => {
+    const dots = instance.current;
+    if (!dots || !source) return;
+    let stop: (() => void) | null = null;
+    let gone = false;
+    void dots.listen(source).then((done) => {
+      if (gone) done();
+      else stop = done;
+    }).catch((error: unknown) => {
+      if (!gone) ref.current?.dispatchEvent(new CustomEvent('mk:error', { bubbles: true, detail: { error } }));
+    });
+    return () => {
+      gone = true;
+      stop?.();
+    };
+  }, [source, count, colorful, size]);
+  useIsomorphicLayoutEffect(() => {
+    if (level !== undefined) instance.current?.setLevel(level);
+  }, [level]);
+  return <div {...props} ref={ref} className={['mk-voice-dots', className].filter(Boolean).join(' ')} />;
+}