insomni-plot 0.1.0-alpha.0

package/src/grammar/geoms/boxplot.ts

@@ -0,0 +1,834 @@
+// ---------------------------------------------------------------------------
+// boxplot geom
+// ---------------------------------------------------------------------------
+// Tukey-style box-and-whisker plots — with optional notches, mean overlay,
+// variable width, sample-size labels, and jittered raw-point overlay. Uses
+// only existing primitives + the categorical-layout helper shared with violin.
+
+import type { Color, Layer, Vec2 } from "insomni";
+import { type ContinuousScale } from "../../scales.ts";
+import {
+  boxStats,
+  jitter,
+  type BoxStats,
+  type QuantileMethod,
+  type WhiskerRule,
+} from "../../stats/index.ts";
+import { pointMark, pushFilledPolygon, type PointShapeKind } from "../../marks.ts";
+import { alphaize } from "../color-utils.ts";
+import { DEFAULT_POINTS_THRESHOLD } from "../constants.ts";
+import type { Aes } from "../aes.ts";
+import type { CompileContext, CompiledHitTest, Geom, ResolvedChannelMap } from "./types.ts";
+import {
+  bucketBandCenter,
+  bucketSeed,
+  countsLabelMark,
+  prepareCategoricalLayout,
+  synthAes,
+  type CategoricalBucket,
+  type CategoricalChannels,
+  type CategoricalLayout,
+} from "./_categorical.ts";
+import { emphasisContext } from "./emphasis.ts";
+
+export type PointsMode = "auto" | "always" | "none";
+
+export interface BoxplotChannels<T> {
+  /** Categorical band axis. */
+  x: Aes<T, string | number | Date>;
+  /**
+   * Numeric value axis (the distribution to summarize) when vertical. For
+   * horizontal layouts (`orientation: "x"`) this carries the band category, so
+   * a string is accepted; the value axis then lives on `x`.
+   */
+  y: Aes<T, string | number | Date>;
+  /**
+   * Optional grouping key. When supplied (and distinct from `x`) the layer
+   * dodges side-by-side by this channel within each band.
+   */
+  color?: Aes<T, unknown>;
+}
+
+/**
+ * Mean-overlay configuration. `true` → default red dot; `false` (default) →
+ * no overlay; object → fully customised.
+ */
+export interface MeanMarkerOptions {
+  shape?: PointShapeKind;
+  /** Radius in pixels. Default `3.5`. */
+  radius?: number;
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+}
+
+export interface BoxplotOptions {
+  /** Auto-detected from scale types when omitted (band axis = category axis). */
+  orientation?: "x" | "y";
+  /**
+   * Box width as a fraction of the bandwidth (or grouped inner bandwidth, when
+   * dodging). Default `0.6`.
+   */
+  width?: number;
+  /**
+   * Scale box widths by `√(n / nMax)` so groups with more samples render
+   * wider — matches ggplot's `varwidth = TRUE`. Default `false`.
+   */
+  varwidth?: boolean;
+  /** Whisker rule. Default `1.5` (Tukey). Pass `"minmax"` for no outliers. */
+  whisker?: WhiskerRule;
+  /** Quantile interpolation method. Default `"type-7"` (R default). */
+  quantile?: QuantileMethod;
+  /**
+   * Render notches around the median at `± 1.58 · IQR / √n` (McGill 1978's
+   * 95% CI). Useful as an informal significance test: non-overlapping
+   * notches between groups suggest medians differ. Default `false`.
+   */
+  notched?: boolean;
+  /**
+   * Notch indent as a fraction of the box width (how far the sides pull in
+   * at the median). Default `0.5`.
+   */
+  notchWidth?: number;
+  /**
+   * When to overlay raw jittered points.
+   *
+   * - `"auto"` (default) — only when `n < pointsThreshold` for the group.
+   *   Rationale: small samples are easy to mislead with a box; show the dots.
+   * - `"always"` — always overlay.
+   * - `"none"` — never overlay (still draws outliers unless `outliers: false`).
+   */
+  points?: PointsMode;
+  /** Threshold for `points: "auto"`. Default `10`. */
+  pointsThreshold?: number;
+  /** Jitter spread, fraction of the per-box width. Default `0.5`. */
+  pointJitter?: number;
+  /** Radius of overlay & outlier points. Default `2.5`. */
+  pointRadius?: number;
+  /** Override fill for jittered overlay points. Default `alphaize(stroke, 0.5)`. */
+  pointFill?: Color;
+  /** Override fill for outlier points. Default = stroke. */
+  outlierFill?: Color;
+  /** Outlier point radius. Default = `pointRadius`. */
+  outlierRadius?: number;
+  /** Seed for deterministic jitter. Default `1`. */
+  jitterSeed?: number;
+  /** Render outlier dots beyond the whiskers. Default `true`. */
+  outliers?: boolean;
+  /** Constant fill when no `color` channel. Default theme palette[0]. */
+  fill?: Color;
+  /**
+   * Override the theme's fill alpha (use `0` for outline-only boxes, e.g.
+   * to match ggplot's bottom-middle "no-fill" look). When unset the layer
+   * uses `theme.marks.fillAlpha`.
+   */
+  fillAlpha?: number;
+  /** Box stroke color. Default theme text color (light line on dark fill). */
+  stroke?: Color;
+  /** Box stroke width. Default `1`. */
+  strokeWidth?: number;
+  /** Median line color. Defaults to `stroke`. */
+  medianStroke?: Color;
+  /** Median line stroke width. Default `2`. */
+  medianStrokeWidth?: number;
+  /** Whisker line stroke width. Default = `strokeWidth`. */
+  whiskerStrokeWidth?: number;
+  /** Whisker cap width as a fraction of box width. Default `0.5`. */
+  capWidth?: number;
+  /**
+   * Mean overlay. `true` for the default red dot; `false` (default) to omit;
+   * pass an object to customize shape, radius, fill, stroke. The mean is
+   * **not** part of the box geometry — it's an annotation on top.
+   */
+  mean?: boolean | MeanMarkerOptions;
+  /** Inner-band padding for grouped (color-split) layout. Default `0.05`. */
+  groupPadding?: number;
+  /**
+   * Render an `n=<count>` label per band-axis category, just outside the
+   * plot frame. Counts are summed across dodge groups. Default `false`.
+   */
+  showCounts?: boolean;
+  /** Pixel offset of count labels from plot frame. Default `28` (vertical) / `32` (horizontal). */
+  countsOffset?: number;
+  countsFontSize?: number;
+  countsColor?: Color;
+  /** Display label for legend. */
+  label?: string;
+}
+
+interface BoxLayout {
+  bucket: CategoricalBucket;
+  /** Index of this bucket in `layout.buckets` — used to match against hover dataIndex. */
+  bucketIndex: number;
+  /** Top-left of box on the band axis. */
+  bandPos: number;
+  /** Box thickness on the band axis (after `varwidth` scaling). */
+  bandSize: number;
+  /** Cap thickness on the band axis. */
+  capSize: number;
+  /** Notch indent in pixels (0 when `notched: false` or n=1). */
+  notchInset: number;
+  /** Half-height of the notch around the median, in value-axis pixels. */
+  notchHalfPx: number;
+  stats: BoxStats;
+  /** Pre-resolved fill (already alphaized). */
+  fill: Color;
+  /** Stroke width for this box. */
+  strokeWidth: number;
+  /** Whisker stroke width for this box. */
+  whiskerStrokeWidth: number;
+  /**
+   * GPU emphasis key for this box (P5-T3). The SAME key is written onto EVERY
+   * primitive of the box (fill rect/notched polygon, median, whiskers, outlier
+   * + raw + mean dots) so the whole entity dims uniformly — a half-dimmed box
+   * is worse than none. Ordinal mirrors the hit identity (`bucketIndex`).
+   * `undefined` when emphasis is off (SSR/SVG, hover disabled).
+   */
+  emphasisKey?: number;
+}
+
+const DEFAULT_MEAN_FILL: Color = { r: 0.85, g: 0.18, b: 0.18, a: 1 };
+
+export function boxplot<T>(channels: BoxplotChannels<T>, options: BoxplotOptions = {}): Geom<T> {
+  // The categorical layout helper stringifies the band axis and reads the
+  // value axis as a number; `y` may be the band category (horizontal layouts),
+  // so widen-then-narrow at the helper boundary. Same pattern as ridgeline.
+  const catChannels = channels as unknown as CategoricalChannels<T>;
+  const whisker = options.whisker ?? 1.5;
+  const quantileMethod = options.quantile ?? "type-7";
+
+  // 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.
+  const statsCache = new WeakMap<CompileContext<T>, Map<CategoricalBucket, BoxStats | null>>();
+  const getStats = (ctx: CompileContext<T>, bucket: CategoricalBucket): BoxStats | null => {
+    let perCtx = statsCache.get(ctx);
+    if (!perCtx) {
+      perCtx = new Map();
+      statsCache.set(ctx, perCtx);
+    }
+    if (perCtx.has(bucket)) return perCtx.get(bucket) ?? null;
+    const s = boxStats(bucket.values, { whisker, quantile: quantileMethod });
+    perCtx.set(bucket, s ?? null);
+    return s ?? null;
+  };
+
+  return {
+    kind: "boxplot",
+    channels: { x: channels.x, y: channels.y, color: channels.color },
+    label: options.label,
+    compile(ctx: CompileContext<T>) {
+      const { plot, theme, atlas } = ctx;
+      const layout = prepareCategoricalLayout(ctx, catChannels, {
+        orientation: options.orientation,
+        groupPadding: options.groupPadding,
+        fill: options.fill,
+      });
+      const { orientation, valueAxis, cellSize, ox, oy, buckets } = layout;
+
+      const widthFraction = options.width ?? 0.6;
+      const capFraction = options.capWidth ?? 0.5;
+      const baseBoxSize = cellSize * widthFraction;
+      const notched = options.notched ?? false;
+      const notchWidth = options.notchWidth ?? 0.5;
+
+      // First pass: compute stats so we know the sample-size max for varwidth.
+      interface PreLayout {
+        bucket: CategoricalBucket;
+        stats: BoxStats;
+      }
+      const pre: PreLayout[] = [];
+      let nMax = 0;
+      for (const bucket of buckets) {
+        const stats = getStats(ctx, bucket);
+        if (!stats) continue;
+        if (stats.n > nMax) nMax = stats.n;
+        pre.push({ bucket, stats });
+      }
+      const useVarwidth = options.varwidth === true && nMax > 0;
+
+      // Apply optional fillAlpha override per-bucket without disturbing the
+      // categorical layout's resolveFill (which already applied theme alpha).
+      const fillAlphaOverride = options.fillAlpha;
+      const reFill = (bucket: CategoricalBucket): Color => {
+        const fill = layout.resolveFill(bucket);
+        return fillAlphaOverride === undefined ? fill : { ...fill, a: fillAlphaOverride };
+      };
+
+      // Hover dim rides the core's GPU emphasis uniform (P5-T3). Polygon-fill
+      // emphasis keys (added in this change) now reach `pushPolygon` (notched
+      // boxes) and glyph markers, so a box can be tagged as ONE entity: the SAME
+      // key is written onto every primitive (fill, median, whiskers, dots, mean)
+      // so the whole box dims uniformly. The ordinal is `bucketIndex`, which is
+      // exactly the `dataIndex` compileHitTest reports — so the mount's
+      // emphasisResolution maps a hover hit to this same key with no recompile.
+      const emph = emphasisContext(ctx, "boxplot");
+      const stroke: Color = options.stroke ?? theme.text.color;
+      const baseStrokeWidth = options.strokeWidth ?? 1;
+      const medianStroke: Color = options.medianStroke ?? stroke;
+      const medianStrokeWidth = options.medianStrokeWidth ?? 2;
+      const baseWhiskerStrokeWidth = options.whiskerStrokeWidth ?? baseStrokeWidth;
+
+      const layouts: BoxLayout[] = [];
+      for (const p of pre) {
+        const bandCenter = bucketBandCenter(layout, p.bucket);
+        if (Number.isNaN(bandCenter)) continue;
+        const bucketIndex = buckets.indexOf(p.bucket);
+
+        const sizeFactor = useVarwidth ? Math.sqrt(p.stats.n / nMax) : 1;
+        const boxSize = baseBoxSize * sizeFactor;
+        const capSize = boxSize * capFraction;
+        const bandPos = bandCenter - boxSize / 2;
+
+        let notchInset = 0;
+        let notchHalfPx = 0;
+        if (notched && p.stats.n > 1) {
+          // McGill notch: ± 1.58 * IQR / sqrt(n).
+          const halfData = (1.58 * p.stats.iqr) / Math.sqrt(p.stats.n);
+          // Clamp the notch into the IQR — avoids the "flying triangles"
+          // artefact when the CI is wider than the box.
+          const q1Px = valueAxis(p.stats.q1);
+          const q3Px = valueAxis(p.stats.q3);
+          const medPx = valueAxis(p.stats.median);
+          const loPx = valueAxis(p.stats.median - halfData);
+          const hiPx = valueAxis(p.stats.median + halfData);
+          const halfPxRaw = Math.max(Math.abs(medPx - loPx), Math.abs(hiPx - medPx));
+          const iqrHalfPx = Math.abs(q3Px - q1Px) / 2;
+          notchHalfPx = Math.min(halfPxRaw, iqrHalfPx);
+          notchInset = (boxSize / 2) * notchWidth;
+        }
+
+        layouts.push({
+          bucket: p.bucket,
+          bucketIndex,
+          bandPos,
+          bandSize: boxSize,
+          capSize,
+          notchInset,
+          notchHalfPx,
+          stats: p.stats,
+          fill: reFill(p.bucket),
+          strokeWidth: baseStrokeWidth,
+          whiskerStrokeWidth: baseWhiskerStrokeWidth,
+          emphasisKey: emph?.keyFor(bucketIndex),
+        });
+      }
+
+      const showOutliers = options.outliers ?? true;
+      const pointsMode: PointsMode = options.points ?? "auto";
+      const pointsThreshold = options.pointsThreshold ?? DEFAULT_POINTS_THRESHOLD;
+      const pointJitter = options.pointJitter ?? 0.5;
+      const pointRadius = options.pointRadius ?? 2.5;
+      const outlierRadius = options.outlierRadius ?? pointRadius;
+      const outlierFill: Color = options.outlierFill ?? stroke;
+      const overlayFill: Color = options.pointFill ?? alphaize(stroke, 0.5);
+      const jitterSeed = options.jitterSeed ?? 1;
+
+      const meanCfg: MeanMarkerOptions | null =
+        options.mean === true
+          ? {}
+          : options.mean === false || options.mean === undefined
+            ? null
+            : options.mean;
+
+      const showCounts = options.showCounts ?? false;
+      const countsFontSize = options.countsFontSize ?? theme.marks.labelFontSize;
+      const countsColor: Color = options.countsColor ?? theme.text.color;
+      const countsOffset = options.countsOffset ?? (orientation === "y" ? 28 : 32);
+
+      const builder = {
+        length: layouts.length,
+        addTo(layer: Layer): Layer {
+          for (const lay of layouts) {
+            drawBox(layer, lay, {
+              orientation,
+              valueAxis,
+              ox,
+              oy,
+              fill: lay.fill,
+              stroke,
+              strokeWidth: lay.strokeWidth,
+              medianStroke,
+              medianStrokeWidth,
+              whiskerStrokeWidth: lay.whiskerStrokeWidth,
+              emphasisKey: lay.emphasisKey,
+            });
+
+            if (showOutliers && lay.stats.outliers.length > 0) {
+              drawPoints(layer, lay, lay.stats.outliers, {
+                orientation,
+                valueAxis,
+                ox,
+                oy,
+                radius: outlierRadius,
+                fill: outlierFill,
+                jitterValues: undefined,
+                emphasisKey: lay.emphasisKey,
+              });
+            }
+
+            const showRaw =
+              pointsMode === "always" || (pointsMode === "auto" && lay.stats.n < pointsThreshold);
+            if (showRaw) {
+              const jitterValues = jitter(
+                bucketSeed(lay.bucket, jitterSeed),
+                lay.bucket.values.length,
+                lay.bandSize * pointJitter,
+              );
+              drawPoints(layer, lay, lay.bucket.values, {
+                orientation,
+                valueAxis,
+                ox,
+                oy,
+                radius: pointRadius,
+                fill: overlayFill,
+                jitterValues,
+                emphasisKey: lay.emphasisKey,
+              });
+            }
+
+            if (meanCfg) {
+              drawMean(layer, lay, meanCfg, {
+                orientation,
+                valueAxis,
+                ox,
+                oy,
+                stroke,
+                emphasisKey: lay.emphasisKey,
+              });
+            }
+          }
+
+          if (showCounts && atlas) {
+            const labelMark = countsLabelMark(
+              layout,
+              {
+                offset: countsOffset,
+                fontSize: countsFontSize,
+                color: countsColor,
+              },
+              plot.width,
+              plot.height,
+            );
+            labelMark.addTo(layer, plot.topLeft);
+          }
+
+          return layer;
+        },
+      };
+
+      return [builder];
+    },
+    emphasisResolution(ctx) {
+      // Ordinal = the hit's `dataIndex`, which compileHitTest sets to the
+      // pre-filter `bucketIndex` — the same value `compile` tags each box with.
+      return emphasisContext(ctx, "boxplot")?.resolver() ?? null;
+    },
+    compileHitTest(ctx: CompileContext<T>): CompiledHitTest<T> | null {
+      const { data } = ctx;
+      const layout = prepareCategoricalLayout(ctx, catChannels, {
+        orientation: options.orientation,
+        groupPadding: options.groupPadding,
+        fill: options.fill,
+      });
+      const { orientation, valueAxis, ox, oy, buckets, dodging } = layout;
+
+      // One hit per non-empty bucket at (bandCenter, median).
+      // Rect covers whisker-low → whisker-high on the value axis × full band slot.
+      const positions = new Float32Array(buckets.length * 2);
+      const rects = new Float32Array(buckets.length * 4);
+      const seriesKey: (string | undefined)[] = Array.from({ length: buckets.length });
+      // Stash per-hit stats so the synthetic channel accessors can return them
+      // on tooltip lookup. Index aligns 1:1 with `dataIndex`.
+      const stats: BoxStats[] = 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, so `compile()` can match
+      // its hovered bucket via `buckets.indexOf(bucket)` and the synth
+      // channel accessors can index into the per-bucket side arrays
+      // (`stats`/`categories`/`groupKeys`) with the same key.
+      const hitBucketIndex: number[] = Array.from({ length: buckets.length });
+      let n = 0;
+      for (let bi = 0; bi < buckets.length; bi++) {
+        const bucket = buckets[bi]!;
+        const s = getStats(ctx, bucket);
+        if (!s) continue;
+        const bandCenter = bucketBandCenter(layout, bucket);
+        if (!Number.isFinite(bandCenter)) continue;
+        const medianPx = valueAxis(s.median);
+        if (!Number.isFinite(medianPx)) continue;
+        const whiskerLoPx = valueAxis(s.lowerWhisker);
+        const whiskerHiPx = valueAxis(s.upperWhisker);
+        const valueLo = Math.min(whiskerLoPx, whiskerHiPx);
+        const valueHi = Math.max(whiskerLoPx, whiskerHiPx);
+        const valueSpan = Math.max(valueHi - valueLo, 1);
+        const bandStart = bandCenter - layout.cellSize / 2;
+        if (orientation === "y") {
+          positions[n * 2] = ox + bandCenter;
+          positions[n * 2 + 1] = oy + medianPx;
+          rects[n * 4] = ox + bandStart;
+          rects[n * 4 + 1] = oy + valueLo;
+          rects[n * 4 + 2] = layout.cellSize;
+          rects[n * 4 + 3] = valueSpan;
+        } else {
+          positions[n * 2] = ox + medianPx;
+          positions[n * 2 + 1] = oy + bandCenter;
+          rects[n * 4] = ox + valueLo;
+          rects[n * 4 + 1] = oy + bandStart;
+          rects[n * 4 + 2] = valueSpan;
+          rects[n * 4 + 3] = layout.cellSize;
+        }
+        seriesKey[n] = dodging ? bucket.groupKey : bucket.category;
+        // Side arrays keyed by pre-filter bucket index; the synth accessors
+        // and `compile`'s hover lookup use the same key.
+        stats[bi] = s;
+        categories[bi] = bucket.category;
+        groupKeys[bi] = bucket.groupKey;
+        hitBucketIndex[n] = bi;
+        n++;
+      }
+      if (n === 0) return null;
+
+      // Half the cell on the band axis is generous enough that the cursor
+      // anywhere over a box picks it. Off-axis distance still matters via
+      // Euclidean default, so users still get a per-bucket selection.
+      const pickRadius = Math.max(layout.cellSize / 2, 8);
+
+      const channelsMap: ResolvedChannelMap<T> = {
+        x: synthAes(orientation === "y" ? "category" : "median", (_d, idx) =>
+          orientation === "y" ? categories[idx] : stats[idx]!.median,
+        ),
+        y: synthAes(orientation === "y" ? "median" : "category", (_d, idx) =>
+          orientation === "y" ? stats[idx]!.median : categories[idx],
+        ),
+        color: dodging ? synthAes("group", (_d, idx) => groupKeys[idx] ?? "") : undefined,
+      };
+
+      // dataIndex points at the pre-filter bucket position so it agrees
+      // with `compile`'s `buckets.indexOf(bucket)` and with the synth
+      // accessors above. `bi ≤ buckets.length ≤ data.length`, so the
+      // value is also a valid (if irrelevant) source-row index.
+      const dataIndexFinal = new Int32Array(n);
+      for (let i = 0; i < n; i++) dataIndexFinal[i] = hitBucketIndex[i]!;
+
+      return {
+        geomKind: "boxplot",
+        label: options.label,
+        positions: positions.subarray(0, n * 2),
+        rects: rects.subarray(0, n * 4),
+        dataIndex: dataIndexFinal,
+        seriesKey: seriesKey.slice(0, n),
+        pickRadius,
+        channels: channelsMap,
+        data,
+      };
+    },
+  };
+}
+
+interface DrawBoxCtx {
+  orientation: "x" | "y";
+  valueAxis: ContinuousScale;
+  ox: number;
+  oy: number;
+  fill: Color;
+  stroke: Color;
+  strokeWidth: number;
+  medianStroke: Color;
+  medianStrokeWidth: number;
+  whiskerStrokeWidth: number;
+  /** GPU emphasis key threaded onto every primitive of the box (P5-T3). */
+  emphasisKey?: number;
+}
+
+function drawBox(layer: Layer, lay: BoxLayout, c: DrawBoxCtx) {
+  const { stats } = lay;
+  const valuePos = (v: number) => c.valueAxis(v);
+  const bp = lay.bandPos;
+  const bs = lay.bandSize;
+  const center = bp + bs / 2;
+  const capHalf = lay.capSize / 2;
+
+  // Draws a whisker line from `boxEdge` to `whiskerEnd` along the value axis,
+  // plus a perpendicular cap at the whisker end. `axis` selects which screen
+  // axis the value lives on.
+  const drawWhisker = (axis: "x" | "y", boxEdge: number, whiskerEnd: number) => {
+    const stemA =
+      axis === "y"
+        ? { x: c.ox + center, y: c.oy + boxEdge }
+        : { x: c.ox + boxEdge, y: c.oy + center };
+    const stemB =
+      axis === "y"
+        ? { x: c.ox + center, y: c.oy + whiskerEnd }
+        : { x: c.ox + whiskerEnd, y: c.oy + center };
+    const capA =
+      axis === "y"
+        ? { x: c.ox + center - capHalf, y: c.oy + whiskerEnd }
+        : { x: c.ox + whiskerEnd, y: c.oy + center - capHalf };
+    const capB =
+      axis === "y"
+        ? { x: c.ox + center + capHalf, y: c.oy + whiskerEnd }
+        : { x: c.ox + whiskerEnd, y: c.oy + center + capHalf };
+    layer.pushPolyline({
+      points: [stemA, stemB],
+      color: c.stroke,
+      width: c.whiskerStrokeWidth,
+      emphasisKey: c.emphasisKey,
+    });
+    layer.pushPolyline({
+      points: [capA, capB],
+      color: c.stroke,
+      width: c.whiskerStrokeWidth,
+      emphasisKey: c.emphasisKey,
+    });
+  };
+
+  if (c.orientation === "y") {
+    const yQ1 = valuePos(stats.q1);
+    const yQ3 = valuePos(stats.q3);
+    const yMed = valuePos(stats.median);
+    const yLo = valuePos(stats.lowerWhisker);
+    const yHi = valuePos(stats.upperWhisker);
+    const yTop = Math.min(yQ1, yQ3);
+    const yBot = Math.max(yQ1, yQ3);
+
+    if (lay.notchInset > 0) {
+      drawNotchedBox(layer, {
+        orientation: "y",
+        ox: c.ox,
+        oy: c.oy,
+        bp,
+        bs,
+        yTop,
+        yBot,
+        yMed,
+        notchInset: lay.notchInset,
+        notchHalfPx: lay.notchHalfPx,
+        fill: c.fill,
+        stroke: c.stroke,
+        strokeWidth: c.strokeWidth,
+        emphasisKey: c.emphasisKey,
+      });
+      layer.pushPolyline({
+        points: [
+          { x: c.ox + bp + lay.notchInset, y: c.oy + yMed },
+          { x: c.ox + bp + bs - lay.notchInset, y: c.oy + yMed },
+        ],
+        color: c.medianStroke,
+        width: c.medianStrokeWidth,
+        emphasisKey: c.emphasisKey,
+      });
+    } else {
+      layer.pushRect({
+        x: c.ox + bp,
+        y: c.oy + yTop,
+        width: bs,
+        height: Math.max(yBot - yTop, 0.5),
+        fill: c.fill,
+        stroke: c.stroke,
+        strokeWidth: c.strokeWidth,
+        emphasisKey: c.emphasisKey,
+      });
+      layer.pushPolyline({
+        points: [
+          { x: c.ox + bp, y: c.oy + yMed },
+          { x: c.ox + bp + bs, y: c.oy + yMed },
+        ],
+        color: c.medianStroke,
+        width: c.medianStrokeWidth,
+        emphasisKey: c.emphasisKey,
+      });
+    }
+
+    drawWhisker("y", yTop, Math.min(yLo, yHi));
+    drawWhisker("y", yBot, Math.max(yLo, yHi));
+  } else {
+    const xQ1 = valuePos(stats.q1);
+    const xQ3 = valuePos(stats.q3);
+    const xMed = valuePos(stats.median);
+    const xLo = valuePos(stats.lowerWhisker);
+    const xHi = valuePos(stats.upperWhisker);
+    const xLeft = Math.min(xQ1, xQ3);
+    const xRight = Math.max(xQ1, xQ3);
+
+    if (lay.notchInset > 0) {
+      drawNotchedBox(layer, {
+        orientation: "x",
+        ox: c.ox,
+        oy: c.oy,
+        bp,
+        bs,
+        yTop: xLeft,
+        yBot: xRight,
+        yMed: xMed,
+        notchInset: lay.notchInset,
+        notchHalfPx: lay.notchHalfPx,
+        fill: c.fill,
+        stroke: c.stroke,
+        strokeWidth: c.strokeWidth,
+        emphasisKey: c.emphasisKey,
+      });
+      layer.pushPolyline({
+        points: [
+          { x: c.ox + xMed, y: c.oy + bp + lay.notchInset },
+          { x: c.ox + xMed, y: c.oy + bp + bs - lay.notchInset },
+        ],
+        color: c.medianStroke,
+        width: c.medianStrokeWidth,
+        emphasisKey: c.emphasisKey,
+      });
+    } else {
+      layer.pushRect({
+        x: c.ox + xLeft,
+        y: c.oy + bp,
+        width: Math.max(xRight - xLeft, 0.5),
+        height: bs,
+        fill: c.fill,
+        stroke: c.stroke,
+        strokeWidth: c.strokeWidth,
+        emphasisKey: c.emphasisKey,
+      });
+      layer.pushPolyline({
+        points: [
+          { x: c.ox + xMed, y: c.oy + bp },
+          { x: c.ox + xMed, y: c.oy + bp + bs },
+        ],
+        color: c.medianStroke,
+        width: c.medianStrokeWidth,
+        emphasisKey: c.emphasisKey,
+      });
+    }
+
+    drawWhisker("x", xLeft, Math.min(xLo, xHi));
+    drawWhisker("x", xRight, Math.max(xLo, xHi));
+  }
+}
+
+interface DrawNotchedCtx {
+  orientation: "x" | "y";
+  ox: number;
+  oy: number;
+  bp: number;
+  bs: number;
+  /** Box edge along the value axis, first endpoint (y-top or x-left). */
+  yTop: number;
+  /** Box edge along the value axis, second endpoint (y-bot or x-right). */
+  yBot: number;
+  /** Median position along the value axis. */
+  yMed: number;
+  notchInset: number;
+  notchHalfPx: number;
+  fill: Color;
+  stroke: Color;
+  strokeWidth: number;
+  emphasisKey?: number;
+}
+
+/**
+ * 10-point polygon for a notched box. Walks: corner → notch top → notch waist
+ * → notch bottom → corner → corner → notch bottom → notch waist → notch top
+ * → corner. Same routine for both orientations — just swaps which axis the
+ * "value" coordinate maps to.
+ */
+function drawNotchedBox(layer: Layer, c: DrawNotchedCtx) {
+  const { bp, bs, yTop, yBot, yMed, notchInset, notchHalfPx } = c;
+  const valTopNotch = yMed - notchHalfPx;
+  const valBotNotch = yMed + notchHalfPx;
+  const bandLeft = bp;
+  const bandRight = bp + bs;
+  const innerLeft = bp + notchInset;
+  const innerRight = bp + bs - notchInset;
+
+  const points: Vec2[] =
+    c.orientation === "y"
+      ? [
+          { x: c.ox + bandLeft, y: c.oy + yTop },
+          { x: c.ox + bandRight, y: c.oy + yTop },
+          { x: c.ox + bandRight, y: c.oy + valTopNotch },
+          { x: c.ox + innerRight, y: c.oy + yMed },
+          { x: c.ox + bandRight, y: c.oy + valBotNotch },
+          { x: c.ox + bandRight, y: c.oy + yBot },
+          { x: c.ox + bandLeft, y: c.oy + yBot },
+          { x: c.ox + bandLeft, y: c.oy + valBotNotch },
+          { x: c.ox + innerLeft, y: c.oy + yMed },
+          { x: c.ox + bandLeft, y: c.oy + valTopNotch },
+        ]
+      : [
+          { x: c.ox + yTop, y: c.oy + bandLeft },
+          { x: c.ox + yTop, y: c.oy + bandRight },
+          { x: c.ox + valTopNotch, y: c.oy + bandRight },
+          { x: c.ox + yMed, y: c.oy + innerRight },
+          { x: c.ox + valBotNotch, y: c.oy + bandRight },
+          { x: c.ox + yBot, y: c.oy + bandRight },
+          { x: c.ox + yBot, y: c.oy + bandLeft },
+          { x: c.ox + valBotNotch, y: c.oy + bandLeft },
+          { x: c.ox + yMed, y: c.oy + innerLeft },
+          { x: c.ox + valTopNotch, y: c.oy + bandLeft },
+        ];
+
+  pushFilledPolygon(layer, points, {
+    fill: c.fill,
+    stroke: c.stroke,
+    strokeWidth: c.strokeWidth,
+    emphasisKey: c.emphasisKey,
+  });
+}
+
+interface DrawPointsCtx {
+  orientation: "x" | "y";
+  valueAxis: ContinuousScale;
+  ox: number;
+  oy: number;
+  radius: number;
+  fill: Color;
+  /** Pre-computed jitter offsets (one per value). Undefined → no jitter. */
+  jitterValues: number[] | undefined;
+  emphasisKey?: number;
+}
+
+function drawPoints(layer: Layer, lay: BoxLayout, values: readonly number[], c: DrawPointsCtx) {
+  const center = lay.bandPos + lay.bandSize / 2;
+  const valuePos = (v: number) => c.valueAxis(v);
+  const mark = pointMark(values as number[], {
+    x: (v, i) =>
+      c.orientation === "y"
+        ? c.ox + center + (c.jitterValues ? (c.jitterValues[i] ?? 0) : 0)
+        : c.ox + valuePos(v),
+    y: (v, i) =>
+      c.orientation === "y"
+        ? c.oy + valuePos(v)
+        : c.oy + center + (c.jitterValues ? (c.jitterValues[i] ?? 0) : 0),
+    radius: c.radius,
+    fill: c.fill,
+    emphasisKey: c.emphasisKey === undefined ? undefined : () => c.emphasisKey,
+  });
+  mark.addTo(layer);
+}
+
+interface DrawMeanCtx {
+  orientation: "x" | "y";
+  valueAxis: ContinuousScale;
+  ox: number;
+  oy: number;
+  stroke: Color;
+  emphasisKey?: number;
+}
+
+function drawMean(layer: Layer, lay: BoxLayout, cfg: MeanMarkerOptions, c: DrawMeanCtx) {
+  const center = lay.bandPos + lay.bandSize / 2;
+  const valuePos = c.valueAxis(lay.stats.mean);
+  const mark = pointMark([lay.stats.mean], {
+    x: () => (c.orientation === "y" ? c.ox + center : c.ox + valuePos),
+    y: () => (c.orientation === "y" ? c.oy + valuePos : c.oy + center),
+    radius: cfg.radius ?? 3.5,
+    fill: cfg.fill ?? DEFAULT_MEAN_FILL,
+    stroke: cfg.stroke,
+    strokeWidth: cfg.strokeWidth,
+    shape: cfg.shape ?? "circle",
+    emphasisKey: c.emphasisKey === undefined ? undefined : () => c.emphasisKey,
+  });
+  mark.addTo(layer);
+}
+
+// Re-export for tests / advanced users that want the shared layout shape.
+export type { CategoricalLayout };