@kitn.ai/ui 0.18.2 → 0.20.0

package/src/elements/slots.ts

@@ -552,11 +552,52 @@ export const MENU_PARTS: PartDef[] = [
   { name: 'shortcut', doc: 'The right-aligned per-item keyboard shortcut, rendered as kai-kbd key caps. Shown only when an item carries a `shortcut`.', recipe: 'kai-menu::part(shortcut) { opacity: 0.8 }' },
 ];
 
+/** Slots of `<kai-thread>` (the standalone scrolling message list; messages come
+ *  from the `messages` prop). */
+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 },
   'kai-conversations': { slots: CONVERSATIONS_SLOTS, parts: CONVERSATIONS_PARTS },
   'kai-message': { slots: MESSAGE_SLOTS, parts: MESSAGE_PARTS },
+  'kai-thread': { slots: THREAD_SLOTS },
   'kai-prompt-input': { slots: PROMPT_INPUT_SLOTS, parts: PROMPT_INPUT_PARTS },
   'kai-button': { slots: BUTTON_SLOTS, parts: BUTTON_PARTS },
   'kai-badge': { parts: BADGE_PARTS },
@@ -590,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/elements/thread.tsx

@@ -0,0 +1,105 @@
+import { createSignal, onMount, onCleanup } from 'solid-js';
+import { defineWebComponent } from './define';
+import { readSlots, THREAD_SLOTS } from './slots';
+import { Thread, type ThreadController } from '../components/thread';
+import type { ChatMessage } from './chat-types';
+import type { ProseSize } from '../primitives/chat-config';
+
+interface Props extends Record<string, unknown> {
+  /** The full message thread to render, newest last. Each entry carries its role,
+   *  content, and optional reasoning/tools/attachments/actions/avatar. Set as a JS
+   *  property (`el.messages = [...]`); a NEW array reference per streaming chunk
+   *  re-renders (mutating in place does not). */
+  messages?: ChatMessage[];
+  /** Show a typing indicator on the pending assistant turn — set while awaiting
+   *  the assistant's reply. */
+  loading?: boolean;
+  /** Body/prose font scale for rendered markdown (`'xs' | 'sm' | 'base' | 'lg'`).
+   *  Defaults to `'sm'`. */
+  proseSize?: ProseSize;
+  /** Shiki theme name for syntax-highlighted code blocks (e.g.
+   *  `'github-dark-dimmed'`). */
+  codeTheme?: string;
+  /** Enable Shiki syntax highlighting in code blocks. Turn off to render plain
+   *  `<pre>` blocks (lighter, no highlighter load). Default true. */
+  codeHighlight?: boolean;
+  /** Whether each message's action bar is always visible (`'always'`, default) or
+   *  only revealed on hover of that message row (`'hover'`). */
+  actionsReveal?: 'always' | 'hover';
+  /** Show the scroll-to-bottom button inside the scroll area. Default true. */
+  scrollButton?: boolean;
+  /** Extra classes applied to the thread's inner root. */
+  class?: string;
+}
+
+/** Events fired by `<kai-thread>`. */
+interface Events extends Record<string, unknown> {
+  /** A message's action button was clicked. `action` is the built-in name (`copy`
+   *  / `like` / `dislike` / `regenerate` / `edit`) or a custom id. `state` is
+   *  present only for the toggleable feedback votes: `'on'` when a like/dislike is
+   *  set, `'off'` when re-tapped to clear. */
+  'kai-message-action': { messageId: string; action: string; state?: 'on' | 'off' };
+}
+
+/**
+ * `<kai-thread>` — the scrolling message list of a chat, as a standalone
+ * composable element: one message row per `messages` entry with markdown / code
+ * highlight / reasoning + tool panels / avatars / action row, stick-to-bottom
+ * scroll with a scroll-to-bottom button, an optional typing indicator, and an
+ * `empty` slot. It fills the height its parent gives it and scrolls internally
+ * (`:host { display:block; height:100% }`). No composer, header, suggestions, or
+ * sidebar — pair it with `<kai-prompt-input>` and your own layout, or reach for
+ * the batteries-included `<kai-chat>`. Emits `kai-message-action`; exposes
+ * `scrollToBottom()`.
+ */
+defineWebComponent<Props, Events>('kai-thread', {
+  messages: undefined,
+  loading: false,
+  proseSize: 'sm',
+  codeTheme: 'github-dark-dimmed',
+  codeHighlight: true,
+  actionsReveal: 'always',
+  scrollButton: true,
+  class: undefined,
+}, (props, { element, dispatch, flag, expose }) => {
+  let controller: ThreadController | undefined;
+
+  // Detect whether the consumer projected `slot="empty"` content, so the built-in
+  // default only renders when they did NOT.
+  const [slots, setSlots] = createSignal<Record<string, boolean>>({});
+  onMount(() => {
+    const read = () => setSlots(readSlots(element, THREAD_SLOTS));
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(element, { childList: true });
+    onCleanup(() => observer.disconnect());
+  });
+
+  // Imperative method API — forward the thread's scroll control onto the host.
+  expose({
+    /** Scroll the message list to the bottom (default `'smooth'`). */
+    scrollToBottom: (behavior?: ScrollBehavior) => controller?.scrollToBottom(behavior),
+  });
+
+  return (
+    <>
+      {/* Fill the height the parent gives us and scroll internally, like
+          <kai-resizable>. Consumers only need to give a parent (or the element) a
+          height. */}
+      <style>{':host{display:block;height:100%}'}</style>
+      <Thread
+        class={props.class as string | undefined}
+        messages={(props.messages as ChatMessage[] | undefined) ?? []}
+        loading={flag('loading')}
+        proseSize={props.proseSize as ProseSize}
+        codeTheme={props.codeTheme as string}
+        codeHighlight={flag('codeHighlight')}
+        actionsReveal={props.actionsReveal as 'always' | 'hover'}
+        scrollButton={props.scrollButton !== false}
+        empty={slots()['empty'] ? <slot name="empty" /> : undefined}
+        onMessageAction={(detail) => dispatch('kai-message-action', detail)}
+        controllerRef={(c) => (controller = c)}
+      />
+    </>
+  );
+});

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;
+}

package/src/primitives/create-tween.ts

@@ -0,0 +1,214 @@
+import { createSignal, onCleanup, untrack, type Accessor } from 'solid-js';
+
+export type Transition =
+  | { duration: number; ease?: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' }
+  | { type: 'spring'; duration: number; bounce: number };
+
+/**
+ * Builds an easing function from a CSS-style cubic bezier. The curve's
+ * endpoints are fixed at (0, 0) and (1, 1); (x1, y1) and (x2, y2) are the
+ * two control points. Given a progress value `t` used as the curve's `x`,
+ * solves `X(s) === t` for the curve parameter `s` via Newton-Raphson (a
+ * handful of iterations converges for these curves), falls back to
+ * bisection if the derivative gets too small or a step would leave
+ * [0, 1], then returns `Y(s)`.
+ */
+function cubicBezier(x1: number, y1: number, x2: number, y2: number): (t: number) => number {
+  const x = (s: number) => 3 * (1 - s) * (1 - s) * s * x1 + 3 * (1 - s) * s * s * x2 + s * s * s;
+  const y = (s: number) => 3 * (1 - s) * (1 - s) * s * y1 + 3 * (1 - s) * s * s * y2 + s * s * s;
+  const xDerivative = (s: number) =>
+    3 * (1 - s) * (1 - s) * x1 + 6 * (1 - s) * s * (x2 - x1) + 3 * s * s * (1 - x2);
+
+  function bisect(t: number): number {
+    let lo = 0;
+    let hi = 1;
+    for (let i = 0; i < 30; i++) {
+      const mid = (lo + hi) / 2;
+      if (x(mid) < t) lo = mid;
+      else hi = mid;
+    }
+    return (lo + hi) / 2;
+  }
+
+  return (t: number) => {
+    if (t <= 0) return 0;
+    if (t >= 1) return 1;
+
+    let s = t;
+    for (let i = 0; i < 8; i++) {
+      const derivative = xDerivative(s);
+      if (Math.abs(derivative) < 1e-6) return y(bisect(t));
+
+      const next = s - (x(s) - t) / derivative;
+      if (next <= 0 || next >= 1) return y(bisect(t));
+
+      s = next;
+    }
+    return y(s);
+  };
+}
+
+// Matches motion's named curves so the visualizers feel like their LiveKit
+// counterparts rather than a plausible-looking approximation.
+const EASINGS = {
+  linear: (t: number) => t,
+  easeIn: cubicBezier(0.42, 0, 1, 1),
+  easeOut: cubicBezier(0, 0, 0.58, 1),
+  easeInOut: cubicBezier(0.42, 0, 0.58, 1),
+} as const;
+
+/**
+ * Damped-spring position at normalized time `t` (0..1), settling at 1.
+ *
+ * `bounce` maps to the damping ratio: 0 is critically damped (no overshoot),
+ * higher values overshoot more. Matches the feel of motion's spring defaults
+ * closely enough for shader uniforms, without the dependency.
+ */
+function spring(t: number, bounce: number): number {
+  const zeta = Math.max(0.05, 1 - Math.min(0.95, bounce));
+  const omega = 10;
+  const damped = omega * Math.sqrt(Math.max(0, 1 - zeta * zeta));
+  return (
+    1 -
+    Math.exp(-zeta * omega * t) *
+      (Math.cos(damped * t) + ((zeta * omega) / (damped || 1)) * Math.sin(damped * t))
+  );
+}
+
+function isSpring(tr: Transition): tr is { type: 'spring'; duration: number; bounce: number } {
+  return 'type' in tr && tr.type === 'spring';
+}
+
+/**
+ * A tweened number driven by requestAnimationFrame.
+ *
+ * Exists so shader uniforms can animate without pulling in a motion library.
+ * CSS transitions cannot help here: uniforms are plain JS numbers handed to
+ * WebGL every frame.
+ *
+ * `to()` interrupts whatever is in flight. An array target ping-pongs between
+ * its two values forever, which is how the listening and thinking pulses read.
+ * `duration: 0` (or no transition) sets instantly, which live volume needs so
+ * the picture never lags the audio.
+ *
+ * `animating` is true exactly while a frame loop is armed: from an animated
+ * `to()` until it lands (a ping-pong never lands, so it stays true), false
+ * for instant sets and after dispose. It is a real signal on purpose -- the
+ * aurora variant's volume-override effect reads it as its upstream-parity
+ * "scale tween idle" guard, and being reactive means that effect re-runs
+ * the moment a landing settles instead of waiting for the next volume tick.
+ */
+export function createTween(initial: number): {
+  value: Accessor<number>;
+  animating: Accessor<boolean>;
+  to(target: number | [number, number], transition?: Transition): void;
+} {
+  const [value, setValue] = createSignal(initial);
+  const [animating, setAnimating] = createSignal(false);
+  let raf = 0;
+  let disposed = false;
+
+  const stop = () => {
+    if (raf) cancelAnimationFrame(raf);
+    raf = 0;
+  };
+
+  onCleanup(() => {
+    disposed = true;
+    stop();
+    setAnimating(false);
+  });
+
+  function to(target: number | [number, number], transition?: Transition) {
+    stop();
+    if (disposed) return;
+
+    const pingPong = Array.isArray(target);
+    // Untracked: `.to()` is an imperative command ("animate to this
+    // target"), not a reactive read. Its normal caller is a createEffect
+    // reacting to some OTHER signal (e.g. state changing); reading this
+    // tween's own `value()` here without untrack() would make that effect
+    // implicitly depend on the tween's own signal too. That is invisible
+    // for a single tween (it would just restart itself every frame and
+    // still crawl toward the target) but is fatal the moment a caller
+    // creates a SECOND tween and `.to()`'s both from the same effect (see
+    // the wave shader variant, which does exactly this for amplitude and
+    // frequency): a browser fires one frame's queued
+    // requestAnimationFrame callbacks in the order they were registered, so
+    // the FIRST tween's step -- which runs first, and whose `setValue`
+    // synchronously re-triggers the (now-dependent) effect -- cancels the
+    // SECOND tween's already-queued step before the browser ever reaches
+    // it. That repeats identically every single frame, so the second
+    // tween's `step` never fires even once and its value never leaves its
+    // initial one, permanently, no matter how long the effect keeps
+    // "restarting" it.
+    const [a, b] = pingPong ? target : [untrack(value), target];
+
+    if (!transition || (!isSpring(transition) && transition.duration === 0)) {
+      setAnimating(false);
+      setValue(pingPong ? a : b);
+      return;
+    }
+
+    const durationMs = transition.duration * 1000;
+    if (durationMs <= 0) {
+      setAnimating(false);
+      setValue(b);
+      return;
+    }
+
+    if (typeof requestAnimationFrame === 'undefined') {
+      setAnimating(false);
+      setValue(b);
+      return;
+    }
+
+    const ease = isSpring(transition)
+      ? (t: number) => spring(t, transition.bounce)
+      : EASINGS[transition.ease ?? 'easeOut'];
+
+    // A ping-pong starts from its first value rather than wherever it was, so
+    // the pulse reads the same every time it restarts. `a` is already an
+    // untracked read of the current value (or the ping-pong's first target
+    // value) from above -- reused here instead of reading `value()` again.
+    let from = a;
+    let to_ = b;
+    if (pingPong) setValue(a);
+
+    // requestAnimationFrame's timestamp and performance.now() share a time
+    // origin per spec, so capturing the origin here, at the moment to() is
+    // called, is directly comparable to the `now` a later frame reports.
+    // That means elapsed time is measured from when this leg actually
+    // started, correct on the very first frame with no lazy-capture dance
+    // and no risk of an idle gap since the last tween being charged against
+    // this one.
+    let legStart = performance.now();
+    const step = (now: number) => {
+      const t = Math.min(1, (now - legStart) / durationMs);
+      setValue(from + (to_ - from) * ease(t));
+
+      if (t < 1) {
+        raf = requestAnimationFrame(step);
+        return;
+      }
+
+      if (!pingPong) {
+        setValue(to_);
+        raf = 0;
+        setAnimating(false);
+        return;
+      }
+
+      // Reverse and run again, from a fresh origin for the new leg.
+      setValue(to_);
+      [from, to_] = [to_, from];
+      legStart = performance.now();
+      raf = requestAnimationFrame(step);
+    };
+
+    setAnimating(true);
+    raf = requestAnimationFrame(step);
+  }
+
+  return { value, animating, to };
+}