refactor(engine): extract pure helpers from compile.ts into compile/ subfolder

Pulls three side-effect-light computations out of compileChart into their own
files in packages/engine/src/compile/:

- data-clip.ts: filterClippedDomains - drops data rows outside clipped
  scale domains on the x/y channels.
- color-scale-range.ts: applyColorScaleRange - applies the theme palette to
  the color scale range when the encoding declares no explicit range.
  Still mutates the scale in place; documented at the callsite.
- watermark-obstacle.ts: computeWatermarkObstacle - computes the rect the
  brand watermark occupies so annotations can avoid it.

The orchestration ordering in compile.ts is unchanged. A comment block
explicitly names the three load-bearing invariants (double legend pass,
in-place computeGridlines mutation, post-hoc defaultColor assignment) so
future edits don't silently regress layout.

The compile-snapshot oracle (previous commit) matches exactly after the
extraction, with no snapshot updates required.

Author: rileyhilliard

packages/engine/src/compile.ts

@@ -32,7 +32,6 @@ import type {
 } from '@opendata-ai/openchart-core';
 import {
   adaptTheme,
-  BRAND_RESERVE_WIDTH,
   computeLabelBounds,
   generateAltText,
   generateDataTable,
@@ -57,6 +56,9 @@ import { ruleRenderer } from './charts/rule';
 import { scatterRenderer } from './charts/scatter';
 import { textRenderer } from './charts/text';
 import { tickRenderer } from './charts/tick';
+import { applyColorScaleRange } from './compile/color-scale-range';
+import { filterClippedDomains } from './compile/data-clip';
+import { computeWatermarkObstacle } from './compile/watermark-obstacle';
 import { compile as compileSpec, flattenLayers } from './compiler/index';
 
 // Register all built-in chart renderers under the new Vega-Lite mark type names.
@@ -307,6 +309,11 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     theme = adaptTheme(theme);
   }
 
+  // ORCHESTRATION INVARIANTS — do not reorder without care:
+  // 1. Legend is computed twice (preliminary + refined) to break a dims/legend dependency cycle.
+  // 2. computeGridlines mutates `axes` in place.
+  // 3. scales.defaultColor is set post-computeScales because the resolution needs theme context.
+
   // Compute legend first (needs to reserve space)
   const preliminaryArea: Rect = {
     x: 0,
@@ -358,19 +365,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   }
 
   // Filter clipped scale domains: when scale.clip is true, exclude rows outside the domain
-  for (const channel of ['x', 'y'] as const) {
-    const enc = chartSpec.encoding[channel];
-    if (!enc?.scale?.clip || !enc.scale.domain) continue;
-    const domain = enc.scale.domain;
-    const field = enc.field;
-    if (Array.isArray(domain) && domain.length === 2 && typeof domain[0] === 'number') {
-      const [lo, hi] = domain as [number, number];
-      renderData = renderData.filter((row) => {
-        const v = Number(row[field]);
-        return Number.isFinite(v) && v >= lo && v <= hi;
-      });
-    }
-  }
+  renderData = filterClippedDomains(renderData, chartSpec.encoding);
 
   // Build a filtered spec for scales and marks, keeping all other properties intact
   const renderSpec = renderData !== chartSpec.data ? { ...chartSpec, data: renderData } : chartSpec;
@@ -379,29 +374,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   const scales = computeScales(renderSpec, chartArea, renderSpec.data);
 
   // Update color scale to use theme palette (only when user hasn't provided an explicit range)
-  if (scales.color) {
-    const hasExplicitRange = !!(
-      renderSpec.encoding.color &&
-      'field' in renderSpec.encoding.color &&
-      (renderSpec.encoding.color.scale?.range as string[] | undefined)?.length
-    );
-    if (scales.color.type === 'sequential') {
-      // Sequential: use first sequential palette (or fall back to categorical endpoints)
-      if (!hasExplicitRange) {
-        const seqStops = Object.values(theme.colors.sequential)[0] ?? theme.colors.categorical;
-        (scales.color.scale as unknown as import('d3-scale').ScaleLinear<string, string>).range([
-          seqStops[0],
-          seqStops[seqStops.length - 1],
-        ]);
-      }
-    } else {
-      if (!hasExplicitRange) {
-        (scales.color.scale as import('d3-scale').ScaleOrdinal<string, string>).range(
-          theme.colors.categorical,
-        );
-      }
-    }
-  }
+  applyColorScaleRange(scales, renderSpec.encoding, theme);
 
   // Set default color for single-series charts. If the user set a fill on the mark def
   // (string or gradient), that takes priority over the theme's first categorical color.
@@ -444,18 +417,8 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   }
 
   // Add brand watermark as an obstacle so annotations avoid overlapping it.
-  // The brand is right-aligned on the same baseline as the first bottom chrome element,
-  // offset below the chart area by x-axis extent (tick labels + axis title).
-  if (watermark) {
-    const brandPadding = theme.spacing.padding;
-    const brandX = dims.total.width - brandPadding - BRAND_RESERVE_WIDTH;
-    const xAxisExtent = axes.x?.label ? 48 : axes.x ? 26 : 0;
-    const firstBottomChrome = dims.chrome.source ?? dims.chrome.byline ?? dims.chrome.footer;
-    const brandY = firstBottomChrome
-      ? chartArea.y + chartArea.height + xAxisExtent + firstBottomChrome.y
-      : chartArea.y + chartArea.height + xAxisExtent + theme.spacing.chartToFooter;
-    obstacles.push({ x: brandX, y: brandY, width: BRAND_RESERVE_WIDTH, height: 30 });
-  }
+  const watermarkRect = computeWatermarkObstacle(dims, watermark, axes, theme);
+  if (watermarkRect) obstacles.push(watermarkRect);
   const annotations: ResolvedAnnotation[] = computeAnnotations(
     chartSpec,
     scales,

packages/engine/src/compile/__tests__/color-scale-range.test.ts

@@ -0,0 +1,79 @@
+import type { Encoding, ResolvedTheme } from '@opendata-ai/openchart-core';
+import { resolveTheme } from '@opendata-ai/openchart-core';
+import { scaleLinear, scaleOrdinal } from 'd3-scale';
+import { describe, expect, it } from 'vitest';
+import type { ResolvedScales } from '../../layout/scales';
+import { applyColorScaleRange } from '../color-scale-range';
+
+const theme: ResolvedTheme = resolveTheme();
+
+describe('applyColorScaleRange', () => {
+  it('is a no-op when no color scale is present', () => {
+    const scales: ResolvedScales = {};
+    const encoding: Encoding = {
+      x: { field: 'x', type: 'quantitative' },
+      y: { field: 'y', type: 'quantitative' },
+    };
+    expect(() => applyColorScaleRange(scales, encoding, theme)).not.toThrow();
+    expect(scales.color).toBeUndefined();
+  });
+
+  it('does not overwrite the range when the encoding declares an explicit palette', () => {
+    // computeScales has already applied the explicit palette to the scale.
+    // The helper must leave it untouched (not replace it with the theme palette).
+    const explicit = ['#111111', '#222222', '#333333'];
+    const ordinal = scaleOrdinal<string, string>().domain(['a', 'b', 'c']).range(explicit);
+    const scales: ResolvedScales = {
+      color: { scale: ordinal, type: 'ordinal', channel: 'color' },
+    };
+    const encoding: Encoding = {
+      x: { field: 'x', type: 'nominal' },
+      y: { field: 'y', type: 'quantitative' },
+      color: {
+        field: 'c',
+        type: 'nominal',
+        scale: { range: explicit },
+      },
+    };
+    applyColorScaleRange(scales, encoding, theme);
+    expect(ordinal.range()).toEqual(explicit);
+    expect(ordinal.range()).not.toEqual(theme.colors.categorical);
+  });
+
+  it('assigns the theme categorical palette when no range is set', () => {
+    const ordinal = scaleOrdinal<string, string>().domain(['a', 'b', 'c']);
+    const scales: ResolvedScales = {
+      color: { scale: ordinal, type: 'ordinal', channel: 'color' },
+    };
+    const encoding: Encoding = {
+      x: { field: 'x', type: 'nominal' },
+      y: { field: 'y', type: 'quantitative' },
+      color: { field: 'c', type: 'nominal' },
+    };
+    applyColorScaleRange(scales, encoding, theme);
+    expect(ordinal.range()).toEqual(theme.colors.categorical);
+  });
+
+  it('uses the first sequential palette endpoints for sequential color scales', () => {
+    const linear = scaleLinear<string, string>().domain([0, 100]);
+    const scales: ResolvedScales = {
+      color: {
+        scale: linear as unknown as ResolvedScales['color'] extends infer T
+          ? T extends { scale: infer S }
+            ? S
+            : never
+          : never,
+        type: 'sequential',
+        channel: 'color',
+      } as NonNullable<ResolvedScales['color']>,
+    };
+    const encoding: Encoding = {
+      x: { field: 'x', type: 'quantitative' },
+      y: { field: 'y', type: 'quantitative' },
+      color: { field: 'v', type: 'quantitative' },
+    };
+    applyColorScaleRange(scales, encoding, theme);
+    const firstSeq = Object.values(theme.colors.sequential)[0] ?? theme.colors.categorical;
+    expect(linear.range()).toEqual([firstSeq[0], firstSeq[firstSeq.length - 1]]);
+  });
+});

packages/engine/src/compile/__tests__/data-clip.test.ts

@@ -0,0 +1,59 @@
+import type { Encoding } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { filterClippedDomains } from '../data-clip';
+
+describe('filterClippedDomains', () => {
+  const data = [
+    { x: -5, y: 10 },
+    { x: 10, y: 20 },
+    { x: 25, y: 80 },
+    { x: 50, y: 110 },
+    { x: 80, y: 200 },
+  ];
+
+  it('returns data unchanged when no channel declares scale.clip', () => {
+    const encoding: Encoding = {
+      x: { field: 'x', type: 'quantitative' },
+      y: { field: 'y', type: 'quantitative' },
+    };
+    const result = filterClippedDomains(data, encoding);
+    expect(result).toBe(data);
+    expect(result).toHaveLength(5);
+  });
+
+  it('filters rows outside the x-axis clipped domain', () => {
+    const encoding: Encoding = {
+      x: {
+        field: 'x',
+        type: 'quantitative',
+        scale: { domain: [0, 30], clip: true },
+      },
+      y: { field: 'y', type: 'quantitative' },
+    };
+    const result = filterClippedDomains(data, encoding);
+    expect(result).toEqual([
+      { x: 10, y: 20 },
+      { x: 25, y: 80 },
+    ]);
+  });
+
+  it('filters rows outside both x- and y-axis clipped domains', () => {
+    const encoding: Encoding = {
+      x: {
+        field: 'x',
+        type: 'quantitative',
+        scale: { domain: [0, 60], clip: true },
+      },
+      y: {
+        field: 'y',
+        type: 'quantitative',
+        scale: { domain: [0, 100], clip: true },
+      },
+    };
+    const result = filterClippedDomains(data, encoding);
+    expect(result).toEqual([
+      { x: 10, y: 20 },
+      { x: 25, y: 80 },
+    ]);
+  });
+});

packages/engine/src/compile/__tests__/watermark-obstacle.test.ts

@@ -0,0 +1,93 @@
+import type { AxisLayout, Rect, ResolvedChrome, ResolvedTheme } from '@opendata-ai/openchart-core';
+import { BRAND_RESERVE_WIDTH, resolveTheme } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import type { AxesResult } from '../../layout/axes';
+import type { LayoutDimensions } from '../../layout/dimensions';
+import { computeWatermarkObstacle } from '../watermark-obstacle';
+
+const theme: ResolvedTheme = resolveTheme();
+
+function makeDims(overrides: Partial<LayoutDimensions> = {}): LayoutDimensions {
+  const total: Rect = { x: 0, y: 0, width: 800, height: 500 };
+  const chartArea: Rect = { x: 60, y: 80, width: 700, height: 360 };
+  const chrome: ResolvedChrome = {
+    topHeight: 80,
+    bottomHeight: 40,
+  } as ResolvedChrome;
+  return {
+    total,
+    chartArea,
+    chrome,
+    margins: { top: 80, right: 40, bottom: 40, left: 60 },
+    theme,
+    ...overrides,
+  };
+}
+
+function makeAxis(label?: string): AxisLayout {
+  return {
+    ticks: [],
+    gridlines: [],
+    label,
+    tickLabelStyle: {
+      fontFamily: theme.fonts.family,
+      fontSize: 12,
+      fontWeight: 400,
+      fill: '#000',
+      lineHeight: 1.2,
+    },
+    start: { x: 0, y: 0 },
+    end: { x: 100, y: 0 },
+  };
+}
+
+describe('computeWatermarkObstacle', () => {
+  it('returns null when watermark is disabled', () => {
+    const dims = makeDims();
+    const axes: AxesResult = { x: makeAxis(), y: makeAxis() };
+    expect(computeWatermarkObstacle(dims, false, axes, theme)).toBeNull();
+  });
+
+  it('sits below the x-axis when no bottom chrome is present', () => {
+    const dims = makeDims();
+    const axes: AxesResult = { x: makeAxis('value'), y: makeAxis() };
+    const rect = computeWatermarkObstacle(dims, true, axes, theme);
+    expect(rect).not.toBeNull();
+    // Right-aligned: total.width - padding - BRAND_RESERVE_WIDTH
+    expect(rect!.x).toBe(dims.total.width - theme.spacing.padding - BRAND_RESERVE_WIDTH);
+    expect(rect!.width).toBe(BRAND_RESERVE_WIDTH);
+    expect(rect!.height).toBe(30);
+    // Watermark sits below chart area, offset by x-axis extent + chartToFooter
+    const expectedY = dims.chartArea.y + dims.chartArea.height + 48 + theme.spacing.chartToFooter;
+    expect(rect!.y).toBe(expectedY);
+  });
+
+  it('aligns with bottom chrome when a source element is present', () => {
+    const sourceY = 20;
+    const dims = makeDims({
+      chrome: {
+        topHeight: 80,
+        bottomHeight: 40,
+        source: {
+          text: 'Source: Test',
+          x: 10,
+          y: sourceY,
+          maxWidth: 500,
+          style: {
+            fontFamily: theme.fonts.family,
+            fontSize: 10,
+            fontWeight: 400,
+            fill: '#666',
+            lineHeight: 1.2,
+          },
+        },
+      } as ResolvedChrome,
+    });
+    const axes: AxesResult = { x: makeAxis(), y: makeAxis() };
+    const rect = computeWatermarkObstacle(dims, true, axes, theme);
+    expect(rect).not.toBeNull();
+    // With axis present but no label, extent is 26.
+    // Y is chartArea.y + chartArea.height + 26 + sourceY
+    expect(rect!.y).toBe(dims.chartArea.y + dims.chartArea.height + 26 + sourceY);
+  });
+});

packages/engine/src/compile/color-scale-range.ts

@@ -0,0 +1,38 @@
+/**
+ * Apply the theme palette as the color scale range when no explicit range was provided.
+ *
+ * Sequential scales take the first/last stops of the first sequential palette
+ * (or the categorical endpoints as a fallback). Categorical scales get the
+ * full categorical palette. A user-provided `encoding.color.scale.range`
+ * always wins.
+ */
+
+import type { Encoding, ResolvedTheme } from '@opendata-ai/openchart-core';
+import type { ScaleLinear, ScaleOrdinal } from 'd3-scale';
+import type { ResolvedScales } from '../layout/scales';
+
+/** Mutates `scales.color.scale.range` in place when no explicit palette was set. */
+export function applyColorScaleRange(
+  scales: ResolvedScales,
+  encoding: Encoding,
+  theme: ResolvedTheme,
+): void {
+  if (!scales.color) return;
+
+  const hasExplicitRange = !!(
+    encoding.color &&
+    'field' in encoding.color &&
+    (encoding.color.scale?.range as string[] | undefined)?.length
+  );
+  if (hasExplicitRange) return;
+
+  if (scales.color.type === 'sequential') {
+    const seqStops = Object.values(theme.colors.sequential)[0] ?? theme.colors.categorical;
+    (scales.color.scale as unknown as ScaleLinear<string, string>).range([
+      seqStops[0],
+      seqStops[seqStops.length - 1],
+    ]);
+  } else {
+    (scales.color.scale as ScaleOrdinal<string, string>).range(theme.colors.categorical);
+  }
+}