Pulse

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

"use client";

import * as React from "react";

import { cn } from "@/lib/utils";

/**
 * Keep:
 * - One rAF loop paints one canvas: the still grid is drawn once offscreen and blitted each frame,
 *   lifted dots are batched into one path per tone and level, and the loop stops when no ring is
 *   left.
 * - Only ids new since the last `events` list land; the first list is history, and events that
 *   arrive off screen or in a hidden tab are dropped, not queued.
 * - Rings add up where they cross and never cancel; past `maxRings` the oldest is dropped.
 * - Labels are stroked with the ground's color so dots never cut through them, and a repeat from
 *   the same spot takes over the label already showing.
 * - Under reduced motion there are no rings: a still spot lights by opacity alone (the dots keep
 *   one size), and labels fade in place without the rise.
 */
const TIMING = {
  /** How fast a ring leaves its point, in px/s (the `ringSpeed` prop). */
  ringSpeed: 420,
  /** A ring fading to nothing, in seconds (the `ringDuration` prop). */
  ringDuration: 1.6,
  /** The afterglow at the landing point, in seconds. */
  glow: 2,
  /** The still spot that replaces a ring under reduced motion, in seconds. */
  spot: 1.2,
  /** A label in, held, and gone by, in seconds from when it lands. */
  label: { in: 0.12, hold: 0.8, out: 1.1 },
  /** Events per minute it lands on its own while the feed is quiet (`ambient`); 0 turns it off. */
  ambient: 0,
} as const;

/* ─────────────────────────────────────────────────────────
 * PULSE STORYBOARD
 *
 *  rest     a still grid of faint dots fills the box, like
 *           water with nothing landing on it
 *  land     a new event (a new id in `events`) drops onto its
 *           point. A ring leaves it at 420px/s: the dots under
 *           the 60px crest swell from 1 to 2.8px and take the
 *           event's tone, a weaker second crest follows, and
 *           both fade out over 1.6s and with distance. Strength
 *           sets how far it carries: 260px for a whisper,
 *           640px for a big one
 *  glow     the landing point stays lit for 2s after the ring
 *           has left, so you can still see where it hit
 *  label    an event with a `label` prints it 10px above its
 *           point in the event's tone, 11px mono: in over
 *           120ms with a 4px rise, held, gone by 1.1s, nudged
 *           inside the box near an edge. A repeat from the
 *           same spot takes over the label already showing; a
 *           different one nearby prints a line higher. It's
 *           how a viewer tells which ring is which log line
 *  weight   dark ink on a light ground draws heavier (rest
 *           0.24, crest to 3.2px at full opacity) than light
 *           ink on a dark one (rest 0.16, crest to 2.8px), so
 *           both schemes read the same
 *  overlap  rings add up where they cross and never cancel.
 *           Past 12 at once the oldest is dropped
 *  ambient  with `ambient` set, it lands events of its own at
 *           random points while your feed is quiet, so the
 *           surface can play alone. A real event pushes the
 *           next ambient one back
 *  sleep    off screen or in a hidden tab nothing draws, and
 *           events that arrive then are dropped, not queued
 *  reduced  no rings: the dots within 40px of the point light
 *           in the tone and fade out by opacity over 1.2s.
 *           Labels fade in and out in place, without the rise
 * ───────────────────────────────────────────────────────── */

const PULSE = {
  band: 60, // px, width of a ring's crest
  echo: { lag: 1.3, amp: 0.35 }, // the second crest: bands behind the first, share of its height
  reach: [260, 640], // px a ring carries at strength 0 and 1
  gain: [0.75, 1], // crest height at strength 0 and 1
  // Dot weight per ground: radius at rest and on a full crest (px), rest opacity, ink crest opacity range.
  onLight: { dot: [1, 3.2], restAlpha: 0.24, crest: [0.34, 1] }, // dark ink on a light ground
  onDark: { dot: [1, 2.8], restAlpha: 0.16, crest: [0.2, 1] }, // light ink on a dark ground
  accentCrest: [0.35, 1], // accent dots' opacity range, either ground
  label: { rise: 4, gap: 10, size: 11, halo: 3, edge: 6 }, // px, px, px, px, px
  labelSame: 40, // px, a repeat of the same label this close takes over the one showing
  labelSlots: 3, // lines a crowded spot stacks labels into
  glow: { radius: 26 }, // px, the afterglow at the landing point
  reduced: { radius: 40 }, // px, the still spot that replaces a ring
  strength: 0.6, // an event's strength when it doesn't say
  maxRings: 12,
  levels: 10, // size and opacity steps lifted dots are batched into
  maxDpr: 2,
} as const;

const REDUCED = "(prefers-reduced-motion: reduce)";
const subscribeReduced = (onChange: () => void) => {
  const query = window.matchMedia(REDUCED);
  query.addEventListener("change", onChange);
  return () => query.removeEventListener("change", onChange);
};

/** Reduced motion from the media query, false on the server and in the hydration render. */
function useReduced() {
  return React.useSyncExternalStore(
    subscribeReduced,
    () => window.matchMedia(REDUCED).matches,
    () => false,
  );
}

const clamp01 = (t: number) => Math.min(1, Math.max(0, t));
const easeOut = (t: number) => 1 - (1 - t) ** 3;

/** A seeded generator, so an event without a point always lands in the same place. */
function seeded(key: string) {
  let h = 2166136261;
  for (let i = 0; i < key.length; i++) h = Math.imul(h ^ key.charCodeAt(i), 16777619);
  return () => {
    h = (h + 0x6d2b79f5) | 0;
    let t = Math.imul(h ^ (h >>> 15), 1 | h);
    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
  };
}

export interface PulseEvent {
  /** Stable id. An event lands once, the first time its id shows up. */
  id: string | number;
  /** Where it lands across the box, 0–1. A missing one gets a point picked from the id. */
  x?: number;
  /** Where it lands down the box, 0–1. */
  y?: number;
  /** 0–1: how far the ring carries and how much the dots swell. */
  strength?: number;
  /** The color the dots take as the ring passes. */
  tone?: "accent" | "ink";
  /** A few characters printed just above the point for about a second, like the region or city it came from. */
  label?: string;
}

type Ring = {
  x: number;
  y: number;
  t0: number;
  strength: number;
  accent: boolean;
  label?: string;
  labelT0: number; // when the label started showing; a repeat from the same spot carries it on
  labelX: number;
  labelY: number;
  slot: number; // lines above the point, so two nearby labels never print over each other
};

/** Relative luminance of any CSS color, read back from a 1px canvas so every color syntax works. */
function luminance(color: string) {
  const c = document.createElement("canvas").getContext("2d", { willReadFrequently: true });
  if (!c) return 0;
  c.fillStyle = color;
  c.fillRect(0, 0, 1, 1);
  const [r, g, b] = c.getImageData(0, 0, 1, 1).data;
  const lin = (v: number) => {
    const s = v / 255;
    return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
  };
  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
}

/** The first painted background at or above `el`, for the halo behind labels. */
function groundColor(el: HTMLElement | null) {
  for (let node = el; node; node = node.parentElement) {
    const bg = getComputedStyle(node).backgroundColor;
    if (bg && bg !== "transparent" && !/rgba?\(.*,\s*0\)$/.test(bg)) return bg;
  }
  return null;
}
type Options = {
  spacing: number;
  ambient: number;
  paused: boolean;
  ringSpeed: number;
  ringDuration: number;
  reduced: boolean;
};

function createPulse() {
  let root: HTMLElement | null = null;
  let canvas: HTMLCanvasElement | null = null;
  let ctx: CanvasRenderingContext2D | null = null;
  let probes: { ink: HTMLElement; accent: HTMLElement } | null = null;
  let ink = "currentColor";
  let accent = "currentColor";
  let halo: string | null = null; // the ground behind the box, stroked around labels
  let font = "monospace";
  let weight: (typeof PULSE)["onLight" | "onDark"] = PULSE.onDark;
  let options: Options = {
    spacing: 18,
    ambient: TIMING.ambient,
    paused: false,
    ringSpeed: TIMING.ringSpeed,
    ringDuration: TIMING.ringDuration,
    reduced: false,
  };
  let onLand: ((event: PulseEvent) => void) | null = null;

  // The grid, rebuilt when the root changes size.
  let width = 0;
  let height = 0;
  let dpr = 1;
  let cols = 0;
  let rows = 0;
  let ox = 0;
  let oy = 0;
  let liftInk = new Float32Array(0);
  let liftAccent = new Float32Array(0);
  let buckets: Int32Array[] = []; // dot indices per tone × level
  let bucketCounts = new Int32Array(0);
  let rest: HTMLCanvasElement | null = null; // the still grid, blitted every frame

  const rings: Ring[] = [];
  let raf = 0;
  let inView = false;
  let pageVisible = true;
  let ambientTimer = 0;
  let ambientCount = 0;
  const ambientRandom = seeded("pulse-ambient");
  const cleanups: (() => void)[] = [];

  const now = () => performance.now() / 1000;
  const awake = () => inView && pageVisible;
  const ringLife = () => (options.reduced ? TIMING.spot : Math.max(options.ringDuration, TIMING.glow));

  function readColors() {
    if (!probes) return;
    const style = getComputedStyle(probes.ink);
    ink = style.color;
    font = style.fontFamily || "monospace";
    accent = getComputedStyle(probes.accent).color;
    halo = groundColor(root);
    weight = luminance(ink) < 0.4 ? PULSE.onLight : PULSE.onDark;
    drawRest();
  }

  function drawRest() {
    if (!rest || !width) return;
    const c = rest.getContext("2d");
    if (!c) return;
    c.setTransform(1, 0, 0, 1, 0, 0);
    c.clearRect(0, 0, rest.width, rest.height);
    c.setTransform(dpr, 0, 0, dpr, 0, 0);
    c.fillStyle = ink;
    c.globalAlpha = weight.restAlpha;
    c.beginPath();
    const r = weight.dot[0];
    for (let row = 0; row < rows; row++) {
      for (let col = 0; col < cols; col++) {
        const x = ox + col * options.spacing;
        const y = oy + row * options.spacing;
        c.moveTo(x + r, y);
        c.arc(x, y, r, 0, Math.PI * 2);
      }
    }
    c.fill();
  }

  function layout() {
    if (!root || !canvas) return;
    const w = root.clientWidth;
    const h = root.clientHeight;
    const nextDpr = Math.min(window.devicePixelRatio || 1, PULSE.maxDpr);
    const s = options.spacing;
    const nextCols = Math.max(1, Math.floor(w / s));
    const nextRows = Math.max(1, Math.floor(h / s));
    if (w === width && h === height && nextDpr === dpr && nextCols === cols && nextRows === rows) return;
    width = w;
    height = h;
    dpr = nextDpr;
    cols = nextCols;
    rows = nextRows;
    ox = (w - (cols - 1) * s) / 2;
    oy = (h - (rows - 1) * s) / 2;
    canvas.width = Math.round(w * dpr);
    canvas.height = Math.round(h * dpr);
    rest ??= document.createElement("canvas");
    rest.width = canvas.width;
    rest.height = canvas.height;
    const count = cols * rows;
    liftInk = new Float32Array(count);
    liftAccent = new Float32Array(count);
    buckets = Array.from({ length: PULSE.levels * 2 }, () => new Int32Array(count));
    bucketCounts = new Int32Array(PULSE.levels * 2);
    drawRest();
    wake();
  }

  /** Adds one ring's lift to the dots it touches this frame. */
  function addRing(ring: Ring, t: number) {
    const age = t - ring.t0;
    const lift = ring.accent ? liftAccent : liftInk;
    const gain = PULSE.gain[0] + (PULSE.gain[1] - PULSE.gain[0]) * ring.strength;

    if (options.reduced) {
      const fade = clamp01(1 - age / TIMING.spot);
      const R = PULSE.reduced.radius;
      eachDot(ring.x, ring.y, R, (i, d) => {
        lift[i] = Math.min(1, lift[i] + fade * (1 - d / R) * gain * 1.4);
      });
      return;
    }

    const radius = options.ringSpeed * age;
    const half = PULSE.band / 2;
    const reach = PULSE.reach[0] + (PULSE.reach[1] - PULSE.reach[0]) * ring.strength;
    const time = clamp01(1 - age / options.ringDuration);
    const timeFade = time * Math.sqrt(time);
    const glow = clamp01(1 - age / TIMING.glow);
    const echoAt = radius - PULSE.band * PULSE.echo.lag;
    const extent = timeFade > 0 ? Math.min(radius + PULSE.band, reach) : PULSE.glow.radius;

    eachDot(ring.x, ring.y, Math.max(extent, PULSE.glow.radius), (i, d) => {
      let v = 0;
      if (timeFade > 0 && d < reach) {
        const k = (d - radius) / half;
        let crest = Math.exp(-k * k);
        if (echoAt > 0) {
          const k2 = (d - echoAt) / half;
          crest += PULSE.echo.amp * Math.exp(-k2 * k2);
        }
        v = crest * timeFade * (1 - d / reach) * gain;
      }
      if (glow > 0 && d < PULSE.glow.radius) {
        v = Math.max(v, glow * glow * (1 - d / PULSE.glow.radius) * gain);
      }
      if (v > 0) lift[i] = Math.min(1, lift[i] + v);
    });
  }

  /** Calls `fn` for every dot within `r` px of (x, y), with its distance. */
  function eachDot(x: number, y: number, r: number, fn: (i: number, d: number) => void) {
    const s = options.spacing;
    const c0 = Math.max(0, Math.ceil((x - r - ox) / s));
    const c1 = Math.min(cols - 1, Math.floor((x + r - ox) / s));
    const r0 = Math.max(0, Math.ceil((y - r - oy) / s));
    const r1 = Math.min(rows - 1, Math.floor((y + r - oy) / s));
    for (let row = r0; row <= r1; row++) {
      const dy = oy + row * s - y;
      for (let col = c0; col <= c1; col++) {
        const dx = ox + col * s - x;
        const d = Math.sqrt(dx * dx + dy * dy);
        if (d <= r) fn(row * cols + col, d);
      }
    }
  }

  function frame() {
    raf = 0;
    if (!ctx || !canvas || !rest) return;
    const t = now();
    const life = ringLife();
    for (let i = rings.length - 1; i >= 0; i--) if (t - rings[i].t0 > life) rings.splice(i, 1);

    ctx.setTransform(1, 0, 0, 1, 0, 0);
    ctx.globalAlpha = 1;
    ctx.clearRect(0, 0, canvas.width, canvas.height);
    ctx.drawImage(rest, 0, 0);
    if (!rings.length) return;

    liftInk.fill(0);
    liftAccent.fill(0);
    for (const ring of rings) addRing(ring, t);

    // Batch every lifted dot by tone and level, then fill each batch in one path.
    bucketCounts.fill(0);
    const L = PULSE.levels;
    for (let i = 0; i < liftInk.length; i++) {
      const a = liftAccent[i];
      const n = liftInk[i];
      const v = Math.max(a, n);
      if (v < 0.04) continue;
      const level = Math.min(L - 1, Math.floor(v * L));
      const b = (a >= n ? L : 0) + level;
      buckets[b][bucketCounts[b]++] = i;
    }
    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
    const s = options.spacing;
    const [r0, r1] = weight.dot;
    for (let b = 0; b < L * 2; b++) {
      const n = bucketCounts[b];
      if (!n) continue;
      const isAccent = b >= L;
      const v = ((b % L) + 0.5) / L;
      // Reduced motion changes opacity only; the dots keep one size.
      const r = options.reduced ? r0 + (r1 - r0) * 0.6 : r0 + (r1 - r0) * v;
      const [a0, a1] = isAccent ? PULSE.accentCrest : weight.crest;
      ctx.globalAlpha = a0 + (a1 - a0) * v;
      ctx.fillStyle = isAccent ? accent : ink;
      ctx.beginPath();
      const list = buckets[b];
      for (let k = 0; k < n; k++) {
        const i = list[k];
        const x = ox + (i % cols) * s;
        const y = oy + Math.floor(i / cols) * s;
        ctx.moveTo(x + r, y);
        ctx.arc(x, y, r, 0, Math.PI * 2);
      }
      ctx.fill();
    }
    drawLabels(t);
    raf = requestAnimationFrame(frame);
  }

  /** Each labelled event's text, just above its point, on a halo of the ground so dots never cut through it. */
  function drawLabels(t: number) {
    if (!ctx) return;
    const L = { ...TIMING.label, ...PULSE.label };
    ctx.font = `500 ${L.size}px ${font}`;
    ctx.textAlign = "center";
    ctx.textBaseline = "alphabetic";
    ctx.lineJoin = "round";
    ctx.lineWidth = L.halo;
    for (const ring of rings) {
      if (!ring.label) continue;
      const age = t - ring.labelT0;
      if (age >= L.out) continue;
      const fadeIn = clamp01(age / L.in);
      const fadeOut = age < L.hold ? 1 : 1 - (age - L.hold) / (L.out - L.hold);
      const rise = options.reduced ? 0 : (1 - easeOut(fadeIn)) * L.rise;
      const half = ctx.measureText(ring.label).width / 2;
      const x = Math.min(width - L.edge - half, Math.max(L.edge + half, ring.labelX));
      // Above the point (a line higher per slot), or below it when the top edge is too close.
      const lift = ring.slot * (L.size + 4);
      // Reduced motion lights a 40px spot instead of a ring, so the label clears it.
      const gap = options.reduced ? PULSE.reduced.radius * 0.6 : L.gap;
      const above = ring.labelY - gap - lift;
      const y =
        Math.min(height - L.edge, above - L.size < L.edge ? ring.labelY + gap + L.size * 0.8 + lift : above) + rise;
      ctx.globalAlpha = Math.min(fadeIn, fadeOut) * (ring.accent ? 1 : 0.8);
      if (halo) {
        ctx.strokeStyle = halo;
        ctx.strokeText(ring.label, x, y);
      }
      ctx.fillStyle = ring.accent ? accent : ink;
      ctx.fillText(ring.label, x, y);
    }
  }

  function wake() {
    if (raf || !awake() || !ctx) return;
    raf = requestAnimationFrame(frame);
  }

  function land(event: PulseEvent) {
    if (options.paused || !awake() || !width) return;
    let x = event.x;
    let y = event.y;
    if (x === undefined || y === undefined) {
      const random = seeded(String(event.id));
      x ??= 0.06 + random() * 0.88;
      y ??= 0.08 + random() * 0.84;
    }
    const t = now();
    const ring: Ring = {
      x: clamp01(x) * width,
      y: clamp01(y) * height,
      t0: t,
      strength: clamp01(event.strength ?? PULSE.strength),
      accent: event.tone === "accent",
      label: event.label,
      labelT0: t,
      labelX: 0,
      labelY: 0,
      slot: 0,
    };
    ring.labelX = ring.x;
    ring.labelY = ring.y;
    if (ring.label) placeLabel(ring, t);
    rings.push(ring);
    if (rings.length > PULSE.maxRings) rings.splice(0, rings.length - PULSE.maxRings);
    onLand?.(event);
    scheduleAmbient();
    wake();
  }

  /**
   * Keeps labels apart. A repeat of a label still showing nearby takes it over in place, already
   * faded in. A different one that would overlap goes on the first free line above.
   */
  function placeLabel(ring: Ring, t: number) {
    const L = { ...TIMING.label, ...PULSE.label };
    const charW = L.size * 0.62; // a mono advance, close enough to test for overlap
    const live = rings.filter((r) => r.label && t - r.labelT0 < L.out);
    for (const r of live) {
      if (r.label === ring.label && Math.hypot(r.labelX - ring.x, r.labelY - ring.y) < PULSE.labelSame) {
        ring.labelT0 = t - Math.min(t - r.labelT0, L.in);
        ring.labelX = r.labelX;
        ring.labelY = r.labelY;
        ring.slot = r.slot;
        r.label = undefined;
        return;
      }
    }
    const wide = (r: Ring) => (r.label?.length ?? 0) * charW;
    for (let slot = 0; slot < PULSE.labelSlots; slot++) {
      const clash = live.some(
        (r) =>
          r.label &&
          Math.abs(r.labelX - ring.x) < (wide(r) + wide(ring)) / 2 + 6 &&
          Math.abs(r.labelY - r.slot * (L.size + 4) - (ring.y - slot * (L.size + 4))) < L.size + 2,
      );
      if (!clash) {
        ring.slot = slot;
        return;
      }
    }
  }

  /** The next event of its own, a random wait around 60 / `ambient` seconds from now. */
  function scheduleAmbient() {
    window.clearTimeout(ambientTimer);
    ambientTimer = 0;
    if (options.ambient <= 0 || options.paused || !awake()) return;
    const wait = (60 / options.ambient) * (0.5 + ambientRandom()) * 1000;
    ambientTimer = window.setTimeout(() => {
      ambientTimer = 0;
      const accentOne = ambientRandom() < 0.25;
      land({
        id: `ambient-${ambientCount++}`,
        x: 0.06 + ambientRandom() * 0.88,
        y: 0.08 + ambientRandom() * 0.84,
        strength: accentOne ? 0.8 : 0.3 + ambientRandom() * 0.35,
        tone: accentOne ? "accent" : "ink",
      });
    }, wait);
  }

  function setAwake() {
    if (awake()) {
      wake();
      scheduleAmbient();
    } else {
      cancelAnimationFrame(raf);
      raf = 0;
      rings.length = 0;
      window.clearTimeout(ambientTimer);
      ambientTimer = 0;
    }
  }

  return {
    connect(el: { root: HTMLElement; canvas: HTMLCanvasElement; ink: HTMLElement; accent: HTMLElement }) {
      root = el.root;
      canvas = el.canvas;
      ctx = canvas.getContext("2d");
      probes = { ink: el.ink, accent: el.accent };
      width = 0;
      layout();
      readColors();
      pageVisible = document.visibilityState === "visible";

      const resize = new ResizeObserver(() => layout());
      resize.observe(root);
      const io = new IntersectionObserver(([entry]) => {
        inView = entry.isIntersecting;
        setAwake();
      });
      io.observe(root);
      const visibility = () => {
        pageVisible = document.visibilityState === "visible";
        setAwake();
      };
      document.addEventListener("visibilitychange", visibility);

      const scheme = window.matchMedia("(prefers-color-scheme: dark)");
      const recolor = () => {
        readColors();
        wake();
      };
      scheme.addEventListener("change", recolor);
      const themeAttrs = new MutationObserver(recolor);
      themeAttrs.observe(document.documentElement, { attributes: true, attributeFilter: ["class", "data-theme", "style"] });

      cleanups.push(
        () => resize.disconnect(),
        () => io.disconnect(),
        () => document.removeEventListener("visibilitychange", visibility),
        () => scheme.removeEventListener("change", recolor),
        () => themeAttrs.disconnect(),
      );
      return () => {
        cancelAnimationFrame(raf);
        raf = 0;
        window.clearTimeout(ambientTimer);
        ambientTimer = 0;
        rings.length = 0;
        inView = false;
        cleanups.splice(0).forEach((fn) => fn());
        root = canvas = null;
        ctx = null;
        probes = null;
      };
    },

    setOptions(next: Options) {
      const relayout = next.spacing !== options.spacing;
      if (next.paused || next.reduced !== options.reduced) rings.length = 0;
      options = next;
      if (relayout) layout();
      scheduleAmbient();
      wake();
    },

    setOnLand(fn: ((event: PulseEvent) => void) | null) {
      onLand = fn;
    },

    land,
  };
}

export interface PulseProps extends React.HTMLAttributes<HTMLDivElement> {
  /** Your feed. Each new id lands once as a ring; ids already there on mount count as history and don't. */
  events?: PulseEvent[];
  /** Events per minute it lands on its own while your feed is quiet. `0` turns it off. */
  ambient?: number;
  /** Distance between dots, in px. */
  spacing?: number;
  /** Draw the still grid and ignore new events. */
  paused?: boolean;
  /** How fast a ring runs out from its point, in px per second. */
  ringSpeed?: number;
  /** Seconds a ring takes to fade to nothing. */
  ringDuration?: number;
  /** Classes that set the dots' color (a `text-*` color). Dots at rest draw it at low opacity. */
  inkClassName?: string;
  /** Classes that set the color an `accent` event's ring paints (a `text-*` color). */
  accentClassName?: string;
  /** Called when an event's ring starts, including the ones `ambient` lands. */
  onLand?: (event: PulseEvent) => void;
}

export function Pulse({
  events,
  ambient = TIMING.ambient,
  spacing = 18,
  paused = false,
  ringSpeed = TIMING.ringSpeed,
  ringDuration = TIMING.ringDuration,
  inkClassName,
  accentClassName,
  onLand,
  className,
  children,
  ...props
}: PulseProps) {
  const rootRef = React.useRef<HTMLDivElement>(null);
  const canvasRef = React.useRef<HTMLCanvasElement>(null);
  const inkRef = React.useRef<HTMLSpanElement>(null);
  const accentRef = React.useRef<HTMLSpanElement>(null);
  const [pulse] = React.useState(createPulse);
  const reduced = useReduced();

  React.useLayoutEffect(() => {
    const root = rootRef.current;
    const canvas = canvasRef.current;
    const ink = inkRef.current;
    const accent = accentRef.current;
    if (!root || !canvas || !ink || !accent) return;
    return pulse.connect({ root, canvas, ink, accent });
  }, [pulse]);

  React.useEffect(() => {
    pulse.setOptions({
      spacing,
      ambient,
      paused,
      ringSpeed: Math.max(1, ringSpeed),
      ringDuration: Math.max(0.05, ringDuration),
      reduced,
    });
  }, [pulse, spacing, ambient, paused, ringSpeed, ringDuration, reduced]);

  const onLandRef = React.useRef(onLand);
  React.useEffect(() => {
    onLandRef.current = onLand;
  });
  React.useEffect(() => {
    pulse.setOnLand((event) => onLandRef.current?.(event));
    return () => pulse.setOnLand(null);
  }, [pulse]);

  // Land only the ids that weren't in the last list. The first list is history.
  const seenRef = React.useRef<Set<PulseEvent["id"]> | null>(null);
  React.useEffect(() => {
    const list = events ?? [];
    const before = seenRef.current;
    seenRef.current = new Set(list.map((e) => e.id));
    if (!before) return;
    for (const event of list) if (!before.has(event.id)) pulse.land(event);
  }, [pulse, events]);

  return (
    <div ref={rootRef} className={cn("relative isolate overflow-hidden", className)} {...props}>
      <canvas ref={canvasRef} aria-hidden className="pointer-events-none absolute inset-0 -z-10 size-full" />
      {/* Probes the canvas reads its colors from. Defaults apply only when no class is given, so a `dark:` default can't win over yours. */}
      <span ref={inkRef} aria-hidden className={cn("hidden font-mono", inkClassName ?? "text-zinc-900 dark:text-zinc-100")} />
      <span ref={accentRef} aria-hidden className={cn("hidden", accentClassName ?? "text-[#ff5a1f] dark:text-[#ff6a3d]")} />
      {children}
    </div>
  );
}