@kitn.ai/ui 0.19.0 → 0.20.0

package/src/elements/define.tsx

@@ -78,6 +78,17 @@ export interface WebComponentContext<E = Record<string, unknown>> {
    * convention). Methods are attached when the facade renders (on element upgrade).
    */
   expose: (methods: Record<string, (...args: never[]) => unknown>) => void;
+  /**
+   * Whether the element should currently render its dark-mode look --
+   * exactly the SAME resolved value that already drives the `.dark` class
+   * every facade's content sits inside (not a second computation of the
+   * `theme='light'|'dark'|'auto'` rule; see `createDarkMode` above). Most
+   * facades never need this directly, since the injected kit CSS already
+   * flips its custom properties under `.dark`. It exists for content that
+   * cannot read CSS at all -- e.g. a WebGL shader baking a colour choice
+   * into a GLSL uniform, which is why `kai-audio-visualizer` reads it.
+   */
+  dark: () => boolean;
 }
 
 /** camelCase prop name → kebab-case attribute (`hoverCard` → `hover-card`). */
@@ -223,7 +234,7 @@ export function defineWebComponent<P extends Record<string, unknown>, E = Record
         <div classList={{ dark: isDark() }} style={{ display: 'contents', color: 'var(--color-foreground)' }}>
           <div ref={portalNode} />
           <ChatConfig portalMount={portalNode}>
-            {Facade(props as unknown as P, { element, dispatch, flag, expose })}
+            {Facade(props as unknown as P, { element, dispatch, flag, expose, dark: isDark })}
           </ChatConfig>
         </div>
       </>

package/src/elements/element-manifest.json

@@ -19,6 +19,7 @@
     "kai-suggestions": "prompt-suggestions",
     "kai-file-upload": "file-upload",
     "kai-voice-input": "voice-input",
+    "kai-audio-visualizer": "audio-visualizer",
     "kai-loader": "loader",
     "kai-text-shimmer": "text-shimmer",
     "kai-image": "image",
@@ -137,6 +138,9 @@
     "voice-input": [
       "kai-voice-input"
     ],
+    "audio-visualizer": [
+      "kai-audio-visualizer"
+    ],
     "loader": [
       "kai-loader"
     ],

package/src/elements/element-meta.json

@@ -456,6 +456,176 @@
       }
     ]
   },
+  {
+    "tag": "kai-audio-visualizer",
+    "className": "KaiAudioVisualizerElement",
+    "displayName": "AudioVisualizer",
+    "props": [
+      {
+        "name": "variant",
+        "type": "undefined | string",
+        "optional": true,
+        "scalar": true,
+        "description": "Look to render: `bar` (default), `grid`, `radial`, `wave`, `aurora`, `custom`. `aura` is accepted as a LiveKit-markup alias for `aurora`. Attribute: `variant`.",
+        "default": "'bar'",
+        "displayType": "undefined | string"
+      },
+      {
+        "name": "state",
+        "type": "undefined | string",
+        "optional": true,
+        "scalar": true,
+        "description": "`idle` (default), `connecting`, `listening`, `thinking`, `speaking`, `disconnected` (connection down: the dead, flat look). LiveKit's room-lifecycle state names are accepted as aliases. Attribute: `state`.",
+        "default": "'idle'",
+        "displayType": "undefined | string"
+      },
+      {
+        "name": "size",
+        "type": "undefined | string",
+        "optional": true,
+        "scalar": true,
+        "description": "`icon` | `sm` | `md` (default) | `lg` | `xl`. Attribute: `size`.",
+        "default": "'md'",
+        "displayType": "undefined | string"
+      },
+      {
+        "name": "barCount",
+        "type": "undefined | number",
+        "optional": true,
+        "scalar": true,
+        "description": "Bars to draw. Bar and radial only. Attribute: `bar-count`.",
+        "displayType": "undefined | number"
+      },
+      {
+        "name": "count",
+        "type": "undefined | number",
+        "optional": true,
+        "scalar": true,
+        "description": "Grid only: rows and columns of the (always square) grid. Attribute: `count`.",
+        "displayType": "undefined | number"
+      },
+      {
+        "name": "radius",
+        "type": "undefined | number",
+        "optional": true,
+        "scalar": true,
+        "description": "Radial only: ring distance from center, in px. Attribute: `radius`.",
+        "displayType": "undefined | number"
+      },
+      {
+        "name": "spread",
+        "type": "undefined | number",
+        "optional": true,
+        "scalar": true,
+        "description": "Grid only: ring distance for the connecting animation, in cells. Attribute: `spread`.",
+        "displayType": "undefined | number"
+      },
+      {
+        "name": "interval",
+        "type": "undefined | number",
+        "optional": true,
+        "scalar": true,
+        "description": "Grid only: ms between scripted frames. Attribute: `interval`.",
+        "displayType": "undefined | number"
+      },
+      {
+        "name": "color",
+        "type": "undefined | string",
+        "optional": true,
+        "scalar": true,
+        "description": "CSS color for the geometry, overriding the inherited `currentColor`. Attribute: `color`.",
+        "displayType": "undefined | string"
+      },
+      {
+        "name": "complexity",
+        "type": "undefined | number",
+        "optional": true,
+        "scalar": true,
+        "description": "Shader variants only: pattern density, 0..1. Attribute: `complexity`.",
+        "displayType": "undefined | number"
+      },
+      {
+        "name": "label",
+        "type": "undefined | string",
+        "optional": true,
+        "scalar": true,
+        "description": "Setting this makes the element an announced image (`role=\"img\"`) instead of decorative (`aria-hidden`). Attribute: `label`.",
+        "displayType": "undefined | string"
+      },
+      {
+        "name": "stream",
+        "type": "undefined | MediaStream",
+        "optional": true,
+        "scalar": false,
+        "description": "Live microphone or WebRTC audio to analyze. JS property only.",
+        "displayType": "undefined | MediaStream"
+      },
+      {
+        "name": "audioElement",
+        "type": "undefined | HTMLMediaElement",
+        "optional": true,
+        "scalar": false,
+        "description": "An `<audio>` or `<video>` element to tap for its audio. JS property only.",
+        "displayType": "undefined | HTMLMediaElement"
+      },
+      {
+        "name": "bands",
+        "type": "undefined | number[]",
+        "optional": true,
+        "scalar": false,
+        "description": "Pre-computed levels, 0..1. Set this and no AudioContext is ever built, which is what keeps headless/SSR rendering and browser-speech-synthesis playback (which exposes no audio node) free of Web Audio entirely. JS property only. A new array reference is required for each update; mutating the existing array in place will not re-render.",
+        "displayType": "undefined | number[]"
+      },
+      {
+        "name": "shader",
+        "type": "undefined | { fragment: string; uniforms?: undefined | Record<string, { type: \"1f\" | \"1i\" | \"1fv\" | \"2f\" | \"3f\" | \"3fv\" | \"4f\" | \"4fv\" | \"Matrix2fv\" | \"Matrix3fv\" | \"Matrix4fv\"; value: number | number[] }> }",
+        "optional": true,
+        "scalar": false,
+        "description": "Custom fragment shader for `variant=\"custom\"`. JS property only.",
+        "displayType": "undefined | { fragment: string; uniforms?: undefined | Record<string, { type: \"1f\" | \"1i\" | \"1fv\" | \"2f\" | \"3f\" | \"3fv\" | \"4f\" | \"4fv\" | \"Matrix2fv\" | \"Matrix3fv\" | \"Matrix4fv\"; value: number | number[] }> }"
+      },
+      {
+        "name": "animateWhenNotVisible",
+        "type": "undefined | false | true",
+        "optional": true,
+        "scalar": true,
+        "description": "Shader variants only: keep animating while scrolled off screen. Off by default, which stops drawing and releases the WebGL context until the element comes back (browsers ration contexts to roughly 16 a page). Does not override `prefers-reduced-motion`. Attribute: `animate-when-not-visible`.",
+        "displayType": "undefined | false | true"
+      }
+    ],
+    "events": [],
+    "methods": [],
+    "composedFrom": [
+      {
+        "name": "AudioVisualizer",
+        "group": "Components",
+        "storyId": "solid-advanced-elements-audiovisualizer--docs"
+      }
+    ],
+    "tokens": [],
+    "parts": [
+      {
+        "name": "bar",
+        "doc": "A single bar in the `bar` variant, or a single spoke in the `radial` variant. Also carries `data-kai-index` and `data-kai-highlighted` (\"true\"/\"false\") for use inside the shadow root; to style the lit state from OUTSIDE, combine with the `highlighted` part below rather than an attribute selector.",
+        "recipe": "kai-audio-visualizer::part(bar) { border-radius: 2px }\nkai-audio-visualizer::part(bar highlighted) { background: var(--brand) }"
+      },
+      {
+        "name": "cell",
+        "doc": "A single dot in the `grid` variant. Also carries `data-kai-index` and `data-kai-highlighted` (\"true\"/\"false\") for use inside the shadow root; to style the lit state from OUTSIDE, combine with the `highlighted` part below rather than an attribute selector.",
+        "recipe": "kai-audio-visualizer::part(cell) { border-radius: 9999px }\nkai-audio-visualizer::part(cell highlighted) { background: var(--brand) }"
+      },
+      {
+        "name": "highlighted",
+        "doc": "A second part TOKEN present on a `bar` or `cell` exactly when the sequencer or live audio has it lit, not a standalone styleable element. Combine it in the same `::part()` argument: `::part(bar highlighted)` or `::part(cell highlighted)`. This is the external equivalent of the internal `data-kai-highlighted=\"true\"` attribute, which a `::part()` selector cannot reach (an attribute selector cannot follow a pseudo-element).",
+        "recipe": "kai-audio-visualizer::part(bar highlighted) { background: var(--brand) }\nkai-audio-visualizer::part(cell highlighted) { background: var(--brand) }"
+      },
+      {
+        "name": "canvas",
+        "doc": "The WebGL canvas backing the `wave` and `aurora` variants. Restyle its size or radius, or layer a mask/filter, from outside.",
+        "recipe": "kai-audio-visualizer::part(canvas) { border-radius: 0.75rem }"
+      }
+    ]
+  },
   {
     "tag": "kai-avatar",
     "className": "KaiAvatarElement",

package/src/elements/element-types.d.ts

@@ -164,6 +164,43 @@ export interface KaiAttachmentsElement extends HTMLElement {
   emptyText?: string;
 }
 
+export interface KaiAudioVisualizerElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** Look to render: `bar` (default), `grid`, `radial`, `wave`, `aurora`, `custom`. `aura` is accepted as a LiveKit-markup alias for `aurora`. Attribute: `variant`. */
+  variant?: string;
+  /** `idle` (default), `connecting`, `listening`, `thinking`, `speaking`, `disconnected` (connection down: the dead, flat look). LiveKit's room-lifecycle state names are accepted as aliases. Attribute: `state`. */
+  state?: string;
+  /** `icon` | `sm` | `md` (default) | `lg` | `xl`. Attribute: `size`. */
+  size?: string;
+  /** Bars to draw. Bar and radial only. Attribute: `bar-count`. */
+  barCount?: number;
+  /** Grid only: rows and columns of the (always square) grid. Attribute: `count`. */
+  count?: number;
+  /** Radial only: ring distance from center, in px. Attribute: `radius`. */
+  radius?: number;
+  /** Grid only: ring distance for the connecting animation, in cells. Attribute: `spread`. */
+  spread?: number;
+  /** Grid only: ms between scripted frames. Attribute: `interval`. */
+  interval?: number;
+  /** CSS color for the geometry, overriding the inherited `currentColor`. Attribute: `color`. */
+  color?: string;
+  /** Shader variants only: pattern density, 0..1. Attribute: `complexity`. */
+  complexity?: number;
+  /** Setting this makes the element an announced image (`role="img"`) instead of decorative (`aria-hidden`). Attribute: `label`. */
+  label?: string;
+  /** Live microphone or WebRTC audio to analyze. JS property only. */
+  stream?: MediaStream;
+  /** An `<audio>` or `<video>` element to tap for its audio. JS property only. */
+  audioElement?: HTMLMediaElement;
+  /** Pre-computed levels, 0..1. Set this and no AudioContext is ever built, which is what keeps headless/SSR rendering and browser-speech-synthesis playback (which exposes no audio node) free of Web Audio entirely. JS property only. A new array reference is required for each update; mutating the existing array in place will not re-render. */
+  bands?: number[];
+  /** Custom fragment shader for `variant="custom"`. JS property only. */
+  shader?: { fragment: string; uniforms?: Record<string, { type: "1f" | "1i" | "1fv" | "2f" | "3f" | "3fv" | "4f" | "4fv" | "Matrix2fv" | "Matrix3fv" | "Matrix4fv"; value: number | number[] }> };
+  /** Shader variants only: keep animating while scrolled off screen. Off by default, which stops drawing and releases the WebGL context until the element comes back (browsers ration contexts to roughly 16 a page). Does not override `prefers-reduced-motion`. Attribute: `animate-when-not-visible`. */
+  animateWhenNotVisible?: boolean;
+}
+
 export interface KaiAvatarElement extends HTMLElement {
   /** Color mode (`auto` follows prefers-color-scheme). */
   theme?: 'light' | 'dark' | 'auto';
@@ -1366,6 +1403,7 @@ declare global {
     'kai-agent-card': KaiAgentCardElement;
     'kai-artifact': KaiArtifactElement;
     'kai-attachments': KaiAttachmentsElement;
+    'kai-audio-visualizer': KaiAudioVisualizerElement;
     'kai-avatar': KaiAvatarElement;
     'kai-badge': KaiBadgeElement;
     'kai-button': KaiButtonElement;

package/src/elements/register-impl.ts

@@ -27,6 +27,7 @@ import './chat-scope-picker';
 import './prompt-suggestions';
 import './file-upload';
 import './voice-input';
+import './audio-visualizer';
 // Phase 4 — indicators & leaves
 import './loader';
 import './text-shimmer';

package/src/elements/slots.ts

@@ -558,6 +558,40 @@ export const THREAD_SLOTS: SlotDef[] = [
   { name: 'empty', mode: 'replace', doc: 'Custom zero-state rendered in the message area while the thread is empty; replaces the built-in default.' },
 ];
 
+/** Styleable `::part`s of `<kai-audio-visualizer>`. Every DOM variant (`bar`,
+ *  `grid`, `radial`) shares the `bar`/`cell` markup pattern; the shader variants
+ *  (`wave`, `aurora`) share the `canvas` part. Lit items ALSO carry the
+ *  `highlighted` part token, so `::part(bar highlighted)`/`::part(cell
+ *  highlighted)` selects only the lit ones. `::part(bar)[data-kai-highlighted=
+ *  "true"]` looks plausible but is invalid CSS: a CSS attribute selector
+ *  cannot follow a pseudo-element (`CSS.supports(selector(...))` returns
+ *  `false` for it in Chromium, and `insertRule` throws). `data-kai-index` /
+ *  `data-kai-highlighted` still exist on the element for consumers reading
+ *  them from INSIDE the shadow root or via the Solid render-prop; they are
+ *  just not reachable from an external `::part()` selector. */
+export const AUDIO_VISUALIZER_PARTS: PartDef[] = [
+  {
+    name: 'bar',
+    doc: 'A single bar in the `bar` variant, or a single spoke in the `radial` variant. Also carries `data-kai-index` and `data-kai-highlighted` ("true"/"false") for use inside the shadow root; to style the lit state from OUTSIDE, combine with the `highlighted` part below rather than an attribute selector.',
+    recipe: 'kai-audio-visualizer::part(bar) { border-radius: 2px }\nkai-audio-visualizer::part(bar highlighted) { background: var(--brand) }',
+  },
+  {
+    name: 'cell',
+    doc: 'A single dot in the `grid` variant. Also carries `data-kai-index` and `data-kai-highlighted` ("true"/"false") for use inside the shadow root; to style the lit state from OUTSIDE, combine with the `highlighted` part below rather than an attribute selector.',
+    recipe: 'kai-audio-visualizer::part(cell) { border-radius: 9999px }\nkai-audio-visualizer::part(cell highlighted) { background: var(--brand) }',
+  },
+  {
+    name: 'highlighted',
+    doc: 'A second part TOKEN present on a `bar` or `cell` exactly when the sequencer or live audio has it lit, not a standalone styleable element. Combine it in the same `::part()` argument: `::part(bar highlighted)` or `::part(cell highlighted)`. This is the external equivalent of the internal `data-kai-highlighted="true"` attribute, which a `::part()` selector cannot reach (an attribute selector cannot follow a pseudo-element).',
+    recipe: 'kai-audio-visualizer::part(bar highlighted) { background: var(--brand) }\nkai-audio-visualizer::part(cell highlighted) { background: var(--brand) }',
+  },
+  {
+    name: 'canvas',
+    doc: 'The WebGL canvas backing the `wave` and `aurora` variants. Restyle its size or radius, or layer a mask/filter, from outside.',
+    recipe: 'kai-audio-visualizer::part(canvas) { border-radius: 0.75rem }',
+  },
+];
+
 export const ELEMENT_COMPOSITION: Record<string, ElementComposition> = {
   'kai-chat': { slots: CHAT_SLOTS, parts: CHAT_PARTS },
   'kai-command': { parts: COMMAND_PARTS },
@@ -597,6 +631,7 @@ export const ELEMENT_COMPOSITION: Record<string, ElementComposition> = {
   'kai-search': { parts: SEARCH_PARTS },
   'kai-kbd': { parts: KBD_PARTS },
   'kai-editable-label': { parts: EDITABLE_LABEL_PARTS },
+  'kai-audio-visualizer': { parts: AUDIO_VISUALIZER_PARTS },
 };
 
 /**

package/src/primitives/audio-bands.ts

@@ -0,0 +1,174 @@
+/**
+ * Pure reductions from AnalyserNode output to the numbers a visualizer draws.
+ *
+ * Ported from livekit/components-js `packages/react/src/hooks/useTrackVolume.ts`
+ * (Apache License 2.0). Both the dB normalization curve AND the band split
+ * are carried over so our output matches theirs frame for frame: the split
+ * is upstream's linear-proportional chunking (their PR #1265). An interim
+ * revision here spaced the buckets geometrically to serve a wide raw-mic
+ * window; both reverted together -- see `reduceToBands` below and the
+ * DEFAULTS docstring in use-audio-analysis.ts for the full story.
+ */
+
+/** dB floor of the normalization curve. Below this reads as silence. */
+const MIN_DB = -100;
+/** dB ceiling. Above this saturates. */
+const MAX_DB = -10;
+
+/**
+ * Map one `getFloatFrequencyData` decibel value to 0..1.
+ *
+ * The `sqrt` at the end is a perceptual curve, not a normalization step: it
+ * lifts quiet detail so low-level audio still moves the bars visibly.
+ */
+export function normalizeDb(value: number): number {
+  if (value === -Infinity) return 0;
+  const clamped = Math.max(MIN_DB, Math.min(MAX_DB, value));
+  return Math.sqrt(1 - (clamped * -1) / 100);
+}
+
+/**
+ * Average a slice of the frequency spectrum into `bands` buckets.
+ *
+ * `loPass` / `hiPass` are BIN INDICES relative to `fftSize`, not frequencies.
+ * Upstream's naming is misleading; the behavior is a plain array slice.
+ *
+ * Bucket edges are LINEAR-PROPORTIONAL across `[loPass, hiPass]` -- upstream
+ * LiveKit's own distribution (`useMultibandTrackVolume`, useTrackVolume.ts
+ * lines 141-153, rewritten to proportional chunking by their PR #1265): each
+ * band averages an equal consecutive run of bins, `floor(i * total / bands)`
+ * to `floor((i + 1) * total / bands)`, and a run that comes out empty reads
+ * 0 (their `chunkLength === 0` branch). With the default window's 100 bins
+ * and 5 bands, that is 20 bins averaged per band -- the averaging itself is
+ * part of upstream's idle stillness, diluting any single flickering bin
+ * 20:1 (noise-floor diagnosis, table B).
+ *
+ * An interim revision spaced these buckets geometrically so that a wide
+ * raw-microphone window (bins 4-120) kept its upper buckets alive. That
+ * concentrated the noisiest few low bins into band 0 undiluted, which the
+ * centre-out mirror below then promoted to the CENTRE element -- the
+ * measured core of the "white noise when the mic is on" defect (diagnosis
+ * table B: geometric band 0 idled at 0.52 on real room tone where this
+ * split reads 0.32 over the same wide window, and exactly 0 over the
+ * default one). Reverted to upstream's split when the default window
+ * reverted; the mirror stays, it is orthogonal.
+ */
+export function reduceToBands(
+  freq: Float32Array,
+  bands: number,
+  loPass: number,
+  hiPass: number,
+): number[] {
+  // `slice` clamps both ends into the buffer and yields an empty window when
+  // hiPass <= loPass -- every bucket then reads 0 below, no special case.
+  const window = freq.slice(Math.max(0, loPass), Math.max(0, hiPass));
+  const total = window.length;
+  const out: number[] = [];
+
+  for (let i = 0; i < bands; i++) {
+    const start = Math.floor((i * total) / bands);
+    const end = Math.floor(((i + 1) * total) / bands);
+    if (end <= start) {
+      out.push(0);
+      continue;
+    }
+    let sum = 0;
+    for (let j = start; j < end; j++) sum += normalizeDb(window[j] as number);
+    out.push(sum / (end - start));
+  }
+
+  return out;
+}
+
+/** Root-mean-square of `getByteFrequencyData`, scaled to 0..1. */
+export function reduceToVolume(bytes: Uint8Array): number {
+  if (bytes.length === 0) return 0;
+  let sum = 0;
+  for (let i = 0; i < bytes.length; i++) {
+    const a = bytes[i] as number;
+    sum += a * a;
+  }
+  return Math.sqrt(sum / bytes.length) / 255;
+}
+
+/**
+ * Resize a caller-supplied band array to exactly `count` entries. Extra values
+ * are dropped; a short array repeats its last value (0 when empty) so a
+ * consumer passing the wrong length gets a sane picture instead of holes.
+ */
+export function normalizeVolumeBands(bands: number[], count: number): number[] {
+  if (bands.length === count) return bands;
+  if (bands.length > count) return bands.slice(0, count);
+  const last = bands[bands.length - 1] ?? 0;
+  return [...bands, ...new Array(count - bands.length).fill(last)];
+}
+
+/**
+ * Maps a smaller, ordered set of "half" band values (index 0 = loudest,
+ * typically lowest frequency) onto `count` positions laid out in a straight
+ * line -- a row of bars, or a row of grid columns -- centre-outward and
+ * mirrored: band 0 lands on the centre (an odd `count`) or the centre PAIR
+ * (an even one, both positions sharing band 0), band 1 on the pair either
+ * side of that, and so on outward to the two ends.
+ *
+ * Every scripted state in this component is already centre-oriented
+ * (`listening` blinks the centre bar, `connecting` sweeps inward from both
+ * ends, `thinking` sweeps the middle row) -- `speaking` ramping left to
+ * right, because it fed the analyser's raw band order straight across, was
+ * the one state inconsistent with that. This closes that gap.
+ *
+ * `halfBands` should have exactly `Math.ceil(count / 2)` entries -- the
+ * caller is responsible for requesting that many bands from
+ * `useAudioAnalysis`, matching counts exactly rather than leaning on
+ * `normalizeVolumeBands`'s pad-by-repeating-the-last-value, which would
+ * produce a subtly wrong (not obviously broken) shape here. A shorter
+ * `halfBands` still degrades sanely: the outermost positions repeat the last
+ * value available rather than reading `undefined`.
+ */
+export function mirrorBandsCenterOut(halfBands: number[], count: number): number[] {
+  const center = (count - 1) / 2;
+  const out: number[] = new Array(count);
+  for (let i = 0; i < count; i++) {
+    const ring = Math.floor(Math.abs(i - center));
+    out[i] = halfBands[Math.min(ring, halfBands.length - 1)] ?? 0;
+  }
+  return out;
+}
+
+/**
+ * Maps a smaller, ordered set of "half" band values onto `count` positions
+ * arranged around a RING (radial's spokes), mirrored left-right across a
+ * single vertical axis rather than fanned from a linear centre: index 0 and
+ * index `count / 2` (for an even `count`; radial warns when `count` is not
+ * divisible by 4, so this is the common case) are each their own fixed
+ * point of the reflection and both land band 0, and every other index pairs
+ * with its mirror partner at `count - i`, sharing a band.
+ *
+ * Radial's own geometry (`variant-radial.tsx`) places index 0 at the
+ * BOTTOM of the ring (`rotate(0) translateY(radius)`, and CSS rotation is
+ * clockwise for a positive angle), so band 0 (usually the loudest) reads at
+ * the bottom, fading toward the top -- not band 0 at both the top AND the
+ * bottom, which would need a second, horizontal mirror axis on top of this
+ * one. Chosen over that fuller symmetry because it reuses the exact same
+ * `Math.ceil(count / 2)` band request as the linear mirror above (one rule
+ * for every variant, not a radial-specific band count), and because the
+ * task's request was "spikes vary in length, not moving as one" -- this
+ * already delivers that. If bottom-loud/top-quiet reads wrong in practice,
+ * swapping to true 4-fold symmetry is a self-contained change here, not
+ * elsewhere.
+ *
+ * For an even `count`, the antipodal index (`count / 2`) needs one more
+ * distinct band than the linear mirror does (rings run 0..`count / 2`, not
+ * 0..`count / 2 - 1`) -- with only `Math.ceil(count / 2)` bands available,
+ * that one index clamps to the same value as its nearest neighbour rather
+ * than getting a unique band. A minor, deliberate simplification for the
+ * same one-rule-for-every-variant reason above.
+ */
+export function mirrorBandsAroundRing(halfBands: number[], count: number): number[] {
+  const out: number[] = new Array(count);
+  for (let i = 0; i < count; i++) {
+    const ring = Math.min(i, count - i);
+    out[i] = halfBands[Math.min(ring, halfBands.length - 1)] ?? 0;
+  }
+  return out;
+}