insomni-plot 0.1.0-alpha.0

package/src/grammar/geoms/ridgeline.ts

@@ -0,0 +1,1164 @@
+// ---------------------------------------------------------------------------
+// ridgeline geom
+// ---------------------------------------------------------------------------
+// One distribution per category, drawn as a closed silhouette that rises off
+// a row baseline. Adjacent rows are allowed to overlap (the iconic "joyplot"
+// look) via the `overlap` factor. Two density estimators:
+//
+//   - `geom: "kde"` (default) — Gaussian/Epanechnikov kernel density,
+//     evaluated on a fixed grid (shared internals with `violin`).
+//   - `geom: "histogram"` — per-row binning with bins shared across rows so
+//     columns align.
+//
+// Two fill modes:
+//
+//   - `fillMode: "solid"` (default) — palette per category (or chart's color
+//     scale when a `color` channel is mapped).
+//   - `fillMode: "gradient"` — value-axis-mapped color ramp; reproduces the
+//     "Lincoln NE temperatures" look. The ramp is rendered as a sequence of
+//     adjacent quads sharing vertices with the KDE/bin grid so there are no
+//     visible seams; the silhouette stroke is drawn afterwards as a single
+//     polyline.
+//
+// Inner annotations (`inner: "median" | "quartile" | "mean"`) and the row
+// baseline are layered on top of the fill.
+
+import type { Color, Layer, Vec2 } from "insomni";
+import { pushFilledPolygon } from "../../marks.ts";
+import {
+  binBreaks,
+  binWithBreaks,
+  boxStats,
+  histogramMeasureValue,
+  type BinClosed,
+  type BinResult,
+  type BinRule,
+  type BoxStats,
+  type HistogramMeasure,
+  type KdeBandwidth,
+  type KdeKernel,
+  type KdeResult,
+  kde as kdeFn,
+  type QuantileMethod,
+  type WhiskerRule,
+} from "../../stats/index.ts";
+import { bandScale, type ContinuousScale } from "../../scales.ts";
+import { resolveAes, type Aes } from "../aes.ts";
+import { withAlpha } from "../color-utils.ts";
+import { DEFAULT_OVERLAP } from "../constants.ts";
+import { selectChannels, wrapMark } from "./_mark.ts";
+import { emphasisContext } from "./emphasis.ts";
+import type {
+  CompileContext,
+  CompiledHitTest,
+  Geom,
+  PositionScaleHint,
+  PrepareRangeContext,
+  RangeHints,
+  ResolvedChannelMap,
+} from "./types.ts";
+import {
+  bucketBandCenter,
+  countsLabelMark,
+  prepareCategoricalLayout,
+  synthAes,
+  type CategoricalBucket,
+  type CategoricalLayout,
+} from "./_categorical.ts";
+import {
+  computeGroupedKde,
+  densityWidthFn,
+  kdeValueExtent,
+  type DensityScale,
+  type GroupedKdeResult,
+} from "./_distribution.ts";
+
+export type RidgelineGeom = "kde" | "histogram";
+export type RidgelineScale = DensityScale;
+export type RidgelineInner = "none" | "median" | "quartile" | "mean";
+export type RidgelineFillMode = "solid" | "gradient";
+
+export interface RidgelineChannels<T> {
+  /** Numeric value being distributed. Provide one of x or y; the other is the row category. */
+  x: Aes<T, string | number>;
+  y: Aes<T, string | number>;
+  /** Optional categorical group key. Drives palette fill (chart color scale). */
+  color?: Aes<T, unknown>;
+}
+
+export interface RidgelineOptions {
+  /** Auto-detected from scale types when omitted. The default reproduces the common "rows on y, values on x" layout. */
+  orientation?: "x" | "y";
+
+  /** Density estimator. Default `"kde"`. */
+  geom?: RidgelineGeom;
+
+  /**
+   * How tall a ridge can be relative to its band-cell spacing. `1` = no
+   * overlap (each ridge stays inside its row); `>1` allows overlap into
+   * neighbours. Default `2.5`.
+   */
+  overlap?: number;
+
+  /**
+   * Across-group height normalization (same semantics as `violin`'s `scale`).
+   *
+   * - `"width"` (default) — each row uses its full allotted height.
+   * - `"area"` — heights normalized by the global max density.
+   * - `"count"` — heights scaled by sample size on top of `"area"`.
+   */
+  scale?: RidgelineScale;
+
+  // KDE pass-throughs (only when `geom === "kde"`)
+  bandwidth?: KdeBandwidth;
+  gridSize?: number;
+  kernel?: KdeKernel;
+  trim?: boolean;
+
+  // Histogram pass-throughs (only when `geom === "histogram"`)
+  bins?: number;
+  binwidth?: number;
+  breaks?: readonly number[];
+  rule?: BinRule;
+  measure?: HistogramMeasure;
+  closed?: BinClosed;
+
+  /**
+   * Solid fill (default) uses the chart color scale per category, or the
+   * theme's categorical palette if no `color` channel is mapped. Gradient
+   * fill ignores the category and applies a value-axis-mapped color ramp,
+   * reproducing the "Lincoln NE temperatures" look.
+   */
+  fillMode?: RidgelineFillMode;
+
+  /**
+   * Color ramp for `fillMode: "gradient"`. Receives `t ∈ [0, 1]` mapped from
+   * the value-axis range. Default = `theme.palettes.continuous`.
+   */
+  gradient?: (t01: number) => Color;
+
+  /** Per-row inner annotation. Default `"none"`. */
+  inner?: RidgelineInner;
+  innerStroke?: Color;
+  innerStrokeWidth?: number;
+  /** Radius of the median/mean dot when `inner` includes a point. Default `3`. */
+  innerDotRadius?: number;
+
+  /** Draw a thin rule along each row's baseline. Default `true`. */
+  baseline?: boolean;
+  baselineStroke?: Color;
+  baselineWidth?: number;
+
+  /** `n=<count>` per row, anchored inline at the row baseline by default. */
+  showCounts?: boolean;
+  countsAnchor?: "outside" | "inline";
+  /** Pixel offset for the counts label. Default 4 (inline) / 28 (outside, vertical) / 32 (outside, horizontal). */
+  countsOffset?: number;
+  countsFontSize?: number;
+  countsColor?: Color;
+
+  /** Solid fill for the silhouette. Default theme palette[0] (overridden by chart color scale when `color` is set). */
+  fill?: Color;
+  fillAlpha?: number;
+  /** Silhouette outline. Default theme text color. */
+  stroke?: Color;
+  strokeWidth?: number;
+  /** Inner-band padding when dodging via `color`. Default `0.05`. */
+  groupPadding?: number;
+
+  // Box-stat options used by inner annotations (only when `inner !== "none"`).
+  whisker?: WhiskerRule;
+  quantile?: QuantileMethod;
+
+  label?: string;
+}
+
+interface KdeRow {
+  bucket: CategoricalBucket;
+  /** Bucket index in `layout.buckets`; used to match against `ctx.hovered`. */
+  bucketIndex: number;
+  /** Center on the band axis (in pixel space). */
+  bandCenter: number;
+  kde: KdeResult;
+  maxDensity: number;
+  n: number;
+  stats: BoxStats;
+  fill: Color;
+  strokeWidth: number;
+  /**
+   * GPU emphasis key (P5-T3) written onto EVERY primitive of this row (ridge
+   * fill + silhouette, baseline, inner annotations) so the whole row dims as one
+   * unit. Ordinal = `bucketIndex` (the hit `dataIndex`). `undefined` when off.
+   */
+  emphasisKey?: number;
+}
+
+interface HistRow {
+  bucket: CategoricalBucket;
+  bucketIndex: number;
+  bandCenter: number;
+  bins: BinResult[];
+  /** Per-bin measured value (count / density / proportion). */
+  values: number[];
+  /** Max value across `values` (post-measure). */
+  maxValue: number;
+  n: number;
+  stats: BoxStats | null;
+  /** See {@link KdeRow.emphasisKey}. */
+  emphasisKey?: number;
+  fill: Color;
+  strokeWidth: number;
+}
+
+export function ridgeline<T>(
+  channels: RidgelineChannels<T>,
+  options: RidgelineOptions = {},
+): Geom<T> {
+  const orientationOpt = options.orientation;
+  const geomMode: RidgelineGeom = options.geom ?? "kde";
+
+  // Shared between compile() and compileHitTest() within a single render —
+  // both receive the same `ctx` instance from pipeline.ts. WeakMap keyed by
+  // ctx so the cache invalidates naturally each frame (new ctx) without
+  // retaining stale layouts.
+  const layoutCache = new WeakMap<CompileContext<T>, CategoricalLayout>();
+  const getLayout = (ctx: CompileContext<T>): CategoricalLayout => {
+    const cached = layoutCache.get(ctx);
+    if (cached) return cached;
+    const layout = prepareCategoricalLayout(
+      ctx,
+      // Cast — the categorical helper accepts `string | number | Date` for
+      // the band axis; ridgeline's surface is the same minus Date.
+      channels as unknown as {
+        x: Aes<T, string | number | Date>;
+        y: Aes<T, number>;
+        color?: Aes<T, unknown>;
+      },
+      {
+        orientation: options.orientation,
+        groupPadding: options.groupPadding,
+        fill: options.fill,
+      },
+    );
+    layoutCache.set(ctx, layout);
+    return layout;
+  };
+
+  return {
+    kind: "ridgeline",
+    channels: { x: channels.x, y: channels.y, color: channels.color },
+    label: options.label,
+
+    prepareDomain(data) {
+      // Run a tiny per-bucket KDE / bin pass to learn the value-axis extent
+      // so the chart's value scale unions in any smoothed tails / bin edges.
+      // Convention (matches violin / _categorical): `orientation` names the
+      // axis the **value** lives on. `"x"` → categories on y, ridges rise
+      // upward (the default look). `"y"` → categories on x, ridges rise
+      // rightward.
+      let orientation: "x" | "y" = orientationOpt ?? "x";
+      if (!orientationOpt && data.length > 0) {
+        const xAes0 = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+        const yAes0 = resolveAes<T, unknown>(channels.y as Aes<T, unknown>);
+        const xSample = xAes0.fn(data[0]!, 0);
+        const ySample = yAes0.fn(data[0]!, 0);
+        if (typeof xSample === "string") orientation = "y";
+        else if (typeof ySample === "string") orientation = "x";
+      }
+      const { categoryChannel, valueChannel } = selectChannels(orientation, channels);
+      const valueAes = resolveAes<T, number>(valueChannel as Aes<T, number>);
+      const bandAes = resolveAes<T, unknown>(categoryChannel as Aes<T, unknown>);
+      const buckets = new Map<string, number[]>();
+      for (let i = 0; i < data.length; i++) {
+        const datum = data[i]!;
+        const v = valueAes.fn(datum, i);
+        if (!Number.isFinite(v)) continue;
+        const key = String(bandAes.fn(datum, i));
+        let arr = buckets.get(key);
+        if (!arr) {
+          arr = [];
+          buckets.set(key, arr);
+        }
+        arr.push(v);
+      }
+      let lo = Number.POSITIVE_INFINITY;
+      let hi = Number.NEGATIVE_INFINITY;
+      if (geomMode === "kde") {
+        const extent = kdeValueExtent(buckets.values(), {
+          bandwidth: options.bandwidth ?? "silverman",
+          gridSize: options.gridSize ?? 64,
+          kernel: options.kernel ?? "gaussian",
+          trim: options.trim ?? true,
+        });
+        if (extent) {
+          lo = extent[0];
+          hi = extent[1];
+        }
+      } else {
+        // Shared bin breaks across all groups so columns align.
+        const flat: number[] = [];
+        for (const values of buckets.values()) for (const v of values) flat.push(v);
+        const breaks = binBreaks(flat, {
+          bins: options.bins,
+          binwidth: options.binwidth,
+          breaks: options.breaks,
+          rule: options.rule,
+        });
+        if (breaks.length >= 2) {
+          lo = breaks[0]!;
+          hi = breaks[breaks.length - 1]!;
+        }
+      }
+      if (!Number.isFinite(lo) || !Number.isFinite(hi)) return undefined;
+      const valueHint: PositionScaleHint = { extend: [lo, hi] };
+      return orientation === "y" ? { y: valueHint } : { x: valueHint };
+    },
+
+    prepareRange(ctx: PrepareRangeContext<T>): RangeHints | undefined {
+      // Ridgelines rise off their baseline by `overlap × cellSize`, which
+      // routinely overshoots the topmost row's headroom (and the plot frame
+      // above it). Compute the worst row's overshoot at the *uncompressed*
+      // band scale, then ask the chart to reserve that much canvas — the
+      // band scale gets shrunk by k = H/(H+overflow) and after compression
+      // every row exactly fits.
+      const { data, plot, scaleOptions } = ctx;
+      if (data.length === 0) return undefined;
+
+      let orientation: "x" | "y" = orientationOpt ?? "x";
+      if (!orientationOpt) {
+        const xAes0 = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+        const yAes0 = resolveAes<T, unknown>(channels.y as Aes<T, unknown>);
+        const xSample = xAes0.fn(data[0]!, 0);
+        const ySample = yAes0.fn(data[0]!, 0);
+        if (typeof xSample === "string") orientation = "y";
+        else if (typeof ySample === "string") orientation = "x";
+      }
+
+      const { categoryChannel, valueChannel } = selectChannels(orientation, channels);
+      const valueAes = resolveAes<T, number>(valueChannel as Aes<T, number>);
+      const bandAes = resolveAes<T, unknown>(categoryChannel as Aes<T, unknown>);
+
+      const order: string[] = [];
+      const buckets = new Map<string, number[]>();
+      for (let i = 0; i < data.length; i++) {
+        const datum = data[i]!;
+        const v = valueAes.fn(datum, i);
+        if (!Number.isFinite(v)) continue;
+        const key = String(bandAes.fn(datum, i));
+        let arr = buckets.get(key);
+        if (!arr) {
+          arr = [];
+          buckets.set(key, arr);
+          order.push(key);
+        }
+        arr.push(v);
+      }
+      if (buckets.size === 0) return undefined;
+
+      // Build a temp band scale matching what the chart will build on the
+      // un-reserved range, so we can read true bandCenters for each bucket.
+      const bandSide = orientation === "y" ? "x" : "y";
+      const bandOpts = scaleOptions[bandSide];
+      const explicitDomain = bandOpts && bandOpts.type === "band" ? bandOpts.domain : undefined;
+      const domain = explicitDomain ?? order;
+      if (domain.length === 0) return undefined;
+      const padding = bandOpts?.padding ?? 0.1;
+      const H = orientation === "x" ? plot.height : plot.width;
+      const range: [number, number] = orientation === "x" ? [H, 0] : [0, H];
+      const tempBand = bandScale<string>(domain, range, { padding });
+      const cellSize = tempBand.bandwidth();
+      if (cellSize <= 0) return undefined;
+
+      const overlap = options.overlap ?? DEFAULT_OVERLAP;
+      const rowHeightPx = cellSize * overlap;
+      const scaleMode: RidgelineScale = options.scale ?? "width";
+
+      let maxOverflow = 0;
+      const consider = (key: string, alpha: number) => {
+        const bandStart = tempBand(key);
+        if (Number.isNaN(bandStart)) return;
+        const bandCenter = bandStart + cellSize / 2;
+        const headroom = orientation === "x" ? bandCenter : H - bandCenter;
+        const overflow = alpha * rowHeightPx - headroom;
+        if (overflow > maxOverflow) maxOverflow = overflow;
+      };
+
+      if (geomMode === "kde") {
+        const kdeOpts = {
+          bandwidth: options.bandwidth ?? "silverman",
+          gridSize: options.gridSize ?? 64,
+          kernel: options.kernel ?? "gaussian",
+          trim: options.trim ?? true,
+        } as const;
+        const peaks: { key: string; maxDensity: number; n: number }[] = [];
+        let globalRef = 0;
+        for (const [key, values] of buckets) {
+          const k = kdeFn(values, kdeOpts);
+          if (!k) continue;
+          let max = 0;
+          for (const y of k.y) if (y > max) max = y;
+          if (max <= 0) continue;
+          const scaled = scaleMode === "count" ? max * values.length : max;
+          if (scaled > globalRef) globalRef = scaled;
+          peaks.push({ key, maxDensity: max, n: values.length });
+        }
+        if (globalRef <= 0) return undefined;
+        for (const p of peaks) {
+          const alpha =
+            scaleMode === "width"
+              ? 1
+              : scaleMode === "area"
+                ? p.maxDensity / globalRef
+                : (p.maxDensity * p.n) / globalRef;
+          consider(p.key, alpha);
+        }
+      } else {
+        const flat: number[] = [];
+        for (const values of buckets.values()) for (const v of values) flat.push(v);
+        const breaks = binBreaks(flat, {
+          bins: options.bins,
+          binwidth: options.binwidth,
+          breaks: options.breaks,
+          rule: options.rule,
+        });
+        if (breaks.length < 2) return undefined;
+        const closed: BinClosed = options.closed ?? "left";
+        const measure: HistogramMeasure = options.measure ?? "count";
+
+        const peaks: { key: string; maxValue: number; n: number }[] = [];
+        let globalRef = 0;
+        for (const [key, values] of buckets) {
+          const bins = binWithBreaks(values, breaks, closed);
+          let n = 0;
+          for (const b of bins) n += b.count;
+          if (n === 0) continue;
+          let max = 0;
+          for (const b of bins) {
+            const v = histogramMeasureValue(b, n, measure);
+            if (v > max) max = v;
+          }
+          if (max <= 0) continue;
+          const scaled = scaleMode === "count" ? max * n : max;
+          if (scaled > globalRef) globalRef = scaled;
+          peaks.push({ key, maxValue: max, n });
+        }
+        if (globalRef <= 0) return undefined;
+        for (const p of peaks) {
+          const alpha =
+            scaleMode === "width"
+              ? 1
+              : scaleMode === "area"
+                ? p.maxValue / globalRef
+                : (p.maxValue * p.n) / globalRef;
+          consider(p.key, alpha);
+        }
+      }
+
+      if (maxOverflow <= 0) return undefined;
+      const reserved = (maxOverflow * H) / (H + maxOverflow);
+      return orientation === "x" ? { top: reserved } : { right: reserved };
+    },
+
+    compile(ctx: CompileContext<T>) {
+      const { plot, theme, atlas } = ctx;
+      const layout = getLayout(ctx);
+      const { orientation, valueAxis, cellSize, ox, oy, buckets } = layout;
+
+      // Hover dim rides the core's GPU emphasis uniform (P5-T3). Each ridge is a
+      // `pushPolygon` KDE fill, which now carries an emphasis key (added this
+      // change), so a whole row is tagged as ONE entity: the SAME key on the
+      // ridge fill + silhouette, the baseline, and the inner annotations. Ordinal
+      // = `bucketIndex` (the hit `dataIndex`), so the mount's emphasisResolution
+      // maps a hover hit to this key with no recompile. The compile-time
+      // `dimFor`/`strokeWidthFor` stay identity — the dim is GPU-side now.
+      const emph = emphasisContext(ctx, "ridgeline");
+      const dimFor = (_bucketIndex: number): number => 1;
+      const strokeWidthFor = (_bucketIndex: number, base: number): number => base;
+
+      const overlap = options.overlap ?? DEFAULT_OVERLAP;
+      const rowHeightPx = cellSize * overlap;
+
+      const scaleMode: RidgelineScale = options.scale ?? "width";
+      const fillMode: RidgelineFillMode = options.fillMode ?? "solid";
+      // Ridgelines rely on z-order occlusion between overlapping rows, so the
+      // default fill is opaque. Theme alpha is bypassed; pass `fillAlpha`
+      // explicitly to opt into translucency.
+      const fillAlpha = options.fillAlpha ?? 1;
+
+      const stroke: Color = options.stroke ?? theme.text.color;
+      const strokeWidth = options.strokeWidth ?? 1;
+
+      const baseline = options.baseline ?? true;
+      const baselineStroke: Color = options.baselineStroke ?? stroke;
+      const baselineWidth = options.baselineWidth ?? 1;
+
+      const innerKind: RidgelineInner = options.inner ?? "none";
+      const innerStroke: Color = options.innerStroke ?? stroke;
+      const innerStrokeWidth = options.innerStrokeWidth ?? 1;
+      const innerDotRadius = options.innerDotRadius ?? 3;
+
+      const showCounts = options.showCounts ?? false;
+      const countsAnchor = options.countsAnchor ?? "inline";
+      const countsFontSize = options.countsFontSize ?? theme.marks.labelFontSize;
+      const countsColor: Color = options.countsColor ?? theme.text.color;
+      const countsOffset =
+        options.countsOffset ?? (countsAnchor === "inline" ? 4 : orientation === "y" ? 28 : 32);
+
+      // Resolve fill per bucket. Solid mode delegates to the categorical
+      // layout's resolver (then `fillAlpha` is forced via `withAlpha`).
+      // Gradient mode ignores the bucket and samples a value-axis-mapped ramp.
+      const gradientPalette = options.gradient ?? ((t: number) => theme.palettes.continuous(t));
+      const gradientFor = (xValue: number): Color => {
+        const [d0, d1] = valueAxis.domain;
+        const t = d0 === d1 ? 0.5 : (xValue - d0) / (d1 - d0);
+        const c = gradientPalette(t < 0 ? 0 : t > 1 ? 1 : t);
+        return withAlpha(c, fillAlpha);
+      };
+
+      // Joyplot z-order: each ridge rises off its baseline and intrudes into
+      // the adjacent row. The row being intruded INTO must paint on top for the
+      // overlap to read correctly. Submission order is the stacking order (v3:
+      // the last-submitted shape paints on top), so the row whose ridge is
+      // overlapped is appended last:
+      // `"x"` ridges rise upward → draw bottom-to-top (descending bandCenter);
+      // `"y"` ridges grow rightward → draw left-to-right (ascending bandCenter).
+      const zOrder = (a: { bandCenter: number }, b: { bandCenter: number }) =>
+        orientation === "x" ? b.bandCenter - a.bandCenter : a.bandCenter - b.bandCenter;
+
+      const builders: { length: number; addTo: (l: Layer) => Layer }[] = [];
+
+      if (geomMode === "kde") {
+        const kdeOpts = {
+          bandwidth: options.bandwidth ?? "silverman",
+          gridSize: options.gridSize ?? 64,
+          kernel: options.kernel ?? "gaussian",
+          trim: options.trim ?? true,
+        } as const;
+        const { groups, globalMaxDensity } = computeGroupedKde(buckets, {
+          kde: kdeOpts,
+          box: {
+            whisker: options.whisker ?? 1.5,
+            quantile: options.quantile ?? "type-7",
+          },
+          scale: scaleMode,
+        });
+
+        const rows: KdeRow[] = [];
+        for (const g of groups) {
+          const bandCenter = bucketBandCenter(layout, g.bucket);
+          if (Number.isNaN(bandCenter)) continue;
+          const bucketIndex = buckets.indexOf(g.bucket);
+          const dim = dimFor(bucketIndex);
+          rows.push({
+            bucket: g.bucket,
+            bucketIndex,
+            bandCenter,
+            kde: g.kde,
+            maxDensity: g.maxDensity,
+            n: g.n,
+            stats: g.stats,
+            fill: withAlpha(layout.resolveFill(g.bucket), fillAlpha * dim),
+            strokeWidth: strokeWidthFor(bucketIndex, strokeWidth),
+            emphasisKey: emph?.keyFor(bucketIndex),
+          });
+        }
+        rows.sort(zOrder);
+
+        builders.push({
+          length: rows.length,
+          addTo(layer: Layer) {
+            for (const row of rows) {
+              const widthFor = densityWidthFn(
+                row as GroupedKdeResult,
+                globalMaxDensity,
+                scaleMode,
+                rowHeightPx,
+              );
+              drawKdeRow(layer, row, {
+                orientation,
+                valueAxis,
+                ox,
+                oy,
+                widthFor,
+                fill: row.fill,
+                stroke,
+                strokeWidth: row.strokeWidth,
+                fillMode,
+                gradientFor,
+                emphasisKey: row.emphasisKey,
+              });
+              if (baseline) {
+                drawBaseline(layer, row.bandCenter, valueAxis, {
+                  orientation,
+                  ox,
+                  oy,
+                  stroke: baselineStroke,
+                  width: baselineWidth,
+                  emphasisKey: row.emphasisKey,
+                });
+              }
+              if (innerKind !== "none") {
+                drawInner(layer, row.bandCenter, row.stats, valueAxis, {
+                  orientation,
+                  ox,
+                  oy,
+                  kind: innerKind,
+                  stroke: innerStroke,
+                  strokeWidth: innerStrokeWidth,
+                  dotRadius: innerDotRadius,
+                  emphasisKey: row.emphasisKey,
+                });
+              }
+            }
+            return layer;
+          },
+        });
+      } else {
+        // Histogram mode — shared breaks across all rows.
+        const allValues: number[] = [];
+        for (const b of buckets) for (const v of b.values) allValues.push(v);
+        const breaks = binBreaks(allValues, {
+          bins: options.bins,
+          binwidth: options.binwidth,
+          breaks: options.breaks,
+          rule: options.rule,
+        });
+        if (breaks.length < 2) return [];
+
+        const closed: BinClosed = options.closed ?? "left";
+        const measure: HistogramMeasure = options.measure ?? "count";
+
+        const measureValue = (b: BinResult, n: number): number =>
+          histogramMeasureValue(b, n, measure);
+
+        const rows: HistRow[] = [];
+        let globalMax = 0;
+        let globalMaxScaled = 0;
+        for (const bucket of buckets) {
+          const bandCenter = bucketBandCenter(layout, bucket);
+          if (Number.isNaN(bandCenter)) continue;
+          const bins = binWithBreaks(bucket.values, breaks, closed);
+          let n = 0;
+          for (const b of bins) n += b.count;
+          if (n === 0) continue;
+          const values = bins.map((b) => measureValue(b, n));
+          let max = 0;
+          for (const v of values) if (v > max) max = v;
+          if (max > globalMax) globalMax = max;
+          const scaled = scaleMode === "count" ? max * n : max;
+          if (scaled > globalMaxScaled) globalMaxScaled = scaled;
+          const stats = boxStats(bucket.values, {
+            whisker: options.whisker ?? 1.5,
+            quantile: options.quantile ?? "type-7",
+          });
+          const bucketIndex = buckets.indexOf(bucket);
+          const dim = dimFor(bucketIndex);
+          rows.push({
+            bucket,
+            bucketIndex,
+            bandCenter,
+            bins,
+            values,
+            maxValue: max,
+            n,
+            stats,
+            fill: withAlpha(layout.resolveFill(bucket), fillAlpha * dim),
+            strokeWidth: strokeWidthFor(bucketIndex, strokeWidth),
+            emphasisKey: emph?.keyFor(bucketIndex),
+          });
+        }
+        rows.sort(zOrder);
+
+        builders.push({
+          length: rows.length,
+          addTo(layer: Layer) {
+            for (const row of rows) {
+              const widthFor = (() => {
+                if (scaleMode === "width") {
+                  if (row.maxValue <= 0) return () => 0;
+                  const k = rowHeightPx / row.maxValue;
+                  return (v: number) => v * k;
+                }
+                const ref = globalMaxScaled > 0 ? globalMaxScaled : 1;
+                if (scaleMode === "count") {
+                  const k = (rowHeightPx * row.n) / ref;
+                  return (v: number) => v * k;
+                }
+                const k = rowHeightPx / ref;
+                return (v: number) => v * k;
+              })();
+
+              drawHistogramRow(layer, row, {
+                orientation,
+                valueAxis,
+                ox,
+                oy,
+                widthFor,
+                fill: row.fill,
+                stroke,
+                strokeWidth: row.strokeWidth,
+                fillMode,
+                gradientFor,
+                emphasisKey: row.emphasisKey,
+              });
+              if (baseline) {
+                drawBaseline(layer, row.bandCenter, valueAxis, {
+                  orientation,
+                  ox,
+                  oy,
+                  stroke: baselineStroke,
+                  width: baselineWidth,
+                  emphasisKey: row.emphasisKey,
+                });
+              }
+              if (innerKind !== "none" && row.stats) {
+                drawInner(layer, row.bandCenter, row.stats, valueAxis, {
+                  orientation,
+                  ox,
+                  oy,
+                  kind: innerKind,
+                  stroke: innerStroke,
+                  strokeWidth: innerStrokeWidth,
+                  dotRadius: innerDotRadius,
+                  emphasisKey: row.emphasisKey,
+                });
+              }
+            }
+            return layer;
+          },
+        });
+      }
+
+      if (showCounts && atlas) {
+        const labelMark = countsLabelMark(
+          layout,
+          {
+            offset: countsOffset,
+            fontSize: countsFontSize,
+            color: countsColor,
+            anchor: countsAnchor,
+          },
+          plot.width,
+          plot.height,
+        );
+        builders.push(wrapMark(labelMark, plot.topLeft, layout.buckets.length));
+      }
+
+      return builders;
+    },
+    emphasisResolution(ctx) {
+      // Ordinal = the hit's `dataIndex`, which compileHitTest sets to the
+      // pre-filter `bucketIndex` — the same value `compile` tags each row with.
+      return emphasisContext(ctx, "ridgeline")?.resolver() ?? null;
+    },
+    compileHitTest(ctx: CompileContext<T>): CompiledHitTest<T> | null {
+      const { data } = ctx;
+      const layout = getLayout(ctx);
+      const { orientation, valueAxis, cellSize, ox, oy, buckets, dodging } = layout;
+
+      // Whole-row hit regions: each bucket claims its full band slot across
+      // the entire value axis. The result is "anywhere on the row" hover,
+      // which matches the painted ridge silhouette far better than the
+      // single-point fallback (median × bandCenter) ever could.
+      const [vDom0, vDom1] = valueAxis.domain;
+      const valueLo = valueAxis(vDom0);
+      const valueHi = valueAxis(vDom1);
+      const valueStart = Math.min(valueLo, valueHi);
+      const valueSpan = Math.abs(valueHi - valueLo);
+
+      const positions = new Float32Array(buckets.length * 2);
+      const rects = new Float32Array(buckets.length * 4);
+      const seriesKey: (string | undefined)[] = Array.from({ length: buckets.length });
+      const medians: number[] = Array.from({ length: buckets.length });
+      const counts: number[] = Array.from({ length: buckets.length });
+      const categories: string[] = Array.from({ length: buckets.length });
+      const groupKeys: (string | undefined)[] = Array.from({ length: buckets.length });
+      // Pre-filter bucket index per emitted hit: the hovered row references the
+      // same `buckets.indexOf(bucket)` the compile path uses. Using a post-filter
+      // `n` here would silently desync whenever a bucket was skipped (no stats /
+      // off-band).
+      const hitBucketIndex: number[] = Array.from({ length: buckets.length });
+      let n = 0;
+      for (let bi = 0; bi < buckets.length; bi++) {
+        const bucket = buckets[bi]!;
+        const stats = boxStats(bucket.values, {
+          whisker: options.whisker ?? 1.5,
+          quantile: options.quantile ?? "type-7",
+        });
+        if (!stats) continue;
+        const bandCenter = bucketBandCenter(layout, bucket);
+        if (!Number.isFinite(bandCenter)) continue;
+        const medianPx = valueAxis(stats.median);
+        if (!Number.isFinite(medianPx)) continue;
+        // For canonical orientation "x" (rows on y, value on x), hit at
+        // (medianPx, bandCenter). For "y" the axes swap.
+        const bandStart = bandCenter - cellSize / 2;
+        if (orientation === "x") {
+          positions[n * 2] = ox + medianPx;
+          positions[n * 2 + 1] = oy + bandCenter;
+          rects[n * 4] = ox + valueStart;
+          rects[n * 4 + 1] = oy + bandStart;
+          rects[n * 4 + 2] = valueSpan;
+          rects[n * 4 + 3] = cellSize;
+        } else {
+          positions[n * 2] = ox + bandCenter;
+          positions[n * 2 + 1] = oy + medianPx;
+          rects[n * 4] = ox + bandStart;
+          rects[n * 4 + 1] = oy + valueStart;
+          rects[n * 4 + 2] = cellSize;
+          rects[n * 4 + 3] = valueSpan;
+        }
+        // `seriesKey` is consumed by the hit-layer keyed on slot index `n`
+        // (it reads `seriesKey[hitIndex]`), so it stays at `n`. The synth
+        // channel accessors below look up by `dataIndex[hitIndex]` (=
+        // pre-filter bucket index), so those side arrays write at `bi`.
+        seriesKey[n] = dodging ? bucket.groupKey : bucket.category;
+        medians[bi] = stats.median;
+        counts[bi] = stats.n;
+        categories[bi] = bucket.category;
+        groupKeys[bi] = bucket.groupKey;
+        hitBucketIndex[n] = bi;
+        n++;
+      }
+      if (n === 0) return null;
+
+      const dataIndex = new Int32Array(n);
+      for (let i = 0; i < n; i++) dataIndex[i] = hitBucketIndex[i]!;
+
+      const channelsMap: ResolvedChannelMap<T> = {
+        x: synthAes(orientation === "x" ? "median" : "category", (_d, idx) =>
+          orientation === "x" ? medians[idx] : categories[idx],
+        ),
+        y: synthAes(orientation === "x" ? "category" : "median", (_d, idx) =>
+          orientation === "x" ? categories[idx] : medians[idx],
+        ),
+        color: dodging ? synthAes("group", (_d, idx) => groupKeys[idx] ?? "") : undefined,
+        size: synthAes("n", (_d, idx) => counts[idx]),
+      };
+
+      return {
+        geomKind: "ridgeline",
+        label: options.label,
+        positions: positions.subarray(0, n * 2),
+        rects: rects.subarray(0, n * 4),
+        dataIndex,
+        seriesKey: seriesKey.slice(0, n),
+        // Region hits cover the band slot exactly; pickRadius is the
+        // fallback used for tooltip anchoring and brush queries.
+        pickRadius: Math.max(layout.cellSize / 2, 8),
+        channels: channelsMap,
+        data,
+      };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// KDE row drawing
+// ---------------------------------------------------------------------------
+
+interface DrawKdeCtx {
+  orientation: "x" | "y";
+  valueAxis: ContinuousScale;
+  ox: number;
+  oy: number;
+  widthFor: (density: number) => number;
+  fill: Color;
+  stroke: Color;
+  strokeWidth: number;
+  fillMode: RidgelineFillMode;
+  gradientFor: (xValue: number) => Color;
+  emphasisKey?: number;
+}
+
+function drawKdeRow(layer: Layer, row: KdeRow, c: DrawKdeCtx) {
+  const k = row.kde;
+  const n = k.x.length;
+  if (n < 2) return;
+  const baselinePx = row.bandCenter;
+
+  // Project KDE samples to (value-axis pixel, density-pixel-offset). With the
+  // shared `orientation` convention ("x" → value on x; "y" → value on y), the
+  // density extends perpendicular to the value axis. For orientation "x"
+  // (the canonical ridgeline look) it pushes upward (-y); for orientation "y"
+  // it pushes rightward (+x).
+  const valuePx = Array.from<number>({ length: n });
+  const topOffset = Array.from<number>({ length: n });
+  for (let i = 0; i < n; i++) {
+    valuePx[i] = c.valueAxis(k.x[i]!);
+    topOffset[i] = c.widthFor(k.y[i]!);
+  }
+
+  const project = (i: number, top: boolean): Vec2 => {
+    if (c.orientation === "x") {
+      return {
+        x: c.ox + valuePx[i]!,
+        y: c.oy + (top ? baselinePx - topOffset[i]! : baselinePx),
+      };
+    }
+    return {
+      x: c.ox + (top ? baselinePx + topOffset[i]! : baselinePx),
+      y: c.oy + valuePx[i]!,
+    };
+  };
+
+  if (c.fillMode === "gradient") {
+    for (let i = 0; i < n - 1; i++) {
+      const xMid = (k.x[i]! + k.x[i + 1]!) / 2;
+      const fill = c.gradientFor(xMid);
+      const quad: Vec2[] = [
+        project(i, false),
+        project(i, true),
+        project(i + 1, true),
+        project(i + 1, false),
+      ];
+      layer.pushPolygon({ points: quad, fill, emphasisKey: c.emphasisKey });
+    }
+    if (c.strokeWidth > 0) {
+      const outline: Vec2[] = Array.from({ length: n });
+      for (let i = 0; i < n; i++) outline[i] = project(i, true);
+      layer.pushPolyline({
+        points: outline,
+        color: c.stroke,
+        width: c.strokeWidth,
+        emphasisKey: c.emphasisKey,
+      });
+    }
+    return;
+  }
+
+  const points: Vec2[] = Array.from({ length: n * 2 });
+  for (let i = 0; i < n; i++) points[i] = project(i, true);
+  for (let i = 0; i < n; i++) points[n + i] = project(n - 1 - i, false);
+  pushFilledPolygon(layer, points, {
+    fill: c.fill,
+    stroke: c.stroke,
+    strokeWidth: c.strokeWidth,
+    emphasisKey: c.emphasisKey,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Histogram row drawing
+// ---------------------------------------------------------------------------
+
+interface DrawHistCtx {
+  orientation: "x" | "y";
+  valueAxis: ContinuousScale;
+  ox: number;
+  oy: number;
+  widthFor: (value: number) => number;
+  fill: Color;
+  stroke: Color;
+  strokeWidth: number;
+  fillMode: RidgelineFillMode;
+  gradientFor: (xValue: number) => Color;
+  emphasisKey?: number;
+}
+
+function drawHistogramRow(layer: Layer, row: HistRow, c: DrawHistCtx) {
+  const baselinePx = row.bandCenter;
+  const k = row.bins.length;
+  if (k === 0) return;
+
+  const projectBin = (binEdgeValuePx: number, top: number, atTop: boolean): Vec2 => {
+    if (c.orientation === "x") {
+      return {
+        x: c.ox + binEdgeValuePx,
+        y: c.oy + (atTop ? baselinePx - top : baselinePx),
+      };
+    }
+    return {
+      x: c.ox + (atTop ? baselinePx + top : baselinePx),
+      y: c.oy + binEdgeValuePx,
+    };
+  };
+
+  if (c.fillMode === "gradient") {
+    for (let i = 0; i < k; i++) {
+      const bin = row.bins[i]!;
+      const top = c.widthFor(row.values[i]!);
+      if (top <= 0) continue;
+      const xMid = (bin.x0 + bin.x1) / 2;
+      const fill = c.gradientFor(xMid);
+      const x0Px = c.valueAxis(bin.x0);
+      const x1Px = c.valueAxis(bin.x1);
+      const quad: Vec2[] = [
+        projectBin(x0Px, top, false),
+        projectBin(x0Px, top, true),
+        projectBin(x1Px, top, true),
+        projectBin(x1Px, top, false),
+      ];
+      layer.pushPolygon({ points: quad, fill, emphasisKey: c.emphasisKey });
+    }
+    if (c.strokeWidth > 0) {
+      const outline = histogramOutline(row, c, /* closeToBaseline */ false);
+      if (outline.length >= 2) {
+        layer.pushPolyline({
+          points: outline,
+          color: c.stroke,
+          width: c.strokeWidth,
+          emphasisKey: c.emphasisKey,
+        });
+      }
+    }
+    return;
+  }
+
+  const closed = histogramOutline(row, c, /* closeToBaseline */ true);
+  if (closed.length >= 3) {
+    pushFilledPolygon(layer, closed, {
+      fill: c.fill,
+      stroke: c.stroke,
+      strokeWidth: c.strokeWidth,
+      emphasisKey: c.emphasisKey,
+    });
+  }
+}
+
+/**
+ * Build the stepped silhouette of a histogram row.
+ *
+ * - `closeToBaseline: true` returns a closed polygon (top edge + baseline
+ *   closure), suitable for `pushPolygon` solid fill.
+ * - `closeToBaseline: false` returns just the top edge — used for the
+ *   stroke pass over a gradient-filled row.
+ */
+function histogramOutline(row: HistRow, c: DrawHistCtx, closeToBaseline: boolean): Vec2[] {
+  const baselinePx = row.bandCenter;
+  const k = row.bins.length;
+  const points: Vec2[] = [];
+  for (let i = 0; i < k; i++) {
+    const bin = row.bins[i]!;
+    const top = c.widthFor(row.values[i]!);
+    const x0Px = c.valueAxis(bin.x0);
+    const x1Px = c.valueAxis(bin.x1);
+    if (c.orientation === "x") {
+      points.push({ x: c.ox + x0Px, y: c.oy + baselinePx - top });
+      points.push({ x: c.ox + x1Px, y: c.oy + baselinePx - top });
+    } else {
+      points.push({ x: c.ox + baselinePx + top, y: c.oy + x0Px });
+      points.push({ x: c.ox + baselinePx + top, y: c.oy + x1Px });
+    }
+  }
+  if (closeToBaseline && points.length > 0) {
+    const lastEdge = c.valueAxis(row.bins[k - 1]!.x1);
+    const firstEdge = c.valueAxis(row.bins[0]!.x0);
+    if (c.orientation === "x") {
+      points.push({ x: c.ox + lastEdge, y: c.oy + baselinePx });
+      points.push({ x: c.ox + firstEdge, y: c.oy + baselinePx });
+    } else {
+      points.push({ x: c.ox + baselinePx, y: c.oy + lastEdge });
+      points.push({ x: c.ox + baselinePx, y: c.oy + firstEdge });
+    }
+  }
+  return points;
+}
+
+// ---------------------------------------------------------------------------
+// Baseline + inner annotations
+// ---------------------------------------------------------------------------
+
+interface BaselineCtx {
+  orientation: "x" | "y";
+  ox: number;
+  oy: number;
+  stroke: Color;
+  width: number;
+  emphasisKey?: number;
+}
+
+function drawBaseline(
+  layer: Layer,
+  bandCenter: number,
+  valueAxis: ContinuousScale,
+  c: BaselineCtx,
+) {
+  const [r0, r1] = valueAxis.range;
+  if (c.orientation === "x") {
+    // Value on x → baseline is horizontal at the row's y position.
+    layer.pushPolyline({
+      points: [
+        { x: c.ox + r0, y: c.oy + bandCenter },
+        { x: c.ox + r1, y: c.oy + bandCenter },
+      ],
+      color: c.stroke,
+      width: c.width,
+      emphasisKey: c.emphasisKey,
+    });
+  } else {
+    // Value on y → baseline is vertical at the column's x position.
+    layer.pushPolyline({
+      points: [
+        { x: c.ox + bandCenter, y: c.oy + r0 },
+        { x: c.ox + bandCenter, y: c.oy + r1 },
+      ],
+      color: c.stroke,
+      width: c.width,
+      emphasisKey: c.emphasisKey,
+    });
+  }
+}
+
+interface InnerCtx {
+  orientation: "x" | "y";
+  ox: number;
+  oy: number;
+  kind: RidgelineInner;
+  stroke: Color;
+  strokeWidth: number;
+  dotRadius: number;
+  emphasisKey?: number;
+}
+
+function drawInner(
+  layer: Layer,
+  bandCenter: number,
+  stats: BoxStats,
+  valueAxis: ContinuousScale,
+  c: InnerCtx,
+) {
+  if (c.kind === "median") {
+    drawDot(layer, valueAxis(stats.median), bandCenter, c.dotRadius, c);
+    return;
+  }
+  if (c.kind === "mean") {
+    drawDot(layer, valueAxis(stats.mean), bandCenter, c.dotRadius, c);
+    return;
+  }
+  if (c.kind === "quartile") {
+    const q1Px = valueAxis(stats.q1);
+    const q3Px = valueAxis(stats.q3);
+    if (c.orientation === "x") {
+      layer.pushPolyline({
+        points: [
+          { x: c.ox + q1Px, y: c.oy + bandCenter },
+          { x: c.ox + q3Px, y: c.oy + bandCenter },
+        ],
+        color: c.stroke,
+        width: c.strokeWidth + 1,
+        emphasisKey: c.emphasisKey,
+      });
+    } else {
+      layer.pushPolyline({
+        points: [
+          { x: c.ox + bandCenter, y: c.oy + q1Px },
+          { x: c.ox + bandCenter, y: c.oy + q3Px },
+        ],
+        color: c.stroke,
+        width: c.strokeWidth + 1,
+        emphasisKey: c.emphasisKey,
+      });
+    }
+    drawDot(layer, valueAxis(stats.median), bandCenter, c.dotRadius, c);
+  }
+}
+
+function drawDot(layer: Layer, valuePx: number, bandCenter: number, radius: number, c: InnerCtx) {
+  const cx = c.orientation === "x" ? c.ox + valuePx : c.ox + bandCenter;
+  const cy = c.orientation === "x" ? c.oy + bandCenter : c.oy + valuePx;
+  layer.pushCircle({ cx, cy, radius, fill: c.stroke, emphasisKey: c.emphasisKey });
+}
+
+// Re-export for tests.
+export type { CategoricalLayout };