{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "core-circle-of-fifths",
  "type": "registry:ui",
  "title": "Circle of Fifths",
  "description": "A pitch-class histogram plotted on the wheel where neighbouring slots are a fifth apart, so the seven notes of any key form one unbroken arc and a modulation is a short slide round the rim. An optional needle points at the tonal centre, its length and opacity scaled by confidence so an ambiguous passage never gets a decisive-looking answer.",
  "dependencies": [
    "maruaudio@>=0.0.3 <0.1.0"
  ],
  "registryDependencies": [],
  "files": [
    {
      "path": "components/ui/circle-of-fifths.tsx",
      "content": "/**\n * Source: https://maru.audio/ui-kit/circle-of-fifths\n * Copyright © [Maru](https://maru.audio)\n *\n * Maru UI Kit — https://maru.audio/ui-kit\n *\n * Installed from the Maru UI registry. This file is yours now: edit it\n * freely, it will not be overwritten unless you re-run the add command.\n *\n * Keep this item’s companion files and CSS imports together. Dependencies\n * declared by the registry are installed with the source.\n */\n/**\n * Circle of Fifths — a pitch-class histogram plotted on the wheel, with an\n * optional tonal-centre needle.\n *\n * The circle of fifths is the layout that makes tonality visible. Neighbouring\n * slots are a fifth apart, so the seven notes of any key form one unbroken arc\n * and a modulation is a short slide round the rim — where a chromatic keyboard\n * scatters the same information all over the octave. Feed it what the music\n * actually played and the shape of the key falls out of the geometry.\n *\n * Each pitch class becomes a radial bar at its circle-of-fifths angle, its\n * length proportional to how much that note sounded. The needle, when supplied,\n * points at the tonal centre: its length and opacity both scale with strength,\n * so an ambiguous or chromatic passage gets a short faint needle rather than a\n * confident lie. Compute one with `tonalCenter` from `lib/tonal-center` — this\n * component deliberately does not, so that a caller with a precomputed centre\n * (a snapshot, a server analysis, a smoothed running estimate) renders through\n * the same wheel as one analysing live.\n *\n * `weights` is CHROMATIC-indexed — index 0 is C, 11 is B — and PEAK-NORMALISED\n * internally, so its units are yours: note counts, seconds held, velocity sums.\n * The component places each into its fifths slot; you never reorder anything.\n *\n * Ported from codex-music-mono's `CircleOfFifthsWheel.vue`. The geometry is\n * carried over exactly — same radius, same inner/outer bar span, same opacity\n * ramps — so the two render identically. Deliberate deviations:\n *\n *   - The bar geometry is an exported pure function (`cofBarGeometry`) rather\n *     than a Vue `computed`, so it is testable in Node and reusable by anything\n *     that needs the same layout.\n *   - Colours come from the kit's `token()` rather than `currentColor` plus a\n *     bare `--accent`, so it sits correctly on a dark instrument face and on a\n *     light docs page without the host setting anything up.\n *   - `highlightPcs` is new: a ring-mark on the pitch classes sounding right\n *     now, which is what lets the wheel double as a live chord readout rather\n *     than only a summary of the past.\n *\n * SSR-safe: pure SVG computed from props, no measurement, no effects.\n *\n * Styling comes from CSS custom properties — see `lib/control-theme/theme.ts`.\n */\n\nimport type { CSSProperties } from \"react\"\nimport { pitchClassName } from \"maruaudio/ui/shared/music-theory-pitch-class\"\nimport { token } from \"maruaudio/ui/shared/theme\"\n\nconst TWO_PI = Math.PI * 2\n\n/** One bar's endpoints, plus the slot it belongs to. */\nexport interface CofBar {\n  /** Circle-of-fifths slot, 0..11 — 0 is C at the top, going clockwise. */\n  cof: number\n  /** The pitch class this slot holds: `(cof * 7) % 12`. */\n  pc: number\n  /** Peak-normalised weight for that pitch class, 0..1. */\n  weight: number\n  /** Angle of the slot in radians, 0 at twelve o'clock, clockwise. */\n  angle: number\n  x1: number\n  y1: number\n  x2: number\n  y2: number\n  /** Suggested stroke opacity, ramped so even a silent slot stays faintly visible. */\n  opacity: number\n}\n\n/** The wheel's geometry: everything derived from `size` alone. */\nexport interface CofGeometry {\n  size: number\n  cx: number\n  cy: number\n  /** Ring radius. The 28px inset leaves room for the rim labels. */\n  r: number\n}\n\n/** Wheel geometry for a given size. */\nexport function cofGeometry(size: number): CofGeometry {\n  return { size, cx: size / 2, cy: size / 2, r: size / 2 - 28 }\n}\n\n/**\n * The twelve radial bars for a pitch-class histogram, in circle-of-fifths order.\n *\n * Pure: no DOM, no React. `weights` is chromatic-indexed (0 = C) and is\n * peak-normalised here — the largest weight reaches full length whatever its\n * units, and an all-zero histogram yields twelve stubs rather than a division by\n * zero. Bars run from `r * 0.16` out to `+ r * 0.8 * weight`, leaving the hub\n * clear for the needle.\n *\n * Returned in slot order (index 0 = C at the top), each carrying the pitch class\n * it represents, so a caller can label or recolour without redoing the mapping.\n */\n/** Six decimals, so server rendering and browser hydration agree despite platform trigonometry rounding. */\nconst six = (value: number) => Number(value.toFixed(6))\n\nexport function cofBarGeometry(weights: ReadonlyArray<number>, size: number): CofBar[] {\n  const { cx, cy, r } = cofGeometry(size)\n\n  // Peak-normalise. The epsilon floor is what keeps an empty histogram finite.\n  let max = 1e-9\n  for (let i = 0; i < 12; i += 1) {\n    const v = weights?.[i]\n    if (typeof v === \"number\" && Number.isFinite(v) && v > max) max = v\n  }\n\n  return Array.from({ length: 12 }, (_, cof) => {\n    const pc = (cof * 7) % 12\n    const raw = weights?.[pc]\n    const value = typeof raw === \"number\" && Number.isFinite(raw) ? raw : 0\n    const weight = Math.max(0, value / max)\n    const angle = (cof / 12) * TWO_PI\n    const inner = r * 0.16\n    const outer = inner + r * 0.8 * weight\n    // Screen mapping: sine on x, minus cosine on y — angle 0 at twelve\n    // o'clock, increasing clockwise.\n    const sin = Math.sin(angle)\n    const cos = Math.cos(angle)\n    return {\n      cof,\n      pc,\n      weight,\n      angle,\n      x1: six(cx + sin * inner),\n      y1: six(cy - cos * inner),\n      x2: six(cx + sin * outer),\n      y2: six(cy - cos * outer),\n      opacity: 0.35 + 0.55 * weight,\n    }\n  })\n}\n\n/** A tonal centre to point at: a continuous angle plus a 0..1 confidence. */\nexport interface CofNeedle {\n  /** Angle in radians, 0 = C at the top, clockwise. */\n  angleRad: number\n  /** Confidence 0..1 — drives both the needle's length and its opacity. */\n  strength: number\n}\n\nexport interface CircleOfFifthsProps {\n  /**\n   * Length-12 pitch-class weights in CHROMATIC order (0 = C … 11 = B),\n   * peak-normalised internally. Units are arbitrary.\n   */\n  weights: ReadonlyArray<number>\n  /** Bar and needle colour. Defaults to the accent token. */\n  color?: string\n  /** Overall square size in pixels. */\n  size?: number\n  /**\n   * The tonal centre to point at, e.g. from `tonalCenter(weights)`. Pass null\n   * or omit for no needle.\n   */\n  needle?: CofNeedle | null\n  /** Draw the pitch-class names around the rim. */\n  showLabels?: boolean\n  /**\n   * Pitch classes to ring-mark — typically the chord sounding right now. Given\n   * chromatically; reduced mod 12, so raw MIDI note numbers work too.\n   */\n  highlightPcs?: ReadonlyArray<number>\n  className?: string\n  style?: CSSProperties\n  \"aria-label\"?: string\n}\n\nexport function CircleOfFifths({\n  weights,\n  color,\n  size = 240,\n  needle = null,\n  showLabels = true,\n  highlightPcs,\n  className,\n  style,\n  \"aria-label\": ariaLabel,\n}: CircleOfFifthsProps) {\n  const { cx, cy, r } = cofGeometry(size)\n  const bars = cofBarGeometry(weights, size)\n  const stroke = color ?? token.accent\n\n  const lit = new Set((highlightPcs ?? []).map((n) => ((n % 12) + 12) % 12))\n\n  // The needle, if there is one. Length and opacity both track strength, so a\n  // weak centre reads as weak instead of merely pointing somewhere else.\n  const strength = needle ? Math.min(1, Math.max(0, needle.strength)) : 0\n  const needleLength = r * (0.25 + 0.7 * strength)\n  const needleX = needle ? cx + Math.sin(needle.angleRad) * needleLength : 0\n  const needleY = needle ? cy - Math.cos(needle.angleRad) * needleLength : 0\n  const needleOpacity = 0.35 + 0.65 * strength\n\n  return (\n    <svg\n      className={`uikit-control${className ? ` ${className}` : \"\"}`}\n      width={size}\n      height={size}\n      viewBox={`0 0 ${size} ${size}`}\n      role=\"img\"\n      aria-label={ariaLabel ?? \"Pitch-class weights on the circle of fifths\"}\n      style={{ display: \"block\", overflow: \"visible\", ...style }}\n    >\n      {/* The rim. */}\n      <circle cx={cx} cy={cy} r={r} fill=\"none\" stroke={token.border} strokeWidth={1.5} />\n\n      {/* Twelve faint spokes, one per slot — they give the eye a grid to read\n          the bar lengths against without competing with the bars. */}\n      {bars.map((bar) => (\n        <line\n          key={`spoke-${bar.cof}`}\n          x1={cx}\n          y1={cy}\n          x2={six(cx + Math.sin(bar.angle) * r)}\n          y2={six(cy - Math.cos(bar.angle) * r)}\n          stroke={token.border}\n          strokeWidth={1}\n          opacity={0.35}\n        />\n      ))}\n\n      {/* The histogram itself. */}\n      {bars.map((bar) => (\n        <line\n          key={`bar-${bar.cof}`}\n          x1={bar.x1}\n          y1={bar.y1}\n          x2={bar.x2}\n          y2={bar.y2}\n          stroke={stroke}\n          strokeWidth={7}\n          strokeLinecap=\"round\"\n          opacity={bar.opacity}\n        />\n      ))}\n\n      {/* Ring-marks on the sounding pitch classes. Drawn at the rim so they\n          read independently of how long the bar underneath happens to be. */}\n      {bars\n        .filter((bar) => lit.has(bar.pc))\n        .map((bar) => (\n          <circle\n            key={`lit-${bar.cof}`}\n            cx={six(cx + Math.sin(bar.angle) * r)}\n            cy={six(cy - Math.cos(bar.angle) * r)}\n            r={5}\n            fill=\"none\"\n            stroke={stroke}\n            strokeWidth={2}\n          />\n        ))}\n\n      {/* Rim labels, in fifths order: C G D A E B F♯ C♯ G♯ D♯ A♯ F. */}\n      {showLabels\n        && bars.map((bar) => (\n          <text\n            key={`label-${bar.cof}`}\n            x={six(cx + Math.sin(bar.angle) * (r + 14))}\n            y={six(cy - Math.cos(bar.angle) * (r + 14))}\n            textAnchor=\"middle\"\n            dominantBaseline=\"middle\"\n            fill={lit.has(bar.pc) ? token.text : token.textMuted}\n            fontFamily={token.font}\n            fontSize={11}\n            fontWeight={lit.has(bar.pc) ? 600 : 400}\n          >\n            {pitchClassName(bar.pc, \"unicode-sharp\")}\n          </text>\n        ))}\n\n      {needle && (\n        <>\n          <line\n            x1={cx}\n            y1={cy}\n            x2={six(needleX)}\n            y2={six(needleY)}\n            stroke={stroke}\n            strokeWidth={3}\n            strokeLinecap=\"round\"\n            opacity={needleOpacity}\n          />\n          <circle cx={six(needleX)} cy={six(needleY)} r={5} fill={stroke} opacity={needleOpacity} />\n        </>\n      )}\n\n      {/* The hub, drawn last so the needle emerges from under it. */}\n      <circle cx={cx} cy={cy} r={3} fill={token.textMuted} />\n    </svg>\n  )\n}\n",
      "type": "registry:component",
      "target": "@ui/circle-of-fifths.tsx"
    }
  ]
}
