feat(engine): scatter trendline stacking/styling and mark-level color/size constants

Trendline grows from `boolean` to `boolean | { layer, stroke, strokeWidth }`.
`layer: 'above'` lifts the reference line over a dense point cloud that would
otherwise occlude it; stroke defaults to the theme's text color so the line
stays visible on both light and dark grounds.

Scatter points honor mark-level constants (fill, size, stroke, strokeWidth,
opacity) when the matching encoding channel isn't a data field, so layered
scatters can set per-layer color and size instead of collapsing to the default.

Author: rileyhilliard

bun.lock

@@ -39,7 +39,9 @@
   },
   "overrides": {
     "strip-ansi": "6.0.1",
-    "string-width": "4.2.3"
+    "string-width": "4.2.3",
+    "react": "19.2.8",
+    "react-dom": "19.2.8"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.4",
@@ -52,8 +54,8 @@
     "husky": "^9.1.7",
     "lightningcss-cli": "^1.32.0",
     "lightningcss-cli-darwin-arm64": "^1.32.0",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
     "ts-json-schema-generator": "^2.9.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.2",

package.json

@@ -140,6 +140,30 @@ export function getRepresentativeColor(fill: string | GradientDef): string {
 // Mark definition (Vega-Lite aligned)
 // ---------------------------------------------------------------------------
 
+/**
+ * Configuration for the scatter regression trend line. Passed as the object
+ * form of `MarkDef.trendline`.
+ */
+export interface TrendlineConfig {
+  /**
+   * Stacking order relative to the point marks. `'below'` (default) draws the
+   * line behind the dots; `'above'` draws it on top so it stays visible over a
+   * dense cloud.
+   */
+  layer?: 'above' | 'below';
+  /**
+   * Stroke color. Defaults to the theme's high-contrast text color so the line
+   * reads on both light and dark grounds. Set an explicit CSS color to override.
+   */
+  stroke?: string;
+  /**
+   * Stroke width in pixels. Defaults to 1.5. Over a dense cloud with `layer:
+   * 'above'`, a heavier line (e.g. 2.5) stays legible where the thin default
+   * disappears into the dots.
+   */
+  strokeWidth?: number;
+}
+
 /**
  * Mark definition object with visual properties.
  *
@@ -217,8 +241,13 @@ export interface MarkDef {
    * suppress it when the chart already carries its own reference line (e.g. a
    * manual x=y diagonal in a separate layer), which would otherwise produce
    * two competing diagonals.
+   *
+   * Pass an object to control stacking order: the line renders `below` the
+   * points by default, but a dense scatter (thousands of overlapping dots)
+   * fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the
+   * reference line over the cloud.
    */
-  trendline?: boolean;
+  trendline?: boolean | TrendlineConfig;
   /**
    * Horizontal pixel offset from the data anchor. Only meaningful when `type`
    * is `'text'`. Use it to lift a label clear of the mark it annotates instead

packages/core/schema/chart.schema.json

@@ -404,6 +404,81 @@ describe('computeScatterMarks', () => {
       expect(uniqueXs.size).toBe(3);
     });
   });
+
+  describe('mark-level constants (no encoding field)', () => {
+    const baseData = [
+      { x: 10, y: 20 },
+      { x: 30, y: 40 },
+    ];
+    const baseEncoding = {
+      x: { field: 'x', type: 'quantitative' as const },
+      y: { field: 'y', type: 'quantitative' as const },
+    };
+    const baseSpec = {
+      markType: 'point' as const,
+      data: baseData,
+      encoding: baseEncoding,
+      chrome: {},
+      annotations: [],
+      responsive: true,
+      theme: {},
+      darkMode: 'off' as const,
+      labels: { density: 'auto' as const, format: '' },
+    };
+
+    it('applies a constant mark.fill to every point when no color field is set', () => {
+      const spec: NormalizedChartSpec = {
+        ...baseSpec,
+        markDef: { type: 'point', fill: '#c1462f' },
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+      expect(marks).toHaveLength(2);
+      expect(marks.every((m) => m.fill === '#c1462f')).toBe(true);
+    });
+
+    it('applies a constant mark.size as the point radius', () => {
+      const spec: NormalizedChartSpec = {
+        ...baseSpec,
+        markDef: { type: 'point', size: 12 },
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+      expect(marks.every((m) => m.r === 12)).toBe(true);
+    });
+
+    it('applies a constant mark.opacity and mark.stroke', () => {
+      const spec: NormalizedChartSpec = {
+        ...baseSpec,
+        markDef: { type: 'point', opacity: 0.15, stroke: 'none' },
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+      expect(marks.every((m) => m.fillOpacity === 0.15)).toBe(true);
+      expect(marks.every((m) => m.stroke === 'none')).toBe(true);
+    });
+
+    it('lets an encoding color field win over a constant mark.fill', () => {
+      const spec: NormalizedChartSpec = {
+        ...baseSpec,
+        data: [
+          { x: 10, y: 20, grp: 'a' },
+          { x: 30, y: 40, grp: 'b' },
+        ],
+        encoding: {
+          ...baseEncoding,
+          color: { field: 'grp', type: 'nominal' },
+        },
+        markDef: { type: 'point', fill: '#c1462f' },
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+      // Two categories -> two distinct scale colors, neither forced to the constant.
+      const fills = new Set(marks.map((m) => m.fill));
+      expect(fills.size).toBe(2);
+      expect(fills.has('#c1462f')).toBe(false);
+    });
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -485,4 +560,45 @@ describe('trendline opt-out', () => {
     expect(marks.some((m) => m.type === 'line')).toBe(false);
     expect(marks.every((m) => m.type === 'point')).toBe(true);
   });
+
+  it('draws the trend line behind the points by default', () => {
+    const spec = makeBasicScatterSpec();
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = scatterRenderer(spec, scales, chartArea, fullStrategy, undefined as never);
+
+    // First mark renders first, i.e. underneath everything drawn after it.
+    expect(marks[0].type).toBe('line');
+  });
+
+  it('draws the trend line on top when trendline.layer is "above"', () => {
+    const base = makeBasicScatterSpec();
+    const spec: NormalizedChartSpec = {
+      ...base,
+      markDef: { type: 'point', trendline: { layer: 'above' } },
+    };
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = scatterRenderer(spec, scales, chartArea, fullStrategy, undefined as never);
+
+    // Line still present, but now last so it paints over the point cloud.
+    expect(marks.some((m) => m.type === 'line')).toBe(true);
+    expect(marks[marks.length - 1].type).toBe('line');
+  });
+
+  it('applies the trendline config stroke and strokeWidth to the line mark', () => {
+    const base = makeBasicScatterSpec();
+    const spec: NormalizedChartSpec = {
+      ...base,
+      markDef: {
+        type: 'point',
+        trendline: { layer: 'above', stroke: '#ff00ff', strokeWidth: 3 },
+      },
+    };
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = scatterRenderer(spec, scales, chartArea, fullStrategy, undefined as never);
+
+    const line = marks.find((m) => m.type === 'line');
+    expect(line).toBeDefined();
+    expect((line as { stroke: string }).stroke).toBe('#ff00ff');
+    expect((line as { strokeWidth: number }).strokeWidth).toBe(3);
+  });
 });

packages/core/schema/vizspec.schema.json

@@ -108,20 +108,36 @@ describe('computeTrendLine', () => {
       expect(result.strokeDasharray).toBe('6 4');
     });
 
-    it('has a subdued stroke color', () => {
+    it('falls back to a subdued stroke color when none is passed', () => {
       const points = [makePoint(100, 200), makePoint(300, 100)];
       const result = computeTrendLine(points)!;
 
       expect(result.stroke).toBe('#666666');
     });
 
-    it('has a thin stroke width', () => {
+    it('uses the passed stroke color so it can read on the current theme ground', () => {
+      // The renderer passes theme.colors.text so the line stays visible on
+      // both light and dark backgrounds (the old hardcoded gray vanished on black).
+      const points = [makePoint(100, 200), makePoint(300, 100)];
+      const result = computeTrendLine(points, '#cccccc')!;
+
+      expect(result.stroke).toBe('#cccccc');
+    });
+
+    it('has a thin stroke width by default', () => {
       const points = [makePoint(100, 200), makePoint(300, 100)];
       const result = computeTrendLine(points)!;
 
       expect(result.strokeWidth).toBe(1.5);
     });
 
+    it('uses the passed stroke width so a dense-cloud line can be made heavier', () => {
+      const points = [makePoint(100, 200), makePoint(300, 100)];
+      const result = computeTrendLine(points, '#fff', 2.5)!;
+
+      expect(result.strokeWidth).toBe(2.5);
+    });
+
     it('has an aria label describing the trend', () => {
       const points = [makePoint(100, 200), makePoint(300, 100)];
       const result = computeTrendLine(points)!;

packages/core/src/types/spec.ts

@@ -120,6 +120,14 @@ export function computeScatterMarks(
   const resolvedSize = buildSizeScale(sizeEnc, spec.data, SIZE_SCALE_DEFAULTS.point);
   const sizeScale = resolvedSize?.scale;
 
+  // Mark-level constants (VL-aligned "Default fill/size/opacity"). These apply
+  // only when the matching encoding channel isn't a data field: a constant
+  // `mark.fill` colors every point, `mark.size` sets a constant radius. Without
+  // this, layered scatters (a dim background layer + a highlighted layer) can't
+  // set per-layer color/size and all points collapse to the default blue.
+  const constFill = spec.markDef.fill;
+  const constSize = spec.markDef.size;
+
   const keyEnc = encoding.key && 'field' in encoding.key ? encoding.key : undefined;
   const keyField = keyEnc?.field;
   const marks: PointMark[] = [];
@@ -140,11 +148,14 @@ export function computeScatterMarks(
       color = Number.isFinite(val)
         ? getSequentialColor(scales, val)
         : getColor(scales, '__default__');
-    } else {
+    } else if (colorField) {
       color = getColor(scales, category ?? '__default__');
+    } else {
+      // No color field: honor a constant mark.fill, else the default series color.
+      color = constFill ?? getColor(scales, '__default__');
     }
 
-    let radius = DEFAULT_POINT_RADIUS;
+    let radius = constSize != null ? constSize : DEFAULT_POINT_RADIUS;
     if (sizeScale && sizeField) {
       const sizeVal = Number(row[sizeField]);
       if (Number.isFinite(sizeVal)) {
@@ -168,9 +179,9 @@ export function computeScatterMarks(
       cy,
       r: radius,
       fill: color,
-      stroke: '#ffffff',
-      strokeWidth: 1,
-      fillOpacity: 0.7,
+      stroke: spec.markDef.stroke ?? '#ffffff',
+      strokeWidth: spec.markDef.strokeWidth ?? 1,
+      fillOpacity: spec.markDef.opacity ?? 0.7,
       data: row as Record<string, unknown>,
       aria,
     });