@dclimate/zarr-map 0.1.0

package/dist/core/index.cjs

@@ -0,0 +1,1603 @@
+'use strict';
+
+// src/core/errors.ts
+var GridError = class extends Error {
+  code;
+  cause;
+  dimension;
+  variable;
+  sourceId;
+  context;
+  constructor(details) {
+    super(details.message);
+    this.name = "GridError";
+    this.code = details.code;
+    this.cause = details.cause;
+    this.dimension = details.dimension;
+    this.variable = details.variable;
+    this.sourceId = details.sourceId;
+    this.context = details.context;
+  }
+};
+function isGridError(error) {
+  return error instanceof GridError;
+}
+function toGridError(details) {
+  return details instanceof GridError ? details : new GridError(details);
+}
+
+// src/core/color.ts
+var builtinPalettes = {
+  viridis: ["#440154", "#31688e", "#35b779", "#fde725"],
+  inferno: ["#000004", "#57106e", "#bc3754", "#f98e09", "#fcffa4"],
+  magma: ["#000004", "#3b0f70", "#8c2981", "#de4968", "#fe9f6d", "#fcfdbf"],
+  plasma: ["#0d0887", "#7e03a8", "#cc4778", "#f89540", "#f0f921"],
+  cividis: ["#00204c", "#31446b", "#666870", "#958f78", "#c6b866", "#ffe945"],
+  turbo: ["#30123b", "#466be3", "#35ab6b", "#faba39", "#7a0403"],
+  greys: ["#000000", "#777777", "#ffffff"],
+  grays: ["#000000", "#777777", "#ffffff"],
+  temperature: ["#2c5ab4", "#67b0f0", "#e0e4dc", "#ffb266", "#cd4434"],
+  precipitation: ["#bae6fd", "#60a5fa", "#2563eb", "#4f46e5", "#6d28d9"],
+  humidity: ["#374151", "#2d5a6e", "#1890b0", "#2dd4bf", "#99f6e4"],
+  vegetation: ["#f7fee7", "#bef264", "#4ade80", "#15803d", "#064e3b"],
+  wind: ["#e2e8f0", "#7dd3fc", "#2dd4bf", "#14b8a6"]
+};
+function validateColorScale(colorScale) {
+  const [min, max] = colorScale.domain;
+  if (!Number.isFinite(min) || !Number.isFinite(max) || min >= max) {
+    throw new GridError({
+      code: "INVALID_COLOR_SCALE",
+      message: "Color scale domain must be finite and ordered as [min, max].",
+      context: { domain: colorScale.domain }
+    });
+  }
+  if (!colorScale.palette) {
+    throw new GridError({
+      code: "INVALID_COLOR_SCALE",
+      message: "Color scale must include a palette name or color stop array."
+    });
+  }
+  paletteToRendererColorMap(colorScale.palette);
+  return colorScale;
+}
+function colorScaleToRendererOptions(colorScale) {
+  if (!colorScale) {
+    return void 0;
+  }
+  validateColorScale(colorScale);
+  return {
+    colormap: paletteToRendererColorMap(colorScale.palette),
+    clim: colorScale.domain
+  };
+}
+function paletteToRendererColorMap(palette) {
+  if (typeof palette !== "string") {
+    if (palette.length < 2) {
+      throw new GridError({
+        code: "INVALID_COLOR_SCALE",
+        message: "Custom color palettes must include at least two color stops.",
+        context: { palette }
+      });
+    }
+    const colors2 = palette.map((color) => color.trim());
+    const invalid = colors2.find((color) => color.length === 0);
+    if (invalid !== void 0) {
+      throw new GridError({
+        code: "INVALID_COLOR_SCALE",
+        message: "Custom color palettes cannot include empty color stops.",
+        context: { palette }
+      });
+    }
+    return colors2;
+  }
+  const normalized = palette.toLowerCase();
+  const colors = builtinPalettes[normalized];
+  if (!colors) {
+    throw new GridError({
+      code: "INVALID_COLOR_SCALE",
+      message: `Unsupported renderer palette "${palette}". Use one of: ${Object.keys(builtinPalettes).join(", ")}.`,
+      context: { palette }
+    });
+  }
+  return colors;
+}
+function colorScaleDisplayDomain(colorScale) {
+  const { displayUnit, quantity, unit } = colorScale;
+  if (!displayUnit || !unit || displayUnit === unit || !quantity) {
+    return colorScale.domain;
+  }
+  return [
+    convertDisplayValue(colorScale.domain[0], {
+      fromUnit: unit,
+      quantity,
+      toUnit: displayUnit
+    }),
+    convertDisplayValue(colorScale.domain[1], {
+      fromUnit: unit,
+      quantity,
+      toUnit: displayUnit
+    })
+  ];
+}
+function convertDisplayValue(value, options) {
+  if (!Number.isFinite(value)) {
+    return value;
+  }
+  if (options.quantity === "temperature") {
+    return temperatureFromKelvin(temperatureToKelvin(value, options.fromUnit), options.toUnit);
+  }
+  return precipitationFromMeters(precipitationToMeters(value, options.fromUnit), options.toUnit);
+}
+function temperatureToKelvin(value, unit) {
+  const normalized = normalizeUnit(unit);
+  if (normalized === "k" || normalized === "kelvin") {
+    return value;
+  }
+  if (["c", "degc", "celsius"].includes(normalized)) {
+    return value + 273.15;
+  }
+  if (["f", "degf", "fahrenheit"].includes(normalized)) {
+    return (value - 32) * 5 / 9 + 273.15;
+  }
+  throw unsupportedUnit(unit, "temperature");
+}
+function temperatureFromKelvin(value, unit) {
+  const normalized = normalizeUnit(unit);
+  if (normalized === "k" || normalized === "kelvin") {
+    return value;
+  }
+  if (["c", "degc", "celsius"].includes(normalized)) {
+    return value - 273.15;
+  }
+  if (["f", "degf", "fahrenheit"].includes(normalized)) {
+    return (value - 273.15) * 9 / 5 + 32;
+  }
+  throw unsupportedUnit(unit, "temperature");
+}
+function precipitationToMeters(value, unit) {
+  const normalized = normalizeUnit(unit);
+  if (["m", "meter", "meters"].includes(normalized)) {
+    return value;
+  }
+  if (["mm", "millimeter", "millimeters"].includes(normalized)) {
+    return value / 1e3;
+  }
+  if (isKilogramPerSquareMeter(normalized)) {
+    return value / 1e3;
+  }
+  if (["in", "inch", "inches"].includes(normalized)) {
+    return value * 0.0254;
+  }
+  throw unsupportedUnit(unit, "precipitation");
+}
+function precipitationFromMeters(value, unit) {
+  const normalized = normalizeUnit(unit);
+  if (["m", "meter", "meters"].includes(normalized)) {
+    return value;
+  }
+  if (["mm", "millimeter", "millimeters"].includes(normalized)) {
+    return value * 1e3;
+  }
+  if (isKilogramPerSquareMeter(normalized)) {
+    return value * 1e3;
+  }
+  if (["in", "inch", "inches"].includes(normalized)) {
+    return value / 0.0254;
+  }
+  throw unsupportedUnit(unit, "precipitation");
+}
+function isKilogramPerSquareMeter(normalizedUnit) {
+  const compact = normalizedUnit.replace(/\s+/g, "");
+  return ["kgm**-2", "kgm^-2", "kgm-2", "kg/m2", "kg/m^2"].includes(compact);
+}
+function normalizeUnit(unit) {
+  return unit.trim().toLowerCase().replace(/^degrees?_?/, "deg").replace("\xB0", "deg");
+}
+function unsupportedUnit(unit, quantity) {
+  return new GridError({
+    code: "UNSUPPORTED_UNIT",
+    message: `Unsupported ${quantity} display unit "${unit}".`,
+    context: { quantity, unit }
+  });
+}
+
+// src/core/validation.ts
+var xAliases = /* @__PURE__ */ new Set(["x", "lon", "lng", "longitude"]);
+var yAliases = /* @__PURE__ */ new Set(["y", "lat", "latitude"]);
+var numericDtypes = /* @__PURE__ */ new Set([
+  "int8",
+  "uint8",
+  "int16",
+  "uint16",
+  "int32",
+  "uint32",
+  "float32",
+  "float64",
+  "i1",
+  "u1",
+  "i2",
+  "u2",
+  "i4",
+  "u4",
+  "f4",
+  "f8"
+]);
+function findVariable(source, variableName) {
+  return source.variables.find(
+    (variable) => variable.name === variableName || variable.path === variableName
+  );
+}
+function findDimension(source, dimensionName) {
+  return source.dimensions.find((dimension) => dimension.name === dimensionName);
+}
+function inferSpatialDimensions(source, variableName = source.variables[0]?.name) {
+  const variable = variableName ? findVariable(source, variableName) : source.variables[0];
+  if (source.spatialDimensions) {
+    return variableIncludesSpatialDimensions(variable, source.spatialDimensions) ? source.spatialDimensions : void 0;
+  }
+  const candidateNames = variable?.dimensions ?? source.dimensions.map((dimension) => dimension.name);
+  let x;
+  let y;
+  for (const name of candidateNames) {
+    const dimension = findDimension(source, name);
+    const normalizedName = name.toLowerCase();
+    const standardName = String(dimension?.standardName ?? "").toLowerCase();
+    const kind = dimension?.kind;
+    if (!x && (kind === "x" || xAliases.has(normalizedName) || standardName === "longitude")) {
+      x = name;
+    }
+    if (!y && (kind === "y" || yAliases.has(normalizedName) || standardName === "latitude")) {
+      y = name;
+    }
+  }
+  return x && y ? { x, y } : void 0;
+}
+function variableIncludesSpatialDimensions(variable, spatialDimensions) {
+  if (!variable) {
+    return false;
+  }
+  return variable.dimensions.includes(spatialDimensions.x) && variable.dimensions.includes(spatialDimensions.y);
+}
+function validateGridDataSource(source, options = {}) {
+  const errors = [];
+  const warnings = [];
+  if (source.variables.length === 0) {
+    errors.push(
+      new GridError({
+        code: "MISSING_VARIABLE",
+        message: "GridDataSource must expose at least one variable.",
+        sourceId: source.id
+      })
+    );
+  }
+  const variable = options.variable ? findVariable(source, options.variable) : source.variables[0];
+  if (options.variable && !variable) {
+    errors.push(
+      new GridError({
+        code: "MISSING_VARIABLE",
+        message: `Variable "${options.variable}" is not present in the grid source.`,
+        sourceId: source.id,
+        variable: options.variable
+      })
+    );
+  }
+  for (const dimension of source.dimensions) {
+    if (!Number.isInteger(dimension.size) || dimension.size <= 0) {
+      errors.push(
+        new GridError({
+          code: "UNSUPPORTED_DIMENSION",
+          message: `Dimension "${dimension.name}" must have a positive integer size.`,
+          dimension: dimension.name,
+          sourceId: source.id
+        })
+      );
+    }
+    if (dimension.coordinates && dimension.coordinates.length !== dimension.size) {
+      errors.push(
+        new GridError({
+          code: "MISSING_COORDINATES",
+          message: `Dimension "${dimension.name}" has ${dimension.coordinates.length} coordinates for size ${dimension.size}.`,
+          dimension: dimension.name,
+          sourceId: source.id
+        })
+      );
+    }
+  }
+  if (variable) {
+    if (!isNumericDType(variable.dtype)) {
+      errors.push(
+        new GridError({
+          code: "UNSUPPORTED_DTYPE",
+          message: `Variable "${variable.name}" has unsupported dtype "${variable.dtype}".`,
+          variable: variable.name,
+          sourceId: source.id
+        })
+      );
+    }
+    if (variable.dimensions.length !== variable.shape.length) {
+      errors.push(
+        new GridError({
+          code: "MISSING_DIMENSION",
+          message: `Variable "${variable.name}" has ${variable.dimensions.length} dimensions but ${variable.shape.length} shape entries.`,
+          variable: variable.name,
+          sourceId: source.id
+        })
+      );
+    }
+    variable.dimensions.forEach((dimensionName, index) => {
+      const dimension = findDimension(source, dimensionName);
+      if (!dimension) {
+        errors.push(
+          new GridError({
+            code: "MISSING_DIMENSION",
+            message: `Variable "${variable.name}" references missing dimension "${dimensionName}".`,
+            dimension: dimensionName,
+            variable: variable.name,
+            sourceId: source.id
+          })
+        );
+        return;
+      }
+      const expectedSize = variable.shape[index];
+      if (expectedSize !== dimension.size) {
+        warnings.push(
+          `Variable "${variable.name}" shape for dimension "${dimensionName}" is ${expectedSize}, but the dimension size is ${dimension.size}.`
+        );
+      }
+    });
+    const spatialDimensions = inferSpatialDimensions(source, variable.name);
+    if (!spatialDimensions) {
+      errors.push(
+        new GridError({
+          code: "MISSING_SPATIAL_DIMENSIONS",
+          message: `Variable "${variable.name}" needs latitude/longitude or x/y spatial dimensions before it can render.`,
+          variable: variable.name,
+          sourceId: source.id
+        })
+      );
+    }
+    if (options.requireRenderable && !source.bounds) {
+      errors.push(
+        new GridError({
+          code: "MISSING_BOUNDS",
+          message: "Renderable grid sources must include explicit [west, south, east, north] bounds.",
+          variable: variable.name,
+          sourceId: source.id
+        })
+      );
+    }
+  }
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function assertValidGridDataSource(source, options = {}) {
+  const result = validateGridDataSource(source, options);
+  if (!result.ok) {
+    throw result.errors[0];
+  }
+}
+function isNumericDType(dtype) {
+  return numericDtypes.has(dtype.toLowerCase()) || /^[<>|]?[ifu]\d+$/.test(dtype.toLowerCase());
+}
+
+// src/core/selectors.ts
+function indexSelector(index) {
+  return { kind: "index", index };
+}
+function coordinateSelector(value) {
+  return { kind: "coordinate", value };
+}
+function isoTimeSelector(iso) {
+  return { kind: "isoTime", iso };
+}
+function normalizeSelectors(source, variableName, selectors = {}) {
+  const variable = findVariable(source, variableName);
+  if (!variable) {
+    throw new GridError({
+      code: "MISSING_VARIABLE",
+      message: `Variable "${variableName}" is not present in the grid source.`,
+      variable: variableName,
+      sourceId: source.id
+    });
+  }
+  const normalized = {};
+  for (const dimensionName of variable.dimensions) {
+    const dimension = findDimension(source, dimensionName);
+    if (!dimension) {
+      throw new GridError({
+        code: "MISSING_DIMENSION",
+        message: `Selector normalization cannot find dimension "${dimensionName}".`,
+        dimension: dimensionName,
+        variable: variableName,
+        sourceId: source.id
+      });
+    }
+    const input = selectors[dimensionName];
+    if (input === void 0) {
+      normalized[dimensionName] = defaultSelectorForDimension(dimension);
+      continue;
+    }
+    normalized[dimensionName] = normalizeSelectorValue(dimension, input, source.id);
+  }
+  return normalized;
+}
+function normalizeSelectorValue(dimension, input, sourceId) {
+  if (input instanceof Date) {
+    return { kind: "coordinate", value: input.toISOString() };
+  }
+  if (typeof input !== "object") {
+    return normalizeCoordinateSelector(dimension, input, sourceId);
+  }
+  if (input.kind === "coordinate") {
+    const value = input.value instanceof Date ? input.value.toISOString() : input.value;
+    return normalizeCoordinateSelector(dimension, value, sourceId);
+  }
+  if (input.kind === "index") {
+    assertIndexInRange(dimension, input.index, sourceId);
+    const value = dimension.coordinates?.[input.index];
+    return {
+      kind: "index",
+      index: input.index,
+      value: value instanceof Date ? value.toISOString() : value
+    };
+  }
+  if (input.kind === "isoTime") {
+    const value = findCoordinateForIso(dimension, input.iso);
+    return value === void 0 ? { kind: "isoTime", iso: input.iso } : { kind: "isoTime", iso: input.iso, value };
+  }
+  throw new GridError({
+    code: "UNSUPPORTED_SELECTOR",
+    message: `Unsupported selector for dimension "${dimension.name}".`,
+    dimension: dimension.name,
+    sourceId
+  });
+}
+function toRendererSelectors(selectors) {
+  const output = {};
+  for (const [dimensionName, selector] of Object.entries(selectors)) {
+    if (selector.kind === "index") {
+      output[dimensionName] = { selected: selector.index, type: "index" };
+      continue;
+    }
+    if (selector.kind === "isoTime") {
+      output[dimensionName] = {
+        selected: selector.value ?? selector.iso,
+        type: "value"
+      };
+      continue;
+    }
+    output[dimensionName] = { selected: selector.value, type: "value" };
+  }
+  return output;
+}
+function selectorToIndex(dimension, selector) {
+  if (selector.kind === "index") {
+    return selector.index;
+  }
+  const selected = selector.kind === "isoTime" ? selector.value ?? selector.iso : selector.value;
+  const index = dimension.coordinates?.findIndex((coordinate) => sameCoordinate(coordinate, selected)) ?? -1;
+  if (index >= 0) {
+    return index;
+  }
+  throw new GridError({
+    code: "UNSUPPORTED_SELECTOR",
+    message: `Selector value "${String(selected)}" does not match coordinates for dimension "${dimension.name}".`,
+    dimension: dimension.name
+  });
+}
+function listTimeCoordinates(source, dimensionName = "time") {
+  const dimension = findDimension(source, dimensionName);
+  if (!dimension) {
+    throw new GridError({
+      code: "MISSING_DIMENSION",
+      message: `Time dimension "${dimensionName}" is not present in the grid source.`,
+      dimension: dimensionName,
+      sourceId: source.id
+    });
+  }
+  if (!dimension.coordinates) {
+    throw new GridError({
+      code: "MISSING_COORDINATES",
+      message: `Time dimension "${dimensionName}" needs coordinate values for a slider.`,
+      dimension: dimensionName,
+      sourceId: source.id
+    });
+  }
+  const coordinates = dimension.coordinates.map((coordinate, index) => {
+    const decoded = decodeTimeCoordinate(coordinate, dimension.units);
+    const forecastLabel = formatForecastStepLabel(source, dimension, coordinate);
+    return {
+      index,
+      value: decoded.value,
+      label: forecastLabel ?? (decoded.iso ? formatHumanUtcDateTime(decoded.iso) : String(decoded.value)),
+      ...decoded.iso ? { iso: decoded.iso } : {}
+    };
+  });
+  assertMonotonicTimeCoordinates(coordinates, dimension.name, source.id);
+  return coordinates;
+}
+function formatForecastStepLabel(source, dimension, coordinate) {
+  if (!isForecastStepDimension(dimension.name)) {
+    return void 0;
+  }
+  const reference = forecastReferenceDate(source);
+  const offsetMs = forecastStepOffsetMs(coordinate, dimension.units);
+  if (!reference || offsetMs === void 0) {
+    return void 0;
+  }
+  return formatHumanUtcDateTime(new Date(reference.getTime() + offsetMs));
+}
+function isForecastStepDimension(name) {
+  return normalizeDimensionName(name) === "step";
+}
+function forecastReferenceDate(source) {
+  const referenceDimension = source.dimensions.find(
+    (dimension) => ["forecastreferencetime", "forecastreferencedate"].includes(
+      normalizeDimensionName(dimension.name)
+    )
+  );
+  if (!referenceDimension) {
+    return void 0;
+  }
+  const referenceCoordinate = referenceDimension.coordinates?.[0];
+  if (referenceCoordinate === void 0) {
+    return void 0;
+  }
+  const decoded = decodeTimeCoordinate(referenceCoordinate, referenceDimension.units);
+  const referenceValue = decoded.iso ?? (typeof decoded.value === "string" ? decoded.value : void 0);
+  if (!referenceValue) {
+    return void 0;
+  }
+  const date = new Date(referenceValue);
+  return Number.isNaN(date.getTime()) ? void 0 : date;
+}
+function forecastStepOffsetMs(coordinate, units) {
+  const value = numericCoordinateValue(coordinate);
+  if (value === void 0) {
+    return void 0;
+  }
+  return value * forecastStepUnitMultiplier(units);
+}
+function numericCoordinateValue(coordinate) {
+  if (typeof coordinate === "number") {
+    return Number.isFinite(coordinate) ? coordinate : void 0;
+  }
+  if (typeof coordinate !== "string") {
+    return void 0;
+  }
+  const value = Number(coordinate);
+  return Number.isFinite(value) ? value : void 0;
+}
+function forecastStepUnitMultiplier(units) {
+  const normalizedUnits = units?.toLowerCase() ?? "";
+  if (normalizedUnits.includes("second")) {
+    return 1e3;
+  }
+  if (normalizedUnits.includes("minute")) {
+    return 6e4;
+  }
+  if (normalizedUnits.includes("day")) {
+    return 864e5;
+  }
+  return 36e5;
+}
+function normalizeDimensionName(name) {
+  return name.toLowerCase().replace(/[_\-\s]+/g, "");
+}
+var UTC_MONTH_LABELS = [
+  "Jan",
+  "Feb",
+  "Mar",
+  "Apr",
+  "May",
+  "Jun",
+  "Jul",
+  "Aug",
+  "Sep",
+  "Oct",
+  "Nov",
+  "Dec"
+];
+function formatHumanUtcDateTime(input) {
+  const date = input instanceof Date ? input : new Date(input);
+  return [
+    UTC_MONTH_LABELS[date.getUTCMonth()],
+    " ",
+    date.getUTCDate(),
+    ", ",
+    date.getUTCFullYear(),
+    ", ",
+    padDatePart(date.getUTCHours()),
+    ":",
+    padDatePart(date.getUTCMinutes()),
+    " UTC"
+  ].join("");
+}
+function padDatePart(value) {
+  return String(value).padStart(2, "0");
+}
+function createDebouncer(callback, waitMs) {
+  let timeout;
+  let lastArgs;
+  const flush = () => {
+    if (!lastArgs) {
+      return;
+    }
+    const args = lastArgs;
+    lastArgs = void 0;
+    if (timeout) {
+      clearTimeout(timeout);
+      timeout = void 0;
+    }
+    callback(...args);
+  };
+  return {
+    call(...args) {
+      lastArgs = args;
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      timeout = setTimeout(flush, waitMs);
+    },
+    flush,
+    cancel() {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+      timeout = void 0;
+      lastArgs = void 0;
+    }
+  };
+}
+function defaultSelectorForDimension(dimension) {
+  const firstValue = dimension.coordinates?.[0];
+  if (firstValue !== void 0) {
+    return {
+      kind: "coordinate",
+      value: firstValue instanceof Date ? firstValue.toISOString() : firstValue
+    };
+  }
+  return { kind: "index", index: 0 };
+}
+function normalizeCoordinateSelector(dimension, value, sourceId) {
+  if (dimension.coordinates && !dimension.coordinates.some((coordinate) => sameCoordinate(coordinate, value))) {
+    throw new GridError({
+      code: "UNSUPPORTED_SELECTOR",
+      message: `Selector value "${String(value)}" does not match coordinates for dimension "${dimension.name}".`,
+      dimension: dimension.name,
+      sourceId
+    });
+  }
+  return { kind: "coordinate", value };
+}
+function assertIndexInRange(dimension, index, sourceId) {
+  if (!Number.isInteger(index) || index < 0 || index >= dimension.size) {
+    throw new GridError({
+      code: "UNSUPPORTED_SELECTOR",
+      message: `Index selector ${index} is outside dimension "${dimension.name}" size ${dimension.size}.`,
+      dimension: dimension.name,
+      sourceId
+    });
+  }
+}
+function findCoordinateForIso(dimension, iso) {
+  return dimension.coordinates?.map((coordinate) => decodeTimeCoordinate(coordinate, dimension.units)).find((coordinate) => coordinate.iso === iso || coordinate.value === iso)?.value;
+}
+function decodeTimeCoordinate(coordinate, units) {
+  if (coordinate instanceof Date) {
+    return { value: coordinate.toISOString(), iso: coordinate.toISOString() };
+  }
+  if (typeof coordinate === "string") {
+    const date = new Date(coordinate);
+    return Number.isNaN(date.getTime()) ? { value: coordinate } : { value: coordinate, iso: date.toISOString() };
+  }
+  const cfTime = decodeCfTime(coordinate, units);
+  return cfTime ? { value: coordinate, iso: cfTime } : { value: coordinate };
+}
+function decodeCfTime(value, units) {
+  if (!units) {
+    return void 0;
+  }
+  const match = /^(seconds|minutes|hours|days) since ([0-9]{4}-[0-9]{2}-[0-9]{2})(?:[ T]([0-9:.Z+-]+))?/i.exec(
+    units
+  );
+  if (!match) {
+    return void 0;
+  }
+  const unit = match[1]?.toLowerCase();
+  const date = match[2];
+  const time = match[3] ?? "00:00:00Z";
+  const origin = /* @__PURE__ */ new Date(`${date}T${time.replace(/Z?$/, "Z")}`);
+  if (Number.isNaN(origin.getTime())) {
+    return void 0;
+  }
+  const multiplier = unit === "seconds" ? 1e3 : unit === "minutes" ? 6e4 : unit === "hours" ? 36e5 : 864e5;
+  return new Date(origin.getTime() + value * multiplier).toISOString();
+}
+function assertMonotonicTimeCoordinates(coordinates, dimensionName, sourceId) {
+  let direction;
+  for (let index = 1; index < coordinates.length; index += 1) {
+    const previous = comparableTimeValue(coordinates[index - 1]);
+    const current = comparableTimeValue(coordinates[index]);
+    if (previous === current) {
+      throw new GridError({
+        code: "UNSUPPORTED_DIMENSION",
+        message: `Time dimension "${dimensionName}" has duplicate coordinate values.`,
+        dimension: dimensionName,
+        sourceId
+      });
+    }
+    const pairDirection = current > previous ? "ascending" : "descending";
+    direction ??= pairDirection;
+    if (pairDirection !== direction) {
+      throw new GridError({
+        code: "UNSUPPORTED_DIMENSION",
+        message: `Time dimension "${dimensionName}" must be monotonic for slider controls.`,
+        dimension: dimensionName,
+        sourceId
+      });
+    }
+  }
+}
+function comparableTimeValue(coordinate) {
+  if (!coordinate) {
+    return 0;
+  }
+  if (coordinate.iso) {
+    return new Date(coordinate.iso).getTime();
+  }
+  if (typeof coordinate.value === "number") {
+    return coordinate.value;
+  }
+  const parsed = new Date(coordinate.value).getTime();
+  return Number.isNaN(parsed) ? coordinate.index : parsed;
+}
+function sameCoordinate(left, right) {
+  const normalizedLeft = left instanceof Date ? left.toISOString() : left;
+  return normalizedLeft === right || String(normalizedLeft) === String(right);
+}
+
+// src/core/jaxray.ts
+function createJaxraySource(input, options = {}) {
+  const dataset = isDatasetLike(input) ? input : arrayToDataset(input);
+  const variables = inferVariables(dataset, options);
+  const dimensions = inferDimensions(dataset, variables, options);
+  const source = {
+    id: options.id ?? dataset.id,
+    label: options.label,
+    source: options.source,
+    store: options.store ?? dataset.store,
+    zarrVersion: options.zarrVersion,
+    crs: options.crs ?? stringAttr(dataset.attrs, "crs") ?? "EPSG:4326",
+    proj4: options.proj4 ?? stringAttr(dataset.attrs, "proj4"),
+    bounds: options.bounds ?? inferBounds(dimensions, dataset.attrs),
+    spatialDimensions: options.spatialDimensions,
+    dimensions,
+    variables,
+    metadata: dataset.attrs,
+    readSlice: async (request) => readJaxraySlice(dataset, source, request.variable, request.selectors)
+  };
+  const firstSpatialVariable = variables.find(
+    (variable) => inferSpatialDimensions(source, variable.name)
+  );
+  source.spatialDimensions = options.spatialDimensions ?? inferSpatialDimensions(source) ?? (firstSpatialVariable ? inferSpatialDimensions(source, firstSpatialVariable.name) : void 0);
+  assertValidGridDataSource(source, {
+    variable: firstSpatialVariable?.name ?? variables[0]?.name
+  });
+  return source;
+}
+function isDatasetLike(input) {
+  return "data_vars" in input || "dataVars" in input || "variables" in input && !("shape" in input) || "sizes" in input;
+}
+function arrayToDataset(array) {
+  const name = array.name ?? "variable";
+  return {
+    data_vars: { [name]: array },
+    coords: array.coords,
+    attrs: array.attrs
+  };
+}
+function inferVariables(dataset, options) {
+  return Array.from(variableEntries(dataset)).map(([name, array]) => {
+    const dimensions = array.dims ?? array.dimensions;
+    if (!dimensions) {
+      throw new GridError({
+        code: "MISSING_DIMENSION",
+        message: `Jaxray variable "${name}" does not expose dims/dimensions metadata.`,
+        variable: name
+      });
+    }
+    const shape = array.shape ?? dimensions.map((dimensionName) => dimensionSize(dataset, dimensionName));
+    if (!shape) {
+      throw new GridError({
+        code: "MISSING_DIMENSION",
+        message: `Jaxray variable "${name}" does not expose shape metadata.`,
+        variable: name
+      });
+    }
+    const override = options.variables?.[name] ?? {};
+    return {
+      name,
+      path: stringAttr(array.attrs, "path"),
+      dtype: override.dtype ?? array.dtype ?? stringAttr(array.attrs, "dtype") ?? "float32",
+      dimensions,
+      shape,
+      chunks: override.chunks ?? array.chunks,
+      units: override.units ?? stringAttr(array.attrs, "units"),
+      longName: override.longName ?? stringAttr(array.attrs, "long_name"),
+      standardName: override.standardName ?? stringAttr(array.attrs, "standard_name"),
+      fillValue: override.fillValue ?? numberAttr(array.attrs, "_FillValue") ?? numberAttr(array.attrs, "fill_value") ?? null,
+      scaleFactor: override.scaleFactor ?? numberAttr(array.attrs, "scale_factor"),
+      addOffset: override.addOffset ?? numberAttr(array.attrs, "add_offset"),
+      attrs: array.attrs
+    };
+  });
+}
+function inferDimensions(dataset, variables, options) {
+  const dimensions = /* @__PURE__ */ new Map();
+  const coords = dataset.coords;
+  for (const variable of variables) {
+    variable.dimensions.forEach((name, index) => {
+      const existing = dimensions.get(name);
+      const coordinates = normalizeCoordinateArray(coordinateValue(coords, name));
+      const override = options.dimensions?.[name] ?? {};
+      const inferredKind = inferDimensionKind(name);
+      const size = variable.shape[index] ?? coordinates?.length ?? 0;
+      dimensions.set(name, {
+        ...existing,
+        name,
+        size: override.size ?? existing?.size ?? size,
+        kind: override.kind ?? existing?.kind ?? inferredKind,
+        coordinates: override.coordinates ?? existing?.coordinates ?? coordinates,
+        units: override.units ?? existing?.units,
+        calendar: override.calendar ?? existing?.calendar,
+        longName: override.longName ?? existing?.longName,
+        standardName: override.standardName ?? existing?.standardName,
+        ascending: override.ascending ?? existing?.ascending ?? inferAscending(coordinates),
+        attrs: override.attrs ?? existing?.attrs
+      });
+    });
+  }
+  return Array.from(dimensions.values());
+}
+function inferDimensionKind(name) {
+  const normalized = name.toLowerCase();
+  if (["lon", "lng", "longitude", "x"].includes(normalized)) {
+    return "x";
+  }
+  if (["lat", "latitude", "y"].includes(normalized)) {
+    return "y";
+  }
+  if (["time", "valid_time", "date"].includes(normalized)) {
+    return "time";
+  }
+  if (["band", "month"].includes(normalized)) {
+    return "band";
+  }
+  if (["level", "height", "pressure"].includes(normalized)) {
+    return "vertical";
+  }
+  return "other";
+}
+function inferBounds(dimensions, attrs) {
+  const attrBounds = attrs?.bounds;
+  if (Array.isArray(attrBounds) && attrBounds.length === 4 && attrBounds.every((value) => typeof value === "number")) {
+    return attrBounds;
+  }
+  const x = dimensions.find((dimension) => dimension.kind === "x");
+  const y = dimensions.find((dimension) => dimension.kind === "y");
+  const xCoordinates = x?.coordinates?.filter(
+    (value) => typeof value === "number"
+  );
+  const yCoordinates = y?.coordinates?.filter(
+    (value) => typeof value === "number"
+  );
+  if (!xCoordinates?.length || !yCoordinates?.length) {
+    return void 0;
+  }
+  return [
+    Math.min(...xCoordinates),
+    Math.min(...yCoordinates),
+    Math.max(...xCoordinates),
+    Math.max(...yCoordinates)
+  ];
+}
+async function readJaxraySlice(dataset, source, variableName, selectors = {}) {
+  const entry = variableEntries(dataset).find(([name2]) => name2 === variableName);
+  if (!entry) {
+    throw new GridError({
+      code: "MISSING_VARIABLE",
+      message: `Jaxray source cannot read missing variable "${variableName}".`,
+      variable: variableName,
+      sourceId: source.id
+    });
+  }
+  const [name, array] = entry;
+  const variable = source.variables.find((candidate) => candidate.name === name);
+  if (!variable) {
+    throw new GridError({
+      code: "MISSING_VARIABLE",
+      message: `Jaxray source metadata is missing variable "${name}".`,
+      variable: name,
+      sourceId: source.id
+    });
+  }
+  const normalizedSelectors = isNormalizedSelectors(selectors) ? selectors : normalizeSelectors(source, variable.name, selectors);
+  const selection = variable.dimensions.reduce(
+    (accumulator, dimensionName) => {
+      const dimension = findDimension(source, dimensionName);
+      if (!dimension) {
+        return accumulator;
+      }
+      accumulator[dimensionName] = selectorToIndex(
+        dimension,
+        normalizedSelectors[dimensionName] ?? { kind: "index", index: 0 }
+      );
+      return accumulator;
+    },
+    {}
+  );
+  const value = await readArrayValue(array, variable, selection);
+  return {
+    variable: name,
+    selectors: normalizedSelectors,
+    dimensions: [],
+    shape: [],
+    data: [value],
+    unit: variable.units,
+    fillValue: variable.fillValue
+  };
+}
+async function readArrayValue(array, variable, selection) {
+  if (array.get) {
+    return array.get(selection);
+  }
+  if (array.isel) {
+    const selected = await array.isel(selection);
+    const computed = selected.isLazy && selected.compute ? await selected.compute() : selected;
+    return scalarFromArrayLike(computed.data ?? computed.values);
+  }
+  const data = array.data ?? array.values;
+  if (!data) {
+    throw new GridError({
+      code: "SOURCE_LOAD_FAILED",
+      message: `Jaxray variable "${variable.name}" does not expose readable data for query helpers.`,
+      variable: variable.name
+    });
+  }
+  let offset = 0;
+  let stride = 1;
+  for (let index = variable.dimensions.length - 1; index >= 0; index -= 1) {
+    const dimensionName = variable.dimensions[index];
+    if (!dimensionName) {
+      continue;
+    }
+    offset += (selection[dimensionName] ?? 0) * stride;
+    stride *= variable.shape[index] ?? 1;
+  }
+  return data[offset] ?? Number.NaN;
+}
+function scalarFromArrayLike(value) {
+  if (typeof value === "number") {
+    return value;
+  }
+  if (Array.isArray(value) || ArrayBuffer.isView(value)) {
+    const first = Array.from(value)[0];
+    return scalarFromArrayLike(first);
+  }
+  return Number.NaN;
+}
+function variableEntries(dataset) {
+  if (Array.isArray(dataset.dataVars) && typeof dataset.getVariable === "function") {
+    return dataset.dataVars.map((name) => [name, dataset.getVariable?.(name) ?? {}]);
+  }
+  if (Array.isArray(dataset.dataVars)) {
+    throw new GridError({
+      code: "MISSING_VARIABLE",
+      message: "Jaxray Dataset exposes dataVars names but no getVariable(name) method."
+    });
+  }
+  const variables = dataset.data_vars ?? dataset.dataVars ?? dataset.variables ?? {};
+  if (variables instanceof Map) {
+    return Array.from(variables.entries());
+  }
+  return Object.entries(variables);
+}
+function normalizeCoordinateArray(input) {
+  const raw = Array.isArray(input) ? input : ArrayBuffer.isView(input) ? Array.from(input) : typeof input === "object" && input !== null && "values" in input && isArrayLike(input.values) ? Array.from(input.values) : typeof input === "object" && input !== null && "data" in input && isArrayLike(input.data) ? Array.from(input.data) : void 0;
+  return raw?.filter(
+    (value) => typeof value === "number" || typeof value === "string"
+  );
+}
+function coordinateValue(coords, name) {
+  if (!coords) {
+    return void 0;
+  }
+  return coords instanceof Map ? coords.get(name) : coords[name];
+}
+function dimensionSize(dataset, dimensionName) {
+  const sizes = dataset.sizes;
+  if (!sizes) {
+    return 0;
+  }
+  return sizes instanceof Map ? sizes.get(dimensionName) ?? 0 : sizes[dimensionName] ?? 0;
+}
+function isArrayLike(value) {
+  return Array.isArray(value) || ArrayBuffer.isView(value) || typeof value === "object" && value !== null && "length" in value && typeof value.length === "number";
+}
+function inferAscending(coordinates) {
+  if (!coordinates || coordinates.length < 2) {
+    return void 0;
+  }
+  const first = coordinates[0];
+  const second = coordinates[1];
+  return typeof first === "number" && typeof second === "number" ? second > first : void 0;
+}
+function stringAttr(attrs, name) {
+  const value = attrs?.[name];
+  return typeof value === "string" ? value : void 0;
+}
+function numberAttr(attrs, name) {
+  const value = attrs?.[name];
+  return typeof value === "number" ? value : void 0;
+}
+function isNormalizedSelectors(selectors) {
+  return Object.values(selectors).every(
+    (value) => typeof value === "object" && value !== null && "kind" in value
+  );
+}
+
+// src/core/preflight.ts
+var dtypeByteSizes = {
+  int8: 1,
+  uint8: 1,
+  i1: 1,
+  u1: 1,
+  int16: 2,
+  uint16: 2,
+  i2: 2,
+  u2: 2,
+  int32: 4,
+  uint32: 4,
+  float32: 4,
+  i4: 4,
+  u4: 4,
+  f4: 4,
+  float64: 8,
+  f8: 8
+};
+function preflightGridRequest(options) {
+  const errors = [];
+  const warnings = [];
+  const dimensions = {};
+  const variable = findVariable(options.source, options.variable);
+  if (!variable) {
+    errors.push(
+      new GridError({
+        code: "MISSING_VARIABLE",
+        message: `Variable "${options.variable}" is not present in the grid source.`,
+        sourceId: options.source.id,
+        variable: options.variable
+      })
+    );
+    return { ok: false, dimensions, warnings, errors };
+  }
+  const spatialDimensions = inferSpatialDimensions(options.source, variable.name);
+  for (const dimensionName of variable.dimensions) {
+    const dimension = findDimension(options.source, dimensionName);
+    if (!dimension) {
+      errors.push(
+        new GridError({
+          code: "MISSING_DIMENSION",
+          message: `Variable "${variable.name}" references missing dimension "${dimensionName}".`,
+          dimension: dimensionName,
+          sourceId: options.source.id,
+          variable: variable.name
+        })
+      );
+      continue;
+    }
+    dimensions[dimension.name] = selectedDimensionSize({
+      bounds: options.bounds,
+      dimension,
+      isSpatialX: spatialDimensions?.x === dimension.name,
+      isSpatialY: spatialDimensions?.y === dimension.name,
+      selectorIsPresent: options.selectors?.[dimension.name] !== void 0,
+      sourceBounds: options.source.bounds,
+      timeRange: options.timeRange,
+      warnings
+    });
+  }
+  const cells = Object.values(dimensions).reduce((total, size) => total * size, 1);
+  const byteSize = dtypeByteSize(variable.dtype);
+  const bytes = byteSize === void 0 ? void 0 : cells * byteSize;
+  if (byteSize === void 0) {
+    warnings.push(`Variable "${variable.name}" has unknown dtype byte size "${variable.dtype}".`);
+  }
+  if (options.limits?.maxCells !== void 0 && cells > options.limits.maxCells) {
+    errors.push(
+      new GridError({
+        code: "QUERY_TOO_EXPENSIVE",
+        message: `Grid request would select approximately ${cells} cells, above the limit of ${options.limits.maxCells}.`,
+        context: { cells, maxCells: options.limits.maxCells },
+        sourceId: options.source.id,
+        variable: variable.name
+      })
+    );
+  }
+  if (bytes !== void 0 && options.limits?.maxBytes !== void 0 && bytes > options.limits.maxBytes) {
+    errors.push(
+      new GridError({
+        code: "QUERY_TOO_EXPENSIVE",
+        message: `Grid request would read approximately ${bytes} uncompressed bytes, above the limit of ${options.limits.maxBytes}.`,
+        context: { bytes, maxBytes: options.limits.maxBytes },
+        sourceId: options.source.id,
+        variable: variable.name
+      })
+    );
+  }
+  return {
+    ok: errors.length === 0,
+    cells,
+    bytes,
+    dimensions,
+    warnings,
+    errors
+  };
+}
+function selectedDimensionSize(options) {
+  if (options.selectorIsPresent) {
+    return 1;
+  }
+  if (options.bounds && options.isSpatialX) {
+    return spatialCount(options.dimension, options.bounds[0], options.bounds[2], {
+      axis: "x",
+      sourceBounds: options.sourceBounds,
+      warnings: options.warnings
+    });
+  }
+  if (options.bounds && options.isSpatialY) {
+    return spatialCount(options.dimension, options.bounds[1], options.bounds[3], {
+      axis: "y",
+      sourceBounds: options.sourceBounds,
+      warnings: options.warnings
+    });
+  }
+  if (options.timeRange && options.dimension.kind === "time") {
+    return timeRangeCount(options.dimension, options.timeRange, options.warnings);
+  }
+  return options.dimension.size;
+}
+function spatialCount(dimension, lowerBound, upperBound, options) {
+  const low = Math.min(lowerBound, upperBound);
+  const high = Math.max(lowerBound, upperBound);
+  const numericCoordinates = dimension.coordinates?.filter(
+    (coordinate) => typeof coordinate === "number"
+  );
+  if (numericCoordinates?.length) {
+    return numericCoordinates.filter((coordinate) => coordinate >= low && coordinate <= high).length;
+  }
+  const sourceRange = spatialRange(options.sourceBounds, options.axis);
+  if (!sourceRange) {
+    options.warnings.push(
+      `Dimension "${dimension.name}" has no coordinates or source bounds, so preflight used the full dimension size.`
+    );
+    return dimension.size;
+  }
+  const [sourceLow, sourceHigh] = sourceRange;
+  const span = sourceHigh - sourceLow;
+  if (span <= 0 || dimension.size <= 0) {
+    return 0;
+  }
+  const overlap = Math.max(0, Math.min(high, sourceHigh) - Math.max(low, sourceLow));
+  if (overlap === 0) {
+    return 0;
+  }
+  return Math.max(1, Math.min(dimension.size, Math.ceil(overlap / span * dimension.size)));
+}
+function timeRangeCount(dimension, timeRange, warnings) {
+  if (!dimension.coordinates?.length) {
+    warnings.push(
+      `Time dimension "${dimension.name}" has no coordinates, so preflight used the full time size.`
+    );
+    return dimension.size;
+  }
+  const start = timeToMillis(timeRange.start, dimension.units);
+  const end = timeToMillis(timeRange.end, dimension.units);
+  if (start === void 0 || end === void 0) {
+    warnings.push(
+      `Time range for "${dimension.name}" could not be parsed, so preflight used the full time size.`
+    );
+    return dimension.size;
+  }
+  const low = Math.min(start, end);
+  const high = Math.max(start, end);
+  let count = 0;
+  for (const coordinate of dimension.coordinates) {
+    const value = timeToMillis(coordinate, dimension.units);
+    if (value !== void 0 && value >= low && value <= high) {
+      count += 1;
+    }
+  }
+  return count;
+}
+function timeToMillis(value, units) {
+  if (value instanceof Date) {
+    return value.getTime();
+  }
+  if (typeof value === "string") {
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? void 0 : parsed;
+  }
+  if (typeof value === "number") {
+    return numericTimeToMillis(value, units);
+  }
+  return void 0;
+}
+function numericTimeToMillis(value, units) {
+  if (!units) {
+    return void 0;
+  }
+  const match = /^(seconds?|minutes?|hours?|days?) since (.+)$/i.exec(units.trim());
+  if (!match) {
+    return void 0;
+  }
+  const [, unit, epoch] = match;
+  if (!unit || !epoch) {
+    return void 0;
+  }
+  const epochMillis = Date.parse(epoch);
+  if (Number.isNaN(epochMillis)) {
+    return void 0;
+  }
+  const multiplier = unit.toLowerCase().startsWith("second") ? 1e3 : unit.toLowerCase().startsWith("minute") ? 60 * 1e3 : unit.toLowerCase().startsWith("hour") ? 60 * 60 * 1e3 : 24 * 60 * 60 * 1e3;
+  return epochMillis + value * multiplier;
+}
+function spatialRange(bounds, axis) {
+  if (!bounds) {
+    return void 0;
+  }
+  return axis === "x" ? [bounds[0], bounds[2]] : [bounds[1], bounds[3]];
+}
+function dtypeByteSize(dtype) {
+  const normalized = dtype.toLowerCase().replace(/^[<>|]/, "");
+  return dtypeByteSizes[normalized];
+}
+
+// src/core/query.ts
+async function queryGrid(request) {
+  if (request.signal?.aborted) {
+    throw abortedError();
+  }
+  if (request.source.queryGeometry) {
+    return request.source.queryGeometry({
+      variable: request.variable,
+      geometry: request.geometry,
+      selectors: request.selectors,
+      maxCells: request.maxCells,
+      signal: request.signal
+    });
+  }
+  switch (request.geometry.type) {
+    case "Point":
+      return queryPoint(
+        request.source,
+        request.variable,
+        request.geometry.coordinates,
+        request.selectors,
+        request.signal
+      );
+    case "BoundingBox":
+      return queryBoundingBox({
+        ...request,
+        geometry: request.geometry
+      });
+    case "Polygon":
+      return queryPolygon({
+        ...request,
+        geometry: request.geometry
+      });
+    default:
+      throw new GridError({
+        code: "UNSUPPORTED_GEOMETRY",
+        message: "Unsupported grid query geometry."
+      });
+  }
+}
+async function queryPoint(source, variableName, coordinates, selectors = {}, signal) {
+  const context = queryContext(source, variableName, selectors);
+  const xIndex = nearestCoordinateIndex(context.xDimension, coordinates[0], source.bounds, "x");
+  const yIndex = nearestCoordinateIndex(context.yDimension, coordinates[1], source.bounds, "y");
+  const sample = await readSample(source, context, xIndex, yIndex, signal);
+  return {
+    variable: variableName,
+    selectors: context.normalizedSelectors,
+    geometry: { type: "Point", coordinates },
+    unit: context.variable.units,
+    samples: [sample],
+    warnings: []
+  };
+}
+async function queryBoundingBox(request) {
+  const context = queryContext(request.source, request.variable, request.selectors);
+  const [west, south, east, north] = request.geometry.bounds;
+  const xIndexes = coordinateIndexesInBounds(context.xDimension, west, east);
+  const yIndexes = coordinateIndexesInBounds(context.yDimension, south, north);
+  const estimatedCells = xIndexes.length * yIndexes.length;
+  const maxCells = request.maxCells ?? 1e4;
+  if (estimatedCells > maxCells) {
+    throw new GridError({
+      code: "QUERY_TOO_EXPENSIVE",
+      message: `Bounding-box query would inspect ${estimatedCells} cells, above the limit of ${maxCells}.`,
+      context: { estimatedCells, maxCells }
+    });
+  }
+  const samples = [];
+  for (const yIndex of yIndexes) {
+    for (const xIndex of xIndexes) {
+      if (request.signal?.aborted) {
+        throw abortedError();
+      }
+      samples.push(await readSample(request.source, context, xIndex, yIndex, request.signal));
+    }
+  }
+  return {
+    variable: request.variable,
+    selectors: context.normalizedSelectors,
+    geometry: request.geometry,
+    unit: context.variable.units,
+    samples,
+    warnings: estimatedCells > 1e3 ? ["Large bounded query; consider lowering maxCells or querying a coarser grid."] : []
+  };
+}
+async function queryPolygon(request) {
+  const bounds = polygonBounds(request.geometry.coordinates);
+  const bounded = await queryBoundingBox({
+    ...request,
+    geometry: { type: "BoundingBox", bounds }
+  });
+  return {
+    ...bounded,
+    geometry: request.geometry,
+    samples: bounded.samples.filter(
+      (sample) => pointInPolygon(sample.coordinates, request.geometry.coordinates)
+    ),
+    warnings: [
+      ...bounded.warnings,
+      "Polygon queries are evaluated by scanning the polygon bounding box."
+    ]
+  };
+}
+function queryContext(source, variableName, selectors = {}) {
+  const variable = findVariable(source, variableName);
+  if (!variable) {
+    throw new GridError({
+      code: "MISSING_VARIABLE",
+      message: `Variable "${variableName}" is not present in the grid source.`,
+      variable: variableName,
+      sourceId: source.id
+    });
+  }
+  const spatialDimensions = inferSpatialDimensions(source, variable.name);
+  if (!spatialDimensions) {
+    throw new GridError({
+      code: "MISSING_SPATIAL_DIMENSIONS",
+      message: `Variable "${variable.name}" needs spatial dimensions for map queries.`,
+      variable: variable.name,
+      sourceId: source.id
+    });
+  }
+  const xDimension = findDimension(source, spatialDimensions.x);
+  const yDimension = findDimension(source, spatialDimensions.y);
+  if (!xDimension || !yDimension) {
+    throw new GridError({
+      code: "MISSING_SPATIAL_DIMENSIONS",
+      message: "Spatial dimensions are missing from the grid source.",
+      variable: variable.name,
+      sourceId: source.id
+    });
+  }
+  if (!source.readSlice) {
+    throw new GridError({
+      code: "SOURCE_LOAD_FAILED",
+      message: "GridDataSource must implement readSlice or queryGeometry before query helpers can read values.",
+      sourceId: source.id,
+      variable: variable.name
+    });
+  }
+  return {
+    variable,
+    normalizedSelectors: normalizeSelectors(source, variable.name, selectors),
+    xDimension,
+    yDimension,
+    spatialDimensions
+  };
+}
+async function readSample(source, context, xIndex, yIndex, signal) {
+  if (signal?.aborted) {
+    throw abortedError();
+  }
+  const selectors = selectorsWithSpatialIndexes(
+    context.normalizedSelectors,
+    context.spatialDimensions.x,
+    xIndex,
+    context.spatialDimensions.y,
+    yIndex
+  );
+  const slice = await source.readSlice?.({
+    variable: context.variable.name,
+    selectors,
+    signal
+  });
+  const rawValue = slice?.data[0];
+  const value = rawValue === void 0 || rawValue === context.variable.fillValue ? null : rawValue * (context.variable.scaleFactor ?? 1) + (context.variable.addOffset ?? 0);
+  return {
+    coordinates: [
+      coordinateAt(context.xDimension, xIndex, source.bounds, "x"),
+      coordinateAt(context.yDimension, yIndex, source.bounds, "y")
+    ],
+    indexes: {
+      [context.spatialDimensions.x]: xIndex,
+      [context.spatialDimensions.y]: yIndex
+    },
+    rawValue: rawValue ?? null,
+    value
+  };
+}
+function selectorsWithSpatialIndexes(selectors, xDimension, xIndex, yDimension, yIndex) {
+  return {
+    ...selectors,
+    [xDimension]: { kind: "index", index: xIndex },
+    [yDimension]: { kind: "index", index: yIndex }
+  };
+}
+function nearestCoordinateIndex(dimension, value, bounds, axis) {
+  if (!dimension.coordinates) {
+    return boundedCoordinateIndex(dimension, value, bounds, axis);
+  }
+  let bestIndex = 0;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  dimension.coordinates.forEach((coordinate, index) => {
+    if (typeof coordinate !== "number") {
+      return;
+    }
+    const distance = Math.abs(coordinate - value);
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      bestIndex = index;
+    }
+  });
+  return bestIndex;
+}
+function coordinateIndexesInBounds(dimension, min, max) {
+  if (!dimension.coordinates) {
+    return range(
+      clamp(Math.floor(min), 0, dimension.size - 1),
+      clamp(Math.ceil(max), 0, dimension.size - 1)
+    );
+  }
+  const low = Math.min(min, max);
+  const high = Math.max(min, max);
+  return dimension.coordinates.reduce((indexes, coordinate, index) => {
+    if (typeof coordinate === "number" && coordinate >= low && coordinate <= high) {
+      indexes.push(index);
+    }
+    return indexes;
+  }, []);
+}
+function coordinateAt(dimension, index, bounds, axis) {
+  const coordinate = dimension.coordinates?.[index];
+  if (typeof coordinate === "number") {
+    return coordinate;
+  }
+  return boundedCoordinateAt(dimension, index, bounds, axis);
+}
+function boundedCoordinateIndex(dimension, value, bounds, axis) {
+  const range2 = spatialRange2(bounds, axis);
+  if (!range2) {
+    return clamp(Math.round(value), 0, dimension.size - 1);
+  }
+  const [min, max] = range2;
+  const span = max - min;
+  if (span <= 0 || dimension.size <= 1) {
+    return 0;
+  }
+  const ascending = dimension.ascending !== false;
+  const ratio = ascending ? (value - min) / span : (max - value) / span;
+  return clamp(Math.round(ratio * (dimension.size - 1)), 0, dimension.size - 1);
+}
+function boundedCoordinateAt(dimension, index, bounds, axis) {
+  const range2 = spatialRange2(bounds, axis);
+  if (!range2 || dimension.size <= 1) {
+    return index;
+  }
+  const [min, max] = range2;
+  const ratio = clamp(index, 0, dimension.size - 1) / (dimension.size - 1);
+  return dimension.ascending === false ? max - ratio * (max - min) : min + ratio * (max - min);
+}
+function spatialRange2(bounds, axis) {
+  if (!bounds) {
+    return void 0;
+  }
+  return axis === "x" ? [bounds[0], bounds[2]] : [bounds[1], bounds[3]];
+}
+function range(start, end) {
+  const values = [];
+  for (let index = start; index <= end; index += 1) {
+    values.push(index);
+  }
+  return values;
+}
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+function polygonBounds(coordinates) {
+  return coordinates.reduce(
+    (bounds, [x, y]) => [
+      Math.min(bounds[0], x),
+      Math.min(bounds[1], y),
+      Math.max(bounds[2], x),
+      Math.max(bounds[3], y)
+    ],
+    [
+      Number.POSITIVE_INFINITY,
+      Number.POSITIVE_INFINITY,
+      Number.NEGATIVE_INFINITY,
+      Number.NEGATIVE_INFINITY
+    ]
+  );
+}
+function pointInPolygon(point, polygon) {
+  let inside = false;
+  for (let index = 0, previous = polygon.length - 1; index < polygon.length; previous = index, index += 1) {
+    const currentPoint = polygon[index];
+    const previousPoint = polygon[previous];
+    if (!currentPoint || !previousPoint) {
+      continue;
+    }
+    const intersects = currentPoint[1] > point[1] !== previousPoint[1] > point[1] && point[0] < (previousPoint[0] - currentPoint[0]) * (point[1] - currentPoint[1]) / (previousPoint[1] - currentPoint[1]) + currentPoint[0];
+    if (intersects) {
+      inside = !inside;
+    }
+  }
+  return inside;
+}
+function abortedError() {
+  return new GridError({
+    code: "ABORTED",
+    message: "Grid query was aborted."
+  });
+}
+
+exports.GridError = GridError;
+exports.assertValidGridDataSource = assertValidGridDataSource;
+exports.colorScaleDisplayDomain = colorScaleDisplayDomain;
+exports.colorScaleToRendererOptions = colorScaleToRendererOptions;
+exports.convertDisplayValue = convertDisplayValue;
+exports.coordinateSelector = coordinateSelector;
+exports.createDebouncer = createDebouncer;
+exports.createJaxraySource = createJaxraySource;
+exports.findDimension = findDimension;
+exports.findVariable = findVariable;
+exports.indexSelector = indexSelector;
+exports.inferSpatialDimensions = inferSpatialDimensions;
+exports.isGridError = isGridError;
+exports.isNumericDType = isNumericDType;
+exports.isoTimeSelector = isoTimeSelector;
+exports.listTimeCoordinates = listTimeCoordinates;
+exports.normalizeSelectorValue = normalizeSelectorValue;
+exports.normalizeSelectors = normalizeSelectors;
+exports.paletteToRendererColorMap = paletteToRendererColorMap;
+exports.preflightGridRequest = preflightGridRequest;
+exports.queryGrid = queryGrid;
+exports.queryPoint = queryPoint;
+exports.selectorToIndex = selectorToIndex;
+exports.toGridError = toGridError;
+exports.toRendererSelectors = toRendererSelectors;
+exports.validateColorScale = validateColorScale;
+exports.validateGridDataSource = validateGridDataSource;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map