@opendata-ai/openchart-engine 8.0.0-rc.1 → 8.0.0-rc.10

package/dist/index.js

@@ -244,7 +244,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 +509,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,
@@ -2160,6 +2167,7 @@ function serializeKeyValue(v) {
   if (v instanceof Date) return String(v.getTime());
   return String(v);
 }
+var KEY_DEDUP_SEP = "\u2E31";
 function dedupeKeys(keys) {
   const counts = /* @__PURE__ */ new Map();
   for (const k of keys) {
@@ -2170,7 +2178,7 @@ function dedupeKeys(keys) {
   for (const k of keys) {
     if (counts.get(k) > 1) {
       const idx = seen.get(k) ?? 0;
-      result.push(`${k}
${idx}`);
+      result.push(`${k}${KEY_DEDUP_SEP}${idx}`);
       seen.set(k, idx + 1);
     } else {
       result.push(k);
@@ -5544,7 +5552,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];
@@ -9836,7 +9846,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;
@@ -10630,7 +10649,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) {
@@ -10725,6 +10745,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"]);
@@ -10783,6 +10804,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;
@@ -11144,15 +11212,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({
@@ -11266,6 +11326,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"`,
@@ -11478,7 +11584,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 === "") {
@@ -11493,7 +11599,7 @@ 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])}`
       });
     }
   }
@@ -11511,7 +11617,7 @@ function validateGraphSpec(spec, errors) {
           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])}`
         });
       }
     }
@@ -11523,10 +11629,16 @@ function validateGraphSpec(spec, errors) {
           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;
@@ -11580,7 +11692,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") {
@@ -11588,7 +11701,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;
     }
@@ -11606,10 +11719,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"',
@@ -11669,7 +11788,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") {
@@ -11677,7 +11797,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;
       }
@@ -11695,11 +11815,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"',
@@ -11738,6 +11866,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") {
@@ -11754,12 +11892,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;
@@ -11793,33 +11950,99 @@ 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" }`
+        });
+      }
+    }
   }
 }
 function validateBarListSpec(spec, errors) {
@@ -11862,7 +12085,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") {
@@ -11870,7 +12094,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;
     }
@@ -11888,7 +12112,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)}`
       });
     }
   }
@@ -11901,10 +12125,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"',
@@ -13649,7 +13879,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);
   }
@@ -13994,6 +14225,7 @@ import {
   estimateTextWidth as estimateTextWidth15,
   getAxisTitleOffset,
   truncateRotatedLabel,
+  X_AXIS_TITLE_BAND,
   X_AXIS_TITLE_BAND_ROTATED
 } from "@opendata-ai/openchart-core";
 
@@ -14606,10 +14838,12 @@ function computeAxes(scales, chartArea, strategy, theme, measureText, dataContex
       measure: (t, fs, fw) => measureLabel(t, fs, fw, measureText)
     });
     if (result.x.label) {
-      const rotatedBand = isRotated ? result.x.extent - X_AXIS_TITLE_BAND_ROTATED + 14 : 35;
+      const titleBand = isRotated ? X_AXIS_TITLE_BAND_ROTATED : X_AXIS_TITLE_BAND;
+      const tickBand = result.x.extent - titleBand;
+      const titleY = isRotated ? tickBand + 14 : tickBand + 9;
       result.x.titlePosition = {
         x: chartArea.x + chartArea.width / 2,
-        y: chartArea.y + chartArea.height + rotatedBand
+        y: chartArea.y + chartArea.height + titleY
       };
     }
   }
@@ -15453,6 +15687,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,
@@ -15687,7 +15925,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
@@ -17665,13 +17903,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) {
@@ -17691,6 +17948,7 @@ function excludePolarFeatures(geojson) {
 }
 
 // src/geo/compile-map.ts
+var OVERLAY_LEGEND_INSET = 18;
 function validateGeoFeatures(geo) {
   if (!geo.features) {
     throw new Error(
@@ -17763,11 +18021,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];
@@ -17790,17 +18050,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) {
@@ -17815,17 +18095,22 @@ 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 neutralFill = isDarkMode ? "#2a2a2a" : "#e8e8e8";
@@ -17833,13 +18118,21 @@ function compileMap(spec, options) {
   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,
@@ -17847,7 +18140,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,
@@ -17889,6 +18182,7 @@ function compileMap(spec, options) {
       pathGen,
       joined,
       colorField: colorEncoding.field,
+      colorScale: colorEncoding.scale,
       isDarkMode: !!isDarkMode,
       neutralFill,
       neutralStroke,
@@ -17896,7 +18190,8 @@ function compileMap(spec, options) {
       fullArea,
       mapAreaHeight,
       legendReserveGap,
-      showLegend,
+      legendPosition,
+      showLegend: showChoroplethLegend,
       droppedFeatures
     });
     featureMarks = result.marks;
@@ -17924,6 +18219,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) {
@@ -17941,12 +18431,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])
@@ -17954,13 +18444,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 = {
@@ -17983,6 +18523,9 @@ function compileMap(spec, options) {
     borders,
     continuousLegend,
     categoricalLegend,
+    pointMarks,
+    pointCategoricalLegend,
+    pointContinuousLegend,
     tooltipDescriptors,
     a11y,
     theme,
@@ -17996,6 +18539,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,
@@ -18017,7 +18600,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;
@@ -18080,6 +18663,7 @@ function buildCategoricalMarks(opts) {
     pathGen,
     joined,
     colorField,
+    colorScale: scaleConfig,
     isDarkMode,
     neutralFill,
     neutralStroke,
@@ -18087,11 +18671,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) {
@@ -18102,9 +18693,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;
@@ -18172,14 +18765,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,
@@ -18191,8 +18784,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") {
@@ -18252,6 +18877,9 @@ function emptyLayout3(chrome, theme, options, watermark) {
     },
     continuousLegend: null,
     categoricalLegend: null,
+    pointMarks: [],
+    pointCategoricalLegend: null,
+    pointContinuousLegend: null,
     tooltipDescriptors: /* @__PURE__ */ new Map(),
     a11y: {
       altText: "Empty map",
@@ -20902,7 +21530,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;
@@ -20980,7 +21608,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);
@@ -22260,6 +22888,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;
@@ -22460,12 +23120,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,
@@ -22625,6 +23308,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,
@@ -22657,10 +23342,12 @@ function compileChart(spec, optionsInput) {
     watermark,
     display: chartSpec.display,
     crosshair,
-    measureText: options.measureText
+    measureText: options.measureText,
+    ...xInvert ? { xInvert } : {},
+    ...yInvert ? { yInvert } : {}
   };
 }
-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;
@@ -22708,7 +23395,8 @@ function compileFaceted(chartSpec, renderSpec, facetChannel, options, theme, str
   );
   const leftReservation = plan.leftGutter;
   const bottomReservation = plan.xAxisExtent;
-  const grid = computeFacetGrid(facetValues, facetChannel.columns, chartArea, {
+  const effectiveColumns = facetDirection === "column" ? facetValues.length : facetChannel.columns;
+  const grid = computeFacetGrid(facetValues, effectiveColumns, chartArea, {
     left: leftReservation,
     bottom: bottomReservation
   });
@@ -22724,8 +23412,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;
@@ -22790,6 +23480,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,
@@ -22843,10 +23543,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" } : {}
       }
     });
   }
@@ -22914,7 +23615,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
     }
   };
 }