panelui-native 0.14.0 → 0.19.0

package/src/components/soundwave/index.tsx

@@ -0,0 +1,1029 @@
+/**
+ * Soundwave — what a voice looks like while an app is listening to it.
+ *
+ * ```tsx
+ * <Soundwave variant="pills" state="listening" level={level} />
+ * ```
+ *
+ * Four looks, because a voice screen needs different ones in different places:
+ * `pills` for the few big capsules over a microphone button, `bars` for a
+ * metering strip in a transcript, `line` for a travelling wave while the
+ * assistant talks back, and `ambient` for a glow that takes the whole screen.
+ *
+ * ## It draws a level; it does not record one
+ *
+ * Nothing here touches the microphone. The app owns the recorder — the
+ * permission prompt, the session, the platform quirks — and hands over a number
+ * between 0 and 1, which keeps this component free of an audio dependency and
+ * usable against a real meter, a synthesised one, or a remote peer's.
+ *
+ * With no `level` at all it animates its own plausible motion for the current
+ * `state`, so a screen can be built and reviewed before any audio exists.
+ *
+ * ## Levels arrive faster than React should re-render
+ *
+ * A recorder reports every 30–60ms. Setting that in state is dozens of renders
+ * a second for a number that only moves pixels, so `level` also accepts a
+ * `SharedValue`: write metering straight into it and nothing above this
+ * component ever re-renders. A plain number works too and is smoothed the same
+ * way — it is the right choice when the level comes from something slow, like a
+ * server-side speaking flag.
+ *
+ * Either way the value is smoothed with a fast attack and a slow release, which
+ * is what makes a meter read as a meter: it snaps up on a syllable and falls
+ * back gently, instead of chattering around every sample.
+ *
+ * ## How each one is drawn
+ *
+ * `bars` and `line` are a *single* animated SVG path — one vertical segment per
+ * bar with a round cap, or one polyline — so forty bars cost one animated prop
+ * a frame rather than forty animated views, and the capsule ends come free from
+ * the stroke cap. `pills` is a handful of views, where that machinery would be
+ * more expensive than the thing it saves. Everything runs in a worklet on the
+ * UI thread; React renders on a resize and otherwise not at all.
+ */
+import { useEffect, useId, useState, type ReactElement, type ReactNode } from 'react';
+import {
+  StyleSheet,
+  View,
+  type LayoutChangeEvent,
+  type ViewProps,
+} from 'react-native';
+import { LinearGradient } from 'expo-linear-gradient';
+import Animated, {
+  useAnimatedProps,
+  useAnimatedStyle,
+  useFrameCallback,
+  useReducedMotion,
+  useSharedValue,
+  type SharedValue,
+} from 'react-native-reanimated';
+import Svg, { Defs, LinearGradient as SvgGradient, Path, Stop } from 'react-native-svg';
+import { useCSSVariable } from 'uniwind';
+import { useIconColor } from '../../icons';
+import { cn } from '../../utils/cn';
+
+const AnimatedPath = Animated.createAnimatedComponent(Path);
+
+export type SoundwaveVariant = 'pills' | 'bars' | 'line' | 'ambient';
+
+export type SoundwaveState = 'idle' | 'listening' | 'thinking' | 'speaking';
+
+/** What each state is doing, for anyone who cannot see it. */
+const STATE_LABEL: Record<SoundwaveState, string> = {
+  idle: 'Idle',
+  listening: 'Listening',
+  thinking: 'Thinking',
+  speaking: 'Speaking',
+};
+
+/**
+ * How fast the smoothed level rises and falls, per second.
+ *
+ * Wildly asymmetric on purpose. A meter that rises and falls at the same rate
+ * either lags the syllable that caused it or flickers on every sample; snapping
+ * up and easing down tracks speech the way an ear expects it to.
+ */
+const ATTACK = 16;
+const RELEASE = 5;
+
+/** Never quite silent: a wave flat at zero reads as broken rather than quiet. */
+const FLOOR = 0.04;
+
+/* -------------------------------------------------------------------------- */
+/* Worklet maths                                                              */
+/* -------------------------------------------------------------------------- */
+
+function clamp01(value: number): number {
+  'worklet';
+  return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+
+/** Deterministic hash in `[0, 1)`. Stable across frames and across mounts. */
+function hashD(a: number, b: number): number {
+  'worklet';
+  const h = Math.sin(a * 12.9898 + b * 78.233) * 43758.5453;
+  return h - Math.floor(h);
+}
+
+/** One decimal place. Path strings are rebuilt every frame; every digit costs. */
+function q(value: number): number {
+  'worklet';
+  return Math.round(value * 10) / 10;
+}
+
+/**
+ * The motion a state runs on its own, with no level supplied.
+ *
+ * Layered at unrelated tempi so it never repeats on a beat — a single sine
+ * reads as a pulse, and a pulse reads as a progress indicator rather than as a
+ * voice.
+ */
+function idleEnergy(state: SoundwaveState, t: number): number {
+  'worklet';
+  if (state === 'listening') {
+    return clamp01(
+      0.34 +
+        0.22 * Math.sin(t * 2.3) +
+        0.16 * Math.sin(t * 3.9 + 1.3) +
+        0.1 * Math.sin(t * 7.1 + 0.6)
+    );
+  }
+  if (state === 'speaking') {
+    return clamp01(
+      0.46 +
+        0.27 * Math.sin(t * 3.1) +
+        0.18 * Math.sin(t * 5.7 + 0.8) +
+        0.09 * Math.sin(t * 9.3)
+    );
+  }
+  if (state === 'thinking') {
+    return clamp01(0.18 + 0.1 * Math.sin(t * 1.6) + 0.05 * Math.sin(t * 2.9 + 2.1));
+  }
+  return clamp01(0.07 + 0.05 * Math.sin(t * 1.1));
+}
+
+/* -------------------------------------------------------------------------- */
+/* The clock every variant shares                                             */
+/* -------------------------------------------------------------------------- */
+
+interface Engine {
+  /** Seconds since mount, scaled by `speed`. */
+  clock: SharedValue<number>;
+  /** Smoothed level, 0–1. What every variant actually draws. */
+  energy: SharedValue<number>;
+  /** Newest first is at the end. Only filled in `scrolling` mode. */
+  samples: SharedValue<number[]>;
+}
+
+const isShared = (value: unknown): value is SharedValue<number> =>
+  typeof value === 'object' && value !== null && 'value' in value;
+
+/**
+ * One shared value to read, whether the caller passed a number or their own.
+ *
+ * A plain number is copied in; a `SharedValue` is handed straight back, which
+ * is the whole reason for accepting one — metering written into it never
+ * re-renders anything.
+ */
+function useNumberSource(value: number | SharedValue<number> | undefined): SharedValue<number> {
+  const own = useSharedValue(0);
+  const external = isShared(value) ? value : null;
+
+  useEffect(() => {
+    if (typeof value === 'number') own.value = value;
+  }, [value, own]);
+
+  return external ?? own;
+}
+
+/** How often `scrolling` mode takes a sample, in seconds. */
+const SAMPLE_INTERVAL = 1 / 24;
+
+interface EngineOptions {
+  level?: number | SharedValue<number>;
+  state: SoundwaveState;
+  sensitivity: number;
+  speed: number;
+  paused: boolean;
+  /** Sample count to keep for `scrolling` mode. Zero keeps none. */
+  history: number;
+}
+
+function useEngine({
+  level,
+  state,
+  sensitivity,
+  speed,
+  paused,
+  history,
+}: EngineOptions): Engine {
+  const reducedMotion = useReducedMotion();
+  const clock = useSharedValue(0);
+  const energy = useSharedValue(0);
+  const samples = useSharedValue<number[]>([]);
+  const nextSample = useSharedValue(0);
+
+  const source = useNumberSource(level);
+  const driven = level !== undefined;
+
+  const running = !paused && !reducedMotion;
+
+  const frame = useFrameCallback((info) => {
+    'worklet';
+    // Elapsed time is accumulated rather than read off the total, so `speed`
+    // can change mid-animation without the wave jumping to wherever the new
+    // rate would have put it. A dropped frame is clamped rather than honoured —
+    // a 300ms hitch played back at full rate is a lurch.
+    const delta = Math.min(info.timeSincePreviousFrame ?? 16, 48) / 1000;
+    clock.value += delta * speed;
+
+    const target = driven
+      ? clamp01(source.value * sensitivity)
+      : idleEnergy(state, clock.value);
+
+    const rate = target > energy.value ? ATTACK : RELEASE;
+    energy.value += (target - energy.value) * Math.min(1, delta * rate);
+
+    if (history > 0 && clock.value >= nextSample.value) {
+      nextSample.value = clock.value + SAMPLE_INTERVAL;
+      // A little per-sample texture, so a held note is a band of varying bars
+      // rather than a solid block — real speech never gives two equal samples.
+      const jitter = 0.82 + 0.36 * hashD(clock.value, 3.3);
+      const next = samples.value.slice(samples.value.length >= history ? 1 : 0);
+      next.push(clamp01(energy.value * jitter));
+      samples.value = next;
+    }
+  }, false);
+
+  const { setActive } = frame;
+  useEffect(() => {
+    setActive(running);
+    return () => setActive(false);
+  }, [running, setActive]);
+
+  // Stopped is not empty: reduced motion and `paused` both get a representative
+  // frame rather than a flat line, which is the difference between "not
+  // animating" and "broken".
+  useEffect(() => {
+    if (running) return;
+    const still = driven ? clamp01(source.value * sensitivity) : 0.42;
+    energy.value = still;
+    if (history > 0) {
+      samples.value = Array.from({ length: history }, (_unused, index) =>
+        clamp01(still * (0.45 + 0.55 * Math.abs(Math.sin(index * 0.7))))
+      );
+    }
+  }, [running, driven, sensitivity, history, source, energy, samples]);
+
+  return { clock, energy, samples };
+}
+
+/* -------------------------------------------------------------------------- */
+/* pills                                                                      */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * One capsule.
+ *
+ * A component rather than a loop of `useAnimatedStyle` in the parent, because
+ * the count is a prop — hooks in a loop is a rule waiting to be broken by
+ * whoever changes the default.
+ */
+function Pill({
+  index,
+  count,
+  engine,
+  width,
+  minHeight,
+  maxHeight,
+  color,
+}: {
+  index: number;
+  count: number;
+  engine: Engine;
+  width: number;
+  minHeight: number;
+  maxHeight: number;
+  color: string;
+}) {
+  const style = useAnimatedStyle(() => {
+    /*
+     * Each capsule runs at its own tempo and phase, hashed off its index. Give
+     * them one tempo and they rise and fall as a block, which reads as a
+     * loading bar; detune them and the group reads as something responding to a
+     * voice, even though they all follow the same level.
+     */
+    const rate = 2.2 + hashD(index, 1.7) * 2.6;
+    const phase = hashD(index, 5.1) * Math.PI * 2;
+    const wobble = 0.55 + 0.45 * Math.sin(engine.clock.value * rate + phase);
+
+    // The middle capsules lead. A voice meter with a flat profile looks like a
+    // level indicator; a slight hump looks like a mouth.
+    const centre = count > 1 ? 1 - Math.abs((index / (count - 1)) * 2 - 1) : 1;
+    const shape = 0.68 + 0.32 * centre;
+
+    const value = clamp01(Math.max(FLOOR, engine.energy.value) * wobble * shape);
+    return { height: minHeight + (maxHeight - minHeight) * value };
+  });
+
+  return (
+    <Animated.View
+      style={[
+        { width, borderRadius: width / 2, backgroundColor: color },
+        style,
+      ]}
+    />
+  );
+}
+
+function PillsWave({
+  engine,
+  count,
+  barWidth,
+  barGap,
+  height,
+  color,
+}: {
+  engine: Engine;
+  count: number;
+  barWidth: number;
+  barGap: number;
+  height: number;
+  color: string;
+}) {
+  // Never shorter than a circle: a capsule squashed past its own width stops
+  // being a capsule.
+  const minHeight = barWidth * 1.35;
+
+  return (
+    <View
+      style={{ height, columnGap: barGap }}
+      className="flex-row items-center justify-center"
+    >
+      {Array.from({ length: count }, (_unused, index) => (
+        <Pill
+          key={index}
+          index={index}
+          count={count}
+          engine={engine}
+          width={barWidth}
+          minHeight={minHeight}
+          maxHeight={height}
+          color={color}
+        />
+      ))}
+    </View>
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/* bars                                                                       */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * One bar's height, 0–1, from whichever source is driving this wave.
+ *
+ * Pulled out of the drawing loop because two paths walk the same bars — the
+ * played part of a recording and the rest of it — and a bar has to come out
+ * identical in both or the split shows as a step.
+ */
+function barValue(
+  i: number,
+  count: number,
+  scrolling: boolean,
+  supplied: number[],
+  history: number[],
+  clock: number,
+  energy: number
+): number {
+  'worklet';
+  if (scrolling) {
+    // The buffer fills from empty, so the newest sample sits at the trailing
+    // edge from the first frame rather than the wave sliding in from nowhere.
+    const offset = i - (count - history.length);
+    return offset >= 0 ? (history[offset] ?? 0) : 0;
+  }
+  if (supplied.length) {
+    // Real bands, resampled to the bar count — an analysis rarely hands back
+    // exactly as many numbers as there are bars, and a recorded waveform never
+    // does.
+    return supplied[Math.floor((i / count) * supplied.length)] ?? 0;
+  }
+  const rate = 2.1 + hashD(i, 1.3) * 2.9;
+  const phase = hashD(i, 4.7) * Math.PI * 2;
+  const wobble = 0.5 + 0.5 * Math.sin(clock * rate + phase);
+  const centre = count > 1 ? Math.sin((Math.PI * (i + 0.5)) / count) : 1;
+  return energy * wobble * (0.45 + 0.55 * centre);
+}
+
+/** Ink left on the part of a recording that has not played yet. */
+const UNPLAYED_OPACITY = 0.3;
+
+/**
+ * The stroke a wave is painted with, when it is not one flat colour.
+ *
+ * One definition covers both jobs, because they are the same object: a run of
+ * colour stops across the width, optionally pinned to transparent at each end.
+ * Doing the edge fade this way rather than as an overlay in the background
+ * colour is what lets a wave sit on a card, a bubble or a photograph — an
+ * overlay only disappears against the one surface it was told about.
+ */
+function WaveGradient({
+  id,
+  colors,
+  fade,
+  edge,
+}: {
+  id: string;
+  colors: readonly string[];
+  fade: boolean;
+  edge: number;
+}) {
+  const stops = colors.length ? colors : ['#000000'];
+  const span = fade ? 1 - edge * 2 : 1;
+  const from = fade ? edge : 0;
+
+  const nodes: ReactElement[] = [];
+  if (fade) nodes.push(<Stop key="fade-start" offset="0" stopColor={stops[0]} stopOpacity="0" />);
+  stops.forEach((stop, index) => {
+    const at = stops.length > 1 ? from + (index / (stops.length - 1)) * span : from;
+    nodes.push(
+      <Stop key={index} offset={String(at)} stopColor={stop} stopOpacity="1" />
+    );
+  });
+  if (fade) {
+    nodes.push(
+      <Stop key="fade-end" offset="1" stopColor={stops[stops.length - 1]} stopOpacity="0" />
+    );
+  }
+
+  return (
+    <Defs>
+      {/* Built as a list rather than inline, because the stop count varies with
+          the palette and with whether the ends are faded. */}
+      <SvgGradient id={id} x1="0" y1="0" x2="1" y2="0">
+        {nodes}
+      </SvgGradient>
+    </Defs>
+  );
+}
+
+function BarsWave({
+  engine,
+  bands,
+  progress,
+  hasProgress,
+  count,
+  barWidth,
+  height,
+  width,
+  centered,
+  scrolling,
+  stroke,
+  trackStroke,
+  defs,
+}: {
+  engine: Engine;
+  bands: SharedValue<number[]>;
+  progress: SharedValue<number>;
+  hasProgress: boolean;
+  count: number;
+  barWidth: number;
+  height: number;
+  width: number;
+  centered: boolean;
+  scrolling: boolean;
+  stroke: string;
+  /** Explicit colour for the unplayed part, if the caller set one. */
+  trackStroke: string | null;
+  defs: ReactNode;
+}) {
+  /*
+   * Two paths, split at the playhead: the bars behind it keep full ink, the
+   * ones ahead are dimmed. It is two animated props a frame rather than one,
+   * and still nothing per bar — which is the point of drawing bars as a stroked
+   * path in the first place.
+   *
+   * With no `progress` the first path takes everything and the second is empty,
+   * so a live meter and a voice note run the same code.
+   */
+  const drawSegment = (played: boolean) => () => {
+    'worklet';
+    const step = count > 1 ? (width - barWidth) / (count - 1) : 0;
+    const span = height - barWidth;
+    const supplied = bands.value;
+    const history = engine.samples.value;
+    const head = hasProgress ? clamp01(progress.value) * count : count;
+    let d = '';
+
+    for (let i = 0; i < count; i++) {
+      // The playhead cuts between bars, not through one: a bar is either
+      // played or it is not, which is what makes the fill land on a beat.
+      const isPlayed = i + 0.5 <= head;
+      if (isPlayed !== played) continue;
+
+      const value = barValue(
+        i,
+        count,
+        scrolling,
+        supplied,
+        history,
+        engine.clock.value,
+        engine.energy.value
+      );
+      const length = span * clamp01(Math.max(FLOOR, value));
+      const x = q(barWidth / 2 + i * step);
+      if (centered) {
+        const half = length / 2;
+        d += `M${x} ${q(height / 2 - half)}L${x} ${q(height / 2 + half)}`;
+      } else {
+        d += `M${x} ${q(height - barWidth / 2)}L${x} ${q(height - barWidth / 2 - length)}`;
+      }
+    }
+
+    return { d };
+  };
+
+  const playedProps = useAnimatedProps(drawSegment(true));
+  const restProps = useAnimatedProps(drawSegment(false));
+
+  return (
+    <Svg width={width} height={height}>
+      {defs}
+      <AnimatedPath
+        animatedProps={restProps}
+        stroke={trackStroke ?? stroke}
+        // A track colour of its own is drawn as given; without one, the unplayed
+        // part is the same ink turned down.
+        strokeOpacity={trackStroke ? 1 : hasProgress ? UNPLAYED_OPACITY : 1}
+        strokeWidth={barWidth}
+        strokeLinecap="round"
+        fill="none"
+      />
+      <AnimatedPath
+        animatedProps={playedProps}
+        stroke={stroke}
+        strokeWidth={barWidth}
+        strokeLinecap="round"
+        fill="none"
+      />
+    </Svg>
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/* line                                                                       */
+/* -------------------------------------------------------------------------- */
+
+/** Points along the wave. Enough to read as a curve, few enough to rebuild. */
+const LINE_POINTS = 56;
+
+function LineWave({
+  engine,
+  width,
+  height,
+  strokeWidth,
+  stroke,
+  defs,
+}: {
+  engine: Engine;
+  width: number;
+  height: number;
+  strokeWidth: number;
+  stroke: string;
+  defs: ReactNode;
+}) {
+  const animatedProps = useAnimatedProps(() => {
+    const mid = height / 2;
+    const amplitude = (height / 2 - strokeWidth) * clamp01(Math.max(FLOOR, engine.energy.value));
+    const t = engine.clock.value;
+    let d = '';
+
+    for (let i = 0; i <= LINE_POINTS; i++) {
+      const f = i / LINE_POINTS;
+      const x = f * width;
+      /*
+       * Three waves at unrelated wavelengths, tapered to nothing at both ends.
+       * The taper is what makes it a wave and not a rope: the line leaves and
+       * meets the edges flat, so there is no hard stop where it is cut off.
+       */
+      const taper = Math.sin(Math.PI * f);
+      const y =
+        mid -
+        amplitude *
+          taper *
+          (0.62 * Math.sin(f * 12.6 - t * 3.1) +
+            0.26 * Math.sin(f * 21.4 - t * 4.7 + 1.1) +
+            0.12 * Math.sin(f * 33.2 - t * 2.3));
+      d += `${i === 0 ? 'M' : 'L'}${q(x)} ${q(y)}`;
+    }
+
+    return { d };
+  });
+
+  return (
+    <Svg width={width} height={height}>
+      {defs}
+      <AnimatedPath
+        animatedProps={animatedProps}
+        stroke={stroke}
+        strokeWidth={strokeWidth}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        fill="none"
+      />
+    </Svg>
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/* ambient                                                                    */
+/* -------------------------------------------------------------------------- */
+
+/** A theme token name — `--color-info` — rather than a literal colour. */
+const isToken = (value: string | undefined): value is string =>
+  typeof value === 'string' && value.startsWith('--');
+
+/** `useCSSVariable` can hand back a non-string when a variable is unset. */
+const asString = (value: unknown): string | undefined =>
+  typeof value === 'string' && value.length > 0 ? value : undefined;
+
+/** Turns any resolved colour into the same colour at a given alpha. */
+function withAlpha(color: string, alpha: number): string {
+  if (color.startsWith('#')) {
+    const hex = color.slice(1);
+    const full =
+      hex.length === 3
+        ? hex
+            .split('')
+            .map((c) => c + c)
+            .join('')
+        : hex.slice(0, 6);
+    const r = parseInt(full.slice(0, 2), 16);
+    const g = parseInt(full.slice(2, 4), 16);
+    const b = parseInt(full.slice(4, 6), 16);
+    if (Number.isNaN(r + g + b)) return color;
+    return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+  }
+
+  const channels = color.match(/rgba?\(([^)]+)\)/)?.[1];
+  if (channels) {
+    const [r, g, b] = channels.split(',').map((part) => part.trim());
+    return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+  }
+
+  return color;
+}
+
+/**
+ * The glow that fills a screen: a bloom rising off the bottom edge and a rim of
+ * light around the rest.
+ *
+ * Both breathe on the level rather than only fading in and out — a glow that
+ * changes opacity alone reads as a screen dimming, where one that also grows
+ * reads as something in the room getting louder.
+ */
+function AmbientWave({
+  engine,
+  color,
+  bloomColors,
+  radius,
+}: {
+  engine: Engine;
+  color: string;
+  /** Bottom to top. Two or more colours make the bloom a gradient of its own. */
+  bloomColors: readonly string[] | null;
+  radius: number;
+}) {
+  const bloom = useAnimatedStyle(() => {
+    const e = clamp01(Math.max(FLOOR, engine.energy.value));
+    const breath = 0.94 + 0.06 * Math.sin(engine.clock.value * 1.7);
+    return {
+      opacity: 0.25 + 0.75 * e,
+      transform: [{ scaleY: (0.72 + 0.4 * e) * breath }],
+    };
+  });
+
+  const rim = useAnimatedStyle(() => {
+    const e = clamp01(Math.max(FLOOR, engine.energy.value));
+    return { opacity: 0.12 + 0.5 * e };
+  });
+
+  /*
+   * The bloom fades in from nothing at the top whatever it is made of, so a
+   * supplied palette is ramped rather than used flat — a gradient that starts
+   * at full strength has a visible edge across the middle of the screen.
+   */
+  const ramp: string[] = bloomColors?.length
+    ? [
+        withAlpha(bloomColors[0]!, 0),
+        ...bloomColors.map((stop, index) =>
+          withAlpha(stop, 0.16 + (0.34 * index) / Math.max(1, bloomColors.length - 1))
+        ),
+      ]
+    : [withAlpha(color, 0), withAlpha(color, 0.16), withAlpha(color, 0.5)];
+
+  return (
+    <View
+      pointerEvents="none"
+      style={[StyleSheet.absoluteFill, { borderRadius: radius, overflow: 'hidden' }]}
+    >
+      {/* The rim, as three rings of falling alpha. Three flat borders read as a
+          soft edge where one crisp border reads as a frame around the screen. */}
+      <Animated.View style={[StyleSheet.absoluteFill, rim]}>
+        {[0, 1, 2].map((ring) => (
+          <View
+            key={ring}
+            style={[
+              StyleSheet.absoluteFill,
+              {
+                margin: ring * 3,
+                borderRadius: Math.max(0, radius - ring * 3),
+                borderWidth: 3,
+                borderColor: withAlpha(color, 0.4 - ring * 0.13),
+              },
+            ]}
+          />
+        ))}
+      </Animated.View>
+
+      <Animated.View
+        style={[
+          { position: 'absolute', left: 0, right: 0, bottom: 0, height: '55%' },
+          // Anchored to the bottom so growing pushes the bloom up the screen
+          // rather than pulling it off the edge.
+          { transformOrigin: 'bottom' },
+          bloom,
+        ]}
+      >
+        <LinearGradient
+          colors={ramp as [string, string, ...string[]]}
+          start={{ x: 0.5, y: 0 }}
+          end={{ x: 0.5, y: 1 }}
+          style={StyleSheet.absoluteFill}
+        />
+      </Animated.View>
+    </View>
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/* Component                                                                  */
+/* -------------------------------------------------------------------------- */
+
+/** Per-variant geometry, so a bare `<Soundwave variant="bars" />` looks right. */
+const DEFAULTS: Record<
+  SoundwaveVariant,
+  { bars: number; barWidth: number; barGap: number; height: number }
+> = {
+  pills: { bars: 4, barWidth: 28, barGap: 10, height: 96 },
+  bars: { bars: 40, barWidth: 3, barGap: 3, height: 56 },
+  line: { bars: 0, barWidth: 3, barGap: 0, height: 72 },
+  ambient: { bars: 0, barWidth: 0, barGap: 0, height: 0 },
+};
+
+export interface SoundwaveProps extends Omit<ViewProps, 'children'> {
+  className?: string;
+  /**
+   * Which look to draw: `pills` for a few capsules over a microphone button,
+   * `bars` for a metering strip, `line` for a travelling wave, `ambient` for a
+   * glow that fills its parent.
+   */
+  variant?: SoundwaveVariant;
+  /**
+   * What the app is doing. With no `level` supplied this picks the motion the
+   * wave runs on its own; it always sets what a screen reader announces.
+   */
+  state?: SoundwaveState;
+  /**
+   * Input level, 0–1, from your own recorder's metering. Pass a `SharedValue`
+   * to keep updates off the JS thread entirely. Omit it and the wave animates
+   * plausible motion for the current `state`.
+   */
+  level?: number | SharedValue<number>;
+  /**
+   * Per-band levels, 0–1 each, for `bars` in `static` mode when the app has a
+   * real frequency analysis — or the stored shape of a finished recording.
+   * Resampled to the bar count, and drawn still rather than animated.
+   */
+  levels?: number[];
+  /**
+   * Playback position through a recording, 0–1. Bars behind it keep full ink
+   * and the rest are dimmed, which is the voice-note progress bar. `bars` only,
+   * and it goes with `levels` — a recording has a fixed shape to play through.
+   */
+  progress?: number | SharedValue<number>;
+  /** How many capsules (`pills`) or bars (`bars`) to draw. */
+  bars?: number;
+  /** Capsule width, or bar stroke width. Also the stroke width of `line`. */
+  barWidth?: number;
+  /** Gap between capsules. `bars` spaces itself evenly across the width. */
+  barGap?: number;
+  /** Drawing height. `ambient` ignores it and fills its parent. */
+  height?: number;
+  /**
+   * `static` gives every bar a band of the current level; `scrolling` keeps a
+   * history that slides across, newest at the trailing edge. `bars` only.
+   */
+  mode?: 'static' | 'scrolling';
+  /** Grow bars from the middle out rather than up from the baseline. */
+  centered?: boolean;
+  /** Fade the wave out at both ends, so it does not stop at a hard edge. */
+  fadeEdges?: boolean;
+  /** Multiplier on the incoming level, applied before it is clamped to 1. */
+  sensitivity?: number;
+  /** Multiplier on the wave's own tempo, including how fast history scrolls. */
+  speed?: number;
+  /**
+   * Ink. Takes a colour — `#f97316`, `rgba(…)` — or a **theme token name**,
+   * `color="--color-info"`, which resolves against the active theme and follows
+   * it into dark mode.
+   *
+   * Left unset, a wave inside a surface that publishes a foreground (a chat
+   * bubble, a button) is drawn in that foreground, and anywhere else in
+   * `--color-foreground` — or `--color-info` for `ambient`.
+   */
+  color?: string;
+  /**
+   * Colour across the wave instead of one flat ink: two or more colours spread
+   * left to right, or ramped up from the bottom edge for `ambient`. Literal
+   * colours only — for a themed one, resolve the tokens with `useCSSVariable`
+   * and pass the result.
+   */
+  gradient?: readonly string[];
+  /**
+   * Colour of the part of a recording that has not played yet. Defaults to the
+   * ink at low opacity, which is right for most surfaces; set it when you want
+   * the track to read as its own thing. `bars` with `progress`.
+   */
+  trackColor?: string;
+  /** Freeze on the current frame. */
+  paused?: boolean;
+  /** Corner radius `ambient` traces. Match it to the screen it sits on. */
+  radius?: number;
+  /** Overrides the per-state default announced to screen readers. */
+  accessibilityLabel?: string;
+}
+
+export function Soundwave({
+  className,
+  variant = 'pills',
+  state = 'listening',
+  level,
+  levels,
+  progress,
+  bars,
+  barWidth,
+  barGap,
+  height,
+  mode = 'static',
+  centered = true,
+  fadeEdges,
+  sensitivity = 1,
+  speed = 1,
+  color,
+  gradient,
+  trackColor,
+  paused = false,
+  radius = 44,
+  accessibilityLabel,
+  style,
+  ...props
+}: SoundwaveProps) {
+  const defaults = DEFAULTS[variant];
+  const count = bars ?? defaults.bars;
+  const stroke = barWidth ?? defaults.barWidth;
+  const gap = barGap ?? defaults.barGap;
+  const box = height ?? defaults.height;
+  const scrolling = variant === 'bars' && mode === 'scrolling';
+  const fade = fadeEdges ?? (variant === 'line' || scrolling);
+
+  const foreground = useCSSVariable('--color-foreground');
+  const info = useCSSVariable('--color-info');
+  /*
+   * A token name is resolved here rather than by the caller, so `color` and
+   * `trackColor` can be written the way the rest of the library is themed —
+   * `--color-info` instead of a hex someone has to keep in step with the theme.
+   */
+  const colorToken = useCSSVariable(isToken(color) ? color : '--color-foreground');
+  const trackToken = useCSSVariable(isToken(trackColor) ? trackColor : '--color-foreground');
+  const themed = variant === 'ambient' ? info : foreground;
+  /*
+   * A wave inside a coloured surface has to be drawn in that surface's
+   * foreground, not the page's: a sent chat bubble is painted in the primary
+   * colour, and in most themes the primary colour *is* the text colour — so a
+   * wave that resolved `--color-foreground` for itself would be invisible on
+   * the one screen it is most likely to appear on. Surfaces already publish
+   * their readable foreground for icons; a wave is ink for the same reason.
+   *
+   * `ambient` opts out: it is a glow behind a whole screen, not ink on a
+   * surface, and it wants its own colour.
+   */
+  const inherited = useIconColor();
+  const surface = variant === 'ambient' ? undefined : inherited;
+  const explicit = isToken(color) ? asString(colorToken) : color;
+  const ink = explicit ?? surface ?? asString(themed) ?? '#0a0a0a';
+  const track = isToken(trackColor) ? asString(trackToken) : trackColor;
+
+  /*
+   * A recording drawn from `levels` has no motion in it: every bar comes from
+   * the stored shape, so the clock advances a frame nobody reads. A transcript
+   * can hold twenty voice notes, and twenty idle frame callbacks is twenty too
+   * many — so a supplied waveform stops the engine, and `progress` still
+   * redraws it, because that is a shared value of its own.
+   */
+  const stillWaveform = variant === 'bars' && !scrolling && (levels?.length ?? 0) > 0;
+
+  const engine = useEngine({
+    level,
+    state,
+    sensitivity,
+    speed,
+    paused: paused || stillWaveform,
+    history: scrolling ? count : 0,
+  });
+
+  // Supplied bands are copied into a shared value so the drawing worklet has a
+  // single place to read from, whichever way the level arrived.
+  const bands = useSharedValue<number[]>([]);
+  useEffect(() => {
+    bands.value = levels ?? [];
+  }, [levels, bands]);
+
+  const playhead = useNumberSource(progress);
+
+  // `bars` and `line` are drawn to the width they are given, which is only
+  // known after layout — a metering strip is nearly always as wide as its row.
+  const [measured, setMeasured] = useState(0);
+  const onLayout = (event: LayoutChangeEvent) => {
+    const next = Math.round(event.nativeEvent.layout.width);
+    if (next !== measured) setMeasured(next);
+  };
+
+  // Two Defs in one tree cannot share an id, and a screen can hold more than
+  // one wave.
+  const gradientId = `panelui-soundwave-${useId().replace(/[^a-zA-Z0-9]/g, '')}`;
+
+  /*
+   * A gradient and an edge fade are the same object — colour stops across the
+   * width — so one definition serves both, and a wave that needs neither is
+   * painted with a flat colour and no `Defs` at all.
+   */
+  const ramp = gradient?.length ? gradient : null;
+  const needsDefs = fade || (ramp !== null && ramp.length > 1);
+  const paint = needsDefs ? `url(#${gradientId})` : ink;
+  const defs = needsDefs ? (
+    <WaveGradient
+      id={gradientId}
+      colors={ramp ?? [ink]}
+      fade={fade}
+      edge={variant === 'line' ? 0.18 : 0.12}
+    />
+  ) : null;
+
+  let content: ReactNode = null;
+  if (variant === 'pills') {
+    content = (
+      <PillsWave
+        engine={engine}
+        count={count}
+        barWidth={stroke}
+        barGap={gap}
+        height={box}
+        color={ink}
+      />
+    );
+  } else if (variant === 'ambient') {
+    content = (
+      <AmbientWave engine={engine} color={ink} bloomColors={ramp} radius={radius} />
+    );
+  } else if (measured > 0) {
+    content =
+      variant === 'bars' ? (
+        <BarsWave
+          engine={engine}
+          bands={bands}
+          progress={playhead}
+          hasProgress={progress !== undefined}
+          count={count}
+          barWidth={stroke}
+          height={box}
+          width={measured}
+          centered={centered}
+          scrolling={scrolling}
+          stroke={paint}
+          trackStroke={track ?? null}
+          defs={defs}
+        />
+      ) : (
+        <LineWave
+          engine={engine}
+          width={measured}
+          height={box}
+          strokeWidth={stroke}
+          stroke={paint}
+          defs={defs}
+        />
+      );
+  }
+
+  return (
+    <View
+      {...props}
+      onLayout={variant === 'bars' || variant === 'line' ? onLayout : undefined}
+      pointerEvents={variant === 'ambient' ? 'none' : props.pointerEvents}
+      accessibilityRole="image"
+      accessibilityLabel={accessibilityLabel ?? STATE_LABEL[state]}
+      className={cn(
+        variant === 'ambient' ? 'absolute inset-0' : 'w-full justify-center',
+        className
+      )}
+      style={[variant === 'ambient' ? null : { height: box }, style]}
+    >
+      {content}
+    </View>
+  );
+}
+
+Soundwave.displayName = 'Soundwave';