insomni-plot 0.1.0-alpha.0

package/src/grammar/pipeline.ts

@@ -0,0 +1,1233 @@
+// ---------------------------------------------------------------------------
+// Chart compile pipeline
+// ---------------------------------------------------------------------------
+// Pure function: takes a frozen ChartConfig + data + three target Layers and
+// emits axes, marks, title, and legend. Used by both the WebGPU mount loop
+// (mount.ts) and the static SVG export (svg.ts).
+
+import type { Color, Frame, GlyphAtlas, Layer, Padding } from "insomni";
+import { truncateToWidth, type AxisOptions } from "../axis.ts";
+import type { ContinuousPalette } from "../colors.ts";
+import { colorBar } from "../colorbar.ts";
+import { placeable, stack, type Placeable } from "../layout/box.ts";
+import { renderAnnotations, type AnnotationSpec } from "./annotations.ts";
+import {
+  computeFacetLayout,
+  groupForFacet,
+  renderFacetStrip,
+  type FacetPanel,
+  type FacetSpec,
+} from "./facet.ts";
+import {
+  legend as legendBuilder,
+  pointSwatch,
+  type LegendBuilder,
+  type PointSwatchSpec,
+  type SwatchSpec,
+} from "../legend.ts";
+import { resolveAes, type Aes, type ResolvedAes } from "./aes.ts";
+import type {
+  AxesSpec,
+  AxisSpec,
+  LegendInsidePosition,
+  LegendMergeChannel,
+  LegendSpec,
+  TitleSpec,
+} from "./chart.ts";
+import { frameBoundCoord, type Coord } from "./coord.ts";
+import type { GrammarTransitions } from "./interactions/transitions.ts";
+import { DEFAULT_CHART_HEIGHT, DEFAULT_CHART_WIDTH, LAYOUT_GAP } from "./constants.ts";
+import type { Geom, PositionScaleHint, RangeHints, ScaleBundle } from "./geoms/index.ts";
+import { geomEmphasisBase } from "./geoms/emphasis.ts";
+import { computeLayout, type SlotMap } from "./layout.ts";
+import { isSignal, type Signal } from "insomni/reactivity";
+import {
+  buildAlphaScale,
+  buildBorderStyleScale,
+  buildCategoricalColorScale,
+  buildColorScale,
+  buildOverlayGlyphScale,
+  buildPositionScale,
+  buildShapeScale,
+  buildSizeScale,
+  numericExtent,
+  type AlphaScaleOptions,
+  type BorderStyleScaleOptions,
+  type ColorScaleOptions,
+  type NumericPositionScaleOptions,
+  type OverlayGlyphScaleOptions,
+  type PositionScaleOptions,
+  type ShapeScaleOptions,
+  type SizeScaleOptions,
+} from "./scales.ts";
+import { type Theme } from "./theme.ts";
+import { resolveTextColor } from "./accessibility.ts";
+import { arraysEqual } from "./equality.ts";
+
+export interface ChartConfig<T> {
+  data: readonly T[] | Signal<readonly T[]>;
+  width: number | undefined;
+  height: number | undefined;
+  background: Color | undefined;
+  padding: Padding;
+  framePadding: { top: number; right: number; bottom: number; left: number };
+  device: GPUDevice | undefined;
+  externalAtlas: GlyphAtlas | undefined;
+  theme: Theme;
+  layers: readonly Geom<T>[];
+  axes: AxesSpec;
+  titles: TitleSpec;
+  legend: LegendSpec;
+  scaleOverrides: {
+    x?: PositionScaleOptions;
+    y?: PositionScaleOptions;
+    color?: ColorScaleOptions<unknown>;
+    size?: SizeScaleOptions;
+    alpha?: AlphaScaleOptions;
+    shape?: ShapeScaleOptions;
+    borderStyle?: BorderStyleScaleOptions;
+    overlayGlyph?: OverlayGlyphScaleOptions;
+  };
+  annotations: readonly AnnotationSpec[];
+  facet?: FacetSpec<T>;
+  /**
+   * Coordinate system. Defaults to `coordCartesian()`. Threaded into
+   * `CompileContext.coord` and used to dispatch axis rendering.
+   */
+  coord: Coord;
+}
+
+export interface PipelineOutput<T = unknown> {
+  scales: ScaleBundle;
+  /** Hit-test contributions from any geom that implements `compileHitTest`. */
+  hitTests: import("./geoms/types.ts").CompiledHitTest<T>[];
+  /**
+   * Hover-focus decorators from geoms that implement `hoverDecoration` (point).
+   * The mount draws these into the overlay layer on hover — a cheap path that
+   * avoids recompiling the baked marks. Empty for geoms whose hover treatment
+   * is global (dim-others), which the mount handles via a marks re-bake.
+   * Faceted charts collect one decorator per (panel, geom), each closing over
+   * its panel's rows (P6-T3).
+   */
+  hoverDecorators: import("./geoms/types.ts").GeomHoverDecorator[];
+  /**
+   * Emphasis-key resolvers from dim-participating geoms (P5-T3). The mount maps
+   * an active hover hit to the geom's namespaced focused key and drives the
+   * core's animated GPU dim. Empty for charts with no dim geom. Faceted charts
+   * collect one resolver per (panel, geom) with a disjoint per-panel key band
+   * (P6-T3), so hovering one panel never dims another.
+   */
+  emphasisResolvers: import("./geoms/emphasis.ts").EmphasisResolver[];
+  /**
+   * Inset chart frame after outer padding — the area available to axes, slots,
+   * and the plot panel. Used to clip the hud layer so overlay marks (e.g. tip
+   * labels) don't bleed into the outer padding region.
+   */
+  outerFrame: Frame;
+  /**
+   * Plot drawing region in absolute element-CSS pixels (top-left of the plot
+   * frame, matching `Frame.topLeft`). For faceted charts this is the union
+   * of all panel frames — wide enough to enclose every panel — used by the
+   * crosshair to clip its guide line to the marks region.
+   */
+  plotFrame: Frame;
+  /**
+   * Position-scale range insets in CSS px (`framePadding` + per-geom
+   * `prepareRange` reservations). The position scales' pixel range is
+   * `[reserve.left, plotFrame.width - reserve.right]` (X) and
+   * `[plotFrame.height - reserve.bottom, reserve.top]` (Y). The mount feeds
+   * this into the data viewport via `setFrame(plotFrame, reserve)` so
+   * `dataToScreen` matches where marks render.
+   */
+  reserve: {
+    readonly left: number;
+    readonly right: number;
+    readonly top: number;
+    readonly bottom: number;
+  };
+  /**
+   * Per-panel plot frames for faceted charts (one entry per panel, in render
+   * order). Empty / undefined for non-faceted charts. Used by the crosshair
+   * to clip its guide line to the active panel rather than the chart-wide
+   * union frame. Coordinates match `plotFrame` (absolute element-CSS px).
+   */
+  panelFrames?: readonly Frame[];
+  /** Categorical legend builder and its placed origin (absolute CSS px). */
+  legend?: {
+    builder: import("../legend.ts").LegendBuilder;
+    origin: { x: number; y: number };
+  };
+}
+
+export function currentData<T>(data: readonly T[] | Signal<readonly T[]>): readonly T[] {
+  return isSignal<readonly T[]>(data) ? data.get() : data;
+}
+
+/**
+ * Optional tail bundle for {@link runPipeline}. Required core args
+ * (`config`, `data`, layers, `atlas`) stay positional; everything that varies
+ * per-frame lives here so call sites don't drift when fields are added.
+ */
+export interface RunPipelineOptions<T> {
+  hovered?: import("./geoms/types.ts").HoveredHit | null;
+  selected?: readonly import("./geoms/types.ts").HoveredHit[];
+  hidden?: ReadonlySet<string>;
+  legendDimAlpha?: number;
+  transitions?: GrammarTransitions;
+  transitionKey?: (datum: T, index: number) => string;
+}
+
+export function runPipeline<T>(
+  config: ChartConfig<T>,
+  data: readonly T[],
+  axisLayer: Layer,
+  marksLayer: Layer,
+  hudLayer: Layer,
+  atlas: GlyphAtlas | undefined,
+  options: RunPipelineOptions<T> = {},
+): PipelineOutput<T> {
+  const { hovered = null, selected, hidden, legendDimAlpha, transitions, transitionKey } = options;
+  const { theme, axes, titles, legend, layers } = config;
+  axisLayer.clear();
+  marksLayer.clear();
+  hudLayer.clear();
+
+  // ---- 1. Resolve channel aesthetics across all layers ------------------
+  // We need samples for axis pre-measurement and union domains for scales.
+  type ChannelData = { aes: ResolvedAes<T, unknown>; values: unknown[] };
+  const xColumns: ChannelData[] = [];
+  const yColumns: ChannelData[] = [];
+  const colorColumns: ChannelData[] = [];
+  const sizeColumns: ChannelData[] = [];
+  const alphaColumns: ChannelData[] = [];
+  const shapeColumns: ChannelData[] = [];
+  const borderStyleColumns: ChannelData[] = [];
+  const overlayGlyphColumns: ChannelData[] = [];
+  const colorLayers: { aes: ResolvedAes<T, unknown>; geom: Geom<T> }[] = [];
+  let xHint: PositionScaleHint | undefined;
+  let yHint: PositionScaleHint | undefined;
+  // When a geom declares array-shaped x or y (multi-series, e.g. stacked bar),
+  // the keys themselves are the color domain — used to drive the auto-legend
+  // and the geom's series fills.
+  let implicitSeries: { keys: readonly string[]; geom: Geom<T> } | undefined;
+
+  // Resolve the position channel for one axis. Single-key columns become a
+  // regular accessor; array-of-keys columns sum across the named columns
+  // (stacked layout) and seed `implicitSeries` for the auto-legend.
+  function extractPositionColumn(
+    raw: unknown,
+    geom: Geom<T>,
+    hasExplicitColor: boolean,
+  ): ChannelData {
+    if (Array.isArray(raw)) {
+      const keys = raw as readonly string[];
+      const totals = rowSums(data, keys);
+      const aes: ResolvedAes<T, unknown> = {
+        kind: "accessor",
+        fn: ((_d: T, i: number) => totals[i]) as (d: T, i: number) => unknown,
+      };
+      // Multi-series array x/y has an implicit color domain = keys so the
+      // auto-legend can label the series. Skip if the user wired their own
+      // explicit color channel.
+      if (!hasExplicitColor && !implicitSeries) {
+        implicitSeries = { keys: [...keys], geom };
+      }
+      return { aes, values: totals };
+    }
+    const aes = resolveAes<T, unknown>(raw as Aes<T, unknown>);
+    return { aes, values: data.map((d, i) => aes.fn(d, i)) };
+  }
+
+  for (const geom of layers) {
+    const c = geom.channels;
+    const hints = geom.scaleHints;
+    if (hints?.x) xHint = mergeHint(xHint, hints.x);
+    if (hints?.y) yHint = mergeHint(yHint, hints.y);
+    const prepared = geom.prepareDomain?.(data);
+    if (prepared?.x) xHint = mergeHint(xHint, prepared.x);
+    if (prepared?.y) yHint = mergeHint(yHint, prepared.y);
+    const hasExplicitColor = c.color !== undefined;
+    if (c.x !== undefined) {
+      xColumns.push(extractPositionColumn(c.x, geom, hasExplicitColor));
+    }
+    if (c.y !== undefined) {
+      yColumns.push(extractPositionColumn(c.y, geom, hasExplicitColor));
+    }
+    if (c.color !== undefined) {
+      const aes = resolveAes<T, unknown>(c.color as Aes<T, unknown>);
+      colorColumns.push({ aes, values: data.map((d, i) => aes.fn(d, i)) });
+      colorLayers.push({ aes, geom });
+    }
+    if (c.size !== undefined) {
+      const aes = resolveAes<T, number>(c.size as Aes<T, number>);
+      sizeColumns.push({
+        aes: aes as ResolvedAes<T, unknown>,
+        values: data.map((d, i) => aes.fn(d, i)),
+      });
+    }
+    if (c.alpha !== undefined) {
+      const aes = resolveAes<T, number>(c.alpha as Aes<T, number>);
+      alphaColumns.push({
+        aes: aes as ResolvedAes<T, unknown>,
+        values: data.map((d, i) => aes.fn(d, i)),
+      });
+    }
+    if (c.shape !== undefined) {
+      const aes = resolveAes<T, unknown>(c.shape as Aes<T, unknown>);
+      shapeColumns.push({ aes, values: data.map((d, i) => aes.fn(d, i)) });
+    }
+    if (c.borderStyle !== undefined) {
+      const aes = resolveAes<T, unknown>(c.borderStyle as Aes<T, unknown>);
+      borderStyleColumns.push({ aes, values: data.map((d, i) => aes.fn(d, i)) });
+    }
+    if (c.overlayGlyph !== undefined) {
+      const aes = resolveAes<T, unknown>(c.overlayGlyph as Aes<T, unknown>);
+      overlayGlyphColumns.push({ aes, values: data.map((d, i) => aes.fn(d, i)) });
+    }
+  }
+
+  const xSample = (xColumns[0]?.values ?? []) as readonly (number | string | Date)[];
+  const ySample = (yColumns[0]?.values ?? []) as readonly (number | string | Date)[];
+
+  // ---- 2. Build non-position scales (pre-layout) ------------------------
+  // Color/size/alpha/shape scales don't depend on plot pixels — only x/y do.
+  // Building them now lets us construct the *real* legend Placeable and
+  // measure it for the layout slot, instead of guessing pixel reservations.
+  function buildNonPositionScales() {
+    const colorScale = colorColumns[0]
+      ? buildColorScale(colorColumns[0].aes, data, theme, config.scaleOverrides.color)
+      : implicitSeries
+        ? buildCategoricalColorScale(implicitSeries.keys, theme, config.scaleOverrides.color)
+        : undefined;
+    const sizeScale = sizeColumns[0]
+      ? buildSizeScale(
+          sizeColumns[0].aes as ResolvedAes<T, number>,
+          data,
+          config.scaleOverrides.size,
+        )
+      : undefined;
+    const alphaScale = alphaColumns[0]
+      ? buildAlphaScale(
+          alphaColumns[0].aes as ResolvedAes<T, number>,
+          data,
+          config.scaleOverrides.alpha,
+        )
+      : undefined;
+    const shapeScale = shapeColumns[0]
+      ? buildShapeScale(shapeColumns[0].aes, data, config.scaleOverrides.shape)
+      : undefined;
+    const borderStyleScale = borderStyleColumns[0]
+      ? buildBorderStyleScale(borderStyleColumns[0].aes, data, config.scaleOverrides.borderStyle)
+      : undefined;
+    const overlayGlyphScale = overlayGlyphColumns[0]
+      ? buildOverlayGlyphScale(overlayGlyphColumns[0].aes, data, config.scaleOverrides.overlayGlyph)
+      : undefined;
+    return { colorScale, sizeScale, alphaScale, shapeScale, borderStyleScale, overlayGlyphScale };
+  }
+  const { colorScale, sizeScale, alphaScale, shapeScale, borderStyleScale, overlayGlyphScale } =
+    buildNonPositionScales();
+
+  // ---- 3. Build legend + title Placeables; compute slot reservations ----
+  const xAxisOptions = makeAxisOptions(axes.x, theme, atlas);
+  const yAxisOptions = makeAxisOptions(axes.y, theme, atlas);
+
+  const titleResolved = resolveTitleEntry(titles.title);
+  const subtitleResolved = resolveTitleEntry(titles.subtitle);
+  const titleBlock =
+    atlas && (titleResolved || subtitleResolved)
+      ? buildTitleBlock(atlas, theme, titleResolved, subtitleResolved)
+      : undefined;
+
+  const hasLegend = colorLayers.length > 0 || implicitSeries !== undefined;
+  const isContinuousLegend =
+    colorScale !== undefined &&
+    (colorScale.type === "continuous" || colorScale.type === "diverging");
+  const showLegend =
+    atlas !== undefined && legend.show !== false && hasLegend && colorScale !== undefined;
+
+  const inside = isInsidePosition(legend.position) ? legend.position : undefined;
+  const outerLegendPosition: "top" | "right" | "bottom" | "left" | undefined = inside
+    ? undefined
+    : ((legend.position as "top" | "right" | "bottom" | "left" | undefined) ??
+      (isContinuousLegend ? "right" : "top"));
+
+  const colorBarLength = legend.length ?? 160;
+  const colorBarThickness = legend.thickness ?? 12;
+
+  const legendBuilt: LegendBuilder | undefined = showLegend
+    ? buildLegend({
+        atlas: atlas!,
+        theme,
+        colorScale,
+        colorLayers,
+        implicitSeries,
+        legendSpec: legend,
+        orientation:
+          outerLegendPosition === "right" || outerLegendPosition === "left"
+            ? "vertical"
+            : "horizontal",
+        colorBarLength,
+        colorBarThickness,
+        hidden,
+        dimAlpha: legendDimAlpha,
+        scales: {
+          color: colorScale,
+          size: sizeScale,
+          alpha: alphaScale,
+          shape: shapeScale,
+          borderStyle: borderStyleScale,
+          overlayGlyph: overlayGlyphScale,
+        },
+      })
+    : undefined;
+
+  // Slot reservations: top slot may stack title + legend (when legend on top);
+  // side legends consume right/left slot; bottom legend consumes bottom slot.
+  // Inside-plot legends consume no slot.
+  const titleSize = titleBlock?.measure();
+  const legendSize = legendBuilt?.measure();
+
+  const slots: SlotMap = {};
+  if (outerLegendPosition === "top" && legendSize) {
+    const totalH =
+      (titleSize?.height ?? 0) + (titleSize ? LAYOUT_GAP.titleToLegend : 0) + legendSize.height;
+    const totalW = Math.max(titleSize?.width ?? 0, legendSize.width);
+    slots.top = { width: totalW, height: totalH };
+  } else if (titleSize) {
+    slots.top = { width: titleSize.width, height: titleSize.height };
+  }
+  if (outerLegendPosition === "right" && legendSize) {
+    slots.right = { width: legendSize.width, height: legendSize.height };
+  }
+  if (outerLegendPosition === "bottom" && legendSize) {
+    slots.bottom = { width: legendSize.width, height: legendSize.height };
+  }
+  if (outerLegendPosition === "left" && legendSize) {
+    slots.left = { width: legendSize.width, height: legendSize.height };
+  }
+
+  const layout = computeLayout({
+    width: config.width ?? DEFAULT_CHART_WIDTH,
+    height: config.height ?? DEFAULT_CHART_HEIGHT,
+    padding: config.padding,
+    theme,
+    atlas,
+    xSample,
+    ySample,
+    xAxisOptions: xAxisOptions as AxisOptions<unknown>,
+    yAxisOptions: yAxisOptions as AxisOptions<unknown>,
+    slots,
+  });
+
+  const plotFrame = layout.plot;
+
+  // ---- 2b. Collect range reservations (post-layout) --------------------
+  // Geoms whose visual extent overshoots their data footprint — ridgeline
+  // rows that rise into the row above — request pixel reservations here so
+  // the band/numeric scale built next sits inside a shrunken range and the
+  // axis ticks follow.
+  let rangeHints: RangeHints = {};
+  for (const geom of layers) {
+    const r = geom.prepareRange?.({
+      data,
+      plot: plotFrame,
+      scaleOptions: { x: config.scaleOverrides.x, y: config.scaleOverrides.y },
+      theme,
+      atlas,
+    });
+    if (r) rangeHints = mergeRangeHints(rangeHints, r);
+  }
+  const fp = config.framePadding;
+  const reserveLeft = (rangeHints.left ?? 0) + fp.left;
+  const reserveRight = (rangeHints.right ?? 0) + fp.right;
+  const reserveTop = (rangeHints.top ?? 0) + fp.top;
+  const reserveBottom = (rangeHints.bottom ?? 0) + fp.bottom;
+  const xRange: [number, number] = [reserveLeft, plotFrame.width - reserveRight];
+  const yRange: [number, number] = [plotFrame.height - reserveBottom, reserveTop];
+
+  // ---- 4. Build position scales (need plot pixels) ---------------------
+  const xScale = xColumns[0]
+    ? buildPositionScale(
+        xColumns[0].aes,
+        data,
+        xRange,
+        applyHint(xColumns[0].values, config.scaleOverrides.x, xHint),
+      )
+    : buildPositionScale(
+        resolveAes<T, unknown>(((_d: T, i: number) => i) as Aes<T, unknown>),
+        data,
+        xRange,
+      );
+  const yScale = yColumns[0]
+    ? buildPositionScale(
+        yColumns[0].aes,
+        data,
+        yRange,
+        applyHint(yColumns[0].values, config.scaleOverrides.y, yHint),
+      )
+    : buildPositionScale(
+        resolveAes<T, unknown>(((_d: T, i: number) => i) as Aes<T, unknown>),
+        data,
+        yRange,
+      );
+
+  const scales: ScaleBundle = {
+    x: xScale,
+    y: yScale,
+    color: colorScale,
+    size: sizeScale,
+    alpha: alphaScale,
+    shape: shapeScale,
+    borderStyle: borderStyleScale,
+    overlayGlyph: overlayGlyphScale,
+  };
+
+  // ---- 4. Render axes + marks ------------------------------------------
+  const hitTests: import("./geoms/types.ts").CompiledHitTest<T>[] = [];
+  const hoverDecorators: import("./geoms/types.ts").GeomHoverDecorator[] = [];
+  const emphasisResolvers: import("./geoms/emphasis.ts").EmphasisResolver[] = [];
+  const panelFrames: Frame[] = [];
+  if (config.facet) {
+    renderFacets({
+      facet: config.facet,
+      data,
+      layers,
+      plotFrame,
+      sharedScales: scales,
+      theme,
+      atlas,
+      coord: config.coord,
+      xColumns,
+      yColumns,
+      xAxisOptions: xAxisOptions as AxisOptions<unknown>,
+      yAxisOptions: yAxisOptions as AxisOptions<unknown>,
+      axisLayer,
+      marksLayer,
+      hudLayer,
+      reserve: { left: reserveLeft, right: reserveRight, top: reserveTop, bottom: reserveBottom },
+      hitTests,
+      hoverDecorators,
+      emphasisResolvers,
+      hovered,
+      selected,
+      hidden,
+      transitions,
+      transitionKey,
+      panelFrames,
+    });
+  } else {
+    renderSinglePanel();
+  }
+
+  function renderSinglePanel() {
+    // Stateful coords (polar) need the plot frame before any `project` or
+    // axis call. Cartesian's bindFrame is a no-op.
+    config.coord.bindFrame(plotFrame);
+    config.coord.renderAxes({
+      axisLayer,
+      scales,
+      plotFrame,
+      hasX: xColumns[0] !== undefined,
+      hasY: yColumns[0] !== undefined,
+      xAxisOptions: xAxisOptions as AxisOptions<unknown>,
+      yAxisOptions: yAxisOptions as AxisOptions<unknown>,
+      atlas,
+    });
+
+    for (let gi = 0; gi < layers.length; gi++) {
+      const geom = layers[gi]!;
+      const activeTransition = transitions?.contextFor(gi);
+      const ctx = {
+        data,
+        scales,
+        plot: plotFrame,
+        theme,
+        atlas,
+        coord: config.coord,
+        hovered,
+        selected,
+        hidden,
+        transitionKey,
+        activeTransition,
+        // Disjoint per-geom emphasis-key band (P5-T3) for GPU hover dim.
+        emphasisBase: geomEmphasisBase(gi),
+      };
+      const builders = geom.compile(ctx);
+      const target = geom.overlay ? hudLayer : marksLayer;
+      for (const b of builders) b.addTo(target);
+      // Capture frame for transitions (always; storeFrame decides when to update stable store).
+      if (transitions && geom.captureFrame) {
+        const frame = geom.captureFrame(ctx);
+        if (frame) transitions.storeFrame(gi, frame);
+      }
+      const hits = geom.compileHitTest?.(ctx);
+      if (hits) hitTests.push(hits);
+      const deco = geom.hoverDecoration?.(ctx);
+      if (deco) hoverDecorators.push(deco);
+      const emphRes = geom.emphasisResolution?.(ctx);
+      if (emphRes) emphasisResolvers.push(emphRes);
+    }
+  }
+
+  // ---- 6. Title + legend -----------------------------------------------
+  // Title block draws at the top slot's left edge. When the legend is also
+  // top-positioned, it draws right-aligned below the title within the same
+  // slot — preserving the historical "title left + legend right" layout.
+  if (titleBlock) {
+    const topAnchor = layout.slots.top ?? { x: layout.outer.x, y: layout.outer.y };
+    titleBlock.addTo(hudLayer, { x: topAnchor.x, y: topAnchor.y });
+  }
+  let legendOriginX: number | undefined;
+  let legendOriginY: number | undefined;
+
+  if (legendBuilt && legendSize) {
+    const { originX, originY } = placeLegend(legendSize);
+    legendOriginX = originX;
+    legendOriginY = originY;
+    legendBuilt.addTo(hudLayer, { x: originX, y: originY });
+  }
+
+  function placeLegend(m: { width: number; height: number }): {
+    originX: number;
+    originY: number;
+  } {
+    if (inside) {
+      // Inside-plot: x/y are normalized 0..1 in plot frame; justify chooses
+      // which corner of the legend bbox lands on that point.
+      const jx = inside.justify?.x ?? "start";
+      const jy = inside.justify?.y ?? "start";
+      const px = plotFrame.x + plotFrame.width * inside.inside.x;
+      const py = plotFrame.y + plotFrame.height * inside.inside.y;
+      return {
+        originX: px - (jx === "end" ? m.width : jx === "center" ? m.width / 2 : 0),
+        originY: py - (jy === "end" ? m.height : jy === "center" ? m.height / 2 : 0),
+      };
+    }
+    if (outerLegendPosition === "top") {
+      const top = layout.slots.top!;
+      // Right-aligned within top slot. Title lives at top-left; legend at
+      // top-right, vertically offset by titleHeight + gap if title present.
+      const yOffset = titleSize !== undefined ? titleSize.height + LAYOUT_GAP.titleToLegend : 0;
+      return { originX: top.x + top.width - m.width, originY: top.y + yOffset };
+    }
+    if (outerLegendPosition === "right") {
+      const r = layout.slots.right!;
+      return { originX: r.x, originY: r.y + Math.max(0, (plotFrame.height - m.height) / 2) };
+    }
+    if (outerLegendPosition === "left") {
+      const l = layout.slots.left!;
+      return { originX: l.x, originY: l.y + Math.max(0, (plotFrame.height - m.height) / 2) };
+    }
+    const b = layout.slots.bottom!;
+    return { originX: b.x + b.width / 2 - m.width / 2, originY: b.y };
+  }
+
+  // ---- 7. Free-form annotations ----------------------------------------
+  if (config.annotations.length > 0) {
+    renderAnnotations(config.annotations, scales, plotFrame, theme, hudLayer);
+  }
+
+  return {
+    scales,
+    hitTests,
+    hoverDecorators,
+    emphasisResolvers,
+    outerFrame: layout.outer,
+    plotFrame,
+    reserve: { left: reserveLeft, right: reserveRight, top: reserveTop, bottom: reserveBottom },
+    panelFrames: panelFrames.length > 0 ? panelFrames : undefined,
+    legend:
+      legendBuilt && legendOriginX !== undefined && legendOriginY !== undefined
+        ? {
+            builder: legendBuilt,
+            origin: { x: legendOriginX, y: legendOriginY },
+          }
+        : undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+interface FacetRenderArgs<T> {
+  facet: FacetSpec<T>;
+  data: readonly T[];
+  layers: readonly Geom<T>[];
+  plotFrame: import("insomni").Frame;
+  sharedScales: ScaleBundle;
+  theme: Theme;
+  atlas: GlyphAtlas | undefined;
+  coord: Coord;
+  xColumns: { aes: ResolvedAes<T, unknown>; values: unknown[] }[];
+  yColumns: { aes: ResolvedAes<T, unknown>; values: unknown[] }[];
+  xAxisOptions: AxisOptions<unknown>;
+  yAxisOptions: AxisOptions<unknown>;
+  axisLayer: Layer;
+  marksLayer: Layer;
+  hudLayer: Layer;
+  reserve: { left: number; right: number; top: number; bottom: number };
+  hitTests: import("./geoms/types.ts").CompiledHitTest<T>[];
+  hoverDecorators: import("./geoms/types.ts").GeomHoverDecorator[];
+  emphasisResolvers: import("./geoms/emphasis.ts").EmphasisResolver[];
+  hovered: import("./geoms/types.ts").HoveredHit | null;
+  selected: readonly import("./geoms/types.ts").HoveredHit[] | undefined;
+  hidden: ReadonlySet<string> | undefined;
+  transitions: GrammarTransitions | undefined;
+  transitionKey: ((datum: T, index: number) => string) | undefined;
+  panelFrames: Frame[];
+}
+
+/**
+ * Faceted render — one panel per group key. With `scales: "fixed"` (default)
+ * each panel reuses the chart-wide x/y domain but maps it onto the panel's
+ * local pixel range, so axes line up across panels. With `scales: "free"`
+ * each panel computes its own domain from its rows.
+ */
+function renderFacets<T>(args: FacetRenderArgs<T>): void {
+  const groups = groupForFacet(args.facet, args.data);
+  if (groups.length === 0) return;
+  const layout = computeFacetLayout(args.facet, groups, args.plotFrame);
+  const scaleMode = args.facet.scales ?? "fixed";
+
+  // Emphasis-key namespacing across panels (P6-T3). Keys are global per frame
+  // (one emphasis uniform), so every (panel, geom) pair needs a DISJOINT band or
+  // hovering panel A would dim panel B's same-index geom. We flatten the 2-D
+  // (panelIndex, gi) coordinate into a single effective geom index
+  // `panelIndex * geomCount + gi` and feed it through the same `geomEmphasisBase`
+  // band formula the non-faceted path uses — no new constants, no per-panel
+  // stride. With `geomCount` panels × geoms this can reach the existing
+  // `EMPHASIS_MAX_GEOM_INDEX` ceiling, which `geomEmphasisBase` already guards.
+  const geomCount = args.layers.length;
+
+  for (let panelIndex = 0; panelIndex < layout.panels.length; panelIndex++) {
+    const panel = layout.panels[panelIndex]!;
+    args.panelFrames.push(panel.frame);
+    renderFacetStrip(
+      args.hudLayer,
+      panel as FacetPanel<unknown>,
+      args.facet as FacetSpec<unknown>,
+      args.theme,
+    );
+
+    const panelData = panel.rows;
+    const panelXRange: [number, number] = [
+      args.reserve.left,
+      panel.frame.width - args.reserve.right,
+    ];
+    const panelYRange: [number, number] = [
+      panel.frame.height - args.reserve.bottom,
+      args.reserve.top,
+    ];
+
+    let panelX = args.sharedScales.x;
+    let panelY = args.sharedScales.y;
+    if (args.xColumns[0]) {
+      // "fixed": pin the inferred domain to the chart-wide one. "free": let
+      // each panel compute its own domain from its rows.
+      panelX = buildPositionScale(
+        args.xColumns[0].aes,
+        scaleMode === "fixed" ? args.data : (panelData as readonly T[]),
+        panelXRange,
+        scaleMode === "fixed" ? shareDomain(panelX) : undefined,
+      );
+    }
+    if (args.yColumns[0]) {
+      panelY = buildPositionScale(
+        args.yColumns[0].aes,
+        scaleMode === "fixed" ? args.data : (panelData as readonly T[]),
+        panelYRange,
+        scaleMode === "fixed" ? shareDomain(panelY) : undefined,
+      );
+    }
+
+    const panelScales: ScaleBundle = {
+      ...args.sharedScales,
+      x: panelX,
+      y: panelY,
+    };
+
+    // Per-panel coord pinned to this panel's frame. The geoms' deferred
+    // `hoverDecoration` closures capture `ctx.coord` and run at hover time —
+    // long after the loop has advanced — so they MUST see a panel-stable frame,
+    // not the shared coord left bound to the last panel. `frameBoundCoord`
+    // re-binds the underlying coord to `panel.frame` on every frame-dependent
+    // call (Cartesian no-ops). Synchronous compile/axes use the same instance.
+    const panelCoord = frameBoundCoord(args.coord, panel.frame);
+    panelCoord.renderAxes({
+      axisLayer: args.axisLayer,
+      scales: panelScales,
+      plotFrame: panel.frame,
+      hasX: args.xColumns[0] !== undefined && panel.isBottomRow,
+      hasY: args.yColumns[0] !== undefined && panel.isLeftCol,
+      xAxisOptions: args.xAxisOptions,
+      yAxisOptions: args.yAxisOptions,
+      atlas: args.atlas,
+    });
+
+    for (let gi = 0; gi < args.layers.length; gi++) {
+      const geom = args.layers[gi]!;
+      const activeTransition = args.transitions?.contextFor(gi, panel.key);
+      // Flatten (panel, geom) → one effective index so each panel's geom gets a
+      // private emphasis band. The resolver/decorator we collect below close over
+      // this panel's `data` (panel.rows), and faceted hits carry that same sliced
+      // array (CompiledHitTest.data = ctx.data), so the mount's `r.data === hit.data`
+      // match stays correct per panel.
+      const effectiveGi = panelIndex * geomCount + gi;
+      const ctx = {
+        data: panelData,
+        scales: panelScales,
+        plot: panel.frame,
+        theme: args.theme,
+        atlas: args.atlas,
+        coord: panelCoord,
+        hovered: args.hovered,
+        selected: args.selected,
+        hidden: args.hidden,
+        transitionKey: args.transitionKey,
+        activeTransition,
+        emphasisBase: geomEmphasisBase(effectiveGi),
+      };
+      const builders = geom.compile(ctx);
+      const target = geom.overlay ? args.hudLayer : args.marksLayer;
+      for (const b of builders) b.addTo(target);
+      if (args.transitions && geom.captureFrame) {
+        const frame = geom.captureFrame(ctx);
+        if (frame) args.transitions.storeFrame(gi, frame, panel.key);
+      }
+      const hits = geom.compileHitTest?.(ctx);
+      if (hits) args.hitTests.push(hits);
+      const deco = geom.hoverDecoration?.(ctx);
+      if (deco) args.hoverDecorators.push(deco);
+      const emphRes = geom.emphasisResolution?.(ctx);
+      if (emphRes) args.emphasisResolvers.push(emphRes);
+    }
+  }
+}
+
+/**
+ * Extract the existing scale's domain into a `PositionScaleOptions` that pins
+ * a new scale to the same input range — used to keep faceted panels aligned
+ * under `scales: "fixed"`.
+ *
+ * Exported for unit testing — not part of the public grammar surface.
+ */
+export function shareDomain(scale: ScaleBundle["x"]): PositionScaleOptions {
+  const dom = (scale.axisScale as { domain: readonly unknown[] }).domain;
+  if (scale.type === "band") {
+    return { type: "band", domain: dom as readonly string[] };
+  }
+  if (scale.type === "time") {
+    return { type: "time", domain: dom as readonly [Date, Date] };
+  }
+  if (scale.type === "log") {
+    return { type: "log", domain: dom as readonly [number, number] };
+  }
+  return {
+    type: scale.type === "sqrt" ? "sqrt" : "linear",
+    domain: dom as readonly [number, number],
+  };
+}
+
+function rowSums<T>(data: readonly T[], keys: readonly string[]): number[] {
+  const out = Array.from<number>({ length: data.length });
+  for (let i = 0; i < data.length; i++) {
+    const d = data[i] as Record<string, number>;
+    let s = 0;
+    for (const k of keys) s += d[k] ?? 0;
+    out[i] = s;
+  }
+  return out;
+}
+
+function mergeRangeHints(a: RangeHints, b: RangeHints): RangeHints {
+  return {
+    top: Math.max(a.top ?? 0, b.top ?? 0) || undefined,
+    bottom: Math.max(a.bottom ?? 0, b.bottom ?? 0) || undefined,
+    left: Math.max(a.left ?? 0, b.left ?? 0) || undefined,
+    right: Math.max(a.right ?? 0, b.right ?? 0) || undefined,
+  };
+}
+
+function mergeHint(a: PositionScaleHint | undefined, b: PositionScaleHint): PositionScaleHint {
+  if (!a) return b;
+  let extend: readonly [number, number] | undefined;
+  if (a.extend && b.extend) {
+    extend = [Math.min(a.extend[0], b.extend[0]), Math.max(a.extend[1], b.extend[1])];
+  } else {
+    extend = a.extend ?? b.extend;
+  }
+  return {
+    domain: a.domain ?? b.domain,
+    includeZero: a.includeZero || b.includeZero,
+    includeOne: a.includeOne || b.includeOne,
+    extend,
+  };
+}
+
+function applyHint(
+  values: readonly unknown[],
+  override: PositionScaleOptions | undefined,
+  hint: PositionScaleHint | undefined,
+): PositionScaleOptions | undefined {
+  if (!hint) return override;
+  if (override?.domain !== undefined) return override;
+  if (override?.type === "band" || override?.type === "time") return override;
+
+  if (hint.domain) {
+    // The `type === "time" | "band"` early-returns above leave only numeric
+    // scales here, so the hint's numeric domain is valid for the result.
+    return { ...override, domain: [hint.domain[0], hint.domain[1]] } as NumericPositionScaleOptions;
+  }
+  if (!hint.includeZero && !hint.includeOne && !hint.extend) return override;
+
+  let [lo, hi] = numericExtent(values);
+  // numericExtent returns [0, 1] for non-numeric input — preserve the original
+  // override in that case rather than fabricating a domain from nothing.
+  if (!values.some((v) => typeof v === "number" && Number.isFinite(v))) {
+    return override;
+  }
+  if (hint.includeZero) {
+    if (0 < lo) lo = 0;
+    if (0 > hi) hi = 0;
+  }
+  if (hint.includeOne) {
+    if (1 < lo) lo = 1;
+    if (1 > hi) hi = 1;
+  }
+  if (hint.extend) {
+    if (hint.extend[0] < lo) lo = hint.extend[0];
+    if (hint.extend[1] > hi) hi = hint.extend[1];
+  }
+  if (lo === hi) hi = lo + 1;
+  return { ...override, domain: [lo, hi] } as NumericPositionScaleOptions;
+}
+
+function resolveTitleEntry(
+  entry: string | { text: string; maxWidth?: number } | undefined,
+): { text: string; maxWidth: number | undefined } | null {
+  if (!entry) return null;
+  if (typeof entry === "string") {
+    return entry.length > 0 ? { text: entry, maxWidth: undefined } : null;
+  }
+  return entry.text.length > 0 ? { text: entry.text, maxWidth: entry.maxWidth } : null;
+}
+
+/**
+ * Recover the original `ContinuousPalette` from a built color scale. We don't
+ * stash it on the scale object today, so reconstruct from the override or the
+ * theme. Diverging scales fall back to the theme's diverging palette.
+ */
+function continuousPaletteFromScale(scale: { type: string }, theme: Theme): ContinuousPalette {
+  const base = scale.type === "diverging" ? theme.palettes.diverging : theme.palettes.continuous;
+  return base.blendSpace === theme.paletteBlendSpace
+    ? base
+    : base.withBlendSpace(theme.paletteBlendSpace);
+}
+
+/** @internal Exported for unit tests only. */
+export function makeAxisOptions(
+  spec: AxisSpec | undefined,
+  theme: Theme,
+  atlas: GlyphAtlas | undefined,
+): AxisOptions<unknown> {
+  const labelColor = resolveTextColor(theme.axis.labelColor, theme.background, theme, {
+    fontSizePx: theme.axis.labelFontSize,
+    site: "axis-label",
+  });
+  const titleColor = resolveTextColor(theme.axis.titleColor, theme.background, theme, {
+    fontSizePx: theme.axis.titleFontSize,
+    bold: true,
+    site: "axis-title",
+  });
+  return {
+    atlas,
+    ticks: spec?.ticks ?? "auto",
+    title: spec?.title,
+    format: spec?.format as (v: unknown) => string,
+    gridLines: spec?.gridLines ?? true,
+    axisLine: spec?.axisLine ?? true,
+    label: spec?.label,
+    labelCollision: spec?.labelCollision ?? "auto",
+    labelFontSize: theme.axis.labelFontSize,
+    labelColor,
+    tickColor: theme.axis.color,
+    axisLineColor: theme.axis.color,
+    gridColor: theme.axis.gridColor,
+    titleFontSize: theme.axis.titleFontSize,
+    titleColor,
+  };
+}
+
+function isInsidePosition(p: LegendSpec["position"]): p is LegendInsidePosition {
+  return typeof p === "object" && p !== null && "inside" in p;
+}
+
+/**
+ * Build the chart title block (title + subtitle) as a single Placeable. The
+ * block is left-aligned and stacked vertically; either child may be absent.
+ */
+function buildTitleBlock(
+  atlas: GlyphAtlas,
+  theme: Theme,
+  title: { text: string; maxWidth: number | undefined } | null,
+  subtitle: { text: string; maxWidth: number | undefined } | null,
+): Placeable | undefined {
+  const items: Placeable[] = [];
+  if (title) {
+    const text = truncateToWidth(atlas, title.text, title.maxWidth, {
+      fontSize: theme.title.fontSize,
+      fontWeight: theme.title.fontWeight,
+    });
+    const w = atlas.measureText(text, {
+      fontSize: theme.title.fontSize,
+      fontWeight: theme.title.fontWeight,
+      simple: true,
+    }).width;
+    const titleColor = resolveTextColor(theme.title.color, theme.background, theme, {
+      fontSizePx: theme.title.fontSize,
+      bold: true,
+      site: "title",
+    });
+    items.push(
+      placeable({ width: w, height: theme.title.fontSize }, (layer, o) => {
+        layer.pushText({
+          simple: true,
+          text,
+          x: o.x,
+          y: o.y,
+          fontSize: theme.title.fontSize,
+          color: titleColor,
+        });
+      }),
+    );
+  }
+  if (subtitle) {
+    const text = truncateToWidth(atlas, subtitle.text, subtitle.maxWidth, {
+      fontSize: theme.subtitle.fontSize,
+    });
+    const w = atlas.measureText(text, { fontSize: theme.subtitle.fontSize, simple: true }).width;
+    const subColor = resolveTextColor(theme.subtitle.color, theme.background, theme, {
+      fontSizePx: theme.subtitle.fontSize,
+      site: "subtitle",
+    });
+    items.push(
+      placeable({ width: w, height: theme.subtitle.fontSize }, (layer, o) => {
+        layer.pushText({
+          simple: true,
+          text,
+          x: o.x,
+          y: o.y,
+          fontSize: theme.subtitle.fontSize,
+          color: subColor,
+        });
+      }),
+    );
+  }
+  if (items.length === 0) return undefined;
+  return stack(items, { direction: "vertical", align: "start", gap: LAYOUT_GAP.subtitleGap });
+}
+
+type LegendChannelScales = Omit<ScaleBundle, "x" | "y">;
+
+interface BuildLegendArgs<T> {
+  atlas: GlyphAtlas;
+  theme: Theme;
+  colorScale: NonNullable<ScaleBundle["color"]>;
+  colorLayers: { aes: ResolvedAes<T, unknown>; geom: Geom<T> }[];
+  implicitSeries: { keys: readonly string[]; geom: Geom<T> } | undefined;
+  legendSpec: LegendSpec;
+  orientation: "horizontal" | "vertical";
+  colorBarLength: number;
+  colorBarThickness: number;
+  hidden: ReadonlySet<string> | undefined;
+  dimAlpha: number | undefined;
+  scales: LegendChannelScales;
+}
+
+/**
+ * Build one point-style swatch for a merged legend entry. Resolves each
+ * listed channel's scale at `value` and composes the result into a single
+ * `PointSwatchSpec`. Channels listed in `mergeSet` but lacking an active
+ * scale are silently skipped — the merge declaration is the consumer's
+ * assertion that the channels exist *if* they're configured.
+ */
+export function composeMergedPointSwatch(
+  value: unknown,
+  color: Color,
+  scales: LegendChannelScales,
+  mergeSet: ReadonlySet<LegendMergeChannel>,
+  theme: Theme,
+): PointSwatchSpec {
+  const swatch: PointSwatchSpec = {
+    kind: "point",
+    fill: color,
+    radius: 5,
+    strokeWidth: theme.marks.pointStrokeWidth,
+  };
+  if (mergeSet.has("shape") && scales.shape) {
+    swatch.shape = scales.shape.fn(value);
+  }
+  if (mergeSet.has("borderStyle") && scales.borderStyle) {
+    swatch.borderStyle = scales.borderStyle.fn(value);
+    if (
+      swatch.borderStyle === "open" ||
+      swatch.borderStyle === "dashed" ||
+      swatch.borderStyle === "dotted"
+    ) {
+      swatch.stroke = color;
+    }
+  }
+  if (mergeSet.has("overlayGlyph") && scales.overlayGlyph) {
+    const og = scales.overlayGlyph.fn(value);
+    if (og) swatch.overlayGlyph = og;
+  }
+  if (mergeSet.has("size") && scales.size) {
+    // Size encodes a *numeric* field, so a categorical merge can't tie a
+    // distinct size to each domain entry. Sample at the domain midpoint so
+    // every row gets the same representative radius — communicates "size is
+    // also encoded by this field" without pretending each category has its
+    // own size. Cap to a sensible legend swatch radius.
+    const [d0, d1] = scales.size.domain;
+    const r = scales.size.fn((d0 + d1) / 2) as number;
+    swatch.radius = Math.min(Math.max(r, 3), 9);
+  }
+  return swatch;
+}
+
+/**
+ * Detect which non-color channels share the color scale's categorical domain,
+ * so the legend can fold them into one row per entry without the consumer
+ * spelling out `merge: [...]`. A channel auto-merges when its scale exists AND
+ * its `.domain` is structurally equal to the color domain. `size` is numeric
+ * and never auto-merges; opt in via `legendSpec.merge` if you want it.
+ *
+ * Exported for testing.
+ */
+export function autoMergeChannels(
+  colorDomain: readonly unknown[],
+  scales: LegendChannelScales,
+): LegendMergeChannel[] {
+  const out: LegendMergeChannel[] = [];
+  // An empty color domain has no entries to merge into; equality with an
+  // empty channel domain is meaningless and would produce phantom merges.
+  if (colorDomain.length === 0) return out;
+  if (
+    scales.shape &&
+    scales.shape.domain.length > 0 &&
+    arraysEqual(colorDomain, scales.shape.domain)
+  ) {
+    out.push("shape");
+  }
+  if (
+    scales.borderStyle &&
+    scales.borderStyle.domain.length > 0 &&
+    arraysEqual(colorDomain, scales.borderStyle.domain)
+  ) {
+    out.push("borderStyle");
+  }
+  if (
+    scales.overlayGlyph &&
+    scales.overlayGlyph.domain.length > 0 &&
+    arraysEqual(colorDomain, scales.overlayGlyph.domain)
+  ) {
+    out.push("overlayGlyph");
+  }
+  return out;
+}
+
+/**
+ * Build the appropriate legend builder (categorical `legend()` vs continuous
+ * `colorBar()`) from a finalized color scale. Returned as a `Placeable` —
+ * the chart pipeline measures it before layout to size the slot exactly.
+ */
+function buildLegend<T>(args: BuildLegendArgs<T>): LegendBuilder {
+  const {
+    atlas,
+    theme,
+    colorScale,
+    colorLayers,
+    implicitSeries,
+    legendSpec,
+    orientation,
+    hidden,
+    dimAlpha,
+  } = args;
+  const isContinuous = colorScale.type === "continuous" || colorScale.type === "diverging";
+  if (isContinuous) {
+    const stashed = colorScale.palette;
+    const palette: ContinuousPalette =
+      stashed && stashed.kind === "continuous"
+        ? stashed
+        : continuousPaletteFromScale(colorScale, theme);
+    const domain = colorScale.domain as readonly [unknown, unknown];
+    const d0 = Number(domain[0]);
+    const d1 = Number(domain[1]);
+    const numericDomain: readonly [number, number] = [
+      Number.isFinite(d0) ? d0 : 0,
+      Number.isFinite(d1) ? d1 : 0,
+    ];
+    const legendLabelColor = resolveTextColor(theme.legend.labelColor, theme.background, theme, {
+      fontSizePx: theme.legend.fontSize,
+      site: "legend-label",
+    });
+    return colorBar({
+      palette,
+      domain: numericDomain,
+      orientation,
+      length: args.colorBarLength,
+      thickness: args.colorBarThickness,
+      ticks: legendSpec.ticks,
+      tickValues: legendSpec.tickValues,
+      minorTicks: legendSpec.minorTicks,
+      labelStep: legendSpec.labelStep,
+      format: legendSpec.format,
+      atlas,
+      fontSize: theme.legend.fontSize,
+      labelColor: legendLabelColor,
+      title: legendSpec.title,
+      titleFontSize: theme.legend.fontSize,
+      titleColor: legendLabelColor,
+      // The color scale already applied `theme.paletteBlendSpace` to
+      // `palette` upstream, so this override only fires when the legend
+      // spec wants a *different* space than the chart's color encoding.
+      blendSpace: legendSpec.blendSpace,
+    });
+  }
+  const swatchGeom = (colorLayers[0]?.geom ?? implicitSeries?.geom)!;
+  const mergeSet = new Set<LegendMergeChannel>(
+    legendSpec.merge ?? autoMergeChannels(colorScale.domain, args.scales),
+  );
+  const mergesPointStyling =
+    mergeSet.has("shape") ||
+    mergeSet.has("borderStyle") ||
+    mergeSet.has("overlayGlyph") ||
+    mergeSet.has("size");
+  const swatchFor: (value: unknown, color: Color) => SwatchSpec = mergesPointStyling
+    ? (value, color) => composeMergedPointSwatch(value, color, args.scales, mergeSet, theme)
+    : swatchGeom.legendSwatch
+      ? (_v, c) => swatchGeom.legendSwatch!(c, theme)
+      : (_v, c) => pointSwatch({ fill: c, radius: 5 });
+  const catLabelColor = resolveTextColor(theme.legend.labelColor, theme.background, theme, {
+    fontSizePx: theme.legend.fontSize,
+    site: "legend-label",
+  });
+  return legendBuilder(
+    colorScale.domain.map((value) => ({
+      label: String(value),
+      swatch: swatchFor(value, colorScale.fn(value)),
+      hidden: hidden?.has(String(value)),
+    })),
+    {
+      atlas,
+      orientation,
+      fontSize: theme.legend.fontSize,
+      labelColor: catLabelColor,
+      entryGap: theme.legend.entryGap,
+      swatchGap: theme.legend.swatchGap,
+      title: legendSpec.title,
+      titleColor: catLabelColor,
+      dimAlpha,
+    },
+  );
+}