insomni-plot 0.1.0-alpha.0

package/src/grammar/geoms/aggregate.ts

@@ -0,0 +1,840 @@
+// ---------------------------------------------------------------------------
+// aggregate geom — data-density binning with semantic-zoom dissolve
+// ---------------------------------------------------------------------------
+// Bins source data along x or y, summarises each bin, and emits the result
+// through one of `point` / `line` / `bar`. When the average datapoints-per-bin
+// drops below `dissolveAt` the geom renders the raw input instead — so at
+// extreme zoom-out you get a clean summary curve, and as you zoom in the geom
+// transparently dissolves to the underlying scatter / line / bars.
+//
+// Generic across any high-cardinality numeric or time-axis stream (telemetry,
+// log events, geo points, financial ticks, sensor readings). The medical
+// weight chart is one consumer.
+//
+// Implementation notes:
+//   - Pure, scale-aware compile. `binSize: 'auto'` reads the active scale's
+//     pixel range + domain to target ~7px per bin on the binned axis.
+//   - Dissolve threshold is checked AFTER binning: if avg/bin < dissolveAt,
+//     skip the synthetic series and forward the original (post-filter) rows
+//     to the chosen inner mark.
+//   - Bin axis must be continuous (linear / log / sqrt / time). Band scales
+//     are not supported as a bin axis — they're already categorical.
+
+import { type Color } from "insomni";
+import {
+  barMark,
+  lineMark,
+  pointMark,
+  type LineCurve,
+  type MarkBuilder,
+  type PointShapeKind,
+} from "../../marks.ts";
+import type { Aes } from "../aes.ts";
+import { resolveAes } from "../aes.ts";
+import { alphaize } from "../color-utils.ts";
+import { interval } from "./interval.ts";
+import { ribbon } from "./ribbon.ts";
+import type { CompileContext, Geom } from "./types.ts";
+import { defaultMarkFill, wrapMark } from "./_mark.ts";
+import { DEFAULT_CI_LEVEL } from "../constants.ts";
+
+export type AggregateBinBy = "x" | "y";
+
+export type AggregateBinSize = number | "auto" | ((info: AutoBinSizeInfo) => number);
+
+export interface AutoBinSizeInfo {
+  /** Pixel span of the binned axis (positive). */
+  pixelSpan: number;
+  /** Domain span of the binned axis in axis units (positive). For time scales, ms. */
+  domainSpan: number;
+  /** `pixelSpan / domainSpan` — pixels per domain unit on the binned axis. */
+  pixelsPerUnit: number;
+}
+
+export type AggregateSummaryKind = "mean" | "median" | "count" | "sum" | "first" | "last";
+
+export interface AggregateBinView<T> {
+  /** Values from the *non-binned* axis, in input order within this bin. */
+  values: readonly number[];
+  /** Source items inside this bin, in input order. */
+  items: readonly T[];
+  /** Count after filter. */
+  count: number;
+  /** Bin's lower edge on the binned axis (inclusive). */
+  lo: number;
+  /** Bin's upper edge on the binned axis (exclusive, except the final bin). */
+  hi: number;
+}
+
+export type AggregateSummary<T> = AggregateSummaryKind | ((bin: AggregateBinView<T>) => number);
+
+/** Result of a bundle summary — one center + a [lo, hi] range per bin. */
+export interface AggregateBundleResult {
+  center: number;
+  lo: number;
+  hi: number;
+}
+
+export type AggregateBundleSummaryKind = "mean+ci" | "median+iqr";
+
+/**
+ * Bundle summaries emit `{ center, lo, hi }` per bin and pair with the
+ * `interval` or `ribbon` inner geom. Built-in kinds plus a quantile triple
+ * `{ quantiles: [loQ, centerQ, hiQ] }` (e.g. `[0.1, 0.5, 0.9]` for an 80%
+ * range) or a custom function returning the bundle directly.
+ */
+export type AggregateBundleSummary<T> =
+  | AggregateBundleSummaryKind
+  | { quantiles: readonly [number, number, number] }
+  | ((bin: AggregateBinView<T>) => AggregateBundleResult);
+
+export interface AggregateChannels<T> {
+  x: Aes<T, number | Date>;
+  y: Aes<T, number | Date>;
+}
+
+export type AggregateInnerGeom = "point" | "line" | "bar" | "interval" | "ribbon";
+
+export interface AggregateOptions<T> {
+  /** Axis to slide along. Default `"x"`. */
+  binBy?: AggregateBinBy;
+  /** Bin width in domain units; `"auto"` targets `~autoTargetPx` px. Default `"auto"`. */
+  binSize?: AggregateBinSize;
+  /**
+   * Reduction applied per bin. Scalar kinds (`"mean"`, `"median"`, …) pair
+   * with `geom: "point" | "line" | "bar"`. Bundle kinds (`"mean+ci"`,
+   * `"median+iqr"`, `{ quantiles }`, function-returning-`{center, lo, hi}`)
+   * pair with `geom: "interval" | "ribbon"`. Default `"mean"`.
+   */
+  summary?: AggregateSummary<T> | AggregateBundleSummary<T>;
+  /** Row predicate. Rejected rows are excluded from both binning and the
+   *  raw-fallback path. */
+  filter?: (datum: T, index: number) => boolean;
+  /** When `avg-points-per-bin < dissolveAt`, render raw geom instead.
+   *  Default `1.2`. */
+  dissolveAt?: number;
+  /** Inner mark kind. Default `"point"`. */
+  geom?: AggregateInnerGeom;
+  /** Fill / stroke applied to every emitted mark. */
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  /** Point-specific. */
+  radius?: number;
+  shape?: PointShapeKind;
+  /** Line-specific. */
+  curve?: LineCurve;
+  /** Target pixels per bin for `"auto"` sizing. Default `7`. */
+  autoTargetPx?: number;
+  /** Display label for legend / hit-test (forwarded to inner mark). */
+  label?: string;
+  /**
+   * Confidence level for the `"mean+ci"` bundle summary. Default `0.95`.
+   * Ignored for other summaries.
+   */
+  ciLevel?: number;
+  /** Interval-specific: render perpendicular caps. Default `true`. */
+  caps?: boolean;
+  /** Interval-specific: cap length in pixels. Default `6`. */
+  capWidth?: number;
+  /** Ribbon-specific: fill alpha override (otherwise theme.marks.ribbonFillAlpha). */
+  fillAlpha?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+interface PreparedRow<T> {
+  binVal: number;
+  otherVal: number;
+  item: T;
+  sourceIndex: number;
+}
+
+interface ResolvedBin<T> {
+  lo: number;
+  hi: number;
+  center: number;
+  count: number;
+  values: number[];
+  items: T[];
+  /** Scalar aggregate (`NaN` when bin is empty or summary is bundle-typed). */
+  value: number;
+  /** Bundle aggregate (`undefined` when bin is empty or summary is scalar-typed). */
+  bundle?: AggregateBundleResult;
+}
+
+const BUNDLE_INNER: ReadonlySet<AggregateInnerGeom> = new Set(["interval", "ribbon"]);
+
+function isBundleSummary<T>(
+  summary: AggregateSummary<T> | AggregateBundleSummary<T> | undefined,
+): summary is AggregateBundleSummary<T> {
+  if (summary === undefined) return false;
+  if (typeof summary === "string") return summary === "mean+ci" || summary === "median+iqr";
+  if (typeof summary === "function") {
+    // Function form is intentionally ambiguous at the type level — callers
+    // must align `summary` with `geom`. The inner-geom kind is the runtime
+    // discriminator (see compile).
+    return false;
+  }
+  return Array.isArray((summary as { quantiles?: unknown }).quantiles);
+}
+
+function quantileSorted(sorted: readonly number[], q: number): number {
+  const n = sorted.length;
+  if (n === 0) return Number.NaN;
+  if (n === 1) return sorted[0]!;
+  const clamped = q < 0 ? 0 : q > 1 ? 1 : q;
+  const pos = clamped * (n - 1);
+  const lo = Math.floor(pos);
+  const hi = Math.ceil(pos);
+  if (lo === hi) return sorted[lo]!;
+  return sorted[lo]! * (1 - (pos - lo)) + sorted[hi]! * (pos - lo);
+}
+
+/**
+ * Inverse standard-normal CDF via Acklam's rational approximation. Used to
+ * map a CI level (e.g. 0.95) → z (≈1.96) without dragging in a stats library.
+ * Accurate to ~1.15e-9 over the full open interval (0, 1).
+ */
+function inverseNormalCdf(p: number): number {
+  if (!(p > 0 && p < 1)) return Number.NaN;
+  const a = [
+    -3.969683028665376e1, 2.209460984245205e2, -2.759285104469687e2, 1.38357751867269e2,
+    -3.066479806614716e1, 2.506628277459239,
+  ];
+  const b = [
+    -5.447609879822406e1, 1.615858368580409e2, -1.556989798598866e2, 6.680131188771972e1,
+    -1.328068155288572e1,
+  ];
+  const c = [
+    -7.784894002430293e-3, -3.223964580411365e-1, -2.400758277161838, -2.549732539343734,
+    4.374664141464968, 2.938163982698783,
+  ];
+  const d = [7.784695709041462e-3, 3.224671290700398e-1, 2.445134137142996, 3.754408661907416];
+  const pLow = 0.02425;
+  const pHigh = 1 - pLow;
+  if (p < pLow) {
+    const q = Math.sqrt(-2 * Math.log(p));
+    return (
+      (((((c[0]! * q + c[1]!) * q + c[2]!) * q + c[3]!) * q + c[4]!) * q + c[5]!) /
+      ((((d[0]! * q + d[1]!) * q + d[2]!) * q + d[3]!) * q + 1)
+    );
+  }
+  if (p <= pHigh) {
+    const q = p - 0.5;
+    const r = q * q;
+    return (
+      ((((((a[0]! * r + a[1]!) * r + a[2]!) * r + a[3]!) * r + a[4]!) * r + a[5]!) * q) /
+      (((((b[0]! * r + b[1]!) * r + b[2]!) * r + b[3]!) * r + b[4]!) * r + 1)
+    );
+  }
+  const q = Math.sqrt(-2 * Math.log(1 - p));
+  return -(
+    (((((c[0]! * q + c[1]!) * q + c[2]!) * q + c[3]!) * q + c[4]!) * q + c[5]!) /
+    ((((d[0]! * q + d[1]!) * q + d[2]!) * q + d[3]!) * q + 1)
+  );
+}
+
+function zForCiLevel(level: number): number {
+  return inverseNormalCdf((1 + level) / 2);
+}
+
+function reduceBundle<T>(
+  summary: AggregateBundleSummary<T>,
+  view: AggregateBinView<T>,
+  ciLevel: number,
+): AggregateBundleResult {
+  if (typeof summary === "function") return summary(view);
+  const values = view.values;
+  const n = values.length;
+  if (n === 0) return { center: Number.NaN, lo: Number.NaN, hi: Number.NaN };
+
+  if (summary === "mean+ci") {
+    let sum = 0;
+    for (const v of values) sum += v;
+    const mean = sum / n;
+    if (n < 2) return { center: mean, lo: mean, hi: mean };
+    let sse = 0;
+    for (const v of values) {
+      const d = v - mean;
+      sse += d * d;
+    }
+    const stderr = Math.sqrt(sse / (n - 1)) / Math.sqrt(n);
+    const z = zForCiLevel(ciLevel);
+    const half = z * stderr;
+    return { center: mean, lo: mean - half, hi: mean + half };
+  }
+
+  // Sorted copy reused by quantile-based bundles.
+  const sorted = values.slice().sort((a, b) => a - b);
+  if (summary === "median+iqr") {
+    return {
+      center: quantileSorted(sorted, 0.5),
+      lo: quantileSorted(sorted, 0.25),
+      hi: quantileSorted(sorted, 0.75),
+    };
+  }
+  const qs = summary.quantiles;
+  return {
+    lo: quantileSorted(sorted, qs[0]),
+    center: quantileSorted(sorted, qs[1]),
+    hi: quantileSorted(sorted, qs[2]),
+  };
+}
+
+function coerceNumeric(value: unknown): number {
+  if (value instanceof Date) return value.getTime();
+  return value as number;
+}
+
+function reduce<T>(summary: AggregateSummary<T>, view: AggregateBinView<T>): number {
+  if (typeof summary === "function") return summary(view);
+  const values = view.values;
+  const n = values.length;
+  if (n === 0) return Number.NaN;
+  switch (summary) {
+    case "count":
+      return n;
+    case "mean": {
+      let s = 0;
+      for (const v of values) s += v;
+      return s / n;
+    }
+    case "sum": {
+      let s = 0;
+      for (const v of values) s += v;
+      return s;
+    }
+    case "first":
+      return values[0]!;
+    case "last":
+      return values[n - 1]!;
+    case "median": {
+      const sorted = values.slice().sort((a, b) => a - b);
+      const mid = n >>> 1;
+      return n % 2 === 0 ? (sorted[mid - 1]! + sorted[mid]!) / 2 : sorted[mid]!;
+    }
+  }
+}
+
+function resolveAutoBinSize(
+  scale: import("../scales.ts").PositionScale | undefined,
+  targetPx: number,
+): { binSize: number; info: AutoBinSizeInfo } | null {
+  if (!scale) return null;
+  if (scale.type === "band") return null;
+  const axis = scale.axisScale;
+  // band scales lack `.domain` as a numeric pair, but we've already returned.
+  const domain = (axis as { domain: readonly [number | Date, number | Date] }).domain;
+  const range = (axis as { range: readonly [number, number] }).range;
+  if (!domain || !range) return null;
+  const d0 = coerceNumeric(domain[0]);
+  const d1 = coerceNumeric(domain[1]);
+  const domainSpan = Math.abs(d1 - d0);
+  const pixelSpan = Math.abs(range[1] - range[0]);
+  if (!(domainSpan > 0) || !(pixelSpan > 0)) return null;
+  const pixelsPerUnit = pixelSpan / domainSpan;
+  const binSize = targetPx / pixelsPerUnit;
+  if (!(binSize > 0) || !Number.isFinite(binSize)) return null;
+  return { binSize, info: { pixelSpan, domainSpan, pixelsPerUnit } };
+}
+
+function buildBins<T>(
+  prepared: readonly PreparedRow<T>[],
+  binSize: number,
+  summary: AggregateSummary<T> | AggregateBundleSummary<T>,
+  extent: readonly [number, number] | null,
+  bundleMode: boolean,
+  ciLevel: number,
+): ResolvedBin<T>[] {
+  if (prepared.length === 0 || !(binSize > 0)) return [];
+
+  let lo: number;
+  let hi: number;
+  if (extent) {
+    [lo, hi] = extent[0] <= extent[1] ? [extent[0], extent[1]] : [extent[1], extent[0]];
+  } else {
+    lo = Number.POSITIVE_INFINITY;
+    hi = Number.NEGATIVE_INFINITY;
+    for (const row of prepared) {
+      if (row.binVal < lo) lo = row.binVal;
+      if (row.binVal > hi) hi = row.binVal;
+    }
+  }
+  if (!Number.isFinite(lo) || !Number.isFinite(hi) || hi < lo) return [];
+
+  // Anchor bins to multiples of binSize so neighbouring frames line up when
+  // the user pans — moves are integer-bin shifts rather than sub-bin drifts.
+  const start = Math.floor(lo / binSize) * binSize;
+  const span = hi - start;
+  const count = Math.max(1, Math.ceil((span + Number.EPSILON) / binSize));
+  if (count > 1_000_000) return [];
+
+  const bins: ResolvedBin<T>[] = Array.from({ length: count });
+  for (let i = 0; i < count; i++) {
+    const binLo = start + i * binSize;
+    bins[i] = {
+      lo: binLo,
+      hi: binLo + binSize,
+      center: binLo + binSize / 2,
+      count: 0,
+      values: [],
+      items: [],
+      value: Number.NaN,
+    };
+  }
+
+  for (const row of prepared) {
+    let idx = Math.floor((row.binVal - start) / binSize);
+    if (idx === count) idx = count - 1;
+    if (idx < 0 || idx >= count) continue;
+    const bin = bins[idx]!;
+    bin.count++;
+    bin.values.push(row.otherVal);
+    bin.items.push(row.item);
+  }
+
+  for (const bin of bins) {
+    if (bin.count === 0) continue;
+    const view: AggregateBinView<T> = {
+      values: bin.values,
+      items: bin.items,
+      count: bin.count,
+      lo: bin.lo,
+      hi: bin.hi,
+    };
+    if (bundleMode) {
+      bin.bundle = reduceBundle(summary as AggregateBundleSummary<T>, view, ciLevel);
+    } else {
+      bin.value = reduce(summary as AggregateSummary<T>, view);
+    }
+  }
+  return bins;
+}
+
+// Synthetic shape used for the inner mark when the geom emits aggregated bins.
+interface BinPoint {
+  x: number;
+  y: number;
+  count: number;
+}
+
+interface BundleBin {
+  x: number;
+  y: number;
+  lo: number;
+  hi: number;
+  count: number;
+}
+
+const GEOM_KIND_BY_INNER: Record<AggregateInnerGeom, import("./types.ts").GeomKind> = {
+  point: "point",
+  line: "line",
+  bar: "bar",
+  interval: "interval",
+  ribbon: "area",
+};
+
+export function aggregate<T>(
+  channels: AggregateChannels<T>,
+  options: AggregateOptions<T> = {},
+): Geom<T> {
+  const binBy: AggregateBinBy = options.binBy ?? "x";
+  const innerKind: AggregateInnerGeom = options.geom ?? "point";
+  const summaryOption = options.summary;
+  const bundleInner = BUNDLE_INNER.has(innerKind);
+  const summaryIsBundle = isBundleSummary(summaryOption);
+  // Function-form summaries are ambiguous at the type level — disambiguate by
+  // the inner geom: bundle inners always run the bundle path; scalar inners
+  // always run the scalar path. Built-in kinds are validated up front.
+  const bundleMode = bundleInner || summaryIsBundle;
+
+  if (summaryIsBundle && !bundleInner) {
+    throw new Error(
+      `aggregate(): bundle summary requires geom: "interval" | "ribbon" (got "${innerKind}").`,
+    );
+  }
+  if (
+    bundleInner &&
+    summaryOption !== undefined &&
+    !summaryIsBundle &&
+    typeof summaryOption !== "function"
+  ) {
+    throw new Error(
+      `aggregate(): geom: "${innerKind}" requires a bundle summary ("mean+ci", "median+iqr", { quantiles }, or a function returning {center, lo, hi}).`,
+    );
+  }
+  if (innerKind === "ribbon" && binBy !== "x") {
+    throw new Error(
+      'aggregate(): geom: "ribbon" only supports binBy: "x" (horizontal ribbons aren\'t supported yet).',
+    );
+  }
+
+  const summary: AggregateSummary<T> | AggregateBundleSummary<T> =
+    summaryOption ?? (bundleInner ? "mean+ci" : "mean");
+  const dissolveAt = options.dissolveAt ?? 1.2;
+  const autoTargetPx = options.autoTargetPx ?? 7;
+  const ciLevel = options.ciLevel ?? DEFAULT_CI_LEVEL;
+
+  return {
+    kind: GEOM_KIND_BY_INNER[innerKind],
+    channels: { x: channels.x as unknown, y: channels.y as unknown },
+    label: options.label,
+    compile(ctx: CompileContext<T>): readonly MarkBuilder[] {
+      const { data, scales, plot, theme } = ctx;
+      if (data.length === 0) return [];
+
+      const xAes = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+      const yAes = resolveAes<T, unknown>(channels.y as Aes<T, unknown>);
+      const xScale = scales.x.fn;
+      const yScale = scales.y.fn;
+
+      // Filter once. Used for both binning and the raw-dissolve path so the
+      // two views stay consistent.
+      const accepted: { item: T; index: number }[] = [];
+      const filter = options.filter;
+      for (let i = 0; i < data.length; i++) {
+        const d = data[i]!;
+        if (filter && !filter(d, i)) continue;
+        accepted.push({ item: d, index: i });
+      }
+      if (accepted.length === 0) return [];
+
+      // Resolve bin size against the binned-axis scale.
+      const binnedScale = binBy === "x" ? scales.x : scales.y;
+      let binSize: number;
+      if (typeof options.binSize === "number") {
+        binSize = options.binSize;
+      } else if (typeof options.binSize === "function") {
+        const auto = resolveAutoBinSize(binnedScale, autoTargetPx);
+        if (!auto) return [];
+        binSize = options.binSize(auto.info);
+      } else {
+        const auto = resolveAutoBinSize(binnedScale, autoTargetPx);
+        if (!auto) return [];
+        binSize = auto.binSize;
+      }
+      if (!(binSize > 0) || !Number.isFinite(binSize)) return [];
+
+      // Numeric-coerce the source rows and split into (bin, other) per axis.
+      const prepared: PreparedRow<T>[] = [];
+      for (const { item, index } of accepted) {
+        const xv = coerceNumeric(xAes.fn(item, index));
+        const yv = coerceNumeric(yAes.fn(item, index));
+        if (!Number.isFinite(xv) || !Number.isFinite(yv)) continue;
+        const binVal = binBy === "x" ? xv : yv;
+        const otherVal = binBy === "x" ? yv : xv;
+        prepared.push({ binVal, otherVal, item, sourceIndex: index });
+      }
+      if (prepared.length === 0) return [];
+
+      // Bin extent follows the active visible domain so zoom-in shrinks both
+      // the bin span and the points considered — that's what makes the
+      // dissolve threshold flip naturally as the user zooms.
+      const extent = visibleDomain(binnedScale);
+      const bins = buildBins(prepared, binSize, summary, extent, bundleMode, ciLevel);
+      const nonEmpty = bins.filter((b) => b.count > 0);
+      // Count points in the bin extent so dissolve / raw-fallback both see
+      // the same view of the data.
+      let pointsInExtent = 0;
+      if (bins.length > 0) {
+        const extLo = bins[0]!.lo;
+        const extHi = bins[bins.length - 1]!.hi;
+        for (const row of prepared) {
+          if (row.binVal >= extLo && row.binVal <= extHi) pointsInExtent++;
+        }
+      }
+      // Dissolve check: divide total points in the extent by the *total* bin
+      // count. At deep zoom-in the bin extent shrinks proportionally with the
+      // pixel-anchored bin size, but the in-extent point count shrinks faster
+      // — so density drops, and we fall back to the raw geom.
+      const avgPerBin = bins.length > 0 ? pointsInExtent / bins.length : 0;
+      // Bundle mode has no sensible "raw" fallback (interval/ribbon need a
+      // [lo, hi] per row, and raw rows don't carry one) — skip dissolve and
+      // always aggregate.
+      const dissolve = !bundleMode && avgPerBin < dissolveAt;
+
+      if (dissolve) {
+        // Forward the filtered rows to the inner mark with the original
+        // channels. We re-derive the items array (preserving input order) so
+        // line/bar accessors see contiguous indices.
+        const rawItems = accepted.map((a) => a.item);
+        return [wrapMark(buildRawMark(innerKind, rawItems, channels, options, ctx), plot.topLeft)];
+      }
+
+      // Bundle path: delegate to interval / ribbon with synthetic bin rows
+      // anchored at bin centers. Per-row state (hidden/selected/hovered) is
+      // cleared since bin-level selection isn't a concept at the aggregate
+      // layer.
+      if (bundleInner) {
+        const bundleBins: BundleBin[] = Array.from({ length: nonEmpty.length });
+        for (let i = 0; i < nonEmpty.length; i++) {
+          const bin = nonEmpty[i]!;
+          const b = bin.bundle!;
+          if (binBy === "x") {
+            bundleBins[i] = { x: bin.center, y: b.center, lo: b.lo, hi: b.hi, count: bin.count };
+          } else {
+            bundleBins[i] = { x: b.center, y: bin.center, lo: b.lo, hi: b.hi, count: bin.count };
+          }
+        }
+        const subCtx: CompileContext<BundleBin> = {
+          ...(ctx as unknown as CompileContext<BundleBin>),
+          data: bundleBins,
+          hidden: undefined,
+          selected: undefined,
+          hovered: null,
+          activeTransition: undefined,
+        };
+        if (innerKind === "interval") {
+          const innerGeom =
+            binBy === "x"
+              ? interval<BundleBin>(
+                  {
+                    x: (b) => b.x,
+                    yMin: (b) => b.lo,
+                    yMax: (b) => b.hi,
+                  },
+                  {
+                    stroke: options.stroke,
+                    strokeWidth: options.strokeWidth,
+                    caps: options.caps,
+                    capWidth: options.capWidth,
+                    label: options.label,
+                  },
+                )
+              : interval<BundleBin>(
+                  {
+                    y: (b) => b.y,
+                    xMin: (b) => b.lo,
+                    xMax: (b) => b.hi,
+                  },
+                  {
+                    stroke: options.stroke,
+                    strokeWidth: options.strokeWidth,
+                    caps: options.caps,
+                    capWidth: options.capWidth,
+                    label: options.label,
+                  },
+                );
+          return innerGeom.compile(subCtx);
+        }
+        // ribbon (binBy === "x" enforced at factory time)
+        const ribbonGeom = ribbon<BundleBin>(
+          {
+            x: (b) => b.x,
+            y0: (b) => b.lo,
+            y1: (b) => b.hi,
+          },
+          {
+            fill: options.fill,
+            stroke: options.stroke,
+            strokeWidth: options.strokeWidth,
+            fillAlpha: options.fillAlpha,
+            label: options.label,
+          },
+        );
+        return ribbonGeom.compile(subCtx);
+      }
+
+      // Build synthetic bin-points; only emit bins with data.
+      const fill = options.fill ?? defaultMarkFill(theme);
+      const stroke = options.stroke;
+      const strokeWidth = options.strokeWidth;
+
+      const points: BinPoint[] = Array.from({ length: nonEmpty.length });
+      for (let i = 0; i < nonEmpty.length; i++) {
+        const bin = nonEmpty[i]!;
+        if (binBy === "x") {
+          points[i] = { x: bin.center, y: bin.value, count: bin.count };
+        } else {
+          points[i] = { x: bin.value, y: bin.center, count: bin.count };
+        }
+      }
+
+      const builders: MarkBuilder[] = [];
+      if (innerKind === "point") {
+        const baseRadius = options.radius ?? theme.marks.pointRadius;
+        const shape = options.shape ?? "circle";
+        const pStroke = stroke === undefined ? (theme.marks.pointStroke ?? undefined) : stroke;
+        const pStrokeWidth = strokeWidth ?? theme.marks.pointStrokeWidth;
+        const mark = pointMark(points, {
+          x: (p) => xScale(p.x),
+          y: (p) => yScale(p.y),
+          radius: baseRadius,
+          fill: alphaize(fill, theme.marks.fillAlpha),
+          stroke: pStroke,
+          strokeWidth: pStrokeWidth,
+          shape,
+        });
+        builders.push(wrapMark(mark, plot.topLeft, points.length));
+      } else if (innerKind === "line") {
+        const lineStroke = strokeWidth ?? theme.marks.strokeWidth;
+        const lineColor = stroke ?? options.fill ?? theme.palettes.categorical(0);
+        // Sort by the binned axis so the polyline draws monotonically. Bins
+        // are already in axis order from `buildBins` (sequential index over
+        // `start + i * binSize`), so no extra sort is needed.
+        const mark = lineMark(points, {
+          x: (p) => xScale(p.x),
+          y: (p) => yScale(p.y),
+          stroke: lineColor,
+          strokeWidth: lineStroke,
+          curve: options.curve ?? "linear",
+        });
+        builders.push(wrapMark(mark, plot.topLeft, points.length));
+      } else {
+        // bar — bar extends one bin in pixel space along the binned axis,
+        // and from the value-axis baseline to the aggregated value on the
+        // other axis. The baseline is `scale(0)` when 0 is in the domain,
+        // else the scale's range floor (so log / off-zero axes don't draw
+        // from a clamped `scale(0)` pixel). See `baselinePixel`.
+        const pixelBinWidth = pixelsForBin(binnedScale, binSize);
+        const barThickness = Math.max(1, pixelBinWidth - 1);
+        const xZero = baselinePixel(scales.x, xScale as (v: number) => number);
+        const yZero = baselinePixel(scales.y, yScale as (v: number) => number);
+        const mark = barMark(points, {
+          x: (p) =>
+            binBy === "x" ? xScale(p.x) - pixelBinWidth / 2 : Math.min(xScale(p.x), xZero),
+          y: (p) =>
+            binBy === "x" ? Math.min(yScale(p.y), yZero) : yScale(p.y) - pixelBinWidth / 2,
+          width: (p) => (binBy === "x" ? barThickness : Math.abs(xScale(p.x) - xZero)),
+          height: (p) => (binBy === "x" ? Math.abs(yScale(p.y) - yZero) : barThickness),
+          fill: alphaize(fill, theme.marks.fillAlpha),
+          stroke,
+          strokeWidth,
+        });
+        builders.push(wrapMark(mark, plot.topLeft, points.length));
+      }
+      return builders;
+    },
+  };
+}
+
+function visibleDomain(
+  scale: import("../scales.ts").PositionScale | undefined,
+): readonly [number, number] | null {
+  if (!scale || scale.type === "band") return null;
+  const axis = scale.axisScale as { domain: readonly [number | Date, number | Date] };
+  const d = axis.domain;
+  if (!d) return null;
+  const lo = coerceNumeric(d[0]);
+  const hi = coerceNumeric(d[1]);
+  if (!Number.isFinite(lo) || !Number.isFinite(hi)) return null;
+  return [lo, hi];
+}
+
+/**
+ * Pixel coordinate of the bar baseline on a value axis.
+ *
+ * When `0` lies inside the scale's domain we project it directly — that's the
+ * correct, conventional baseline for a linear axis spanning zero (bars hang
+ * up *and* down from the zero line). When `0` is outside the domain (e.g. a log
+ * axis, whose domain never includes 0, or any axis panned off zero),
+ * `scale(0)` extrapolates to a clamped/garbage pixel, so bars would draw from
+ * the wrong place. In that case we fall back to the *range endpoint paired with
+ * the domain extreme nearest zero* — i.e. the visual floor of the bars.
+ *
+ * Reasoning about which range endpoint is the floor: a scale maps
+ * `domain[0] → range[0]` and `domain[1] → range[1]`. The bars' floor is the
+ * smallest-magnitude data value's pixel, which on a same-sign axis is whichever
+ * domain endpoint is nearest zero. We pick the range endpoint that pairs with
+ * it — this is orientation-agnostic and works for inverted ranges (the typical
+ * `y` range is `[height, 0]`) and for both `x` and `y` axes.
+ *
+ * Falls back to `scale(0)` if the axis can't be introspected (band scales, or
+ * scales missing domain/range).
+ */
+function baselinePixel(
+  scale: import("../scales.ts").PositionScale | undefined,
+  scaleFn: (value: number) => number,
+): number {
+  if (!scale || scale.type === "band") return scaleFn(0);
+  const axis = scale.axisScale as {
+    domain?: readonly [number | Date, number | Date];
+    range?: readonly [number, number];
+  };
+  const domain = axis.domain;
+  const range = axis.range;
+  if (!domain || !range) return scaleFn(0);
+  const d0 = coerceNumeric(domain[0]);
+  const d1 = coerceNumeric(domain[1]);
+  if (!Number.isFinite(d0) || !Number.isFinite(d1)) return scaleFn(0);
+  const lo = Math.min(d0, d1);
+  const hi = Math.max(d0, d1);
+  // 0 inside [lo, hi] → existing correct behavior.
+  if (lo <= 0 && 0 <= hi) return scaleFn(0);
+  // 0 outside the domain → use the range endpoint paired with the domain
+  // extreme nearest zero (the smallest-magnitude value = the bars' floor).
+  const nearestZeroIsD0 = Math.abs(d0) <= Math.abs(d1);
+  const px = nearestZeroIsD0 ? range[0] : range[1];
+  return Number.isFinite(px) ? px : scaleFn(0);
+}
+
+function pixelsForBin(
+  scale: import("../scales.ts").PositionScale | undefined,
+  binSize: number,
+): number {
+  if (!scale || scale.type === "band") return 0;
+  const axis = scale.axisScale as {
+    domain: readonly [number | Date, number | Date];
+    range: readonly [number, number];
+  };
+  const d0 = coerceNumeric(axis.domain[0]);
+  const d1 = coerceNumeric(axis.domain[1]);
+  const domainSpan = Math.abs(d1 - d0);
+  const pixelSpan = Math.abs(axis.range[1] - axis.range[0]);
+  if (!(domainSpan > 0) || !(pixelSpan > 0)) return 0;
+  return (binSize / domainSpan) * pixelSpan;
+}
+
+function buildRawMark<T>(
+  kind: AggregateInnerGeom,
+  rows: readonly T[],
+  channels: AggregateChannels<T>,
+  options: AggregateOptions<T>,
+  ctx: CompileContext<T>,
+): MarkBuilder {
+  const { scales, theme } = ctx;
+  const xAes = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+  const yAes = resolveAes<T, unknown>(channels.y as Aes<T, unknown>);
+  const xScale = scales.x.fn;
+  const yScale = scales.y.fn;
+  const fill = options.fill ?? defaultMarkFill(theme);
+
+  if (kind === "point") {
+    return pointMark(rows, {
+      x: (d, i) => xScale(xAes.fn(d, i)),
+      y: (d, i) => yScale(yAes.fn(d, i)),
+      radius: options.radius ?? theme.marks.pointRadius,
+      fill: alphaize(fill, theme.marks.fillAlpha),
+      stroke: options.stroke ?? theme.marks.pointStroke ?? undefined,
+      strokeWidth: options.strokeWidth ?? theme.marks.pointStrokeWidth,
+      shape: options.shape ?? "circle",
+    });
+  }
+  if (kind === "line") {
+    return lineMark(rows, {
+      x: (d, i) => xScale(xAes.fn(d, i)),
+      y: (d, i) => yScale(yAes.fn(d, i)),
+      stroke: options.stroke ?? options.fill ?? theme.palettes.categorical(0),
+      strokeWidth: options.strokeWidth ?? theme.marks.strokeWidth,
+      curve: options.curve ?? "linear",
+    });
+  }
+  // bar fallback: 1px tick at each row's position. Bar-as-raw isn't a common
+  // request (the dissolve case for bars usually means showing the source
+  // points), but we keep the path consistent. Baseline matches the aggregate
+  // path: `yScale(0)` when 0 is in the domain, else the y range floor (so log
+  // / off-zero axes don't draw from a clamped `yScale(0)` pixel).
+  const yBase = baselinePixel(scales.y, yScale as (v: number) => number);
+  return barMark(rows, {
+    x: (d, i) => xScale(xAes.fn(d, i)) - 0.5,
+    y: (d, i) => Math.min(yScale(yAes.fn(d, i)), yBase),
+    width: 1,
+    height: (d, i) => Math.abs(yScale(yAes.fn(d, i)) - yBase),
+    fill: alphaize(fill, theme.marks.fillAlpha),
+    stroke: options.stroke,
+    strokeWidth: options.strokeWidth,
+  });
+}