fix(engine): warn when a dense chart silently falls back to SVG (#111)

The 'auto' renderer promotes to canvas above 1,000 points, but canvas is
refused outright on faceted, layered, and sparkline charts and on
non-point marks. When both were true -- dense enough to want canvas,
shaped so canvas can't run -- the author got no signal. The only symptom
was a chart that felt heavy, with nothing pointing at the shape as the
cause rather than the point count.

Now that case warns once, above AUTO_CANVAS_REFUSAL_WARN_THRESHOLD
(5,000 points). That sits well clear of the 1,000-point promotion
threshold on purpose: a chart that trips 1,000 by a little renders fine
as SVG, and warning there would fire on ordinary facet and layer charts
that have nothing wrong with them. Explicit renderer: 'canvas' keeps its
existing always-warn behavior and takes precedence, so a dense explicit
request still gets one warning, not two. No dev gating -- the engine has
no such convention; hosts silence or reroute via onWarn.

Writing the end-to-end test surfaced a related bug: compileFaceted never
called resolveMarkRenderMode at all, so renderer: 'canvas' on a facet
grid was ignored with no warning, unlike every other refused shape. The
resolver was unit-tested with faceted: true passed directly, so nothing
caught that the compiler never set it. The facet path now resolves too
(always 'svg', never stamped -- it runs for the reporting).

Co-authored-by: Riley Hilliard <rileyhilliard@users.noreply.github.com>

Author: rileyhilliard

CHANGELOG.md

@@ -31,6 +31,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ### Bug Fixes
 
+- **renderer:** faceted charts never resolved a rendering backend at all, so `renderer: 'canvas'` on a facet grid was ignored with no warning (every other refused shape reported it). The facet compile path now runs the same resolution and reports the refusal.
+- **renderer:** a chart dense enough to want the canvas layer but shaped so canvas is refused (faceted, layered, sparkline, non-point) now warns once instead of silently painting a DOM node per point. Fires above 5,000 point marks, well clear of the 1,000-point `'auto'` promotion threshold so ordinary facet/layer charts stay quiet. Hosts can reroute or silence it through `onWarn` like any other advisory warning.
 - **graph:** spec validation checks encoding fields against the union of keys across ALL nodes/edges instead of only the first row — a field present on some nodes/edges no longer hard-fails validation. `edgeStyle` is accepted as an edge channel, and `sort` on a quantitative field warns instead of erroring.
 - **graph:** node/edge tooltip race eliminated — hovering from an edge onto a node can no longer leave a stale edge tooltip; edge-hover state always clears before the node hover fires.
 - **legend:** rows missing the color field no longer manufacture a phantom `undefined` legend entry. In a layered spec every layer's rows flatten into the color-legend source, so a sibling layer (e.g. a diagonal reference-line) that doesn't carry the color field was seeding `String(undefined)` as a category — and with an explicit `scale.domain` it appended past the authored entries, breaking domain authority.

packages/engine/src/compile.ts

@@ -1364,6 +1364,25 @@ function compileFaceted(
   // Assign animation indices across all panels
   assignAnimationIndices(allMarks, resolvedAnimation);
 
+  // Rendering backend, resolved against the pooled panel marks. The canvas
+  // layer cannot express a facet grid, so this always answers 'svg' and never
+  // stamps the layout; it runs purely so the refusal is reported -- an explicit
+  // renderer: 'canvas' gets told it was ignored, and a dense facet grid gets
+  // told why it is painting every point as a DOM node.
+  const facetRenderModeWarnings: string[] = [];
+  resolveMarkRenderMode(
+    {
+      requested: options.renderer,
+      markType: chartSpec.markType,
+      pointCount: allMarks.reduce((n, m) => (m.type === 'point' ? n + 1 : n), 0),
+      display: chartSpec.display,
+      faceted: true,
+      layered: options.layered ?? false,
+    },
+    facetRenderModeWarnings,
+  );
+  emitSpecWarnings(facetRenderModeWarnings, options.onWarn);
+
   // Figure-level axes are null (axes live in panels)
   // Figure-level marks are the union of all panel marks (for tooltip/keyboard nav)
   return {

packages/engine/src/compiler/__tests__/mark-render-mode.test.ts

@@ -4,14 +4,19 @@
  * Pure function: it decides SVG vs canvas from the host's requested backend
  * (the `renderer` compile option), the mark type, the compiled point count,
  * and the chart shape (facet/layer/sparkline). Refusals collect a warning
- * string only when the host explicitly asked for canvas; the caller emits
- * them through emitSpecWarnings.
+ * string when the host explicitly asked for canvas, or when 'auto' wanted
+ * canvas for a chart dense enough that the SVG fallback is a real cost; the
+ * caller emits them through emitSpecWarnings.
  */
 
 import type { Display } from '@opendata-ai/openchart-core';
 import { describe, expect, it, vi } from 'vitest';
 import { compileChart } from '../../compile';
-import { AUTO_CANVAS_THRESHOLD, resolveMarkRenderMode } from '../mark-render-mode';
+import {
+  AUTO_CANVAS_REFUSAL_WARN_THRESHOLD,
+  AUTO_CANVAS_THRESHOLD,
+  resolveMarkRenderMode,
+} from '../mark-render-mode';
 
 /** Baseline args: a plain scatter with a huge point count. */
 function args(overrides: Partial<Parameters<typeof resolveMarkRenderMode>[0]> = {}) {
@@ -104,14 +109,75 @@ describe('resolveMarkRenderMode', () => {
     expect(warnings).toHaveLength(1);
   });
 
-  it('never warns on a refused shape when requested is auto or absent', () => {
+  it('stays quiet on a refused shape for auto or absent below the warn threshold', () => {
     const warnings: string[] = [];
-    resolveMarkRenderMode(args({ requested: 'auto', markType: 'bar' }), warnings);
-    resolveMarkRenderMode(args({ requested: undefined, markType: 'bar' }), warnings);
-    resolveMarkRenderMode(args({ requested: undefined, faceted: true }), warnings);
+    const quiet = { pointCount: AUTO_CANVAS_REFUSAL_WARN_THRESHOLD };
+    resolveMarkRenderMode(args({ ...quiet, requested: 'auto', markType: 'bar' }), warnings);
+    resolveMarkRenderMode(args({ ...quiet, requested: undefined, markType: 'bar' }), warnings);
+    resolveMarkRenderMode(args({ ...quiet, requested: undefined, faceted: true }), warnings);
     expect(warnings).toEqual([]);
   });
 
+  it('warns on an auto refusal once the chart is dense enough to hurt', () => {
+    const warnings: string[] = [];
+    expect(
+      resolveMarkRenderMode(
+        args({
+          requested: 'auto',
+          layered: true,
+          pointCount: AUTO_CANVAS_REFUSAL_WARN_THRESHOLD + 1,
+        }),
+        warnings,
+      ),
+    ).toBe('svg');
+    expect(warnings).toHaveLength(1);
+    // Names the count, the shape that refused, and stays on the [openchart] prefix.
+    expect(warnings[0]).toContain(String(AUTO_CANVAS_REFUSAL_WARN_THRESHOLD + 1));
+    expect(warnings[0]).toContain('layered');
+    expect(warnings[0]).toContain('[openchart]');
+  });
+
+  it('treats an absent requested value like auto for the dense refusal warning', () => {
+    const warnings: string[] = [];
+    resolveMarkRenderMode(
+      args({
+        requested: undefined,
+        faceted: true,
+        pointCount: AUTO_CANVAS_REFUSAL_WARN_THRESHOLD + 1,
+      }),
+      warnings,
+    );
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('faceted');
+  });
+
+  it('does not warn about density when the shape supports canvas', () => {
+    // A plain dense scatter is promoted, not refused: nothing to report.
+    const warnings: string[] = [];
+    expect(
+      resolveMarkRenderMode(
+        args({ requested: 'auto', pointCount: AUTO_CANVAS_REFUSAL_WARN_THRESHOLD + 1 }),
+        warnings,
+      ),
+    ).toBe('canvas');
+    expect(warnings).toEqual([]);
+  });
+
+  it('warns once, not twice, when an explicit canvas request is also dense', () => {
+    const warnings: string[] = [];
+    resolveMarkRenderMode(
+      args({
+        requested: 'canvas',
+        layered: true,
+        pointCount: AUTO_CANVAS_REFUSAL_WARN_THRESHOLD + 1,
+      }),
+      warnings,
+    );
+    expect(warnings).toHaveLength(1);
+    // The explicit-request phrasing wins; it already tells the author what to do.
+    expect(warnings[0]).toContain('is not supported');
+  });
+
   it('promotes auto to canvas above the threshold', () => {
     expect(
       resolveMarkRenderMode(args({ requested: 'auto', pointCount: AUTO_CANVAS_THRESHOLD + 1 })),
@@ -242,6 +308,50 @@ describe('compileChart markRenderMode', () => {
     }
   });
 
+  it('warns through onWarn when a dense faceted chart silently falls back to svg', () => {
+    // The case the warning exists for: the author asked for nothing, the chart
+    // is far too dense for SVG, and the facet shape is what refused canvas.
+    const onWarn = vi.fn();
+    const dense = Array.from({ length: AUTO_CANVAS_REFUSAL_WARN_THRESHOLD + 200 }, (_, i) => ({
+      x: i % 500,
+      y: i,
+      g: i % 2 === 0 ? 'a' : 'b',
+    }));
+    compileChart(
+      {
+        mark: 'point',
+        data: dense,
+        encoding: { ...SCATTER_ENCODING, facet: { field: 'g', type: 'nominal' as const } },
+        width: 600,
+        height: 400,
+      },
+      { width: 600, height: 400, onWarn },
+    );
+    const denseWarnings = onWarn.mock.calls.filter((c) =>
+      String(c[0]).includes('point marks as SVG'),
+    );
+    expect(denseWarnings).toHaveLength(1);
+    expect(String(denseWarnings[0][0])).toContain('faceted');
+  });
+
+  it('stays silent for a small faceted chart with no renderer requested', () => {
+    const onWarn = vi.fn();
+    compileChart(
+      {
+        mark: 'point',
+        data: SCATTER_DATA.map((row, i) => ({ ...row, g: i % 2 === 0 ? 'a' : 'b' })),
+        encoding: { ...SCATTER_ENCODING, facet: { field: 'g', type: 'nominal' as const } },
+        width: 600,
+        height: 400,
+      },
+      { width: 600, height: 400, onWarn },
+    );
+    const denseWarnings = onWarn.mock.calls.filter((c) =>
+      String(c[0]).includes('point marks as SVG'),
+    );
+    expect(denseWarnings).toEqual([]);
+  });
+
   it('warns on and strips the removed mark.render spec field', () => {
     const onWarn = vi.fn();
     const layout = compileChart(

packages/engine/src/compiler/mark-render-mode.ts

@@ -5,15 +5,27 @@
  * High-cardinality scatter plots are the only case where the trade is worth
  * it, so canvas is refused for every other mark type and for the layout shapes
  * the canvas layer cannot express (facets, layers, sparklines). Refusals are
- * advisory: they warn only when the author explicitly asked for canvas, never
- * for `'auto'`.
+ * advisory: an explicit `'canvas'` request always warns, and an `'auto'`
+ * refusal warns only once the chart is dense enough for the SVG fallback to
+ * actually hurt (AUTO_CANVAS_REFUSAL_WARN_THRESHOLD).
  */
 
 import type { Display } from '@opendata-ai/openchart-core';
 
 /** Point count above which `'auto'` prefers canvas over SVG. */
 export const AUTO_CANVAS_THRESHOLD = 1000;
 
+/**
+ * Point count above which an `'auto'` refusal is worth telling the author about.
+ *
+ * Set well clear of AUTO_CANVAS_THRESHOLD on purpose. A chart that trips the
+ * threshold by a little renders fine as SVG, and warning there would fire on
+ * ordinary faceted and layered charts that have nothing wrong with them. This
+ * is the "you are painting enough DOM nodes to feel it" line, so the advice is
+ * actionable rather than noise.
+ */
+export const AUTO_CANVAS_REFUSAL_WARN_THRESHOLD = 5000;
+
 /** Inputs to mark render mode resolution. */
 export interface MarkRenderModeArgs {
   /** The host's requested backend (`CompileOptions.renderer`), or undefined for `'auto'`. */
@@ -36,8 +48,9 @@ export interface MarkRenderModeArgs {
  * Precedence:
  * 1. Explicit `'svg'` wins outright.
  * 2. Unsupported shape (non-point mark, facet, layer, sparkline) falls back to
- *    SVG, pushing one warning onto `warnings` only when the author explicitly
- *    asked for canvas.
+ *    SVG, pushing one warning onto `warnings` when the author explicitly asked
+ *    for canvas, or when `'auto'` wanted canvas for a chart dense enough that
+ *    the SVG fallback is a real cost.
  * 3. Explicit `'canvas'` wins at any point count.
  * 4. `'auto'` (or absent) promotes to canvas above AUTO_CANVAS_THRESHOLD.
  *
@@ -59,6 +72,13 @@ export function resolveMarkRenderMode(
       warnings.push(
         `Chart warning: renderer "canvas" is not supported ${refusal}; rendering marks as SVG instead.`,
       );
+    } else if (pointCount > AUTO_CANVAS_REFUSAL_WARN_THRESHOLD) {
+      // The author asked for nothing and got the slow path. Without this the
+      // only symptom is a chart that feels heavy, with no hint that the shape
+      // (not the point count) is what kept it on SVG.
+      warnings.push(
+        `[openchart] Rendering ${pointCount} point marks as SVG: the canvas mark layer is not supported ${refusal}. Expect slow paint and interaction. Reduce the point count, or restructure so the dense marks compile as a single unlayered, unfaceted point chart.`,
+      );
     }
     return 'svg';
   }