insomni-plot 0.1.0-alpha.0

package/src/grammar/geoms/histogram.ts

@@ -0,0 +1,740 @@
+// ---------------------------------------------------------------------------
+// histogram geom
+// ---------------------------------------------------------------------------
+// Counts samples into bins and draws one rect per bin. Composes with the
+// existing position machinery (`identity` / `stack` / `dodge` / `fill`) so
+// multi-group overlay, stacked, dodged, and 100% stacked histograms all fall
+// out of the same code path. `mirror: true` renders the bars below the
+// baseline so two layers compose into a back-to-back distribution.
+
+import type { Color, Layer } from "insomni";
+import { valueLabelMark } from "../../annotations.ts";
+import {
+  binBreaks,
+  binWithBreaks,
+  groupBy,
+  histogramMeasureValue,
+  type BinClosed,
+  type BinResult,
+  type BinRule,
+  type HistogramMeasure,
+} from "../../stats/index.ts";
+
+export type { HistogramMeasure };
+import type { ContinuousScale } from "../../scales.ts";
+import { resolveAes, type Aes, type ResolvedAes } from "../aes.ts";
+import { alphaize, seriesColor } from "../color-utils.ts";
+import { barSwatch } from "../../legend.ts";
+import type {
+  CompileContext,
+  CompiledHitTest,
+  Geom,
+  GeomHoverDecorator,
+  HoveredHit,
+  ResolvedChannelMap,
+  ScaleHints,
+} from "./types.ts";
+import { defaultMarkFill, wrapMark } from "./_mark.ts";
+import { emphasisContext } from "./emphasis.ts";
+import { DEFAULT_GROUP_PADDING, synthAes } from "./_categorical.ts";
+
+export type HistogramPosition = "identity" | "stack" | "dodge" | "fill";
+
+export interface HistogramChannels<T> {
+  /** Numeric variable to bin. Provide one of `x` (vertical bars) or `y`. */
+  x?: Aes<T, number>;
+  /** Numeric variable to bin. Provide one of `x` (vertical bars) or `y`. */
+  y?: Aes<T, number>;
+  /** Optional categorical group key — splits the sample into per-group bins. */
+  color?: Aes<T, unknown>;
+}
+
+export interface HistogramOptions {
+  /** Explicit bin count. Loses to `binwidth` and `breaks`. */
+  bins?: number;
+  /** Explicit bin width in data units. Beats `bins` and `rule`. */
+  binwidth?: number;
+  /** Fully explicit edge array. Beats every other bin selector. */
+  breaks?: readonly number[];
+  /**
+   * Auto-bin rule when none of `bins`, `binwidth`, `breaks` is set.
+   *
+   * - `"sturges"` (default) — R / ggplot default; works for ~normal data.
+   * - `"rice"` — slightly more bins.
+   * - `"scott"` — uses σ; good for normal-ish data.
+   * - `"fd"` — Freedman–Diaconis; robust to outliers.
+   */
+  rule?: BinRule;
+  /** Clip / extend the value-axis range used when computing edges. */
+  domain?: readonly [number, number];
+  /** Round outer edges + step to nice numbers. Default `true`. */
+  nice?: boolean;
+  /** Edge convention. Default `"left"` (`[x0, x1)` plus closed last bin). */
+  closed?: BinClosed;
+  /**
+   * Y measure. Default `"count"`.
+   *
+   * - `"count"` / `"frequency"` — raw bin count.
+   * - `"density"` — `count / (n · width)`. Integrates to 1 across bins.
+   * - `"proportion"` — `count / n`. Sums to 1 across bins (per group).
+   */
+  y?: HistogramMeasure;
+  /**
+   * Multi-group layout. Default `"stack"` when `color` channel is present,
+   * else `"identity"`.
+   *
+   * - `"identity"` — bars share a baseline of 0; useful with reduced
+   *   `fillAlpha` for an overlay effect.
+   * - `"stack"` — per-bin counts stacked.
+   * - `"dodge"` — sub-divide bin width across groups, side by side.
+   * - `"fill"` — stack normalized to `[0, 1]` per bin.
+   */
+  position?: HistogramPosition;
+  /** Render bars below the baseline (negate the count axis). Default `false`. */
+  mirror?: boolean;
+  /** Override theme `fillAlpha`. Lower this for `position: "identity"` overlays. */
+  fillAlpha?: number;
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  cornerRadius?: number;
+  /** Pixel gap between adjacent bars. Default `0` (continuous wall). */
+  gap?: number;
+  /** Inner-band padding for `position: "dodge"` (fraction of bin width). Default `0.05`. */
+  groupPadding?: number;
+  /** Optional per-bar label (uses bin midpoint + value). */
+  showCounts?: (value: number, bin: BinResult, key?: string) => string;
+  labelColor?: Color;
+  labelFontSize?: number;
+  /** Used by the auto-legend. */
+  label?: string;
+}
+
+interface PerGroup {
+  key: string;
+  bins: BinResult[];
+  /** Sample size (after filtering non-finite + domain). */
+  n: number;
+  fill: Color;
+}
+
+interface ResolvedLayout {
+  orientation: "x" | "y";
+  breaks: number[];
+  groups: PerGroup[];
+  position: HistogramPosition;
+  measure: HistogramMeasure;
+}
+
+export function histogram<T>(
+  channels: HistogramChannels<T>,
+  options: HistogramOptions = {},
+): Geom<T> {
+  if (channels.x === undefined && channels.y === undefined) {
+    throw new Error("histogram(): one of `x` or `y` must be provided");
+  }
+  if (channels.x !== undefined && channels.y !== undefined) {
+    throw new Error("histogram(): provide either `x` or `y`, not both");
+  }
+
+  const orientation: "x" | "y" = channels.x !== undefined ? "x" : "y";
+  const valueAesRaw = (orientation === "x" ? channels.x : channels.y) as Aes<T, number>;
+
+  // Synthesise the count-axis channel as a constant-0 accessor. The pipeline
+  // builds a numeric scale on the back of this; `prepareDomain` then overrides
+  // the domain with the actual count extent.
+  const synthesisedCount: Aes<T, number> = 0 as unknown as Aes<T, number>;
+  const declaredChannels = {
+    x: orientation === "x" ? channels.x : synthesisedCount,
+    y: orientation === "y" ? channels.y : synthesisedCount,
+    color: channels.color,
+  };
+
+  const measure: HistogramMeasure = options.y ?? "count";
+  const positionDefault: HistogramPosition = channels.color !== undefined ? "stack" : "identity";
+  const position: HistogramPosition = options.position ?? positionDefault;
+  const mirror = options.mirror ?? false;
+
+  function buildLayout(data: readonly T[]): ResolvedLayout | null {
+    const valueAes = resolveAes<T, number>(valueAesRaw);
+    const colorAes: ResolvedAes<T, unknown> | undefined = channels.color
+      ? resolveAes<T, unknown>(channels.color)
+      : undefined;
+
+    // Null policy (see aes.ts): rows whose categorical color channel is
+    // null/undefined are dropped — they do not form a `"null"` bin group.
+    // Numeric values are kept; downstream `binBreaks` already tolerates NaN.
+    const allValues: number[] = [];
+    const allKeys: string[] | undefined = colorAes ? [] : undefined;
+    for (let i = 0; i < data.length; i++) {
+      const datum = data[i]!;
+      if (colorAes) {
+        const k = colorAes.fn(datum, i);
+        if (k === null || k === undefined) continue;
+        // oxlint-disable-next-line no-base-to-string -- color key is a scalar (string/number); String() is safe here
+        allKeys!.push(String(k));
+      }
+      allValues.push(valueAes.fn(datum, i));
+    }
+
+    const breaks = binBreaks(allValues, {
+      bins: options.bins,
+      binwidth: options.binwidth,
+      breaks: options.breaks,
+      rule: options.rule,
+      domain: options.domain,
+      nice: options.nice,
+    });
+    if (breaks.length < 2) return null;
+
+    // Group order: first-occurrence in input. Single-group fast-path uses one
+    // bucket keyed by the empty string.
+    const groupValues = allKeys
+      ? groupBy(allValues, (_v, i) => allKeys[i]!)
+      : new Map<string, number[]>([["", allValues]]);
+    const groupOrder = [...groupValues.keys()];
+
+    const closed = options.closed ?? "left";
+    const groups: PerGroup[] = [];
+    for (const key of groupOrder) {
+      const values = groupValues.get(key)!;
+      const bins = binWithBreaks(values, breaks, closed);
+      let n = 0;
+      for (const b of bins) n += b.count;
+      groups.push({ key, bins, n, fill: { r: 0, g: 0, b: 0, a: 1 } });
+    }
+
+    return {
+      orientation,
+      breaks,
+      groups,
+      position,
+      measure,
+    };
+  }
+
+  const measureValue = (b: BinResult, n: number): number => histogramMeasureValue(b, n, measure);
+
+  /**
+   * Per-bin position offsets keyed by group index. Returns parallel arrays
+   * `[base, top]` per group per bin so the renderer doesn't recompute them.
+   */
+  function computeStacks(layout: ResolvedLayout): { base: number; top: number }[][] {
+    const k = layout.breaks.length - 1;
+    const groupCount = layout.groups.length;
+    const out: { base: number; top: number }[][] = layout.groups.map(() =>
+      Array.from({ length: k }),
+    );
+
+    if (layout.position === "identity") {
+      for (let g = 0; g < groupCount; g++) {
+        const group = layout.groups[g]!;
+        for (let i = 0; i < k; i++) {
+          const v = measureValue(group.bins[i]!, group.n);
+          out[g]![i] = { base: 0, top: v };
+        }
+      }
+      return out;
+    }
+
+    if (layout.position === "stack" || layout.position === "fill") {
+      for (let i = 0; i < k; i++) {
+        let acc = 0;
+        let total = 0;
+        if (layout.position === "fill") {
+          for (let g = 0; g < groupCount; g++) {
+            total += measureValue(layout.groups[g]!.bins[i]!, layout.groups[g]!.n);
+          }
+        }
+        for (let g = 0; g < groupCount; g++) {
+          const v = measureValue(layout.groups[g]!.bins[i]!, layout.groups[g]!.n);
+          let base = acc;
+          let top = acc + v;
+          if (layout.position === "fill") {
+            if (total > 0) {
+              base = acc / total;
+              top = (acc + v) / total;
+            } else {
+              base = 0;
+              top = 0;
+            }
+          }
+          out[g]![i] = { base, top };
+          acc += v;
+        }
+      }
+      return out;
+    }
+
+    // dodge: each group draws its own bar within the bin slot — base 0, top v.
+    for (let g = 0; g < groupCount; g++) {
+      const group = layout.groups[g]!;
+      for (let i = 0; i < k; i++) {
+        const v = measureValue(group.bins[i]!, group.n);
+        out[g]![i] = { base: 0, top: v };
+      }
+    }
+    return out;
+  }
+
+  function maxStackTop(stacks: { base: number; top: number }[][]): number {
+    let max = 0;
+    for (const group of stacks) {
+      for (const seg of group) {
+        if (seg.top > max) max = seg.top;
+      }
+    }
+    return max;
+  }
+
+  return {
+    kind: "histogram",
+    channels: declaredChannels,
+    label: options.label,
+    scaleHints: {
+      [orientation === "x" ? "y" : "x"]: { includeZero: true },
+    } as ScaleHints,
+    legendSwatch: (color) => barSwatch({ fill: color, size: 12 }),
+    prepareDomain(data) {
+      const layout = buildLayout(data);
+      if (!layout) return undefined;
+      const stacks = computeStacks(layout);
+      const max = maxStackTop(stacks);
+      const valueExtend: [number, number] = [
+        layout.breaks[0]!,
+        layout.breaks[layout.breaks.length - 1]!,
+      ];
+      // The count axis is synthesised (constant 0 per row) so numericExtent
+      // yields a useless `[-1, 1]`. Pin it explicitly via `domain` (which
+      // takes precedence over `extend`/`includeZero` in `applyHint`). The
+      // value axis only needs to extend to bin edges, so we use `extend` —
+      // unions cleanly with sibling layers via `mergeHint`.
+      const countLo = mirror ? -max : 0;
+      const countHi = mirror ? 0 : max;
+      const countDomain: [number, number] = countLo === countHi ? [0, 1] : [countLo, countHi];
+      const valueHint = { extend: valueExtend };
+      const countHint = { domain: countDomain };
+      if (layout.orientation === "x") {
+        return { x: valueHint, y: countHint };
+      }
+      return { x: countHint, y: valueHint };
+    },
+    compile(ctx: CompileContext<T>) {
+      const { data, scales, plot, theme, atlas } = ctx;
+      const layout = buildLayout(data);
+      if (!layout) return [];
+
+      const stacks = computeStacks(layout);
+
+      // Resolve fills.
+      const fillAlpha = options.fillAlpha ?? theme.marks.fillAlpha;
+      const baseFill: Color = options.fill ?? defaultMarkFill(theme);
+      if (channels.color) {
+        const keys = layout.groups.map((g) => g.key);
+        const fillFor = seriesColor(scales.color, theme.palettes.categorical, keys);
+        for (const g of layout.groups) g.fill = alphaize(fillFor(g.key), fillAlpha);
+      } else {
+        const fill = alphaize(baseFill, fillAlpha);
+        for (const g of layout.groups) g.fill = fill;
+      }
+
+      const stroke = options.stroke;
+      const strokeWidth = options.strokeWidth;
+      const cornerRadius = options.cornerRadius ?? theme.marks.barCornerRadius;
+      const gap = options.gap ?? 0;
+      const groupPadding = options.groupPadding ?? DEFAULT_GROUP_PADDING;
+
+      const valueAxis = (
+        layout.orientation === "x" ? scales.x.axisScale : scales.y.axisScale
+      ) as ContinuousScale;
+      const countAxis = (
+        layout.orientation === "x" ? scales.y.axisScale : scales.x.axisScale
+      ) as ContinuousScale;
+
+      const ox = plot.topLeft.x;
+      const oy = plot.topLeft.y;
+      const groupCount = layout.groups.length;
+
+      // Hover emphasis — the dim-others treatment rides the core's GPU emphasis
+      // uniform (P5-T3): tag each cell with a stable per-cell key (the flat cell
+      // counter that compileHitTest reports as `dataIndex`); the mount fades
+      // non-focused cells with no marks recompile. No compile-time color dim /
+      // halo. `dataIndex` in compileHitTest is the flat counter `n` over the same
+      // i × g iteration order (skipping empty cells), so we replicate it here.
+      const emph = emphasisContext(ctx, "histogram");
+
+      const builders: { length: number; addTo: (l: Layer) => Layer }[] = [];
+      // Note: first builder uses a custom addTo that paints rects directly,
+      // so it can't reuse `wrapMark`. Label builder below does.
+
+      builders.push({
+        length: layout.breaks.length - 1,
+        addTo(layer: Layer) {
+          let cellN = 0; // mirrors compileHitTest's `n` counter
+
+          for (let i = 0; i < layout.breaks.length - 1; i++) {
+            const x0Px = valueAxis(layout.breaks[i]!);
+            const x1Px = valueAxis(layout.breaks[i + 1]!);
+            const binLo = Math.min(x0Px, x1Px);
+            const binHi = Math.max(x0Px, x1Px);
+            const binSpan = binHi - binLo;
+            for (let g = 0; g < groupCount; g++) {
+              const group = layout.groups[g]!;
+              const seg = stacks[g]![i]!;
+              if (seg.top === seg.base) continue;
+              const baseV = mirror ? -seg.base : seg.base;
+              const topV = mirror ? -seg.top : seg.top;
+              const basePx = countAxis(baseV);
+              const topPx = countAxis(topV);
+              const lo = Math.min(basePx, topPx);
+              const hi = Math.max(basePx, topPx);
+
+              let cellLo = binLo;
+              let cellSpan = binSpan;
+              if (layout.position === "dodge" && groupCount > 1) {
+                const padPx = binSpan * groupPadding;
+                const inner = (binSpan - padPx) / groupCount;
+                cellLo = binLo + padPx / 2 + g * inner;
+                cellSpan = inner;
+              }
+              const halfGap = Math.min(gap / 2, Math.max(0, cellSpan / 2 - 0.5));
+              const x = cellLo + halfGap;
+              const w = Math.max(0, cellSpan - halfGap * 2);
+
+              // Per-cell emphasis key — keyed by the flat cell counter `cellN`,
+              // which is exactly the `dataIndex` compileHitTest reports.
+              const emphasisKey = emph?.keyFor(cellN);
+
+              if (layout.orientation === "x") {
+                layer.pushRect({
+                  x: ox + x,
+                  y: oy + lo,
+                  width: w,
+                  height: Math.max(0, hi - lo),
+                  fill: group.fill,
+                  stroke,
+                  strokeWidth,
+                  cornerRadius,
+                  emphasisKey,
+                });
+              } else {
+                layer.pushRect({
+                  x: ox + lo,
+                  y: oy + x,
+                  width: Math.max(0, hi - lo),
+                  height: w,
+                  fill: group.fill,
+                  stroke,
+                  strokeWidth,
+                  cornerRadius,
+                  emphasisKey,
+                });
+              }
+              cellN++;
+            }
+          }
+
+          return layer;
+        },
+      });
+
+      // Optional value labels above each bar.
+      if (atlas && options.showCounts) {
+        const fmt = options.showCounts;
+        const labelColor: Color = options.labelColor ?? theme.text.color;
+        const labelFontSize = options.labelFontSize ?? theme.marks.labelFontSize;
+
+        type LabelEntry = {
+          binIndex: number;
+          groupIndex: number;
+          bin: BinResult;
+          group: PerGroup;
+          seg: { base: number; top: number };
+        };
+        const entries: LabelEntry[] = [];
+        for (let i = 0; i < layout.breaks.length - 1; i++) {
+          for (let g = 0; g < groupCount; g++) {
+            const group = layout.groups[g]!;
+            const seg = stacks[g]![i]!;
+            if (seg.top === seg.base) continue;
+            entries.push({
+              binIndex: i,
+              groupIndex: g,
+              bin: group.bins[i]!,
+              group,
+              seg,
+            });
+          }
+        }
+
+        const orientationX = layout.orientation === "x";
+        const labelMark = valueLabelMark(entries, {
+          x: (e) => {
+            const x0Px = valueAxis(layout.breaks[e.binIndex]!);
+            const x1Px = valueAxis(layout.breaks[e.binIndex + 1]!);
+            const lo = Math.min(x0Px, x1Px);
+            const hi = Math.max(x0Px, x1Px);
+            const span = hi - lo;
+            if (orientationX) {
+              if (layout.position === "dodge" && groupCount > 1) {
+                const inner = (span * (1 - groupPadding)) / groupCount;
+                return lo + span * (groupPadding / 2) + e.groupIndex * inner + inner / 2;
+              }
+              return (lo + hi) / 2;
+            }
+            // horizontal: x is the count axis
+            const topV = mirror ? -e.seg.top : e.seg.top;
+            return countAxis(topV);
+          },
+          y: (e) => {
+            if (orientationX) {
+              const topV = mirror ? -e.seg.top : e.seg.top;
+              return countAxis(topV);
+            }
+            const x0Px = valueAxis(layout.breaks[e.binIndex]!);
+            const x1Px = valueAxis(layout.breaks[e.binIndex + 1]!);
+            const lo = Math.min(x0Px, x1Px);
+            const hi = Math.max(x0Px, x1Px);
+            const span = hi - lo;
+            if (layout.position === "dodge" && groupCount > 1) {
+              const inner = (span * (1 - groupPadding)) / groupCount;
+              return lo + span * (groupPadding / 2) + e.groupIndex * inner + inner / 2;
+            }
+            return (lo + hi) / 2;
+          },
+          text: (e) =>
+            fmt(
+              measureValue(e.bin, e.group.n),
+              e.bin,
+              e.group.key === "" ? undefined : e.group.key,
+            ),
+          color: labelColor,
+          fontSize: labelFontSize,
+          align: orientationX ? "center" : "left",
+          offset: orientationX
+            ? { x: 0, y: mirror ? labelFontSize + 2 : -6 }
+            : { x: mirror ? -6 : 6, y: 0 },
+        });
+        builders.push(wrapMark(labelMark, plot.topLeft, entries.length));
+      }
+
+      return builders;
+    },
+    emphasisResolution(ctx) {
+      return emphasisContext(ctx, "histogram")?.resolver() ?? null;
+    },
+    hoverDecoration(ctx: CompileContext<T>): GeomHoverDecorator | null {
+      // Focus halo on the hovered bin cell — recovered from the old snap path's
+      // compile-time outline (deleted in e6d5643). Now an OVERLAY decorator
+      // replayed into the live overlay layer (NO marks recompile). Overlay shapes
+      // leave emphasisKey 0 ⇒ EXEMPT ⇒ the halo stays full-strength while the
+      // other cells dim via the GPU uniform. The hit's `dataIndex` is the flat
+      // cell counter `cellN`, so we replicate the same i×g iteration order
+      // (skipping empty cells) to find the hovered cell's rect + group fill.
+      const { data, plot } = ctx;
+      const hoverCfg = ctx.theme.interactions.hover;
+      const layout = buildLayout(data);
+      if (!layout) return null;
+
+      const fillAlpha = options.fillAlpha ?? ctx.theme.marks.fillAlpha;
+      const baseFill: Color = options.fill ?? defaultMarkFill(ctx.theme);
+      if (ctx.scales.color && layout.groups.length > 0 && options.fill === undefined) {
+        const keys = layout.groups.map((g) => g.key);
+        const fillFor = seriesColor(ctx.scales.color, ctx.theme.palettes.categorical, keys);
+        for (const g of layout.groups) g.fill = alphaize(fillFor(g.key), fillAlpha);
+      } else {
+        const fill = alphaize(baseFill, fillAlpha);
+        for (const g of layout.groups) g.fill = fill;
+      }
+
+      const stacks = computeStacks(layout);
+      const cornerRadius = options.cornerRadius ?? ctx.theme.marks.barCornerRadius;
+      const gap = options.gap ?? 0;
+      const groupPadding = options.groupPadding ?? DEFAULT_GROUP_PADDING;
+      const valueAxis = (
+        layout.orientation === "x" ? ctx.scales.x.axisScale : ctx.scales.y.axisScale
+      ) as ContinuousScale;
+      const countAxis = (
+        layout.orientation === "x" ? ctx.scales.y.axisScale : ctx.scales.x.axisScale
+      ) as ContinuousScale;
+      const ox = plot.topLeft.x;
+      const oy = plot.topLeft.y;
+      const groupCount = layout.groups.length;
+
+      return {
+        geomKind: "histogram",
+        data,
+        decorate(hit: HoveredHit, layer: Layer): void {
+          if (!hoverCfg.enabled || hit.data !== data) return;
+          let cellN = 0;
+          for (let i = 0; i < layout.breaks.length - 1; i++) {
+            const x0Px = valueAxis(layout.breaks[i]!);
+            const x1Px = valueAxis(layout.breaks[i + 1]!);
+            const binLo = Math.min(x0Px, x1Px);
+            const binHi = Math.max(x0Px, x1Px);
+            const binSpan = binHi - binLo;
+            for (let g = 0; g < groupCount; g++) {
+              const group = layout.groups[g]!;
+              const seg = stacks[g]![i]!;
+              if (seg.top === seg.base) continue;
+              if (cellN === hit.dataIndex) {
+                const baseV = mirror ? -seg.base : seg.base;
+                const topV = mirror ? -seg.top : seg.top;
+                const basePx = countAxis(baseV);
+                const topPx = countAxis(topV);
+                const lo = Math.min(basePx, topPx);
+                const hi = Math.max(basePx, topPx);
+                let cellLo = binLo;
+                let cellSpan = binSpan;
+                if (layout.position === "dodge" && groupCount > 1) {
+                  const padPx = binSpan * groupPadding;
+                  const inner = (binSpan - padPx) / groupCount;
+                  cellLo = binLo + padPx / 2 + g * inner;
+                  cellSpan = inner;
+                }
+                const halfGap = Math.min(gap / 2, Math.max(0, cellSpan / 2 - 0.5));
+                const x = cellLo + halfGap;
+                const w = Math.max(0, cellSpan - halfGap * 2);
+                const ringColor: Color = hoverCfg.haloColor ?? { ...group.fill, a: 1 };
+                if (layout.orientation === "x") {
+                  layer.pushRect({
+                    x: ox + x,
+                    y: oy + lo,
+                    width: w,
+                    height: Math.max(0, hi - lo),
+                    cornerRadius,
+                    stroke: ringColor,
+                    strokeWidth: hoverCfg.haloStrokeWidth,
+                  });
+                } else {
+                  layer.pushRect({
+                    x: ox + lo,
+                    y: oy + x,
+                    width: Math.max(0, hi - lo),
+                    height: w,
+                    cornerRadius,
+                    stroke: ringColor,
+                    strokeWidth: hoverCfg.haloStrokeWidth,
+                  });
+                }
+                return;
+              }
+              cellN++;
+            }
+          }
+        },
+      };
+    },
+    compileHitTest(ctx: CompileContext<T>): CompiledHitTest<T> | null {
+      const { data, scales, plot } = ctx;
+      const layout = buildLayout(data);
+      if (!layout) return null;
+
+      const stacks = computeStacks(layout);
+      const valueAxis = (
+        layout.orientation === "x" ? scales.x.axisScale : scales.y.axisScale
+      ) as ContinuousScale;
+      const countAxis = (
+        layout.orientation === "x" ? scales.y.axisScale : scales.x.axisScale
+      ) as ContinuousScale;
+      const groupPadding = options.groupPadding ?? DEFAULT_GROUP_PADDING;
+      const groupCount = layout.groups.length;
+      const k = layout.breaks.length - 1;
+
+      const ox = plot.topLeft.x;
+      const oy = plot.topLeft.y;
+      const cap = groupCount * k;
+      const positions = new Float32Array(cap * 2);
+      const rects = new Float32Array(cap * 4);
+      const dataIndex = new Int32Array(cap);
+      const seriesKey: (string | undefined)[] = Array.from({ length: cap });
+      const binMidpoints: number[] = Array.from({ length: cap });
+      const binValues: number[] = Array.from({ length: cap });
+      const groupKeys: (string | undefined)[] = Array.from({ length: cap });
+      let n = 0;
+      let minBinSpan = Infinity;
+      for (let i = 0; i < k; i++) {
+        const x0Px = valueAxis(layout.breaks[i]!);
+        const x1Px = valueAxis(layout.breaks[i + 1]!);
+        const binLo = Math.min(x0Px, x1Px);
+        const binHi = Math.max(x0Px, x1Px);
+        const binSpan = binHi - binLo;
+        for (let g = 0; g < groupCount; g++) {
+          const seg = stacks[g]![i]!;
+          if (seg.top === seg.base) continue;
+          const baseV = mirror ? -seg.base : seg.base;
+          const topV = mirror ? -seg.top : seg.top;
+          const basePx = countAxis(baseV);
+          const topPx = countAxis(topV);
+          const segLo = Math.min(basePx, topPx);
+          const segHi = Math.max(basePx, topPx);
+
+          let cellLo = binLo;
+          let cellSpan = binSpan;
+          if (layout.position === "dodge" && groupCount > 1) {
+            const padPx = binSpan * groupPadding;
+            const inner = (binSpan - padPx) / groupCount;
+            cellLo = binLo + padPx / 2 + g * inner;
+            cellSpan = inner;
+          }
+          if (cellSpan < minBinSpan) minBinSpan = cellSpan;
+          const cx = cellLo + cellSpan / 2;
+          const cy = (segLo + segHi) / 2;
+
+          if (layout.orientation === "x") {
+            positions[n * 2] = ox + cx;
+            positions[n * 2 + 1] = oy + cy;
+            // Whole-bar footprint for region hit testing.
+            rects[n * 4] = ox + cellLo;
+            rects[n * 4 + 1] = oy + segLo;
+            rects[n * 4 + 2] = cellSpan;
+            rects[n * 4 + 3] = segHi - segLo;
+          } else {
+            positions[n * 2] = ox + cy;
+            positions[n * 2 + 1] = oy + cx;
+            rects[n * 4] = ox + segLo;
+            rects[n * 4 + 1] = oy + cellLo;
+            rects[n * 4 + 2] = segHi - segLo;
+            rects[n * 4 + 3] = cellSpan;
+          }
+          const group = layout.groups[g]!;
+          const groupKey = group.key === "" ? undefined : group.key;
+          seriesKey[n] = groupKey ?? `bin${i}`;
+          groupKeys[n] = groupKey;
+          binMidpoints[n] = (layout.breaks[i]! + layout.breaks[i + 1]!) / 2;
+          binValues[n] = measureValue(group.bins[i]!, group.n);
+          dataIndex[n] = n;
+          n++;
+        }
+      }
+      if (n === 0) return null;
+
+      const hasGroups = channels.color !== undefined;
+      const channelsMap: ResolvedChannelMap<T> = {
+        x: synthAes(layout.orientation === "x" ? "bin" : measure, (_d, idx) =>
+          layout.orientation === "x" ? binMidpoints[idx] : binValues[idx],
+        ),
+        y: synthAes(layout.orientation === "x" ? measure : "bin", (_d, idx) =>
+          layout.orientation === "x" ? binValues[idx] : binMidpoints[idx],
+        ),
+        color: hasGroups ? synthAes("group", (_d, idx) => groupKeys[idx] ?? "") : undefined,
+      };
+
+      // Sized to half the smallest dodged-cell span so the cursor inside a
+      // bar's footprint picks it; off-axis still uses Euclidean default.
+      const pickRadius = Math.max(Number.isFinite(minBinSpan) ? minBinSpan / 2 : 0, 6);
+
+      return {
+        geomKind: "histogram",
+        label: options.label,
+        positions: positions.subarray(0, n * 2),
+        rects: rects.subarray(0, n * 4),
+        dataIndex: dataIndex.subarray(0, n),
+        seriesKey: seriesKey.slice(0, n),
+        pickRadius,
+        channels: channelsMap,
+        data,
+      };
+    },
+  };
+}