@dclimate/zarr-map 0.1.0

package/dist/renderers/index.js

@@ -0,0 +1,899 @@
+// 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;
+  }
+};
+
+// 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;
+}
+
+// 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 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 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 sameCoordinate(left, right) {
+  const normalizedLeft = left instanceof Date ? left.toISOString() : left;
+  return normalizedLeft === right || String(normalizedLeft) === String(right);
+}
+
+// src/renderers/maplibre.ts
+function createMapLibreGridLayer(options) {
+  return new MapLibreGridLayerController(options);
+}
+function buildZarrLayerOptions(options) {
+  assertValidGridDataSource(options.source, {
+    variable: options.variable,
+    requireRenderable: true
+  });
+  const variable = options.source.variables.find(
+    (candidate) => candidate.name === options.variable || candidate.path === options.variable
+  );
+  if (!variable) {
+    throw new GridError({
+      code: "MISSING_VARIABLE",
+      message: `Variable "${options.variable}" is not present in the grid source.`,
+      variable: options.variable,
+      sourceId: options.source.id
+    });
+  }
+  const spatialDimensions = inferSpatialDimensions(options.source, variable.name);
+  if (!spatialDimensions) {
+    throw new GridError({
+      code: "MISSING_SPATIAL_DIMENSIONS",
+      message: `Variable "${variable.name}" needs spatial dimensions before rendering.`,
+      variable: variable.name,
+      sourceId: options.source.id
+    });
+  }
+  const colorOptions = colorScaleToRendererOptions(options.colorScale);
+  const rendererVariable = variable.path ?? variable.name;
+  const normalizedSelectors = normalizeSelectors(options.source, variable.name, options.selectors);
+  const rendererSelectors = omitSpatialSelectors(normalizedSelectors, spatialDimensions);
+  const yDimension = options.source.dimensions.find(
+    (dimension) => dimension.name === spatialDimensions.y
+  );
+  const shaderOptions = buildColorScaleShaderOptions(options.colorScale, rendererVariable);
+  return {
+    id: options.layerId ?? `zarr-map-${options.source.id ?? variable.name}`,
+    source: options.source.source,
+    store: options.source.store,
+    variable: rendererVariable,
+    selector: toRendererSelectors(rendererSelectors),
+    spatialDimensions: { lon: spatialDimensions.x, lat: spatialDimensions.y },
+    zarrVersion: options.source.zarrVersion,
+    crs: options.source.crs,
+    proj4: options.source.proj4,
+    bounds: options.source.bounds,
+    fillValue: variable.fillValue,
+    colormap: colorOptions?.colormap,
+    clim: colorOptions?.clim,
+    opacity: options.opacity,
+    latIsAscending: yDimension?.ascending,
+    customFrag: shaderOptions?.customFrag,
+    uniforms: shaderOptions?.uniforms,
+    onLoad: () => {
+      options.onLoadingChange?.(false);
+      options.onLoadingStateChange?.(completeLoadingState());
+    },
+    onLoadingStateChange: (state) => {
+      const loadingState = normalizeLoadingState(state);
+      options.onLoadingChange?.(loadingState.loading);
+      options.onLoadingStateChange?.(loadingState);
+    },
+    onError: (error) => options.onError?.(
+      new GridError({
+        code: "CHUNK_LOAD_FAILED",
+        message: "Zarr renderer reported a metadata or chunk loading error.",
+        cause: error,
+        sourceId: options.source.id,
+        variable: options.variable
+      })
+    )
+  };
+}
+function buildColorScaleShaderOptions(colorScale, rendererVariable) {
+  const transparentPalette = transparentPaletteKind(colorScale);
+  if (!transparentPalette || !isValidGlslIdentifier(rendererVariable)) {
+    return void 0;
+  }
+  return {
+    customFrag: transparentPalette === "vegetation" ? vegetationOverlayShader(rendererVariable) : transparentPalette === "magma" ? magmaTransparentLowerBoundShader(rendererVariable) : precipitationOverlayShader(rendererVariable),
+    uniforms: {}
+  };
+}
+function precipitationOverlayShader(rendererVariable) {
+  return `
+  if (${rendererVariable} <= 0.0) {
+    discard;
+  }
+
+  float rescaled = clamp((${rendererVariable} - clim.x) / (clim.y - clim.x), 0.0, 1.0);
+  vec4 c = texture(colormap, vec2(rescaled, 0.5));
+  float precipAlpha = opacity * mix(0.22, 1.0, rescaled);
+  fragColor = vec4(c.rgb, precipAlpha);
+  fragColor.rgb *= fragColor.a;
+`;
+}
+function vegetationOverlayShader(rendererVariable) {
+  return `
+  float vegetationRange = clim.y - clim.x;
+  float noVegetationCutoff = clim.x + vegetationRange * 0.04;
+  if (${rendererVariable} <= noVegetationCutoff) {
+    discard;
+  }
+
+  float rescaled = clamp((${rendererVariable} - clim.x) / vegetationRange, 0.0, 1.0);
+  vec4 c = texture(colormap, vec2(rescaled, 0.5));
+  float vegetationAlpha = opacity * mix(0.14, 1.0, smoothstep(0.04, 0.85, rescaled));
+  fragColor = vec4(c.rgb, vegetationAlpha);
+  fragColor.rgb *= fragColor.a;
+`;
+}
+function magmaTransparentLowerBoundShader(rendererVariable) {
+  return `
+  float rescaled = clamp((${rendererVariable} - clim.x) / (clim.y - clim.x), 0.0, 1.0);
+  vec4 c = texture(colormap, vec2(rescaled, 0.5));
+  float magmaAlpha = opacity * smoothstep(0.0, 0.2, rescaled);
+  fragColor = vec4(c.rgb, magmaAlpha);
+  fragColor.rgb *= fragColor.a;
+`;
+}
+function transparentPaletteKind(colorScale) {
+  if (typeof colorScale?.palette !== "string") {
+    return void 0;
+  }
+  const palette = colorScale.palette.toLowerCase();
+  if (palette === "magma" || palette === "precipitation" || palette === "vegetation") {
+    return palette;
+  }
+  return void 0;
+}
+function isValidGlslIdentifier(value) {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+function colorScaleShaderSignature(options) {
+  const variable = options.source.variables.find(
+    (candidate) => candidate.name === options.variable || candidate.path === options.variable
+  );
+  const rendererVariable = variable?.path ?? variable?.name ?? options.variable;
+  return buildColorScaleShaderOptions(options.colorScale, rendererVariable)?.customFrag ?? "";
+}
+var MapLibreGridLayerController = class {
+  id;
+  ownsMap;
+  options;
+  map;
+  layer;
+  removed = false;
+  constructor(options) {
+    this.id = options.layerId ?? `zarr-map-${options.source.id ?? options.variable}`;
+    this.options = { ...options, layerId: this.id };
+    this.map = options.map;
+    this.ownsMap = !options.map;
+  }
+  async mount() {
+    if (this.layer || this.removed) {
+      return;
+    }
+    this.options.onLoadingChange?.(true);
+    this.options.onLoadingStateChange?.({
+      loading: true,
+      metadata: false,
+      chunks: false,
+      percent: 5,
+      stage: "map"
+    });
+    try {
+      this.map ??= await this.createMap();
+      await this.whenMapReady(this.map);
+      this.options.onLoadingStateChange?.({
+        loading: true,
+        metadata: false,
+        chunks: false,
+        percent: 25,
+        stage: "layer"
+      });
+      this.layer = await (this.options.layerFactory ?? createDefaultZarrLayer)(
+        buildZarrLayerOptions(this.options)
+      );
+      this.map.addLayer(this.layer, this.options.beforeId);
+      this.options.onLoadingStateChange?.({
+        loading: true,
+        metadata: false,
+        chunks: true,
+        percent: 65,
+        stage: "chunks"
+      });
+    } catch (error) {
+      this.options.onLoadingChange?.(false);
+      this.handleError("RENDERER_SETUP_FAILED", "Failed to create the MapLibre Zarr layer.", error);
+    }
+  }
+  async update(update) {
+    const nextOptions = {
+      ...this.options,
+      ...update
+    };
+    if (!this.layer) {
+      this.options = nextOptions;
+      await this.mount();
+      return;
+    }
+    try {
+      if (update.source && update.source !== this.options.source) {
+        await this.replaceLayer(nextOptions);
+        this.options = nextOptions;
+        return;
+      }
+      if (colorScaleShaderSignature(nextOptions) !== colorScaleShaderSignature(this.options)) {
+        await this.replaceLayer(nextOptions);
+        this.options = nextOptions;
+        return;
+      }
+      this.options = nextOptions;
+      if (update.colorScale) {
+        const colorOptions = colorScaleToRendererOptions(update.colorScale);
+        this.layer.setColormap?.(colorOptions?.colormap ?? []);
+        this.layer.setClim?.(colorOptions?.clim ?? update.colorScale.domain);
+      }
+      if (typeof update.opacity === "number") {
+        this.layer.setOpacity?.(update.opacity);
+      }
+      if (update.variable) {
+        this.layer.setVariable?.(update.variable);
+      }
+      if (update.selectors || update.variable || update.source) {
+        const variable = update.variable ?? this.options.variable;
+        const source = update.source ?? this.options.source;
+        const spatialDimensions = inferSpatialDimensions(source, variable);
+        const normalizedSelectors = normalizeSelectors(source, variable, this.options.selectors);
+        const rendererSelectors = spatialDimensions ? omitSpatialSelectors(normalizedSelectors, spatialDimensions) : normalizedSelectors;
+        this.layer.setSelector?.(toRendererSelectors(rendererSelectors));
+      }
+    } catch (error) {
+      this.handleError("RENDERER_SETUP_FAILED", "Failed to update the MapLibre Zarr layer.", error);
+    }
+  }
+  async replaceLayer(nextOptions) {
+    if (!this.map) {
+      this.options = nextOptions;
+      await this.mount();
+      return;
+    }
+    this.options.onLoadingChange?.(true);
+    this.options.onLoadingStateChange?.({
+      loading: true,
+      metadata: false,
+      chunks: false,
+      percent: 5,
+      stage: "layer"
+    });
+    const previousLayer = this.layer;
+    if (previousLayer && this.map.getLayer(previousLayer.id)) {
+      this.map.removeLayer(previousLayer.id);
+    }
+    if (previousLayer?.id && this.map.getSource?.(previousLayer.id)) {
+      this.map.removeSource?.(previousLayer.id);
+    }
+    this.layer = void 0;
+    try {
+      this.options.onLoadingStateChange?.({
+        loading: true,
+        metadata: false,
+        chunks: false,
+        percent: 35,
+        stage: "layer"
+      });
+      const nextLayer = await (nextOptions.layerFactory ?? createDefaultZarrLayer)(
+        buildZarrLayerOptions(nextOptions)
+      );
+      this.layer = nextLayer;
+      this.map.addLayer(nextLayer, nextOptions.beforeId);
+      this.options.onLoadingStateChange?.({
+        loading: true,
+        metadata: false,
+        chunks: true,
+        percent: 65,
+        stage: "chunks"
+      });
+    } catch (error) {
+      this.options.onLoadingChange?.(false);
+      this.handleError("RENDERER_SETUP_FAILED", "Failed to update the MapLibre Zarr layer.", error);
+    }
+  }
+  remove() {
+    if (this.removed) {
+      return;
+    }
+    this.removed = true;
+    if (this.layer && this.map?.getLayer(this.layer.id)) {
+      this.map.removeLayer(this.layer.id);
+    }
+    if (this.layer?.id && this.map?.getSource?.(this.layer.id)) {
+      this.map.removeSource?.(this.layer.id);
+    }
+    if (this.ownsMap) {
+      this.map?.remove?.();
+    }
+    this.layer = void 0;
+    this.map = void 0;
+  }
+  async query(geometry) {
+    if (!this.layer?.queryData) {
+      throw new GridError({
+        code: "UNSUPPORTED_GEOMETRY",
+        message: "The active renderer layer does not expose queryData."
+      });
+    }
+    return this.layer.queryData(geometry);
+  }
+  getMap() {
+    return this.map;
+  }
+  getLayer() {
+    return this.layer;
+  }
+  async createMap() {
+    if (!this.options.mapConfig) {
+      throw new GridError({
+        code: "RENDERER_SETUP_FAILED",
+        message: "Provide either an existing map instance or mapConfig to create one."
+      });
+    }
+    if (this.options.mapFactory) {
+      return this.options.mapFactory(this.options.mapConfig);
+    }
+    const maplibre = await import('maplibre-gl');
+    return new maplibre.Map(
+      this.options.mapConfig
+    );
+  }
+  async whenMapReady(map) {
+    if (this.isStyleReady(map) || !map.once) {
+      return;
+    }
+    if (map.isStyleLoaded) {
+      await new Promise((resolve) => {
+        let resolved = false;
+        const resolveWhenStyleReady = () => {
+          if (resolved) {
+            return;
+          }
+          if (this.isStyleReady(map)) {
+            resolved = true;
+            resolve();
+            return;
+          }
+          map.once?.("styledata", resolveWhenStyleReady);
+        };
+        map.once?.("styledata", resolveWhenStyleReady);
+        map.once?.("load", resolveWhenStyleReady);
+      });
+      return;
+    }
+    if (!map.loaded || map.loaded()) {
+      return;
+    }
+    await new Promise((resolve) => {
+      map.once?.("load", () => resolve());
+    });
+  }
+  isStyleReady(map) {
+    return map.isStyleLoaded?.() ?? map.loaded?.() ?? true;
+  }
+  handleError(code, message, cause) {
+    const gridError = cause instanceof GridError ? cause : new GridError({
+      code,
+      message: errorMessageWithCause(message, cause),
+      cause,
+      sourceId: this.options.source.id,
+      variable: this.options.variable
+    });
+    this.options.onError?.(gridError);
+    throw gridError;
+  }
+};
+function errorMessageWithCause(message, cause) {
+  if (cause instanceof Error && cause.message) {
+    return `${message} ${cause.message}`;
+  }
+  return message;
+}
+function omitSpatialSelectors(selectors, spatialDimensions) {
+  return Object.fromEntries(
+    Object.entries(selectors).filter(([dimensionName]) => {
+      return dimensionName !== spatialDimensions.x && dimensionName !== spatialDimensions.y;
+    })
+  );
+}
+function normalizeLoadingState(state) {
+  if (typeof state === "boolean") {
+    return {
+      loading: state,
+      metadata: state,
+      chunks: false,
+      percent: state ? 35 : 100,
+      stage: state ? "metadata" : "complete"
+    };
+  }
+  const loading = Boolean(state.loading ?? state.metadata ?? state.chunks);
+  const metadata = Boolean(state.metadata);
+  const chunks = Boolean(state.chunks);
+  return {
+    loading,
+    metadata,
+    chunks,
+    stage: state.stage ?? loadingStage(loading, metadata, chunks),
+    percent: typeof state.percent === "number" ? Math.max(0, Math.min(100, state.percent)) : loading ? loadingPercent(metadata, chunks) : 100
+  };
+}
+function loadingStage(loading, metadata, chunks) {
+  if (!loading) {
+    return "complete";
+  }
+  if (chunks) {
+    return "chunks";
+  }
+  if (metadata) {
+    return "metadata";
+  }
+  return "layer";
+}
+function loadingPercent(metadata, chunks) {
+  if (chunks) {
+    return 85;
+  }
+  if (metadata) {
+    return 45;
+  }
+  return 65;
+}
+function completeLoadingState() {
+  return {
+    loading: false,
+    metadata: false,
+    chunks: false,
+    percent: 100,
+    stage: "complete"
+  };
+}
+var zarrLayerConstructorPromise;
+async function preloadDefaultZarrLayer() {
+  await loadDefaultZarrLayerConstructor();
+}
+async function createDefaultZarrLayer(options) {
+  const ZarrLayer = await loadDefaultZarrLayerConstructor();
+  return new ZarrLayer(options);
+}
+async function loadDefaultZarrLayerConstructor() {
+  zarrLayerConstructorPromise ??= import('@carbonplan/zarr-layer').then((module) => {
+    const zarrLayerModule = module;
+    const ZarrLayer = zarrLayerModule.ZarrLayer ?? zarrLayerModule.default;
+    if (!ZarrLayer) {
+      throw new GridError({
+        code: "RENDERER_SETUP_FAILED",
+        message: "@carbonplan/zarr-layer did not export ZarrLayer."
+      });
+    }
+    return ZarrLayer;
+  }).catch((error) => {
+    zarrLayerConstructorPromise = void 0;
+    throw error;
+  });
+  return zarrLayerConstructorPromise;
+}
+
+export { buildZarrLayerOptions, createMapLibreGridLayer, preloadDefaultZarrLayer };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map