@opendata-ai/openchart-engine 8.0.0-rc.2 → 8.0.0-rc.20

package/dist/index.js

@@ -9,6 +9,7 @@ import {
   getHeightClass,
   getLayoutStrategy,
   isAxislessMark as isAxislessMark3,
+  MAX_SR_TABLE_ROWS,
   resolveTheme as resolveTheme7
 } from "@opendata-ai/openchart-core";
 
@@ -244,7 +245,10 @@ function refreshConnector(connector, bounds, markerRadius) {
   }
   const exit = connectorExit(bounds, endpoint.x, endpoint.y);
   if (!exit) return void 0;
-  const from = { x: exit.x, y: exit.y };
+  const from = {
+    x: exit.x + (connector.fromOffset?.dx ?? 0),
+    y: exit.y + (connector.fromOffset?.dy ?? 0)
+  };
   const gap = connectorPullbackGap(markerRadius, connector.arrow);
   const cdx = endpoint.x - from.x;
   const cdy = endpoint.y - from.y;
@@ -506,6 +510,10 @@ function resolveTextAnnotation(annotation, scales, chartArea, isDark, measure =
           from,
           to,
           endpoint,
+          fromOffset: annotation.connectorOffset?.from ? {
+            dx: annotation.connectorOffset.from.dx ?? 0,
+            dy: annotation.connectorOffset.from.dy ?? 0
+          } : void 0,
           stroke: connectorStroke,
           style: connectorStyle,
           arrow: connectorArrow,
@@ -5545,7 +5553,9 @@ var SIZE_SCALE_DEFAULTS = {
    * Text glyphs. Linear, not sqrt -- a word reads by its height, which is
    * linear in font size, where a disc reads by its area.
    */
-  text: { curve: "linear", range: [11, 32] }
+  text: { curve: "linear", range: [11, 32] },
+  /** Map point dots. sqrt for area-proportional, tighter range than scatter. */
+  mapPoint: { curve: "sqrt", range: [3, 20] }
 };
 function sizeScaleDefaultsFor(markType) {
   const found = SIZE_SCALE_DEFAULTS[markType];
@@ -9078,7 +9088,7 @@ function resolvePosition2(value2, channelType, scale) {
     }
   }
 }
-function computeScatterMarks(spec, scales, _chartArea, _strategy) {
+function computeScatterMarks(spec, scales, _chartArea, _strategy, theme) {
   const encoding = spec.encoding;
   const xChannel = encoding.x;
   const yChannel = encoding.y;
@@ -9096,6 +9106,10 @@ function computeScatterMarks(spec, scales, _chartArea, _strategy) {
   const sizeField = sizeEnc?.field;
   const resolvedSize = buildSizeScale(sizeEnc, spec.data, SIZE_SCALE_DEFAULTS.point);
   const sizeScale = resolvedSize?.scale;
+  const constFill = spec.markDef.fill;
+  const constSize = spec.markDef.size;
+  const bg = theme?.colors?.background;
+  const defaultStroke = bg && bg !== "transparent" ? bg : "#ffffff";
   const keyEnc = encoding.key && "field" in encoding.key ? encoding.key : void 0;
   const keyField = keyEnc?.field;
   const marks = [];
@@ -9110,10 +9124,12 @@ function computeScatterMarks(spec, scales, _chartArea, _strategy) {
     if (isSequentialColor && colorField) {
       const val = Number(row[colorField]);
       color2 = Number.isFinite(val) ? getSequentialColor(scales, val) : getColor(scales, "__default__");
-    } else {
+    } else if (colorField) {
       color2 = getColor(scales, category ?? "__default__");
+    } else {
+      color2 = constFill ?? getColor(scales, "__default__");
     }
-    let radius = DEFAULT_POINT_RADIUS2;
+    let radius = constSize != null ? constSize : DEFAULT_POINT_RADIUS2;
     if (sizeScale && sizeField) {
       const sizeVal = Number(row[sizeField]);
       if (Number.isFinite(sizeVal)) {
@@ -9134,9 +9150,9 @@ function computeScatterMarks(spec, scales, _chartArea, _strategy) {
       cy,
       r: radius,
       fill: color2,
-      stroke: "#ffffff",
-      strokeWidth: 1,
-      fillOpacity: 0.7,
+      stroke: spec.markDef.stroke ?? defaultStroke,
+      strokeWidth: spec.markDef.strokeWidth ?? 1,
+      fillOpacity: spec.markDef.opacity ?? 0.7,
       data: row,
       aria
     });
@@ -9177,7 +9193,7 @@ function linearRegression(points) {
   const intercept = (sumY - slope * sumX) / n;
   return { slope, intercept };
 }
-function computeTrendLine(marks) {
+function computeTrendLine(marks, stroke = TRENDLINE_COLOR, strokeWidth = TRENDLINE_STROKE_WIDTH) {
   if (marks.length < 2) return null;
   const points = marks.map((m) => ({ x: m.cx, y: m.cy }));
   const result = linearRegression(points);
@@ -9200,8 +9216,8 @@ function computeTrendLine(marks) {
       { x: minX, y: y12 },
       { x: maxX, y: y2 }
     ],
-    stroke: TRENDLINE_COLOR,
-    strokeWidth: TRENDLINE_STROKE_WIDTH,
+    stroke,
+    strokeWidth,
     strokeDasharray: TRENDLINE_DASH,
     data: [],
     aria
@@ -9209,13 +9225,20 @@ function computeTrendLine(marks) {
 }
 
 // src/charts/scatter/index.ts
-var scatterRenderer = (spec, scales, chartArea, strategy, _theme) => {
-  const pointMarks = computeScatterMarks(spec, scales, chartArea, strategy);
+var scatterRenderer = (spec, scales, chartArea, strategy, theme) => {
+  const pointMarks = computeScatterMarks(spec, scales, chartArea, strategy, theme);
   const marks = [...pointMarks];
-  if (spec.markDef?.trendline !== false) {
-    const trendLine = computeTrendLine(pointMarks);
+  const trendline = spec.markDef?.trendline;
+  if (trendline !== false) {
+    const config = typeof trendline === "object" ? trendline : void 0;
+    const stroke = config?.stroke ?? theme?.colors?.text;
+    const trendLine = computeTrendLine(pointMarks, stroke, config?.strokeWidth);
     if (trendLine) {
-      marks.unshift(trendLine);
+      if (config?.layer === "above") {
+        marks.push(trendLine);
+      } else {
+        marks.unshift(trendLine);
+      }
     }
   }
   return marks;
@@ -9837,7 +9860,16 @@ function expandChannelSugar(spec, warnings) {
   }
   return result;
 }
-var COUNT_GROUP_CHANNELS = ["x", "y", "color", "detail", "strokeDash", "facet"];
+var COUNT_GROUP_CHANNELS = [
+  "x",
+  "y",
+  "color",
+  "detail",
+  "strokeDash",
+  "facet",
+  "row",
+  "column"
+];
 function expandCountAggregate(spec) {
   const encoding = spec.encoding;
   if (!encoding || typeof encoding !== "object") return spec;
@@ -10072,6 +10104,12 @@ function resolveAnimation(spec) {
   const enter = resolvePhase(config.enter, ENTER_DEFAULTS);
   const update = resolvePhase(config.update, UPDATE_DEFAULTS);
   const exit = resolvePhase(config.exit, EXIT_DEFAULTS);
+  if (update && config.update && typeof config.update === "object" && !Array.isArray(config.update)) {
+    const cap = config.update.maxMarks;
+    if (typeof cap === "number" && Number.isFinite(cap) && cap >= 1) {
+      update.maxMarks = Math.floor(cap);
+    }
+  }
   if (!enter && !update && !exit) return void 0;
   return {
     enter: enter ?? void 0,
@@ -10464,6 +10502,7 @@ function normalizeChartSpec(spec, warnings) {
     data: spec.data,
     encoding,
     chrome: normalizeChrome(spec.chrome),
+    chromeLayout: spec.chromeLayout,
     metrics: spec.metrics,
     seriesSearch: normalizeSeriesSearch(spec, encoding, warnings),
     youDrawIt: normalizeYouDrawIt(spec),
@@ -10538,15 +10577,10 @@ function normalizeSankeySpec(spec, _warnings) {
   };
 }
 function normalizeGraphSpec(spec) {
-  const defaultLayout = {
+  const layout = {
     type: "force",
-    chargeStrength: -300,
-    linkDistance: 30
-  };
-  const layout = spec.layout ? {
-    ...defaultLayout,
     ...spec.layout
-  } : defaultLayout;
+  };
   return {
     type: "graph",
     nodes: spec.nodes,
@@ -10558,7 +10592,10 @@ function normalizeGraphSpec(spec) {
     annotations: normalizeAnnotations(spec.annotations),
     theme: spec.theme ?? {},
     darkMode: spec.darkMode ?? "off",
-    watermark: spec.watermark ?? true
+    watermark: spec.watermark ?? true,
+    animation: spec.animation,
+    interaction: spec.interaction,
+    legend: spec.legend
   };
 }
 function normalizeTileMapSpec(spec, warnings) {
@@ -10631,7 +10668,8 @@ function normalizeMapSpec(spec, _warnings) {
     darkMode: spec.darkMode ?? "off",
     watermark: spec.watermark ?? true,
     animation: spec.animation,
-    valueFormat: spec.valueFormat
+    valueFormat: spec.valueFormat,
+    points: spec.points
   };
 }
 function normalizeBarListSpec(spec, _warnings) {
@@ -10726,6 +10764,7 @@ import {
   MARK_ENCODING_RULES,
   MARK_TYPES,
   resolveSchemeName as resolveSchemeName2,
+  SEQUENTIAL_PALETTES,
   SUPPORTED_SCHEME_NAMES
 } from "@opendata-ai/openchart-core";
 var VALID_FIELD_TYPES = /* @__PURE__ */ new Set(["quantitative", "temporal", "nominal", "ordinal"]);
@@ -10784,6 +10823,53 @@ function didYouMean(field, columns) {
   const match = nearestColumn(field, columns);
   return match ? ` Did you mean "${match}"?` : "";
 }
+function checkSchemeName(channelObj, channelPath, errors) {
+  const scale = channelObj.scale;
+  if (scale && typeof scale.scheme === "string" && !resolveSchemeName2(scale.scheme)) {
+    errors.push({
+      message: `Spec error: ${channelPath}.scale.scheme "${scale.scheme}" is not a supported scheme name`,
+      path: `${channelPath}.scale.scheme`,
+      code: "INVALID_VALUE",
+      suggestion: `Use one of the supported scheme names: ${[...SUPPORTED_SCHEME_NAMES].join(", ")}. Or provide explicit colors via scale.range.`
+    });
+  }
+}
+function checkSchemeUnused(encoding, errors, familyNote, suggestion) {
+  for (const [channel, ch] of Object.entries(encoding)) {
+    if (!ch || typeof ch !== "object" || Array.isArray(ch)) continue;
+    const scale = ch.scale;
+    if (scale && typeof scale.scheme === "string") {
+      errors.push({
+        message: `Spec error: encoding.${channel}.scale.scheme has no effect \u2014 ${familyNote}`,
+        path: `encoding.${channel}.scale.scheme`,
+        code: "INVALID_VALUE",
+        suggestion
+      });
+    }
+  }
+}
+var MAP_PALETTE_NAMES = Object.keys(SEQUENTIAL_PALETTES).join(", ");
+function checkMapSchemeName(channelObj, channelPath, errors) {
+  const scale = channelObj.scale;
+  if (!scale || typeof scale.scheme !== "string") return;
+  if (channelObj.type === "nominal" || channelObj.type === "ordinal") {
+    errors.push({
+      message: `Spec error: ${channelPath}.scale.scheme has no effect \u2014 categorical map colors come from scale.range and scale.domain`,
+      path: `${channelPath}.scale.scheme`,
+      code: "INVALID_VALUE",
+      suggestion: "Remove scale.scheme. To customize categorical map colors, provide explicit colors via scale.range (with scale.domain for category order)."
+    });
+    return;
+  }
+  if (!(scale.scheme in SEQUENTIAL_PALETTES)) {
+    errors.push({
+      message: `Spec error: ${channelPath}.scale.scheme "${scale.scheme}" is not a supported map palette`,
+      path: `${channelPath}.scale.scheme`,
+      code: "INVALID_VALUE",
+      suggestion: `Maps support the sequential palettes: ${MAP_PALETTE_NAMES}. The default is "blue".`
+    });
+  }
+}
 var VALID_RANGE_STYLES = /* @__PURE__ */ new Set(["dumbbell", "arrow", "bar"]);
 function validateRangeSpec(spec, errors) {
   const encoding = spec.encoding;
@@ -10942,6 +11028,21 @@ function validateCalendarSpec(spec, errors) {
     seenDays.set(dayKey, i);
   }
 }
+var VALID_RENDER_MODES = /* @__PURE__ */ new Set(["auto", "svg", "canvas"]);
+function validateMarkRenderMode(spec, errors) {
+  const mark = spec.mark;
+  if (!mark || typeof mark !== "object" || Array.isArray(mark)) return;
+  const render = mark.render;
+  if (render === void 0) return;
+  if (typeof render !== "string" || !VALID_RENDER_MODES.has(render)) {
+    errors.push({
+      message: `Spec error: mark.render ${JSON.stringify(render)} is not valid. Must be one of: auto, svg, canvas`,
+      path: "mark.render",
+      code: "INVALID_VALUE",
+      suggestion: 'Use mark: { type: "point", render: "auto" } (default), "canvas" to force the canvas mark layer, or "svg" to force one circle per point.'
+    });
+  }
+}
 function validateChartSpec(spec, errors) {
   const markType = typeof spec.mark === "string" ? spec.mark : spec.mark?.type;
   if (!Array.isArray(spec.data)) {
@@ -11047,6 +11148,7 @@ function validateChartSpec(spec, errors) {
   if (markType === "calendar") {
     validateCalendarSpec(spec, errors);
   }
+  validateMarkRenderMode(spec, errors);
   if (Array.isArray(spec.transform)) {
     const transforms = spec.transform;
     for (let i = 0; i < transforms.length; i++) {
@@ -11145,15 +11247,7 @@ function validateChartSpec(spec, errors) {
         suggestion: `Use one of: ${[...VALID_FIELD_TYPES].join(", ")}`
       });
     }
-    const channelScale = channelObj.scale;
-    if (channelScale && typeof channelScale.scheme === "string" && !resolveSchemeName2(channelScale.scheme)) {
-      errors.push({
-        message: `Spec error: encoding.${channel}.scale.scheme "${channelScale.scheme}" is not a supported scheme name`,
-        path: `encoding.${channel}.scale.scheme`,
-        code: "INVALID_VALUE",
-        suggestion: `Use one of the supported scheme names: ${[...SUPPORTED_SCHEME_NAMES].join(", ")}. Or provide explicit colors via scale.range.`
-      });
-    }
+    checkSchemeName(channelObj, `encoding.${channel}`, errors);
     if (channelRule && channelObj.type && channelRule.allowedTypes.length > 0) {
       if (!channelRule.allowedTypes.includes(channelObj.type)) {
         errors.push({
@@ -11267,6 +11361,52 @@ function validateChartSpec(spec, errors) {
       }
     }
   }
+  for (const channel of ["row", "column"]) {
+    const ch = encoding[channel];
+    if (ch && typeof ch === "object") {
+      const facetCh = ch;
+      if (!facetCh.field || typeof facetCh.field !== "string") {
+        errors.push({
+          message: `Spec error: encoding.${channel}.field is required and must be a non-empty string`,
+          path: `encoding.${channel}.field`,
+          code: "MISSING_FIELD",
+          suggestion: `Add a field property to encoding.${channel} (e.g. { field: "category", type: "nominal" })`
+        });
+      } else if (!dataColumns.has(facetCh.field) && !transformFields.has(facetCh.field)) {
+        errors.push({
+          message: `Spec error: encoding.${channel}.field "${facetCh.field}" does not exist in data. Available columns: ${availableColumns}`,
+          path: `encoding.${channel}.field`,
+          code: "DATA_FIELD_MISSING",
+          suggestion: `Use one of the available data columns: ${availableColumns}.${didYouMean(facetCh.field, columnList)}`
+        });
+      }
+      if (!facetCh.type || facetCh.type !== "nominal" && facetCh.type !== "ordinal") {
+        errors.push({
+          message: `Spec error: encoding.${channel}.type must be "nominal" or "ordinal"${facetCh.type ? `, got "${facetCh.type}"` : ""}`,
+          path: `encoding.${channel}.type`,
+          code: facetCh.type ? "INVALID_VALUE" : "MISSING_FIELD",
+          suggestion: `Set encoding.${channel}.type to "nominal" or "ordinal"`
+        });
+      }
+      if (encoding.facet && typeof encoding.facet === "object") {
+        errors.push({
+          message: `Spec error: encoding.${channel} and encoding.facet cannot be used together`,
+          path: `encoding.${channel}`,
+          code: "INVALID_VALUE",
+          suggestion: `Use either encoding.${channel} or encoding.facet, not both`
+        });
+      }
+      const otherChannel = channel === "row" ? "column" : "row";
+      if (encoding[otherChannel]) {
+        errors.push({
+          message: "Spec error: encoding.row and encoding.column cannot be used together (cross-product faceting is not yet supported)",
+          path: `encoding.${channel}`,
+          code: "INVALID_VALUE",
+          suggestion: "Use encoding.facet with columns for grid layout, or use only row or column"
+        });
+      }
+    }
+  }
   if (spec.darkMode !== void 0 && !VALID_DARK_MODES.has(spec.darkMode)) {
     errors.push({
       message: `Spec error: darkMode must be "auto", "force", or "off"`,
@@ -11479,7 +11619,7 @@ function validateGraphSpec(spec, errors) {
         message: `Spec error: edges[${i}].source "${edge.source}" does not reference an existing node id`,
         path: `edges[${i}].source`,
         code: "DATA_FIELD_MISSING",
-        suggestion: `Use one of the existing node ids: ${[...nodeIds].slice(0, 5).join(", ")}${nodeIds.size > 5 ? "..." : ""}`
+        suggestion: `Use one of the existing node ids: ${[...nodeIds].slice(0, 5).join(", ")}${nodeIds.size > 5 ? "..." : ""}.${didYouMean(edge.source, [...nodeIds])}`
       });
     }
     if (typeof edge.target !== "string" || edge.target === "") {
@@ -11494,40 +11634,60 @@ function validateGraphSpec(spec, errors) {
         message: `Spec error: edges[${i}].target "${edge.target}" does not reference an existing node id`,
         path: `edges[${i}].target`,
         code: "DATA_FIELD_MISSING",
-        suggestion: `Use one of the existing node ids: ${[...nodeIds].slice(0, 5).join(", ")}${nodeIds.size > 5 ? "..." : ""}`
+        suggestion: `Use one of the existing node ids: ${[...nodeIds].slice(0, 5).join(", ")}${nodeIds.size > 5 ? "..." : ""}.${didYouMean(edge.target, [...nodeIds])}`
       });
     }
   }
   if (spec.encoding && typeof spec.encoding === "object") {
     const encoding = spec.encoding;
-    const firstNode = nodes[0];
-    const firstEdge = edges.length > 0 ? edges[0] : null;
-    const nodeFields = firstNode ? new Set(Object.keys(firstNode)) : /* @__PURE__ */ new Set();
-    const edgeFields = firstEdge ? new Set(Object.keys(firstEdge)) : /* @__PURE__ */ new Set();
-    const nodeChannels = ["nodeColor", "nodeSize", "nodeLabel"];
+    const nodeFields = /* @__PURE__ */ new Set();
+    for (const node of nodes) {
+      if (node && typeof node === "object") {
+        for (const key of Object.keys(node)) nodeFields.add(key);
+      }
+    }
+    const edgeFields = /* @__PURE__ */ new Set();
+    for (const edge of edges) {
+      if (edge && typeof edge === "object") {
+        for (const key of Object.keys(edge)) edgeFields.add(key);
+      }
+    }
+    const nodeChannels = [
+      "nodeColor",
+      "nodeSize",
+      "nodeOpacity",
+      "nodeLabel",
+      "nodeLabelPriority"
+    ];
     for (const channel of nodeChannels) {
       const ch = encoding[channel];
-      if (ch?.field && typeof ch.field === "string" && !nodeFields.has(ch.field)) {
+      if (ch?.field && typeof ch.field === "string" && nodes.length > 0 && !nodeFields.has(ch.field)) {
         errors.push({
           message: `Spec error: encoding.${channel}.field "${ch.field}" does not exist on nodes. Available fields: ${[...nodeFields].join(", ")}`,
           path: `encoding.${channel}.field`,
           code: "DATA_FIELD_MISSING",
-          suggestion: `Use one of the node fields: ${[...nodeFields].join(", ")}`
+          suggestion: `Use one of the node fields: ${[...nodeFields].join(", ")}.${didYouMean(ch.field, [...nodeFields])}`
         });
       }
     }
-    const edgeChannels = ["edgeColor", "edgeWidth"];
+    const edgeChannels = ["edgeColor", "edgeWidth", "edgeStyle"];
     for (const channel of edgeChannels) {
       const ch = encoding[channel];
-      if (ch?.field && typeof ch.field === "string" && firstEdge && !edgeFields.has(ch.field)) {
+      if (ch?.field && typeof ch.field === "string" && edges.length > 0 && !edgeFields.has(ch.field)) {
         errors.push({
           message: `Spec error: encoding.${channel}.field "${ch.field}" does not exist on edges. Available fields: ${[...edgeFields].join(", ")}`,
           path: `encoding.${channel}.field`,
           code: "DATA_FIELD_MISSING",
-          suggestion: `Use one of the edge fields: ${[...edgeFields].join(", ")}`
+          suggestion: `Use one of the edge fields: ${[...edgeFields].join(", ")}.${didYouMean(ch.field, [...edgeFields])}`
         });
       }
     }
+    checkSchemeUnused(
+      encoding,
+      errors,
+      "graph colors come from scale.range and scale.domain",
+      "Remove scale.scheme. To customize graph colors, provide explicit colors via scale.range."
+    );
   }
   if (spec.layout && typeof spec.layout === "object") {
     const layout = spec.layout;
@@ -11581,7 +11741,8 @@ function validateSankeySpec(spec, errors) {
   }
   const encoding = spec.encoding;
   const dataColumns = new Set(Object.keys(firstRow));
-  const availableColumns = [...dataColumns].join(", ");
+  const columnList = [...dataColumns];
+  const availableColumns = columnList.join(", ");
   for (const channel of ["source", "target", "value"]) {
     const ch = encoding[channel];
     if (!ch || typeof ch !== "object") {
@@ -11589,7 +11750,7 @@ function validateSankeySpec(spec, errors) {
         message: `Spec error: sankey encoding requires "${channel}" channel`,
         path: `encoding.${channel}`,
         code: "MISSING_FIELD",
-        suggestion: `Add encoding.${channel} with a field from your data (${availableColumns}). Example: ${channel}: { field: "${[...dataColumns][0] ?? "myField"}", type: "${channel === "value" ? "quantitative" : "nominal"}" }`
+        suggestion: `Add encoding.${channel} with a field from your data (${availableColumns}). Example: ${channel}: { field: "${columnList[0] ?? "myField"}", type: "${channel === "value" ? "quantitative" : "nominal"}" }`
       });
       continue;
     }
@@ -11607,10 +11768,16 @@ function validateSankeySpec(spec, errors) {
         message: `Spec error: encoding.${channel}.field "${ch.field}" does not exist in data. Available columns: ${availableColumns}`,
         path: `encoding.${channel}.field`,
         code: "DATA_FIELD_MISSING",
-        suggestion: `Use one of the available data columns: ${availableColumns}`
+        suggestion: `Use one of the available data columns: ${availableColumns}.${didYouMean(ch.field, columnList)}`
       });
     }
   }
+  checkSchemeUnused(
+    encoding,
+    errors,
+    "sankey node colors cycle the theme categorical palette",
+    "Remove scale.scheme. To customize sankey colors, set theme.colors.categorical."
+  );
   if (spec.darkMode !== void 0 && !VALID_DARK_MODES.has(spec.darkMode)) {
     errors.push({
       message: 'Spec error: darkMode must be "auto", "force", or "off"',
@@ -11670,7 +11837,8 @@ function validateTileMapSpec(spec, errors) {
     }
     const encoding = spec.encoding;
     const dataColumns = new Set(Object.keys(firstRow));
-    const availableColumns = [...dataColumns].join(", ");
+    const columnList = [...dataColumns];
+    const availableColumns = columnList.join(", ");
     for (const channel of ["state", "value"]) {
       const ch = encoding[channel];
       if (!ch || typeof ch !== "object") {
@@ -11678,7 +11846,7 @@ function validateTileMapSpec(spec, errors) {
           message: `Spec error: tilemap encoding requires "${channel}" channel`,
           path: `encoding.${channel}`,
           code: "MISSING_FIELD",
-          suggestion: `Add encoding.${channel} with a field from your data (${availableColumns}). Example: ${channel}: { field: "${[...dataColumns][0] ?? "myField"}", type: "${channel === "value" ? "quantitative" : "nominal"}" }`
+          suggestion: `Add encoding.${channel} with a field from your data (${availableColumns}). Example: ${channel}: { field: "${columnList[0] ?? "myField"}", type: "${channel === "value" ? "quantitative" : "nominal"}" }`
         });
         continue;
       }
@@ -11696,11 +11864,19 @@ function validateTileMapSpec(spec, errors) {
           message: `Spec error: encoding.${channel}.field "${ch.field}" does not exist in data. Available columns: ${availableColumns}`,
           path: `encoding.${channel}.field`,
           code: "DATA_FIELD_MISSING",
-          suggestion: `Use one of the available data columns: ${availableColumns}`
+          suggestion: `Use one of the available data columns: ${availableColumns}.${didYouMean(ch.field, columnList)}`
         });
       }
     }
   }
+  if (spec.encoding && typeof spec.encoding === "object") {
+    checkSchemeUnused(
+      spec.encoding,
+      errors,
+      "tilemap fills come from the top-level palette property",
+      `Remove scale.scheme and set the top-level palette property instead, e.g. palette: "green". Supported: ${MAP_PALETTE_NAMES}.`
+    );
+  }
   if (spec.darkMode !== void 0 && !VALID_DARK_MODES.has(spec.darkMode)) {
     errors.push({
       message: 'Spec error: darkMode must be "auto", "force", or "off"',
@@ -11739,6 +11915,16 @@ function validateMapSpec(spec, errors) {
     });
     return;
   }
+  const mapEncoding = spec.encoding;
+  if (mapEncoding.color && typeof mapEncoding.color === "object") {
+    checkMapSchemeName(mapEncoding.color, "encoding.color", errors);
+  }
+  if (spec.points && typeof spec.points === "object") {
+    const pointsLayer = spec.points;
+    if (pointsLayer.color && typeof pointsLayer.color === "object") {
+      checkMapSchemeName(pointsLayer.color, "points.color", errors);
+    }
+  }
   if ("focus" in geo && geo.focus !== void 0 && geo.focus !== null) {
     const focus = geo.focus;
     if (typeof focus === "string" || typeof focus === "number") {
@@ -11755,12 +11941,31 @@ function validateMapSpec(spec, errors) {
       }
     } else if (typeof focus === "object") {
       const focusObj = focus;
-      if (!("features" in focusObj) || focusObj.features == null) {
+      if ("points" in focusObj) {
+        const pts = focusObj.points;
+        const isSubset = typeof pts === "object" && pts !== null && typeof pts.field === "string" && "value" in pts;
+        if (pts !== true && !isSubset) {
+          errors.push({
+            message: "Spec error: geo.focus.points must be true or { field: string, value: string | number }",
+            path: "geo.focus.points",
+            code: "INVALID_TYPE",
+            suggestion: 'Use { points: true } to fit all points, or { points: { field: "rating", value: "F" } } to fit a subset.'
+          });
+        }
+        if (focusObj.padding !== void 0 && typeof focusObj.padding !== "number") {
+          errors.push({
+            message: "Spec error: geo.focus.padding must be a number",
+            path: "geo.focus.padding",
+            code: "INVALID_TYPE",
+            suggestion: "Provide padding as a number in map-local units, e.g. padding: 16"
+          });
+        }
+      } else if (!("features" in focusObj) || focusObj.features == null) {
         errors.push({
-          message: 'Spec error: geo.focus object must have a "features" property',
+          message: 'Spec error: geo.focus object must have a "features" or "points" property',
           path: "geo.focus.features",
           code: "MISSING_FIELD",
-          suggestion: 'Provide feature id(s) to focus on, e.g. geo: { focus: { features: "36", padding: 32 } }'
+          suggestion: 'Provide feature id(s) to focus on, e.g. { features: "36", padding: 32 }, or { points: true } to fit the point cluster.'
         });
       } else {
         const feats = focusObj.features;
@@ -11794,32 +11999,98 @@ function validateMapSpec(spec, errors) {
       }
     } else {
       errors.push({
-        message: "Spec error: geo.focus must be a string, number, array of ids, or object with { features, padding? }",
+        message: "Spec error: geo.focus must be a string, number, array of ids, or object with { features, padding? } or { points: true, padding? }",
         path: "geo.focus",
         code: "INVALID_TYPE",
-        suggestion: 'Use a feature id, array of ids, or { features: "36", padding: 16 }. Pass null to clear focus.'
+        suggestion: 'Use a feature id, array of ids, { features: "36", padding: 16 }, or { points: true }. Pass null to clear focus.'
       });
     }
   }
   const encoding = spec.encoding;
-  for (const channel of ["key", "color"]) {
-    const ch = encoding[channel];
-    if (!ch || typeof ch !== "object") {
+  const hasPoints = spec.points && typeof spec.points === "object" && !Array.isArray(spec.points);
+  const specData = spec.data;
+  const isBasemapOnly = hasPoints && (!specData || specData.length === 0);
+  const keyCh = encoding.key;
+  if (!isBasemapOnly) {
+    if (!keyCh || typeof keyCh !== "object") {
       errors.push({
-        message: `Spec error: map encoding requires "${channel}" channel`,
-        path: `encoding.${channel}`,
+        message: 'Spec error: map encoding requires "key" channel',
+        path: "encoding.key",
         code: "MISSING_FIELD",
-        suggestion: `Add encoding.${channel}, e.g. ${channel}: { field: "${channel === "key" ? "id" : "value"}", type: "${channel === "key" ? "nominal" : "quantitative"}" }`
+        suggestion: 'Add encoding.key, e.g. key: { field: "id", type: "nominal" }'
+      });
+    } else if (!keyCh.field || typeof keyCh.field !== "string") {
+      errors.push({
+        message: 'Spec error: encoding.key must have a "field" string',
+        path: "encoding.key.field",
+        code: "MISSING_FIELD",
+        suggestion: 'Add a field name, e.g. key: { field: "id" }'
       });
-      continue;
     }
-    if (!ch.field || typeof ch.field !== "string") {
+  }
+  const colorCh = encoding.color;
+  if (!hasPoints) {
+    if (!colorCh || typeof colorCh !== "object") {
       errors.push({
-        message: `Spec error: encoding.${channel} must have a "field" string`,
-        path: `encoding.${channel}.field`,
+        message: 'Spec error: map encoding requires "color" channel (or add a "points" layer for basemap-only mode)',
+        path: "encoding.color",
         code: "MISSING_FIELD",
-        suggestion: `Add a field name, e.g. ${channel}: { field: "${channel === "key" ? "id" : "value"}" }`
+        suggestion: 'Add encoding.color, e.g. color: { field: "value", type: "quantitative" }'
       });
+    } else if (!colorCh.field || typeof colorCh.field !== "string") {
+      errors.push({
+        message: 'Spec error: encoding.color must have a "field" string',
+        path: "encoding.color.field",
+        code: "MISSING_FIELD",
+        suggestion: 'Add a field name, e.g. color: { field: "value" }'
+      });
+    }
+  } else if (colorCh && typeof colorCh === "object" && (!colorCh.field || typeof colorCh.field !== "string")) {
+    errors.push({
+      message: 'Spec error: encoding.color must have a "field" string when provided',
+      path: "encoding.color.field",
+      code: "MISSING_FIELD",
+      suggestion: 'Add a field name, e.g. color: { field: "value" }'
+    });
+  }
+  if (hasPoints) {
+    const points = spec.points;
+    if (!Array.isArray(points.data)) {
+      errors.push({
+        message: "Spec error: points.data must be an array of data rows",
+        path: "points.data",
+        code: "INVALID_TYPE",
+        suggestion: "Provide data as an array of objects with lat/lng fields"
+      });
+    }
+    for (const ch of ["longitude", "latitude"]) {
+      const enc = points[ch];
+      if (!enc || typeof enc !== "object") {
+        errors.push({
+          message: `Spec error: points requires "${ch}" encoding channel`,
+          path: `points.${ch}`,
+          code: "MISSING_FIELD",
+          suggestion: `Add points.${ch}, e.g. ${ch}: { field: "${ch === "longitude" ? "lon" : "lat"}", type: "quantitative" }`
+        });
+      } else if (!enc.field || typeof enc.field !== "string") {
+        errors.push({
+          message: `Spec error: points.${ch} must have a "field" string`,
+          path: `points.${ch}.field`,
+          code: "MISSING_FIELD",
+          suggestion: `Add a field name, e.g. ${ch}: { field: "${ch === "longitude" ? "lon" : "lat"}" }`
+        });
+      }
+    }
+    for (const ch of ["size", "color", "key"]) {
+      const enc = points[ch];
+      if (enc && typeof enc === "object" && (!enc.field || typeof enc.field !== "string")) {
+        errors.push({
+          message: `Spec error: points.${ch} must have a "field" string when provided`,
+          path: `points.${ch}.field`,
+          code: "MISSING_FIELD",
+          suggestion: `Add a field name, e.g. ${ch}: { field: "myField" }`
+        });
+      }
     }
   }
 }
@@ -11863,7 +12134,8 @@ function validateBarListSpec(spec, errors) {
   }
   const encoding = spec.encoding;
   const dataColumns = new Set(Object.keys(firstRow));
-  const availableColumns = [...dataColumns].join(", ");
+  const columnList = [...dataColumns];
+  const availableColumns = columnList.join(", ");
   for (const channel of ["label", "value"]) {
     const ch = encoding[channel];
     if (!ch || typeof ch !== "object") {
@@ -11871,7 +12143,7 @@ function validateBarListSpec(spec, errors) {
         message: `Spec error: barlist encoding requires "${channel}" channel`,
         path: `encoding.${channel}`,
         code: "MISSING_FIELD",
-        suggestion: `Add encoding.${channel} with a field from your data (${availableColumns}). Example: ${channel}: { field: "${[...dataColumns][0] ?? "myField"}", type: "${channel === "value" ? "quantitative" : "nominal"}" }`
+        suggestion: `Add encoding.${channel} with a field from your data (${availableColumns}). Example: ${channel}: { field: "${columnList[0] ?? "myField"}", type: "${channel === "value" ? "quantitative" : "nominal"}" }`
       });
       continue;
     }
@@ -11889,7 +12161,7 @@ function validateBarListSpec(spec, errors) {
         message: `Spec error: encoding.${channel}.field "${ch.field}" does not exist in data. Available columns: ${availableColumns}`,
         path: `encoding.${channel}.field`,
         code: "DATA_FIELD_MISSING",
-        suggestion: `Use one of the available data columns: ${availableColumns}`
+        suggestion: `Use one of the available data columns: ${availableColumns}.${didYouMean(ch.field, columnList)}`
       });
     }
   }
@@ -11902,10 +12174,16 @@ function validateBarListSpec(spec, errors) {
         message: `Spec error: encoding.${channel}.field "${field}" does not exist in data. Available columns: ${availableColumns}`,
         path: `encoding.${channel}.field`,
         code: "DATA_FIELD_MISSING",
-        suggestion: `Use one of the available data columns: ${availableColumns}`
+        suggestion: `Use one of the available data columns: ${availableColumns}.${didYouMean(field, columnList)}`
       });
     }
   }
+  checkSchemeUnused(
+    encoding,
+    errors,
+    "bar list colors cycle the built-in barlist palette",
+    "Remove scale.scheme. Bar list colors are not configurable via encoding; they cycle the built-in palette."
+  );
   if (spec.darkMode !== void 0 && !VALID_DARK_MODES.has(spec.darkMode)) {
     errors.push({
       message: 'Spec error: darkMode must be "auto", "force", or "off"',
@@ -11988,6 +12266,22 @@ function validateLayerSpec(spec, errors) {
     }
   }
 }
+function validateAnimation(spec, errors) {
+  const animation = spec.animation;
+  if (!animation || typeof animation !== "object" || Array.isArray(animation)) return;
+  const update = animation.update;
+  if (!update || typeof update !== "object" || Array.isArray(update)) return;
+  const maxMarks = update.maxMarks;
+  if (maxMarks === void 0) return;
+  if (typeof maxMarks !== "number" || !Number.isFinite(maxMarks) || maxMarks < 1) {
+    errors.push({
+      message: `Spec error: animation.update.maxMarks must be a number >= 1, got ${JSON.stringify(maxMarks)}`,
+      path: "animation.update.maxMarks",
+      code: "INVALID_VALUE",
+      suggestion: "Set animation.update.maxMarks to the largest mark count that should still tween, e.g. animation: { update: { maxMarks: 5000 } }. Omit it to use the default of 500."
+    });
+  }
+}
 function validateSpec(spec) {
   const errors = [];
   if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
@@ -12096,6 +12390,9 @@ function validateSpec(spec) {
   } else if (isBarList) {
     validateBarListSpec(obj, errors);
   }
+  if (!isGraph) {
+    validateAnimation(obj, errors);
+  }
   if (errors.length > 0) {
     return { valid: false, errors, normalized: null };
   }
@@ -12119,6 +12416,36 @@ ${errorMessages}`);
   return { spec: normalized, warnings };
 }
 
+// src/layout/shared.ts
+function chromeToInput(chrome) {
+  return {
+    eyebrow: chrome.eyebrow,
+    title: chrome.title,
+    subtitle: chrome.subtitle,
+    source: chrome.source,
+    byline: chrome.byline,
+    footer: chrome.footer,
+    brand: chrome.brand
+  };
+}
+function scalePadding(basePadding, width, height) {
+  const minDim = Math.min(width, height);
+  if (minDim >= 500) return basePadding;
+  if (minDim <= 200) return Math.max(Math.round(basePadding * 0.5), 4);
+  const t = (minDim - 200) / 300;
+  return Math.max(Math.round(basePadding * (0.5 + t * 0.5)), 4);
+}
+function bottomMargin(bottomHeight, padding, xAxisHeight) {
+  return padding + bottomHeight + xAxisHeight;
+}
+var INLINE_TICK_OVERHANG_PAD = 6;
+function resolveChromeLayout(spec, options) {
+  const encoding = spec?.encoding;
+  const isFaceted = !!(encoding?.facet || encoding?.row || encoding?.column);
+  if (isFaceted) return "subtract";
+  return spec?.chromeLayout ?? options?.chromeLayout ?? "subtract";
+}
+
 // src/barlist/compile-barlist.ts
 var DEFAULT_ROW_GAP = 8;
 var LABEL_BAR_GAP = 12;
@@ -12166,14 +12493,19 @@ function compileBarList(spec, options) {
     watermark
   );
   const padding = theme.spacing.padding;
+  const chromeLayout = resolveChromeLayout(
+    spec,
+    options
+  );
+  const grownHeight = chromeLayout === "grow" ? options.height + chrome.topHeight + chrome.bottomHeight : options.height;
   const fullArea = {
     x: padding,
     y: padding + chrome.topHeight,
     width: options.width - padding * 2,
-    height: options.height - chrome.topHeight - chrome.bottomHeight - padding * 2
+    height: chromeLayout === "grow" ? options.height - padding * 2 : options.height - chrome.topHeight - chrome.bottomHeight - padding * 2
   };
   if (fullArea.width <= 0 || fullArea.height <= 0) {
-    return emptyLayout2(chrome, theme, options, watermark);
+    return emptyLayout2(chrome, theme, { ...options, height: grownHeight }, watermark);
   }
   const labelField = barlistSpec.encoding.label.field;
   const valueField = barlistSpec.encoding.value.field;
@@ -12358,7 +12690,7 @@ function compileBarList(spec, options) {
     a11y,
     theme,
     width: options.width,
-    height: options.height,
+    height: grownHeight,
     animation: resolvedAnimation,
     watermark,
     measureText
@@ -13650,7 +13982,8 @@ function computeLegendContent(spec, strategy, theme, availableWidth, availableHe
     fill: theme.colors.text,
     lineHeight: 1.3
   };
-  const resolvedPosition = spec.legend?.position ?? (strategy.legendPosition === "right" ? "right" : "top");
+  const specPosition = spec.legend?.position === "top-left" ? "top" : spec.legend?.position;
+  const resolvedPosition = specPosition ?? (strategy.legendPosition === "right" ? "right" : "top");
   if (entries.length === 0) {
     return emptyContent(resolvedPosition, theme);
   }
@@ -14651,30 +14984,6 @@ function computeAxes(scales, chartArea, strategy, theme, measureText, dataContex
   return result;
 }
 
-// src/layout/shared.ts
-function chromeToInput(chrome) {
-  return {
-    eyebrow: chrome.eyebrow,
-    title: chrome.title,
-    subtitle: chrome.subtitle,
-    source: chrome.source,
-    byline: chrome.byline,
-    footer: chrome.footer,
-    brand: chrome.brand
-  };
-}
-function scalePadding(basePadding, width, height) {
-  const minDim = Math.min(width, height);
-  if (minDim >= 500) return basePadding;
-  if (minDim <= 200) return Math.max(Math.round(basePadding * 0.5), 4);
-  const t = (minDim - 200) / 300;
-  return Math.max(Math.round(basePadding * (0.5 + t * 0.5)), 4);
-}
-function bottomMargin(bottomHeight, padding, xAxisHeight) {
-  return padding + bottomHeight + xAxisHeight;
-}
-var INLINE_TICK_OVERHANG_PAD = 6;
-
 // src/layout/plan.ts
 function createMeasureFn(measureText) {
   if (measureText) {
@@ -14896,7 +15205,9 @@ function resolveLayoutPlan(chartSpec, renderSpec, options, theme, strategy, wate
     if (hasTopLegend) topMargin += TOP_LEGEND_GAP_ABOVE + legendContent.height + gap;
     topMargin += effectiveTopAxisGap;
     const bMargin = bottomMargin(chrome.bottomHeight, padding, xAxisExtent);
-    const chartHeight = Math.max(0, height - topMargin - bMargin);
+    const chromeLayout = resolveChromeLayout(renderSpec, options);
+    const effectiveHeight = chromeLayout === "grow" ? height + chrome.topHeight + chrome.bottomHeight : height;
+    const chartHeight = Math.max(0, effectiveHeight - topMargin - bMargin);
     const rightMargin = hPad + (isRadial ? hPad : axisMargin);
     const rightAxisReserve = options.rightAxisReserve ?? 0;
     const provisionalArea = {
@@ -15048,11 +15359,12 @@ function compileLayer(spec, options, compileChart2) {
     const singleSpec = buildPrimarySpec(leaves, spec);
     return compileChart2(singleSpec, options);
   }
+  const layerOptions = { ...options, layered: true };
   if (spec.resolve?.scale?.y === "independent") {
-    return compileLayerIndependent(leaves, spec, options, compileChart2);
+    return compileLayerIndependent(leaves, spec, layerOptions, compileChart2);
   }
   const primarySpec = buildPrimarySpec(leaves, spec);
-  const primaryLayout = compileChart2(primarySpec, options);
+  const primaryLayout = compileChart2(primarySpec, layerOptions);
   const allMarks = [];
   const seenLabels = /* @__PURE__ */ new Set();
   const pLegend = primaryLayout.legend;
@@ -15065,7 +15377,7 @@ function compileLayer(spec, options, compileChart2) {
     zIndex: leaf.zIndex ?? i
   }));
   indexedLeaves.sort((a, b) => a.zIndex - b.zIndex);
-  const leafOptions = { ...options, frozenChartArea: primaryLayout.area };
+  const leafOptions = { ...layerOptions, frozenChartArea: primaryLayout.area };
   const sharedDomains = computeSharedDomains(leaves);
   for (const { leaf } of indexedLeaves) {
     const themedLeaf = {
@@ -15174,11 +15486,9 @@ function compileLayerIndependent(leaves, layerSpec, options, compileChart2) {
   };
   const xField0 = leaf0.encoding?.x?.field;
   const xField1 = leaf1.encoding?.x?.field;
-  const unionXValues = /* @__PURE__ */ new Set();
-  if (xField0) for (const row of leaf0.data) unionXValues.add(row[xField0]);
-  if (xField1) for (const row of leaf1.data) unionXValues.add(row[xField1]);
-  let leaf0WithUnionX = ensureXDomainCoverage(leaf0, xField0, unionXValues);
-  let leaf1WithUnionX = ensureXDomainCoverage(leaf1, xField1, unionXValues);
+  const union = withUnionXDomain(leaf0, leaf1);
+  let leaf0WithUnionX = union.leaf0;
+  let leaf1WithUnionX = union.leaf1;
   const aligned = alignYDomains(leaf0WithUnionX, leaf1WithUnionX);
   if (aligned) {
     leaf0WithUnionX = withYDomain(leaf0WithUnionX, aligned.domain0);
@@ -15325,20 +15635,75 @@ function compileLayerIndependent(leaves, layerSpec, options, compileChart2) {
     tooltipDescriptors: mergedTooltips
   };
 }
-function ensureXDomainCoverage(leaf, xField, allXValues) {
-  if (!xField || allXValues.size === 0) return leaf;
-  const existingXValues = /* @__PURE__ */ new Set();
-  for (const row of leaf.data) existingXValues.add(row[xField]);
-  const missingRows = [];
-  for (const xVal of allXValues) {
-    if (!existingXValues.has(xVal)) {
-      missingRows.push({ [xField]: xVal });
+function withXDomain(leaf, domain) {
+  if (!leaf.encoding?.x) return leaf;
+  return {
+    ...leaf,
+    encoding: {
+      ...leaf.encoding,
+      x: {
+        ...leaf.encoding.x,
+        scale: {
+          ...leaf.encoding.x.scale,
+          domain
+        }
+      }
+    }
+  };
+}
+function withUnionXDomain(leaf0, leaf1) {
+  const xEnc0 = leaf0.encoding?.x;
+  const xEnc1 = leaf1.encoding?.x;
+  const xField0 = xEnc0?.field;
+  const xField1 = xEnc1?.field;
+  if (!xField0 || !xField1) return { leaf0, leaf1 };
+  const xType = xEnc0?.type ?? xEnc1?.type;
+  const pinned0 = xEnc0?.scale?.domain !== void 0;
+  const pinned1 = xEnc1?.scale?.domain !== void 0;
+  if (pinned0 && pinned1) return { leaf0, leaf1 };
+  const values0 = leaf0.data.map((row) => row[xField0]);
+  const values1 = leaf1.data.map((row) => row[xField1]);
+  const allValues = [...values0, ...values1].filter((v) => v != null);
+  if (allValues.length === 0) return { leaf0, leaf1 };
+  let domain;
+  if (xType === "temporal") {
+    let minMs = Number.POSITIVE_INFINITY;
+    let maxMs = Number.NEGATIVE_INFINITY;
+    for (const v of allValues) {
+      const ms = (v instanceof Date ? v : new Date(String(v))).getTime();
+      if (Number.isNaN(ms)) continue;
+      if (ms < minMs) minMs = ms;
+      if (ms > maxMs) maxMs = ms;
+    }
+    if (minMs <= maxMs) {
+      domain = [new Date(minMs).toISOString(), new Date(maxMs).toISOString()];
+    }
+  } else if (xType === "quantitative") {
+    let min4 = Number.POSITIVE_INFINITY;
+    let max4 = Number.NEGATIVE_INFINITY;
+    for (const v of allValues) {
+      const n = typeof v === "number" ? v : Number(v);
+      if (!Number.isFinite(n)) continue;
+      if (n < min4) min4 = n;
+      if (n > max4) max4 = n;
+    }
+    if (min4 <= max4) domain = [min4, max4];
+  } else {
+    const seen = /* @__PURE__ */ new Set();
+    const categories = [];
+    for (const v of allValues) {
+      const s = String(v);
+      if (!seen.has(s)) {
+        seen.add(s);
+        categories.push(s);
+      }
     }
+    if (categories.length > 0) domain = categories;
   }
-  if (missingRows.length === 0) return leaf;
+  if (domain === void 0) return { leaf0, leaf1 };
   return {
-    ...leaf,
-    data: [...leaf.data, ...missingRows]
+    leaf0: pinned0 ? leaf0 : withXDomain(leaf0, domain),
+    leaf1: pinned1 ? leaf1 : withXDomain(leaf1, domain)
   };
 }
 function alignYDomains(leaf0, leaf1) {
@@ -15457,6 +15822,10 @@ function buildPrimarySpec(leaves, layerSpec) {
     ...leaves[0],
     data: allData,
     chrome: layerSpec.chrome ?? leaves[0].chrome,
+    // Annotations come from the parent LayerSpec when present, otherwise
+    // the first flattened leaf's. Later leaves' annotations are silently
+    // dropped. The dual-axis path (compileLayerIndependent) explicitly
+    // clears the secondary axis spec's annotations.
     annotations: layerSpec.annotations ?? leaves[0].annotations,
     labels: layerSpec.labels ?? leaves[0].labels,
     legend: layerSpec.legend ?? leaves[0].legend,
@@ -15613,6 +15982,34 @@ function collectContrastWarnings(scales, markType, theme) {
   return warnings;
 }
 
+// src/compiler/mark-render-mode.ts
+var AUTO_CANVAS_THRESHOLD = 1e3;
+var AUTO_ENABLED = true;
+function resolveMarkRenderMode(args, warnings = []) {
+  const { markDef, markType, pointCount, display, faceted, layered } = args;
+  const requested = markDef?.render ?? "auto";
+  if (requested === "svg") return "svg";
+  const refusal = describeRefusal(markType, display, faceted, layered);
+  if (refusal) {
+    if (requested === "canvas") {
+      warnings.push(
+        `Chart warning: mark.render "canvas" is not supported ${refusal}; rendering marks as SVG instead.`
+      );
+    }
+    return "svg";
+  }
+  if (requested === "canvas") return "canvas";
+  if (!AUTO_ENABLED) return "svg";
+  return pointCount > AUTO_CANVAS_THRESHOLD ? "canvas" : "svg";
+}
+function describeRefusal(markType, display, faceted, layered) {
+  if (markType !== "point") return `for ${markType} marks (point marks only)`;
+  if (faceted) return "on faceted charts";
+  if (layered) return "on layered charts";
+  if (display === "sparkline") return "on sparklines";
+  return void 0;
+}
+
 // src/compiler/sparkline-defaults.ts
 var TREND_DEADBAND = 5e-4;
 function computeTrend(values) {
@@ -15691,7 +16088,7 @@ import {
   HPAD_COMPACT_FRACTION as HPAD_COMPACT_FRACTION2,
   HPAD_COMPACT_MIN as HPAD_COMPACT_MIN2,
   resolveTheme as resolveTheme3,
-  SEQUENTIAL_PALETTES
+  SEQUENTIAL_PALETTES as SEQUENTIAL_PALETTES2
 } from "@opendata-ai/openchart-core";
 
 // ../../node_modules/.bun/d3-geo@3.1.1/node_modules/d3-geo/src/math.js
@@ -17669,13 +18066,32 @@ function joinDataToFeatures(features, data, dataKeyField, featureIdField) {
 
 // src/geo/projections.ts
 var MERCATOR_FIT_MIN_LAT = -60;
-function createProjection(type, width, height, geojson) {
+function createProjection(type, width, height, geojson, inset = 0) {
   if (type === "identity") {
+    if (inset > 0) {
+      return identity_default4().fitExtent(
+        [
+          [inset, inset],
+          [width - inset, height - inset]
+        ],
+        geojson
+      );
+    }
     return identity_default4().fitSize([width, height], geojson);
   }
   const projection2 = type === "albersUsa" ? albersUsa_default() : type === "equalEarth" ? equalEarth_default() : mercator_default();
   const fitGeometry = type === "mercator" ? excludePolarFeatures(geojson) : geojson;
-  projection2.fitSize([width, height], fitGeometry);
+  if (inset > 0) {
+    projection2.fitExtent(
+      [
+        [inset, inset],
+        [width - inset, height - inset]
+      ],
+      fitGeometry
+    );
+  } else {
+    projection2.fitSize([width, height], fitGeometry);
+  }
   return projection2;
 }
 function excludePolarFeatures(geojson) {
@@ -17695,6 +18111,7 @@ function excludePolarFeatures(geojson) {
 }
 
 // src/geo/compile-map.ts
+var OVERLAY_LEGEND_INSET = 18;
 function validateGeoFeatures(geo) {
   if (!geo.features) {
     throw new Error(
@@ -17752,11 +18169,15 @@ function compileMap(spec, options) {
     watermark
   );
   const padding = getBreakpoint(options.width) === "compact" ? Math.max(HPAD_COMPACT_MIN2, Math.round(theme.spacing.padding * HPAD_COMPACT_FRACTION2)) : theme.spacing.padding;
+  const chromeLayout = resolveChromeLayout(
+    spec,
+    options
+  );
   const fullArea = {
     x: padding,
     y: padding + chrome.topHeight,
     width: options.width - padding * 2,
-    height: options.height - chrome.topHeight - chrome.bottomHeight - padding * 2
+    height: chromeLayout === "grow" ? options.height - padding * 2 : options.height - chrome.topHeight - chrome.bottomHeight - padding * 2
   };
   if (fullArea.width <= 0 || fullArea.height <= 0) {
     return emptyLayout3(chrome, theme, options, watermark);
@@ -17767,11 +18188,13 @@ function compileMap(spec, options) {
   const compileWarnings = [];
   const showLegend = mapSpec.legend?.show !== false;
   const colorEncoding = mapSpec.encoding.color;
-  const isQuantitative = colorEncoding.type === "quantitative";
+  const showChoroplethLegend = showLegend && colorEncoding?.legend !== null;
+  const isQuantitative = colorEncoding?.type === "quantitative";
   const legendPosition = mapSpec.legend?.position === "bottom" ? "bottom" : "top";
+  const pointLegendOverlay = mapSpec.legend?.position === "top-left";
   let legendBlockHeight = 0;
   let continuousContent = null;
-  if (showLegend && isQuantitative) {
+  if (showChoroplethLegend && colorEncoding && isQuantitative) {
     const colorValues = [];
     for (const row of mapSpec.data) {
       const v = row[colorEncoding.field];
@@ -17794,17 +18217,37 @@ function compileMap(spec, options) {
       const labelRowHeight = Math.ceil(theme.fonts.sizes.small * 1.3);
       legendBlockHeight = continuousContent.barHeight + CONTINUOUS_LABEL_GAP + labelRowHeight;
     }
-  } else if (showLegend) {
+  } else if (showChoroplethLegend && colorEncoding) {
     const labelHeight = Math.ceil(theme.fonts.sizes.small * 1.3);
     legendBlockHeight = Math.max(10, labelHeight) + 6;
   }
+  if (showLegend && !pointLegendOverlay && mapSpec.points?.color) {
+    if (mapSpec.points.color.type === "quantitative") {
+      const labelRowHeight = Math.ceil(theme.fonts.sizes.small * 1.3);
+      legendBlockHeight += CONTINUOUS_BAR_HEIGHT + CONTINUOUS_LABEL_GAP + labelRowHeight + 8;
+    } else {
+      const ptLabelHeight = Math.ceil(theme.fonts.sizes.small * 1.3);
+      legendBlockHeight += Math.max(10, ptLabelHeight) + 6 + 8;
+    }
+  }
   const legendReserveGap = legendBlockHeight > 0 ? 8 : 0;
   const mapAreaHeight = fullArea.height - legendBlockHeight - legendReserveGap;
   if (mapAreaHeight <= 0) {
     return emptyLayout3(chrome, theme, options, watermark);
   }
   const projectionType = mapSpec.geo.projection;
-  const projection2 = createProjection(projectionType, fullArea.width, mapAreaHeight, geoCollection);
+  let pointInset = 0;
+  if (mapSpec.points) {
+    const sizeRange = mapSpec.points.size?.scale?.range;
+    pointInset = sizeRange ? sizeRange[1] : SIZE_SCALE_DEFAULTS.mapPoint.range[1];
+  }
+  const projection2 = createProjection(
+    projectionType,
+    fullArea.width,
+    mapAreaHeight,
+    geoCollection,
+    pointInset
+  );
   const pathGen = path_default(projection2);
   if (projectionType !== "identity") {
     for (const feat of geoFeatures) {
@@ -17819,31 +18262,44 @@ function compileMap(spec, options) {
       }
     }
   }
-  const featureObjs = geoFeatures.map((f) => ({
-    id: f.id,
-    properties: f.properties ?? {}
-  }));
-  const { joined, warnings: joinWarnings } = joinDataToFeatures(
-    featureObjs,
-    mapSpec.data,
-    mapSpec.encoding.key.field,
-    mapSpec.geo.idField
-  );
-  compileWarnings.push(...joinWarnings);
+  let joined = /* @__PURE__ */ new Map();
+  if (mapSpec.encoding.key) {
+    const featureObjs = geoFeatures.map((f) => ({
+      id: f.id,
+      properties: f.properties ?? {}
+    }));
+    const joinResult = joinDataToFeatures(
+      featureObjs,
+      mapSpec.data,
+      mapSpec.encoding.key.field,
+      mapSpec.geo.idField
+    );
+    joined = joinResult.joined;
+    const filteredJoinWarnings = mapSpec.data.length === 0 && mapSpec.points ? joinResult.warnings.filter((w) => w.code !== "UNMATCHED_FEATURES") : joinResult.warnings;
+    compileWarnings.push(...filteredJoinWarnings);
+  }
   const droppedFeatures = [];
-  const formatter = buildD3Formatter2(mapSpec.valueFormat) ?? formatNumber3;
+  const formatter = buildD3Formatter2(mapSpec.encoding?.color?.format ?? mapSpec.valueFormat) ?? formatNumber3;
   const neutralFill = isDarkMode ? "#2a2a2a" : "#e8e8e8";
   const neutralStroke = isDarkMode ? "rgba(255,255,255,0.08)" : "rgba(0,0,0,0.06)";
   let featureMarks;
   let continuousLegend = null;
   let categoricalLegend = null;
-  if (isQuantitative) {
+  if (!colorEncoding) {
+    featureMarks = buildBasemapMarks({
+      geoFeatures,
+      pathGen,
+      neutralFill,
+      neutralStroke,
+      droppedFeatures
+    });
+  } else if (isQuantitative) {
     const result = buildQuantitativeMarks({
       geoFeatures,
       pathGen,
       joined,
       colorField: colorEncoding.field,
-      palette: mapSpec.encoding.color.scale?.scheme ?? "blue",
+      palette: colorEncoding.scale?.scheme ?? "blue",
       isDarkMode: !!isDarkMode,
       neutralFill,
       neutralStroke,
@@ -17851,7 +18307,7 @@ function compileMap(spec, options) {
       droppedFeatures
     });
     featureMarks = result.marks;
-    if (showLegend && continuousContent) {
+    if (showChoroplethLegend && continuousContent) {
       const labelStyle = {
         fontFamily: theme.fonts.family,
         fontSize: theme.fonts.sizes.small,
@@ -17893,6 +18349,7 @@ function compileMap(spec, options) {
       pathGen,
       joined,
       colorField: colorEncoding.field,
+      colorScale: colorEncoding.scale,
       isDarkMode: !!isDarkMode,
       neutralFill,
       neutralStroke,
@@ -17900,7 +18357,8 @@ function compileMap(spec, options) {
       fullArea,
       mapAreaHeight,
       legendReserveGap,
-      showLegend,
+      legendPosition,
+      showLegend: showChoroplethLegend,
       droppedFeatures
     });
     featureMarks = result.marks;
@@ -17928,6 +18386,201 @@ function compileMap(spec, options) {
   const interiorStroke = isDarkMode ? "rgba(255,255,255,0.3)" : "rgba(0,0,0,0.15)";
   const outlineStroke = isDarkMode ? "rgba(255,255,255,0.5)" : "rgba(0,0,0,0.3)";
   const borders = { interiorPath, outlinePath, interiorStroke, outlineStroke };
+  const pointMarks = [];
+  let pointCategoricalLegend = null;
+  let pointContinuousLegend = null;
+  if (mapSpec.points) {
+    const pts = mapSpec.points;
+    const lonField = pts.longitude.field;
+    const latField = pts.latitude.field;
+    const keyChannel = pts.key;
+    const sizeScale = buildSizeScale(pts.size, pts.data, SIZE_SCALE_DEFAULTS.mapPoint);
+    let pointColorScale = null;
+    const pointCategories = [];
+    const pointCategoryColors = /* @__PURE__ */ new Map();
+    if (pts.color) {
+      if (pts.color.type === "quantitative") {
+        const colorValues = [];
+        for (const row of pts.data) {
+          const raw = row[pts.color.field];
+          if (raw != null) {
+            const v = Number(raw);
+            if (Number.isFinite(v)) colorValues.push(v);
+          }
+        }
+        if (colorValues.length > 0) {
+          const palette = pts.color.scale?.scheme ?? "blue";
+          const paletteStops = [...SEQUENTIAL_PALETTES2[palette] ?? SEQUENTIAL_PALETTES2.blue];
+          const qScale = quantile2().domain(colorValues).range(paletteStops);
+          pointColorScale = (val) => {
+            const v = Number(val);
+            return Number.isFinite(v) ? qScale(v) : CATEGORICAL_PALETTE[0];
+          };
+        }
+      } else {
+        const explicitDomain = pts.color.scale?.domain;
+        const explicitRange = pts.color.scale?.range;
+        if (explicitDomain && Array.isArray(explicitDomain)) {
+          for (const cat of explicitDomain) {
+            pointCategories.push(String(cat));
+          }
+        }
+        const seen = new Set(pointCategories);
+        for (const row of pts.data) {
+          const raw = row[pts.color.field];
+          if (raw != null) {
+            const cat = String(raw);
+            if (!seen.has(cat)) {
+              seen.add(cat);
+              pointCategories.push(cat);
+            }
+          }
+        }
+        const colorSource = explicitRange && Array.isArray(explicitRange) ? explicitRange : CATEGORICAL_PALETTE;
+        for (let i = 0; i < pointCategories.length; i++) {
+          pointCategoryColors.set(pointCategories[i], colorSource[i % colorSource.length]);
+        }
+        pointColorScale = (val) => {
+          if (val == null) return colorSource[0];
+          return pointCategoryColors.get(String(val)) ?? colorSource[0];
+        };
+      }
+    }
+    const defaultFill = CATEGORICAL_PALETTE[0];
+    const pointOpacity = pts.opacity ?? 0.65;
+    let animIndex = 0;
+    const droppedPoints = [];
+    for (let i = 0; i < pts.data.length; i++) {
+      const row = pts.data[i];
+      const lon = Number(row[lonField]);
+      const lat = Number(row[latField]);
+      if (!Number.isFinite(lon) || !Number.isFinite(lat)) continue;
+      const projected = projection2([lon, lat]);
+      if (!projected) {
+        droppedPoints.push([lon, lat]);
+        continue;
+      }
+      const r = sizeScale ? sizeScale.scale(Number(row[sizeScale.field])) : 5;
+      const fill = pointColorScale && pts.color ? pointColorScale(row[pts.color.field]) : defaultFill;
+      const key = keyChannel ? String(row[keyChannel.field] ?? i) : String(i);
+      const stroke = isDarkMode ? "rgba(0,0,0,0.5)" : "rgba(255,255,255,0.8)";
+      pointMarks.push({
+        type: "map-point",
+        cx: projected[0],
+        cy: projected[1],
+        r,
+        fill,
+        stroke,
+        strokeWidth: 1,
+        fillOpacity: pointOpacity,
+        key,
+        data: row,
+        aria: { role: "img", label: key },
+        animationIndex: animIndex++
+      });
+    }
+    if (droppedPoints.length > 0) {
+      const sample = droppedPoints.slice(0, 3).map(([lo, la]) => `[${lo}, ${la}]`).join(", ");
+      compileWarnings.push({
+        code: "POINT_NULL_PROJECTION",
+        message: `${droppedPoints.length} point(s) project to null and were dropped (e.g. ${sample}). This is common with albersUsa which excludes territories. Consider using projection: "mercator" or "equalEarth".`,
+        context: { count: droppedPoints.length, samples: droppedPoints.slice(0, 5) }
+      });
+    }
+    if (pts.color && pts.color.type !== "quantitative" && pointCategories.length > 0 && showLegend) {
+      const labelStyle = {
+        fontFamily: theme.fonts.family,
+        fontSize: theme.fonts.sizes.small,
+        fontWeight: theme.fonts.weights.normal,
+        fill: theme.colors.text,
+        lineHeight: 1.2
+      };
+      const entries = pointCategories.map((cat) => ({
+        label: cat,
+        color: pointCategoryColors.get(cat),
+        shape: "circle"
+      }));
+      const bottomChoroplethHeight = legendPosition === "bottom" ? continuousLegend?.bounds.height ?? categoricalLegend?.bounds.height ?? 0 : 0;
+      const choroplethLegendGap = bottomChoroplethHeight > 0 ? 8 : 0;
+      const legendX = pointLegendOverlay ? fullArea.x + OVERLAY_LEGEND_INSET : fullArea.x;
+      const legendY = pointLegendOverlay ? fullArea.y + OVERLAY_LEGEND_INSET : fullArea.y + mapAreaHeight + legendReserveGap + bottomChoroplethHeight + choroplethLegendGap;
+      const legendWidth = pointLegendOverlay ? fullArea.width - OVERLAY_LEGEND_INSET * 2 : fullArea.width;
+      const swatchSize = 10;
+      const swatchGap = 6;
+      const entryGap = 16;
+      pointCategoricalLegend = {
+        type: "categorical",
+        position: pointLegendOverlay ? "top-left" : "bottom",
+        bounds: { x: legendX, y: legendY, width: legendWidth, height: swatchSize + 6 },
+        labelStyle,
+        entries,
+        swatchSize,
+        swatchGap,
+        entryGap,
+        swatchChipFill: isDarkMode ? "rgba(255,255,255,0.06)" : "rgba(0,0,0,0.04)"
+      };
+    }
+    if (pts.color && pts.color.type === "quantitative" && showLegend) {
+      const ptColorValues = [];
+      for (const row of pts.data) {
+        const v = row[pts.color.field];
+        if (v != null) {
+          const n = Number(v);
+          if (Number.isFinite(n)) ptColorValues.push(n);
+        }
+      }
+      const ptLegendChannel = {
+        ...pts.color,
+        scale: { ...pts.color.scale, type: "quantile" }
+      };
+      const ptContinuousContent = computeContinuousLegendContentForChannel(
+        ptColorValues,
+        ptLegendChannel,
+        theme,
+        fullArea.width
+      );
+      if (ptContinuousContent) {
+        const labelStyle = {
+          fontFamily: theme.fonts.family,
+          fontSize: theme.fonts.sizes.small,
+          fontWeight: theme.fonts.weights.normal,
+          fill: theme.colors.text,
+          lineHeight: 1.3,
+          fontVariant: "tabular-nums"
+        };
+        const bottomChoroplethH = legendPosition === "bottom" ? continuousLegend?.bounds.height ?? categoricalLegend?.bounds.height ?? 0 : 0;
+        const choroplethLegendGap = bottomChoroplethH > 0 ? 8 : 0;
+        const legendX = pointLegendOverlay ? fullArea.x + OVERLAY_LEGEND_INSET : fullArea.x;
+        const legendY = pointLegendOverlay ? fullArea.y + OVERLAY_LEGEND_INSET : fullArea.y + mapAreaHeight + legendReserveGap + bottomChoroplethH + choroplethLegendGap;
+        const ptLabelRowHeight = Math.ceil(theme.fonts.sizes.small * 1.3);
+        const ptLegendHeight = ptContinuousContent.barHeight + CONTINUOUS_LABEL_GAP + ptLabelRowHeight;
+        const bounds = {
+          x: legendX,
+          y: legendY,
+          width: ptContinuousContent.barWidth,
+          height: ptLegendHeight
+        };
+        const bar = {
+          x: bounds.x,
+          y: bounds.y,
+          width: ptContinuousContent.barWidth,
+          height: ptContinuousContent.barHeight
+        };
+        pointContinuousLegend = {
+          type: "continuous",
+          mode: ptContinuousContent.mode,
+          position: pointLegendOverlay ? "top-left" : "bottom",
+          bounds,
+          labelStyle,
+          bar,
+          colorStops: ptContinuousContent.colorStops,
+          bins: ptContinuousContent.bins.map((b) => ({ ...b, x: b.x + bar.x })),
+          ticks: ptContinuousContent.ticks.map((t) => ({ ...t, x: t.x + bar.x })),
+          labelY: bar.y + bar.height + CONTINUOUS_LABEL_GAP + labelStyle.fontSize
+        };
+      }
+    }
+  }
   const tooltipChannels = mapSpec.encoding.tooltip ? Array.isArray(mapSpec.encoding.tooltip) ? mapSpec.encoding.tooltip : [mapSpec.encoding.tooltip] : null;
   const tooltipDescriptors = /* @__PURE__ */ new Map();
   for (const mark of featureMarks) {
@@ -17945,12 +18598,12 @@ function compileMap(spec, options) {
           });
         }
       }
-    } else if (isQuantitative && mark.data[colorEncoding.field] != null) {
+    } else if (colorEncoding && isQuantitative && mark.data[colorEncoding.field] != null) {
       fields.push({
         label: colorEncoding.title ?? colorEncoding.field,
         value: formatter(Number(mark.data[colorEncoding.field]))
       });
-    } else if (!isQuantitative && mark.data[colorEncoding.field] != null) {
+    } else if (colorEncoding && !isQuantitative && mark.data[colorEncoding.field] != null) {
       fields.push({
         label: colorEncoding.title ?? colorEncoding.field,
         value: String(mark.data[colorEncoding.field])
@@ -17958,13 +18611,63 @@ function compileMap(spec, options) {
     }
     tooltipDescriptors.set(String(mark.id), { fields });
   }
+  if (mapSpec.points && pointMarks.length > 0) {
+    const ptTooltipChannels = mapSpec.points.tooltip ? Array.isArray(mapSpec.points.tooltip) ? mapSpec.points.tooltip : [mapSpec.points.tooltip] : null;
+    for (const pm of pointMarks) {
+      const fields = [];
+      if (ptTooltipChannels) {
+        for (const ch of ptTooltipChannels) {
+          const val = pm.data[ch.field];
+          if (val != null) {
+            fields.push({
+              label: ch.title ?? ch.field,
+              value: ch.type === "quantitative" ? formatter(Number(val)) : String(val)
+            });
+          }
+        }
+      } else {
+        const pts = mapSpec.points;
+        if (pts.key) {
+          const val = pm.data[pts.key.field];
+          if (val != null)
+            fields.push({ label: pts.key.title ?? pts.key.field, value: String(val) });
+        }
+        if (pts.color) {
+          const val = pm.data[pts.color.field];
+          if (val != null)
+            fields.push({
+              label: pts.color.title ?? pts.color.field,
+              value: pts.color.type === "quantitative" ? formatter(Number(val)) : String(val)
+            });
+        }
+        if (pts.size) {
+          const val = pm.data[pts.size.field];
+          if (val != null)
+            fields.push({ label: pts.size.title ?? pts.size.field, value: formatter(Number(val)) });
+        }
+      }
+      if (fields.length > 0) {
+        tooltipDescriptors.set(`point:${pm.key}`, { fields });
+      }
+    }
+  }
+  const a11yDataField = colorEncoding?.field;
   const a11y = {
-    altText: `Map showing ${geoFeatures.length} regions with ${isQuantitative ? "quantitative" : "categorical"} data`,
-    dataTableFallback: featureMarks.filter((m) => m.data).map((m) => [m.name ?? String(m.id), String(m.data?.[colorEncoding.field] ?? "")]),
+    altText: pointMarks.length > 0 ? colorEncoding ? `Map showing ${geoFeatures.length} regions with ${isQuantitative ? "quantitative" : "categorical"} data and ${pointMarks.length} point markers` : `Map showing ${geoFeatures.length} regions with ${pointMarks.length} point markers` : colorEncoding ? `Map showing ${geoFeatures.length} regions with ${isQuantitative ? "quantitative" : "categorical"} data` : `Map showing ${geoFeatures.length} regions`,
+    dataTableFallback: [
+      ...featureMarks.filter((m) => m.data).map((m) => [
+        m.name ?? String(m.id),
+        a11yDataField ? String(m.data?.[a11yDataField] ?? "") : ""
+      ]),
+      ...pointMarks.map((pm) => [
+        pm.key,
+        mapSpec.points?.color ? String(pm.data[mapSpec.points.color.field] ?? "") : ""
+      ])
+    ],
     role: "img",
-    keyboardNavigable: featureMarks.length > 0
+    keyboardNavigable: featureMarks.length > 0 || pointMarks.length > 0
   };
-  const resolvedFocus = resolveFocus(mapSpec.geo.focus, featureMarks, compileWarnings);
+  const resolvedFocus = resolveFocus(mapSpec.geo.focus, featureMarks, pointMarks, compileWarnings);
   const resolvedAnimation = resolveAnimation(mapSpec.animation);
   const mapAreaY = legendPosition === "top" && legendBlockHeight > 0 ? fullArea.y + legendBlockHeight + legendReserveGap : fullArea.y;
   const mapArea = {
@@ -17987,6 +18690,9 @@ function compileMap(spec, options) {
     borders,
     continuousLegend,
     categoricalLegend,
+    pointMarks,
+    pointCategoricalLegend,
+    pointContinuousLegend,
     tooltipDescriptors,
     a11y,
     theme,
@@ -18000,6 +18706,46 @@ function compileMap(spec, options) {
     focus: resolvedFocus
   };
 }
+function buildBasemapMarks(opts) {
+  const { geoFeatures, pathGen, neutralFill, neutralStroke, droppedFeatures } = opts;
+  const marks = [];
+  let animIndex = 0;
+  for (const feat of geoFeatures) {
+    const pathD = pathGen(feat);
+    if (!pathD) {
+      const name2 = feat.properties?.name ?? String(feat.id);
+      droppedFeatures.push(name2);
+      continue;
+    }
+    const featureId = feat.id;
+    const props = feat.properties;
+    const name = props?.name ?? props?.NAME;
+    const b = pathGen.bounds(feat);
+    const bx = Number.isFinite(b[0][0]) ? b[0][0] : 0;
+    const by = Number.isFinite(b[0][1]) ? b[0][1] : 0;
+    const bw = Number.isFinite(b[1][0]) ? b[1][0] - bx : 0;
+    const bh = Number.isFinite(b[1][1]) ? b[1][1] - by : 0;
+    const bounds = { x: bx, y: by, width: bw, height: bh };
+    const rawCentroid = pathGen.centroid(feat);
+    const cx = Number.isFinite(rawCentroid[0]) ? rawCentroid[0] : bx + bw / 2;
+    const cy = Number.isFinite(rawCentroid[1]) ? rawCentroid[1] : by + bh / 2;
+    marks.push({
+      type: "map-feature",
+      path: pathD,
+      fill: neutralFill,
+      stroke: neutralStroke,
+      strokeWidth: 0.5,
+      id: featureId,
+      name,
+      data: null,
+      aria: { role: "img", label: name ?? String(featureId) },
+      animationIndex: animIndex++,
+      bounds,
+      centroid: [cx, cy]
+    });
+  }
+  return marks;
+}
 function buildQuantitativeMarks(opts) {
   const {
     geoFeatures,
@@ -18021,7 +18767,7 @@ function buildQuantitativeMarks(opts) {
       if (!Number.isNaN(v)) values.push(v);
     }
   }
-  const paletteStops = [...SEQUENTIAL_PALETTES[palette] ?? SEQUENTIAL_PALETTES.blue];
+  const paletteStops = [...SEQUENTIAL_PALETTES2[palette] ?? SEQUENTIAL_PALETTES2.blue];
   const colorScale = quantile2().domain(values).range(paletteStops);
   const marks = [];
   let animIndex = 0;
@@ -18084,6 +18830,7 @@ function buildCategoricalMarks(opts) {
     pathGen,
     joined,
     colorField,
+    colorScale: scaleConfig,
     isDarkMode,
     neutralFill,
     neutralStroke,
@@ -18091,11 +18838,18 @@ function buildCategoricalMarks(opts) {
     fullArea,
     mapAreaHeight,
     legendReserveGap,
+    legendPosition,
     showLegend,
     droppedFeatures
   } = opts;
   const categories = [];
-  const seen = /* @__PURE__ */ new Set();
+  const explicitDomain = scaleConfig?.domain;
+  if (explicitDomain && Array.isArray(explicitDomain)) {
+    for (const cat of explicitDomain) {
+      categories.push(String(cat));
+    }
+  }
+  const seen = new Set(categories);
   for (const row of joined.values()) {
     const raw = row[colorField];
     if (raw != null) {
@@ -18106,9 +18860,11 @@ function buildCategoricalMarks(opts) {
       }
     }
   }
+  const explicitRange = scaleConfig?.range;
+  const colorSource = explicitRange && Array.isArray(explicitRange) ? explicitRange : CATEGORICAL_PALETTE;
   const categoryColors = /* @__PURE__ */ new Map();
   for (let i = 0; i < categories.length; i++) {
-    categoryColors.set(categories[i], CATEGORICAL_PALETTE[i % CATEGORICAL_PALETTE.length]);
+    categoryColors.set(categories[i], colorSource[i % colorSource.length]);
   }
   const marks = [];
   let animIndex = 0;
@@ -18176,14 +18932,14 @@ function buildCategoricalMarks(opts) {
       shape: "square"
     }));
     const legendX = fullArea.x;
-    const legendY = fullArea.y + mapAreaHeight + legendReserveGap;
+    const legendY = legendPosition === "bottom" ? fullArea.y + mapAreaHeight + legendReserveGap : fullArea.y + legendReserveGap;
     const legendWidth = fullArea.width;
     const swatchSize = 10;
     const swatchGap = 6;
     const entryGap = 16;
     legend = {
       type: "categorical",
-      position: "bottom",
+      position: legendPosition,
       bounds: { x: legendX, y: legendY, width: legendWidth, height: swatchSize + 6 },
       labelStyle,
       entries,
@@ -18195,8 +18951,40 @@ function buildCategoricalMarks(opts) {
   }
   return { marks, legend };
 }
-function resolveFocus(focus, features, warnings) {
+function resolveFocus(focus, features, pointMarks, warnings) {
   if (focus === null || focus === void 0) return null;
+  if (typeof focus === "object" && !Array.isArray(focus) && "points" in focus) {
+    const filter = focus.points;
+    const matched = filter === true ? pointMarks : pointMarks.filter((p) => p.data[filter.field] === filter.value);
+    if (matched.length === 0) {
+      const detail = filter === true ? "the map has no points to fit" : `no points match { field: "${filter.field}", value: ${JSON.stringify(filter.value)} }`;
+      warnings.push({
+        code: "FOCUS_UNMATCHED",
+        message: `geo.focus.points is set but ${detail}`,
+        context: {}
+      });
+      return null;
+    }
+    const padding2 = focus.padding ?? 16;
+    let minX2 = Infinity;
+    let minY2 = Infinity;
+    let maxX2 = -Infinity;
+    let maxY2 = -Infinity;
+    for (const p of matched) {
+      minX2 = Math.min(minX2, p.cx);
+      minY2 = Math.min(minY2, p.cy);
+      maxX2 = Math.max(maxX2, p.cx);
+      maxY2 = Math.max(maxY2, p.cy);
+    }
+    const w = Math.max(maxX2 - minX2, 1);
+    const h = Math.max(maxY2 - minY2, 1);
+    return {
+      target: { x: minX2, y: minY2, width: w, height: h, padding: padding2 },
+      // No feature ids: focus-dim is a feature concept, so a points focus
+      // dims no features (there are no "other" features to mute).
+      ids: []
+    };
+  }
   let ids;
   let padding = 16;
   if (typeof focus === "string" || typeof focus === "number") {
@@ -18256,6 +19044,9 @@ function emptyLayout3(chrome, theme, options, watermark) {
     },
     continuousLegend: null,
     categoricalLegend: null,
+    pointMarks: [],
+    pointCategoricalLegend: null,
+    pointContinuousLegend: null,
     tooltipDescriptors: /* @__PURE__ */ new Map(),
     a11y: {
       altText: "Empty map",
@@ -18283,6 +19074,65 @@ import {
   resolveTheme as resolveTheme4
 } from "@opendata-ai/openchart-core";
 
+// src/graphs/animation.ts
+var ENTER_DEFAULT = {
+  duration: 500,
+  ease: "smooth",
+  stagger: true,
+  cameraFit: true
+};
+var UPDATE_DEFAULT = { duration: 300, ease: "smooth" };
+var EXIT_DEFAULT = { duration: 300, ease: "smooth" };
+var CAMERA_DEFAULT = { duration: "auto", ease: "smooth" };
+var HOVER_DEFAULT = { duration: 150, ease: "smooth" };
+function fullDefaults() {
+  return {
+    enter: { ...ENTER_DEFAULT },
+    update: { ...UPDATE_DEFAULT },
+    exit: { ...EXIT_DEFAULT },
+    camera: { ...CAMERA_DEFAULT },
+    hover: { ...HOVER_DEFAULT }
+  };
+}
+function resolveGraphAnimation(spec) {
+  if (spec === void 0 || spec === true) return fullDefaults();
+  if (spec === false) return void 0;
+  return {
+    enter: resolveEnter(spec.enter),
+    update: resolveDurationPhase(spec.update, UPDATE_DEFAULT),
+    exit: resolveDurationPhase(spec.exit, EXIT_DEFAULT),
+    camera: resolveCamera(spec.camera),
+    hover: resolveDurationPhase(spec.hover, HOVER_DEFAULT)
+  };
+}
+function resolveEnter(phase) {
+  if (phase === false) return null;
+  if (phase === void 0 || phase === true) return { ...ENTER_DEFAULT };
+  return {
+    duration: phase.duration ?? ENTER_DEFAULT.duration,
+    ease: phase.ease ?? ENTER_DEFAULT.ease,
+    stagger: phase.stagger !== false,
+    cameraFit: ENTER_DEFAULT.cameraFit
+  };
+}
+function resolveDurationPhase(phase, defaults) {
+  if (phase === false) return null;
+  if (phase === void 0 || phase === true)
+    return { duration: defaults.duration, ease: defaults.ease };
+  return {
+    duration: phase.duration ?? defaults.duration,
+    ease: phase.ease ?? defaults.ease
+  };
+}
+function resolveCamera(phase) {
+  if (phase === false) return null;
+  if (phase === void 0 || phase === true) return { ...CAMERA_DEFAULT };
+  return {
+    duration: phase.duration ?? CAMERA_DEFAULT.duration,
+    ease: phase.ease ?? CAMERA_DEFAULT.ease
+  };
+}
+
 // src/graphs/encoding.ts
 var DEFAULT_NODE_RADIUS = 5;
 var MIN_NODE_RADIUS = 3;
@@ -18322,16 +19172,42 @@ function computeDegrees(nodes, edges) {
   }
   return degrees2;
 }
+function resolveCategoricalDomain(values, sort, scaleDomain) {
+  if (Array.isArray(scaleDomain) && scaleDomain.length > 0) {
+    return scaleDomain.map((v) => String(v));
+  }
+  const seen = [];
+  const set = /* @__PURE__ */ new Set();
+  for (const v of values) {
+    if (!set.has(v)) {
+      set.add(v);
+      seen.push(v);
+    }
+  }
+  if (sort === null) return seen;
+  if (Array.isArray(sort)) {
+    const pinned = sort.filter((v) => set.has(v));
+    const pinnedSet = new Set(pinned);
+    const rest = seen.filter((v) => !pinnedSet.has(v));
+    return [...pinned, ...rest];
+  }
+  const sorted = [...seen].sort((a, b) => a.localeCompare(b));
+  return sort === "descending" ? sorted.reverse() : sorted;
+}
 function resolveNodeVisuals(nodes, encoding, edges, theme, nodeOverrides) {
   const degrees2 = computeDegrees(nodes, edges);
   const maxDegree = Math.max(1, ...degrees2.values());
   let sizeScale;
   if (encoding.nodeSize?.field) {
     const field = encoding.nodeSize.field;
+    const scaleConfig = encoding.nodeSize.scale;
     const values = nodes.map((n) => Number(n[field])).filter((v) => Number.isFinite(v));
     const sizeMin = min(values) ?? 0;
     const sizeMax = max(values) ?? 1;
-    sizeScale = sqrt().domain([sizeMin, sizeMax]).range([MIN_NODE_RADIUS, MAX_NODE_RADIUS]);
+    const domain = scaleConfig?.domain && scaleConfig.domain.length === 2 ? scaleConfig.domain : [sizeMin, sizeMax];
+    const range3 = scaleConfig?.range && scaleConfig.range.length >= 2 ? [Number(scaleConfig.range[0]), Number(scaleConfig.range[1])] : [MIN_NODE_RADIUS, MAX_NODE_RADIUS];
+    const ctor = scaleConfig?.type === "linear" ? linear2 : sqrt;
+    sizeScale = ctor().domain(domain).range(range3);
   }
   let colorFn;
   if (encoding.nodeColor?.field) {
@@ -18352,13 +19228,39 @@ function resolveNodeVisuals(nodes, encoding, edges, theme, nodeOverrides) {
         return Number.isFinite(val) ? colorScale(val) : theme.colors.categorical[0];
       };
     } else {
-      const domain = scaleConfig?.domain && Array.isArray(scaleConfig.domain) ? scaleConfig.domain : [...new Set(nodes.map((n) => String(n[field] ?? "")))];
+      const domain = resolveCategoricalDomain(
+        nodes.map((n) => String(n[field] ?? "")),
+        encoding.nodeColor.sort,
+        scaleConfig?.domain
+      );
       const range3 = scaleConfig?.range && scaleConfig.range.length > 0 ? scaleConfig.range : theme.colors.categorical;
       const ordinalScale = ordinal().domain(domain).range(range3);
       colorFn = (node) => ordinalScale(String(node[field] ?? ""));
     }
   }
   const defaultColor = theme.colors.categorical[0];
+  let opacityScale;
+  if (encoding.nodeOpacity?.field) {
+    const field = encoding.nodeOpacity.field;
+    const scaleConfig = encoding.nodeOpacity.scale;
+    const values = nodes.map((n) => Number(n[field])).filter((v) => Number.isFinite(v));
+    const opMin = min(values) ?? 0;
+    const opMax = max(values) ?? 1;
+    const domain = scaleConfig?.domain && scaleConfig.domain.length === 2 ? scaleConfig.domain : [opMin, opMax];
+    const range3 = scaleConfig?.range && scaleConfig.range.length >= 2 ? [Number(scaleConfig.range[0]), Number(scaleConfig.range[1])] : [0.25, 1];
+    opacityScale = linear2().domain(domain).range(range3);
+  }
+  let labelPriorityScale;
+  if (encoding.nodeLabelPriority?.field) {
+    const field = encoding.nodeLabelPriority.field;
+    const scaleConfig = encoding.nodeLabelPriority.scale;
+    const values = nodes.map((n) => Number(n[field])).filter((v) => Number.isFinite(v));
+    const lpMin = min(values) ?? 0;
+    const lpMax = max(values) ?? 1;
+    const domain = scaleConfig?.domain && scaleConfig.domain.length === 2 ? scaleConfig.domain : [lpMin, lpMax];
+    const range3 = scaleConfig?.range && scaleConfig.range.length >= 2 ? [Number(scaleConfig.range[0]), Number(scaleConfig.range[1])] : [0, 1];
+    labelPriorityScale = linear2().domain(domain).range(range3);
+  }
   return nodes.map((node) => {
     let radius = DEFAULT_NODE_RADIUS;
     if (sizeScale && encoding.nodeSize?.field) {
@@ -18367,6 +19269,13 @@ function resolveNodeVisuals(nodes, encoding, edges, theme, nodeOverrides) {
         radius = sizeScale(val);
       }
     }
+    let opacity = 1;
+    if (opacityScale && encoding.nodeOpacity?.field) {
+      const val = Number(node[encoding.nodeOpacity.field]);
+      if (Number.isFinite(val)) {
+        opacity = opacityScale(val);
+      }
+    }
     const fill = colorFn ? colorFn(node) : defaultColor;
     const stroke = darkenColor(fill);
     let label;
@@ -18376,8 +19285,14 @@ function resolveNodeVisuals(nodes, encoding, edges, theme, nodeOverrides) {
     } else {
       label = node.id;
     }
-    const degree = degrees2.get(node.id) ?? 0;
-    const labelPriority = maxDegree > 0 ? degree / maxDegree : 0;
+    let labelPriority;
+    if (labelPriorityScale && encoding.nodeLabelPriority?.field) {
+      const val = Number(node[encoding.nodeLabelPriority.field]);
+      labelPriority = Number.isFinite(val) ? labelPriorityScale(val) : 0;
+    } else {
+      const degree = degrees2.get(node.id) ?? 0;
+      labelPriority = maxDegree > 0 ? degree / maxDegree : 0;
+    }
     const { id: _id, ...rest } = node;
     const data = { id: node.id, ...rest };
     const override = nodeOverrides?.[node.id];
@@ -18395,6 +19310,7 @@ function resolveNodeVisuals(nodes, encoding, edges, theme, nodeOverrides) {
       label,
       labelPriority: finalLabelPriority,
       community: void 0,
+      opacity,
       data
     };
   });
@@ -18427,7 +19343,11 @@ function resolveEdgeVisuals(edges, encoding, theme) {
         return Number.isFinite(val) ? colorScale(val) : hexWithOpacity(theme.colors.axis, 0.4);
       };
     } else {
-      const domain = scaleConfig?.domain && Array.isArray(scaleConfig.domain) ? scaleConfig.domain : [...new Set(edges.map((e) => String(e[field] ?? "")))];
+      const domain = resolveCategoricalDomain(
+        edges.map((e) => String(e[field] ?? "")),
+        encoding.edgeColor.sort,
+        scaleConfig?.domain
+      );
       const range3 = scaleConfig?.range && scaleConfig.range.length > 0 ? scaleConfig.range : theme.colors.categorical;
       const ordinalScale = ordinal().domain(domain).range(range3);
       edgeColorFn = (edge) => ordinalScale(String(edge[field] ?? ""));
@@ -18438,10 +19358,14 @@ function resolveEdgeVisuals(edges, encoding, theme) {
   let styleFn;
   if (encoding.edgeStyle?.field) {
     const field = encoding.edgeStyle.field;
-    const uniqueValues = [...new Set(edges.map((e) => String(e[field] ?? "")))];
+    const domain = resolveCategoricalDomain(
+      edges.map((e) => String(e[field] ?? "")),
+      encoding.edgeStyle.sort,
+      encoding.edgeStyle.scale?.domain
+    );
     const styleMap = /* @__PURE__ */ new Map();
-    for (let i = 0; i < uniqueValues.length; i++) {
-      styleMap.set(uniqueValues[i], EDGE_STYLES[i % EDGE_STYLES.length]);
+    for (let i = 0; i < domain.length; i++) {
+      styleMap.set(domain[i], EDGE_STYLES[i % EDGE_STYLES.length]);
     }
     styleFn = (edge) => styleMap.get(String(edge[field] ?? "")) ?? "solid";
   }
@@ -18499,12 +19423,49 @@ function applyCommunityColors(nodes, colorMap) {
   }
 }
 
+// src/graphs/interaction.ts
+var DEFAULT_DIM_OPACITY = 0.15;
+var DEFAULT_CURSOR_RADIUS = 80;
+var DEFAULT_CURSOR_STRENGTH = 30;
+function resolveGraphInteraction(cfg) {
+  const hover = cfg?.hover;
+  const cursor = cfg?.cursorRepulsion;
+  let cursorRepulsion = null;
+  if (cursor === true) {
+    cursorRepulsion = { radius: DEFAULT_CURSOR_RADIUS, strength: DEFAULT_CURSOR_STRENGTH };
+  } else if (cursor && typeof cursor === "object") {
+    cursorRepulsion = {
+      radius: cursor.radius ?? DEFAULT_CURSOR_RADIUS,
+      strength: cursor.strength ?? DEFAULT_CURSOR_STRENGTH
+    };
+  }
+  return {
+    hoverMode: hover?.mode ?? "neighbors",
+    dimOpacity: hover?.dimOpacity ?? DEFAULT_DIM_OPACITY,
+    selectFlyTo: cfg?.select?.flyTo ?? false,
+    cursorRepulsion,
+    springyDrag: cfg?.springyDrag ?? false
+  };
+}
+
 // src/graphs/compile-graph.ts
 var graphNumberFormatter = defaultNumberFormatter8({ allIntegers: false, surface: "chart" });
 var SWATCH_SIZE2 = 12;
 var SWATCH_GAP2 = 6;
 var ENTRY_GAP2 = 16;
-function buildGraphLegend(nodes, communityColorMap, hasCommunities, theme, nodeColorField) {
+var ENERGY_PRESETS = {
+  gentle: { chargeStrength: -150, velocityDecay: 0.5 },
+  balanced: { chargeStrength: -300, velocityDecay: 0.4 },
+  energetic: { chargeStrength: -600, velocityDecay: 0.3 }
+};
+var SETTLE_PRESETS = {
+  quick: 0.05,
+  balanced: 0.0228,
+  thorough: 0.01
+};
+var DEFAULT_WARMUP_TICKS = 100;
+var DEFAULT_WARMUP_BUDGET_MS = 250;
+function buildGraphLegend(nodes, communityColorMap, hasCommunities, theme, nodeColorField, legendOrder) {
   const labelStyle = {
     fontFamily: theme.fonts.family,
     fontSize: theme.fonts.sizes.small,
@@ -18514,25 +19475,35 @@ function buildGraphLegend(nodes, communityColorMap, hasCommunities, theme, nodeC
   };
   let entries;
   if (hasCommunities && communityColorMap.size > 0) {
+    const counts = /* @__PURE__ */ new Map();
+    for (const node of nodes) {
+      if (node.community != null) {
+        counts.set(node.community, (counts.get(node.community) ?? 0) + 1);
+      }
+    }
     entries = [...communityColorMap.entries()].map(([label, color2]) => ({
       label,
       color: color2,
       shape: "circle",
-      active: true
+      active: true,
+      count: counts.get(label) ?? 0
     }));
   } else if (nodeColorField) {
     const categoryColors = /* @__PURE__ */ new Map();
+    const categoryCounts = /* @__PURE__ */ new Map();
     for (const node of nodes) {
       const category = String(node.data[nodeColorField] ?? node.label ?? node.id);
       if (!categoryColors.has(category)) {
         categoryColors.set(category, node.fill);
       }
+      categoryCounts.set(category, (categoryCounts.get(category) ?? 0) + 1);
     }
-    entries = categoryColors.size <= 1 ? [] : [...categoryColors.entries()].map(([label, color2]) => ({
+    entries = categoryColors.size <= 1 ? [] : (legendOrder ?? [...categoryColors.keys()]).filter((label) => categoryColors.has(label)).map((label) => ({
       label,
-      color: color2,
+      color: categoryColors.get(label),
       shape: "circle",
-      active: true
+      active: true,
+      count: categoryCounts.get(label) ?? 0
     }));
   } else {
     entries = [];
@@ -18548,6 +19519,30 @@ function buildGraphLegend(nodes, communityColorMap, hasCommunities, theme, nodeC
     swatchChipFill: theme.colors.annotationFill
   };
 }
+function buildEdgeLegend(edges, encoding) {
+  const field = encoding.edgeColor?.field;
+  if (!field || (encoding.edgeColor?.type ?? "nominal") === "quantitative") return void 0;
+  const categoryColors = /* @__PURE__ */ new Map();
+  const categoryCounts = /* @__PURE__ */ new Map();
+  for (const edge of edges) {
+    const category = String(edge.data[field] ?? "");
+    if (!categoryColors.has(category)) categoryColors.set(category, edge.stroke);
+    categoryCounts.set(category, (categoryCounts.get(category) ?? 0) + 1);
+  }
+  if (categoryColors.size <= 1) return void 0;
+  const order = resolveCategoricalDomain(
+    edges.map((e) => String(e.data[field] ?? "")),
+    encoding.edgeColor?.sort,
+    encoding.edgeColor?.scale?.domain
+  );
+  return order.filter((label) => categoryColors.has(label)).map((label) => ({
+    label,
+    color: categoryColors.get(label),
+    shape: "line",
+    active: true,
+    count: categoryCounts.get(label) ?? 0
+  }));
+}
 function buildGraphTooltips(nodes) {
   const descriptors = /* @__PURE__ */ new Map();
   for (const node of nodes) {
@@ -18574,6 +19569,21 @@ function buildGraphTooltips(nodes) {
   }
   return descriptors;
 }
+function buildEdgeTooltip(edge) {
+  const fields = [];
+  for (const [key, value2] of Object.entries(edge.data)) {
+    if (key === "source" || key === "target") continue;
+    if (value2 == null) continue;
+    fields.push({
+      label: key,
+      value: typeof value2 === "number" ? graphNumberFormatter(value2) : String(value2)
+    });
+  }
+  return {
+    title: `${edge.source} \u2192 ${edge.target}`,
+    fields
+  };
+}
 function compileGraph(spec, options) {
   const { spec: normalized, warnings } = compile(spec);
   emitSpecWarnings(warnings, options.onWarn);
@@ -18583,6 +19593,16 @@ function compileGraph(spec, options) {
     );
   }
   const graphSpec = normalized;
+  for (const [name, ch] of [
+    ["nodeColor", graphSpec.encoding.nodeColor],
+    ["edgeColor", graphSpec.encoding.edgeColor]
+  ]) {
+    if (ch?.sort != null && ch.type === "quantitative") {
+      options.onWarn?.(
+        `encoding.${name}.sort is ignored for a quantitative field (sort only orders categorical domains).`
+      );
+    }
+  }
   const rawWatermark = spec.watermark;
   const watermark = rawWatermark !== void 0 ? graphSpec.watermark : options.watermark ?? true;
   const mergedThemeConfig = options.theme ? { ...graphSpec.theme, ...options.theme } : graphSpec.theme;
@@ -18608,13 +19628,30 @@ function compileGraph(spec, options) {
   }
   const compiledEdges = resolveEdgeVisuals(graphSpec.edges, graphSpec.encoding, theme);
   const useCommunitiesForLegend = hasCommunities && !hasNodeColorEncoding;
+  const nodeColorField = graphSpec.encoding.nodeColor?.field;
+  const legendOrder = nodeColorField ? resolveCategoricalDomain(
+    compiledNodes.map((n) => String(n.data[nodeColorField] ?? n.label ?? n.id)),
+    graphSpec.encoding.nodeColor?.sort,
+    graphSpec.encoding.nodeColor?.scale?.domain
+  ) : void 0;
   const legend = buildGraphLegend(
     compiledNodes,
     communityColorMap,
     useCommunitiesForLegend,
     theme,
-    graphSpec.encoding.nodeColor?.field
+    nodeColorField,
+    legendOrder
   );
+  const edgeLegend = buildEdgeLegend(compiledEdges, graphSpec.encoding);
+  const legendField = nodeColorField ?? (useCommunitiesForLegend ? clusteringField ?? null : null);
+  let initialHighlight;
+  if (nodeColorField && graphSpec.encoding.nodeColor?.highlight != null) {
+    const raw = graphSpec.encoding.nodeColor.highlight;
+    const requested = Array.isArray(raw) ? raw : [raw];
+    const available = new Set(legendOrder ?? []);
+    const values = requested.filter((v) => available.has(v));
+    if (values.length > 0) initialHighlight = { field: nodeColorField, values };
+  }
   const tooltipDescriptors = buildGraphTooltips(compiledNodes);
   const communityCount = communityColorMap.size;
   const altParts = [
@@ -18631,17 +19668,26 @@ function compileGraph(spec, options) {
   };
   const collisionPadding = graphSpec.layout.collisionPadding ?? 2;
   const maxRadius = compiledNodes.length > 0 ? Math.max(...compiledNodes.map((n) => n.radius)) : DEFAULT_COLLISION_PADDING;
+  const energyPreset = graphSpec.layout.energy ? ENERGY_PRESETS[graphSpec.layout.energy] : ENERGY_PRESETS.balanced;
+  const settlePreset = graphSpec.layout.settle ? SETTLE_PRESETS[graphSpec.layout.settle] : SETTLE_PRESETS.balanced;
+  const warmupRaw = graphSpec.layout.warmup;
+  const warmupTicks = warmupRaw === false ? 0 : typeof warmupRaw === "number" ? Math.max(0, Math.floor(warmupRaw)) : DEFAULT_WARMUP_TICKS;
   const simulationConfig = {
-    chargeStrength: graphSpec.layout.chargeStrength ?? -300,
+    chargeStrength: graphSpec.layout.chargeStrength ?? energyPreset.chargeStrength,
     linkDistance: graphSpec.layout.linkDistance ?? 30,
     clustering: clusteringField ? { field: clusteringField, strength: 0.5 } : null,
-    alphaDecay: 0.0228,
-    velocityDecay: 0.4,
+    alphaDecay: settlePreset,
+    velocityDecay: energyPreset.velocityDecay,
     collisionRadius: maxRadius + collisionPadding,
     collisionPadding,
     linkStrength: graphSpec.layout.linkStrength,
-    centerForce: graphSpec.layout.centerForce
+    centerForce: graphSpec.layout.centerForce,
+    seed: graphSpec.layout.seed,
+    warmupTicks,
+    warmupBudgetMs: DEFAULT_WARMUP_BUDGET_MS
   };
+  const animation = resolveGraphAnimation(graphSpec.animation);
+  const interaction = resolveGraphInteraction(graphSpec.interaction);
   const chrome = computeChrome4(
     {
       title: graphSpec.chrome.title,
@@ -18670,7 +19716,12 @@ function compileGraph(spec, options) {
       height: options.height
     },
     simulationConfig,
-    watermark
+    watermark,
+    animation,
+    interaction,
+    legendField,
+    initialHighlight,
+    edgeLegend
   };
 }
 var DEFAULT_COLLISION_PADDING = 5;
@@ -18763,6 +19814,7 @@ function legendLayoutHasContent(legendLayout) {
 }
 var MIN_CHART_WIDTH = 60;
 var MIN_CHART_HEIGHT2 = 40;
+var PLOT_SHARE_MAX = 0.4;
 var SERIES_SEARCH_INPUT_HEIGHT = 32;
 var SERIES_SEARCH_GAP = 12;
 function getMinChartDims(display) {
@@ -18805,8 +19857,10 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
     watermark,
     bottomLegendReservation
   );
+  const chromeLayout = resolveChromeLayout(spec, options);
+  const effectiveHeight = chromeLayout === "grow" ? height + chrome.topHeight + chrome.bottomHeight : height;
   if (isSparkline) {
-    const total2 = { x: 0, y: 0, width, height };
+    const total2 = { x: 0, y: 0, width, height: effectiveHeight };
     const sparkPad = getSparklinePad(spec);
     const xAxisSpace = userExplicit.xAxis ? 26 : 0;
     const yAxisSpace = userExplicit.yAxis ? 30 : 0;
@@ -18830,7 +19884,7 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
       x: margins2.left,
       y: margins2.top,
       width: Math.max(0, width - margins2.left - margins2.right),
-      height: Math.max(0, height - margins2.top - margins2.bottom)
+      height: Math.max(0, effectiveHeight - margins2.top - margins2.bottom)
     };
     return {
       total: total2,
@@ -18842,7 +19896,7 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
       effectiveAxisGap: 0
     };
   }
-  const total = { x: 0, y: 0, width, height };
+  const total = { x: 0, y: 0, width, height: effectiveHeight };
   const isRadial = isAxislessMark2(spec.markType);
   const encoding = spec.encoding;
   const xAxisSuppressed = encoding.x?.axis === false;
@@ -19072,10 +20126,11 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
     x: margins.left,
     y: margins.top,
     width: Math.max(0, width - margins.left - margins.right),
-    height: Math.max(0, height - margins.top - margins.bottom)
+    height: Math.max(0, effectiveHeight - margins.top - margins.bottom)
   };
   const minDims = getMinChartDims(spec.display);
-  if ((chartArea.width < minDims.width || chartArea.height < minDims.height) && chromeMode !== "hidden") {
+  const chromeEatsPlot = chromeLayout !== "grow" && chrome.topHeight > height * PLOT_SHARE_MAX;
+  if ((chartArea.width < minDims.width || chartArea.height < minDims.height || chromeEatsPlot) && chromeMode !== "hidden") {
     const fallbackMode = chromeMode === "full" ? "compact" : "hidden";
     const fallbackChrome = computeChrome5(
       chromeToInput(spec.chrome),
@@ -19101,7 +20156,7 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
         x: margins.left,
         y: margins.top,
         width: Math.max(0, width - margins.left - margins.right),
-        height: Math.max(0, height - margins.top - margins.bottom)
+        height: Math.max(0, effectiveHeight - margins.top - margins.bottom)
       };
       const fallbackMetricsTopY = topPad + fallbackChrome.topHeight;
       const fallbackMetricsArea = { x: hPad, width: Math.max(0, width - hPad * 2) };
@@ -19118,7 +20173,7 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
         chartArea = {
           ...chartArea,
           y: margins.top,
-          height: Math.max(0, height - margins.top - margins.bottom)
+          height: Math.max(0, effectiveHeight - margins.top - margins.bottom)
         };
       }
       return {
@@ -19134,7 +20189,8 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
           fallbackMetricsArea
         ) : void 0,
         xAxisHeight,
-        effectiveAxisGap: fallbackEffectiveAxisGap
+        effectiveAxisGap: fallbackEffectiveAxisGap,
+        chromeStripped: true
       };
     }
   }
@@ -19146,7 +20202,7 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
     chartArea = {
       ...chartArea,
       y: margins.top,
-      height: Math.max(0, height - margins.top - margins.bottom)
+      height: Math.max(0, effectiveHeight - margins.top - margins.bottom)
     };
   }
   return {
@@ -19898,14 +20954,19 @@ function compileSankey(spec, options) {
     watermark
   );
   const padding = theme.spacing.padding;
+  const chromeLayout = resolveChromeLayout(
+    spec,
+    options
+  );
+  const grownHeight = chromeLayout === "grow" ? options.height + chrome.topHeight + chrome.bottomHeight : options.height;
   const fullArea = {
     x: padding,
     y: padding + chrome.topHeight,
     width: options.width - padding * 2,
-    height: options.height - chrome.topHeight - chrome.bottomHeight - padding * 2
+    height: chromeLayout === "grow" ? options.height - padding * 2 : options.height - chrome.topHeight - chrome.bottomHeight - padding * 2
   };
   if (fullArea.width <= 0 || fullArea.height <= 0) {
-    return emptyLayout4(fullArea, chrome, theme, options, watermark);
+    return emptyLayout4(fullArea, chrome, theme, { ...options, height: grownHeight }, watermark);
   }
   const sourceField = sankeySpec.encoding.source.field;
   const targetField = sankeySpec.encoding.target.field;
@@ -19945,7 +21006,7 @@ function compileSankey(spec, options) {
     height: fullArea.height - legend.bounds.height - legendGap2
   };
   if (area.height <= 0) {
-    return emptyLayout4(area, chrome, theme, options, watermark);
+    return emptyLayout4(area, chrome, theme, { ...options, height: grownHeight }, watermark);
   }
   const labelFontSize = theme.fonts.sizes.small;
   const labelFontWeight = theme.fonts.weights.normal;
@@ -20097,7 +21158,7 @@ function compileSankey(spec, options) {
     theme,
     dimensions: {
       width: options.width,
-      height: options.height
+      height: grownHeight
     },
     animation: resolvedAnimation,
     watermark,
@@ -20906,7 +21967,7 @@ import {
   HPAD_COMPACT_MIN as HPAD_COMPACT_MIN4,
   pickLabelColor as pickLabelColor4,
   resolveTheme as resolveTheme6,
-  SEQUENTIAL_PALETTES as SEQUENTIAL_PALETTES2
+  SEQUENTIAL_PALETTES as SEQUENTIAL_PALETTES3
 } from "@opendata-ai/openchart-core";
 var TILE_CORNER_RADIUS = 6;
 var TILE_STROKE_WIDTH = 1;
@@ -20916,6 +21977,10 @@ var LEGEND_ENTRY_GAP = 16;
 function clamp(value2, min4, max4) {
   return Math.min(max4, Math.max(min4, value2));
 }
+function growContentHeight(contentHeight, chromeLayout, budgetHeight, chrome) {
+  if (chromeLayout !== "grow") return contentHeight;
+  return Math.max(contentHeight, budgetHeight + chrome.topHeight + chrome.bottomHeight);
+}
 function compileTileMap(spec, options) {
   const sugarWarnings = [];
   const expandedSpec = spec && typeof spec === "object" && !Array.isArray(spec) ? expandSpecSugar(spec, sugarWarnings) : spec;
@@ -20952,22 +22017,44 @@ function compileTileMap(spec, options) {
     watermark
   );
   const padding = getBreakpoint2(options.width) === "compact" ? Math.max(HPAD_COMPACT_MIN4, Math.round(theme.spacing.padding * HPAD_COMPACT_FRACTION4)) : theme.spacing.padding;
+  const chromeLayout = resolveChromeLayout(
+    spec,
+    options
+  );
   const fullArea = {
     x: padding,
     y: padding + chrome.topHeight,
     width: options.width - padding * 2,
-    height: options.height - chrome.topHeight - chrome.bottomHeight - padding * 2
+    height: chromeLayout === "grow" ? options.height - padding * 2 : options.height - chrome.topHeight - chrome.bottomHeight - padding * 2
   };
   if (fullArea.width <= 0 || fullArea.height <= 0) {
     return emptyLayout5(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 compileCategorical(
+      tilemapSpec,
+      options,
+      theme,
+      chrome,
+      fullArea,
+      isDarkMode,
+      watermark,
+      chromeLayout
+    );
   }
-  return compileQuantitative(tilemapSpec, options, theme, chrome, fullArea, isDarkMode, watermark);
+  return compileQuantitative(
+    tilemapSpec,
+    options,
+    theme,
+    chrome,
+    fullArea,
+    isDarkMode,
+    watermark,
+    chromeLayout
+  );
 }
-function compileQuantitative(tilemapSpec, options, theme, chrome, fullArea, isDarkMode, watermark) {
+function compileQuantitative(tilemapSpec, options, theme, chrome, fullArea, isDarkMode, watermark, chromeLayout) {
   const stateField = tilemapSpec.encoding.state.field;
   const valueField = tilemapSpec.encoding.value.field;
   const stateValueMap = /* @__PURE__ */ new Map();
@@ -20984,7 +22071,7 @@ function compileQuantitative(tilemapSpec, options, theme, chrome, fullArea, isDa
   const values = Array.from(stateValueMap.values());
   const min4 = values.length > 0 ? Math.min(...values) : 0;
   const max4 = values.length > 0 ? Math.max(...values) : 100;
-  const paletteStops = [...SEQUENTIAL_PALETTES2[tilemapSpec.palette] ?? SEQUENTIAL_PALETTES2.blue];
+  const paletteStops = [...SEQUENTIAL_PALETTES3[tilemapSpec.palette] ?? SEQUENTIAL_PALETTES3.blue];
   const baseColor = isDarkMode ? paletteStops[0] : paletteStops[paletteStops.length - 1];
   const opacityRange = isDarkMode ? [0.15, 1] : [0.2, 1];
   const opacityScale = linear2().domain([min4, max4]).range(opacityRange).clamp(true);
@@ -21068,7 +22155,12 @@ function compileQuantitative(tilemapSpec, options, theme, chrome, fullArea, isDa
   };
   const resolvedAnimation = resolveAnimation(tilemapSpec.animation);
   const padding = fullArea.x;
-  const contentHeight = tileGridOffsetY + tilePositions.gridHeight + legendGap2 + legendTotalHeight + chrome.bottomHeight + padding;
+  const contentHeight = growContentHeight(
+    tileGridOffsetY + tilePositions.gridHeight + legendGap2 + legendTotalHeight + chrome.bottomHeight + padding,
+    chromeLayout,
+    options.height,
+    chrome
+  );
   return {
     area: fullArea,
     chrome,
@@ -21085,7 +22177,7 @@ function compileQuantitative(tilemapSpec, options, theme, chrome, fullArea, isDa
     measureText: options.measureText ?? ((text, fontSize) => ({ width: estimateTextWidth23(text, fontSize), height: fontSize }))
   };
 }
-function compileCategorical(tilemapSpec, options, theme, chrome, fullArea, isDarkMode, watermark) {
+function compileCategorical(tilemapSpec, options, theme, chrome, fullArea, isDarkMode, watermark, chromeLayout) {
   const stateField = tilemapSpec.encoding.state.field;
   const colorField = tilemapSpec.encoding.color?.field ?? tilemapSpec.encoding.value.field;
   const stateCategoryMap = /* @__PURE__ */ new Map();
@@ -21204,7 +22296,12 @@ function compileCategorical(tilemapSpec, options, theme, chrome, fullArea, isDar
   };
   const resolvedAnimation = resolveAnimation(tilemapSpec.animation);
   const padding = fullArea.x;
-  const contentHeight = tileGridOffsetY + tilePositions.gridHeight + legendGap2 + legendTotalHeight + chrome.bottomHeight + padding;
+  const contentHeight = growContentHeight(
+    tileGridOffsetY + tilePositions.gridHeight + legendGap2 + legendTotalHeight + chrome.bottomHeight + padding,
+    chromeLayout,
+    options.height,
+    chrome
+  );
   return {
     area: fullArea,
     chrome,
@@ -22264,6 +23361,38 @@ function applySparklineDefaults(spec, theme) {
   }
   return { ...spec, markDef: newMarkDef };
 }
+function resolveScaleInvert(resolved) {
+  if (!resolved) return void 0;
+  const { scale, type } = resolved;
+  if (type === "band" || type === "point") {
+    const domain = scale.domain();
+    const positions = domain.map((v) => {
+      const pos = scale(v) ?? 0;
+      return type === "band" ? pos + scale.bandwidth() / 2 : pos;
+    });
+    const range4 = scale.range();
+    return {
+      topPixel: range4[0],
+      bottomPixel: range4[range4.length - 1],
+      topData: 0,
+      bottomData: 0,
+      domain,
+      positions
+    };
+  }
+  const invert = scale.invert;
+  if (typeof invert !== "function") return void 0;
+  const range3 = scale.range();
+  const topPx = range3[0];
+  const bottomPx = range3[range3.length - 1];
+  const topVal = invert.call(scale, topPx);
+  const bottomVal = invert.call(scale, bottomPx);
+  const topData = topVal instanceof Date ? +topVal : Number(topVal);
+  const bottomData = bottomVal instanceof Date ? +bottomVal : Number(bottomVal);
+  if (!Number.isFinite(topData) || !Number.isFinite(bottomData)) return void 0;
+  const scaleType = type;
+  return { topPixel: topPx, bottomPixel: bottomPx, topData, bottomData, scaleType };
+}
 function compileChart(spec, optionsInput) {
   const sugarWarnings = [];
   const expandedSpec = spec && typeof spec === "object" && !Array.isArray(spec) ? expandSpecSugar(spec, sugarWarnings) : spec;
@@ -22464,12 +23593,35 @@ function compileChart(spec, optionsInput) {
       }
     };
   }
+  let facetDirection = "wrap";
+  const rowChannel = renderSpec.encoding.row;
+  const colChannel = renderSpec.encoding.column;
+  if (rowChannel?.field || colChannel?.field) {
+    const channel = rowChannel?.field ? rowChannel : colChannel;
+    facetDirection = rowChannel?.field ? "row" : "column";
+    const desugared = { ...renderSpec.encoding };
+    delete desugared.row;
+    delete desugared.column;
+    desugared.facet = {
+      field: channel.field,
+      type: channel.type,
+      sort: channel.sort,
+      ...facetDirection === "row" ? { columns: 1 } : {}
+    };
+    renderSpec = { ...renderSpec, encoding: desugared };
+    const chartDesugared = { ...chartSpec.encoding };
+    delete chartDesugared.row;
+    delete chartDesugared.column;
+    chartDesugared.facet = desugared.facet;
+    chartSpec = { ...chartSpec, encoding: chartDesugared };
+  }
   const facetChannel = renderSpec.encoding.facet;
   if (facetChannel?.field) {
     return compileFaceted(
       chartSpec,
       renderSpec,
       facetChannel,
+      facetDirection,
       options,
       theme,
       strategy,
@@ -22534,7 +23686,10 @@ function compileChart(spec, optionsInput) {
     skipY,
     markType: chartSpec.markType,
     totalWidth: options.width,
-    precomputedYTicks: plan.yTickValues.length > 0 ? plan.yTickValues : void 0
+    // If the guardrail stripped chrome, the plan's y-ticks were sized
+    // against the pre-strip (shorter) plot. Drop them so computeAxes
+    // regenerates against the final (taller) chartArea.
+    precomputedYTicks: !dims.chromeStripped && plan.yTickValues.length > 0 ? plan.yTickValues : void 0
   });
   const xAxisExtent = axes.x?.extent ?? 0;
   dims.chrome.bottomAnchorY = chartArea.y + chartArea.height + xAxisExtent;
@@ -22549,6 +23704,19 @@ function compileChart(spec, optionsInput) {
   const renderer = getChartRenderer(rendererKey);
   const marks = renderer ? renderer(renderSpec, scales, chartArea, strategy, theme, options.width) : [];
   applyFillPatterns(marks, chartSpec.markDef, theme);
+  const markRenderModeWarnings = [];
+  const markRenderMode = resolveMarkRenderMode(
+    {
+      markDef: chartSpec.markDef,
+      markType: chartSpec.markType,
+      pointCount: marks.reduce((n, m) => m.type === "point" ? n + 1 : n, 0),
+      display: chartSpec.display,
+      faceted: false,
+      layered: options.layered ?? false
+    },
+    markRenderModeWarnings
+  );
+  emitSpecWarnings(markRenderModeWarnings, options.onWarn);
   const xFieldForYdi = chartSpec.encoding.x && "field" in chartSpec.encoding.x ? chartSpec.encoding.x.field : void 0;
   const youDrawIt = resolveYouDrawIt(chartSpec.youDrawIt, marks, scales, chartArea, xFieldForYdi);
   const endpointLabels = computeEndpointLabels(
@@ -22629,6 +23797,8 @@ function compileChart(spec, optionsInput) {
   );
   assignAnimationIndices(marks, resolvedAnimation);
   const chrome = footnotes ? { ...dims.chrome, footnotes } : dims.chrome;
+  const xInvert = resolveScaleInvert(scales.x);
+  const yInvert = resolveScaleInvert(scales.y);
   return {
     area: chartArea,
     chrome,
@@ -22648,6 +23818,7 @@ function compileChart(spec, optionsInput) {
     a11y: {
       altText,
       dataTableFallback,
+      ...chartSpec.data.length > MAX_SR_TABLE_ROWS ? { totalRows: chartSpec.data.length } : {},
       role: "img",
       keyboardNavigable: marks.length > 0,
       ...chartSpec.a11y?.hidden ? { hidden: true } : {}
@@ -22655,16 +23826,22 @@ function compileChart(spec, optionsInput) {
     theme,
     dimensions: {
       width: options.width,
-      height: options.height
+      // In chromeLayout 'grow' mode, computeDimensions grows total.height by the
+      // chrome height so the plot keeps its full budget. In the default
+      // 'subtract' mode total.height === options.height, so this is a no-op.
+      height: dims.total.height
     },
     animation: resolvedAnimation,
     watermark,
     display: chartSpec.display,
     crosshair,
-    measureText: options.measureText
+    measureText: options.measureText,
+    ...xInvert ? { xInvert } : {},
+    ...yInvert ? { yInvert } : {},
+    ...markRenderMode === "canvas" ? { markRenderMode } : {}
   };
 }
-function compileFaceted(chartSpec, renderSpec, facetChannel, options, theme, strategy, watermark, resolvedAnimation, crosshair, rawSpec, optionsInput) {
+function compileFaceted(chartSpec, renderSpec, facetChannel, facetDirection, options, theme, strategy, watermark, resolvedAnimation, crosshair, rawSpec, optionsInput) {
   const measure = createMeasureFn(options.measureText);
   const panelEncoding = { ...renderSpec.encoding };
   delete panelEncoding.facet;
@@ -22710,10 +23887,10 @@ function compileFaceted(chartSpec, renderSpec, facetChannel, options, theme, str
     plan.xAxisExtent,
     dims.effectiveAxisGap
   );
-  const leftReservation = plan.leftGutter;
   const bottomReservation = plan.xAxisExtent;
-  const grid = computeFacetGrid(facetValues, facetChannel.columns, chartArea, {
-    left: leftReservation,
+  const effectiveColumns = facetDirection === "column" ? facetValues.length : facetChannel.columns;
+  const grid = computeFacetGrid(facetValues, effectiveColumns, chartArea, {
+    left: 0,
     bottom: bottomReservation
   });
   if (!optionsInput.facetHeightGrown && grid.panels.length > 0 && grid.panels[0].area.height < MIN_PANEL_HEIGHT) {
@@ -22728,8 +23905,10 @@ function compileFaceted(chartSpec, renderSpec, facetChannel, options, theme, str
     }
   }
   const resolveConfig = chartSpec.resolve;
-  const yResolve = resolveConfig?.scale?.y ?? "shared";
-  const xResolve = resolveConfig?.scale?.x ?? "shared";
+  const xDefault = facetDirection === "column" ? "independent" : "shared";
+  const yDefault = facetDirection === "row" ? "independent" : "shared";
+  const yResolve = resolveConfig?.scale?.y ?? yDefault;
+  const xResolve = resolveConfig?.scale?.x ?? xDefault;
   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;
@@ -22794,6 +23973,16 @@ function compileFaceted(chartSpec, renderSpec, facetChannel, options, theme, str
         tickMarks: false
       };
     }
+    const isBottomRow = gridPanel.row === grid.rows - 1;
+    if (xResolve === "shared" && facetDirection === "row" && !isBottomRow && panelAxes.x) {
+      panelAxes.x = {
+        ...panelAxes.x,
+        ticks: [],
+        label: void 0,
+        domainLine: false,
+        tickMarks: false
+      };
+    }
     const panelMarks = renderer ? renderer(
       panelSpecWithDomains,
       panelScales,
@@ -22847,10 +24036,11 @@ function compileFaceted(chartSpec, renderSpec, facetChannel, options, theme, str
       annotations: panelAnnotations,
       header: {
         text: gridPanel.key,
-        x: gridPanel.headerPos.x,
+        x: facetDirection === "row" ? gridPanel.area.x : gridPanel.headerPos.x,
         y: gridPanel.headerPos.y,
         fontSize: theme.fonts.sizes.body,
-        fontWeight: theme.fonts.weights.medium
+        fontWeight: theme.fonts.weights.medium,
+        ...facetDirection === "row" ? { textAnchor: "start" } : {}
       }
     });
   }
@@ -22903,6 +24093,7 @@ function compileFaceted(chartSpec, renderSpec, facetChannel, options, theme, str
     a11y: {
       altText,
       dataTableFallback,
+      ...chartSpec.data.length > MAX_SR_TABLE_ROWS ? { totalRows: chartSpec.data.length } : {},
       role: "img",
       keyboardNavigable: allMarks.length > 0,
       ...chartSpec.a11y?.hidden ? { hidden: true } : {}
@@ -22918,7 +24109,8 @@ function compileFaceted(chartSpec, renderSpec, facetChannel, options, theme, str
       panels: panelLayouts,
       facetField: facetChannel.field,
       columns: grid.columns,
-      sharedScales: yResolve === "shared" && xResolve === "shared"
+      sharedScales: yResolve === "shared" && xResolve === "shared",
+      direction: facetDirection
     }
   };
 }
@@ -22972,6 +24164,7 @@ export {
   EXIT_DEFAULTS,
   UPDATE_DEFAULTS,
   buildAreaPath,
+  buildEdgeTooltip,
   buildLinePath,
   clampStaggerDelay,
   clearRenderers,