{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "spectrum",
  "title": "Spectrum",
  "description": "A frequency spectrum analyser drawn on canvas as bars, a line or an area, with peak hold, a grid and frequency and level axes.",
  "registryDependencies": [
    "@audiocn/core",
    "@audiocn/use-frame-source",
    "@audiocn/use-reduced-motion",
    "@audiocn/use-visibility"
  ],
  "files": [
    {
      "path": "components/ui/spectrum.tsx",
      "content": "\"use client\";\n\nimport { createContext, useContext, useEffect, useMemo, useRef } from \"react\";\nimport type { ComponentProps, CSSProperties, RefObject } from \"react\";\n\nimport { useFrameSource } from \"@/hooks/use-frame-source\";\nimport { useReducedMotion } from \"@/hooks/use-reduced-motion\";\nimport { useVisibility } from \"@/hooks/use-visibility\";\nimport { clamp } from \"@/lib/audio/decibels\";\nimport { subscribeFrame } from \"@/lib/audio/frame-loop\";\nimport { linearTaper, logTaper } from \"@/lib/audio/taper\";\nimport type { FrameSource, Taper, VisualFrame } from \"@/lib/audio/types\";\nimport { cn } from \"@/lib/utils\";\n\nconst COLOR_REFRESH_FRAMES = 30;\nconst PEAK_RELEASE_PER_FRAME = 0.985;\n/** The frame length PEAK_RELEASE_PER_FRAME is tuned for. */\nconst FRAME_MS = 1000 / 60;\nconst REDUCED_MOTION_INTERVAL_MS = 250;\nconst LEVEL_TICK_DB = 12;\nconst DEFAULT_FREQUENCY_TICKS = [100, 1000, 10_000];\n\ninterface SpectrumContextValue {\n  minDb: number;\n  maxDb: number;\n  minHz: number;\n  maxHz: number;\n  frequencyTaper: Taper;\n  variant: \"bars\" | \"line\" | \"area\";\n  peakHold: boolean;\n  grid: boolean;\n  frameRef: RefObject<VisualFrame | null>;\n  /** Bumped on every frame, so each canvas knows whether it has painted it. */\n  versionRef: RefObject<number>;\n}\n\nconst SpectrumContext = createContext<SpectrumContextValue | null>(null);\n\nconst useSpectrum = (part: string) => {\n  const context = useContext(SpectrumContext);\n  if (!context) {\n    throw new Error(`${part} must be used inside Spectrum.`);\n  }\n  return context;\n};\n\nconst formatHz = (hz: number) => (hz >= 1000 ? `${hz / 1000}k` : String(hz));\n\nconst formatLevel = (db: number) => String(Math.round(db));\n\ninterface Size {\n  width: number;\n  height: number;\n  ratio: number;\n}\n\ninterface Colors {\n  grid: string;\n  line: string;\n  peak: string;\n}\n\nconst readColors = (canvas: HTMLCanvasElement): Colors => {\n  const style = getComputedStyle(canvas);\n  return {\n    grid: style.getPropertyValue(\"--spectrum-grid\").trim() || style.color,\n    line: style.getPropertyValue(\"--spectrum\").trim() || style.color,\n    peak: style.getPropertyValue(\"--spectrum-peak\").trim() || style.color,\n  };\n};\n\nconst drawGrid = (\n  context: CanvasRenderingContext2D,\n  size: Size,\n  settings: SpectrumContextValue,\n  color: string\n) => {\n  const { frequencyTaper, maxDb, maxHz, minDb, minHz } = settings;\n  const span = maxDb - minDb;\n  context.strokeStyle = color;\n  context.lineWidth = 1;\n  context.beginPath();\n  for (const db of [maxDb, maxDb - span / 3, maxDb - (span * 2) / 3]) {\n    const y = Math.round((1 - (db - minDb) / span) * size.height) + 0.5;\n    context.moveTo(0, y);\n    context.lineTo(size.width, y);\n  }\n  for (const hz of DEFAULT_FREQUENCY_TICKS) {\n    if (hz > minHz && hz < maxHz) {\n      const x = Math.round(frequencyTaper.toPosition(hz) * size.width) + 0.5;\n      context.moveTo(x, 0);\n      context.lineTo(x, size.height);\n    }\n  }\n  context.stroke();\n};\n\nconst drawBars = (\n  context: CanvasRenderingContext2D,\n  size: Size,\n  bands: Float32Array\n) => {\n  const slot = size.width / bands.length;\n  const gap = Math.min(2, slot * 0.25);\n  for (const [index, band] of bands.entries()) {\n    const barHeight = clamp(band, 0, 1) * size.height;\n    context.fillRect(\n      index * slot + gap / 2,\n      size.height - barHeight,\n      Math.max(1, slot - gap),\n      barHeight\n    );\n  }\n};\n\nconst drawCurve = (\n  context: CanvasRenderingContext2D,\n  size: Size,\n  bands: Float32Array,\n  filled: boolean\n) => {\n  const slot = size.width / bands.length;\n  context.lineWidth = 1.5;\n  context.lineJoin = \"round\";\n  context.beginPath();\n  for (const [index, band] of bands.entries()) {\n    const x = (index + 0.5) * slot;\n    const y = size.height - clamp(band, 0, 1) * size.height;\n    if (index === 0) {\n      context.moveTo(x, y);\n    } else {\n      context.lineTo(x, y);\n    }\n  }\n  if (filled) {\n    context.lineTo((bands.length - 0.5) * slot, size.height);\n    context.lineTo(0.5 * slot, size.height);\n    context.closePath();\n    context.globalAlpha = 0.3;\n    context.fill();\n    context.globalAlpha = 1;\n  }\n  context.stroke();\n};\n\n/** Draws held peaks and reports whether any are still falling. */\nconst drawPeaks = (\n  context: CanvasRenderingContext2D,\n  size: Size,\n  bands: Float32Array,\n  peaks: Float32Array,\n  release: number\n) => {\n  const slot = size.width / bands.length;\n  let falling = false;\n  for (const [index, band] of bands.entries()) {\n    const level = clamp(band, 0, 1);\n    const held = Math.max(level, (peaks[index] ?? 0) * release);\n    peaks[index] = held;\n    if (held > level + 0.001) {\n      falling = true;\n    }\n    context.fillRect(\n      index * slot,\n      size.height - held * size.height - 1,\n      Math.max(1, slot - 1),\n      2\n    );\n  }\n  return falling;\n};\n\nexport const SpectrumCanvas = ({\n  className,\n  ...props\n}: ComponentProps<\"canvas\">) => {\n  const settings = useSpectrum(\"SpectrumCanvas\");\n  const reducedMotion = useReducedMotion();\n  const canvasRef = useRef<HTMLCanvasElement>(null);\n  const visibleRef = useVisibility(canvasRef);\n\n  useEffect(() => {\n    const canvas = canvasRef.current;\n    const context = canvas?.getContext(\"2d\");\n    if (!(canvas && context)) {\n      return;\n    }\n    const { frameRef, grid, peakHold, variant, versionRef } = settings;\n    const size: Size = { height: 0, ratio: 1, width: 0 };\n    let colors = readColors(canvas);\n    let framesSinceColor = 0;\n    let peaks = new Float32Array(0);\n    let lastPaintMs = 0;\n    // Each canvas keeps its own state, so two in one Spectrum both paint.\n    let dirty = true;\n    let paintedVersion = -1;\n\n    const resize = () => {\n      const rect = canvas.getBoundingClientRect();\n      size.ratio = window.devicePixelRatio || 1;\n      size.width = rect.width;\n      size.height = rect.height;\n      canvas.width = Math.max(1, Math.round(rect.width * size.ratio));\n      canvas.height = Math.max(1, Math.round(rect.height * size.ratio));\n      dirty = true;\n    };\n    resize();\n    const observer = new ResizeObserver(resize);\n    observer.observe(canvas);\n\n    const shouldPaint = (nowMs: number) => {\n      framesSinceColor += 1;\n      if (framesSinceColor >= COLOR_REFRESH_FRAMES) {\n        framesSinceColor = 0;\n        const next = readColors(canvas);\n        if (\n          next.grid !== colors.grid ||\n          next.line !== colors.line ||\n          next.peak !== colors.peak\n        ) {\n          colors = next;\n          dirty = true;\n        }\n      }\n      const stale = dirty || versionRef.current !== paintedVersion;\n      if (!stale || size.width === 0 || !visibleRef.current) {\n        return false;\n      }\n      return (\n        !reducedMotion || nowMs - lastPaintMs >= REDUCED_MOTION_INTERVAL_MS\n      );\n    };\n\n    const draw = (nowMs: number) => {\n      if (!shouldPaint(nowMs)) {\n        return;\n      }\n      const elapsedMs = lastPaintMs === 0 ? 0 : nowMs - lastPaintMs;\n      lastPaintMs = nowMs;\n      dirty = false;\n      paintedVersion = versionRef.current;\n      context.setTransform(size.ratio, 0, 0, size.ratio, 0, 0);\n      context.clearRect(0, 0, size.width, size.height);\n      if (grid) {\n        drawGrid(context, size, settings, colors.grid);\n      }\n      const bands = frameRef.current?.bands;\n      if (!bands || bands.length === 0) {\n        return;\n      }\n      context.fillStyle = colors.line;\n      context.strokeStyle = colors.line;\n      if (variant === \"bars\") {\n        drawBars(context, size, bands);\n      } else {\n        drawCurve(context, size, bands, variant === \"area\");\n      }\n      if (peakHold) {\n        if (peaks.length !== bands.length) {\n          peaks = new Float32Array(bands.length);\n        }\n        context.fillStyle = colors.peak;\n        // Decay by elapsed time, not per paint, so peaks fall at the same\n        // speed at 60 Hz, at 120 Hz and with reduced motion.\n        dirty = drawPeaks(\n          context,\n          size,\n          bands,\n          peaks,\n          PEAK_RELEASE_PER_FRAME ** (elapsedMs / FRAME_MS)\n        );\n      }\n    };\n\n    const unsubscribe = subscribeFrame(draw);\n    return () => {\n      unsubscribe();\n      observer.disconnect();\n    };\n  }, [reducedMotion, settings, visibleRef]);\n\n  return (\n    <canvas\n      aria-hidden\n      className={cn(\n        \"[grid-column:2] [grid-row:1] size-full min-h-0\",\n        className\n      )}\n      data-slot=\"spectrum-canvas\"\n      ref={canvasRef}\n      {...props}\n    />\n  );\n};\n\nexport interface SpectrumFrequencyAxisProps extends ComponentProps<\"div\"> {\n  /** Default 100 Hz, 1 kHz and 10 kHz. */\n  ticks?: number[];\n  format?: (hz: number) => string;\n}\n\nexport const SpectrumFrequencyAxis = ({\n  ticks = DEFAULT_FREQUENCY_TICKS,\n  format = formatHz,\n  className,\n  ...props\n}: SpectrumFrequencyAxisProps) => {\n  const { frequencyTaper, maxHz, minHz } = useSpectrum(\"SpectrumFrequencyAxis\");\n  return (\n    <div\n      aria-hidden\n      className={cn(\n        \"text-muted-foreground relative [grid-column:2] [grid-row:2] h-4 text-[0.625rem] tabular-nums\",\n        className\n      )}\n      data-slot=\"spectrum-frequency-axis\"\n      {...props}\n    >\n      {ticks\n        .filter((hz) => hz >= minHz && hz <= maxHz)\n        .map((hz) => (\n          <span\n            className=\"absolute top-0 left-(--tick-position) -translate-x-1/2\"\n            key={hz}\n            style={\n              {\n                \"--tick-position\": `${frequencyTaper.toPosition(hz) * 100}%`,\n              } as CSSProperties\n            }\n          >\n            {format(hz)}\n          </span>\n        ))}\n    </div>\n  );\n};\n\nexport interface SpectrumLevelAxisProps extends ComponentProps<\"div\"> {\n  /** Default: every 12 dB inside the range. */\n  ticks?: number[];\n  format?: (db: number) => string;\n}\n\nexport const SpectrumLevelAxis = ({\n  ticks,\n  format = formatLevel,\n  className,\n  ...props\n}: SpectrumLevelAxisProps) => {\n  const { maxDb, minDb } = useSpectrum(\"SpectrumLevelAxis\");\n  const values =\n    ticks ??\n    Array.from(\n      { length: Math.floor((maxDb - minDb) / LEVEL_TICK_DB) + 1 },\n      (_, index) => maxDb - index * LEVEL_TICK_DB\n    );\n\n  return (\n    <div\n      aria-hidden\n      className={cn(\n        \"text-muted-foreground relative [grid-column:1] [grid-row:1] w-7 text-[0.625rem] tabular-nums\",\n        className\n      )}\n      data-slot=\"spectrum-level-axis\"\n      {...props}\n    >\n      {values.map((db) => (\n        <span\n          className=\"absolute right-0 bottom-(--tick-position) translate-y-1/2\"\n          key={db}\n          style={\n            {\n              \"--tick-position\": `${((db - minDb) / (maxDb - minDb)) * 100}%`,\n            } as CSSProperties\n          }\n        >\n          {format(db)}\n        </span>\n      ))}\n    </div>\n  );\n};\n\nexport interface SpectrumProps extends ComponentProps<\"div\"> {\n  source?: FrameSource<VisualFrame> | null;\n  /** Default `bars`. */\n  variant?: \"bars\" | \"line\" | \"area\";\n  /** The level range the bands cover. Match your analyser. Default −100 / −30. */\n  minDb?: number;\n  maxDb?: number;\n  /** The frequency range the bands cover. Match your analyser. Default 40 / 16000. */\n  minHz?: number;\n  maxHz?: number;\n  /** Frequency axis law. Default `log`. */\n  scale?: \"log\" | \"linear\";\n  /** Keep falling peak markers. Default false. */\n  peakHold?: boolean;\n  /** Draw grid lines. Default true. */\n  grid?: boolean;\n}\n\nexport const Spectrum = ({\n  source,\n  variant = \"bars\",\n  minDb = -100,\n  maxDb = -30,\n  minHz = 40,\n  maxHz = 16_000,\n  scale = \"log\",\n  peakHold = false,\n  grid = true,\n  className,\n  children,\n  ...props\n}: SpectrumProps) => {\n  const frameRef = useRef<VisualFrame | null>(null);\n  const versionRef = useRef(0);\n\n  useFrameSource(source, (frame) => {\n    frameRef.current = frame;\n    versionRef.current += 1;\n  });\n\n  const frequencyTaper = useMemo(\n    () =>\n      scale === \"log\" ? logTaper(minHz, maxHz) : linearTaper(minHz, maxHz),\n    [maxHz, minHz, scale]\n  );\n\n  const contextValue = useMemo<SpectrumContextValue>(\n    () => ({\n      frameRef,\n      frequencyTaper,\n      grid,\n      maxDb,\n      maxHz,\n      minDb,\n      minHz,\n      peakHold,\n      variant,\n      versionRef,\n    }),\n    [frequencyTaper, grid, maxDb, maxHz, minDb, minHz, peakHold, variant]\n  );\n\n  return (\n    <SpectrumContext.Provider value={contextValue}>\n      <div\n        aria-label=\"Frequency spectrum\"\n        className={cn(\n          \"grid h-40 w-full grid-cols-[auto_minmax(0,1fr)] grid-rows-[minmax(0,1fr)_auto] gap-1 [--spectrum-grid:var(--border)] [--spectrum-peak:var(--foreground)] [--spectrum:var(--primary)]\",\n          className\n        )}\n        data-slot=\"spectrum\"\n        data-variant={variant}\n        role=\"img\"\n        {...props}\n      >\n        {children ?? (\n          <>\n            <SpectrumLevelAxis />\n            <SpectrumCanvas />\n            <SpectrumFrequencyAxis />\n          </>\n        )}\n      </div>\n    </SpectrumContext.Provider>\n  );\n};\n",
      "type": "registry:ui"
    }
  ],
  "type": "registry:ui"
}