Plinko

// Shared motion tokens. Easing curves mirror the CSS custom properties in
// globals.css; springs are the canonical physics used across components.
// Strong custom variants — defaults like `ease-in`/`ease-out` feel weak.

export const EASE_OUT = [0.16, 1, 0.3, 1] as const;
export const EASE_IN_OUT = [0.77, 0, 0.175, 1] as const;
export const EASE_DRAWER = [0.32, 0.72, 0, 1] as const;

/** CSS string form of EASE_OUT for inline style transitions. */
export const EASE_OUT_CSS = "cubic-bezier(0.16, 1, 0.3, 1)";

/** Press feedback on buttons and other tappable surfaces. */
export const SPRING_PRESS = {
  type: "spring",
  stiffness: 500,
  damping: 30,
  mass: 0.6,
} as const;

/** Content swaps — label/icon slots trading places inside a control. */
export const SPRING_SWAP = {
  type: "spring",
  stiffness: 460,
  damping: 30,
  mass: 0.55,
} as const;

/** Overlay panel entrances — modals and sheets summoned by pointer. */
export const SPRING_PANEL = {
  type: "spring",
  stiffness: 420,
  damping: 40,
  mass: 0.5,
} as const;

/** Shared-layout glides — pills, indicators and panels morphing between positions. */
export const SPRING_LAYOUT = {
  type: "spring",
  stiffness: 360,
  damping: 32,
  mass: 0.6,
} as const;

/** Cursor-follow physics for decorative mouse tracking (magnetic, tilt, dock). */
export const SPRING_MOUSE = {
  stiffness: 200,
  damping: 15,
  mass: 0.3,
} as const;

/** Dragged handles and fills (sliders) — critically damped `useSpring` config,
 * so the value follows the pointer butterily and never rebounds off an end. */
export const SPRING_GLIDE = {
  stiffness: 700,
  damping: 50,
  mass: 0.5,
} as const;

// Synthesizes a short, dry mechanical detent for gesture feedback (e.g. the
// WheelPicker row-cross click) entirely at runtime. Several inharmonic modes
// make it read as a tiny physical impact instead of an oscillator beep, while
// the high-passed transient gives it definition through phone speakers.

import { getAudioContext, retainAudioContext } from "@/lib/audio-context";

const DURATION = 0.016; // seconds, short enough to stay distinct during a fling
const MASTER_GAIN = 0.055;

const MODES = [
  { frequency: 980, decay: 0.0038, gain: 0.5, phase: 0 },
  { frequency: 1820, decay: 0.0024, gain: 0.3, phase: 0.65 },
  { frequency: 3160, decay: 0.00115, gain: 0.12, phase: 1.3 },
] as const;

// The context is shared page-wide (lib/audio-context.ts). The gain and the
// click buffer belong to it, so they are rebuilt if it was closed and
// recreated.
let output: { gain: GainNode; buffer: AudioBuffer } | null = null;

function buildClickBuffer(context: AudioContext): AudioBuffer {
  const sampleRate = context.sampleRate;
  const length = Math.ceil(DURATION * sampleRate);
  const buffer = context.createBuffer(1, length, sampleRate);
  const data = buffer.getChannelData(0);

  let peak = 0;
  let previousNoise = 0;
  for (let i = 0; i < length; i++) {
    const t = i / sampleRate;
    const attack = Math.min(1, t / 0.00012);
    const fadeOut = Math.min(1, (DURATION - t) / 0.001);
    let resonance = 0;
    for (const mode of MODES) {
      resonance +=
        Math.sin(2 * Math.PI * mode.frequency * t + mode.phase) *
        Math.exp(-t / mode.decay) *
        mode.gain;
    }

    // Differencing consecutive noise samples removes the low, papery part of
    // white noise and leaves only a tiny impact at the front of the sound.
    const noise = Math.random() * 2 - 1;
    const transient =
      (noise - previousNoise) * Math.exp(-t / 0.00038) * 0.035;
    previousNoise = noise;

    data[i] = (resonance + transient) * attack * fadeOut;
    peak = Math.max(peak, Math.abs(data[i]));
  }
  if (peak > 0) {
    const norm = 0.9 / peak;
    for (let i = 0; i < length; i++) data[i] *= norm;
  }

  return buffer;
}

function prepareOutput() {
  const ctx = getAudioContext();
  if (!ctx) return null;
  if (output?.gain.context !== ctx) {
    const gain = ctx.createGain();
    gain.gain.value = MASTER_GAIN;
    gain.connect(ctx.destination);
    output = { gain, buffer: buildClickBuffer(ctx) };
  }
  return { ctx, ...output };
}

interface TickPlayer {
  prepare: () => void;
  /** `rate` below 1 plays a lower, longer tick; above 1 a higher, shorter one. */
  play: (rate?: number) => void;
  dispose: () => void;
}

/**
 * Lazily-initialized tick player. No `AudioContext` is created until the first
 * `prepare()` or `play()` call anywhere on the page. Every player shares the
 * same context and buffer; the context closes once the last player anywhere
 * on the page is disposed. Safe during SSR or in browsers without Web Audio:
 * `prepare()` and `play()` become silent no-ops.
 */
export function createTickPlayer(): TickPlayer {
  const release = retainAudioContext();
  let disposed = false;
  let activeSource: AudioBufferSourceNode | null = null;

  return {
    prepare() {
      if (disposed) return;
      prepareOutput();
    },
    play(rate = 1) {
      if (disposed) return;
      const ready = prepareOutput();
      if (!ready) return;
      const { ctx, gain, buffer } = ready;
      // A fast fling can cross rows more quickly than the tail of a tick.
      // Cutting that tail keeps the feedback dry instead of stacking into a
      // louder metallic ring.
      activeSource?.stop();
      const source = ctx.createBufferSource();
      source.buffer = buffer;
      source.playbackRate.value = rate;
      source.connect(gain);
      source.onended = () => {
        source.disconnect();
        if (activeSource === source) activeSource = null;
      };
      activeSource = source;
      source.start();
    },
    dispose() {
      if (disposed) return;
      disposed = true;
      activeSource?.stop();
      activeSource = null;
      release();
    },
  };
}

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

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

"use client";

import { type RefObject, useEffect } from "react";

/**
 * What the dismissing gesture does to the control it landed on.
 *
 * `"pass-through"` is the platform norm (native popover light-dismiss): the
 * tap closes the overlay *and* activates whatever was under it. Use
 * `"consume"` where the open overlay sits over or beside controls that would
 * be costly to trigger by accident — the dismissal then swallows the
 * activation too, so the gesture only closes.
 */
export type DismissBehavior = "pass-through" | "consume";

export interface DismissOptions {
  /** Default `"pass-through"`. */
  behavior?: DismissBehavior;
  /** Dismiss on Escape as well. Default true. */
  escape?: boolean;
  /** Return true for an outside target that should *not* dismiss. Must be stable. */
  ignore?: (target: Element) => boolean;
}

/**
 * What every currently open dismiss scope counts as inside itself. A consumed
 * dismissal reads this to tell a stray gesture from one that belongs to an
 * overlay in front of it: overlays have no shared z-order to consult, but the
 * one the gesture landed in has said as much by registering it.
 */
const openScopes = new Set<(target: Element) => boolean>();

function claimedByAnotherScope(
  self: (target: Element) => boolean,
  target: Element,
) {
  for (const scope of openScopes) {
    if (scope !== self && scope(target)) return true;
  }
  return false;
}

// preventDefault on pointerdown does not suppress the click that follows, so
// consuming a gesture means swallowing that click itself. The swallower
// deliberately outlives the effect that installed it — the dismissal it
// belongs to has already unmounted or re-rendered by the time the click lands.
// It releases on that click, or on the next gesture if the pointer is dragged
// away and no click ever arrives, so it can never eat a later one. A keydown
// releases it too: a gesture that ends with neither a click nor a cancel would
// otherwise leave it armed, and the click Enter synthesizes on some focused
// control is not the one this dismissal was owed.
function consumeActivation(source: Event) {
  const swallow = (event: MouseEvent) => {
    event.preventDefault();
    event.stopPropagation();
    release();
  };
  const restart = (event: Event) => {
    if (event !== source) release();
  };
  const release = () => {
    window.removeEventListener("click", swallow, true);
    window.removeEventListener("pointerdown", restart, true);
    window.removeEventListener("pointercancel", restart, true);
    window.removeEventListener("keydown", release, true);
  };
  window.addEventListener("click", swallow, true);
  window.addEventListener("pointerdown", restart, true);
  window.addEventListener("pointercancel", restart, true);
  window.addEventListener("keydown", release, true);
}

/**
 * Close an open overlay on Escape or a pointerdown outside `ref`. Pass `null`
 * for `ref` when what counts as inside isn't one element, and say so with
 * `ignore` instead.
 *
 * The pointerdown listener is capture-phase: a bubble-phase one is blinded by
 * any handler in between that stops propagation, and an overlay cannot know
 * what it is layered over. `onDismiss` and `ignore` must be stable (wrap in
 * useCallback) so the listeners aren't re-bound every render while open.
 */
export function useDismiss(
  open: boolean,
  onDismiss: () => void,
  ref: RefObject<HTMLElement | SVGElement | null> | null,
  {
    behavior = "pass-through",
    escape: dismissOnEscape = true,
    ignore,
  }: DismissOptions = {},
) {
  useEffect(() => {
    if (!open) return;
    const inside = (target: Element) =>
      Boolean(ref?.current?.contains(target)) || Boolean(ignore?.(target));
    const onKey = (event: KeyboardEvent) => {
      if (dismissOnEscape && event.key === "Escape") onDismiss();
    };
    const onPointer = (event: PointerEvent) => {
      const target = event.target as Element | null;
      if (!target || inside(target)) return;
      // Outside this overlay, but inside one that is also open: the gesture is
      // that overlay's to answer, and swallowing its click from behind would
      // cost the user the control they actually aimed at.
      if (behavior === "consume" && !claimedByAnotherScope(inside, target)) {
        consumeActivation(event);
      }
      onDismiss();
    };
    openScopes.add(inside);
    window.addEventListener("keydown", onKey);
    window.addEventListener("pointerdown", onPointer, true);
    return () => {
      openScopes.delete(inside);
      window.removeEventListener("keydown", onKey);
      window.removeEventListener("pointerdown", onPointer, true);
    };
  }, [open, onDismiss, ref, behavior, dismissOnEscape, ignore]);
}

"use client";

import { useMemo, useRef } from "react";
import { isHoveringPointer } from "@/lib/touch";

interface BoundaryEvent {
  pointerId: number;
  pointerType: string;
  buttons: number;
}

export interface HoverGesture {
  /** True when this enter starts a hover: the pointer arrived resting, not pressing. */
  enter: (event: BoundaryEvent) => boolean;
  /** True when this leave ends a hover that entered as one. */
  leave: (event: BoundaryEvent) => boolean;
}

/**
 * Pairs a surface's enter with its leave, per pointer.
 *
 * `isHoveringPointer` answers the question the *enter* asks — is this pointer
 * resting on the surface or pressing it — and both boundary cases go wrong if
 * the leave is asked the same question again:
 *
 * - A pen with no hover never rests. It arrives in contact, taps, and the spec
 *   then requires its boundary events after `pointerup`, so the leave carries
 *   `buttons: 0` and reads as a mouse gliding off. Hover teardown then undid
 *   the tap — the panel the pen had just opened closed under it.
 * - A mouse pressed on the surface and dragged off leaves with `buttons: 1`.
 *   Skipping teardown there strands the surface open: the release happens
 *   outside, and no second leave ever comes.
 *
 * So the state a hover holds is released by the pointer that took it, whatever
 * the buttons say at the boundary, and a pointer that arrived in contact never
 * took it in the first place. Contact is the exception tracked here, not
 * hover: a leave from a pointer this surface never saw enter — mounted under
 * the cursor, say — still counts, since the alternative is state with no way
 * out.
 */
export function useHoverGesture(): HoverGesture {
  const contact = useRef(new Set<number>());

  return useMemo(
    () => ({
      enter: (event) => {
        if (isHoveringPointer(event)) {
          contact.current.delete(event.pointerId);
          return true;
        }
        contact.current.add(event.pointerId);
        return false;
      },
      leave: (event) => {
        const arrivedInContact = contact.current.delete(event.pointerId);
        return !arrivedInContact && event.pointerType !== "touch";
      },
    }),
    [],
  );
}

"use client";

import { useMemo, useRef } from "react";

/** What a pointerdown recorded, read back by the click that ends its gesture. */
export interface TapRecord<S> {
  /** Which input started the gesture. */
  pointerType: string;
  /** What the surface was showing when it started. */
  state: S;
}

export interface TapGesture<S> {
  /** Record the gesture a pointerdown starts, with the state it starts in. */
  start: (event: { pointerType: string }, state: S) => void;
  /** Read the record and clear it. `null` when no pointer is behind this click. */
  take: () => TapRecord<S> | null;
  /** Drop the record: this gesture will never spend it on a click. */
  drop: () => void;
}

/**
 * The pointer gesture behind a click, recorded where the click cannot report
 * it. A `click` carries no `pointerType` in the engines that matter, so the
 * `pointerdown` before it is the only thing that says which input activated
 * the control — and whether one did at all, since keyboard activation
 * synthesizes a click with no pointer behind it.
 *
 * State goes in with the record because a click reports that no better: a
 * browser that focuses a control on contact can open the very panel the tap
 * was meant to open, and reading "is it open" at click time then undoes it.
 * What the gesture started against is what it acts on.
 *
 * The record is spent by one click and dropped by everything else, because a
 * record that outlives its gesture is worse than none:
 *
 * - A scroll or an OS gesture takes the touch away — `pointercancel`, no click
 *   ever — and the finger would sit in the record until some later click.
 * - That later click is often `Enter` on a keyboard, which arrives with no
 *   pointerdown of its own and would inherit the abandoned finger. A keydown
 *   is the start of a keyboard activation and never part of a tap, so it drops
 *   the record too.
 *
 * Both ends have to be wired by the surface: `drop` on `onPointerCancel` and
 * on `onKeyDown`.
 */
export function useTapGesture<S>(): TapGesture<S> {
  const record = useRef<TapRecord<S> | null>(null);

  return useMemo(
    () => ({
      start: (event, state) => {
        record.current = { pointerType: event.pointerType, state };
      },
      take: () => {
        const spent = record.current;
        record.current = null;
        return spent;
      },
      drop: () => {
        record.current = null;
      },
    }),
    [],
  );
}

// One AudioContext for every synthesized sound on the page (lib/tick-sound.ts,
// lib/game-sounds.ts). Browsers cap concurrent contexts, and a page can show a
// date made of several WheelPickers next to a game, so they all share this
// one. It is created on first use and closed once every player is disposed.

type AudioContextCtor = typeof AudioContext;

let context: AudioContext | null = null;
let users = 0;

/**
 * Registers a sound player. Call the returned function when the player is
 * disposed; the context closes after the last one.
 */
export function retainAudioContext() {
  users++;
  let released = false;
  return () => {
    if (released) return;
    released = true;
    users--;
    if (users === 0 && context) {
      void context.close();
      context = null;
    }
  };
}

/**
 * The shared context, created on first call and resumed if suspended. Null
 * during SSR and in browsers without Web Audio.
 */
export function getAudioContext(): AudioContext | null {
  if (!context) {
    if (typeof window === "undefined") return null;
    const Ctor =
      window.AudioContext ??
      (window as unknown as { webkitAudioContext?: AudioContextCtor }).webkitAudioContext;
    if (!Ctor) return null;
    context = new Ctor();
  }
  // Browsers may refuse outside a user gesture. Players call this from
  // pointer and key handlers first, so a later call finds it running.
  if (context.state === "suspended") void context.resume().catch(() => undefined);
  return context;
}

"use client";

import { useEffect, useState } from "react";

/**
 * Returns true only on devices that have a true hover (mouse / trackpad).
 * Touch devices fire phantom `:hover` on tap that sticks until tap-elsewhere
 * — gate hover-only effects (scale lifts, magnetic pulls) behind this.
 */
export function useHoverCapable() {
  const [canHover, setCanHover] = useState(false);

  useEffect(() => {
    if (typeof window === "undefined" || !window.matchMedia) return;
    const mq = window.matchMedia("(hover: hover) and (pointer: fine)");
    const update = () => setCanHover(mq.matches);
    update();
    mq.addEventListener?.("change", update);
    return () => mq.removeEventListener?.("change", update);
  }, []);

  return canHover;
}

// Shared touch primitives. iOS and iPadOS run their own gestures on top of the
// page — the long-press selection callout and the selection it drags in with
// it — and they win: once the platform claims a touch it cancels ours
// mid-gesture, so a press-and-hold or a drag simply dies. Surfaces that own
// their gesture have to opt out.
//
// What the two classes below cover, precisely:
// - `-webkit-touch-callout: none` stops iOS's long-press callout. WebKit-only:
//   it is not a property other engines have, so it is inert everywhere else.
// - `user-select: none` stops the long-press selection on every engine,
//   Android included, and stops a drag from painting a selection under the
//   cursor. It is inherited, so it reaches every descendant — which is why the
//   two classes differ only in whether they apply it unconditionally.
// What neither covers:
// - Chrome for Android's long-press menu on a link or an image. No CSS
//   suppresses it; a gesture surface that wraps one needs its own
//   `onContextMenu` with `preventDefault()`.
// - The native drag of an `<img>` or `<a>` descendant. `-webkit-user-drag` is
//   not inherited and plain divs and buttons are not drag sources, so setting
//   it on the surface does nothing — the child itself needs `draggable={false}`.

/**
 * Classes for a surface that *is* the control: a thumb, a drum, a stage, a
 * handle, a hold button. Selection is suppressed on every input, because a
 * drag that highlights the control's own label is wrong on a mouse too.
 * Compose with `touch-none` when the surface also owns the scroll axis — leave
 * it off when the page must still scroll from there.
 */
export const TOUCH_GESTURE_CLASS = "select-none [-webkit-touch-callout:none]";

/**
 * The same opt-out for a gesture surface that wraps content the consumer owns:
 * a scroller, a context-menu trigger, a sheet header, a list row. Selection is
 * suppressed only where the platform runs its own press gestures — a coarse
 * pointer — so a mouse user can still select and copy that content. If the
 * gesture itself would paint a selection under the cursor, add `select-none`
 * for the duration of the gesture rather than reaching for
 * `TOUCH_GESTURE_CLASS`.
 *
 * `pointer: coarse` describes the *primary* pointer and nothing else, so a
 * hybrid machine reads it wrong in both directions: a tablet with a mouse
 * plugged in keeps touch as primary and loses mouse selection, and a laptop
 * with a touchscreen keeps the mouse as primary and leaves selection live
 * under a finger. No media query can answer per interaction — the query is
 * about the device, and the question is about the gesture in progress. The
 * default stays here because it is right on the machines that are one thing or
 * the other, and losing a selection is a nuisance; where the miss costs a
 * *gesture* instead, the surface pairs it with `holdSelection` on the press.
 */
export const TOUCH_GESTURE_CONTENT_CLASS =
  "[-webkit-touch-callout:none] pointer-coarse:select-none";

/**
 * Suppress selection on `element` for as long as a gesture is running on it,
 * whatever the primary pointer of the machine happens to be. Returns the
 * release. Inline, so it wins over the class above and is gone again the
 * moment the gesture ends.
 *
 * For the press gestures a native selection would otherwise steal — a
 * long-press that opens a menu. Elsewhere prefer the classes: a surface that
 * takes selection away for the whole session is a surface whose text nobody
 * can copy.
 */
export function holdSelection(element: HTMLElement) {
  element.style.setProperty("user-select", "none");
  element.style.setProperty("-webkit-user-select", "none");
  return () => {
    element.style.removeProperty("user-select");
    element.style.removeProperty("-webkit-user-select");
  };
}

/**
 * Pointer capture, best effort. WebKit throws `NotFoundError` when the pointer
 * is already gone by the time the handler runs — routine on iOS, where the
 * system can claim the touch first — and an uncaught throw takes the rest of
 * the handler, the gesture included, down with it. Touch pointers carry
 * implicit capture anyway, so losing it is never fatal.
 */
export function capturePointer(element: Element, pointerId: number) {
  try {
    element.setPointerCapture(pointerId);
  } catch {
    // Pointer is no longer active — implicit capture still applies on touch.
  }
}

/** Release a capture taken with `capturePointer`, ignoring a stale pointer. */
export function releasePointer(element: Element, pointerId: number) {
  try {
    if (element.hasPointerCapture(pointerId)) {
      element.releasePointerCapture(pointerId);
    }
  } catch {
    // Capture was already dropped by the browser.
  }
}

/**
 * Whether this event came from a pointer that is *hovering*: not a touch, and
 * not currently pressed. Which input the user is holding right now is not
 * something a device capability can answer — a touchscreen laptop hovers and
 * taps, and iPadOS reports a fine hovering pointer for a finger — so both
 * paths stay live and each handler branches on the event it was given.
 *
 * A pen resting on the glass is making contact, not hovering: `buttons` is the
 * tell, and it sends a pen tap down the same route a finger takes.
 *
 * This answers what an *enter* asks. A leave is the other half of a pair and
 * has to be read against the enter that started it — `useHoverGesture` in
 * `lib/hooks/use-hover-gesture` does that, and hover surfaces should use it
 * rather than asking this question twice.
 */
export const isHoveringPointer = (event: {
  pointerType: string;
  buttons: number;
}) => event.pointerType !== "touch" && event.buttons === 0;

"use client";
// beui.dev/components/blocks/plinko

import { type LucideIcon, Volume2, VolumeX, Zap, ZapOff } from "lucide-react";
import { AnimatePresence, motion, useAnimate, useReducedMotion } from "motion/react";
import { useEffect, useRef, useState } from "react";
import { ActionSwapCascadeIcon } from "@/components/motion/action-swap-cascade";
import { Button } from "@/components/motion/button";
import { Tooltip } from "@/components/motion/tooltip";
import { EASE_OUT } from "@/lib/ease";
import { createTickPlayer } from "@/lib/tick-sound";
import { cn } from "@/lib/utils";

export type PlinkoValue = string | number;

export interface PlinkoProps {
  /** Rows of pegs when `slots` isn't passed. Default 12. */
  rows?: number;
  /**
   * Slot values, left to right. Their count sets the board: n slots get
   * n - 1 rows of pegs, so `rows` is ignored when this is passed. Without it
   * the slots come from `plinkoSlots(rows)`. Fewer than 2 slots render nothing.
   */
  slots?: PlinkoValue[];
  /** Called with the slot index and its value when a ball lands. */
  onLand?: (slot: number, value: PlinkoValue) => void;
  /** Balls allowed in flight at once. Default 12. */
  maxBalls?: number;
  /** Label of the drop button. Default "Drop ball". */
  dropLabel?: string;
  /** Flash each peg as the ball hits it (controlled). Its button is hidden with reduced motion, where no pegs are hit. */
  pegFlash?: boolean;
  /** Initial peg flash state when uncontrolled. Default true. */
  defaultPegFlash?: boolean;
  /** Called when the peg flash button is toggled. */
  onPegFlashChange?: (pegFlash: boolean) => void;
  /** Tooltip and accessible name of the peg flash button. Default "Peg flash". */
  pegFlashLabel?: string;
  /** Click on every peg hit and landing (controlled). */
  sound?: boolean;
  /** Initial sound state when uncontrolled. Default false. */
  defaultSound?: boolean;
  /** Called when the sound button is toggled. */
  onSoundChange?: (sound: boolean) => void;
  /** Tooltip and accessible name of the sound button. Default "Sound". */
  soundLabel?: string;
  /** Accessible name for the board. Default "Plinko board". */
  "aria-label"?: string;
  className?: string;
}

// Board geometry in SVG units; the board scales to its container's width.
const GAP = 32; // horizontal space between pegs
const ROW = 30; // vertical space between peg rows
const PEG = 3.5;
const BALL = 7;
const TOP = 48; // first peg row
const SLOT = 34; // slot height

// A ball falls between pegs under gravity and rises a little after each hit.
// lib/ease has no ease-in, and the fall must accelerate, so these two are
// local: FALL speeds up like a drop, RISE slows down like a hop.
const FALL = [0.55, 0, 1, 0.45] as const;
const RISE = [0, 0.55, 0.45, 1] as const;
const HOP_TIME = 0.09; // seconds rising after a peg
const DROP_TIME = 0.16; // seconds falling to the next peg
const HOP_HEIGHT = 7;
// Landing tick playback rates: 0.55 in the centre slot, up to 0.95 at the edges.
const LANDING_RATE = 0.55;
const LANDING_SPREAD = 0.4;

type Ball = {
  id: number;
  path: { x: number; y: number }[];
  times: number[];
  slot: number;
  duration: number;
  /** Id of the peg hit on each row, top to bottom. */
  pegs: string[];
  /** Row of the last peg hit, -1 before the first. */
  lastRow: number;
  /** Last rendered y, to catch the frame the ball turns back up off a peg. */
  y: number;
  /** Moving up on the last frame: still on the hop from the last peg. */
  rising: boolean;
  /** Set once the ball reaches its slot; its exit fade must not land again. */
  landed?: boolean;
};

let nextBall = 0;

/** Height of the ball's centre where it touches a peg on `row`. */
const contactY = (row: number) => TOP + row * ROW - PEG - BALL;

/** Random left/right steps from the top peg to a slot, as keyframes. */
function plan(rows: number, width: number): Omit<Ball, "id" | "lastRow" | "y" | "rising"> {
  const center = width / 2;
  const points = [{ x: center, y: BALL }]; // enters fully inside the board
  const steps: number[] = [0.22]; // first fall from the chute to the top peg
  const pegs: string[] = [];
  let k = 0; // rightward steps so far
  for (let row = 0; row < rows; row++) {
    const x = center + (k - row / 2) * GAP;
    pegs.push(`${row}-${k}`);
    points.push({ x, y: contactY(row) });
    const right = Math.random() < 0.5;
    points.push({ x: x + (right ? GAP / 4 : -GAP / 4), y: contactY(row) - HOP_HEIGHT });
    steps.push(HOP_TIME, DROP_TIME);
    if (right) k++;
  }
  // Come to rest just inside the slot's top edge, clear of its label.
  const slotY = TOP + rows * ROW - BALL + 3;
  points.push({ x: center + (k - rows / 2) * GAP, y: slotY });
  const duration = steps.reduce((sum, step) => sum + step, 0);
  const times = [0];
  for (const step of steps) times.push(times[times.length - 1] + step / duration);
  return { path: points, times, slot: k, duration, pegs };
}

/**
 * A Plinko board: balls drop through rows of pegs, bounce left or right off
 * each one and land in a slot. Pegs flash when hit and the slot pulses on
 * landing. Optional sound clicks on every peg and lands with a thunk that
 * brightens toward the rarer edge slots. With reduced motion a ball lands at
 * once.
 */
export function Plinko({
  rows: rowsProp = 12,
  slots,
  onLand,
  maxBalls = 12,
  dropLabel = "Drop ball",
  pegFlash,
  defaultPegFlash = true,
  onPegFlashChange,
  pegFlashLabel = "Peg flash",
  sound,
  defaultSound = false,
  onSoundChange,
  soundLabel = "Sound",
  "aria-label": ariaLabel = "Plinko board",
  className,
}: PlinkoProps) {
  const reduce = useReducedMotion() ?? false;
  const [scope, animate] = useAnimate();
  const [balls, setBalls] = useState<Ball[]>([]);
  const [announcement, setAnnouncement] = useState("");
  // The last slot hit stays marked after its flash fades.
  const [lastSlot, setLastSlot] = useState<number | null>(null);
  const [internalSound, setInternalSound] = useState(defaultSound);
  const soundOn = sound ?? internalSound;
  const [internalFlash, setInternalFlash] = useState(defaultPegFlash);
  const flashOn = pegFlash ?? internalFlash;

  // Landings are numbered so a second ball in the same slot still changes
  // the live region's text and is announced again.
  const landings = useRef(0);
  // Each player cuts its own previous tick, so landings get their own player:
  // another ball's peg click would otherwise cut the longer landing thunk.
  const players = useRef<Record<"peg" | "landing", ReturnType<typeof createTickPlayer>> | null>(null);
  const getPlayers = () => {
    if (!players.current) players.current = { peg: createTickPlayer(), landing: createTickPlayer() };
    return players.current;
  };
  useEffect(
    () => () => {
      players.current?.peg.dispose();
      players.current?.landing.dispose();
      players.current = null;
    },
    [],
  );

  const togglePegFlash = () => {
    const next = !flashOn;
    if (pegFlash === undefined) setInternalFlash(next);
    onPegFlashChange?.(next);
  };

  const toggleSound = () => {
    const next = !soundOn;
    // Unlock audio inside the click, where browsers allow it.
    if (next) getPlayers().peg.prepare();
    if (sound === undefined) setInternalSound(next);
    onSoundChange?.(next);
  };

  const labels = slots ?? plinkoSlots(rowsProp);
  const rows = labels.length - 1;
  const invalid = labels.length < 2;
  useEffect(() => {
    if (process.env.NODE_ENV !== "production" && invalid)
      console.warn("Plinko needs at least 2 slots; it renders nothing until it has them.");
  }, [invalid]);

  // A new board size makes every ball in flight point at pegs that moved, so
  // drop them in the same render. Clearing them in an effect would mount them
  // in the new board first, and their exit would land in a slot that may not
  // exist any more.
  const [boardRows, setBoardRows] = useState(rows);
  if (boardRows !== rows) {
    setBoardRows(rows);
    setBalls([]);
    setLastSlot(null);
  }

  const width = (rows + 2) * GAP;
  const height = TOP + rows * ROW + SLOT;
  // Each row runs one peg past the ball's reach on both sides, so the board
  // reads as a triangle that widens down to the slots.
  const pegs = Array.from({ length: rows }, (_, row) =>
    Array.from({ length: row + 3 }, (_, i) => ({
      id: `${row}-${i - 1}`,
      x: width / 2 + (i - 1 - row / 2) * GAP,
      y: TOP + row * ROW,
    })),
  ).flat();

  const land = (slot: number) => {
    animate(`[data-slot="${slot}"]`, { opacity: [0.9, 0] }, { duration: 0.3, ease: EASE_OUT });
    // A lower thunk than a peg hit marks the landing. It brightens toward
    // the edges, where landing is rarest, so a good drop is heard.
    if (soundOn)
      getPlayers().landing.play(LANDING_RATE + LANDING_SPREAD * (Math.abs(slot - rows / 2) / (rows / 2)));
    setLastSlot(slot);
    landings.current++;
    setAnnouncement(`Ball ${landings.current} landed in slot ${slot + 1}: ${labels[slot]}`);
    onLand?.(slot, labels[slot]);
  };

  // Flash and click a peg on the frame the ball turns back up off it. Reading
  // the ball's own frames keeps both on its clock: a background tab pauses
  // them together. motion rebinds onUpdate every render, so the settings
  // read here are always current.
  const hitPegs = (ball: Ball, y: number) => {
    const rising = y < ball.y;
    // The row comes from where the ball turned, not from counting turns, so
    // a slow frame that skips a whole hop misses only that peg. Both frames
    // sit within a hop height above the contact, which rounds to its row.
    const row = Math.round((Math.max(ball.y, y) - contactY(0)) / ROW);
    if (rising && !ball.rising && row > ball.lastRow && row < ball.pegs.length) {
      ball.lastRow = row;
      const peg = ball.pegs[row];
      if (flashOn) {
        // Fast attack, slower decay: the pop peaks a third of the way in.
        animate(
          `[data-peg="${peg}"]`,
          { scale: [1, 1.8, 1], opacity: [0.4, 1, 0.4] },
          { duration: 0.3, times: [0, 0.3, 1], ease: EASE_OUT },
        );
      }
      if (soundOn) getPlayers().peg.play();
    }
    ball.y = y;
    ball.rising = rising;
  };

  const full = balls.length >= maxBalls;
  const drop = () => {
    if (full) return;
    const ball: Ball = { id: nextBall++, lastRow: -1, y: 0, rising: false, ...plan(rows, width) };
    if (soundOn) getPlayers().peg.prepare();
    if (reduce) {
      land(ball.slot);
      return;
    }
    setBalls((current) => [...current, ball]);
  };

  if (invalid) return null;

  return (
    <section aria-label={ariaLabel} className={cn("flex w-full flex-col items-center gap-4", className)}>
      <svg
        ref={scope}
        viewBox={`0 0 ${width} ${height}`}
        // Grow with the board so pegs keep the same on-screen spacing at any
        // row count, until the container's width runs out.
        style={{ maxWidth: width * 1.4 }}
        className="w-full"
        aria-hidden="true"
      >
        {pegs.map((peg) => (
          <circle
            key={peg.id}
            data-peg={peg.id}
            cx={peg.x}
            cy={peg.y}
            r={PEG}
            className="fill-foreground opacity-40 [transform-box:fill-box] [transform-origin:center]"
          />
        ))}

        {labels.map((label, slot) => {
          const x = width / 2 + (slot - rows / 2) * GAP - GAP / 2;
          const y = TOP + rows * ROW;
          return (
            // biome-ignore lint/suspicious/noArrayIndexKey: slots are positional
            <g key={slot}>
              <rect
                x={x + 2}
                y={y}
                width={GAP - 4}
                height={SLOT - 4}
                rx={6}
                className={slot === lastSlot ? "fill-primary/20" : "fill-muted"}
              />
              <rect data-slot={slot} x={x + 2} y={y} width={GAP - 4} height={SLOT - 4} rx={6} className="fill-primary opacity-0" />
              <text
                x={x + GAP / 2}
                y={y + (SLOT - 4) / 2}
                textAnchor="middle"
                dominantBaseline="central"
                // Long values shrink to fit their slot.
                fontSize={Math.min(9, (GAP - 8) / (String(label).length * 0.6))}
                className={cn("fill-foreground tabular-nums", slot === lastSlot ? "font-semibold" : "font-medium")}
              >
                {label}
              </text>
            </g>
          );
        })}

        {/* Keyed by size: balls from a board that changed size leave at once. */}
        <AnimatePresence key={rows}>
        {balls.map((ball) => (
          <motion.circle
            key={ball.id}
            r={BALL}
            cx={0}
            cy={0}
            className="fill-primary"
            // Enters from 90% scale and transparent, never from nothing. The
            // circle is drawn at 0,0 and placed by translate, so it scales
            // about its own centre.
            initial={{ x: ball.path[0].x, y: ball.path[0].y, opacity: 0, scale: 0.9 }}
            animate={{
              x: ball.path.map((point) => point.x),
              y: ball.path.map((point) => point.y),
              opacity: 1,
              scale: 1,
            }}
            // Settle into the slot: a short fade with a small drop.
            exit={{
              opacity: 0,
              y: (ball.path.at(-1)?.y ?? 0) + 4,
              transition: { duration: 0.12, ease: EASE_OUT },
            }}
            transition={{
              opacity: { duration: 0.15, ease: EASE_OUT },
              scale: { duration: 0.15, ease: EASE_OUT },
              x: { duration: ball.duration, times: ball.times, ease: "linear" },
              y: {
                duration: ball.duration,
                times: ball.times,
                // Fall into the first peg, then hop up and fall down per row.
                ease: ball.times.slice(1).map((_, i) => (i % 2 === 1 ? RISE : FALL)),
              },
            }}
            onUpdate={(latest) => {
              if (typeof latest.y === "number") hitPegs(ball, latest.y);
            }}
            onAnimationComplete={() => {
              if (ball.landed) return;
              ball.landed = true;
              land(ball.slot);
              setBalls((current) => current.filter((other) => other.id !== ball.id));
            }}
          />
        ))}
        </AnimatePresence>
      </svg>

      <div className="flex items-center gap-2">
        {/* aria-disabled, not disabled: a disabled button drops keyboard focus. */}
        <Button
          onClick={drop}
          aria-disabled={full || undefined}
          pressScale={0.96}
          className="aria-disabled:cursor-not-allowed aria-disabled:opacity-50"
        >
          {dropLabel}
        </Button>
        {/* With reduced motion balls land at once and hit no pegs. */}
        {reduce ? null : (
          <ToggleButton on={flashOn} onToggle={togglePegFlash} label={pegFlashLabel} onIcon={Zap} offIcon={ZapOff} />
        )}
        <ToggleButton on={soundOn} onToggle={toggleSound} label={soundLabel} onIcon={Volume2} offIcon={VolumeX} />
      </div>
      <p aria-live="polite" className="sr-only">
        {announcement}
      </p>
    </section>
  );
}

/**
 * Slot values for a board of `rows`: `center` in the middle, growing evenly
 * (geometrically) to `edge` at both ends, where landing is rarest. Rounded to
 * readable numbers: 12 rows give 100, 50, 20, 10, 5, 2, 1, 2, 5, 10, 20, 50, 100.
 * Values from 1 to 10 round to whole numbers, the rest to one significant
 * figure, so fractional curves work: 8 rows with `center: 0.5, edge: 10`
 * give 10, 5, 2, 1, 0.5, 1, 2, 5, 10.
 * `rows` is rounded to at least 1, `center` raised to at least 0.01 and
 * `edge` to at least `center`.
 */
export function plinkoSlots(
  rowCount: number,
  options: { center?: number; edge?: number } = {},
): number[] {
  const rows = Math.max(1, Math.round(rowCount) || 1);
  // Any positive center works; zero or below would divide by zero.
  const center = Math.max(0.01, options.center ?? 1);
  const edge = Math.max(center, options.edge ?? 100);
  const half = rows / 2;
  return Array.from({ length: rows + 1 }, (_, slot) => {
    const value = center * (edge / center) ** (Math.abs(slot - half) / half);
    if (value >= 1 && value < 10) return Math.round(value);
    // One significant figure: 46 reads as 50, 315 as 300, 0.46 as 0.5.
    return Number(value.toPrecision(1));
  });
}

/** An icon button that shows and toggles one on/off setting. */
function ToggleButton({
  on,
  onToggle,
  label,
  onIcon: OnIcon,
  offIcon: OffIcon,
}: {
  on: boolean;
  onToggle: () => void;
  label: string;
  onIcon: LucideIcon;
  offIcon: LucideIcon;
}) {
  return (
    // aria-label names the button; the tooltip shows the same label on hover
    // and focus. Tooltip's asLabel would hydrate differently from the server.
    <Tooltip content={label} side="top">
      <Button
        variant="secondary"
        onClick={onToggle}
        aria-label={label}
        aria-pressed={on}
        pressScale={0.96}
        // Full strength when on, muted when off: the slash alone is a thin cue.
        className={cn("w-10 px-0", on ? "text-foreground" : "text-muted-foreground")}
      >
        <ActionSwapCascadeIcon value={on ? "on" : "off"} className="size-4">
          {on ? <OnIcon aria-hidden="true" className="size-4" /> : <OffIcon aria-hidden="true" className="size-4" />}
        </ActionSwapCascadeIcon>
      </Button>
    </Tooltip>
  );
}