rustial_engine/

style_json.rs

//! JSON style-spec parsing and resolution for the style runtime.
//!
//! This module adds a declarative style-document layer closer to MapLibre's
//! `style/style.ts`: JSON source and layer definitions are parsed into a
//! lightweight spec and then resolved through a host-provided runtime source
//! registry into an executable [`StyleDocument`](crate::style::StyleDocument).

use crate::style::{
    BackgroundStyleLayer, CircleStyleLayer, FillExtrusionStyleLayer, FillStyleLayer,
    HeatmapStyleLayer, HillshadeStyleLayer, LightConfig, LineStyleLayer, ModelStyleLayer,
    RasterStyleLayer, SkyConfig, StyleDocument, StyleError, StyleLayer, StyleLayerMeta,
    StyleProjection, StyleSource, StyleSourceId, StyleSourceKind, StyleValue, SymbolStyleLayer,
    VectorStyleLayer,
};
use crate::symbols::{
    SymbolAnchor, SymbolIconTextFit, SymbolPlacement, SymbolTextJustify, SymbolTextTransform,
    SymbolWritingMode,
};
use serde::{Deserialize, Serialize};
use serde_json::{Map, Value};
use std::collections::HashMap;
use std::fmt;

/// Errors produced while parsing or resolving a JSON style specification.
#[derive(Debug)]
pub enum StyleSpecError {
    /// Failed to parse JSON.
    Json(serde_json::Error),
    /// A style source required by the JSON spec has no runtime binding.
    MissingRuntimeSource(String),
    /// The runtime binding for a source does not match the declared source kind.
    RuntimeSourceKindMismatch {
        /// Source id being resolved.
        source_id: String,
        /// Declared spec kind.
        declared: StyleSourceKind,
        /// Actual bound runtime kind.
        actual: StyleSourceKind,
    },
    /// A layer references a source but omits the `source` field.
    MissingLayerSource(String),
    /// A JSON field had the wrong shape.
    InvalidField {
        /// Layer or source id for diagnostics.
        id: String,
        /// Field name.
        field: &'static str,
        /// Human-readable expectation.
        expected: &'static str,
    },
    /// The runtime style document rejected the resolved document.
    Runtime(StyleError),
}

impl fmt::Display for StyleSpecError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            StyleSpecError::Json(err) => write!(f, "style JSON parse error: {err}"),
            StyleSpecError::MissingRuntimeSource(id) => {
                write!(f, "missing runtime source binding for style source `{id}`")
            }
            StyleSpecError::RuntimeSourceKindMismatch {
                source_id,
                declared,
                actual,
            } => write!(
                f,
                "runtime source `{source_id}` kind mismatch: declared `{}`, bound `{}`",
                declared.as_str(),
                actual.as_str()
            ),
            StyleSpecError::MissingLayerSource(id) => {
                write!(f, "style layer `{id}` requires a `source` field")
            }
            StyleSpecError::InvalidField {
                id,
                field,
                expected,
            } => {
                write!(f, "invalid field `{field}` in `{id}`, expected {expected}")
            }
            StyleSpecError::Runtime(err) => err.fmt(f),
        }
    }
}

impl std::error::Error for StyleSpecError {}

impl From<serde_json::Error> for StyleSpecError {
    fn from(value: serde_json::Error) -> Self {
        Self::Json(value)
    }
}

impl From<StyleError> for StyleSpecError {
    fn from(value: StyleError) -> Self {
        Self::Runtime(value)
    }
}

/// Declarative JSON style document.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StyleSpecDocument {
    /// Style-spec version.
    #[serde(default = "default_style_version")]
    pub version: u8,
    /// Optional human-readable style name.
    #[serde(default)]
    pub name: Option<String>,
    /// Declared source definitions.
    #[serde(default)]
    pub sources: HashMap<StyleSourceId, StyleSpecSource>,
    /// Ordered layer definitions.
    #[serde(default)]
    pub layers: Vec<StyleSpecLayer>,
    /// Optional terrain configuration.
    #[serde(default)]
    pub terrain: Option<StyleSpecTerrain>,
    /// Optional top-level projection configuration.
    #[serde(default)]
    pub projection: Option<StyleSpecProjection>,
    /// Optional top-level lights configuration (Mapbox v3 style spec).
    #[serde(default)]
    pub lights: Option<Vec<StyleSpecLight>>,
    /// Optional top-level sky configuration (Mapbox style spec).
    #[serde(default)]
    pub sky: Option<StyleSpecSky>,
    /// Optional global transition timing (Mapbox style spec).
    ///
    /// Applies to all paint properties that do not have a per-layer or
    /// per-property transition override.
    #[serde(default)]
    pub transition: Option<StyleSpecTransition>,
}

/// Transition timing as declared in a JSON style spec.
///
/// Matches Mapbox GL JS `TransitionSpecification`:
/// ```json
/// { "duration": 300, "delay": 0 }
/// ```
///
/// Both values are in **milliseconds** (they are converted to seconds at
/// resolution time).
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
pub struct StyleSpecTransition {
    /// Duration in milliseconds. Default: `300`.
    #[serde(default = "default_transition_duration")]
    pub duration: f32,
    /// Delay in milliseconds. Default: `0`.
    #[serde(default)]
    pub delay: f32,
}

fn default_transition_duration() -> f32 {
    300.0
}

impl StyleSpecTransition {
    /// Convert to the runtime [`TransitionSpec`] (seconds).
    pub fn to_runtime(&self) -> crate::style::TransitionSpec {
        crate::style::TransitionSpec {
            duration: self.duration / 1000.0,
            delay: self.delay / 1000.0,
        }
    }
}

impl StyleSpecDocument {
    /// Parse a JSON style string.
    pub fn from_json(json: &str) -> Result<Self, StyleSpecError> {
        Ok(serde_json::from_str(json)?)
    }

    /// Resolve the declarative style into a runtime [`StyleDocument`].
    pub fn resolve(&self, registry: &StyleSourceRegistry) -> Result<StyleDocument, StyleSpecError> {
        let mut document = StyleDocument::new();

        for (id, source_spec) in &self.sources {
            let runtime = registry
                .source(id)
                .ok_or_else(|| StyleSpecError::MissingRuntimeSource(id.to_string()))?;
            if runtime.kind() != source_spec.source_type.runtime_kind() {
                return Err(StyleSpecError::RuntimeSourceKindMismatch {
                    source_id: id.to_string(),
                    declared: source_spec.source_type.runtime_kind(),
                    actual: runtime.kind(),
                });
            }
            document.add_source(id.clone(), runtime.clone())?;
        }

        if let Some(terrain) = &self.terrain {
            document.set_terrain_source(Some(terrain.source.clone()));
        }

        if let Some(projection) = &self.projection {
            document.set_projection(projection.projection_type.runtime_projection());
        }

        if let Some(lights) = &self.lights {
            document.set_lights(Some(resolve_lights(lights)));
        }

        if let Some(sky) = &self.sky {
            document.set_sky(Some(resolve_sky(sky)));
        }

        if let Some(transition) = &self.transition {
            document.set_transition(transition.to_runtime());
        }

        for layer in &self.layers {
            document.add_layer(layer.to_runtime_layer()?)?;
        }

        Ok(document)
    }
}

/// Runtime source registry used while resolving JSON specs.
#[derive(Debug, Clone, Default)]
pub struct StyleSourceRegistry {
    sources: HashMap<StyleSourceId, StyleSource>,
}

impl StyleSourceRegistry {
    /// Create an empty source registry.
    pub fn new() -> Self {
        Self::default()
    }

    /// Register or replace a runtime source binding.
    pub fn set_source(&mut self, id: impl Into<String>, source: StyleSource) {
        self.sources.insert(id.into(), source);
    }

    /// Look up a bound source.
    pub fn source(&self, id: &str) -> Option<&StyleSource> {
        self.sources.get(id)
    }

    /// Resolve a parsed spec document into a runtime style document.
    pub fn resolve_document(
        &self,
        spec: &StyleSpecDocument,
    ) -> Result<StyleDocument, StyleSpecError> {
        spec.resolve(self)
    }
}

/// Top-level terrain entry in a JSON style spec.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StyleSpecTerrain {
    /// Source id referenced by the terrain configuration.
    pub source: StyleSourceId,
}

/// Top-level projection entry in a JSON style spec.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StyleSpecProjection {
    /// Projection type.
    #[serde(rename = "type")]
    pub projection_type: StyleSpecProjectionType,
}

/// Projection kinds accepted by the current JSON style spec.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum StyleSpecProjectionType {
    /// Web Mercator projection.
    #[serde(rename = "mercator")]
    Mercator,
    /// Equirectangular planar projection.
    #[serde(rename = "equirectangular")]
    Equirectangular,
    /// Globe / geocentric projection.
    #[serde(rename = "globe")]
    Globe,
    /// Near-sided vertical perspective projection.
    #[serde(rename = "vertical-perspective")]
    VerticalPerspective,
}

impl StyleSpecProjectionType {
    fn runtime_projection(self) -> StyleProjection {
        match self {
            StyleSpecProjectionType::Mercator => StyleProjection::Mercator,
            StyleSpecProjectionType::Equirectangular => StyleProjection::Equirectangular,
            StyleSpecProjectionType::Globe => StyleProjection::Globe,
            StyleSpecProjectionType::VerticalPerspective => StyleProjection::VerticalPerspective,
        }
    }
}

// ---------------------------------------------------------------------------
// Lights spec
// ---------------------------------------------------------------------------

/// A single light entry in the style-spec `"lights"` array.
///
/// Follows the Mapbox GL JS v3 convention:
/// ```json
/// "lights": [
///   { "type": "ambient", "properties": { "color": "white", "intensity": 0.5 } },
///   { "type": "directional", "properties": { "direction": [210, 45], "color": "white", "intensity": 0.5 } }
/// ]
/// ```
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StyleSpecLight {
    /// Light type: `"ambient"`, `"directional"`, or `"flat"`.
    #[serde(rename = "type")]
    pub light_type: StyleSpecLightType,
    /// Light properties (optional; missing fields use defaults).
    #[serde(default)]
    pub properties: StyleSpecLightProperties,
}

/// Light type discriminant.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum StyleSpecLightType {
    /// Ambient hemisphere light.
    #[serde(rename = "ambient")]
    Ambient,
    /// Directional / sun light.
    #[serde(rename = "directional")]
    Directional,
    /// Flat / unlit mode.
    #[serde(rename = "flat")]
    Flat,
}

/// Unioned property bag for all light types.
///
/// Fields that do not apply to a given light type are silently ignored.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct StyleSpecLightProperties {
    /// Light colour as a CSS colour string (e.g. `"white"`, `"#ff8800"`).
    ///
    /// Currently only `"white"` and `"#rrggbb"` hex are parsed.
    /// Unrecognised values fall back to white.
    #[serde(default)]
    pub color: Option<String>,
    /// Intensity multiplier.
    #[serde(default)]
    pub intensity: Option<f32>,
    /// `[azimuth_deg, altitude_deg]` for directional lights.
    #[serde(default)]
    pub direction: Option<[f32; 2]>,
    /// Whether the directional light casts shadows.
    #[serde(default, rename = "cast-shadows")]
    pub cast_shadows: Option<bool>,
}

/// Resolve a `"lights"` array from the JSON style spec into a
/// [`LightConfig`].
fn resolve_lights(lights: &[StyleSpecLight]) -> LightConfig {
    use crate::style::{AmbientLight, DirectionalLight, LightingMode};

    let mut config = LightConfig::default();

    for light in lights {
        let color = light
            .properties
            .color
            .as_deref()
            .map(parse_light_color)
            .unwrap_or([1.0, 1.0, 1.0]);

        match light.light_type {
            StyleSpecLightType::Ambient => {
                config.ambient = AmbientLight {
                    color,
                    intensity: light.properties.intensity.unwrap_or(0.5),
                };
            }
            StyleSpecLightType::Directional => {
                config.directional = DirectionalLight {
                    direction: light.properties.direction.unwrap_or([210.0, 45.0]),
                    color,
                    intensity: light.properties.intensity.unwrap_or(0.5),
                    cast_shadows: light.properties.cast_shadows.unwrap_or(false),
                };
            }
            StyleSpecLightType::Flat => {
                config.mode = LightingMode::Flat;
            }
        }
    }

    config
}

/// Parse a CSS-style colour string into linear RGB [0, 1].
///
/// Supports `"white"`, `"black"`, and `"#rrggbb"` hex notation.
/// Unknown values fall back to white.
fn parse_light_color(s: &str) -> [f32; 3] {
    match s.trim().to_lowercase().as_str() {
        "white" => [1.0, 1.0, 1.0],
        "black" => [0.0, 0.0, 0.0],
        hex if hex.starts_with('#') && hex.len() == 7 => {
            let r = u8::from_str_radix(&hex[1..3], 16).unwrap_or(255);
            let g = u8::from_str_radix(&hex[3..5], 16).unwrap_or(255);
            let b = u8::from_str_radix(&hex[5..7], 16).unwrap_or(255);
            // sRGB → linear (approximate).
            [
                (r as f32 / 255.0).powf(2.2),
                (g as f32 / 255.0).powf(2.2),
                (b as f32 / 255.0).powf(2.2),
            ]
        }
        _ => [1.0, 1.0, 1.0],
    }
}

// ---------------------------------------------------------------------------
// Sky spec
// ---------------------------------------------------------------------------

/// Top-level `"sky"` configuration in the style-spec.
///
/// Follows the Mapbox GL JS v3 convention:
/// ```json
/// "sky": {
///   "sky-type": "atmosphere",
///   "sky-atmosphere-sun": [210, 45],
///   "sky-atmosphere-sun-intensity": 10,
///   "sky-atmosphere-color": "white",
///   "sky-atmosphere-halo-color": "white",
///   "sky-opacity": 1.0
/// }
/// ```
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct StyleSpecSky {
    /// `"atmosphere"` or `"gradient"`.  Default: `"atmosphere"`.
    #[serde(default, rename = "sky-type")]
    pub sky_type: Option<String>,
    /// Sun position as `[azimuth_deg, altitude_deg]`.
    #[serde(default, rename = "sky-atmosphere-sun")]
    pub sun_position: Option<[f32; 2]>,
    /// Sun brightness multiplier (0–100).
    #[serde(default, rename = "sky-atmosphere-sun-intensity")]
    pub sun_intensity: Option<f32>,
    /// Tint for Rayleigh scattering (CSS colour string).
    #[serde(default, rename = "sky-atmosphere-color")]
    pub atmosphere_color: Option<String>,
    /// Tint for Mie scattering / halo (CSS colour string).
    #[serde(default, rename = "sky-atmosphere-halo-color")]
    pub halo_color: Option<String>,
    /// Overall sky opacity (0–1).
    #[serde(default, rename = "sky-opacity")]
    pub opacity: Option<f32>,
}

/// Resolve a `"sky"` JSON object into a [`SkyConfig`].
fn resolve_sky(spec: &StyleSpecSky) -> SkyConfig {
    use crate::style::{SkyConfig, SkyType};

    let sky_type = match spec.sky_type.as_deref() {
        Some("gradient") => SkyType::Gradient,
        _ => SkyType::Atmosphere,
    };

    SkyConfig {
        sky_type,
        sun_position: spec.sun_position,
        sun_intensity: spec.sun_intensity.unwrap_or(10.0),
        atmosphere_color: spec
            .atmosphere_color
            .as_deref()
            .map(parse_light_color)
            .unwrap_or([1.0, 1.0, 1.0]),
        halo_color: spec
            .halo_color
            .as_deref()
            .map(parse_light_color)
            .unwrap_or([1.0, 1.0, 1.0]),
        opacity: spec.opacity.unwrap_or(1.0),
    }
}

/// Source kinds accepted by the JSON style spec.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum StyleSpecSourceType {
    /// Raster tile source.
    #[serde(rename = "raster")]
    Raster,
    /// Raster DEM / terrain source.
    #[serde(rename = "raster-dem")]
    RasterDem,
    /// GeoJSON source.
    #[serde(rename = "geojson")]
    GeoJson,
    /// Vector-tile-like source.
    #[serde(rename = "vector")]
    Vector,
    /// Image source.
    #[serde(rename = "image")]
    Image,
    /// Video source.
    #[serde(rename = "video")]
    Video,
    /// Canvas source.
    #[serde(rename = "canvas")]
    Canvas,
    /// Model source.
    #[serde(rename = "model")]
    Model,
}

impl StyleSpecSourceType {
    fn runtime_kind(self) -> StyleSourceKind {
        match self {
            StyleSpecSourceType::Raster => StyleSourceKind::Raster,
            StyleSpecSourceType::RasterDem => StyleSourceKind::Terrain,
            StyleSpecSourceType::GeoJson => StyleSourceKind::GeoJson,
            StyleSpecSourceType::Vector => StyleSourceKind::VectorTile,
            StyleSpecSourceType::Image => StyleSourceKind::Image,
            StyleSpecSourceType::Video => StyleSourceKind::Video,
            StyleSpecSourceType::Canvas => StyleSourceKind::Canvas,
            StyleSpecSourceType::Model => StyleSourceKind::Model,
        }
    }
}

/// Declarative source entry.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StyleSpecSource {
    /// Source type.
    #[serde(rename = "type")]
    pub source_type: StyleSpecSourceType,
    /// Optional URL.
    #[serde(default)]
    pub url: Option<String>,
    /// Optional tile URL templates.
    #[serde(default)]
    pub tiles: Vec<String>,
    /// Optional arbitrary metadata.
    #[serde(default)]
    pub metadata: HashMap<String, Value>,
}

/// Layer kinds accepted by the JSON style spec.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum StyleSpecLayerType {
    #[serde(rename = "background")]
    /// Background style layer entry.
    Background,
    #[serde(rename = "hillshade")]
    /// Hillshade style layer entry.
    Hillshade,
    #[serde(rename = "raster")]
    /// Raster style layer entry.
    Raster,
    #[serde(rename = "vector")]
    /// Generic vector style layer entry.
    Vector,
    #[serde(rename = "fill")]
    /// Fill style layer entry.
    Fill,
    #[serde(rename = "line")]
    /// Line style layer entry.
    Line,
    #[serde(rename = "circle")]
    /// Circle style layer entry.
    Circle,
    #[serde(rename = "heatmap")]
    /// Heatmap style layer entry.
    Heatmap,
    #[serde(rename = "fill-extrusion")]
    /// Fill-extrusion style layer entry.
    FillExtrusion,
    #[serde(rename = "symbol")]
    /// Symbol style layer entry.
    Symbol,
    #[serde(rename = "model")]
    /// Model style layer entry.
    Model,
}

/// Declarative layer entry.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StyleSpecLayer {
    /// Style layer id.
    pub id: String,
    /// Layer type.
    #[serde(rename = "type")]
    pub layer_type: StyleSpecLayerType,
    /// Optional source id.
    #[serde(default)]
    pub source: Option<StyleSourceId>,
    /// Optional source-layer id for vector-tile-like sources.
    #[serde(default, rename = "source-layer")]
    pub source_layer: Option<String>,
    /// Optional minimum zoom.
    #[serde(default)]
    pub minzoom: Option<f32>,
    /// Optional maximum zoom.
    #[serde(default)]
    pub maxzoom: Option<f32>,
    /// Layout properties.
    #[serde(default)]
    pub layout: Map<String, Value>,
    /// Paint properties.
    #[serde(default)]
    pub paint: Map<String, Value>,
}

impl StyleSpecLayer {
    fn to_runtime_layer(&self) -> Result<StyleLayer, StyleSpecError> {
        let meta = self.meta()?;
        let layer = match self.layer_type {
            StyleSpecLayerType::Background => {
                let mut layer = BackgroundStyleLayer::new(
                    self.id.clone(),
                    paint_color(&self.paint, "background-color")?
                        .unwrap_or_else(|| [0.0, 0.0, 0.0, 1.0].into()),
                );
                layer.meta = meta;
                StyleLayer::Background(layer)
            }
            StyleSpecLayerType::Hillshade => {
                let mut layer = HillshadeStyleLayer::new(self.id.clone());
                layer.meta = meta;
                if let Some(value) = paint_color(&self.paint, "hillshade-highlight-color")? {
                    layer.highlight_color = value;
                }
                if let Some(value) = paint_color(&self.paint, "hillshade-shadow-color")? {
                    layer.shadow_color = value;
                }
                if let Some(value) = paint_color(&self.paint, "hillshade-accent-color")? {
                    layer.accent_color = value;
                }
                if let Some(value) = paint_f32(&self.paint, "hillshade-illumination-direction")? {
                    layer.illumination_direction_deg = value;
                }
                if let Some(value) = paint_f32(&self.paint, "hillshade-illumination-altitude")? {
                    layer.illumination_altitude_deg = value;
                }
                if let Some(value) = paint_f32(&self.paint, "hillshade-exaggeration")? {
                    layer.exaggeration = value;
                }
                StyleLayer::Hillshade(layer)
            }
            StyleSpecLayerType::Raster => {
                let source = self.required_source()?;
                let mut layer = RasterStyleLayer::new(self.id.clone(), source);
                layer.meta = meta;
                StyleLayer::Raster(layer)
            }
            StyleSpecLayerType::Vector => {
                let source = self.required_source()?;
                let mut layer = VectorStyleLayer::new(self.id.clone(), source);
                layer.meta = meta;
                layer.source_layer = self.source_layer.clone();
                if let Some(value) = paint_color(&self.paint, "fill-color")? {
                    layer.fill_color = value;
                }
                if let Some(value) = paint_color(&self.paint, "line-color")? {
                    layer.stroke_color = value;
                }
                if let Some(value) = paint_f32(&self.paint, "line-width")? {
                    layer.stroke_width = value;
                }
                StyleLayer::Vector(layer)
            }
            StyleSpecLayerType::Fill => {
                let source = self.required_source()?;
                let mut layer = FillStyleLayer::new(self.id.clone(), source);
                layer.meta = meta;
                layer.source_layer = self.source_layer.clone();
                if let Some(value) = paint_color(&self.paint, "fill-color")? {
                    layer.fill_color = value;
                }
                if let Some(value) = paint_color(&self.paint, "fill-outline-color")? {
                    layer.outline_color = value;
                }
                if let Some(value) = paint_f32(&self.paint, "fill-outline-width")? {
                    layer.outline_width = value;
                }
                StyleLayer::Fill(layer)
            }
            StyleSpecLayerType::Line => {
                let source = self.required_source()?;
                let mut layer = LineStyleLayer::new(self.id.clone(), source);
                layer.meta = meta;
                layer.source_layer = self.source_layer.clone();
                if let Some(value) = paint_color(&self.paint, "line-color")? {
                    layer.color = value;
                }
                if let Some(value) = paint_f32(&self.paint, "line-width")? {
                    layer.width = value;
                }
                StyleLayer::Line(layer)
            }
            StyleSpecLayerType::Circle => {
                let source = self.required_source()?;
                let mut layer = CircleStyleLayer::new(self.id.clone(), source);
                layer.meta = meta;
                layer.source_layer = self.source_layer.clone();
                if let Some(value) = paint_color(&self.paint, "circle-color")? {
                    layer.color = value;
                }
                if let Some(value) = paint_f32(&self.paint, "circle-radius")? {
                    layer.radius = value;
                }
                if let Some(value) = paint_color(&self.paint, "circle-stroke-color")? {
                    layer.stroke_color = value;
                }
                if let Some(value) = paint_f32(&self.paint, "circle-stroke-width")? {
                    layer.stroke_width = value;
                }
                StyleLayer::Circle(layer)
            }
            StyleSpecLayerType::Heatmap => {
                let source = self.required_source()?;
                let mut layer = HeatmapStyleLayer::new(self.id.clone(), source);
                layer.meta = meta;
                layer.source_layer = self.source_layer.clone();
                if let Some(value) = paint_color(&self.paint, "heatmap-color")? {
                    layer.color = value;
                }
                if let Some(value) = paint_f32(&self.paint, "heatmap-radius")? {
                    layer.radius = value;
                }
                if let Some(value) = paint_f32(&self.paint, "heatmap-intensity")? {
                    layer.intensity = value;
                }
                StyleLayer::Heatmap(layer)
            }
            StyleSpecLayerType::FillExtrusion => {
                let source = self.required_source()?;
                let mut layer = FillExtrusionStyleLayer::new(self.id.clone(), source);
                layer.meta = meta;
                layer.source_layer = self.source_layer.clone();
                if let Some(value) = paint_color(&self.paint, "fill-extrusion-color")? {
                    layer.color = value;
                }
                if let Some(value) = paint_f32(&self.paint, "fill-extrusion-base")? {
                    layer.base = value;
                }
                if let Some(value) = paint_f32(&self.paint, "fill-extrusion-height")? {
                    layer.height = value;
                }
                StyleLayer::FillExtrusion(layer)
            }
            StyleSpecLayerType::Symbol => {
                let source = self.required_source()?;
                let mut layer = SymbolStyleLayer::new(self.id.clone(), source);
                layer.meta = meta;
                layer.source_layer = self.source_layer.clone();
                if let Some(value) = paint_color(&self.paint, "text-color")?
                    .or_else(|| paint_color(&self.paint, "icon-color").ok().flatten())
                {
                    layer.color = value;
                }
                if let Some(value) = paint_color(&self.paint, "text-halo-color")? {
                    layer.halo_color = value;
                }
                if let Some(value) = paint_f32(&self.layout, "text-size")?
                    .or_else(|| paint_f32(&self.layout, "icon-size").ok().flatten())
                {
                    layer.size = value;
                }
                if let Some(value) = string_value(self.layout.get("text-field"))? {
                    layer.text_field = Some(value);
                }
                if let Some(value) = string_value(self.layout.get("icon-image"))? {
                    layer.icon_image = Some(value);
                }
                if let Some(value) = string_value(self.layout.get("text-font"))
                    .or_else(|_| first_string_from_array(self.layout.get("text-font")))?
                {
                    layer.font_stack = value;
                }
                if let Some(value) = paint_f32(&self.layout, "text-padding")? {
                    layer.padding = value;
                }
                if let Some(value) = bool_value(self.layout.get("text-allow-overlap"))? {
                    layer.text_allow_overlap = Some(value);
                }
                if let Some(value) = bool_value(self.layout.get("icon-allow-overlap"))? {
                    layer.icon_allow_overlap = Some(value);
                }
                if let Some(value) = bool_value(self.layout.get("text-optional"))? {
                    layer.text_optional = Some(value);
                }
                if let Some(value) = bool_value(self.layout.get("icon-optional"))? {
                    layer.icon_optional = Some(value);
                }
                if let Some(value) = bool_value(self.layout.get("text-ignore-placement"))? {
                    layer.text_ignore_placement = Some(value);
                }
                if let Some(value) = bool_value(self.layout.get("icon-ignore-placement"))? {
                    layer.icon_ignore_placement = Some(value);
                }
                if let Some(value) = paint_f32(&self.layout, "text-radial-offset")? {
                    layer.radial_offset = Some(value);
                }
                if let Some(value) =
                    symbol_anchor_offset_array(self.layout.get("text-variable-anchor-offset"))?
                {
                    layer.variable_anchor_offsets = Some(value);
                }
                if let Some(value) = symbol_anchor(self.layout.get("text-anchor"))? {
                    layer.anchor = value;
                }
                if let Some(value) = symbol_text_justify(self.layout.get("text-justify"))? {
                    layer.justify = value;
                }
                if let Some(value) = symbol_text_transform(self.layout.get("text-transform"))? {
                    layer.transform = value;
                }
                if let Some(value) = paint_f32(&self.layout, "text-max-width")? {
                    layer.max_width = Some(value);
                }
                if let Some(value) = paint_f32(&self.layout, "text-line-height")? {
                    layer.line_height = Some(value);
                }
                if let Some(value) = paint_f32(&self.layout, "text-letter-spacing")? {
                    layer.letter_spacing = Some(value);
                }
                if let Some(value) = symbol_icon_text_fit(self.layout.get("icon-text-fit"))? {
                    layer.icon_text_fit = value;
                }
                if let Some(value) = vec4_value(
                    self.layout.get("icon-text-fit-padding"),
                    "icon-text-fit-padding",
                )? {
                    layer.icon_text_fit_padding = value;
                }
                if let Some(value) = paint_f32(&self.layout, "symbol-sort-key")? {
                    layer.sort_key = Some(value);
                }
                if let Some(value) = symbol_placement(self.layout.get("symbol-placement"))? {
                    layer.placement = value;
                }
                if let Some(value) = paint_f32(&self.layout, "symbol-spacing")? {
                    layer.spacing = value;
                }
                if let Some(value) = paint_f32(&self.layout, "text-max-angle")? {
                    layer.max_angle = value;
                }
                if let Some(value) = bool_value(self.layout.get("text-keep-upright"))? {
                    layer.keep_upright = value;
                }
                if let Some(value) = symbol_anchor_array(self.layout.get("text-variable-anchor"))? {
                    layer.variable_anchors = value;
                }
                if let Some(value) = symbol_writing_mode(self.layout.get("text-writing-mode"))? {
                    layer.writing_mode = value;
                }
                if let Some(value) = vec2_value(self.layout.get("text-offset"))? {
                    layer.offset = value;
                }
                StyleLayer::Symbol(layer)
            }
            StyleSpecLayerType::Model => {
                let source = self.required_source()?;
                let mut layer = ModelStyleLayer::new(self.id.clone(), source);
                layer.meta = meta;
                StyleLayer::Model(layer)
            }
        };
        Ok(layer)
    }

    fn meta(&self) -> Result<StyleLayerMeta, StyleSpecError> {
        let mut meta = StyleLayerMeta::new(self.id.clone());
        meta.min_zoom = self.minzoom;
        meta.max_zoom = self.maxzoom;

        if let Some(value) = self.opacity_value()? {
            meta.opacity = value;
        }

        if let Some(visibility) = self.layout.get("visibility") {
            let visible = match visibility.as_str() {
                Some("visible") | None => true,
                Some("none") => false,
                Some(_) => {
                    return Err(StyleSpecError::InvalidField {
                        id: self.id.clone(),
                        field: "layout.visibility",
                        expected: "`visible` or `none`",
                    })
                }
            };
            meta.visible = visible.into();
        }

        Ok(meta)
    }

    fn opacity_value(&self) -> Result<Option<StyleValue<f32>>, StyleSpecError> {
        let keys = match self.layer_type {
            StyleSpecLayerType::Background => &["background-opacity"][..],
            StyleSpecLayerType::Hillshade => &["hillshade-opacity"],
            StyleSpecLayerType::Raster => &["raster-opacity"],
            StyleSpecLayerType::Vector => &["opacity"],
            StyleSpecLayerType::Fill => &["fill-opacity"],
            StyleSpecLayerType::Line => &["line-opacity"],
            StyleSpecLayerType::Circle => &["circle-opacity"],
            StyleSpecLayerType::Heatmap => &["heatmap-opacity"],
            StyleSpecLayerType::FillExtrusion => &["fill-extrusion-opacity"],
            StyleSpecLayerType::Symbol => &["text-opacity", "icon-opacity"],
            StyleSpecLayerType::Model => &["model-opacity"],
        };

        for key in keys {
            if let Some(value) = self.paint.get(*key) {
                return Ok(Some(f32_value_from_json(&self.id, key, value)?));
            }
        }
        Ok(None)
    }

    fn required_source(&self) -> Result<String, StyleSpecError> {
        self.source
            .clone()
            .ok_or_else(|| StyleSpecError::MissingLayerSource(self.id.clone()))
    }
}

/// Parse a JSON style string.
pub fn parse_style_json(json: &str) -> Result<StyleSpecDocument, StyleSpecError> {
    StyleSpecDocument::from_json(json)
}

fn paint_color(
    map: &Map<String, Value>,
    key: &'static str,
) -> Result<Option<StyleValue<[f32; 4]>>, StyleSpecError> {
    map.get(key)
        .map(|value| color_value_from_json(key, key, value))
        .transpose()
}

fn paint_f32(
    map: &Map<String, Value>,
    key: &'static str,
) -> Result<Option<StyleValue<f32>>, StyleSpecError> {
    map.get(key)
        .map(|value| f32_value_from_json(key, key, value))
        .transpose()
}

fn string_value(value: Option<&Value>) -> Result<Option<StyleValue<String>>, StyleSpecError> {
    value
        .map(|value| string_value_from_json("symbol", "text-field", value))
        .transpose()
}

fn bool_value(value: Option<&Value>) -> Result<Option<StyleValue<bool>>, StyleSpecError> {
    value
        .map(|value| bool_value_from_json("symbol", "allow-overlap", value))
        .transpose()
}

fn first_string_from_array(
    value: Option<&Value>,
) -> Result<Option<StyleValue<String>>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    let Some(array) = value.as_array() else {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-font",
            expected: "string or string array",
        });
    };
    let Some(first) = array.first() else {
        return Ok(None);
    };
    Ok(Some(string_value_from_json("symbol", "text-font", first)?))
}

fn vec2_value(value: Option<&Value>) -> Result<Option<[f32; 2]>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    let Some(array) = value.as_array() else {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-offset",
            expected: "two-element numeric array",
        });
    };
    if array.len() != 2 {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-offset",
            expected: "two-element numeric array",
        });
    }
    Ok(Some([
        array[0]
            .as_f64()
            .ok_or_else(|| StyleSpecError::InvalidField {
                id: "symbol".into(),
                field: "text-offset",
                expected: "two-element numeric array",
            })? as f32,
        array[1]
            .as_f64()
            .ok_or_else(|| StyleSpecError::InvalidField {
                id: "symbol".into(),
                field: "text-offset",
                expected: "two-element numeric array",
            })? as f32,
    ]))
}

fn symbol_anchor_array(value: Option<&Value>) -> Result<Option<Vec<SymbolAnchor>>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    let Some(array) = value.as_array() else {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-variable-anchor",
            expected: "string array",
        });
    };
    let mut anchors = Vec::with_capacity(array.len());
    for value in array {
        let Some(text) = value.as_str() else {
            return Err(StyleSpecError::InvalidField {
                id: "symbol".into(),
                field: "text-variable-anchor",
                expected: "string array",
            });
        };
        anchors.push(parse_symbol_anchor(text)?);
    }
    Ok(Some(anchors))
}

#[allow(clippy::type_complexity)]
fn symbol_anchor_offset_array(
    value: Option<&Value>,
) -> Result<Option<Vec<(SymbolAnchor, [f32; 2])>>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    let Some(array) = value.as_array() else {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-variable-anchor-offset",
            expected: "alternating anchor / [x, y] array",
        });
    };
    if array.len() % 2 != 0 {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-variable-anchor-offset",
            expected: "alternating anchor / [x, y] array",
        });
    }

    let mut parsed = Vec::with_capacity(array.len() / 2);
    for pair in array.chunks_exact(2) {
        let anchor_text = pair[0]
            .as_str()
            .ok_or_else(|| StyleSpecError::InvalidField {
                id: "symbol".into(),
                field: "text-variable-anchor-offset",
                expected: "anchor string in alternating anchor / [x, y] array",
            })?;
        let anchor = parse_symbol_anchor(anchor_text)?;
        let offset = parse_vec2_array(
            "symbol",
            "text-variable-anchor-offset",
            pair[1]
                .as_array()
                .ok_or_else(|| StyleSpecError::InvalidField {
                    id: "symbol".into(),
                    field: "text-variable-anchor-offset",
                    expected: "[x, y] offset array in alternating anchor / [x, y] array",
                })?,
        )?;
        parsed.push((anchor, offset));
    }

    Ok(Some(parsed))
}

fn symbol_writing_mode(value: Option<&Value>) -> Result<Option<SymbolWritingMode>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    let Some(text) = value.as_str() else {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-writing-mode",
            expected: "string value",
        });
    };
    Ok(Some(parse_symbol_writing_mode(text)?))
}

fn symbol_placement(value: Option<&Value>) -> Result<Option<SymbolPlacement>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    let Some(text) = value.as_str() else {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "symbol-placement",
            expected: "string value",
        });
    };
    Ok(Some(parse_symbol_placement(text)?))
}

fn symbol_anchor(value: Option<&Value>) -> Result<Option<SymbolAnchor>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    let Some(text) = value.as_str() else {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-anchor",
            expected: "string value",
        });
    };
    Ok(Some(parse_symbol_anchor(text)?))
}

fn symbol_text_justify(
    value: Option<&Value>,
) -> Result<Option<StyleValue<SymbolTextJustify>>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    Ok(Some(match value {
        Value::String(text) => StyleValue::Constant(parse_symbol_text_justify(text)?),
        Value::Object(object) => {
            parse_zoom_stops("symbol", "text-justify", object, |id, field, value| {
                let text = value.as_str().ok_or_else(|| StyleSpecError::InvalidField {
                    id: id.to_owned(),
                    field,
                    expected: "string value",
                })?;
                parse_symbol_text_justify(text)
            })?
        }

        _ => {
            return Err(StyleSpecError::InvalidField {
                id: "symbol".into(),
                field: "text-justify",
                expected: "string value or `{ stops: ... }`",
            })
        }
    }))
}

fn symbol_icon_text_fit(
    value: Option<&Value>,
) -> Result<Option<StyleValue<SymbolIconTextFit>>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    Ok(Some(match value {
        Value::String(text) => StyleValue::Constant(parse_symbol_icon_text_fit(text)?),
        Value::Object(object) => {
            parse_zoom_stops("symbol", "icon-text-fit", object, |id, field, value| {
                let text = value.as_str().ok_or_else(|| StyleSpecError::InvalidField {
                    id: id.to_owned(),
                    field,
                    expected: "string value",
                })?;
                parse_symbol_icon_text_fit(text)
            })?
        }
        _ => {
            return Err(StyleSpecError::InvalidField {
                id: "symbol".into(),
                field: "icon-text-fit",
                expected: "string value or `{ stops: ... }`",
            })
        }
    }))
}

fn symbol_text_transform(
    value: Option<&Value>,
) -> Result<Option<StyleValue<SymbolTextTransform>>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    Ok(Some(match value {
        Value::String(text) => StyleValue::Constant(parse_symbol_text_transform(text)?),
        Value::Object(object) => {
            parse_zoom_stops("symbol", "text-transform", object, |id, field, value| {
                let text = value.as_str().ok_or_else(|| StyleSpecError::InvalidField {
                    id: id.to_owned(),
                    field,
                    expected: "string value",
                })?;
                parse_symbol_text_transform(text)
            })?
        }
        _ => {
            return Err(StyleSpecError::InvalidField {
                id: "symbol".into(),
                field: "text-transform",
                expected: "string value or `{ stops: ... }`",
            })
        }
    }))
}

fn parse_symbol_anchor(text: &str) -> Result<SymbolAnchor, StyleSpecError> {
    match text {
        "center" => Ok(SymbolAnchor::Center),
        "top" => Ok(SymbolAnchor::Top),
        "bottom" => Ok(SymbolAnchor::Bottom),
        "left" => Ok(SymbolAnchor::Left),
        "right" => Ok(SymbolAnchor::Right),
        "top-left" => Ok(SymbolAnchor::TopLeft),
        "top-right" => Ok(SymbolAnchor::TopRight),
        "bottom-left" => Ok(SymbolAnchor::BottomLeft),
        "bottom-right" => Ok(SymbolAnchor::BottomRight),
        _ => Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-variable-anchor",
            expected: "known symbol-anchor string",
        }),
    }
}

fn parse_symbol_icon_text_fit(text: &str) -> Result<SymbolIconTextFit, StyleSpecError> {
    match text {
        "none" => Ok(SymbolIconTextFit::None),
        "width" => Ok(SymbolIconTextFit::Width),
        "height" => Ok(SymbolIconTextFit::Height),
        "both" => Ok(SymbolIconTextFit::Both),
        _ => Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "icon-text-fit",
            expected: "`none`, `width`, `height`, or `both`",
        }),
    }
}

fn parse_symbol_text_transform(text: &str) -> Result<SymbolTextTransform, StyleSpecError> {
    match text {
        "none" => Ok(SymbolTextTransform::None),
        "uppercase" => Ok(SymbolTextTransform::Uppercase),
        "lowercase" => Ok(SymbolTextTransform::Lowercase),
        _ => Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-transform",
            expected: "`none`, `uppercase`, or `lowercase`",
        }),
    }
}

fn parse_symbol_text_justify(text: &str) -> Result<SymbolTextJustify, StyleSpecError> {
    match text {
        "auto" => Ok(SymbolTextJustify::Auto),
        "left" => Ok(SymbolTextJustify::Left),
        "center" => Ok(SymbolTextJustify::Center),
        "right" => Ok(SymbolTextJustify::Right),
        _ => Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-justify",
            expected: "`auto`, `left`, `center`, or `right`",
        }),
    }
}

fn parse_symbol_placement(text: &str) -> Result<SymbolPlacement, StyleSpecError> {
    match text {
        "point" => Ok(SymbolPlacement::Point),
        "line" => Ok(SymbolPlacement::Line),
        _ => Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "symbol-placement",
            expected: "`point` or `line`",
        }),
    }
}

fn parse_symbol_writing_mode(text: &str) -> Result<SymbolWritingMode, StyleSpecError> {
    match text {
        "horizontal" => Ok(SymbolWritingMode::Horizontal),
        "vertical" => Ok(SymbolWritingMode::Vertical),
        _ => Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field: "text-writing-mode",
            expected: "`horizontal` or `vertical`",
        }),
    }
}

fn bool_value_from_json(
    id: &str,
    field: &'static str,
    value: &Value,
) -> Result<StyleValue<bool>, StyleSpecError> {
    match value {
        Value::Bool(value) => Ok(StyleValue::Constant(*value)),
        Value::Object(object) => parse_zoom_stops(id, field, object, parse_bool_constant),
        Value::Array(arr) if is_expression_array(arr) => parse_expression_bool(id, field, arr),
        _ => Err(StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "boolean value, `{ stops: ... }`, or expression array",
        }),
    }
}

fn f32_value_from_json(
    id: &str,
    field: &'static str,
    value: &Value,
) -> Result<StyleValue<f32>, StyleSpecError> {
    match value {
        Value::Number(number) => {
            Ok(StyleValue::Constant(
                number
                    .as_f64()
                    .ok_or_else(|| StyleSpecError::InvalidField {
                        id: id.to_owned(),
                        field,
                        expected: "numeric value",
                    })? as f32,
            ))
        }
        Value::Object(object) => parse_zoom_stops(id, field, object, parse_f32_constant),
        Value::Array(arr) if is_expression_array(arr) => parse_expression_f32(id, field, arr),
        _ => Err(StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "numeric value, `{ stops: ... }`, or expression array",
        }),
    }
}

fn string_value_from_json(
    id: &str,
    field: &'static str,
    value: &Value,
) -> Result<StyleValue<String>, StyleSpecError> {
    match value {
        Value::String(text) => Ok(StyleValue::Constant(text.clone())),
        Value::Object(object) => parse_zoom_stops(id, field, object, parse_string_constant),
        Value::Array(arr) if is_expression_array(arr) => parse_expression_string(id, field, arr),
        _ => Err(StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "string value, `{ stops: ... }`, or expression array",
        }),
    }
}

fn color_value_from_json(
    id: &str,
    field: &'static str,
    value: &Value,
) -> Result<StyleValue<[f32; 4]>, StyleSpecError> {
    match value {
        Value::String(text) => Ok(StyleValue::Constant(parse_color_string(id, field, text)?)),
        Value::Array(array) if is_expression_array(array) => {
            parse_expression_color(id, field, array)
        }
        Value::Array(array) => Ok(StyleValue::Constant(parse_color_array(id, field, array)?)),
        Value::Object(object) => {
            parse_zoom_stops(id, field, object, |id, field, value| match value {
                Value::String(text) => parse_color_string(id, field, text),
                Value::Array(array) => parse_color_array(id, field, array),
                _ => Err(StyleSpecError::InvalidField {
                    id: id.to_owned(),
                    field,
                    expected: "color string or RGBA array",
                }),
            })
        }
        _ => Err(StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "color string, RGBA array, or `{ stops: ... }`",
        }),
    }
}

fn parse_zoom_stops<T>(
    id: &str,
    field: &'static str,
    object: &Map<String, Value>,
    parse_value: impl Fn(&str, &'static str, &Value) -> Result<T, StyleSpecError>,
) -> Result<StyleValue<T>, StyleSpecError> {
    let Some(stops) = object.get("stops").and_then(Value::as_array) else {
        return Err(StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "object with `stops` array",
        });
    };

    let mut parsed = Vec::with_capacity(stops.len());
    for stop in stops {
        let pair = stop
            .as_array()
            .ok_or_else(|| StyleSpecError::InvalidField {
                id: id.to_owned(),
                field,
                expected: "stop tuple `[zoom, value]`",
            })?;
        if pair.len() != 2 {
            return Err(StyleSpecError::InvalidField {
                id: id.to_owned(),
                field,
                expected: "stop tuple `[zoom, value]`",
            });
        }
        let zoom = pair[0]
            .as_f64()
            .ok_or_else(|| StyleSpecError::InvalidField {
                id: id.to_owned(),
                field,
                expected: "numeric stop zoom",
            })? as f32;
        let value = parse_value(id, field, &pair[1])?;
        parsed.push((zoom, value));
    }
    Ok(StyleValue::ZoomStops(parsed))
}

fn parse_f32_constant(id: &str, field: &'static str, value: &Value) -> Result<f32, StyleSpecError> {
    value
        .as_f64()
        .map(|v| v as f32)
        .ok_or_else(|| StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "numeric value",
        })
}

fn parse_string_constant(
    id: &str,
    field: &'static str,
    value: &Value,
) -> Result<String, StyleSpecError> {
    value
        .as_str()
        .map(ToOwned::to_owned)
        .ok_or_else(|| StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "string value",
        })
}

fn parse_bool_constant(
    id: &str,
    field: &'static str,
    value: &Value,
) -> Result<bool, StyleSpecError> {
    value.as_bool().ok_or_else(|| StyleSpecError::InvalidField {
        id: id.to_owned(),
        field,
        expected: "boolean value",
    })
}

fn vec4_value(
    value: Option<&Value>,
    field: &'static str,
) -> Result<Option<[f32; 4]>, StyleSpecError> {
    let Some(value) = value else {
        return Ok(None);
    };
    let arr = value
        .as_array()
        .ok_or_else(|| StyleSpecError::InvalidField {
            id: "symbol".into(),
            field,
            expected: "array of 4 numbers",
        })?;
    if arr.len() != 4 {
        return Err(StyleSpecError::InvalidField {
            id: "symbol".into(),
            field,
            expected: "array of 4 numbers",
        });
    }
    let mut out = [0.0f32; 4];
    for (i, v) in arr.iter().enumerate() {
        out[i] = v.as_f64().ok_or_else(|| StyleSpecError::InvalidField {
            id: "symbol".into(),
            field,
            expected: "numeric array element",
        })? as f32;
    }
    Ok(Some(out))
}

fn parse_vec2_array(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<[f32; 2], StyleSpecError> {
    if arr.len() != 2 {
        return Err(StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "[x, y] array of 2 numbers",
        });
    }
    let x = arr[0]
        .as_f64()
        .ok_or_else(|| StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "numeric value in [x, y] array",
        })? as f32;
    let y = arr[1]
        .as_f64()
        .ok_or_else(|| StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "numeric value in [x, y] array",
        })? as f32;
    Ok([x, y])
}

fn parse_color_array(
    id: &str,
    field: &'static str,
    array: &[Value],
) -> Result<[f32; 4], StyleSpecError> {
    if !(array.len() == 3 || array.len() == 4) {
        return Err(StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "RGB or RGBA array",
        });
    }
    let mut rgba = [0.0, 0.0, 0.0, 1.0];
    for (i, value) in array.iter().enumerate() {
        rgba[i] = value.as_f64().ok_or_else(|| StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "numeric RGB/RGBA components",
        })? as f32;
    }
    Ok(rgba)
}

fn parse_color_string(
    id: &str,
    field: &'static str,
    text: &str,
) -> Result<[f32; 4], StyleSpecError> {
    let hex = text
        .strip_prefix('#')
        .ok_or_else(|| StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "hex color string like `#RRGGBB` or `#RRGGBBAA`",
        })?;

    let rgba = match hex.len() {
        3 => {
            let r = u8::from_str_radix(&hex[0..1].repeat(2), 16).ok();
            let g = u8::from_str_radix(&hex[1..2].repeat(2), 16).ok();
            let b = u8::from_str_radix(&hex[2..3].repeat(2), 16).ok();
            [r, g, b, Some(255)]
        }
        4 => {
            let r = u8::from_str_radix(&hex[0..1].repeat(2), 16).ok();
            let g = u8::from_str_radix(&hex[1..2].repeat(2), 16).ok();
            let b = u8::from_str_radix(&hex[2..3].repeat(2), 16).ok();
            let a = u8::from_str_radix(&hex[3..4].repeat(2), 16).ok();
            [r, g, b, a]
        }
        6 => {
            let r = u8::from_str_radix(&hex[0..2], 16).ok();
            let g = u8::from_str_radix(&hex[2..4], 16).ok();
            let b = u8::from_str_radix(&hex[4..6], 16).ok();
            [r, g, b, Some(255)]
        }
        8 => {
            let r = u8::from_str_radix(&hex[0..2], 16).ok();
            let g = u8::from_str_radix(&hex[2..4], 16).ok();
            let b = u8::from_str_radix(&hex[4..6], 16).ok();
            let a = u8::from_str_radix(&hex[6..8], 16).ok();
            [r, g, b, a]
        }
        _ => [None, None, None, None],
    };

    match rgba {
        [Some(r), Some(g), Some(b), Some(a)] => Ok([
            r as f32 / 255.0,
            g as f32 / 255.0,
            b as f32 / 255.0,
            a as f32 / 255.0,
        ]),
        _ => Err(StyleSpecError::InvalidField {
            id: id.to_owned(),
            field,
            expected: "hex color string like `#RRGGBB` or `#RRGGBBAA`",
        }),
    }
}

fn default_style_version() -> u8 {
    8
}

// ---------------------------------------------------------------------------
// MapLibre expression JSON parsing
// ---------------------------------------------------------------------------
//
// MapLibre expressions are JSON arrays where the first element is a string
// operator name. This parser converts them into the typed `Expression<T>`
// AST. For example:
//
//   ["get", "height"]          → Expression::GetProperty { key: "height", fallback }
//   ["interpolate", ["linear"], ["zoom"], 0, 1, 20, 10]
//                              → Expression::Interpolate { input: Zoom, stops }
//   ["match", ["get", "type"], "residential", "#00f", "commercial", "#f00", "#888"]
//                              → Expression::Match { input, cases, fallback }
//   ["step", ["zoom"], 1, 5, 2, 10, 3]
//                              → Expression::Step { input: Zoom, default, stops }
//   ["case", cond1, val1, ..., fallback]
//                              → Expression::Case { branches, fallback }

use crate::expression::{BoolExpression, Expression, NumericExpression, StringExpression};

/// Check whether a JSON array looks like a MapLibre expression (starts with a string operator).
fn is_expression_array(arr: &[Value]) -> bool {
    arr.first()
        .and_then(Value::as_str)
        .map(|op| {
            matches!(
                op,
                "get"
                    | "has"
                    | "!"
                    | "all"
                    | "any"
                    | "=="
                    | "!="
                    | ">"
                    | ">="
                    | "<"
                    | "<="
                    | "+"
                    | "-"
                    | "*"
                    | "/"
                    | "%"
                    | "^"
                    | "abs"
                    | "ln"
                    | "sqrt"
                    | "min"
                    | "max"
                    | "interpolate"
                    | "step"
                    | "match"
                    | "case"
                    | "coalesce"
                    | "zoom"
                    | "pitch"
                    | "concat"
                    | "upcase"
                    | "downcase"
                    | "feature-state"
                    | "to-number"
                    | "to-string"
                    | "to-boolean"
                    | "literal"
            )
        })
        .unwrap_or(false)
}

/// Parse a MapLibre expression array into an `Expression<f32>`.
fn parse_expression_f32(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<f32>, StyleSpecError> {
    let op = arr[0].as_str().unwrap_or("");
    match op {
        "literal" if arr.len() == 2 => {
            let v = arr[1]
                .as_f64()
                .ok_or_else(|| expr_err(id, field, "literal number"))? as f32;
            Ok(Expression::Constant(v))
        }
        "get" if arr.len() == 2 => {
            let key = arr[1]
                .as_str()
                .ok_or_else(|| expr_err(id, field, "get property key"))?;
            Ok(Expression::GetProperty {
                key: key.to_owned(),
                fallback: 0.0,
            })
        }
        "feature-state" if arr.len() == 2 => {
            let key = arr[1]
                .as_str()
                .ok_or_else(|| expr_err(id, field, "feature-state key"))?;
            Ok(Expression::FeatureState {
                key: key.to_owned(),
                fallback: 0.0,
            })
        }
        "zoom" => Ok(Expression::Interpolate {
            input: Box::new(NumericExpression::Zoom),
            stops: vec![],
        }),
        "interpolate" => parse_interpolate_f32(id, field, arr),
        "step" => parse_step_f32(id, field, arr),
        "case" => parse_case_f32(id, field, arr),
        "coalesce" => {
            let exprs: Result<Vec<_>, _> = arr[1..]
                .iter()
                .map(|v| match v {
                    Value::Number(n) => Ok(Expression::Constant(n.as_f64().unwrap_or(0.0) as f32)),
                    Value::Array(a) if is_expression_array(a) => parse_expression_f32(id, field, a),
                    _ => Err(expr_err(id, field, "coalesce sub-expression")),
                })
                .collect();
            Ok(Expression::Coalesce(exprs?))
        }
        _ => Err(expr_err(
            id,
            field,
            &format!("f32 expression (unsupported operator `{op}`)"),
        )),
    }
}

/// Parse a MapLibre expression array into an `Expression<[f32; 4]>` (color).
fn parse_expression_color(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<[f32; 4]>, StyleSpecError> {
    let op = arr[0].as_str().unwrap_or("");
    match op {
        "literal" if arr.len() == 2 => {
            if let Some(a) = arr[1].as_array() {
                let c = parse_color_array(id, field, a)?;
                Ok(Expression::Constant(c))
            } else {
                Err(expr_err(id, field, "literal color array"))
            }
        }
        "interpolate" => parse_interpolate_color(id, field, arr),
        "step" => parse_step_color(id, field, arr),
        "match" => parse_match_color(id, field, arr),
        "case" => parse_case_color(id, field, arr),
        _ => Err(expr_err(
            id,
            field,
            &format!("color expression (unsupported operator `{op}`)"),
        )),
    }
}

/// Parse a MapLibre expression array into an `Expression<String>`.
fn parse_expression_string(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<String>, StyleSpecError> {
    let op = arr[0].as_str().unwrap_or("");
    match op {
        "literal" if arr.len() == 2 => {
            let s = arr[1]
                .as_str()
                .ok_or_else(|| expr_err(id, field, "literal string"))?;
            Ok(Expression::Constant(s.to_owned()))
        }
        "get" if arr.len() == 2 => {
            let key = arr[1]
                .as_str()
                .ok_or_else(|| expr_err(id, field, "get property key"))?;
            Ok(Expression::GetProperty {
                key: key.to_owned(),
                fallback: String::new(),
            })
        }
        "feature-state" if arr.len() == 2 => {
            let key = arr[1]
                .as_str()
                .ok_or_else(|| expr_err(id, field, "feature-state key"))?;
            Ok(Expression::FeatureState {
                key: key.to_owned(),
                fallback: String::new(),
            })
        }
        "concat" => {
            let exprs: Result<Vec<_>, _> = arr[1..]
                .iter()
                .map(|v| match v {
                    Value::String(s) => Ok(Expression::Constant(s.clone())),
                    Value::Array(a) if is_expression_array(a) => {
                        parse_expression_string(id, field, a)
                    }
                    _ => Err(expr_err(id, field, "concat sub-expression")),
                })
                .collect();
            Ok(Expression::Coalesce(exprs?))
        }
        _ => Err(expr_err(
            id,
            field,
            &format!("string expression (unsupported operator `{op}`)"),
        )),
    }
}

/// Parse a MapLibre expression array into an `Expression<bool>`.
fn parse_expression_bool(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<bool>, StyleSpecError> {
    let op = arr[0].as_str().unwrap_or("");
    match op {
        "literal" if arr.len() == 2 => {
            let b = arr[1]
                .as_bool()
                .ok_or_else(|| expr_err(id, field, "literal boolean"))?;
            Ok(Expression::Constant(b))
        }
        "get" if arr.len() == 2 => {
            let key = arr[1]
                .as_str()
                .ok_or_else(|| expr_err(id, field, "get property key"))?;
            Ok(Expression::GetProperty {
                key: key.to_owned(),
                fallback: false,
            })
        }
        "feature-state" if arr.len() == 2 => {
            let key = arr[1]
                .as_str()
                .ok_or_else(|| expr_err(id, field, "feature-state key"))?;
            Ok(Expression::FeatureState {
                key: key.to_owned(),
                fallback: false,
            })
        }
        "has" if arr.len() == 2 => {
            let key = arr[1]
                .as_str()
                .ok_or_else(|| expr_err(id, field, "has property key"))?;
            Ok(Expression::Case {
                branches: vec![(BoolExpression::Has(key.to_owned()), true)],
                fallback: false,
            })
        }
        _ => Err(expr_err(
            id,
            field,
            &format!("boolean expression (unsupported operator `{op}`)"),
        )),
    }
}

// ---------------------------------------------------------------------------
// Expression sub-parsers
// ---------------------------------------------------------------------------

/// Parse a numeric sub-expression (used as input to interpolate/step).
fn parse_numeric_input(
    id: &str,
    field: &'static str,
    value: &Value,
) -> Result<NumericExpression, StyleSpecError> {
    match value {
        Value::Number(n) => Ok(NumericExpression::Literal(n.as_f64().unwrap_or(0.0))),
        Value::Array(arr) if !arr.is_empty() => {
            let op = arr[0].as_str().unwrap_or("");
            match op {
                "zoom" => Ok(NumericExpression::Zoom),
                "pitch" => Ok(NumericExpression::Pitch),
                "get" if arr.len() == 2 => {
                    let key = arr[1]
                        .as_str()
                        .ok_or_else(|| expr_err(id, field, "get key"))?;
                    Ok(NumericExpression::GetProperty {
                        key: key.to_owned(),
                        fallback: 0.0,
                    })
                }
                "feature-state" if arr.len() == 2 => {
                    let key = arr[1]
                        .as_str()
                        .ok_or_else(|| expr_err(id, field, "feature-state key"))?;
                    Ok(NumericExpression::GetState {
                        key: key.to_owned(),
                        fallback: 0.0,
                    })
                }
                "+" if arr.len() == 3 => Ok(NumericExpression::Add(
                    Box::new(parse_numeric_input(id, field, &arr[1])?),
                    Box::new(parse_numeric_input(id, field, &arr[2])?),
                )),
                "-" if arr.len() == 3 => Ok(NumericExpression::Sub(
                    Box::new(parse_numeric_input(id, field, &arr[1])?),
                    Box::new(parse_numeric_input(id, field, &arr[2])?),
                )),
                "*" if arr.len() == 3 => Ok(NumericExpression::Mul(
                    Box::new(parse_numeric_input(id, field, &arr[1])?),
                    Box::new(parse_numeric_input(id, field, &arr[2])?),
                )),
                "/" if arr.len() == 3 => Ok(NumericExpression::Div(
                    Box::new(parse_numeric_input(id, field, &arr[1])?),
                    Box::new(parse_numeric_input(id, field, &arr[2])?),
                )),
                "%" if arr.len() == 3 => Ok(NumericExpression::Mod(
                    Box::new(parse_numeric_input(id, field, &arr[1])?),
                    Box::new(parse_numeric_input(id, field, &arr[2])?),
                )),
                "^" if arr.len() == 3 => Ok(NumericExpression::Pow(
                    Box::new(parse_numeric_input(id, field, &arr[1])?),
                    Box::new(parse_numeric_input(id, field, &arr[2])?),
                )),
                "abs" if arr.len() == 2 => Ok(NumericExpression::Abs(Box::new(
                    parse_numeric_input(id, field, &arr[1])?,
                ))),
                "ln" if arr.len() == 2 => Ok(NumericExpression::Ln(Box::new(parse_numeric_input(
                    id, field, &arr[1],
                )?))),
                "sqrt" if arr.len() == 2 => Ok(NumericExpression::Sqrt(Box::new(
                    parse_numeric_input(id, field, &arr[1])?,
                ))),
                "min" if arr.len() == 3 => Ok(NumericExpression::Min(
                    Box::new(parse_numeric_input(id, field, &arr[1])?),
                    Box::new(parse_numeric_input(id, field, &arr[2])?),
                )),
                "max" if arr.len() == 3 => Ok(NumericExpression::Max(
                    Box::new(parse_numeric_input(id, field, &arr[1])?),
                    Box::new(parse_numeric_input(id, field, &arr[2])?),
                )),
                _ => Err(expr_err(
                    id,
                    field,
                    &format!("numeric input (unsupported `{op}`)"),
                )),
            }
        }
        _ => Err(expr_err(id, field, "numeric input")),
    }
}

/// Parse a string sub-expression input (used as input to match).
fn parse_string_input(
    id: &str,
    field: &'static str,
    value: &Value,
) -> Result<StringExpression, StyleSpecError> {
    match value {
        Value::String(s) => Ok(StringExpression::Literal(s.clone())),
        Value::Array(arr) if !arr.is_empty() => {
            let op = arr[0].as_str().unwrap_or("");
            match op {
                "get" if arr.len() == 2 => {
                    let key = arr[1]
                        .as_str()
                        .ok_or_else(|| expr_err(id, field, "get key"))?;
                    Ok(StringExpression::GetProperty {
                        key: key.to_owned(),
                        fallback: String::new(),
                    })
                }
                "feature-state" if arr.len() == 2 => {
                    let key = arr[1]
                        .as_str()
                        .ok_or_else(|| expr_err(id, field, "feature-state key"))?;
                    Ok(StringExpression::GetState {
                        key: key.to_owned(),
                        fallback: String::new(),
                    })
                }
                "upcase" if arr.len() == 2 => Ok(StringExpression::Upcase(Box::new(
                    parse_string_input(id, field, &arr[1])?,
                ))),
                "downcase" if arr.len() == 2 => Ok(StringExpression::Downcase(Box::new(
                    parse_string_input(id, field, &arr[1])?,
                ))),
                "concat" if arr.len() >= 3 => {
                    let left = parse_string_input(id, field, &arr[1])?;
                    let right = parse_string_input(id, field, &arr[2])?;
                    Ok(StringExpression::Concat(Box::new(left), Box::new(right)))
                }
                _ => Err(expr_err(
                    id,
                    field,
                    &format!("string input (unsupported `{op}`)"),
                )),
            }
        }
        _ => Err(expr_err(id, field, "string input")),
    }
}

/// Parse a boolean condition expression.
fn parse_bool_condition(
    id: &str,
    field: &'static str,
    value: &Value,
) -> Result<BoolExpression, StyleSpecError> {
    match value {
        Value::Bool(b) => Ok(BoolExpression::Literal(*b)),
        Value::Array(arr) if !arr.is_empty() => {
            let op = arr[0].as_str().unwrap_or("");
            match op {
                "has" if arr.len() == 2 => {
                    let key = arr[1]
                        .as_str()
                        .ok_or_else(|| expr_err(id, field, "has key"))?;
                    Ok(BoolExpression::Has(key.to_owned()))
                }
                "get" if arr.len() == 2 => {
                    let key = arr[1]
                        .as_str()
                        .ok_or_else(|| expr_err(id, field, "get key"))?;
                    Ok(BoolExpression::GetProperty {
                        key: key.to_owned(),
                        fallback: false,
                    })
                }
                "!" if arr.len() == 2 => Ok(BoolExpression::Not(Box::new(parse_bool_condition(
                    id, field, &arr[1],
                )?))),
                "all" => {
                    let exprs: Result<Vec<_>, _> = arr[1..]
                        .iter()
                        .map(|v| parse_bool_condition(id, field, v))
                        .collect();
                    Ok(BoolExpression::All(exprs?))
                }
                "any" => {
                    let exprs: Result<Vec<_>, _> = arr[1..]
                        .iter()
                        .map(|v| parse_bool_condition(id, field, v))
                        .collect();
                    Ok(BoolExpression::Any(exprs?))
                }
                "==" if arr.len() == 3 => {
                    // Try numeric comparison first, then string.
                    if let (Ok(a), Ok(b)) = (
                        parse_numeric_input(id, field, &arr[1]),
                        parse_numeric_input(id, field, &arr[2]),
                    ) {
                        Ok(BoolExpression::Eq(a, b))
                    } else if let (Ok(a), Ok(b)) = (
                        parse_string_input(id, field, &arr[1]),
                        parse_string_input(id, field, &arr[2]),
                    ) {
                        Ok(BoolExpression::StrEq(a, b))
                    } else {
                        Err(expr_err(id, field, "== operands"))
                    }
                }
                "!=" if arr.len() == 3 => {
                    let a = parse_numeric_input(id, field, &arr[1])?;
                    let b = parse_numeric_input(id, field, &arr[2])?;
                    Ok(BoolExpression::Neq(a, b))
                }
                ">" if arr.len() == 3 => {
                    let a = parse_numeric_input(id, field, &arr[1])?;
                    let b = parse_numeric_input(id, field, &arr[2])?;
                    Ok(BoolExpression::Gt(a, b))
                }
                ">=" if arr.len() == 3 => {
                    let a = parse_numeric_input(id, field, &arr[1])?;
                    let b = parse_numeric_input(id, field, &arr[2])?;
                    Ok(BoolExpression::Gte(a, b))
                }
                "<" if arr.len() == 3 => {
                    let a = parse_numeric_input(id, field, &arr[1])?;
                    let b = parse_numeric_input(id, field, &arr[2])?;
                    Ok(BoolExpression::Lt(a, b))
                }
                "<=" if arr.len() == 3 => {
                    let a = parse_numeric_input(id, field, &arr[1])?;
                    let b = parse_numeric_input(id, field, &arr[2])?;
                    Ok(BoolExpression::Lte(a, b))
                }
                _ => Err(expr_err(
                    id,
                    field,
                    &format!("boolean condition (unsupported `{op}`)"),
                )),
            }
        }
        _ => Err(expr_err(id, field, "boolean condition")),
    }
}

// ---------------------------------------------------------------------------
// Interpolate / Step / Match / Case parsers (f32)
// ---------------------------------------------------------------------------

/// Parse `["interpolate", ["linear"], input, z0, v0, z1, v1, ...]` for f32.
fn parse_interpolate_f32(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<f32>, StyleSpecError> {
    // arr[0] = "interpolate", arr[1] = interpolation type, arr[2] = input, arr[3..] = stop pairs
    if arr.len() < 5 || !(arr.len() - 3).is_multiple_of(2) {
        return Err(expr_err(id, field, "interpolate with even stop pairs"));
    }
    let input = parse_numeric_input(id, field, &arr[2])?;
    let mut stops = Vec::with_capacity((arr.len() - 3) / 2);
    for chunk in arr[3..].chunks(2) {
        let z = chunk[0]
            .as_f64()
            .ok_or_else(|| expr_err(id, field, "interpolate stop zoom"))? as f32;
        let v = chunk[1]
            .as_f64()
            .ok_or_else(|| expr_err(id, field, "interpolate stop value"))? as f32;
        stops.push((z, v));
    }
    Ok(Expression::Interpolate {
        input: Box::new(input),
        stops,
    })
}

/// Parse `["step", input, default, z0, v0, z1, v1, ...]` for f32.
fn parse_step_f32(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<f32>, StyleSpecError> {
    if arr.len() < 3 {
        return Err(expr_err(id, field, "step expression"));
    }
    let input = parse_numeric_input(id, field, &arr[1])?;
    let default = arr[2]
        .as_f64()
        .ok_or_else(|| expr_err(id, field, "step default"))? as f32;
    let mut stops = Vec::new();
    for chunk in arr[3..].chunks(2) {
        if chunk.len() == 2 {
            let z = chunk[0]
                .as_f64()
                .ok_or_else(|| expr_err(id, field, "step threshold"))? as f32;
            let v = chunk[1]
                .as_f64()
                .ok_or_else(|| expr_err(id, field, "step value"))? as f32;
            stops.push((z, v));
        }
    }
    Ok(Expression::Step {
        input: Box::new(input),
        default,
        stops,
    })
}

/// Parse `["case", cond1, val1, ..., fallback]` for f32.
fn parse_case_f32(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<f32>, StyleSpecError> {
    // arr = ["case", cond1, val1, ..., condN, valN, fallback]
    // After "case": (arr.len()-1) interior elements = pairs + 1 fallback → must be odd, i.e. (arr.len()-1) is odd.
    if arr.len() < 4 || (arr.len() - 1).is_multiple_of(2) {
        return Err(expr_err(id, field, "case expression"));
    }
    // Last element is fallback, preceding pairs are (condition, value).
    let fallback = arr[arr.len() - 1]
        .as_f64()
        .ok_or_else(|| expr_err(id, field, "case fallback"))? as f32;
    let mut branches = Vec::new();
    for chunk in arr[1..arr.len() - 1].chunks(2) {
        let cond = parse_bool_condition(id, field, &chunk[0])?;
        let val = chunk[1]
            .as_f64()
            .ok_or_else(|| expr_err(id, field, "case value"))? as f32;
        branches.push((cond, val));
    }
    Ok(Expression::Case { branches, fallback })
}

// ---------------------------------------------------------------------------
// Interpolate / Step / Match / Case parsers (color)
// ---------------------------------------------------------------------------

/// Parse `["interpolate", ["linear"], input, z0, c0, z1, c1, ...]` for colors.
fn parse_interpolate_color(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<[f32; 4]>, StyleSpecError> {
    if arr.len() < 5 || !(arr.len() - 3).is_multiple_of(2) {
        return Err(expr_err(id, field, "interpolate with even stop pairs"));
    }
    let input = parse_numeric_input(id, field, &arr[2])?;
    let mut stops = Vec::with_capacity((arr.len() - 3) / 2);
    for chunk in arr[3..].chunks(2) {
        let z = chunk[0]
            .as_f64()
            .ok_or_else(|| expr_err(id, field, "interpolate stop zoom"))? as f32;
        let c = parse_json_color(id, field, &chunk[1])?;
        stops.push((z, c));
    }
    Ok(Expression::Interpolate {
        input: Box::new(input),
        stops,
    })
}

/// Parse `["step", input, default_color, z0, c0, z1, c1, ...]` for colors.
fn parse_step_color(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<[f32; 4]>, StyleSpecError> {
    if arr.len() < 3 {
        return Err(expr_err(id, field, "step expression"));
    }
    let input = parse_numeric_input(id, field, &arr[1])?;
    let default = parse_json_color(id, field, &arr[2])?;
    let mut stops = Vec::new();
    for chunk in arr[3..].chunks(2) {
        if chunk.len() == 2 {
            let z = chunk[0]
                .as_f64()
                .ok_or_else(|| expr_err(id, field, "step threshold"))? as f32;
            let c = parse_json_color(id, field, &chunk[1])?;
            stops.push((z, c));
        }
    }
    Ok(Expression::Step {
        input: Box::new(input),
        default,
        stops,
    })
}

/// Parse `["match", input, label1, color1, ..., fallback_color]`.
fn parse_match_color(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<[f32; 4]>, StyleSpecError> {
    if arr.len() < 4 {
        return Err(expr_err(id, field, "match expression"));
    }
    let input = parse_string_input(id, field, &arr[1])?;
    let fallback = parse_json_color(id, field, &arr[arr.len() - 1])?;
    let mut cases = Vec::new();
    // arr[2..last-1] are label/value pairs.
    let pairs = &arr[2..arr.len() - 1];
    for chunk in pairs.chunks(2) {
        if chunk.len() == 2 {
            let label = chunk[0]
                .as_str()
                .ok_or_else(|| expr_err(id, field, "match label"))?;
            let color = parse_json_color(id, field, &chunk[1])?;
            cases.push((label.to_owned(), color));
        }
    }
    Ok(Expression::Match {
        input: Box::new(input),
        cases,
        fallback,
    })
}

/// Parse `["case", cond1, color1, ..., fallback_color]`.
fn parse_case_color(
    id: &str,
    field: &'static str,
    arr: &[Value],
) -> Result<StyleValue<[f32; 4]>, StyleSpecError> {
    // arr = ["case", cond1, val1, ..., condN, valN, fallback] → need at least 4 elements
    if arr.len() < 4 || (arr.len() - 1).is_multiple_of(2) {
        return Err(expr_err(id, field, "case expression"));
    }
    let fallback = parse_json_color(id, field, &arr[arr.len() - 1])?;
    let mut branches = Vec::new();
    for chunk in arr[1..arr.len() - 1].chunks(2) {
        if chunk.len() == 2 {
            let cond = parse_bool_condition(id, field, &chunk[0])?;
            let color = parse_json_color(id, field, &chunk[1])?;
            branches.push((cond, color));
        }
    }
    Ok(Expression::Case { branches, fallback })
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

/// Parse a color from a JSON value (string or array).
fn parse_json_color(
    id: &str,
    field: &'static str,
    value: &Value,
) -> Result<[f32; 4], StyleSpecError> {
    match value {
        Value::String(s) => parse_color_string(id, field, s),
        Value::Array(a) => parse_color_array(id, field, a),
        _ => Err(expr_err(id, field, "color value")),
    }
}

/// Build a standardised expression parse error.
fn expr_err(id: &str, field: &'static str, expected: &str) -> StyleSpecError {
    StyleSpecError::InvalidField {
        id: id.to_owned(),
        field,
        expected: Box::leak(format!("expression: {expected}").into_boxed_str()),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::geometry::{Feature, FeatureCollection, Geometry, Point};
    use crate::models::{ModelInstance, ModelMesh};
    use crate::style::{GeoJsonSource, ModelSource, VectorTileSource};
    use crate::tile_source::{TileResponse, TileSource};
    use rustial_math::{GeoCoord, TileId};

    #[derive(Clone, Default)]
    struct StubTileSource;

    impl TileSource for StubTileSource {
        fn request(&self, _id: TileId) {}
        fn poll(&self) -> Vec<(TileId, Result<TileResponse, crate::TileError>)> {
            Vec::new()
        }
    }

    fn sample_features() -> FeatureCollection {
        FeatureCollection {
            features: vec![Feature {
                geometry: Geometry::Point(Point {
                    coord: GeoCoord::from_lat_lon(51.1, 17.0),
                }),
                properties: HashMap::new(),
            }],
        }
    }

    #[test]
    fn parses_and_resolves_style_json() {
        let json = r##"
        {
          "version": 8,
          "projection": { "type": "equirectangular" },
           "terrain": { "source": "dem" },
           "sources": {
             "base": { "type": "raster" },
             "dem": { "type": "raster-dem" },
             "places": { "type": "geojson" },
             "labels": { "type": "vector" },
             "hero": { "type": "model" }
           },
           "layers": [
             { "id": "bg", "type": "background", "paint": { "background-color": "#112233" } },
             { "id": "raster", "type": "raster", "source": "base", "paint": { "raster-opacity": 0.75 } },
             { "id": "fill", "type": "fill", "source": "places", "paint": { "fill-color": "#ff0000" } },
             { "id": "symbol", "type": "symbol", "source": "labels", "layout": { "text-field": "name", "text-size": 18 }, "paint": { "text-color": "#00ff00" } },
             { "id": "model", "type": "model", "source": "hero" }
           ]
        }
        "##;

        let spec = parse_style_json(json).expect("parse spec");
        let mut registry = StyleSourceRegistry::new();
        registry.set_source(
            "base",
            StyleSource::Raster(crate::style::RasterSource::new(|| Box::new(StubTileSource))),
        );
        registry.set_source(
            "dem",
            StyleSource::Terrain(crate::style::TerrainSource::new(|| {
                Box::new(crate::terrain::FlatElevationSource::new(4, 4))
            })),
        );
        registry.set_source(
            "places",
            StyleSource::GeoJson(GeoJsonSource::new(sample_features())),
        );
        registry.set_source(
            "labels",
            StyleSource::VectorTile(VectorTileSource::new(sample_features())),
        );
        registry.set_source(
            "hero",
            StyleSource::Model(ModelSource::new(vec![ModelInstance::new(
                GeoCoord::from_lat_lon(0.0, 0.0),
                ModelMesh {
                    positions: vec![[0.0, 0.0, 0.0]],
                    normals: vec![[0.0, 0.0, 1.0]],
                    uvs: vec![[0.0, 0.0]],
                    indices: vec![0],
                },
            )])),
        );

        let document = spec.resolve(&registry).expect("resolve");
        assert_eq!(document.layers().len(), 5);
        assert_eq!(document.terrain_source(), Some("dem"));
        assert_eq!(document.projection(), StyleProjection::Equirectangular);
    }

    #[test]
    fn parses_projection_from_json_without_layers() {
        let json = r##"
        {
          "version": 8,
          "projection": { "type": "globe" },
           "sources": {},
           "layers": []
         }
         "##;

        let spec = parse_style_json(json).expect("parse spec");
        assert!(matches!(
            spec.projection,
            Some(StyleSpecProjection {
                projection_type: StyleSpecProjectionType::Globe
            })
        ));

        let registry = StyleSourceRegistry::new();
        let document = spec.resolve(&registry).expect("resolve");
        assert_eq!(document.projection(), StyleProjection::Globe);
    }

    #[test]
    fn parses_vertical_perspective_projection_from_json() {
        let json = r##"
        {
          "version": 8,
          "projection": { "type": "vertical-perspective" },
          "sources": {},
          "layers": []
        }
        "##;

        let spec = parse_style_json(json).expect("parse spec");
        assert!(matches!(
            spec.projection,
            Some(StyleSpecProjection {
                projection_type: StyleSpecProjectionType::VerticalPerspective
            })
        ));

        let registry = StyleSourceRegistry::new();
        let document = spec.resolve(&registry).expect("resolve");
        assert_eq!(document.projection(), StyleProjection::VerticalPerspective);
    }

    #[test]
    fn parses_zoom_stop_values_from_json() {
        let json = r##"
        {
          "version": 8,
          "sources": { "places": { "type": "geojson" } },
          "layers": [
            {
              "id": "circles",
              "type": "circle",
              "source": "places",
              "paint": {
                "circle-radius": { "stops": [[5, 4], [10, 12]] },
                "circle-color": { "stops": [[5, "#000000"], [10, "#ffffff"]] }
              }
            }
          ]
        }
        "##;

        let spec = parse_style_json(json).expect("parse spec");
        let mut registry = StyleSourceRegistry::new();
        registry.set_source(
            "places",
            StyleSource::GeoJson(GeoJsonSource::new(sample_features())),
        );
        let document = spec.resolve(&registry).expect("resolve");

        match &document.layers()[0] {
            StyleLayer::Circle(layer) => {
                assert!(matches!(layer.radius, StyleValue::ZoomStops(_)));
                assert!(matches!(layer.color, StyleValue::ZoomStops(_)));
            }
            other => panic!("expected circle layer, got {other:?}"),
        }
    }

    #[test]
    fn parses_symbol_overlap_placement_spacing_max_angle_keep_upright_writing_mode_and_offset() {
        let json = r##"
        {
          "version": 8,
          "sources": { "labels": { "type": "vector" } },
          "layers": [
            {
              "id": "symbol",
              "type": "symbol",
              "source": "labels",
              "layout": {
                "symbol-placement": "line",
                "text-allow-overlap": true,
                "icon-allow-overlap": false,
                "text-optional": true,
                "icon-optional": false,
                "text-ignore-placement": true,
                "icon-ignore-placement": false,
                "text-radial-offset": 2,
                "text-anchor": "top-right",
                "text-justify": "auto",
                "text-transform": "uppercase",
                "text-max-width": 8,
                "text-line-height": 1.5,
                "text-letter-spacing": 0.25,
                "icon-text-fit": "both",
                "icon-text-fit-padding": [1, 2, 3, 4],
                "text-variable-anchor-offset": ["top", [1, 2], "bottom", [3, 4]],
                "symbol-sort-key": 7,
                "symbol-spacing": 320,
                "text-max-angle": 90,
                "text-keep-upright": false,
                "text-field": "name",
                "text-variable-anchor": ["center", "top"],
                "text-writing-mode": "vertical",
                "text-offset": [1, 2]
              }
            }
          ]
        }
        "##;

        let spec = parse_style_json(json).expect("parse spec");
        let mut registry = StyleSourceRegistry::new();
        registry.set_source(
            "labels",
            StyleSource::VectorTile(VectorTileSource::new(sample_features())),
        );
        let document = spec.resolve(&registry).expect("resolve");

        match &document.layers()[0] {
            StyleLayer::Symbol(layer) => {
                assert_eq!(
                    layer.text_allow_overlap.as_ref().map(StyleValue::evaluate),
                    Some(true)
                );
                assert_eq!(
                    layer.icon_allow_overlap.as_ref().map(StyleValue::evaluate),
                    Some(false)
                );
                assert_eq!(
                    layer.text_optional.as_ref().map(StyleValue::evaluate),
                    Some(true)
                );
                assert_eq!(
                    layer.icon_optional.as_ref().map(StyleValue::evaluate),
                    Some(false)
                );
                assert_eq!(
                    layer
                        .text_ignore_placement
                        .as_ref()
                        .map(StyleValue::evaluate),
                    Some(true)
                );
                assert_eq!(
                    layer
                        .icon_ignore_placement
                        .as_ref()
                        .map(StyleValue::evaluate),
                    Some(false)
                );
                assert_eq!(
                    layer.radial_offset.as_ref().map(StyleValue::evaluate),
                    Some(2.0)
                );
                assert_eq!(layer.anchor, SymbolAnchor::TopRight);
                assert_eq!(layer.justify.evaluate(), SymbolTextJustify::Auto);
                assert_eq!(layer.transform.evaluate(), SymbolTextTransform::Uppercase);
                assert_eq!(
                    layer.max_width.as_ref().map(StyleValue::evaluate),
                    Some(8.0)
                );
                assert_eq!(
                    layer.line_height.as_ref().map(StyleValue::evaluate),
                    Some(1.5)
                );
                assert_eq!(
                    layer.letter_spacing.as_ref().map(StyleValue::evaluate),
                    Some(0.25)
                );
                assert_eq!(layer.icon_text_fit.evaluate(), SymbolIconTextFit::Both);
                assert_eq!(layer.icon_text_fit_padding, [1.0, 2.0, 3.0, 4.0]);
                assert_eq!(
                    layer.variable_anchor_offsets,
                    Some(vec![
                        (SymbolAnchor::Top, [1.0, 2.0]),
                        (SymbolAnchor::Bottom, [3.0, 4.0]),
                    ])
                );
                assert_eq!(layer.sort_key.as_ref().map(StyleValue::evaluate), Some(7.0));
                assert_eq!(layer.placement, SymbolPlacement::Line);
                assert_eq!(layer.spacing.evaluate(), 320.0);
                assert_eq!(layer.max_angle.evaluate(), 90.0);
                assert!(!layer.keep_upright.evaluate());
                assert_eq!(
                    layer.variable_anchors,
                    vec![SymbolAnchor::Center, SymbolAnchor::Top]
                );
                assert_eq!(layer.writing_mode, SymbolWritingMode::Vertical);
                assert_eq!(layer.offset, [1.0, 2.0]);
            }
            other => panic!("expected symbol layer, got {other:?}"),
        }
    }

    #[test]
    fn parses_source_layer_for_vector_style_layers() {
        let json = r##"
        {
          "version": 8,
          "sources": { "labels": { "type": "vector" } },
          "layers": [
            {
              "id": "roads",
              "type": "line",
              "source": "labels",
              "source-layer": "transport"
            }
          ]
        }
        "##;

        let spec = parse_style_json(json).expect("parse spec");
        assert_eq!(spec.layers.len(), 1);
        assert_eq!(spec.layers[0].source_layer.as_deref(), Some("transport"));

        let mut registry = StyleSourceRegistry::new();
        let mut source_layers = HashMap::new();
        source_layers.insert(
            "transport".to_string(),
            FeatureCollection {
                features: vec![Feature {
                    geometry: Geometry::Point(Point {
                        coord: GeoCoord::from_lat_lon(1.0, 2.0),
                    }),
                    properties: HashMap::new(),
                }],
            },
        );
        registry.set_source(
            "labels",
            StyleSource::VectorTile(VectorTileSource::from_source_layers(source_layers)),
        );

        let document = spec.resolve(&registry).expect("resolve");
        match &document.layers()[0] {
            StyleLayer::Line(layer) => {
                assert_eq!(layer.source_layer.as_deref(), Some("transport"));
            }
            other => panic!("expected line layer, got {other:?}"),
        }
    }

    // -----------------------------------------------------------------------
    // Expression JSON parsing tests
    // -----------------------------------------------------------------------

    #[test]
    fn f32_expression_interpolate_on_zoom() {
        let json = r##"
        {
          "version": 8,
          "sources": { "s": { "type": "vector" } },
          "layers": [
            {
              "id": "l",
              "type": "line",
              "source": "s",
              "paint": {
                "line-width": ["interpolate", ["linear"], ["zoom"], 0, 1, 20, 10]
              }
            }
          ]
        }
        "##;
        let spec = parse_style_json(json).expect("parse");
        let mut registry = StyleSourceRegistry::new();
        registry.set_source(
            "s",
            StyleSource::VectorTile(VectorTileSource::new(sample_features())),
        );
        let doc = spec.resolve(&registry).expect("resolve");
        match &doc.layers()[0] {
            StyleLayer::Line(layer) => {
                let ctx = crate::style::StyleEvalContext::new(10.0);
                let width = layer.width.evaluate_with_context(ctx);
                assert!((width - 5.5).abs() < 0.1, "expected ~5.5, got {width}");
            }
            other => panic!("expected line, got {other:?}"),
        }
    }

    #[test]
    fn f32_expression_step_on_zoom() {
        let json = r##"
        {
          "version": 8,
          "sources": { "s": { "type": "vector" } },
          "layers": [
            {
              "id": "l",
              "type": "circle",
              "source": "s",
              "paint": {
                "circle-radius": ["step", ["zoom"], 2, 5, 4, 10, 8]
              }
            }
          ]
        }
        "##;
        let spec = parse_style_json(json).expect("parse");
        let mut registry = StyleSourceRegistry::new();
        registry.set_source(
            "s",
            StyleSource::VectorTile(VectorTileSource::new(sample_features())),
        );
        let doc = spec.resolve(&registry).expect("resolve");
        match &doc.layers()[0] {
            StyleLayer::Circle(layer) => {
                use crate::expression::ExprEvalContext;
                // Below first stop
                assert!(
                    (layer.radius.eval_full(&ExprEvalContext::zoom_only(3.0)) - 2.0).abs()
                        < f32::EPSILON
                );
                // At first stop
                assert!(
                    (layer.radius.eval_full(&ExprEvalContext::zoom_only(5.0)) - 4.0).abs()
                        < f32::EPSILON
                );
                // Between stops
                assert!(
                    (layer.radius.eval_full(&ExprEvalContext::zoom_only(7.0)) - 4.0).abs()
                        < f32::EPSILON
                );
                // At second stop
                assert!(
                    (layer.radius.eval_full(&ExprEvalContext::zoom_only(10.0)) - 8.0).abs()
                        < f32::EPSILON
                );
                // Above all stops
                assert!(
                    (layer.radius.eval_full(&ExprEvalContext::zoom_only(15.0)) - 8.0).abs()
                        < f32::EPSILON
                );
            }
            other => panic!("expected circle, got {other:?}"),
        }
    }

    #[test]
    fn color_expression_match_on_property() {
        let json = r##"
        {
          "version": 8,
          "sources": { "s": { "type": "vector" } },
          "layers": [
            {
              "id": "l",
              "type": "fill",
              "source": "s",
              "paint": {
                "fill-color": ["match", ["get", "type"], "residential", "#0000ff", "commercial", "#ff0000", "#888888"]
              }
            }
          ]
        }
        "##;
        let spec = parse_style_json(json).expect("parse");
        let mut registry = StyleSourceRegistry::new();
        registry.set_source(
            "s",
            StyleSource::VectorTile(VectorTileSource::new(sample_features())),
        );
        let doc = spec.resolve(&registry).expect("resolve");
        match &doc.layers()[0] {
            StyleLayer::Fill(layer) => {
                use crate::expression::ExprEvalContext;
                use crate::geometry::PropertyValue;

                let mut props = std::collections::HashMap::new();
                props.insert(
                    "type".to_string(),
                    PropertyValue::String("residential".to_string()),
                );
                let ctx = ExprEvalContext::with_feature(10.0, &props);
                let color = layer.fill_color.eval_full(&ctx);
                assert!((color[0] - 0.0).abs() < 0.01);
                assert!((color[2] - 1.0).abs() < 0.01);

                props.insert(
                    "type".to_string(),
                    PropertyValue::String("commercial".to_string()),
                );
                let ctx = ExprEvalContext::with_feature(10.0, &props);
                let color = layer.fill_color.eval_full(&ctx);
                assert!((color[0] - 1.0).abs() < 0.01);
                assert!((color[2] - 0.0).abs() < 0.01);

                // fallback
                props.insert(
                    "type".to_string(),
                    PropertyValue::String("industrial".to_string()),
                );
                let ctx = ExprEvalContext::with_feature(10.0, &props);
                let color = layer.fill_color.eval_full(&ctx);
                assert!((color[0] - 0.533).abs() < 0.01);
            }
            other => panic!("expected fill, got {other:?}"),
        }
    }

    #[test]
    fn f32_expression_get_property() {
        let json = r##"
        {
          "version": 8,
          "sources": { "s": { "type": "vector" } },
          "layers": [
            {
              "id": "l",
              "type": "fill-extrusion",
              "source": "s",
              "paint": {
                "fill-extrusion-height": ["get", "height"],
                "fill-extrusion-base": ["get", "base"]
              }
            }
          ]
        }
        "##;
        let spec = parse_style_json(json).expect("parse");
        let mut registry = StyleSourceRegistry::new();
        registry.set_source(
            "s",
            StyleSource::VectorTile(VectorTileSource::new(sample_features())),
        );
        let doc = spec.resolve(&registry).expect("resolve");
        match &doc.layers()[0] {
            StyleLayer::FillExtrusion(layer) => {
                use crate::expression::ExprEvalContext;
                use crate::geometry::PropertyValue;
                let mut props = std::collections::HashMap::new();
                props.insert("height".to_string(), PropertyValue::Number(50.0));
                props.insert("base".to_string(), PropertyValue::Number(10.0));
                let ctx = ExprEvalContext::with_feature(14.0, &props);
                assert!((layer.height.eval_full(&ctx) - 50.0).abs() < f32::EPSILON);
                assert!((layer.base.eval_full(&ctx) - 10.0).abs() < f32::EPSILON);
            }
            other => panic!("expected fill-extrusion, got {other:?}"),
        }
    }

    #[test]
    fn f32_expression_case_with_comparison() {
        let json = r##"
        {
          "version": 8,
          "sources": { "s": { "type": "vector" } },
          "layers": [
            {
              "id": "l",
              "type": "line",
              "source": "s",
              "paint": {
                "line-width": ["case", [">", ["get", "lanes"], 2], 8, 2]
              }
            }
          ]
        }
        "##;
        let spec = parse_style_json(json).expect("parse");
        let mut registry = StyleSourceRegistry::new();
        registry.set_source(
            "s",
            StyleSource::VectorTile(VectorTileSource::new(sample_features())),
        );
        let doc = spec.resolve(&registry).expect("resolve");
        match &doc.layers()[0] {
            StyleLayer::Line(layer) => {
                use crate::expression::ExprEvalContext;
                use crate::geometry::PropertyValue;

                // lanes = 4 > 2, so width = 8
                let mut props = std::collections::HashMap::new();
                props.insert("lanes".to_string(), PropertyValue::Number(4.0));
                let ctx = ExprEvalContext::with_feature(14.0, &props);
                assert!((layer.width.eval_full(&ctx) - 8.0).abs() < f32::EPSILON);

                // lanes = 1, not > 2, so width = 2 (fallback)
                props.insert("lanes".to_string(), PropertyValue::Number(1.0));
                let ctx = ExprEvalContext::with_feature(14.0, &props);
                assert!((layer.width.eval_full(&ctx) - 2.0).abs() < f32::EPSILON);
            }
            other => panic!("expected line, got {other:?}"),
        }
    }
}