passerelle-geo-components 0.2.0-alpha.1

package/schemas/scene_manifest.schema.json

@@ -0,0 +1,905 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nic01asfr.github.io/Passerelle/schemas/scene_manifest/0.3.1.json",
+  "title": "SceneManifest V0.3.1",
+  "description": "Contract unifie passerelle-geo-components pivot cross-projet (workspace SIG + editeur livrables + widget carto). Voir CONTRACT-V0.3.1.md pour la spec humaine complete.",
+  "type": "object",
+  "required": [
+    "manifest_version",
+    "produced_at",
+    "provenance",
+    "title",
+    "basemap",
+    "zone",
+    "layers"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri",
+      "description": "Pointeur JSON Schema self-description (facultatif si absent)."
+    },
+    "manifest_version": {
+      "type": "string",
+      "pattern": "^0\\.3\\.[0-9]+$",
+      "description": "Version SemVer strict du contract. V0.3.x lit tout 0.3.y avec y ≤ x (compat descendante 2 versions mineures).",
+      "readOnly": true
+    },
+    "scene_hash": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$",
+      "description": "Hash SHA-256 canonique du manifest_body. Calculé UNIQUEMENT côté producteur (au snapshot dans scene_store/). Le consommateur ne recalcule jamais côté main thread. Helper computeSceneHashInWorker() disponible pour vérification offline.",
+      "readOnly": true
+    },
+    "manifest_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "UUID4 unique du manifest. Généré au publish.",
+      "readOnly": true
+    },
+    "produced_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Timestamp ISO 8601 avec TZ. Généré au publish.",
+      "readOnly": true
+    },
+    "title": {
+      "type": "string",
+      "maxLength": 300,
+      "description": "Titre principal de la scène (affiché en header carto)."
+    },
+    "subtitle": {
+      "type": "string",
+      "maxLength": 300,
+      "description": "Sous-titre optionnel."
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 2000,
+      "description": "Description longue (paragraphe intro)."
+    },
+    "source_text": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Citation datée des sources de données (BD TOPO IGN 2024, ...)."
+    },
+    "caveat": {
+      "type": "string",
+      "maxLength": 2000,
+      "description": "Disclaimer méthodologique (marge d'erreur, données pédagogiques, ...)."
+    },
+    "provenance": { "$ref": "#/$defs/Provenance" },
+    "projection": {
+      "description": "Projection cartographique. 'mercator' (défaut), 'globe' (MapLibre v5+), 'lambert93' (via adapter proj-lambert93). Enum ouverte : accepte x_<projet>_* avec fallback graceful 'mercator'.",
+      "type": "string",
+      "oneOf": [
+        { "const": "mercator", "title": "Web Mercator EPSG:3857 (standard MapLibre)" },
+        { "const": "globe", "title": "Projection globe (MapLibre v5+, requiert setProjection)" },
+        { "const": "lambert93", "title": "Lambert-93 EPSG:2154 (requiert adapters/proj-lambert93.js)" },
+        { "type": "string", "pattern": "^x_[a-z_]+$", "title": "Extension nommée par projet" }
+      ],
+      "default": "mercator"
+    },
+    "basemap": { "$ref": "#/$defs/Basemap" },
+    "basemap_switcher": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "IDs de basemaps proposés en toggle runtime UI (opt.). Défaut : uniquement basemap.id actuel."
+    },
+    "zone": { "$ref": "#/$defs/Zone" },
+    "camera_presets": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/CameraPreset" },
+      "description": "Presets caméra nommés (top, 3d, street, ...). Utilisés par API impérative flyToPreset()."
+    },
+    "terrain": { "$ref": "#/$defs/Terrain" },
+    "sky": { "$ref": "#/$defs/Sky" },
+    "layers": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Layer" },
+      "description": "Couches cartographiques. Ordre = ordre de rendu (z_index respecté si défini)."
+    },
+    "custom_layers": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/CustomLayer" },
+      "description": "Couches custom Three.js. Trigger dimension='3d' auto (lib dérivée). Chargé uniquement si <geo-3d-scene> composition slot présent."
+    },
+    "legend": { "$ref": "#/$defs/Legend" },
+    "scalebar": {
+      "type": "object",
+      "properties": {
+        "position": { "$ref": "#/$defs/OverlayPosition" },
+        "unit": { "enum": ["metric", "imperial", "nautical"], "default": "metric" }
+      },
+      "additionalProperties": false
+    },
+    "north_arrow": {
+      "type": "object",
+      "properties": {
+        "position": { "$ref": "#/$defs/OverlayPosition" }
+      },
+      "additionalProperties": false
+    },
+    "counters": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Counter" },
+      "description": "Compteurs live bindés (nb features filtrés, %, ...)."
+    },
+    "extensions": {
+      "type": "object",
+      "description": "Extensions par-projet indexees par prefix (x_livrables, x_atlas, x_sig, x_zebra, ...). Contenu libre (additionalProperties: true).",
+      "patternProperties": {
+        "^[a-z][a-z_0-9]*$": { "type": "object", "additionalProperties": true }
+      },
+      "additionalProperties": false
+    }
+  },
+  "$defs": {
+    "Provenance": {
+      "type": "object",
+      "required": ["producer", "producer_version"],
+      "properties": {
+        "producer": {
+          "description": "Producteur du manifest. Enum ouverte : accepte x_<projet>_* avec fallback graceful 'manual'.",
+          "oneOf": [
+            { "const": "qgis-sspcloud" },
+            { "const": "cerema-livrables" },
+            { "const": "atlas" },
+            { "const": "manual" },
+            { "type": "string", "pattern": "^x_[a-z_]+$" }
+          ]
+        },
+        "producer_version": { "type": "string" },
+        "source_project": { "type": "string", "description": "Chemin projet source (ex: .qgz path)." },
+        "qgz_hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+        "agent_conversation_id": { "type": "string", "description": "ID conversation LLM si issu d'un agent." },
+        "recipe_used": {
+          "type": "object",
+          "properties": {
+            "slug": { "type": "string" },
+            "version_sha": { "type": "string" }
+          },
+          "additionalProperties": false
+        },
+        "extensions": {
+          "type": "object",
+          "patternProperties": { "^[a-z][a-z_0-9]*$": { "type": "object", "additionalProperties": true } },
+          "additionalProperties": false,
+          "description": "Extensions provenance par-projet (ex: atlas.native_payload_hash pour round-trip fidèle)."
+        }
+      },
+      "additionalProperties": true,
+      "readOnly": true
+    },
+
+    "Basemap": {
+      "type": "object",
+      "required": ["id"],
+      "properties": {
+        "id": {
+          "description": "ID du fond de carte. Enum ouverte : accepte x_<projet>_* avec fallback graceful 'osm'.",
+          "oneOf": [
+            { "const": "osm", "title": "OpenStreetMap Positron (CartoDB CDN)" },
+            { "const": "plan-ign-v2", "title": "Plan IGN Standard (WMTS Géoplateforme)" },
+            { "const": "plan-ign-v2-gris", "title": "Plan IGN GRIS (neutre, recommandé fond thématique)" },
+            { "const": "ortho-ign", "title": "Orthophoto IGN (WMTS)" },
+            { "const": "hillshade-ign", "title": "Estompage IGN (WMTS)" },
+            { "const": "dsfr-sobre", "title": "Fond DSFR sobre" },
+            { "const": "etalab", "title": "Étalab" },
+            { "const": "openfreemap-liberty", "title": "OpenFreeMap Liberty vecteur" },
+            { "const": "openfreemap-bright", "title": "OpenFreeMap Bright" },
+            { "const": "openfreemap-positron", "title": "OpenFreeMap Positron" },
+            { "const": "cartodb-positron-nolabels", "title": "Positron sans labels (CartoDB CDN)" },
+            { "const": "custom", "title": "Style JSON custom (via basemap.style)" },
+            { "type": "string", "pattern": "^x_[a-z_]+$", "title": "Extension nommée par projet" }
+          ]
+        },
+        "style": {
+          "type": ["object", "null"],
+          "description": "Style JSON MapLibre v8 (utilisé si id='custom' ou fallback si id inconnu).",
+          "additionalProperties": true
+        },
+        "alternatives": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "IDs alternatifs pour switcher UI runtime."
+        },
+        "toggles": {
+          "type": "object",
+          "properties": {
+            "labels": { "type": "boolean", "default": true, "description": "Toggle labels basemap (absorbé de ex-overlays)." },
+            "buildings_3d": { "type": "boolean", "default": false, "description": "Toggle fill-extrusion bâtiments natifs basemap." }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "Zone": {
+      "description": "Zone d'étude / vue caméra initiale. Discriminated union sur 'kind'.",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["kind"],
+          "properties": {
+            "kind": { "const": "manual" },
+            "bbox": { "$ref": "#/$defs/BBox" },
+            "center": { "$ref": "#/$defs/Coord" },
+            "zoom": { "type": "number", "minimum": 0, "maximum": 22 },
+            "pitch": { "type": "number", "minimum": 0, "maximum": 85 },
+            "bearing": { "type": "number", "minimum": -180, "maximum": 180 },
+            "max_pitch": { "type": "number", "minimum": 0, "maximum": 85, "default": 60 }
+          },
+          "additionalProperties": false,
+          "description": "Zone manuelle : bbox OU (center + zoom). Au moins l'un des deux requis."
+        },
+        {
+          "type": "object",
+          "required": ["kind", "insee"],
+          "properties": {
+            "kind": { "enum": ["commune", "insee_arm"] },
+            "insee": {
+              "type": "string",
+              "pattern": "^[0-9AB]{5}$",
+              "description": "Code INSEE 5 chars (commune 75001-...; arrondissement 75101-75120, 13201-13216, 69381-69389)."
+            },
+            "buffer_km": { "type": "number", "minimum": 0, "maximum": 50, "description": "Rayon buffer autour de la commune (facultatif)." },
+            "pitch": { "type": "number", "minimum": 0, "maximum": 85 },
+            "bearing": { "type": "number", "minimum": -180, "maximum": 180 },
+            "max_pitch": { "type": "number", "minimum": 0, "maximum": 85, "default": 60 }
+          },
+          "additionalProperties": false,
+          "description": "Zone administrative : commune ou arrondissement municipal. Center + zoom dérivés côté renderer."
+        },
+        {
+          "type": "object",
+          "required": ["kind"],
+          "properties": {
+            "kind": { "const": "auto_bounds" },
+            "pitch": { "type": "number", "minimum": 0, "maximum": 85 },
+            "bearing": { "type": "number", "minimum": -180, "maximum": 180 },
+            "max_pitch": { "type": "number", "minimum": 0, "maximum": 85, "default": 60 }
+          },
+          "additionalProperties": false,
+          "description": "Zone dérivée automatiquement de layers[].bbox unifiés."
+        },
+        {
+          "type": "object",
+          "required": ["kind"],
+          "properties": {
+            "kind": { "type": "string", "pattern": "^x_[a-z_]+$", "description": "Extension nommée par projet." }
+          },
+          "additionalProperties": true
+        }
+      ]
+    },
+
+    "BBox": {
+      "type": "array",
+      "items": { "type": "number" },
+      "minItems": 4,
+      "maxItems": 4,
+      "description": "Bounding box [west, south, east, north] EPSG:4326 (GeoJSON RFC 7946 §5)."
+    },
+    "Coord": {
+      "type": "array",
+      "items": { "type": "number" },
+      "minItems": 2,
+      "maxItems": 2,
+      "description": "Coordonnée [longitude, latitude] EPSG:4326."
+    },
+
+    "CameraPreset": {
+      "type": "object",
+      "required": ["id", "pitch", "bearing", "zoom"],
+      "properties": {
+        "id": { "type": "string", "description": "Identifiant unique du preset (top, 3d, street, ...)." },
+        "pitch": { "type": "number", "minimum": 0, "maximum": 85 },
+        "bearing": { "type": "number", "minimum": -180, "maximum": 180 },
+        "zoom": { "type": "number", "minimum": 0, "maximum": 22 }
+      },
+      "additionalProperties": false
+    },
+
+    "Terrain": {
+      "type": "object",
+      "required": ["source_id"],
+      "properties": {
+        "source_id": {
+          "description": "Source DEM. Enum ouverte : accepte x_* pour custom.",
+          "oneOf": [
+            { "const": "ign-lidar", "title": "IGN LIDAR HD (France, requiert adapter ignmnt)" },
+            { "const": "terrarium", "title": "Terrarium AWS (mondial, sans clé)" },
+            { "const": "custom", "title": "URL WMTS raster-dem custom (requiert custom_tiles_url)" },
+            { "type": "string", "pattern": "^x_[a-z_]+$" }
+          ]
+        },
+        "encoding": { "enum": ["mapbox", "terrarium"], "default": "mapbox" },
+        "exaggeration": { "type": "number", "minimum": 0, "maximum": 10, "default": 1.0 },
+        "adapter": {
+          "description": "Adapter chargé à la demande (registre ADAPTERS fermé). null si source_id ne nécessite pas d'adapter.",
+          "type": ["string", "null"],
+          "enum": ["ignmnt", null]
+        },
+        "custom_tiles_url": { "type": "string", "format": "uri", "description": "URL tiles raster-dem si source_id='custom'." },
+        "hillshade": {
+          "type": ["object", "null"],
+          "properties": {
+            "opacity": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.35 },
+            "blend_mode": { "enum": ["multiply", "normal", "overlay"], "default": "multiply" }
+          },
+          "additionalProperties": false,
+          "description": "Effet hillshade (absorbe l'ex overlays.hillshade)."
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "Sky": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean", "default": true },
+        "dynamic_sun": { "type": "boolean", "default": true, "description": "Recalcul SunCalc auto selon sun_datetime + location_for_suncalc." },
+        "sun_datetime": { "type": "string", "format": "date-time" },
+        "location_for_suncalc": {
+          "type": "object",
+          "properties": {
+            "lat": { "type": "number", "minimum": -90, "maximum": 90 },
+            "lng": { "type": "number", "minimum": -180, "maximum": 180 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "Layer": {
+      "type": "object",
+      "required": ["id", "name", "role", "geometry_type", "source", "style"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_-]*$",
+          "description": "Identifiant slug unique dans le manifest."
+        },
+        "name": { "type": "string", "maxLength": 300, "description": "Nom affiché en légende." },
+        "role": {
+          "description": "Rôle sémantique. Enum ouverte + fallback 'primary'.",
+          "oneOf": [
+            { "const": "primary", "title": "Couche métier principale (style + tooltip actifs)." },
+            { "const": "context", "title": "Contexte territorial (opacité réduite, non interactif)." },
+            { "const": "emprise", "title": "Contour emprise du sujet (Livrables — fill + line surlignage)." },
+            { "const": "members", "title": "Documents/entités groupés (Livrables — 1 emprise = N docs)." },
+            { "const": "site", "title": "Site ponctuel unique (marker prominent)." },
+            { "type": "string", "pattern": "^x_[a-z_]+$", "title": "Rôle métier custom (fallback: primary)." }
+          ]
+        },
+        "geometry_type": {
+          "enum": ["point", "line", "polygon", "multipolygon", "raster"],
+          "description": "Type géométrie MapLibre (guide l'auto-split polygon+point si Feature Collection mixte)."
+        },
+        "source": { "$ref": "#/$defs/LayerSource" },
+        "n_features": { "type": "integer", "minimum": 0, "description": "Nombre de features (pré-calculé — obligatoire si source.type ≠ geojson)." },
+        "bbox": { "$ref": "#/$defs/BBox" },
+        "attribute_stats": {
+          "type": "object",
+          "patternProperties": {
+            "^[a-zA-Z_][a-zA-Z0-9_]*$": {
+              "type": "object",
+              "properties": {
+                "min": { "type": "number" },
+                "max": { "type": "number" },
+                "null_count": { "type": "integer" },
+                "distinct_count": { "type": "integer" },
+                "distinct_values": { "type": "array" }
+              },
+              "additionalProperties": true
+            }
+          },
+          "additionalProperties": true
+        },
+        "style": { "$ref": "#/$defs/LayerStyle" },
+        "interactions": { "$ref": "#/$defs/Interactions" },
+        "min_zoom": { "type": ["number", "null"], "minimum": 0, "maximum": 22 },
+        "max_zoom": { "type": ["number", "null"], "minimum": 0, "maximum": 22 },
+        "extensions": {
+          "type": "object",
+          "patternProperties": { "^[a-z][a-z_0-9]*$": { "type": "object", "additionalProperties": true } },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "LayerSource": {
+      "description": "Source de données. Discriminated union sur 'type'. Alignée MapLibre style spec (v8+).",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["type", "data"],
+          "properties": {
+            "type": { "const": "geojson" },
+            "data": {
+              "description": "FeatureCollection inline OU URL. AUTORISÉ UNIQUEMENT si n_features ≤ 500 (500 KB) — sinon warning validation, interdit au-delà de 5 MB.",
+              "oneOf": [
+                { "type": "string", "format": "uri" },
+                { "type": "object", "required": ["type", "features"], "properties": { "type": { "const": "FeatureCollection" }, "features": { "type": "array" } }, "additionalProperties": true }
+              ]
+            },
+            "crs": { "type": "string", "const": "EPSG:4326", "default": "EPSG:4326" }
+          },
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "required": ["type", "path"],
+          "properties": {
+            "type": { "const": "geojson_path" },
+            "path": { "type": "string", "description": "Chemin PVC ou URL relative (résolu côté hub)." },
+            "crs": { "type": "string", "const": "EPSG:4326", "default": "EPSG:4326" }
+          },
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "required": ["type", "url", "source_layer"],
+          "properties": {
+            "type": { "const": "vector" },
+            "url": { "type": "string", "description": "URL template MapLibre : https://.../{z}/{x}/{y}.pbf" },
+            "source_layer": { "type": "string" },
+            "min_zoom": { "type": "integer", "minimum": 0, "maximum": 22 },
+            "max_zoom": { "type": "integer", "minimum": 0, "maximum": 22 },
+            "promote_id": { "type": "string" }
+          },
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "required": ["type", "url", "source_layer"],
+          "properties": {
+            "type": { "const": "pmtiles" },
+            "url": { "type": "string", "format": "uri", "description": "URL fichier .pmtiles (résolu via pmtiles:// protocol MapLibre)." },
+            "source_layer": { "type": "string" },
+            "promote_id": { "type": "string" }
+          },
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "required": ["type", "table"],
+          "properties": {
+            "type": { "const": "grist_table" },
+            "table": { "type": "string", "description": "Nom table Grist dans le doc courant." },
+            "id_field": { "type": "string", "default": "id" },
+            "sync": {
+              "enum": ["load", "reactive", "save"],
+              "default": "load",
+              "description": "load: one-shot fetch. reactive: subscribe onRecords. save: bidirectionnel."
+            }
+          },
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "required": ["type", "url", "type_name"],
+          "properties": {
+            "type": { "const": "wfs" },
+            "url": { "type": "string", "format": "uri" },
+            "type_name": { "type": "string", "description": "WFS TypeName (ex: BATIMENT.BATIMENT)." }
+          },
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "required": ["type", "catalog_id"],
+          "properties": {
+            "type": { "const": "boundary_admin" },
+            "catalog_id": { "type": "string", "description": "ID catalog IGN admin (arrondissements_marseille, communes, epci, ...)." },
+            "filter": { "type": "object", "additionalProperties": true, "description": "Filtre attributaire (ex: {insee_arm: '13204'})." }
+          },
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "required": ["type"],
+          "properties": {
+            "type": { "type": "string", "pattern": "^x_[a-z_]+$", "description": "Extension source nommée par projet." }
+          },
+          "additionalProperties": true
+        }
+      ]
+    },
+
+    "LayerStyle": {
+      "type": "object",
+      "properties": {
+        "visible": { "type": "boolean", "default": true },
+        "z_index": { "type": ["integer", "null"], "description": "Ordre d'affichage (plus élevé = au-dessus). null = ordre du tableau." },
+        "opacity": { "$ref": "#/$defs/Opacity" },
+        "classification": { "$ref": "#/$defs/Classification" },
+        "extrusion": {
+          "type": ["object", "null"],
+          "properties": {
+            "enabled": { "type": "boolean", "default": false, "description": "Active fill-extrusion 2.5D (dérive dimension='2.5d')." },
+            "height_field": { "type": "string" },
+            "base_field": { "type": ["string", "null"] },
+            "vertical_gradient": { "type": "boolean", "default": true }
+          },
+          "additionalProperties": false
+        },
+        "outline": {
+          "type": ["object", "null"],
+          "properties": {
+            "enabled": { "type": "boolean", "default": false },
+            "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "default": "#000091" },
+            "width": { "type": "number", "minimum": 0, "default": 1 }
+          },
+          "additionalProperties": false,
+          "description": "Ajoute automatiquement un layer 'line' sur la même source (absorbe workaround Livrables)."
+        },
+        "hollow_point": {
+          "type": ["object", "null"],
+          "properties": {
+            "enabled": { "type": "boolean", "default": false },
+            "stroke_color_from_field": { "type": "string" },
+            "radius": { "type": "number", "minimum": 0, "default": 7 }
+          },
+          "additionalProperties": false,
+          "description": "Point creux pour features approximatives (absorbe workaround Livrables addPoints)."
+        },
+        "maplibre_paint_override": {
+          "type": ["object", "null"],
+          "additionalProperties": true,
+          "description": "Passthrough MapLibre setPaintProperty pour props avancées non-couvertes par classification."
+        }
+      },
+      "additionalProperties": true
+    },
+
+    "Opacity": {
+      "description": "Opacité statique ou réactive (bindée sur événement geo:bind).",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["kind", "value"],
+          "properties": {
+            "kind": { "const": "static" },
+            "value": { "type": "number", "minimum": 0, "maximum": 1 }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["kind", "prop", "matched", "before", "after"],
+          "properties": {
+            "kind": { "const": "reactive" },
+            "prop": { "type": "string", "description": "Event geo:bind prop (time, scenario, filter, ...)." },
+            "matched": { "type": "number", "minimum": 0, "maximum": 1 },
+            "before": { "type": "number", "minimum": 0, "maximum": 1 },
+            "after": { "type": "number", "minimum": 0, "maximum": 1 },
+            "null_value": { "type": "number", "minimum": 0, "maximum": 1 }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+
+    "Classification": {
+      "type": "object",
+      "properties": {
+        "color": { "$ref": "#/$defs/ColorClassification" },
+        "size": { "$ref": "#/$defs/SizeClassification" },
+        "model": { "$ref": "#/$defs/ModelClassification" },
+        "label": {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean", "default": false },
+            "field": { "type": ["string", "null"] }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": true
+    },
+
+    "ColorClassification": {
+      "description": "Discriminated union sur 'mode'. Voir §4.4 CONTRACT-V0.3.1.md pour combinaisons valides.",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["mode", "value"],
+          "properties": {
+            "mode": { "const": "single" },
+            "value": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
+            "default": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["mode", "field", "categories", "default"],
+          "properties": {
+            "mode": { "const": "categorized" },
+            "field": { "type": "string" },
+            "categories": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["value", "color"],
+                "properties": {
+                  "value": { "type": ["string", "number", "boolean", "null"] },
+                  "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
+                  "count": { "type": "integer", "minimum": 0 }
+                },
+                "additionalProperties": false
+              }
+            },
+            "default": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["mode", "field", "method", "breaks", "palette", "default"],
+          "properties": {
+            "mode": { "const": "graduated" },
+            "field": { "type": "string" },
+            "method": {
+              "description": "Méthode. INPUT agent : single/categorized/manual/linear. COMPUTED producteur : + jenks/quantile/equal_interval/log/sqrt (pré-calculés en 'manual').",
+              "enum": ["linear", "log", "sqrt", "jenks", "quantile", "equal_interval", "manual"]
+            },
+            "breaks": {
+              "type": "array",
+              "items": { "type": "number" },
+              "minItems": 1,
+              "description": "Bornes intérieures. N breaks = N+1 classes."
+            },
+            "palette": { "type": "string", "description": "Nom palette (voir §4.3 CONTRACT-V0.3.1.md)." },
+            "default": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
+            "_compiled_expression": {
+              "description": "MapLibre expression compilée. Source de vérité rendu. readOnly (généré producteur).",
+              "type": "array",
+              "readOnly": true
+            }
+          },
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "required": ["mode", "expr"],
+          "properties": {
+            "mode": { "const": "expression" },
+            "expr": {
+              "type": "array",
+              "description": "MapLibre expression brute passthrough (non-portable renderers non-MapLibre)."
+            },
+            "default": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+
+    "SizeClassification": {
+      "description": "Discriminated union sur 'mode' pour size (cercles proportionnels, extrusion, ...).",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["mode", "value"],
+          "properties": {
+            "mode": { "const": "single" },
+            "value": { "type": "number", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["mode", "field", "output_range"],
+          "properties": {
+            "mode": { "const": "graduated" },
+            "field": { "type": "string" },
+            "output_range": {
+              "type": "array",
+              "items": { "type": "number", "minimum": 0 },
+              "minItems": 2,
+              "maxItems": 2
+            },
+            "method": { "enum": ["linear", "log", "sqrt"], "default": "linear" }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+
+    "ModelClassification": {
+      "description": "Discriminated union pour choix modèle 3D (Atlas).",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["mode"],
+          "properties": {
+            "mode": { "const": "single" },
+            "value": { "type": ["string", "null"], "description": "modelId ou null." }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["mode", "field", "categories", "default_model_id"],
+          "properties": {
+            "mode": { "const": "categorized" },
+            "field": { "type": "string" },
+            "categories": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["value", "model_id"],
+                "properties": {
+                  "value": { "type": ["string", "number", "boolean"] },
+                  "model_id": { "type": "string" }
+                },
+                "additionalProperties": false
+              }
+            },
+            "default_model_id": { "type": ["string", "null"] }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+
+    "Interactions": {
+      "type": "object",
+      "properties": {
+        "popup_template": {
+          "type": ["object", "null"],
+          "required": ["kind", "body"],
+          "properties": {
+            "kind": { "enum": ["handlebars", "html"] },
+            "body": { "type": "string", "maxLength": 4000 }
+          },
+          "additionalProperties": false
+        },
+        "tooltip_field": { "type": ["string", "null"] },
+        "hover_attributes": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "emits_events": {
+          "type": "boolean",
+          "default": true,
+          "description": "Si true, émet geo:feature-click/hover canoniques. Noms d'événements fixés par la lib (voir §4.5)."
+        },
+        "feature_state_selected_field": {
+          "type": ["string", "null"],
+          "description": "Attribut identifiant pour setFeatureState('selected') MapLibre (bidirectionnel Grist bridge)."
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "CustomLayer": {
+      "type": "object",
+      "required": ["id", "kind", "adapter"],
+      "properties": {
+        "id": { "type": "string" },
+        "kind": {
+          "description": "Type sémantique du contenu (renderer neutre). Enum ouverte.",
+          "oneOf": [
+            { "const": "gltf_instances", "title": "Instances de modèles GLTF (Atlas mobilier urbain)." },
+            { "const": "custom_3d_layer", "title": "Custom layer 3D générique (SURFAC²E éditeur volumes)." },
+            { "type": "string", "pattern": "^x_[a-z_]+$", "title": "Extension custom layer nommée par projet." }
+          ]
+        },
+        "adapter": {
+          "description": "Adapter registre ADAPTERS de la lib (chargé à la demande).",
+          "oneOf": [
+            { "const": "geo-3d-scene", "title": "Adapter Three.js custom layer standard." },
+            { "type": "string", "pattern": "^x_[a-z_]+$" }
+          ]
+        },
+        "source_layer_id": {
+          "type": "string",
+          "description": "Référence un layers[].id porteur des features instances (P0-K, évite instances[] inline)."
+        },
+        "params": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Params spécifiques adapter (gltf_base_url, shadow_map, ...)."
+        },
+        "extensions": {
+          "type": "object",
+          "patternProperties": { "^[a-z][a-z_0-9]*$": { "type": "object", "additionalProperties": true } },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "Legend": {
+      "description": "Légende. Discriminated union sur 'mode'.",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["mode", "from_layer"],
+          "properties": {
+            "mode": { "const": "auto" },
+            "from_layer": { "type": "string", "description": "layers[].id source de la classification." },
+            "position": { "$ref": "#/$defs/OverlayPosition" },
+            "format": { "$ref": "#/$defs/LegendFormat" },
+            "title": { "type": "string", "maxLength": 200 }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["mode", "items"],
+          "properties": {
+            "mode": { "const": "manual" },
+            "items": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["label"],
+                "properties": {
+                  "label": { "type": "string" },
+                  "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
+                  "count": { "type": "integer", "minimum": 0 },
+                  "size": { "type": "number", "minimum": 0 },
+                  "layer": { "type": "string" }
+                },
+                "additionalProperties": false
+              }
+            },
+            "position": { "$ref": "#/$defs/OverlayPosition" },
+            "format": { "$ref": "#/$defs/LegendFormat" },
+            "title": { "type": "string", "maxLength": 200 }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+
+    "LegendFormat": {
+      "enum": ["chips", "gradient_bar", "proportional"],
+      "default": "chips"
+    },
+
+    "OverlayPosition": {
+      "enum": ["top-left", "top-right", "bottom-left", "bottom-right", "bottom", "right", "floating"],
+      "default": "bottom-left"
+    },
+
+    "Counter": {
+      "type": "object",
+      "required": ["id", "bind", "expr", "template"],
+      "properties": {
+        "id": { "type": "string" },
+        "bind": {
+          "description": "Source de mise à jour du compteur. Enum ouverte.",
+          "oneOf": [
+            { "const": "time", "title": "Binding geo:bind prop=time (timeline)." },
+            { "const": "scenario", "title": "Binding geo:bind prop=scenario." },
+            { "const": "filter", "title": "Après setFilter." },
+            { "const": "selection", "title": "Après setSelection." },
+            { "type": "string", "pattern": "^x_[a-z_]+$" }
+          ]
+        },
+        "expr": {
+          "description": "Expression du compteur.",
+          "oneOf": [
+            { "const": "filtered_count", "title": "Nb features actuellement rendues (après filter)." },
+            { "const": "total", "title": "Nb features total." },
+            { "const": "percentage", "title": "Pourcentage filtré/total." },
+            { "type": "string", "pattern": "^x_[a-z_]+$" }
+          ]
+        },
+        "template": { "type": "string", "description": "Template Handlebars avec vars {{count}}, {{total}}, {{pct}}." },
+        "position": { "$ref": "#/$defs/OverlayPosition" }
+      },
+      "additionalProperties": false
+    }
+  }
+}