@opendata-ai/openchart-engine 7.6.0 → 7.7.0

package/dist/index.js

@@ -1158,7 +1158,7 @@ function computeAnnotations(spec, scalesOrCtx, chartArea, strategy, isDark, obst
       measure: heuristicMeasure
     };
   }
-  const isCompact = ctx.strategy.annotationPosition === "tooltip-only";
+  const isCompact = ctx.strategy.annotationPosition === "tooltip-only" && !ctx.autoThin;
   const svgRect = { x: 0, y: 0, width: ctx.svg.width, height: ctx.svg.height };
   const annotations = [];
   const autoQueue = [];
@@ -1347,6 +1347,65 @@ function computeAnnotations(spec, scalesOrCtx, chartArea, strategy, isDark, obst
   return annotations;
 }
 
+// src/annotations/thinning.ts
+import { detectCollision as detectCollision2 } from "@opendata-ai/openchart-core";
+function thinAnnotations(annotations, specs, measure) {
+  if (annotations.length <= 1) {
+    return { annotations, footnotes: [] };
+  }
+  const entries = annotations.map((a, i) => ({
+    resolved: a,
+    spec: i < specs.length && specs[i].type === "text" ? specs[i] : void 0,
+    index: i
+  }));
+  const pinned = [];
+  const candidates = [];
+  for (const entry of entries) {
+    if (entry.resolved.type !== "text" || !entry.resolved.label) {
+      pinned.push(entry);
+    } else if (entry.spec?.responsive === false) {
+      pinned.push(entry);
+    } else {
+      candidates.push(entry);
+    }
+  }
+  candidates.sort((a, b) => {
+    const pa = a.spec?.priority ?? Number.MAX_SAFE_INTEGER;
+    const pb = b.spec?.priority ?? Number.MAX_SAFE_INTEGER;
+    if (pa !== pb) return pa - pb;
+    return a.index - b.index;
+  });
+  const placedBounds = [];
+  for (const entry of pinned) {
+    if (entry.resolved.type === "text" && entry.resolved.label) {
+      const bounds = entry.resolved.bounds ?? estimateLabelBounds(entry.resolved.label, measure);
+      placedBounds.push(bounds);
+    }
+  }
+  const footnotes = [];
+  for (const entry of candidates) {
+    const bounds = entry.resolved.bounds ?? estimateLabelBounds(entry.resolved.label, measure);
+    if (bounds.width <= 0 || bounds.height <= 0) {
+      placedBounds.push(bounds);
+      continue;
+    }
+    const overlaps = placedBounds.some(
+      (pb) => pb.width > 0 && pb.height > 0 && detectCollision2(bounds, pb)
+    );
+    if (overlaps) {
+      const footnoteIndex = footnotes.length + 1;
+      footnotes.push({
+        index: footnoteIndex,
+        text: entry.resolved.label.text
+      });
+      entry.resolved.footnoteIndex = footnoteIndex;
+    } else {
+      placedBounds.push(bounds);
+    }
+  }
+  return { annotations, footnotes };
+}
+
 // src/endpoint-labels/compute.ts
 import { estimateTextWidth as estimateTextWidth2, wrapText } from "@opendata-ai/openchart-core";
 
@@ -1359,13 +1418,14 @@ function legendShownExplicitly(spec) {
 function legendHiddenExplicitly(spec) {
   return spec.legend?.show === false;
 }
+var EP_CONFIG_ONLY_KEYS = /* @__PURE__ */ new Set(["show", "maxSeries"]);
 function endpointLabelsExplicitlyOn(spec) {
   const ep = spec.endpointLabels;
   if (ep === true) return true;
   if (ep === false || ep == null) return false;
   if (ep.show === true) return true;
   if (ep.show === false) return false;
-  return Object.keys(ep).some((k) => k !== "show");
+  return Object.keys(ep).some((k) => !EP_CONFIG_ONLY_KEYS.has(k));
 }
 function endpointLabelsExplicitlyOff(spec) {
   const ep = spec.endpointLabels;
@@ -1373,6 +1433,12 @@ function endpointLabelsExplicitlyOff(spec) {
   if (typeof ep === "object" && ep != null && ep.show === false) return true;
   return false;
 }
+var DEFAULT_MAX_SERIES = 8;
+function getMaxSeries(spec) {
+  const ep = spec.endpointLabels;
+  if (typeof ep === "object" && ep != null && ep.maxSeries != null) return ep.maxSeries;
+  return DEFAULT_MAX_SERIES;
+}
 function resolveSuppression(spec, ctx) {
   const isLineOrArea2 = spec.markType === "line" || spec.markType === "area";
   const hasColorEncoding = spec.encoding.color != null;
@@ -1398,7 +1464,9 @@ function resolveSuppression(spec, ctx) {
       showEndOfLineLabels: false
     };
   }
-  const epExplicitOff = endpointLabelsExplicitlyOff(spec);
+  const exceedsCutoff = !endpointLabelsExplicitlyOn(spec) && ctx.seriesCount > getMaxSeries(spec);
+  const demoted = !endpointLabelsExplicitlyOn(spec) && !!ctx.endpointLabelsDemoted;
+  const epExplicitOff = endpointLabelsExplicitlyOff(spec) || exceedsCutoff || demoted;
   const legShown = legendShownExplicitly(spec);
   const legHidden = legendHiddenExplicitly(spec);
   const showEndpointLabels = !epExplicitOff;
@@ -1717,7 +1785,8 @@ function emptyLayout(theme) {
     fontSize: ENDPOINT_VALUE_FONT_SIZE,
     fontWeight: ENDPOINT_VALUE_FONT_WEIGHT,
     fill: theme.colors.annotationText ?? theme.colors.text,
-    lineHeight: ENDPOINT_LINE_HEIGHT
+    lineHeight: ENDPOINT_LINE_HEIGHT,
+    fontVariant: "tabular-nums"
   };
   return {
     entries: [],
@@ -1748,6 +1817,21 @@ function lastDataPoint(mark) {
   }
   return null;
 }
+function firstDataPoint(mark) {
+  if (mark.dataPoints && mark.dataPoints.length > 0) {
+    const first = mark.dataPoints[0];
+    return { x: first.x, y: first.y };
+  }
+  if (mark.type === "line" && mark.points.length > 0) {
+    const first = mark.points[0];
+    return { x: first.x, y: first.y };
+  }
+  if (mark.type === "area" && mark.topPoints.length > 0) {
+    const first = mark.topPoints[0];
+    return { x: first.x, y: first.y };
+  }
+  return null;
+}
 function readValue(mark, valueField) {
   if (!valueField) return null;
   const dp = mark.dataPoints;
@@ -1762,6 +1846,20 @@ function readValue(mark, valueField) {
   }
   return null;
 }
+function readFirstValue(mark, valueField) {
+  if (!valueField) return null;
+  const dp = mark.dataPoints;
+  if (dp && dp.length > 0) {
+    const datum = dp[0].datum;
+    const v = datum[valueField];
+    return typeof v === "number" || typeof v === "string" ? v : null;
+  }
+  if (mark.data.length > 0) {
+    const v = mark.data[0][valueField];
+    return typeof v === "number" || typeof v === "string" ? v : null;
+  }
+  return null;
+}
 function bidirectionalSweep(entries, areaTop, areaBottom) {
   const n = entries.length;
   if (n === 0) return [];
@@ -1788,16 +1886,20 @@ function bidirectionalSweep(entries, areaTop, areaBottom) {
   }
   return result;
 }
-function computeEndpointLabels(spec, marks, theme, chartArea, strategy) {
+function computeEndpointLabels(spec, marks, theme, chartArea, strategy, endpointLabelsDemoted) {
   if (strategy?.labelMode === "none") return emptyLayout(theme);
+  const highlight = spec.highlight ?? [];
+  const highlightActive = highlight.length > 0;
   const seriesCount = countColorSeries(spec);
   const sup = resolveSuppression(spec, {
     seriesCount,
     // The 'none' branch above returned; by here labelMode is not 'none'.
     labelsHiddenByStrategy: false,
-    labelsDensityNone: spec.labels.density === "none"
+    labelsDensityNone: spec.labels.density === "none",
+    endpointLabelsDemoted
   });
-  if (!sup.showEndpointLabels) return emptyLayout(theme);
+  const epExplicitlyOff = spec.endpointLabels === false || typeof spec.endpointLabels === "object" && spec.endpointLabels?.show === false;
+  if (!sup.showEndpointLabels && !(highlightActive && !epExplicitlyOff)) return emptyLayout(theme);
   const bySeriesKey = /* @__PURE__ */ new Map();
   for (const mark of marks) {
     if (!isLineOrArea(mark) || !mark.seriesKey) continue;
@@ -1828,7 +1930,8 @@ function computeEndpointLabels(spec, marks, theme, chartArea, strategy) {
     fontSize: ENDPOINT_VALUE_FONT_SIZE,
     fontWeight: ENDPOINT_VALUE_FONT_WEIGHT,
     fill: theme.colors.annotationText ?? theme.colors.text,
-    lineHeight: ENDPOINT_LINE_HEIGHT
+    lineHeight: ENDPOINT_LINE_HEIGHT,
+    fontVariant: "tabular-nums"
   };
   const provisional = [];
   const labelLineHeight = ENDPOINT_LABEL_FONT_SIZE * ENDPOINT_LINE_HEIGHT;
@@ -1836,6 +1939,7 @@ function computeEndpointLabels(spec, marks, theme, chartArea, strategy) {
   for (const mark of lineOrAreaMarks) {
     const seriesKey = mark.seriesKey;
     if (!seriesKey) continue;
+    if (highlightActive && !highlight.includes(seriesKey)) continue;
     const last = lastDataPoint(mark);
     if (!last) continue;
     const labelLines = wrapText(
@@ -1868,7 +1972,8 @@ function computeEndpointLabels(spec, marks, theme, chartArea, strategy) {
       width: entryWidth
     });
   }
-  if (provisional.length < 2) return emptyLayout(theme);
+  if (provisional.length === 0) return emptyLayout(theme);
+  if (provisional.length < 2 && !highlightActive) return emptyLayout(theme);
   const sweepInput = provisional.map((p, i) => ({
     naturalTop: p.dataY - ENDPOINT_LABEL_FONT_SIZE / 2,
     height: p.height + ENDPOINT_ENTRY_GAP,
@@ -1907,6 +2012,97 @@ function computeEndpointLabels(spec, marks, theme, chartArea, strategy) {
     }
     return entry;
   });
+  const endsBoth = config?.ends === "both";
+  let leading;
+  let leadingBounds;
+  if (endsBoth) {
+    const leadingProvisional = [];
+    for (const mark of lineOrAreaMarks) {
+      const seriesKey = mark.seriesKey;
+      if (!seriesKey) continue;
+      if (highlightActive && !highlight.includes(seriesKey)) continue;
+      const first = firstDataPoint(mark);
+      if (!first) continue;
+      const labelLines = wrapText(
+        seriesKey,
+        ENDPOINT_LABEL_FONT_SIZE,
+        ENDPOINT_LABEL_FONT_WEIGHT,
+        wrapWidth
+      );
+      const rawValue = readFirstValue(mark, valueField);
+      const value2 = formatEndpointValue(rawValue, formatString);
+      let entryWidth = 0;
+      for (const line of labelLines) {
+        const w = estimateTextWidth2(line, ENDPOINT_LABEL_FONT_SIZE, ENDPOINT_LABEL_FONT_WEIGHT);
+        if (w > entryWidth) entryWidth = w;
+      }
+      const valueWidth = value2 ? estimateTextWidth2(value2, ENDPOINT_VALUE_FONT_SIZE, ENDPOINT_VALUE_FONT_WEIGHT) : 0;
+      if (valueWidth > entryWidth) entryWidth = valueWidth;
+      const labelHeight = labelLines.length * labelLineHeight;
+      const valueHeight = value2 ? valueLineHeight : 0;
+      const entryHeight = labelHeight + (value2 ? ENDPOINT_VALUE_GAP : 0) + valueHeight;
+      const color2 = mark.type === "line" ? mark.stroke : mark.stroke ?? (typeof mark.fill === "string" ? mark.fill : theme.colors.categorical[0]);
+      leadingProvisional.push({
+        seriesKey,
+        labelLines,
+        value: value2,
+        color: color2,
+        dataX: first.x,
+        dataY: first.y,
+        height: entryHeight,
+        width: entryWidth
+      });
+    }
+    if (leadingProvisional.length >= 2 || leadingProvisional.length === 1 && highlightActive) {
+      const leadingSweepInput = leadingProvisional.map((p, i) => ({
+        naturalTop: p.dataY - ENDPOINT_LABEL_FONT_SIZE / 2,
+        height: p.height + ENDPOINT_ENTRY_GAP,
+        index: i
+      }));
+      const leadingSweptTops = bidirectionalSweep(
+        leadingSweepInput,
+        chartArea.y,
+        chartArea.y + chartArea.height
+      );
+      const leadingColumnWidth = Math.max(
+        ENDPOINT_SWATCH_SIZE + ENDPOINT_GAP + Math.max(...leadingProvisional.map((p) => p.width), 0) + 4,
+        32
+      );
+      const leadingColumnX = chartArea.x - ENDPOINT_COLUMN_GAP - leadingColumnWidth;
+      leading = leadingProvisional.map((p, i) => {
+        const labelY = leadingSweptTops[i];
+        const swatchRowY = labelY + ENDPOINT_LABEL_FONT_SIZE / 2;
+        const displaced = Math.abs(swatchRowY - p.dataY) > ENDPOINT_LEADER_THRESHOLD;
+        const entry = {
+          seriesKey: p.seriesKey,
+          labelLines: p.labelLines,
+          value: p.value,
+          color: p.color,
+          dataY: p.dataY,
+          labelY,
+          showLeader: showLeader && displaced
+        };
+        if (showMarker) {
+          entry.marker = {
+            x: p.dataX - markerRadius,
+            y: p.dataY,
+            dataX: p.dataX,
+            fill: markerFill,
+            stroke: config?.markerStyle?.stroke ?? p.color,
+            strokeWidth: markerStrokeWidth,
+            radius: markerRadius
+          };
+        }
+        return entry;
+      });
+      leadingBounds = {
+        x: leadingColumnX,
+        y: chartArea.y,
+        width: leadingColumnWidth,
+        height: chartArea.height
+      };
+    }
+  }
   return {
     entries,
     bounds: {
@@ -1920,7 +2116,9 @@ function computeEndpointLabels(spec, marks, theme, chartArea, strategy) {
     swatchSize: ENDPOINT_SWATCH_SIZE,
     gap: ENDPOINT_GAP,
     valueGap: ENDPOINT_VALUE_GAP,
-    swatchChipFill: theme.colors.annotationFill ?? theme.colors.background
+    swatchChipFill: theme.colors.annotationFill ?? theme.colors.background,
+    leading,
+    leadingBounds
   };
 }
 
@@ -2512,7 +2710,8 @@ function computeBarLabels(marks, _chartArea, density = "auto", labelFormat, labe
         fill,
         lineHeight: 1.2,
         textAnchor,
-        dominantBaseline: "central"
+        dominantBaseline: "central",
+        fontVariant: "tabular-nums"
       }
     });
   }
@@ -2935,7 +3134,8 @@ function computeColumnLabels(marks, _chartArea, density = "auto", labelFormat, l
         fontWeight: LABEL_FONT_WEIGHT2,
         fill: labelColor ?? getRepresentativeColor2(mark.fill),
         lineHeight: 1.2,
-        textAnchor: "middle"
+        textAnchor: "middle",
+        fontVariant: "tabular-nums"
       }
     });
   }
@@ -3174,7 +3374,8 @@ function computeDotLabels(marks, _chartArea, density = "auto", labelPrefix, labe
         fill: getRepresentativeColor3(mark.fill),
         lineHeight: 1.2,
         textAnchor: "start",
-        dominantBaseline: "central"
+        dominantBaseline: "central",
+        fontVariant: "tabular-nums"
       }
     });
   }
@@ -4363,10 +4564,23 @@ function computeStackedArea(spec, scales, chartArea, darkMode) {
 function computeAreaMarks(spec, scales, chartArea, darkMode) {
   const encoding = spec.encoding;
   const yChannel = encoding.y;
+  let marks;
   if (yChannel && isStacked(yChannel.stack)) {
-    return computeStackedArea(spec, scales, chartArea, darkMode);
+    marks = computeStackedArea(spec, scales, chartArea, darkMode);
+  } else {
+    marks = computeSingleArea(spec, scales, chartArea);
+  }
+  const highlight = spec.highlight ?? [];
+  if (highlight.length > 0) {
+    const highlightSet = new Set(highlight);
+    marks.sort((a, b) => {
+      const aMuted = a.seriesKey != null && !highlightSet.has(a.seriesKey);
+      const bMuted = b.seriesKey != null && !highlightSet.has(b.seriesKey);
+      if (aMuted === bMuted) return 0;
+      return aMuted ? -1 : 1;
+    });
   }
-  return computeSingleArea(spec, scales, chartArea);
+  return marks;
 }
 
 // src/charts/line/compute.ts
@@ -4385,7 +4599,10 @@ function computeLineMarks(spec, scales, _chartArea, _strategy) {
   const colorField = isSequentialColor ? void 0 : colorEnc?.field;
   const sequentialColorField = isSequentialColor ? colorEnc.field : void 0;
   const groups = groupByField(spec.data, colorField);
-  const marks = [];
+  const mutedMarks = [];
+  const highlightedMarks = [];
+  const highlight = spec.highlight ?? [];
+  const highlightActive = highlight.length > 0;
   for (const [seriesKey, rows] of groups) {
     const color2 = isSequentialColor ? getSequentialColor(scales, _getMidValue(rows, sequentialColorField)) : getColor(scales, seriesKey);
     const strokeColor = spec.markDef.stroke ?? getRepresentativeColor5(color2);
@@ -4430,6 +4647,11 @@ function computeLineMarks(spec, scales, _chartArea, _strategy) {
     const combinedPath = pathParts.join(" ");
     const seriesStyleKey = seriesKey === "__default__" ? void 0 : seriesKey;
     const styleOverride = seriesStyleKey ? spec.seriesStyles?.[seriesStyleKey] : void 0;
+    const isMuted = highlightActive && !highlight.includes(seriesKey);
+    let resolvedStrokeWidth = styleOverride?.strokeWidth ?? spec.markDef.strokeWidth ?? DEFAULT_STROKE_WIDTH;
+    if (isMuted) {
+      resolvedStrokeWidth = Math.max(1, resolvedStrokeWidth * 0.75);
+    }
     let strokeDasharray;
     if (styleOverride?.lineStyle === "dashed") strokeDasharray = "6 4";
     else if (styleOverride?.lineStyle === "dotted") strokeDasharray = "2 3";
@@ -4438,7 +4660,7 @@ function computeLineMarks(spec, scales, _chartArea, _strategy) {
       points: allPoints,
       path: combinedPath,
       stroke: strokeColor,
-      strokeWidth: styleOverride?.strokeWidth ?? spec.markDef.strokeWidth ?? DEFAULT_STROKE_WIDTH,
+      strokeWidth: resolvedStrokeWidth,
       strokeDasharray,
       opacity: styleOverride?.opacity,
       seriesKey: seriesStyleKey,
@@ -4446,7 +4668,8 @@ function computeLineMarks(spec, scales, _chartArea, _strategy) {
       dataPoints: pointsWithData.map((p) => ({ x: p.x, y: p.y, datum: p.row })),
       aria
     };
-    marks.push(lineMark);
+    const bucket = isMuted ? mutedMarks : highlightedMarks;
+    bucket.push(lineMark);
     const markPoint = spec.markDef.point;
     const isSingleEndpoint = markPoint === "last" || markPoint === "first";
     const showPoints = markPoint === true || markPoint === "transparent" || markPoint === "endpoints" || isSingleEndpoint || isSequentialColor;
@@ -4473,20 +4696,16 @@ function computeLineMarks(spec, scales, _chartArea, _strategy) {
         const hollow = isEndpoints && visible;
         const pointColorStr = getRepresentativeColor5(pointColor);
         if (isSingleEndpoint) {
-          marks.push({
+          bucket.push({
             type: "point",
             cx: p.x,
             cy: p.y,
-            // 3.5 reads as a deliberate terminator against the 2px sparkline
-            // line — smaller dots blur into the stroke at typical card sizes.
             r: 3.5,
             fill: strokeColor,
             stroke: "transparent",
             strokeWidth: 0,
             fillOpacity: 1,
             data: p.row,
-            // No label: decorative marks render with aria-hidden="true" and
-            // don't participate in the accessible data table.
             aria: { decorative: true }
           });
           continue;
@@ -4505,11 +4724,11 @@ function computeLineMarks(spec, scales, _chartArea, _strategy) {
             label: `Data point: ${xChannel.field}=${String(p.row[xChannel.field])}, ${yChannel.field}=${String(p.row[yChannel.field])}`
           }
         };
-        marks.push(pointMark);
+        bucket.push(pointMark);
       }
     }
   }
-  return marks;
+  return [...mutedMarks, ...highlightedMarks];
 }
 function _getMidValue(rows, field) {
   const values = rows.map((r) => Number(r[field])).filter(Number.isFinite);
@@ -4853,7 +5072,8 @@ function computePieLabels(marks, _chartArea, density = "auto", _textFill = "#333
         fill: _textFill,
         lineHeight: 1.2,
         textAnchor: isRight ? "start" : "end",
-        dominantBaseline: "central"
+        dominantBaseline: "central",
+        fontVariant: "tabular-nums"
       }
     });
     targetMarkIndices.push(mi);
@@ -8007,6 +8227,30 @@ function normalizeLabels(labels) {
     fontSize: labels.fontSize
   };
 }
+function normalizeHighlight(encoding, data, warnings) {
+  const color2 = encoding.color;
+  if (!color2 || !("field" in color2)) return [];
+  const raw = color2.highlight;
+  if (raw == null) return [];
+  const highlight = Array.isArray(raw) ? raw : [raw];
+  if (highlight.length > 0 && data.length > 0) {
+    const colorField = color2.field;
+    const knownValues = new Set(data.map((row) => String(row[colorField])));
+    for (const v of highlight) {
+      if (!knownValues.has(v)) {
+        warnings.push(
+          `[openchart] encoding.color.highlight value "${v}" does not match any value in the "${colorField}" data column`
+        );
+      }
+    }
+  }
+  if (highlight.length > 0 && color2.scale?.range) {
+    warnings.push(
+      "[openchart] encoding.color.highlight has no effect on color assignment when encoding.color.scale.range is explicitly provided"
+    );
+  }
+  return highlight;
+}
 function normalizeChartSpec(spec, warnings) {
   const encoding = inferEncodingTypes(spec.encoding, spec.data, warnings);
   const markType = resolveMarkType(spec.mark);
@@ -8028,13 +8272,16 @@ function normalizeChartSpec(spec, warnings) {
     labels: normalizeLabels(spec.labels),
     legend: spec.legend,
     endpointLabels: spec.endpointLabels,
-    responsive: spec.responsive ?? true,
+    responsive: typeof spec.responsive === "object" ? true : spec.responsive ?? true,
+    autoThin: typeof spec.responsive === "object" ? spec.responsive.autoThin ?? true : spec.responsive ?? true,
     theme: spec.theme ?? {},
     darkMode: spec.darkMode ?? "off",
     hiddenSeries: spec.hiddenSeries ?? [],
     seriesStyles: spec.seriesStyles ?? {},
     watermark: spec.watermark ?? true,
+    highlight: normalizeHighlight(encoding, spec.data, warnings),
     display,
+    resolve: spec.resolve,
     // Default empty userExplicit; compileChart overwrites this with the real
     // descriptor built from the raw expanded spec before normalize runs.
     userExplicit: {
@@ -8119,13 +8366,26 @@ function normalizeTileMapSpec(spec, warnings) {
   if (!Array.isArray(spec.data)) {
     data = Object.entries(spec.data).map(([state, value2]) => ({ state, value: value2 }));
   }
+  const hasStringValues = !Array.isArray(spec.data) && Object.values(spec.data).some((v) => typeof v === "string");
+  const isCategorical = spec.colors !== void 0 || spec.encoding?.color !== void 0 || hasStringValues;
+  if (hasStringValues && !Array.isArray(spec.data)) {
+    const hasNumericValues = Object.values(spec.data).some((v) => typeof v === "number");
+    if (hasNumericValues) {
+      warnings.push(
+        "TileMap data: record map contains mixed number and string values. Treating as categorical. Use all numbers for quantitative or all strings for categorical."
+      );
+    }
+  }
   let encoding = spec.encoding;
   if (!encoding) {
     encoding = {
       state: { field: "state", type: "nominal" },
-      value: { field: "value", type: "quantitative" }
+      value: { field: "value", type: isCategorical ? "nominal" : "quantitative" }
     };
   }
+  if (isCategorical && !encoding.color) {
+    encoding = { ...encoding, color: encoding.value };
+  }
   let matchedCount = 0;
   for (const row of data) {
     const stateCode = String(row[encoding.state.field]);
@@ -8144,6 +8404,7 @@ function normalizeTileMapSpec(spec, warnings) {
     data,
     encoding,
     palette: spec.palette ?? "blue",
+    colors: spec.colors,
     chrome: normalizeChrome(spec.chrome),
     legend: spec.legend,
     theme: spec.theme ?? {},
@@ -8238,6 +8499,7 @@ function flattenLayers(spec, parentData, parentEncoding, parentTransforms, paren
 
 // src/compiler/validate.ts
 import {
+  inferFieldType as inferFieldType2,
   MARK_ENCODING_RULES,
   MARK_TYPES
 } from "@opendata-ai/openchart-core";
@@ -8440,6 +8702,68 @@ function validateChartSpec(spec, errors) {
       }
     }
   }
+  if (encoding) {
+    const colorCh = encoding.color;
+    if (colorCh && colorCh.highlight != null) {
+      const hlVal = colorCh.highlight;
+      const isValidType = typeof hlVal === "string" || Array.isArray(hlVal) && hlVal.every((v) => typeof v === "string");
+      if (!isValidType) {
+        errors.push({
+          message: "Spec error: encoding.color.highlight must be a string or array of strings",
+          path: "encoding.color.highlight",
+          code: "INVALID_TYPE",
+          suggestion: "Provide a series name (string) or an array of series names."
+        });
+      } else {
+        const colorType = colorCh.type ?? (colorCh.field && Array.isArray(spec.data) && spec.data.length > 0 ? inferFieldType2(spec.data, colorCh.field) : void 0);
+        if (colorType === "quantitative") {
+          errors.push({
+            message: "Spec error: encoding.color.highlight is not supported on quantitative color channels",
+            path: "encoding.color.highlight",
+            code: "INVALID_VALUE",
+            suggestion: "Highlight works with nominal/ordinal color (categorical series). Remove highlight or change encoding.color.type to nominal."
+          });
+        }
+      }
+    }
+  }
+  if (encoding.facet && typeof encoding.facet === "object") {
+    const facet = encoding.facet;
+    if (!facet.field || typeof facet.field !== "string") {
+      errors.push({
+        message: "Spec error: encoding.facet.field is required and must be a non-empty string",
+        path: "encoding.facet.field",
+        code: "MISSING_FIELD",
+        suggestion: 'Add a field property to encoding.facet (e.g. { field: "category", type: "nominal" })'
+      });
+    } else if (!dataColumns.has(facet.field) && !transformFields.has(facet.field)) {
+      errors.push({
+        message: `Spec error: encoding.facet.field "${facet.field}" does not exist in data. Available columns: ${availableColumns}`,
+        path: "encoding.facet.field",
+        code: "DATA_FIELD_MISSING",
+        suggestion: `Use one of the available data columns: ${availableColumns}`
+      });
+    }
+    if (!facet.type || facet.type !== "nominal" && facet.type !== "ordinal") {
+      errors.push({
+        message: `Spec error: encoding.facet.type must be "nominal" or "ordinal"${facet.type ? `, got "${facet.type}"` : ""}`,
+        path: "encoding.facet.type",
+        code: facet.type ? "INVALID_VALUE" : "MISSING_FIELD",
+        suggestion: 'Set encoding.facet.type to "nominal" or "ordinal"'
+      });
+    }
+    if (facet.columns !== void 0) {
+      const cols = Number(facet.columns);
+      if (!Number.isInteger(cols) || cols < 1) {
+        errors.push({
+          message: "Spec error: encoding.facet.columns must be a positive integer",
+          path: "encoding.facet.columns",
+          code: "INVALID_VALUE",
+          suggestion: "Set columns to a positive integer (e.g. 3)"
+        });
+      }
+    }
+  }
   if (spec.darkMode !== void 0 && !VALID_DARK_MODES.has(spec.darkMode)) {
     errors.push({
       message: `Spec error: darkMode must be "auto", "force", or "off"`,
@@ -9262,7 +9586,8 @@ function compileBarList(spec, options) {
       fontSize: VALUE_FONT_SIZE,
       fontWeight: VALUE_FONT_WEIGHT,
       fill: valueColor,
-      lineHeight: 1.4
+      lineHeight: 1.4,
+      fontVariant: "tabular-nums"
     };
     const rowMark = {
       type: "barlist-row",
@@ -9507,7 +9832,9 @@ function assignAnimationIndices(marks, animation) {
 }
 
 // src/compile/color-scale-range.ts
-function applyColorScaleRange(scales, encoding, theme) {
+import { ACHROMATIC_RAMP } from "@opendata-ai/openchart-core";
+var MUTED_COLOR = "#bfc3c8";
+function applyColorScaleRange(scales, encoding, theme, highlight) {
   if (!scales.color) return;
   const hasExplicitRange = !!(encoding.color && "field" in encoding.color && encoding.color.scale?.range?.length);
   if (hasExplicitRange) return;
@@ -9518,7 +9845,34 @@ function applyColorScaleRange(scales, encoding, theme) {
       seqStops[seqStops.length - 1]
     ]);
   } else {
-    scales.color.scale.range(theme.colors.categorical);
+    const ordinalScale = scales.color.scale;
+    const palette = theme.colors.categorical;
+    const domain = ordinalScale.domain();
+    if (highlight && highlight.length > 0) {
+      const highlightSet = new Set(highlight);
+      const colors = domain.map(
+        (v, i) => highlightSet.has(v) ? palette[i % palette.length] : MUTED_COLOR
+      );
+      ordinalScale.range(colors);
+    } else {
+      const strategy = theme.seriesStrategy ?? "palette";
+      if (strategy !== "accent-neutral") {
+        ordinalScale.range(palette);
+      } else {
+        const count = domain.length;
+        if (count <= 1) {
+          ordinalScale.range([palette[0]]);
+        } else if (count <= 4) {
+          const neutrals = theme.isDark ? [ACHROMATIC_RAMP.fgMuted, ACHROMATIC_RAMP.fgSubtle, ACHROMATIC_RAMP.fgFaint] : [ACHROMATIC_RAMP.fgFaint, ACHROMATIC_RAMP.fgSubtle, ACHROMATIC_RAMP.fgMuted];
+          const colors = domain.map(
+            (_, i) => i === 0 ? palette[0] : neutrals[(i - 1) % neutrals.length]
+          );
+          ordinalScale.range(colors);
+        } else {
+          ordinalScale.range(palette);
+        }
+      }
+    }
   }
 }
 
@@ -9546,7 +9900,7 @@ import {
   AXIS_TITLE_TRAILING_PAD as AXIS_TITLE_TRAILING_PAD2,
   abbreviateNumber as abbreviateNumber4,
   BREAKPOINT_COMPACT_MAX as BREAKPOINT_COMPACT_MAX2,
-  estimateTextWidth as estimateTextWidth12,
+  estimateTextWidth as estimateTextWidth13,
   formatNumber as formatNumber5,
   getAxisTitleOffset,
   resolveTheme as resolveTheme2,
@@ -9561,7 +9915,7 @@ import {
   BREAKPOINT_COMPACT_MAX,
   computeChrome as computeChrome2,
   computeXAxisExtentFromLabels,
-  estimateTextWidth as estimateTextWidth11,
+  estimateTextWidth as estimateTextWidth12,
   formatNumber as formatNumber4,
   HPAD_COMPACT_FRACTION,
   HPAD_COMPACT_MIN,
@@ -9575,11 +9929,66 @@ import {
   TOP_PAD_EXTRA_NARROW
 } from "@opendata-ai/openchart-core";
 
+// src/endpoint-labels/predict.ts
+import { estimateTextWidth as estimateTextWidth9, wrapText as wrapText2 } from "@opendata-ai/openchart-core";
+function predictEndpointLabelsWidth(spec, _theme) {
+  if (spec.endpointLabels === false) return 0;
+  if (spec.markType !== "line" && spec.markType !== "area") return 0;
+  const colorEnc = spec.encoding.color;
+  if (!colorEnc) return 0;
+  if ("condition" in colorEnc) return 0;
+  if (colorEnc.type === "quantitative") return 0;
+  const colorField = "field" in colorEnc ? colorEnc.field : void 0;
+  if (!colorField) return 0;
+  const seriesNames = /* @__PURE__ */ new Set();
+  for (const row of spec.data) {
+    seriesNames.add(String(row[colorField]));
+  }
+  if (seriesNames.size < 2) return 0;
+  if (typeof spec.endpointLabels === "object" && spec.endpointLabels?.show === false) return 0;
+  const maxSeries = typeof spec.endpointLabels === "object" && spec.endpointLabels?.maxSeries || 8;
+  if (!endpointLabelsExplicitlyOn(spec) && seriesNames.size > maxSeries) return 0;
+  const config = typeof spec.endpointLabels === "object" ? spec.endpointLabels : void 0;
+  const wrapWidth = config?.width ?? ENDPOINT_WRAP_WIDTH_DEFAULT;
+  let maxLabelWidth = 0;
+  for (const name of seriesNames) {
+    const lines = wrapText2(name, ENDPOINT_LABEL_FONT_SIZE, ENDPOINT_LABEL_FONT_WEIGHT, wrapWidth);
+    for (const line of lines) {
+      const w = estimateTextWidth9(line, ENDPOINT_LABEL_FONT_SIZE, ENDPOINT_LABEL_FONT_WEIGHT);
+      if (w > maxLabelWidth) maxLabelWidth = w;
+    }
+  }
+  const yField = config?.valueField ?? spec.encoding.y?.field;
+  const yFormat = config?.format ?? spec.encoding.y?.axis?.format;
+  let valueWidth = 0;
+  if (yField) {
+    let maxAbs = 0;
+    for (const row of spec.data) {
+      const v = Number(row[yField]);
+      if (Number.isFinite(v) && Math.abs(v) > maxAbs) maxAbs = Math.abs(v);
+    }
+    let sample;
+    if (yFormat) {
+      sample = formatEndpointValue(maxAbs, yFormat);
+    } else if (maxAbs >= 1e9) sample = "1.5B";
+    else if (maxAbs >= 1e6) sample = "1.5M";
+    else if (maxAbs >= 1e3) sample = "1.5K";
+    else sample = String(Math.round(maxAbs * 100) / 100);
+    valueWidth = estimateTextWidth9(sample, ENDPOINT_VALUE_FONT_SIZE, ENDPOINT_VALUE_FONT_WEIGHT);
+  }
+  const textColumn = Math.max(maxLabelWidth, valueWidth);
+  return ENDPOINT_SWATCH_SIZE + ENDPOINT_GAP + textColumn + 4;
+}
+function isEndsBoth(spec) {
+  const ep = spec.endpointLabels;
+  return typeof ep === "object" && ep != null && ep.ends === "both";
+}
+
 // src/legend/compute.ts
-import { BRAND_RESERVE_WIDTH, COMPACT_WIDTH as COMPACT_WIDTH2, estimateTextWidth as estimateTextWidth10 } from "@opendata-ai/openchart-core";
+import { BRAND_RESERVE_WIDTH, COMPACT_WIDTH as COMPACT_WIDTH2, estimateTextWidth as estimateTextWidth11 } from "@opendata-ai/openchart-core";
 
 // src/legend/wrap.ts
-import { COMPACT_WIDTH, estimateTextWidth as estimateTextWidth9 } from "@opendata-ai/openchart-core";
+import { COMPACT_WIDTH, estimateTextWidth as estimateTextWidth10 } from "@opendata-ai/openchart-core";
 var SWATCH_SIZE = 12;
 var SWATCH_GAP = 6;
 var ENTRY_GAP = 16;
@@ -9592,7 +10001,7 @@ function measureLegendWrap(entries, maxWidth, labelStyle, maxRows, entryGap = EN
   if (entries.length === 0) {
     return { rowCount: 0, fittingCount: 0, rowWidths: [], placements: [] };
   }
-  const measureWidth = measure ?? estimateTextWidth9;
+  const measureWidth = measure ?? estimateTextWidth10;
   let rowCount = 1;
   let rowWidth = 0;
   const rowWidths = [];
@@ -9721,8 +10130,8 @@ function emptyContent(position, theme) {
     ...categoricalDefaults(theme)
   };
 }
-function computeLegendContent(spec, strategy, theme, availableWidth, availableHeight, watermark = true, measure) {
-  const measureWidth = measure ?? estimateTextWidth10;
+function computeLegendContent(spec, strategy, theme, availableWidth, availableHeight, watermark = true, measure, endpointLabelsDemoted) {
+  const measureWidth = measure ?? estimateTextWidth11;
   const sparklineHidden = spec.display === "sparkline" && !spec.userExplicit.legend;
   if (sparklineHidden || spec.legend?.show === false || strategy.legendMaxHeight === 0) {
     return emptyContent("top", theme);
@@ -9732,11 +10141,23 @@ function computeLegendContent(spec, strategy, theme, availableWidth, availableHe
   const suppression = resolveSuppression(spec, {
     seriesCount,
     labelsHiddenByStrategy: strategy.labelMode === "none",
-    labelsDensityNone: spec.labels.density === "none"
+    labelsDensityNone: spec.labels.density === "none",
+    endpointLabelsDemoted
   });
   if (!suppression.showTraditionalLegend) {
     entries = [];
   }
+  const hasRedundantLegend = spec.markType === "bar" || spec.markType === "lollipop";
+  if (hasRedundantLegend && entries.length > 0 && !spec.userExplicit?.legend) {
+    const colorEnc = spec.encoding.color;
+    const colorField = colorEnc && "field" in colorEnc ? colorEnc.field : void 0;
+    if (colorField) {
+      const categoryField = spec.encoding.y?.type === "quantitative" ? spec.encoding.x?.field : spec.encoding.y?.field;
+      if (colorField === categoryField) {
+        entries = [];
+      }
+    }
+  }
   const labelStyle = {
     fontFamily: theme.fonts.family,
     fontSize: theme.fonts.sizes.small,
@@ -10611,7 +11032,7 @@ function createMeasureFn(measureText) {
   if (measureText) {
     return (text, fontSize, fontWeight) => measureText(text, fontSize, fontWeight).width;
   }
-  return estimateTextWidth11;
+  return estimateTextWidth12;
 }
 function sampleLabelFromMagnitude(maxAbsVal) {
   return maxAbsVal >= 1e3 ? abbreviateNumber3(maxAbsVal) : formatNumber4(maxAbsVal);
@@ -10743,6 +11164,14 @@ function resolveLayoutPlan(chartSpec, renderSpec, options, theme, strategy, wate
   }
   let prev = null;
   let finalPlan = null;
+  const MAX_ENDPOINT_FRACTION = 0.3;
+  let endpointLabelsDemoted = false;
+  if (chartSpec.autoThin) {
+    const epWidth = predictEndpointLabelsWidth(chartSpec, theme);
+    if (epWidth > 0 && epWidth / width > MAX_ENDPOINT_FRACTION) {
+      endpointLabelsDemoted = true;
+    }
+  }
   for (let iter = 0; iter < 2; iter++) {
     const legendAvailWidth = width - padding - leftGutter;
     const legendContent = computeLegendContent(
@@ -10752,7 +11181,8 @@ function resolveLayoutPlan(chartSpec, renderSpec, options, theme, strategy, wate
       legendAvailWidth,
       height,
       watermark,
-      measure
+      measure,
+      endpointLabelsDemoted
     );
     const bottomLegendReservation = legendContent.entries.length > 0 && legendContent.position === "bottom" ? legendContent.height + legendGap(width) : 0;
     const chrome = computeChrome2(
@@ -10938,7 +11368,8 @@ function resolveLayoutPlan(chartSpec, renderSpec, options, theme, strategy, wate
         yTickValues,
         yTickCount,
         converged: prev === null || converged,
-        inlineYLabelInset
+        inlineYLabelInset,
+        endpointLabelsDemoted
       };
       break;
     }
@@ -10976,8 +11407,14 @@ function compileLayer(spec, options, compileChart2) {
     zIndex: leaf.zIndex ?? i
   }));
   indexedLeaves.sort((a, b) => a.zIndex - b.zIndex);
+  const leafOptions = { ...options, frozenChartArea: primaryLayout.area };
   for (const { leaf } of indexedLeaves) {
-    const leafLayout = compileChart2(leaf, options);
+    const themedLeaf = {
+      ...leaf,
+      theme: leaf.theme ?? spec.theme,
+      darkMode: leaf.darkMode ?? spec.darkMode
+    };
+    const leafLayout = compileChart2(themedLeaf, leafOptions);
     allMarks.push(...leafLayout.marks);
     const leafLeg = leafLayout.legend;
     if ("entries" in leafLeg) {
@@ -11003,7 +11440,7 @@ function estimateYAxisLabelWidth(data, encoding, baseFontSize, measure) {
   const yEnc = encoding.y;
   const yField = yEnc.field;
   if (!yField) return 40;
-  const m = measure ?? estimateTextWidth12;
+  const m = measure ?? estimateTextWidth13;
   const yType = yEnc.type;
   if (yType === "nominal" || yType === "ordinal") {
     let maxWidth = 0;
@@ -11802,17 +12239,17 @@ var DEFAULT_COLLISION_PADDING = 5;
 import {
   axisTitleOffset as axisTitleOffset2,
   computeXAxisExtentFromLabels as computeXAxisExtentFromLabels2,
-  estimateTextWidth as estimateTextWidth14,
+  estimateTextWidth as estimateTextWidth15,
   getAxisTitleOffset as getAxisTitleOffset2,
   X_AXIS_TITLE_BAND_ROTATED
 } from "@opendata-ai/openchart-core";
 
 // src/layout/axes/thinning.ts
-import { estimateTextWidth as estimateTextWidth13 } from "@opendata-ai/openchart-core";
+import { estimateTextWidth as estimateTextWidth14 } from "@opendata-ai/openchart-core";
 var MIN_TICK_GAP_FACTOR = 0.5;
 var MIN_TICK_COUNT = 2;
 function measureLabel(text, fontSize, fontWeight, measureText) {
-  return measureText ? measureText(text, fontSize, fontWeight).width : estimateTextWidth13(text, fontSize, fontWeight);
+  return measureText ? measureText(text, fontSize, fontWeight).width : estimateTextWidth14(text, fontSize, fontWeight);
 }
 function ticksOverlap(ticks2, fontSize, fontWeight, measureText, orientation = "horizontal") {
   if (ticks2.length < 2) return false;
@@ -11857,6 +12294,7 @@ var HEIGHT_REDUCED_THRESHOLD = 100;
 var WIDTH_MINIMAL_THRESHOLD = 150;
 var WIDTH_REDUCED_THRESHOLD = 300;
 var DENSITY_ORDER = ["full", "reduced", "minimal"];
+var GROUNDED_MARKS = /* @__PURE__ */ new Set(["bar", "tick", "lollipop"]);
 function effectiveDensity(baseDensity, axisLength, minimalThreshold, reducedThreshold) {
   let density = baseDensity;
   if (axisLength < minimalThreshold) {
@@ -12021,9 +12459,10 @@ function computeAxes(scales, chartArea, strategy, theme, measureText, dataContex
     const axisTitle = axisConfig?.title;
     const xLabelColor = axisConfig?.labelColor;
     const xTickPosition = axisConfig?.tickPosition ?? "gutter";
+    const xDomainLine = axisConfig?.domain ?? (GROUNDED_MARKS.has(dataContext?.markType ?? "") ? void 0 : false);
     result.x = {
       ticks: ticks2,
-      gridlines: axisConfig?.grid ? gridlines : [],
+      gridlines: axisConfig?.grid ?? dataContext?.markType === "point" ? gridlines : [],
       label: axisTitle,
       labelStyle: xLabelColor ? { ...axisLabelStyle, fill: xLabelColor } : axisLabelStyle,
       tickLabelStyle: xLabelColor ? { ...tickLabelStyle, fill: xLabelColor } : tickLabelStyle,
@@ -12031,7 +12470,7 @@ function computeAxes(scales, chartArea, strategy, theme, measureText, dataContex
       start: { x: chartArea.x, y: chartArea.y + chartArea.height },
       end: { x: chartArea.x + chartArea.width, y: chartArea.y + chartArea.height },
       orient: axisConfig?.orient,
-      domainLine: axisConfig?.domain,
+      domainLine: xDomainLine,
       tickMarks: axisConfig?.ticks,
       offset: axisConfig?.offset,
       titlePadding: axisConfig?.titlePadding,
@@ -12144,7 +12583,7 @@ function computeAxes(scales, chartArea, strategy, theme, measureText, dataContex
       };
     } else {
       const maxTickLabelWidth = result.y.ticks.reduce((max4, t) => {
-        const w = estimateTextWidth14(
+        const w = estimateTextWidth15(
           t.label,
           result.y.tickLabelStyle.fontSize,
           result.y.tickLabelStyle.fontWeight ?? 400
@@ -12181,55 +12620,6 @@ import {
   TOP_PAD_EXTRA_NARROW as TOP_PAD_EXTRA_NARROW2
 } from "@opendata-ai/openchart-core";
 
-// src/endpoint-labels/predict.ts
-import { estimateTextWidth as estimateTextWidth15, wrapText as wrapText2 } from "@opendata-ai/openchart-core";
-function predictEndpointLabelsWidth(spec, _theme) {
-  if (spec.endpointLabels === false) return 0;
-  if (spec.markType !== "line" && spec.markType !== "area") return 0;
-  const colorEnc = spec.encoding.color;
-  if (!colorEnc) return 0;
-  if ("condition" in colorEnc) return 0;
-  if (colorEnc.type === "quantitative") return 0;
-  const colorField = "field" in colorEnc ? colorEnc.field : void 0;
-  if (!colorField) return 0;
-  const seriesNames = /* @__PURE__ */ new Set();
-  for (const row of spec.data) {
-    seriesNames.add(String(row[colorField]));
-  }
-  if (seriesNames.size < 2) return 0;
-  if (typeof spec.endpointLabels === "object" && spec.endpointLabels?.show === false) return 0;
-  const config = typeof spec.endpointLabels === "object" ? spec.endpointLabels : void 0;
-  const wrapWidth = config?.width ?? ENDPOINT_WRAP_WIDTH_DEFAULT;
-  let maxLabelWidth = 0;
-  for (const name of seriesNames) {
-    const lines = wrapText2(name, ENDPOINT_LABEL_FONT_SIZE, ENDPOINT_LABEL_FONT_WEIGHT, wrapWidth);
-    for (const line of lines) {
-      const w = estimateTextWidth15(line, ENDPOINT_LABEL_FONT_SIZE, ENDPOINT_LABEL_FONT_WEIGHT);
-      if (w > maxLabelWidth) maxLabelWidth = w;
-    }
-  }
-  const yField = config?.valueField ?? spec.encoding.y?.field;
-  const yFormat = config?.format ?? spec.encoding.y?.axis?.format;
-  let valueWidth = 0;
-  if (yField) {
-    let maxAbs = 0;
-    for (const row of spec.data) {
-      const v = Number(row[yField]);
-      if (Number.isFinite(v) && Math.abs(v) > maxAbs) maxAbs = Math.abs(v);
-    }
-    let sample;
-    if (yFormat) {
-      sample = formatEndpointValue(maxAbs, yFormat);
-    } else if (maxAbs >= 1e9) sample = "1.5B";
-    else if (maxAbs >= 1e6) sample = "1.5M";
-    else if (maxAbs >= 1e3) sample = "1.5K";
-    else sample = String(Math.round(maxAbs * 100) / 100);
-    valueWidth = estimateTextWidth15(sample, ENDPOINT_VALUE_FONT_SIZE, ENDPOINT_VALUE_FONT_WEIGHT);
-  }
-  const textColumn = Math.max(maxLabelWidth, valueWidth);
-  return ENDPOINT_SWATCH_SIZE + ENDPOINT_GAP + textColumn + 4;
-}
-
 // src/layout/metrics.ts
 import { estimateTextWidth as estimateTextWidth16 } from "@opendata-ai/openchart-core";
 var DEFAULT_LABEL_FONT_SIZE = 10;
@@ -12413,13 +12803,17 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
   const sup = resolveSuppression(spec, {
     seriesCount,
     labelsHiddenByStrategy,
-    labelsDensityNone: labelDensity === "none"
+    labelsDensityNone: labelDensity === "none",
+    endpointLabelsDemoted: plan?.endpointLabelsDemoted
   });
   let endpointWidth = 0;
   if (sup.showEndpointLabels && !labelsHiddenByStrategy) {
     endpointWidth = predictEndpointLabelsWidth(spec, theme);
     if (endpointWidth > 0) {
       margins.right = Math.max(margins.right, hPad) + endpointWidth + 16;
+      if (isEndsBoth(spec)) {
+        margins.left = Math.max(margins.left, hPad) + endpointWidth + 16;
+      }
     }
   }
   if (endpointWidth === 0 && sup.showEndOfLineLabels && (spec.markType === "line" || spec.markType === "area") && labelDensity !== "none" && !labelsHiddenByStrategy) {
@@ -12695,6 +13089,57 @@ function resolveMetrics(spec, metricsTopY, metricsArea, remainingChartHeight, me
   );
 }
 
+// src/layout/facet.ts
+var MIN_PANEL_WIDTH = 200;
+var PANEL_GAP = 12;
+var HEADER_HEIGHT = 20;
+function autoColumns(panelCount, availableWidth) {
+  const sqrtCols = Math.ceil(Math.sqrt(panelCount));
+  const fitCols = Math.max(1, Math.floor(availableWidth / MIN_PANEL_WIDTH));
+  return Math.min(sqrtCols, fitCols, panelCount);
+}
+function computeFacetGrid(facetValues, requestedColumns, totalArea, outerAxisReservation) {
+  const n = facetValues.length;
+  if (n === 0) return { panels: [], columns: 0, rows: 0 };
+  const usableWidth = totalArea.width - outerAxisReservation.left;
+  let columns = Math.min(requestedColumns ?? autoColumns(n, usableWidth), n);
+  while (columns > 1) {
+    const panelWidth2 = (usableWidth - (columns - 1) * PANEL_GAP) / columns;
+    if (panelWidth2 >= MIN_PANEL_WIDTH) break;
+    columns--;
+  }
+  const rows = Math.ceil(n / columns);
+  const panelWidth = Math.max(0, (usableWidth - (columns - 1) * PANEL_GAP) / columns);
+  const usableHeight = totalArea.height - outerAxisReservation.bottom;
+  const panelHeight = Math.max(
+    0,
+    (usableHeight - rows * HEADER_HEIGHT - (rows - 1) * PANEL_GAP) / rows
+  );
+  const panels = [];
+  for (let i = 0; i < n; i++) {
+    const col = i % columns;
+    const row = Math.floor(i / columns);
+    const x2 = totalArea.x + outerAxisReservation.left + col * (panelWidth + PANEL_GAP);
+    const y2 = totalArea.y + row * (HEADER_HEIGHT + panelHeight + PANEL_GAP);
+    panels.push({
+      key: facetValues[i],
+      area: {
+        x: x2,
+        y: y2 + HEADER_HEIGHT,
+        width: panelWidth,
+        height: panelHeight
+      },
+      headerPos: {
+        x: x2 + panelWidth / 2,
+        y: y2 + HEADER_HEIGHT * 0.6
+      },
+      row,
+      col
+    });
+  }
+  return { panels, columns, rows };
+}
+
 // src/layout/gridlines.ts
 function computeGridlines(axes, chartArea, showVertical = false) {
   const horizontal = [];
@@ -14333,6 +14778,7 @@ function compileTableLayout(spec, options, theme) {
 import {
   adaptTheme as adaptTheme4,
   buildD3Formatter as buildD3Formatter8,
+  CATEGORICAL_PALETTE,
   computeChrome as computeChrome7,
   estimateTextWidth as estimateTextWidth20,
   formatNumber as formatNumber8,
@@ -14341,6 +14787,9 @@ import {
 } from "@opendata-ai/openchart-core";
 var TILE_CORNER_RADIUS = 6;
 var TILE_STROKE_WIDTH = 1;
+var LEGEND_SWATCH_SIZE = 10;
+var LEGEND_SWATCH_GAP = 6;
+var LEGEND_ENTRY_GAP = 16;
 function compileTileMap(spec, options) {
   const { spec: normalized } = compile(spec);
   if (!("type" in normalized) || normalized.type !== "tilemap") {
@@ -14383,6 +14832,13 @@ function compileTileMap(spec, options) {
   if (fullArea.width <= 0 || fullArea.height <= 0) {
     return emptyLayout4(chrome, theme, options, watermark);
   }
+  const isCategorical = tilemapSpec.encoding.color !== void 0 || tilemapSpec.colors !== void 0;
+  if (isCategorical) {
+    return compileCategorical(tilemapSpec, options, theme, chrome, fullArea, isDarkMode, watermark);
+  }
+  return compileQuantitative(tilemapSpec, options, theme, chrome, fullArea, isDarkMode, watermark);
+}
+function compileQuantitative(tilemapSpec, options, theme, chrome, fullArea, isDarkMode, watermark) {
   const stateField = tilemapSpec.encoding.state.field;
   const valueField = tilemapSpec.encoding.value.field;
   const stateValueMap = /* @__PURE__ */ new Map();
@@ -14416,12 +14872,8 @@ function compileTileMap(spec, options) {
   const legendY = tileGridOffsetY + tilePositions.gridHeight + legendGap2;
   const legendWidth = tilePositions.gridWidth;
   const formatter = buildD3Formatter8(tilemapSpec.valueFormat) ?? formatNumber8;
-  const neutralFillLight = "#e0e0e0";
-  const neutralFillDark = "#1e2a30";
-  const neutralStrokeLight = "#d0d0d0";
-  const neutralStrokeDark = "rgba(255,255,255,0.08)";
-  const neutralFill = isDarkMode ? neutralFillDark : neutralFillLight;
-  const neutralStroke = isDarkMode ? neutralStrokeDark : neutralStrokeLight;
+  const neutralFill = isDarkMode ? "#1e2a30" : "#e0e0e0";
+  const neutralStroke = isDarkMode ? "rgba(255,255,255,0.08)" : "#d0d0d0";
   const tiles = [];
   for (const { state: stateCode } of US_STATE_TILES) {
     const pos = tilePositions.positions.get(stateCode);
@@ -14432,71 +14884,24 @@ function compileTileMap(spec, options) {
     const fill = hasData ? baseColor : neutralFill;
     const stroke = hasData ? isDarkMode ? "rgba(255,255,255,0.1)" : "rgba(0,0,0,0.1)" : neutralStroke;
     const formattedValue = hasData ? formatter(value2) : "\u2013";
-    const labelStyle = {
-      fontFamily: theme.fonts.family,
-      fontSize: tilePositions.tileSize > 24 ? 10 : 7,
-      fontWeight: 700,
-      fill: "#ffffff",
-      lineHeight: 1.2
-    };
-    const valueLabelStyle = {
-      fontFamily: theme.fonts.family,
-      fontSize: tilePositions.tileSize > 24 ? 10 : 7,
-      fontWeight: 300,
-      fill: "rgba(255,255,255,0.6)",
-      lineHeight: 1.2
-    };
-    const tileCenterX = tileGridOffsetX + pos.x + tilePositions.tileSize / 2;
-    const tileTopY = tileGridOffsetY + pos.y;
-    const sz = tilePositions.tileSize;
-    const valueLabel = sz < 24 ? { text: "", x: 0, y: 0, style: valueLabelStyle, visible: false } : {
-      text: formattedValue,
-      x: tileCenterX,
-      y: tileTopY + sz * 0.78,
-      style: valueLabelStyle,
-      visible: true
-    };
-    const tile = {
-      type: "tile",
-      stateCode,
-      x: tileGridOffsetX + pos.x,
-      y: tileTopY,
-      size: sz,
-      fill,
-      fillOpacity: hasData ? opacity : 1,
-      stroke,
-      strokeWidth: TILE_STROKE_WIDTH,
-      cornerRadius: TILE_CORNER_RADIUS,
-      value: value2 ?? null,
-      formattedValue,
-      hasData,
-      label: {
-        text: stateCode,
-        x: tileCenterX,
-        y: tileTopY + sz * 0.28,
-        style: labelStyle,
-        visible: true
-      },
-      valueLabel,
-      data: { state: stateCode, value: value2, stateName: STATE_NAMES[stateCode] ?? stateCode },
-      aria: {
-        role: "img",
-        label: `${STATE_NAMES[stateCode] ?? stateCode}: ${formattedValue}`
-      },
-      animationIndex: 0
-    };
-    tiles.push(tile);
-  }
-  const indices = Array.from({ length: tiles.length }, (_, i) => i);
-  let seed = 42;
-  for (let i = indices.length - 1; i > 0; i--) {
-    seed = seed * 1103515245 + 12345 & 2147483647;
-    const j = seed % (i + 1);
-    [indices[i], indices[j]] = [indices[j], indices[i]];
-  }
-  for (let i = 0; i < tiles.length; i++) {
-    tiles[i].animationIndex = indices[i];
+    tiles.push(
+      buildTileMark({
+        stateCode,
+        pos,
+        tileSize: tilePositions.tileSize,
+        gridOffsetX: tileGridOffsetX,
+        gridOffsetY: tileGridOffsetY,
+        fill,
+        fillOpacity: hasData ? opacity : 1,
+        stroke,
+        value: value2,
+        formattedValue,
+        hasData,
+        theme
+      })
+    );
   }
+  assignAnimationIndices2(tiles);
   let gradientLegend = null;
   if (showLegend) {
     const numStops = 5;
@@ -14521,19 +14926,7 @@ function compileTileMap(spec, options) {
       maxLabel: formatter(max4)
     };
   }
-  const tooltipDescriptors = /* @__PURE__ */ new Map();
-  for (const tile of tiles) {
-    const fields = [
-      {
-        label: "Value",
-        value: tile.formattedValue
-      }
-    ];
-    tooltipDescriptors.set(tile.stateCode, {
-      title: STATE_NAMES[tile.stateCode] ?? tile.stateCode,
-      fields
-    });
-  }
+  const tooltipDescriptors = buildTooltips(tiles);
   const a11y = {
     altText: `Tile map of US states showing values from ${formatter(min4)} to ${formatter(max4)}`,
     dataTableFallback: tiles.map((t) => [t.stateCode, t.formattedValue]),
@@ -14541,12 +14934,144 @@ function compileTileMap(spec, options) {
     keyboardNavigable: tiles.length > 0
   };
   const resolvedAnimation = resolveAnimation(tilemapSpec.animation);
+  const padding = theme.spacing.padding;
   const contentHeight = tileGridOffsetY + tilePositions.gridHeight + legendGap2 + legendTotalHeight + chrome.bottomHeight + padding;
   return {
     area: fullArea,
     chrome,
     tiles,
     gradientLegend,
+    categoricalLegend: null,
+    tooltipDescriptors,
+    a11y,
+    theme,
+    width: options.width,
+    height: contentHeight,
+    animation: resolvedAnimation,
+    watermark,
+    measureText: options.measureText ?? ((text, fontSize) => ({ width: estimateTextWidth20(text, fontSize), height: fontSize }))
+  };
+}
+function compileCategorical(tilemapSpec, options, theme, chrome, fullArea, isDarkMode, watermark) {
+  const stateField = tilemapSpec.encoding.state.field;
+  const colorField = tilemapSpec.encoding.color?.field ?? tilemapSpec.encoding.value.field;
+  const stateCategoryMap = /* @__PURE__ */ new Map();
+  for (const row of tilemapSpec.data) {
+    const stateCode = String(row[stateField]);
+    const raw = row[colorField];
+    if (STATE_CODE_SET.has(stateCode) && raw !== null && raw !== void 0) {
+      stateCategoryMap.set(stateCode, String(raw));
+    }
+  }
+  const categories = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const row of tilemapSpec.data) {
+    const raw = row[colorField];
+    if (raw !== null && raw !== void 0) {
+      const cat = String(raw);
+      if (!seen.has(cat)) {
+        seen.add(cat);
+        categories.push(cat);
+      }
+    }
+  }
+  const categoryColors = /* @__PURE__ */ new Map();
+  if (tilemapSpec.colors) {
+    for (const cat of categories) {
+      categoryColors.set(
+        cat,
+        tilemapSpec.colors[cat] ?? CATEGORICAL_PALETTE[categoryColors.size % CATEGORICAL_PALETTE.length]
+      );
+    }
+  } else {
+    for (let i = 0; i < categories.length; i++) {
+      categoryColors.set(categories[i], CATEGORICAL_PALETTE[i % CATEGORICAL_PALETTE.length]);
+    }
+  }
+  const showLegend = tilemapSpec.legend?.show !== false;
+  const legendRowHeight = LEGEND_SWATCH_SIZE + 6;
+  const legendTotalHeight = showLegend ? legendRowHeight : 0;
+  const legendGap2 = showLegend ? 8 : 0;
+  const tileAreaHeight = fullArea.height - legendTotalHeight - legendGap2;
+  const tilePositions = computeTilePositions(fullArea.width, tileAreaHeight, 5);
+  const tileGridOffsetX = fullArea.x + (fullArea.width - tilePositions.gridWidth) / 2;
+  const tileGridOffsetY = fullArea.y;
+  const legendX = tileGridOffsetX;
+  const legendY = tileGridOffsetY + tilePositions.gridHeight + legendGap2;
+  const legendWidth = tilePositions.gridWidth;
+  const neutralFill = isDarkMode ? "#1e2a30" : "#e0e0e0";
+  const neutralStroke = isDarkMode ? "rgba(255,255,255,0.08)" : "#d0d0d0";
+  const tiles = [];
+  for (const { state: stateCode } of US_STATE_TILES) {
+    const pos = tilePositions.positions.get(stateCode);
+    if (!pos) continue;
+    const hasData = stateCategoryMap.has(stateCode);
+    const category = hasData ? stateCategoryMap.get(stateCode) : null;
+    const fill = hasData ? categoryColors.get(category) ?? neutralFill : neutralFill;
+    const stroke = hasData ? isDarkMode ? "rgba(255,255,255,0.1)" : "rgba(0,0,0,0.1)" : neutralStroke;
+    const formattedValue = category ? formatCategoryLabel(category) : "\u2013";
+    tiles.push(
+      buildTileMark({
+        stateCode,
+        pos,
+        tileSize: tilePositions.tileSize,
+        gridOffsetX: tileGridOffsetX,
+        gridOffsetY: tileGridOffsetY,
+        fill,
+        fillOpacity: 1,
+        stroke,
+        value: null,
+        formattedValue,
+        hasData,
+        theme,
+        category: hasData ? category : void 0
+      })
+    );
+  }
+  assignAnimationIndices2(tiles);
+  let categoricalLegend = null;
+  if (showLegend) {
+    const labelStyle = {
+      fontFamily: theme.fonts.family,
+      fontSize: 11,
+      fontWeight: 400,
+      fill: theme.colors.text,
+      lineHeight: 1.2
+    };
+    const entries = categories.map((cat) => ({
+      label: formatCategoryLabel(cat),
+      color: categoryColors.get(cat),
+      shape: "square"
+    }));
+    categoricalLegend = {
+      type: "categorical",
+      position: "bottom",
+      bounds: { x: legendX, y: legendY, width: legendWidth, height: legendRowHeight },
+      labelStyle,
+      entries,
+      swatchSize: LEGEND_SWATCH_SIZE,
+      swatchGap: LEGEND_SWATCH_GAP,
+      entryGap: LEGEND_ENTRY_GAP,
+      swatchChipFill: "transparent"
+    };
+  }
+  const tooltipDescriptors = buildTooltips(tiles, "Category");
+  const categoryList = categories.map(formatCategoryLabel).join(", ");
+  const a11y = {
+    altText: `Tile map of US states showing categories: ${categoryList}`,
+    dataTableFallback: tiles.map((t) => [t.stateCode, t.formattedValue]),
+    role: "img",
+    keyboardNavigable: tiles.length > 0
+  };
+  const resolvedAnimation = resolveAnimation(tilemapSpec.animation);
+  const padding = theme.spacing.padding;
+  const contentHeight = tileGridOffsetY + tilePositions.gridHeight + legendGap2 + legendTotalHeight + chrome.bottomHeight + padding;
+  return {
+    area: fullArea,
+    chrome,
+    tiles,
+    gradientLegend: null,
+    categoricalLegend,
     tooltipDescriptors,
     a11y,
     theme,
@@ -14557,6 +15082,109 @@ function compileTileMap(spec, options) {
     measureText: options.measureText ?? ((text, fontSize) => ({ width: estimateTextWidth20(text, fontSize), height: fontSize }))
   };
 }
+function buildTileMark(opts) {
+  const {
+    stateCode,
+    pos,
+    tileSize,
+    gridOffsetX,
+    gridOffsetY,
+    fill,
+    fillOpacity,
+    stroke,
+    value: value2,
+    formattedValue,
+    hasData,
+    theme,
+    category
+  } = opts;
+  const tileCenterX = gridOffsetX + pos.x + tileSize / 2;
+  const tileTopY = gridOffsetY + pos.y;
+  const labelStyle = {
+    fontFamily: theme.fonts.family,
+    fontSize: tileSize > 24 ? 10 : 7,
+    fontWeight: 700,
+    fill: "#ffffff",
+    lineHeight: 1.2
+  };
+  const valueLabelStyle = {
+    fontFamily: theme.fonts.family,
+    fontSize: tileSize > 24 ? 10 : 7,
+    fontWeight: 300,
+    fill: "rgba(255,255,255,0.6)",
+    lineHeight: 1.2
+  };
+  const valueLabel = tileSize < 24 ? { text: "", x: 0, y: 0, style: valueLabelStyle, visible: false } : {
+    text: formattedValue,
+    x: tileCenterX,
+    y: tileTopY + tileSize * 0.78,
+    style: valueLabelStyle,
+    visible: true
+  };
+  const data = {
+    state: stateCode,
+    value: value2,
+    stateName: STATE_NAMES[stateCode] ?? stateCode
+  };
+  if (category !== void 0) {
+    data.category = category;
+  }
+  return {
+    type: "tile",
+    stateCode,
+    x: gridOffsetX + pos.x,
+    y: tileTopY,
+    size: tileSize,
+    fill,
+    fillOpacity,
+    stroke,
+    strokeWidth: TILE_STROKE_WIDTH,
+    cornerRadius: TILE_CORNER_RADIUS,
+    value: value2,
+    formattedValue,
+    hasData,
+    label: {
+      text: stateCode,
+      x: tileCenterX,
+      y: tileTopY + tileSize * 0.28,
+      style: labelStyle,
+      visible: true
+    },
+    valueLabel,
+    data,
+    aria: {
+      role: "img",
+      label: `${STATE_NAMES[stateCode] ?? stateCode}: ${formattedValue}`
+    },
+    animationIndex: 0
+  };
+}
+function assignAnimationIndices2(tiles) {
+  const indices = Array.from({ length: tiles.length }, (_, i) => i);
+  let seed = 42;
+  for (let i = indices.length - 1; i > 0; i--) {
+    seed = seed * 1103515245 + 12345 & 2147483647;
+    const j = seed % (i + 1);
+    [indices[i], indices[j]] = [indices[j], indices[i]];
+  }
+  for (let i = 0; i < tiles.length; i++) {
+    tiles[i].animationIndex = indices[i];
+  }
+}
+function buildTooltips(tiles, fieldLabel = "Value") {
+  const tooltipDescriptors = /* @__PURE__ */ new Map();
+  for (const tile of tiles) {
+    const fields = [{ label: fieldLabel, value: tile.formattedValue }];
+    tooltipDescriptors.set(tile.stateCode, {
+      title: STATE_NAMES[tile.stateCode] ?? tile.stateCode,
+      fields
+    });
+  }
+  return tooltipDescriptors;
+}
+function formatCategoryLabel(category) {
+  return category.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
 function emptyLayout4(chrome, theme, options, watermark) {
   return {
     area: { x: 0, y: 0, width: 0, height: 0 },
@@ -14577,6 +15205,7 @@ function emptyLayout4(chrome, theme, options, watermark) {
       minLabel: "0",
       maxLabel: "0"
     },
+    categoricalLegend: null,
     tooltipDescriptors: /* @__PURE__ */ new Map(),
     a11y: {
       altText: "Empty tile map",
@@ -15546,6 +16175,20 @@ function compileChart(spec, options) {
       }
     };
   }
+  const facetChannel = renderSpec.encoding.facet;
+  if (facetChannel?.field) {
+    return compileFaceted(
+      chartSpec,
+      renderSpec,
+      facetChannel,
+      options,
+      theme,
+      strategy,
+      watermark,
+      resolvedAnimation,
+      crosshair
+    );
+  }
   const measure = createMeasureFn(options.measureText);
   const plan = resolveLayoutPlan(
     chartSpec,
@@ -15564,7 +16207,7 @@ function compileChart(spec, options) {
     plan.xAxisExtent
   );
   const dims = computeDimensions(chartSpec, options, legendStub, theme, strategy, watermark, plan);
-  const chartArea = dims.chartArea;
+  const chartArea = options.frozenChartArea ?? dims.chartArea;
   const finalLegend = placeLegend(
     plan.legendContent,
     chartArea,
@@ -15582,7 +16225,7 @@ function compileChart(spec, options) {
     };
   }
   const scales = computeScales(renderSpec, scaleArea, renderSpec.data);
-  applyColorScaleRange(scales, renderSpec.encoding, theme);
+  applyColorScaleRange(scales, renderSpec.encoding, theme, renderSpec.highlight);
   scales.defaultColor = chartSpec.markDef.fill ?? chartSpec.markDef.stroke ?? theme.colors.categorical[0];
   const isRadial = chartSpec.markType === "arc";
   const skipX = chartSpec.display === "sparkline" && !chartSpec.userExplicit.xAxis;
@@ -15608,7 +16251,14 @@ function compileChart(spec, options) {
   );
   const renderer = getChartRenderer(rendererKey);
   const marks = renderer ? renderer(renderSpec, scales, chartArea, strategy, theme, options.width) : [];
-  const endpointLabels = computeEndpointLabels(chartSpec, marks, theme, chartArea, strategy);
+  const endpointLabels = computeEndpointLabels(
+    chartSpec,
+    marks,
+    theme,
+    chartArea,
+    strategy,
+    plan.endpointLabelsDemoted
+  );
   const obstacles = [];
   if (finalLegend.bounds.width > 0) {
     obstacles.push({ ...finalLegend.bounds, kind: "legend" });
@@ -15625,15 +16275,24 @@ function compileChart(spec, options) {
     obstacles.push({ ...endpointLabels.bounds, kind: "endpoint-label" });
   }
   const annotationMeasure = options.measureText ? (text, font) => options.measureText(text, font.fontSize, font.fontWeight).width : heuristicMeasure;
-  const annotations = computeAnnotations(chartSpec, {
+  let annotations = computeAnnotations(chartSpec, {
     scales,
     chartArea,
     strategy,
     isDark: theme.isDark,
     obstacles,
     svg: { width: dims.total.width, height: dims.total.height },
-    measure: annotationMeasure
+    measure: annotationMeasure,
+    autoThin: chartSpec.autoThin
   });
+  let footnotes;
+  if (chartSpec.autoThin && annotations.length > 1) {
+    const result = thinAnnotations(annotations, chartSpec.annotations, annotationMeasure);
+    annotations = result.annotations;
+    if (result.footnotes.length > 0) {
+      footnotes = result.footnotes;
+    }
+  }
   const tooltipDescriptors = computeTooltipDescriptors(chartSpec, marks);
   const altText = generateAltText(
     {
@@ -15653,9 +16312,10 @@ function compileChart(spec, options) {
     chartSpec.data
   );
   assignAnimationIndices(marks, resolvedAnimation);
+  const chrome = footnotes ? { ...dims.chrome, footnotes } : dims.chrome;
   return {
     area: chartArea,
-    chrome: dims.chrome,
+    chrome,
     metrics: dims.metrics,
     axes: {
       x: axes.x,
@@ -15684,6 +16344,196 @@ function compileChart(spec, options) {
     measureText: options.measureText
   };
 }
+function compileFaceted(chartSpec, renderSpec, facetChannel, options, theme, strategy, watermark, resolvedAnimation, crosshair) {
+  const measure = createMeasureFn(options.measureText);
+  const panelEncoding = { ...renderSpec.encoding };
+  delete panelEncoding.facet;
+  const panelSpec = { ...renderSpec, encoding: panelEncoding };
+  const panelChartSpec = { ...chartSpec, encoding: panelEncoding };
+  const groups = groupByField(renderSpec.data, facetChannel.field);
+  const facetValues = Array.from(groups.keys());
+  if (facetChannel.sort !== null) {
+    const dir = facetChannel.sort === "descending" ? -1 : 1;
+    facetValues.sort((a, b) => dir * a.localeCompare(b));
+  }
+  const plan = resolveLayoutPlan(
+    panelChartSpec,
+    panelSpec,
+    options,
+    theme,
+    strategy,
+    watermark,
+    measure
+  );
+  const legendStub = placeLegend(
+    plan.legendContent,
+    { x: 0, y: 0, width: options.width, height: options.height },
+    options.width,
+    theme,
+    plan.xAxisExtent
+  );
+  const dims = computeDimensions(
+    panelChartSpec,
+    options,
+    legendStub,
+    theme,
+    strategy,
+    watermark,
+    plan
+  );
+  const chartArea = dims.chartArea;
+  const finalLegend = placeLegend(
+    plan.legendContent,
+    chartArea,
+    options.width,
+    theme,
+    plan.xAxisExtent
+  );
+  const leftReservation = plan.leftGutter;
+  const bottomReservation = plan.xAxisExtent;
+  const grid = computeFacetGrid(facetValues, facetChannel.columns, chartArea, {
+    left: leftReservation,
+    bottom: bottomReservation
+  });
+  const resolveConfig = chartSpec.resolve;
+  const yResolve = resolveConfig?.scale?.y ?? "shared";
+  const xResolve = resolveConfig?.scale?.x ?? "shared";
+  const fullScales = computeScales(panelSpec, chartArea, renderSpec.data);
+  const sharedXDomain = xResolve === "shared" && fullScales.x ? fullScales.x.scale.domain() : void 0;
+  const sharedYDomain = yResolve === "shared" && fullScales.y ? fullScales.y.scale.domain() : void 0;
+  const isRadial = chartSpec.markType === "arc";
+  const rendererKey = resolveRendererKey(
+    renderSpec.markType,
+    panelEncoding,
+    renderSpec.markDef
+  );
+  const renderer = getChartRenderer(rendererKey);
+  const allMarks = [];
+  const panelLayouts = [];
+  for (const gridPanel of grid.panels) {
+    const panelData = groups.get(gridPanel.key) ?? [];
+    const panelSpecLocal = { ...panelSpec, data: panelData };
+    let panelEnc = { ...panelEncoding };
+    if (sharedXDomain && panelEnc.x) {
+      const xCh = panelEnc.x;
+      panelEnc = {
+        ...panelEnc,
+        x: { ...xCh, scale: { ...xCh.scale ?? {}, domain: sharedXDomain } }
+      };
+    }
+    if (sharedYDomain && panelEnc.y) {
+      const yCh = panelEnc.y;
+      panelEnc = {
+        ...panelEnc,
+        y: { ...yCh, scale: { ...yCh.scale ?? {}, domain: sharedYDomain } }
+      };
+    }
+    const panelSpecWithDomains = {
+      ...panelSpecLocal,
+      encoding: panelEnc
+    };
+    const panelScales = computeScales(panelSpecWithDomains, gridPanel.area, panelData);
+    applyColorScaleRange(panelScales, panelSpecWithDomains.encoding, theme);
+    panelScales.defaultColor = chartSpec.markDef.fill ?? chartSpec.markDef.stroke ?? theme.colors.categorical[0];
+    const isLeftCol = gridPanel.col === 0;
+    const isBottomRow = gridPanel.row === grid.rows - 1;
+    const panelAxes = isRadial ? { x: void 0, y: void 0 } : computeAxes(panelScales, gridPanel.area, strategy, theme, options.measureText, {
+      data: panelData,
+      encoding: panelSpecWithDomains.encoding,
+      skipX: xResolve === "shared" ? !isBottomRow : false,
+      skipY: yResolve === "shared" ? !isLeftCol : false,
+      markType: chartSpec.markType,
+      totalWidth: gridPanel.area.width
+    });
+    if (!isRadial) {
+      computeGridlines(panelAxes, gridPanel.area);
+    }
+    const panelMarks = renderer ? renderer(
+      panelSpecWithDomains,
+      panelScales,
+      gridPanel.area,
+      strategy,
+      theme,
+      gridPanel.area.width
+    ) : [];
+    const annotationMeasure = options.measureText ? (text, font) => options.measureText(text, font.fontSize, font.fontWeight).width : heuristicMeasure;
+    const panelAnnotations = computeAnnotations(panelSpecWithDomains, {
+      scales: panelScales,
+      chartArea: gridPanel.area,
+      strategy,
+      isDark: theme.isDark,
+      obstacles: [],
+      svg: { width: options.width, height: options.height },
+      measure: annotationMeasure,
+      autoThin: panelSpecWithDomains.autoThin
+    });
+    allMarks.push(...panelMarks);
+    panelLayouts.push({
+      key: gridPanel.key,
+      area: gridPanel.area,
+      marks: panelMarks,
+      axes: { x: panelAxes.x, y: panelAxes.y },
+      annotations: panelAnnotations,
+      header: {
+        text: gridPanel.key,
+        x: gridPanel.headerPos.x,
+        y: gridPanel.headerPos.y,
+        fontSize: theme.fonts.sizes.body,
+        fontWeight: theme.fonts.weights.medium
+      }
+    });
+  }
+  const tooltipDescriptors = computeTooltipDescriptors(panelChartSpec, allMarks);
+  const panelCount = facetValues.length;
+  const baseAltText = generateAltText(
+    {
+      mark: chartSpec.markType,
+      data: chartSpec.data,
+      encoding: chartSpec.encoding,
+      chrome: chartSpec.chrome
+    },
+    chartSpec.data
+  );
+  const altText = `${baseAltText} Faceted into ${panelCount} panels by ${facetChannel.field}.`;
+  const dataTableFallback = generateDataTable(
+    {
+      mark: chartSpec.markType,
+      data: chartSpec.data,
+      encoding: chartSpec.encoding
+    },
+    chartSpec.data
+  );
+  assignAnimationIndices(allMarks, resolvedAnimation);
+  return {
+    area: chartArea,
+    chrome: dims.chrome,
+    metrics: dims.metrics,
+    axes: { x: void 0, y: void 0 },
+    marks: allMarks,
+    annotations: [],
+    legend: finalLegend,
+    tooltipDescriptors,
+    a11y: {
+      altText,
+      dataTableFallback,
+      role: "img",
+      keyboardNavigable: allMarks.length > 0
+    },
+    theme,
+    dimensions: { width: options.width, height: options.height },
+    animation: resolvedAnimation,
+    watermark,
+    display: chartSpec.display,
+    crosshair,
+    measureText: options.measureText,
+    facet: {
+      panels: panelLayouts,
+      facetField: facetChannel.field,
+      columns: grid.columns,
+      sharedScales: yResolve === "shared" && xResolve === "shared"
+    }
+  };
+}
 function compileLayer2(spec, options) {
   return compileLayer(spec, options, compileChart);
 }