feat(engine)!: reject point-mark sizes above 50px radius

openchart point size is a radius in px (default 5), but Vega-Lite — the
prior every LLM and most authors carry — defines point size as an area
in px². VL-habit values (60-900) therefore render as chart-swallowing
discs, and this mistake kept recurring in downstream chart authoring.

validateSpec now errors on mark.size, encoding.size.value, and
encoding.size.scale.range values above 50 for point marks, with the
sqrt(area/pi) conversion recipe in the message. Docstrings on
MarkDef.size and the size channel now document radius semantics
honestly (the size channel previously claimed VL alignment).

Author: rileyhilliard

CHANGELOG.md

@@ -8,6 +8,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ### Breaking Changes
 
+- **validate!:** point-mark sizes above 50 now fail validation. Openchart point sizes are radii in px (`mark.size` default 5; `encoding.size` range default [3, 30]), but Vega-Lite defines point `size` as an area in px², so VL-habit values (60-900) rendered as chart-swallowing discs and were, in practice, always a units mistake. The error carries the conversion (r = sqrt(area/pi), e.g. VL 110 → `size: 6`) on `mark.size`, `encoding.size.value`, and `encoding.size.scale.range`. Intentional radii up to 50 stay valid; `MarkDef.size` and the `size` channel docs now state the units per mark type.
+
 - **bar/area!:** multi-series bar and area charts now default to stacked (`stack: 'zero'`) when a `color` encoding is present, matching Vega-Lite. Pass `stack: null` on the value channel to keep the old grouped (bar) or overlap (area) behavior. See [migration guide](docs/migrating-v8.md#1-multi-series-bararea-charts-default-to-stacked).
 - **arc!:** `encoding.theta` is now the canonical value channel for arc, waffle, and parliament marks. `encoding.y` still works at runtime (sugar rewrites it to theta with a deprecation warning) but is removed from the TypeScript type.
 - **encoding!:** dead channels `shape`, `radius`, `href`, and `order` removed from the `Encoding` interface and `MARK_ENCODING_RULES`. They were never implemented. Runtime strips them with a warning for backward compat.

docs/spec-reference.md

@@ -315,7 +315,7 @@ The engine validates encoding channels at runtime using `CHART_ENCODING_RULES`.
 
 **color channel**: Series differentiation. Assigns colors from the categorical palette. Required for pie/donut (defines slices). Optional for all others (creates multi-series with legend).
 
-**size channel**: Mark size. Creates bubble charts when applied to scatter. Maps a quantitative field to the mark radius or area.
+**size channel**: Mark size. Creates bubble charts when applied to scatter. Maps a quantitative field to the dot **radius in pixels**, area-proportionally (sqrt curve); the default range is [3, 30] and `scale.range` overrides it in radius px. A constant lives at `mark.size`, also a radius (default 5, typical 2-12). Note this differs from Vega-Lite, where point `size` is an **area** in px² — a VL size of 110 is `mark.size: 6` here (r = √(area/π)); validation rejects radii above 50 with the conversion.
 
 **detail channel**: Grouping without visual encoding. Splits data into groups (like color does) but doesn't assign different colors. Useful when you want separate lines per group but all the same color.
 

packages/core/src/types/spec.ts

@@ -219,7 +219,15 @@ export interface MarkDef {
   endAngle?: number;
   /** Corner radius for rect/bar marks. 'pill' sets rx to half the bar thickness. */
   cornerRadius?: number | 'pill';
-  /** Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band. */
+  /**
+   * Bar/column marks: fixed bar thickness in pixels. When set, bars are this
+   * height (horizontal) or width (vertical), centered within the band.
+   *
+   * Point marks: the dot RADIUS in pixels (default 5, typical 2-12). This is
+   * NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of
+   * 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation
+   * rejects values above 50 with the conversion.
+   */
   size?: number;
   /** Whether the mark is filled (vs stroked only). */
   filled?: boolean;
@@ -701,9 +709,13 @@ export interface Encoding<TData extends DataRow = DataRow> {
    */
   color?: EncodingChannel<TData> | ConditionalValueDef<TData> | ValueDef;
   /**
-   * Size channel. Used by point/bubble charts to scale dot area by a quantitative field.
-   * Accepts a conditional definition to vary size based on data predicates,
-   * or a bare `{ value }` constant (VL aligned; expanded to `mark.size`).
+   * Size channel. Used by point/bubble charts to scale dots by a quantitative
+   * field, area-proportionally (sqrt curve). The units are dot RADII in px:
+   * `scale.range` defaults to [3, 30] for scatter, and a bare `{ value }`
+   * constant expands to `mark.size`, also a radius. This differs from
+   * Vega-Lite, where point size is an area in px^2 -- VL-scale values
+   * (60-900) are rejected by validation with the conversion.
+   * Accepts a conditional definition to vary size based on data predicates.
    */
   size?: EncodingChannel<TData> | ConditionalValueDef<TData> | ValueDef;
   /**

packages/engine/src/compiler/__tests__/point-size.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Tests for the Vega-Lite point-size near-miss guard.
+ *
+ * VL defines point `size` as an area in px^2; openchart's `mark.size` and
+ * `encoding.size` ranges are radii in px. Values above the plausibility
+ * ceiling are always imported VL area numbers in practice, so they must fail
+ * validation with the radius conversion in the suggestion.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { validateSpec } from '../validate';
+
+const DATA = [
+  { spend: 10_266, score: 219.3 },
+  { spend: 29_720, score: 214.6 },
+];
+
+function scatter(overrides: Record<string, unknown> = {}) {
+  return {
+    mark: { type: 'point', filled: true },
+    data: DATA,
+    encoding: {
+      x: { field: 'spend', type: 'quantitative' },
+      y: { field: 'score', type: 'quantitative' },
+    },
+    ...overrides,
+  };
+}
+
+describe('point size validation', () => {
+  it('accepts radius-scale mark.size values', () => {
+    const result = validateSpec(scatter({ mark: { type: 'point', size: 6 } }));
+    expect(result.valid).toBe(true);
+  });
+
+  it('accepts the ceiling itself', () => {
+    const result = validateSpec(scatter({ mark: { type: 'point', size: 50 } }));
+    expect(result.valid).toBe(true);
+  });
+
+  it('rejects VL-area mark.size values with the radius conversion', () => {
+    const result = validateSpec(scatter({ mark: { type: 'point', size: 110 } }));
+    expect(result.valid).toBe(false);
+    const error = result.errors.find((e) => e.path === 'mark.size');
+    expect(error).toBeDefined();
+    expect(error?.code).toBe('INVALID_VALUE');
+    // sqrt(110 / pi) ~ 5.9 -> 6
+    expect(error?.suggestion).toContain('use 6');
+    expect(error?.suggestion).toContain('radi');
+  });
+
+  it('rejects a VL-area encoding.size.value constant', () => {
+    const spec = scatter();
+    (spec.encoding as Record<string, unknown>).size = { value: 130 };
+    const result = validateSpec(spec);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.path === 'encoding.size.value')).toBe(true);
+  });
+
+  it('rejects VL-area encoding.size scale ranges', () => {
+    const spec = scatter();
+    (spec.encoding as Record<string, unknown>).size = {
+      field: 'spend',
+      type: 'quantitative',
+      scale: { range: [80, 900] },
+    };
+    const result = validateSpec(spec);
+    expect(result.valid).toBe(false);
+    const error = result.errors.find((e) => e.path === 'encoding.size.scale.range');
+    expect(error).toBeDefined();
+  });
+
+  it('accepts radius-scale encoding.size ranges', () => {
+    const spec = scatter();
+    (spec.encoding as Record<string, unknown>).size = {
+      field: 'spend',
+      type: 'quantitative',
+      scale: { range: [4, 18] },
+    };
+    expect(validateSpec(spec).valid).toBe(true);
+  });
+
+  it('leaves bar mark.size (thickness px) alone', () => {
+    const result = validateSpec({
+      mark: { type: 'bar', size: 60 },
+      data: [
+        { state: 'UT', score: 219.3 },
+        { state: 'NY', score: 214.6 },
+      ],
+      encoding: {
+        x: { field: 'state', type: 'nominal' },
+        y: { field: 'score', type: 'quantitative' },
+      },
+    });
+    expect(result.valid).toBe(true);
+  });
+});

packages/engine/src/compiler/validate.ts

@@ -455,6 +455,71 @@ function validateMarkRenderMode(spec: Record<string, unknown>, errors: Validatio
   }
 }
 
+// ---------------------------------------------------------------------------
+// Point size validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Ceiling above which a point size is, in practice, always an imported
+ * Vega-Lite *area* value rather than an intentional radius. VL defines point
+ * `size` as symbol area in px^2 (size: 110 is a ~12px-wide dot); openchart's
+ * `mark.size` and `encoding.size` ranges are a radius in px (default 5), so
+ * VL-habit values render as chart-swallowing discs. Radii up to the ceiling
+ * stay legal: a 50px bubble is enormous but plausible as a deliberate choice.
+ */
+const MAX_PLAUSIBLE_POINT_RADIUS = 50;
+
+function pointSizeError(path: string, value: number): ValidationError {
+  const radius = Math.max(1, Math.round(Math.sqrt(value / Math.PI)));
+  return {
+    message: `Spec error: ${path} is a radius in pixels, and ${value} would draw a ${Math.round(value * 2)}px-wide circle. This usually means the value was written in Vega-Lite's units, where point size is an area in px^2.`,
+    path,
+    code: 'INVALID_VALUE',
+    suggestion: `Point sizes are radii in px (default 5, typical 2-12). For the dot a Vega-Lite size of ${value} draws, use ${radius} (r = sqrt(area / pi)).`,
+  };
+}
+
+/**
+ * Guard against Vega-Lite size semantics on point marks -- the same
+ * near-miss-VL treatment as `data.url` and string `calculate` expressions:
+ * a form that would silently do the wrong thing fails loud with the recipe.
+ */
+function validatePointSize(spec: Record<string, unknown>, errors: ValidationError[]): void {
+  const markType =
+    typeof spec.mark === 'string' ? spec.mark : (spec.mark as Record<string, unknown>)?.type;
+  if (markType !== 'point') return;
+
+  if (spec.mark && typeof spec.mark === 'object') {
+    const size = (spec.mark as Record<string, unknown>).size;
+    if (typeof size === 'number' && size > MAX_PLAUSIBLE_POINT_RADIUS) {
+      errors.push(pointSizeError('mark.size', size));
+    }
+  }
+
+  const sizeEnc =
+    spec.encoding && typeof spec.encoding === 'object'
+      ? ((spec.encoding as Record<string, unknown>).size as Record<string, unknown> | undefined)
+      : undefined;
+  if (!sizeEnc || typeof sizeEnc !== 'object') return;
+
+  if (typeof sizeEnc.value === 'number' && sizeEnc.value > MAX_PLAUSIBLE_POINT_RADIUS) {
+    errors.push(pointSizeError('encoding.size.value', sizeEnc.value));
+  }
+
+  const range =
+    sizeEnc.scale && typeof sizeEnc.scale === 'object'
+      ? (sizeEnc.scale as Record<string, unknown>).range
+      : undefined;
+  if (Array.isArray(range)) {
+    const worst = range.find(
+      (entry) => typeof entry === 'number' && entry > MAX_PLAUSIBLE_POINT_RADIUS,
+    );
+    if (typeof worst === 'number') {
+      errors.push(pointSizeError('encoding.size.scale.range', worst));
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Chart validation
 // ---------------------------------------------------------------------------
@@ -613,6 +678,10 @@ function validateChartSpec(spec: Record<string, unknown>, errors: ValidationErro
   // but a value outside the union is a typo and fails loud.
   validateMarkRenderMode(spec, errors);
 
+  // Point sizes that only make sense as Vega-Lite areas fail loud with the
+  // radius conversion, before they render as chart-swallowing discs.
+  validatePointSize(spec, errors);
+
   // Near-miss: VL's string expression form of calculate. A restricted string
   // grammar is deliberately not supported (decision: structured form only);
   // point authors at the structured equivalent instead.