@kitn.ai/ui 0.18.2 → 0.20.0

package/LICENSE

@@ -19,3 +19,9 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+---
+
+This package includes third-party components under other licenses, including
+files licensed under the Apache License 2.0. See the NOTICE file for the
+per-file attribution and license terms that apply to them.

package/NOTICE

@@ -0,0 +1,54 @@
+@kitn.ai/ui
+Copyright (c) kitn.ai
+
+This product includes software developed at LiveKit
+(https://github.com/livekit/components-js), licensed under the
+Apache License, Version 2.0.
+
+The following files are ports or verbatim copies of LiveKit work:
+
+  src/primitives/audio-bands.ts
+      from packages/react/src/hooks/useTrackVolume.ts
+  src/primitives/visualizer-sequences.ts
+      from packages/shadcn/hooks/agents-ui/use-agent-audio-visualizer-{bar,grid,radial,wave}.ts
+  src/components/audio-visualizer/sizes.ts
+  src/components/audio-visualizer/variant-bar.tsx
+  src/components/audio-visualizer/variant-grid.tsx
+  src/components/audio-visualizer/variant-radial.tsx
+  src/components/audio-visualizer/variant-wave.tsx
+      from packages/shadcn/components/agents-ui/agent-audio-visualizer-{bar,grid,radial,wave}.tsx
+  src/components/audio-visualizer/wave.glsl.ts
+      verbatim, from agent-audio-visualizer-wave.tsx
+
+The following file contains no ported code, but takes animation values from
+LiveKit work:
+
+  src/components/audio-visualizer/variant-aurora.tsx
+      from packages/shadcn/hooks/agents-ui/use-agent-audio-visualizer-aura.ts
+      (Apache-2.0). Its per-state animation targets -- speed, scale,
+      amplitude, frequency and brightness per agent state, the listening
+      spring (1.0s, bounce 0.35), and the tween and pulse cadences -- match
+      that hook, as do the analyser settings (fftSize 512,
+      smoothingTimeConstant 0.55). The implementation is our own; the
+      values are attributed here.
+
+You may obtain a copy of the Apache License 2.0 at
+http://www.apache.org/licenses/LICENSE-2.0
+
+The following file is ORIGINAL work and is NOT derived from LiveKit or any
+third party:
+
+  src/components/audio-visualizer/aurora.glsl.ts
+
+The variant-aurora.tsx attribution above does not extend to this file. That
+attribution covers per-state animation values only; none of it reaches the
+rendering. LiveKit's own aura shader is separately licensed, was never read,
+and contributed nothing here.
+
+This file's own provenance (whether it may itself later be attributed,
+relicensed, or otherwise handled) is a separate, pending decision and is not
+resolved by this NOTICE.
+
+The full clean-room derivation record for that file, including its evidence
+index, is at docs/provenance/aurora-clean-room.md in the source repository
+(https://github.com/kitn-ai/ui).

package/dist/components/audio-visualizer/audio-visualizer.voice-fixture.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A real recorded voice, baked into a short seamless loop for the
+ * `speaking` tiles in the stories -- the genuine article, not a generator.
+ *
+ * Real voice, recorded by the project owner: "This is a test, testing one
+ * two three, hello world." Captured mono at 44.1kHz, then extracted through
+ * the component's ALIGNED analysis chain -- the same values upstream
+ * LiveKit's components run: AnalyserNode fftSize 2048 / smoothing 0.8,
+ * window bins 100-200 (the components' own loPass/hiPass; see DEFAULTS in
+ * primitives/use-audio-analysis.ts), `reduceToBands`' linear-proportional
+ * split as it exists in THIS tree, ~32ms cadence. Third bake of this
+ * fixture: the first was 5 linear bands over a wide raw-mic window
+ * (bins 4-120), the second 3 geometric bands over the same wide window;
+ * both predate the pipeline realignment that reverted window and split to
+ * upstream's.
+ *
+ * GAIN: the raw take is boosted 8x (+18dB) through a GainNode before the
+ * analysers -- an honest approximation of capture-side AGC, which every
+ * real input to the aligned window gets (LiveKit captures local mics with
+ * autoGainControl on; the mic stories request the same) but this recording,
+ * made raw, never had. Un-gained, quiet natural-volume speech sits at or
+ * under the -100dB floor across bins 100-200 and the loop's time-averaged
+ * band profile comes out flat-to-inverted (edges louder than centre);
+ * measured at +18dB the bake hits the live-AGC targets: speech-active
+ * volume through the aligned byte path (minDecibels -100 / maxDecibels
+ * -80) averages 0.73, no speech frame reads all-zero bands, and the
+ * time-averaged mirrored md profile is centre-strictly-max --
+ * [0.41, 0.42, 0.44, 0.42, 0.41]. The trade, recorded honestly: +18dB also
+ * lifts part of the room tone over the floor, so rest frames idle near
+ * [0.2, 0.04, 0] instead of the exact zeros an un-gained bake would show
+ * -- which is also what a real AGC mic does between words.
+ *
+ * 3 bands per frame is HALF width on purpose: `Math.ceil(count / 2)`, the
+ * exact band count the component itself requests at `md` before mirroring
+ * (see `bandCount()` in index.tsx). The `bands` prop is a raw passthrough
+ * by contract, so the stories mirror these half bands out to the full
+ * element count themselves through `mirrorBandsCenterOut` /
+ * `mirrorBandsAroundRing` -- the same primitives the live-audio path runs.
+ * See `useVoiceBands` in the stories file.
+ *
+ * Trimmed to the same 196-frame window (~6.4s) as the previous bake:
+ * about half a second of rest before the first word, just under a second
+ * after the last, and BOTH natural pauses in the middle -- one short gap
+ * around "test," / "testing", the longer one after "three," before
+ * "hello" -- since those are what prove the visualizer falls back to rest
+ * and recovers. Loops by wrapping frame 195 back to frame 0. Re-verified
+ * at the aligned values: the endpoints differ by 0.034 pre-quantization
+ * ([0.22,0.05,0] vs [0.2,0.03,0] after it), which sits between the median
+ * (0.025) and p90 (0.053) of ADJACENT quiet frames' natural motion at this
+ * gain -- the wrap step is indistinguishable from ordinary idle flicker.
+ * (The previous bake's endpoints quantized identical, but only because its
+ * un-gained rest frames were all zeros -- trivial, not preserved here.)
+ *
+ * Quantized to 2 decimals. Playback treats the cadence as a flat
+ * `VOICE_FRAME_MS`; the capture's real ticks land at 32-33ms (setTimeout
+ * jitter), a ~2% difference nobody can see. Body is ~3.8KB.
+ */
+export declare const VOICE_FRAME_MS = 32;
+export declare const VOICE_BANDS: readonly (readonly number[])[];

package/dist/components/audio-visualizer/aurora.glsl.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Aurora ("veil") fragment shader.
+ *
+ * ORIGINAL WORK for @kitn.ai/ui. Written for Task 14 of
+ * docs/superpowers/plans/2026-08-07-audio-visualizers.md, from two inputs
+ * only:
+ *   1. .superpowers/sdd/2026-08-07-audio-visualizers/reference/aura-prototype/
+ *      lk-aura-factsheet.md -- a two-team clean-room functional spec (facts
+ *      and mathematics; no code and no expression, and no identifiers
+ *      beyond the public prop names and the uniform inventory, both
+ *      disclosed in that document's own preamble) covering LiveKit's
+ *      public "aura" visualizer look. What was checked, and how, is in
+ *      `docs/provenance/aurora-clean-room.md` section 4.
+ *   2. The adopted prototype's own `aura-proto.html` (mode 3, "veil"), which
+ *      was itself implemented from that fact sheet by an author who never
+ *      saw LiveKit's source.
+ *
+ * This file is NOT derived from, and was not written with reference to,
+ * LiveKit's `agent-audio-visualizer-aura.tsx` or the aura GLSL inlined in
+ * it. That component is Polyform Non-Resale 1.0.0, (c) UNCRN LLC -- a
+ * license incompatible with publishing this package -- and was never
+ * opened. The fact sheet's numbers and formulas (independently re-derived
+ * and checked by hand below, not copied) are what stand in for it.
+ *
+ * Its sibling `use-agent-audio-visualizer-aura.ts`, the DRIVING hook, is a
+ * separate matter: that file is Apache-2.0 (repo license, no Polyform
+ * header) and carries only the per-state behaviour, not the shader. It
+ * contributes nothing to this file; the state targets it describes live in
+ * `variant-aurora.tsx`.
+ *
+ * The construction: 36 phase-offset copies of one ring, each pushed through
+ * the same 4-octave directional-sine warp cascade, fused into soft veils by
+ * an analytic neighbour-distance blur -- see `auroraWarp` and the strand
+ * loop in `mainImage`.
+ *
+ * One deliberate deviation from the fact sheet: section 1 states the
+ * shipped output is "hotter than premultiplied" (written RGB may exceed
+ * written alpha), and section 4 confirms the light-mode branch never
+ * multiplies RGB by alpha or brightness at all. That is exactly the pattern
+ * that produces dark fringes on translucent edges once composited with a
+ * `premultipliedAlpha: true` canvas context over a light page background --
+ * see the doc on `ShaderCanvas`'s `fragment` prop. This port keeps every
+ * other number and formula but replaces the final write with true
+ * premultiplied output, `fragColor = vec4(rgb * alpha, alpha)`.
+ *
+ * PARITY RE-TUNE (campaign task #6). A pixel-level behavioral audit
+ * (examples/internal/livekit-parity scripts/aurora-audit.mjs) measured the
+ * rendered output against the reference and this file was re-tuned to the
+ * MEASURED targets -- numbers from screenshots and Rob's reference
+ * recording, never from restricted source. Four departures from the
+ * original fact-sheet pipeline, all clean-room rendering choices:
+ *   1. Wind direction + solid-body rotation: the octave phase runs on
+ *      NEGATIVE tau (the audit measured our lobes drifting counter-
+ *      clockwise where the reference turns clockwise, ~+13..+20 deg/s when
+ *      speaking), plus a per-state `uRotation` trim of the coordinate
+ *      frame so each state's measured rotation lands on its reference
+ *      value (see `auroraTargets` in variant-aurora.tsx).
+ *   2. Dark tonemap is chroma-preserving with a steeper knee (11x/(1+11x)
+ *      on the max channel, rescaled) plus an HSV shape-up: hue +0.013
+ *      turns, saturation scaled by (1.02 + 0.35 * value) capped at 0.98.
+ *      Rendered targets: hue ~197.5deg, saturation ~0.95 rising with
+ *      brightness, never white (the audit measured the original
+ *      per-channel 4x/(1+4x) map desaturating to ~0.72 and dragging hue
+ *      toward green).
+ *   3. Brightness is applied through strongly compressive curves
+ *      ((b/1.5)^0.07 on colour, 0.97*(b/1.5)^0.09 on alpha, with a
+ *      smoothstep alpha knee): the thinking/connecting pulse DRIVES
+ *      0.5..2.5 but must RENDER inside roughly 0.5..0.65 mean brightness
+ *      (the reference holds 0.53..0.65 where the linear map swung
+ *      0.16..0.83 and blinked the ring out entirely at pulse minima).
+ *   4. Edge falloff tightened (exp(2.3*spacing), was exp(2*spacing)) and
+ *      made asymmetric: the OUTER side of the ring renders at 0.66x the
+ *      inner width -- the reference's outer edge is consistently sharper
+ *      than its inner one at every volume.
+ *
+ * Uniforms are declared by ShaderCanvas. Do not declare them here.
+ *
+ * Uniform contract (see the module doc in the Task 14 report for the full
+ * per-state table):
+ *   uColor       vec3  -- accent RGB, 0..1.
+ *   uIntensity   float -- brightness/gain, fact sheet section 5's
+ *                         "brightness" column directly (roughly 0.5..2.5,
+ *                         NOT the 0..1 convention other variants use).
+ *   uSpeed       float -- octave phase rate in rad/s, fact sheet section
+ *                         5's `S / 20` directly (roughly 0.5..3.5).
+ *   uComplexity  float -- warp spatial-frequency parameter, fact sheet
+ *                         section 5's `freqParam` directly (roughly
+ *                         0.4..1.25, default 0.5); mapped internally to
+ *                         F = 2 + 13 * uComplexity.
+ *   uAmplitude   float -- warp displacement amplitude, fact sheet section
+ *                         5's `amplitude` column directly (roughly
+ *                         0.5..1.2, default 1.0).
+ *   uScale       float -- ring radius, fraction of half-canvas, fact sheet
+ *                         section 5's `scale` column directly (0.2..0.3).
+ *                         The caller is responsible for folding in the
+ *                         instant voice-driven growth
+ *                         (`0.2 + 0.2 * volume`, speaking state only,
+ *                         fact sheet section 5) before setting this --
+ *                         the shader does not read a separate volume
+ *                         uniform to avoid double-applying it.
+ *   uTheme       float -- < 0.5 selects the dark colour pipeline, >= 0.5
+ *                         the light one (fact sheet section 4). This is a
+ *                         genuine branch in the math, not just a
+ *                         compositing background -- set it from the kit's
+ *                         active theme, not a fixed constant.
+ *   uRotation    float -- solid-body rotation rate of the whole figure,
+ *                         rad/s, positive = CLOCKWISE on screen. A
+ *                         parity-calibrated per-state trim on top of the
+ *                         wind's own drift (see the module doc above and
+ *                         `auroraTargets`); the caller pins it to 0 under
+ *                         reduced motion, like uSpeed.
+ */
+declare const _default: "\nconst float PI = 3.14159265359;\n// Strand phase span: 0.5 + pi (fact sheet section 2's \"sigma\", the\n// midpoint of the interval [1, 2*pi] with the interpolation knob fixed\n// at 0.5).\nconst float STRAND_SIGMA = 0.5 + PI;\nconst int STRAND_COUNT = 36;\n\n// 4-octave directional-sine warp cascade. M0 and the per-octave rotation B\n// (cos 0.6, sin 0.8, an exact ~53.13 degree rotation) are fact sheet\n// section 2's stated matrices; M1/M2/M3 = B composed with the previous\n// octave's matrix, and each v_k is the first row of M_k. Hand-derived and\n// checked against the fact sheet's own listed v_0..v_3 below, not copied\n// from any source.\nconst mat2 WARP_M0 = mat2(0.6, 0.25, -0.25, 0.9);\nconst mat2 WARP_M1 = mat2(0.16, 0.63, -0.87, 0.34);\nconst mat2 WARP_M2 = mat2(-0.408, 0.506, -0.794, -0.492);\nconst mat2 WARP_M3 = mat2(-0.6496, -0.0228, -0.0828, -0.9304);\nconst vec2 WARP_V0 = vec2(0.600, -0.250);\nconst vec2 WARP_V1 = vec2(0.160, -0.870);\nconst vec2 WARP_V2 = vec2(-0.408, -0.794);\nconst vec2 WARP_V3 = vec2(-0.650, -0.083);\n\n// Displaces p through all 4 octaves. Octave k's phase carries k*tau, so\n// octave 0 is static in time and octave 3 moves fastest -- fine\n// corrugation slides across coarse folds, which reads as flowing wind\n// (fact sheet section 2, \"Mechanism of the fold / wind\").\nvec2 auroraWarp(vec2 p, float phi, float tau, float freq, float amp) {\n  vec2 x = p;\n  float f = freq;\n  float a = amp;\n\n  vec2 q = WARP_M0 * x;\n  vec2 w = sin(f * q + vec2(phi));\n  x += (a / f) * WARP_V0 * w;\n  f *= 1.4;\n  a *= 1.0 + 0.1 * (max(w.x, w.y) - 1.0);\n\n  q = WARP_M1 * x;\n  w = sin(f * q + vec2(tau + phi));\n  x += (a / f) * WARP_V1 * w;\n  f *= 1.4;\n  a *= 1.0 + 0.1 * (max(w.x, w.y) - 1.0);\n\n  q = WARP_M2 * x;\n  w = sin(f * q + vec2(2.0 * tau + phi));\n  x += (a / f) * WARP_V2 * w;\n  f *= 1.4;\n  a *= 1.0 + 0.1 * (max(w.x, w.y) - 1.0);\n\n  q = WARP_M3 * x;\n  w = sin(f * q + vec2(3.0 * tau + phi));\n  x += (a / f) * WARP_V3 * w;\n\n  return x;\n}\n\nvec3 auroraRgb2Hsv(vec3 c) {\n  vec4 K = vec4(0.0, -1.0 / 3.0, 2.0 / 3.0, -1.0);\n  vec4 p = mix(vec4(c.bg, K.wz), vec4(c.gb, K.xy), step(c.b, c.g));\n  vec4 q = mix(vec4(p.xyw, c.r), vec4(c.r, p.yzx), step(p.x, c.r));\n  float d = q.x - min(q.w, q.y);\n  return vec3(abs(q.z + (q.w - q.y) / (6.0 * d + 1.0e-10)), d / (q.x + 1.0e-10), q.x);\n}\n\nvec3 auroraHsv2Rgb(vec3 c) {\n  vec4 K = vec4(1.0, 2.0 / 3.0, 1.0 / 3.0, 3.0);\n  vec3 p = abs(fract(c.xxx + K.xyz) * 6.0 - K.www);\n  return c.z * mix(K.xxx, clamp(p - K.xxx, 0.0, 1.0), c.y);\n}\n\nvoid mainImage(out vec4 fragColor, in vec2 fragCoord) {\n  // Fact sheet section 2: u in [0,1]^2, centered point p = u - 0.5, no\n  // aspect correction -- the element is forced square by CSS, so this is\n  // only correct on a square canvas (true for every audio-visualizer size).\n  vec2 uv = fragCoord / iResolution.xy;\n  vec2 p = uv - 0.5;\n\n  // Solid-body rotation of the sampling frame (module doc, departure 1).\n  // gl_FragCoord's y-up frame is mirrored against the screen's y-down one,\n  // so the sign here is what makes positive uRotation read CLOCKWISE on\n  // screen -- verified empirically against the audit's estimator (which\n  // measures +10 for uRotation = +10 deg/s with the wind frozen).\n  float rotA = -uRotation * iTime;\n  float rc = cos(rotA);\n  float rs = sin(rotA);\n  p = mat2(rc, -rs, rs, rc) * p;\n\n  // Negative tau: time-reversing the octave phases flips the wind's\n  // emergent angular drift from counter-clockwise (measured on the original)\n  // to the reference's clockwise, without touching any static property --\n  // lobes, radii, spectra are distribution-identical (module doc,\n  // departure 1).\n  float tau = -iTime * uSpeed;\n  float freq = max(2.0 + 13.0 * uComplexity, 1.0);\n  float amp = uAmplitude;\n  float ringRadius = uScale;\n\n  vec3 hsv = auroraRgb2Hsv(uColor);\n  // Chain-seed strand, phase -1/36 NOT scaled by STRAND_SIGMA (fact sheet\n  // section 2), so inter-strand spacing is defined for strand 1 too.\n  vec2 prevStrand = auroraWarp(p, -1.0 / float(STRAND_COUNT), tau, freq, amp);\n\n  vec3 accum = vec3(0.0);\n  for (int j = 1; j <= STRAND_COUNT; j++) {\n    float frac = float(j) / float(STRAND_COUNT);\n    float phi = frac * STRAND_SIGMA;\n    vec2 strand = auroraWarp(p, phi, tau, freq, amp);\n\n    // Signed distance to the (warped) ring, per strand: negative inside,\n    // positive outside -- the sign feeds the asymmetric edge width below.\n    float sd = length(strand) - ringRadius;\n    float dist = abs(sd);\n    // Inter-strand spacing through the chain: an analytic blur exactly\n    // proportional to how far this strand's warp has drifted from its\n    // neighbour's. Fanned regions (large spacing) fuse into soft veils;\n    // bunched regions (small spacing) stay crisp -- this is what turns 36\n    // discrete rings into an aurora (fact sheet section 2). The 2.3 growth\n    // rate (fact sheet's own is 2.0) and the 0.66x outer-side factor are\n    // the parity edge calibration: the reference holds a 10-90% rise of\n    // ~6-10px(2x) with the OUTER edge always the sharper of the two\n    // (module doc, departure 4).\n    float spacing = length(strand - prevStrand);\n    float edgeWidth = 0.01 + max(exp(2.3 * spacing) - 1.0, 0.001);\n    edgeWidth *= mix(1.0, 0.66, step(0.0, sd));\n    float coverage = 1.0 - smoothstep(0.0, 1.0, dist / edgeWidth);\n\n    // Fixed hue drift across the strand fan, matching the fact sheet's\n    // documented colorShift default (0.05 turns at weight 0.3, i.e. 0.015\n    // turns end to end); earliest strand shifts most.\n    vec3 strandColor = auroraHsv2Rgb(vec3(fract(hsv.x + (1.0 - frac) * 0.015), hsv.y, hsv.z));\n    accum += coverage * strandColor;\n    prevStrand = strand;\n  }\n\n  // Mean soft coverage across all 36 strands (fact sheet section 2's image\n  // accumulator I). The inverse-distance glow accumulator G is omitted: the\n  // fact sheet states its gain ships as 0, so it contributes nothing.\n  vec3 image = accum / float(STRAND_COUNT);\n\n  // Deterministic per-pixel dither, +/- 1/510, identical on all channels\n  // (fact sheet section 3). Kept as a plain vec3 offset, not pre-mixed into\n  // the image accumulator, so each branch can add it at the point the fact\n  // sheet actually specifies (see the dark branch below).\n  float n = fract(sin(dot(fragCoord, vec2(12.9898, 78.233))) * 43758.5453);\n  vec3 dither = vec3((n - 0.5) / 255.0);\n\n  float brightness = uIntensity;\n  vec3 rgb;\n  float alpha;\n\n  if (uTheme < 0.5) {\n    // Dark pipeline, parity-calibrated (module doc, departures 2 + 3).\n    // RGB1 = 1.2 * I, THEN add dither (fact sheet order: pre-gain first so\n    // the dither's written amplitude stays +/- 1/510), then floor at 0 --\n    // a negative dither on a near-black pixel would otherwise be blown up\n    // by the chroma-preserving rescale's division right below.\n    vec3 x1 = max(1.2 * image + dither, 0.0);\n\n    // Chroma-preserving tonemap: knee the MAX channel (11x/(1+11x) -- a\n    // steeper knee than the fact sheet's per-channel 4x/(1+4x)) and rescale\n    // the vector, so ribbon cores land on a stable brightness level largely\n    // independent of how thin the veils have fanned (the audit measured the\n    // per-channel map crushing spread-out states to ~half the reference's\n    // rendered brightness) while hue and saturation pass through untouched\n    // for the HSV shape-up to own.\n    float mxc = max(x1.r, max(x1.g, x1.b));\n    float tmMax = 11.0 * mxc / (1.0 + 11.0 * mxc);\n    vec3 tm = x1 * (tmMax / max(mxc, 1.0e-5));\n\n    // Rendered-colour calibration: hue +0.013 turns (audit target\n    // ~197.5deg for the default accent), saturation proportional to the\n    // caller's own (a desaturated accent stays desaturated) but rising\n    // with the pixel's value and capped at 0.98 -- Rob's reference:\n    // saturation RISES with brightness, and nothing is ever white.\n    vec3 hv = auroraRgb2Hsv(tm);\n    hv.x = fract(hv.x + 0.013);\n    hv.y = min(hv.y * (1.02 + 0.35 * hv.z), 0.98);\n    tm = auroraHsv2Rgb(hv);\n\n    // Brightness compression (departure 3): uIntensity DRIVES 0.5..2.5 at\n    // the thinking/connecting pulse but must RENDER inside roughly\n    // 0.5..0.65 mean brightness, never dropping the ring below visibility.\n    // Two compressive powers (colour flatter than alpha) plus a smoothstep\n    // alpha knee that lifts ribbon cores to full opacity while cutting the\n    // dim tails -- which is also what keeps the centre transparent and the\n    // edges crisp. max(brightness, 0.05) only guards pow() against a\n    // (contractually impossible) zero or negative uniform.\n    float bVal = pow(max(brightness, 0.05) / 1.5, 0.07);\n    float bAlpha = 0.97 * pow(max(brightness, 0.05) / 1.5, 0.09);\n    float luma = dot(tm, vec3(0.299, 0.587, 0.114));\n    // Clamped to [0,1] before the premultiply below, mirroring the light\n    // branch, so rgb * alpha <= alpha stays enforced for every input.\n    rgb = clamp(tm * bVal, 0.0, 1.0);\n    alpha = clamp(smoothstep(0.0, 0.50, luma) * bAlpha, 0.0, 1.0);\n  } else {\n    // Light pipeline (fact sheet section 4): RGB1 = I, then add dither;\n    // brightness curve on vector length, hue direction kept, saturation\n    // extrapolated 3x about gray.\n    vec3 x1 = image + dither;\n    float mag = length(x1);\n    vec3 dir = x1 / max(mag, 1.0e-5);\n    float mag2 = 2.0 * mag / (1.0 + 2.0 * mag);\n    vec3 x2 = dir * mag2;\n    float gray = dot(x2, vec3(0.2, 0.5, 0.1));\n    rgb = clamp(vec3(gray) + 3.0 * (x2 - vec3(gray)), 0.0, 1.0);\n    alpha = clamp(mag2 * clamp(brightness, 1.0, 2.0), 0.0, 1.0);\n  }\n\n  // PREMULTIPLIED output. Both branches above clamp their natural rgb to\n  // [0,1] before this line, which is what makes rgb * alpha <= alpha\n  // (componentwise) a property the code enforces unconditionally, not one\n  // that happens to hold for the inputs this was tested against. See the\n  // module doc above for why this departs from the fact sheet's own\n  // (deliberately non-premultiplied) pipeline.\n  fragColor = vec4(rgb * alpha, alpha);\n}\n";
+export default _default;

package/dist/components/audio-visualizer/index.d.ts

@@ -0,0 +1,155 @@
+import { Accessor, JSX } from 'solid-js';
+import { VariantProps } from './variant-bar';
+import { VisualizerSize } from './sizes';
+import { UniformType } from './shader-canvas';
+export type VisualizerVariant = 'bar' | 'grid' | 'radial' | 'wave' | 'aurora' | 'custom';
+export declare function normalizeVariant(input: string | undefined): VisualizerVariant;
+/** A consumer-supplied fragment shader, for `variant="custom"`. */
+export interface ShaderSpec {
+    /**
+     * GLSL source defining `mainImage(out vec4 fragColor, in vec2 fragCoord)`.
+     *
+     * MUST output premultiplied colour: `fragColor = vec4(rgb * alpha, alpha);`,
+     * never `vec4(rgb, alpha)`. The canvas composites using the browser's
+     * default `premultipliedAlpha: true`; a translucent edge written the
+     * natural (straight-alpha) way gets a dark fringe where it meets a light
+     * page background.
+     */
+    fragment: string;
+    /**
+     * Custom uniforms. The canvas DECLARES these for you; declaring them in the
+     * shader too is a compile error.
+     *
+     * `type` is narrowed to `UniformType`, not a bare string: an unrecognized
+     * type here is caught by TypeScript for a TS-authored `shader` prop, before
+     * it can produce `uniform undefined <name>;` in the assembled source (a
+     * confusing compile error). A consumer reaching this through the
+     * `<kai-audio-visualizer>` custom element or an attribute-driven wrapper
+     * bypasses this check entirely (it is JS at that boundary, not TS) --
+     * `variant-custom.tsx`'s `customUniforms` re-checks `type` at runtime for
+     * exactly that reason.
+     */
+    uniforms?: Record<string, {
+        type: UniformType;
+        value: number | number[];
+    }>;
+}
+export interface AudioVisualizerProps {
+    variant?: VisualizerVariant;
+    state?: string;
+    size?: VisualizerSize;
+    barCount?: number;
+    /** Grid only: rows and columns of the square grid. */
+    count?: number;
+    /** Radial only: distance from center, in px. */
+    radius?: number;
+    /** Grid only: ring distance for the connecting animation, in cells. */
+    spread?: number;
+    /** Grid only: ms between scripted frames. */
+    interval?: number;
+    color?: string;
+    /** Shader variants only: pattern density, 0..1. */
+    complexity?: number;
+    /** Setting this makes the element an announced image instead of decorative. */
+    label?: string;
+    stream?: MediaStream;
+    audioElement?: HTMLMediaElement;
+    /** Pre-computed levels. Set this and no AudioContext is ever constructed. */
+    bands?: number[];
+    /**
+     * Custom fragment shader for `variant="custom"`. See `ShaderSpec` for the
+     * full contract -- most importantly, `fragment` MUST output premultiplied
+     * colour (`vec4(rgb * alpha, alpha)`, not `vec4(rgb, alpha)`), or
+     * translucent edges get dark fringes on light backgrounds.
+     */
+    shader?: ShaderSpec;
+    /**
+     * Shader variants only (`wave`/`aurora`/`custom`): keep animating while the
+     * element is scrolled off screen. Default `false`, which stops the draw loop
+     * and releases the WebGL context until it comes back -- see `ShaderCanvas`'s
+     * `animateWhenNotVisible` for the context-budget reasoning and the cost of
+     * opting out. Does not override `prefers-reduced-motion`.
+     */
+    animateWhenNotVisible?: boolean;
+    class?: string;
+    /**
+     * Render each DOM variant's items yourself -- the same render-prop the
+     * underlying bar/grid/radial component takes, imported rather than
+     * redeclared so the two cannot drift. Not used by the shader variants
+     * (`wave`/`aurora`/`custom`): a fragment shader has no per-item DOM for it
+     * to replace.
+     */
+    children?: VariantProps['children'];
+    /**
+     * Explicit `'light'` or `'dark'` wins; `'auto'` (the default) follows a
+     * live `prefers-color-scheme` listener -- the same rule
+     * `elements/define.tsx`'s `createDarkMode` applies for every `kai-*`
+     * element. Only the shader variants read this (aurora/wave pick a colour
+     * pipeline with it): the three DOM variants already get dark-mode styling
+     * for free via CSS custom properties, which a shader baking colour into a
+     * GLSL uniform cannot do. `<kai-audio-visualizer>` forwards its own
+     * already-resolved `theme` attribute through this prop; a bare
+     * `<AudioVisualizer>` with no wrapping element needs it set directly.
+     */
+    theme?: 'light' | 'dark' | 'auto';
+}
+/** Tracks `prefers-reduced-motion`, live. */
+export declare function usePrefersReducedMotion(): Accessor<boolean>;
+/**
+ * Resolves `theme` (`'light' | 'dark' | 'auto'`) to a boolean, mirroring
+ * `elements/define.tsx`'s `createDarkMode` rule exactly: an explicit value
+ * wins, `'auto'` (the default) follows a live `prefers-color-scheme`
+ * listener.
+ *
+ * This is a SEPARATE implementation of that rule, not an import of it:
+ * `components/` is the framework-agnostic layer `elements/` wraps (see the
+ * kit's architecture), so it cannot depend on `elements/define.tsx` without
+ * inverting that direction. When driven through `<kai-audio-visualizer>`,
+ * the facade has already resolved `'auto'` against its OWN listener (the one
+ * already wired to the visible `.dark` class) before handing this an
+ * explicit `'light'`/`'dark'` -- so this hook's own listener only ever
+ * actually decides anything for a bare `<AudioVisualizer>` used directly,
+ * with no wrapping element at all.
+ */
+export declare function useResolvedDark(theme: () => string | undefined): Accessor<boolean>;
+/**
+ * Props a shader variant (`wave`, `aurora`, `custom`) receives from the
+ * dispatcher: everything a DOM variant gets, minus `children` (a fragment
+ * shader has no per-item DOM for a render-prop to replace, so the field is
+ * dropped rather than inherited-but-unused), plus the scalar `volume` reading
+ * (shaders read one number, not per-band levels) and the shader-specific
+ * knobs. This is the compile-time contract Tasks 12 to 15 build against --
+ * keep it honest rather than casting around a looser type at the render site.
+ */
+export interface ShaderVariantProps extends Omit<VariantProps, 'children'> {
+    volume: number;
+    /** Pattern density, 0..1. */
+    complexity?: number;
+    /** Only meaningful for `variant="custom"`. */
+    shader?: ShaderSpec;
+    /**
+     * Already-resolved: `true` selects the dark colour pipeline, `false`
+     * selects light -- matching `elements/define.tsx`'s `createDarkMode`
+     * output exactly (`classList={{ dark: isDark() }}`). This is that SAME
+     * resolved value forwarded down, not a re-derivation, so a shader baking
+     * colour into a GLSL uniform never needs its own `prefers-color-scheme`
+     * listener for the common case. Optional: a shader mounted standalone (no
+     * dispatcher resolving `theme` above it) may fall back to reading the
+     * media query itself.
+     */
+    dark?: boolean;
+    /**
+     * Keep animating while off screen instead of releasing the WebGL context.
+     * Relayed straight through to `ShaderCanvas`, which owns the behaviour and
+     * documents the trade-off; the variants are pure conduits for it.
+     */
+    animateWhenNotVisible?: boolean;
+    /**
+     * Call this if the shader cannot render at all -- most commonly
+     * `canvas.getContext('webgl')` returning null. Permanent for this mount:
+     * the dispatcher swaps to the bar fallback and will not retry the shader
+     * on any later reactive update, only on switching to a different variant.
+     */
+    onUnavailable: () => void;
+}
+export declare function AudioVisualizer(props: AudioVisualizerProps): JSX.Element;

package/dist/components/audio-visualizer/shader-canvas.d.ts

@@ -0,0 +1,130 @@
+import { JSX } from 'solid-js';
+export type UniformType = '1f' | '1i' | '1fv' | '2f' | '3f' | '3fv' | '4f' | '4fv' | 'Matrix2fv' | 'Matrix3fv' | 'Matrix4fv';
+export interface UniformSpec {
+    type: UniformType;
+    value: number | number[];
+    /**
+     * For array uniforms (`1fv`, `3fv`, `4fv`, or a matrix type repeated), the
+     * declared length. Optional: when omitted, it is inferred from
+     * `value.length` -- see `inferArraySize`. The inferred length is exactly
+     * what the recompile check uses too (see `effectiveArraySize`), so a
+     * length change recompiles the shader whether `arraySize` was passed
+     * explicitly or left to be inferred -- e.g. a per-band uniform whose
+     * length tracks a reactive `size`/`barCount` prop stays correct across a
+     * band-count change with no extra care from the caller.
+     */
+    arraySize?: number;
+}
+export interface ShaderCanvasProps {
+    /**
+     * GLSL defining `mainImage(out vec4 fragColor, in vec2 fragCoord)`.
+     *
+     * MUST output PREMULTIPLIED colour: `fragColor = vec4(rgb * alpha, alpha);`,
+     * not `vec4(rgb, alpha)`. The canvas context uses the browser default
+     * `premultipliedAlpha: true` (see `ShaderCanvas`'s doc for why), so a
+     * naturally written soft/anti-aliased edge that returns straight (not
+     * premultiplied) colour composites with a dark fringe or halo -- most
+     * visible on a light page background.
+     */
+    fragment: string;
+    /**
+     * Custom uniforms. THIS CANVAS DECLARES THEM FOR YOU by injecting
+     * `uniform <type> <name>;` into the shader source. Declaring them yourself
+     * in `fragment` too is a GLSL redefinition and fails to compile.
+     */
+    uniforms?: Record<string, UniformSpec>;
+    precision?: 'lowp' | 'mediump' | 'highp';
+    /**
+     * Called when the shader cannot render at all: no WebGL context, or a
+     * compile/link failure. Not called again for a later value-only uniform
+     * update (see the reactivity note on `ShaderCanvas` below) -- only when
+     * the shader itself is rebuilt and that rebuild fails.
+     */
+    onError?: (message: string) => void;
+    /**
+     * Keep animating while the canvas is off screen. Default `false`.
+     *
+     * By default an off-screen canvas stops drawing AND hands its WebGL context
+     * back to the browser (see `ShaderCanvas`'s doc), because contexts are
+     * rationed at roughly 16 per renderer process and a page of visualizers
+     * blows through that. Set this when a canvas must keep running unseen --
+     * capturing frames, or a shader whose state must not visibly jump when it
+     * scrolls back in. The cost is one permanently-held context per canvas, so
+     * it does not scale: a page that sets this on more than a handful of
+     * visualizers is back to the eviction problem the default exists to avoid.
+     *
+     * Named to match upstream's prop of the same name, though ours opts out of
+     * something stronger: theirs only pauses the draw loop, ours also releases
+     * the context.
+     *
+     * This does NOT override `prefers-reduced-motion`. Reduced motion is applied
+     * a layer up, by the variants zeroing their own speed uniforms, so a frozen
+     * shader stays a still image whether or not this is set -- this only decides
+     * whether frames keep being drawn, never what they contain.
+     */
+    animateWhenNotVisible?: boolean;
+    class?: string;
+}
+/** Default accent for the shader variants, matching upstream's. */
+export declare const DEFAULT_SHADER_COLOR = "#1FD5F9";
+/**
+ * `#rrggbb` to three 0..1 floats, for a `3fv` uniform. Falls back to the
+ * default on malformed input (short forms like `#fff`, bare colour names,
+ * empty strings) rather than throwing into a render loop.
+ *
+ * Lives here, not duplicated, because wave, aurora, and custom variants all
+ * need it.
+ */
+export declare function hexToRgb(hex: string): [number, number, number];
+/**
+ * Assemble the full fragment shader: precision, built-ins, auto-declared
+ * custom uniforms, the caller's body, and a `main()` that forwards to
+ * `mainImage`.
+ *
+ * Declares every entry in `uniforms` for the caller (`uniform <type>
+ * <name>;`, injected right after the precision qualifier). Declaring the
+ * SAME uniform name inside `fragment` too is a GLSL redefinition and fails
+ * to compile -- that is the contract this function exists to protect.
+ *
+ * Split out from the component because it is the only part testable without
+ * a GPU (jsdom has no WebGL at all), and it is where both a compile-breaking
+ * duplicate declaration and an array-size mismatch would show up.
+ */
+export declare function buildFragmentSource(fragment: string, uniforms: Record<string, UniformSpec>, precision: string): string;
+/**
+ * A full-screen fragment shader on a canvas, ShaderToy-compatible.
+ *
+ * Deliberately does NOT support textures, `iChannel` inputs, video,
+ * multipass, or device orientation. Those are what make upstream's runner
+ * 988 lines, and an audio visualizer needs none of them.
+ *
+ * Renders with a fully transparent clear colour (`gl.clearColor(0,0,0,0)`).
+ * Compositing over the page comes from the canvas context's default
+ * `premultipliedAlpha: true`, NOT from `gl.blendFunc` (see the comment at
+ * the blend call site for why that call has no effect on today's
+ * single-pass output). Because of that default, `fragment` MUST output
+ * premultiplied colour -- see the doc on the `fragment` prop for the exact
+ * contract.
+ *
+ * Reactivity note: only `fragment`, `precision`, and the STRUCTURE of
+ * `uniforms` (which names exist, with which types/sizes) trigger a rebuild
+ * of the GL program. A uniform's VALUE is read fresh every animation frame
+ * without forcing a rebuild -- see `uniformShapeKey` above. This matters
+ * because a caller typically re-creates the `uniforms` object every render
+ * (e.g. `{ uVolume: { type: '1f', value: volume() } }`); tracking that
+ * object directly would tear down and recompile the whole program on every
+ * frame the volume changes. `fragment` and `precision` are ALSO read through
+ * their own memos, not directly, for the same reason: a variant's `precision`
+ * is commonly computed from a prop (`size`) that arrives via a dispatcher
+ * spread bundling unrelated fast-changing signals (`bands`), so an unmemoized
+ * read can mark this effect stale on every one of those, even though
+ * `precision`'s resolved value never changes. See the comment above
+ * `fragmentMemo`/`precisionMemo` below for the measured failure this caused.
+ *
+ * Visibility: while the canvas is off screen this canvas RELEASES its WebGL
+ * context outright, and takes it back when the canvas returns -- see the
+ * `ContextState` block inside the component for the whole mechanism and the
+ * context-budget measurement that forced it. There is no prop for this; it is
+ * always on.
+ */
+export declare function ShaderCanvas(props: ShaderCanvasProps): JSX.Element;

package/dist/components/audio-visualizer/sizes.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Size scales for the audio visualizer variants.
+ *
+ * Values carried from livekit/components-js `packages/shadcn/components/agents-ui/`
+ * (Apache License 2.0). Kept as numbers rather than Tailwind classes so bar
+ * counts and radii can be interpolated: upstream hardcodes arbitrary values
+ * (`w-[4px]`) in cva variants, which cannot vary with a runtime count.
+ */
+export type VisualizerSize = 'icon' | 'sm' | 'md' | 'lg' | 'xl';
+export declare const SIZES: readonly VisualizerSize[];
+/** Overall height of the bar and radial containers, in px. */
+export declare const CONTAINER_HEIGHT: Record<VisualizerSize, number>;
+/** Gap between bars, in px. */
+export declare const GAP: Record<VisualizerSize, number>;
+/** Bar width, in px. Doubles as the bar's min-height so a dot shows at zero. */
+export declare const BAR_WIDTH: Record<VisualizerSize, number>;
+/** Grid cell diameter, in px. */
+export declare const GRID_CELL: Record<VisualizerSize, number>;
+/** Grid gap, in px. Note this diverges from GAP above at lg and xl. */
+export declare const GRID_GAP: Record<VisualizerSize, number>;
+/** Distance from center to the radial ring, in px. */
+export declare const RADIAL_RADIUS: Record<VisualizerSize, number>;
+export declare function defaultBarCount(size: VisualizerSize): number;
+export declare function defaultRadialBarCount(size: VisualizerSize): number;
+export declare function defaultGridCount(size: VisualizerSize): number;