From acaa876b677c75d5b6f0b23bf6559cfd61c99796 Mon Sep 17 00:00:00 2001
From: amit-spatial <amit.kumar@gramvaani.org>
Date: Tue, 21 Jul 2026 23:30:40 +0000
Subject: [PATCH 1/9] added GeoLibre v2.2 integration

---
 src/components/geolibre/GeoLibreFrame.jsx     | 214 +++++
 .../geolibre/GeoLibreFrame.test.jsx           |  73 ++
 src/components/geolibre/README.md             | 143 ++++
 src/components/geolibre/geolibreProject.js    | 746 ++++++++++++++++++
 .../geolibre/geolibreProject.test.js          | 200 +++++
 src/config/geolibre.config.js                 |  88 +++
 src/config/geolibre.config.test.js            |  48 ++
 src/config/geolibreLayers.js                  | 330 ++++++++
 src/pages/LE_homepage.jsx                     |  21 +-
 src/pages/LandscapeExplorer.jsx               | 545 +++----------
 10 files changed, 1967 insertions(+), 441 deletions(-)
 create mode 100644 src/components/geolibre/GeoLibreFrame.jsx
 create mode 100644 src/components/geolibre/GeoLibreFrame.test.jsx
 create mode 100644 src/components/geolibre/README.md
 create mode 100644 src/components/geolibre/geolibreProject.js
 create mode 100644 src/components/geolibre/geolibreProject.test.js
 create mode 100644 src/config/geolibre.config.js
 create mode 100644 src/config/geolibre.config.test.js
 create mode 100644 src/config/geolibreLayers.js

diff --git a/src/components/geolibre/GeoLibreFrame.jsx b/src/components/geolibre/GeoLibreFrame.jsx
new file mode 100644
index 00000000..91447862
--- /dev/null
+++ b/src/components/geolibre/GeoLibreFrame.jsx
@@ -0,0 +1,214 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import {
+  GEOLIBRE_CONFIG,
+  geoLibreVersionStatus,
+  resolveGeoLibreViewer,
+} from "../../config/geolibre.config";
+
+const GeoLibreFrame = ({
+  project,
+  preparationMessage,
+  preparationError,
+  warning,
+  onRetry,
+}) => {
+  const frameRef = useRef(null);
+  const fitTimerRef = useRef(null);
+  const sentProjectRef = useRef(null);
+  const sequenceRef = useRef(0);
+  const [viewerState, setViewerState] = useState("loading");
+  const [viewerError, setViewerError] = useState("");
+  const [readyGeneration, setReadyGeneration] = useState(0);
+
+  const viewer = useMemo(() => {
+    try {
+      return { ...resolveGeoLibreViewer(), error: "" };
+    } catch (error) {
+      return {
+        url: "",
+        origin: "",
+        error:
+          error instanceof Error
+            ? error.message
+            : "The configured GeoLibre URL is invalid.",
+      };
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!viewer.url) return undefined;
+    const frame = frameRef.current;
+    if (!frame) return undefined;
+
+    let handshakeTimer = window.setTimeout(() => {
+      setViewerError(
+        `GeoLibre ${GEOLIBRE_CONFIG.version} did not complete its iframe handshake. Check the configured viewer URL and browser console.`
+      );
+      setViewerState("error");
+    }, 90000);
+
+    const handleMessage = (event) => {
+      if (
+        event.origin !== viewer.origin ||
+        event.source !== frame.contentWindow ||
+        !event.data ||
+        typeof event.data !== "object"
+      ) {
+        return;
+      }
+
+      if (event.data.type === "geolibre:ready") {
+        window.clearTimeout(handshakeTimer);
+        handshakeTimer = null;
+        const status = geoLibreVersionStatus(event.data.version);
+        if (!status.compatible) {
+          setViewerError(status.message);
+          setViewerState("error");
+          return;
+        }
+        sentProjectRef.current = null;
+        setViewerError("");
+        setViewerState("ready");
+        setReadyGeneration((generation) => generation + 1);
+        return;
+      }
+
+      if (event.data.type === "geolibre:error") {
+        setViewerError(
+          event.data.message || "GeoLibre could not load the generated project."
+        );
+        setViewerState("error");
+      }
+    };
+
+    window.addEventListener("message", handleMessage);
+    return () => {
+      window.removeEventListener("message", handleMessage);
+      if (handshakeTimer !== null) window.clearTimeout(handshakeTimer);
+    };
+  }, [viewer.origin, viewer.url]);
+
+  useEffect(
+    () => () => {
+      if (fitTimerRef.current !== null) {
+        window.clearTimeout(fitTimerRef.current);
+      }
+    },
+    []
+  );
+
+  useEffect(() => {
+    const target = frameRef.current?.contentWindow;
+    if (
+      !target ||
+      !project ||
+      !["ready", "loaded"].includes(viewerState) ||
+      sentProjectRef.current === project
+    ) {
+      return;
+    }
+
+    sequenceRef.current += 1;
+    const sequence = sequenceRef.current;
+    target.postMessage(
+      {
+        type: "geolibre:load-project",
+        project,
+        seq: sequence,
+      },
+      viewer.origin
+    );
+    sentProjectRef.current = project;
+    if (fitTimerRef.current !== null) {
+      window.clearTimeout(fitTimerRef.current);
+    }
+    const bounds = project.mapView?.bbox;
+    if (Array.isArray(bounds) && bounds.length === 4) {
+      fitTimerRef.current = window.setTimeout(() => {
+        target.postMessage(
+          {
+            type: "geolibre:command",
+            requestId: `kyl-fit-bounds-${sequence}`,
+            method: "fitBounds",
+            params: { bounds },
+          },
+          viewer.origin
+        );
+        fitTimerRef.current = null;
+      }, 1500);
+    }
+    setViewerState("loaded");
+  }, [project, readyGeneration, viewer.origin, viewerState]);
+
+  const activeError = viewer.error || preparationError || viewerError;
+  const showProgress = !activeError && (!project || viewerState === "loading");
+
+  return (
+    <main className="relative min-h-0 flex-1 overflow-hidden bg-slate-100">
+      {viewer.url && (
+        <iframe
+          ref={frameRef}
+          src={viewer.url}
+          title="GeoLibre GIS workspace"
+          className="h-full w-full border-0 bg-white"
+          allow="fullscreen; clipboard-read; clipboard-write"
+          allowFullScreen
+          onLoad={() => setViewerState((current) =>
+            current === "loaded" ? current : "loading"
+          )}
+        />
+      )}
+
+      {(showProgress || activeError) && (
+        <div className="absolute inset-0 flex items-center justify-center bg-slate-950/35 p-5 backdrop-blur-[1px]">
+          <div
+            className="w-full max-w-md rounded-2xl bg-white p-6 text-center shadow-2xl"
+            role={activeError ? "alert" : "status"}
+          >
+            {activeError ? (
+              <>
+                <h1 className="text-lg font-semibold text-slate-900">
+                  GeoLibre could not be opened
+                </h1>
+                <p className="mt-2 text-sm leading-6 text-slate-600">
+                  {activeError}
+                </p>
+                {onRetry && (
+                  <button
+                    type="button"
+                    onClick={onRetry}
+                    className="mt-5 rounded-lg bg-purple-700 px-4 py-2 text-sm font-semibold text-white hover:bg-purple-800"
+                  >
+                    Try again
+                  </button>
+                )}
+              </>
+            ) : (
+              <>
+                <div className="mx-auto h-9 w-9 animate-spin rounded-full border-4 border-purple-100 border-t-purple-700" />
+                <h1 className="mt-4 text-base font-semibold text-slate-900">
+                  Preparing GeoLibre
+                </h1>
+                <p className="mt-1 text-sm text-slate-600">
+                  {preparationMessage ||
+                    `Starting GeoLibre ${GEOLIBRE_CONFIG.version}…`}
+                </p>
+              </>
+            )}
+          </div>
+        </div>
+      )}
+
+      {!activeError && warning && viewerState === "loaded" && (
+        <div
+          className="absolute bottom-4 left-1/2 max-w-[calc(100%-2rem)] -translate-x-1/2 rounded-lg border border-amber-300 bg-amber-50/95 px-4 py-2 text-sm text-amber-950 shadow-lg"
+          role="status"
+        >
+          {warning}
+        </div>
+      )}
+    </main>
+  );
+};
+
+export default GeoLibreFrame;
diff --git a/src/components/geolibre/GeoLibreFrame.test.jsx b/src/components/geolibre/GeoLibreFrame.test.jsx
new file mode 100644
index 00000000..48b0b455
--- /dev/null
+++ b/src/components/geolibre/GeoLibreFrame.test.jsx
@@ -0,0 +1,73 @@
+import { act, render, screen } from "@testing-library/react";
+import GeoLibreFrame from "./GeoLibreFrame";
+
+const project = {
+  version: "0.2.0",
+  name: "Lakhipur project",
+  mapView: {
+    center: [93.04, 24.84],
+    zoom: 9.6,
+    bearing: 0,
+    pitch: 0,
+    bbox: [92.91, 24.71, 93.17, 24.99],
+  },
+  layers: [],
+};
+
+const announceReady = (frame, version = "2.2.0") => {
+  window.dispatchEvent(
+    new MessageEvent("message", {
+      origin: "https://web.geolibre.app",
+      source: frame.contentWindow,
+      data: { type: "geolibre:ready", version },
+    })
+  );
+};
+
+describe("GeoLibre iframe bridge", () => {
+  beforeEach(() => jest.useFakeTimers());
+  afterEach(() => jest.useRealTimers());
+
+  it("loads the project and fits its bbox after a valid v2.2 handshake", () => {
+    render(<GeoLibreFrame project={project} />);
+    const frame = screen.getByTitle("GeoLibre GIS workspace");
+    const postMessage = jest.spyOn(frame.contentWindow, "postMessage");
+
+    act(() => announceReady(frame));
+
+    expect(postMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: "geolibre:load-project",
+        project,
+        seq: 1,
+      }),
+      "https://web.geolibre.app"
+    );
+
+    act(() => jest.advanceTimersByTime(1500));
+    expect(postMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: "geolibre:command",
+        method: "fitBounds",
+        params: { bounds: project.mapView.bbox },
+      }),
+      "https://web.geolibre.app"
+    );
+  });
+
+  it("does not send a project to an unexpected viewer version", () => {
+    render(<GeoLibreFrame project={project} />);
+    const frame = screen.getByTitle("GeoLibre GIS workspace");
+    const postMessage = jest.spyOn(frame.contentWindow, "postMessage");
+
+    act(() => announceReady(frame, "2.3.0"));
+
+    expect(screen.getByRole("alert").textContent).toMatch(
+      /configured for GeoLibre 2\.2\.0.*loaded 2\.3\.0/i
+    );
+    expect(postMessage).not.toHaveBeenCalledWith(
+      expect.objectContaining({ type: "geolibre:load-project" }),
+      expect.any(String)
+    );
+  });
+});
diff --git a/src/components/geolibre/README.md b/src/components/geolibre/README.md
new file mode 100644
index 00000000..c38e33a5
--- /dev/null
+++ b/src/components/geolibre/README.md
@@ -0,0 +1,143 @@
+# KYL GeoLibre integration
+
+`/download_layers` is a thin host for GeoLibre. KYL keeps its existing header
+(including **QGIS Documentation**) and gives the rest of the page to a trusted
+GeoLibre iframe. There is no second KYL map, layer selector, or project panel.
+
+The implementation targets
+[GeoLibre v2.2.0](https://github.com/opengeos/GeoLibre/releases/tag/v2.2.0)
+and uses its supported embed bridge and WFS project representation.
+
+## Runtime flow
+
+1. The KYL homepage carries the selected state, district, and tehsil to
+   `/download_layers` as query parameters.
+2. `geolibreProject.js` fetches the Socio-Economic WFS layer first and derives
+   the complete tehsil bounding box from its GeoJSON.
+3. It fetches MWS next, followed by the remaining vectors. Duplicate sources
+   (Socio-Economic / Administrative Boundary and MWS / Hydrological Boundary)
+   are fetched once and reused.
+4. Vector layers are represented exactly as GeoLibre 2.2 WFS layers: an
+   embedded `FeatureCollection`, a live `sourcePath`, and
+   `metadata.sourceKind = "wfs-getfeature"`.
+5. WMS layers are configured but hidden, so raster tiles are requested only
+   when a user makes a layer visible in GeoLibre.
+6. The iframe reports `geolibre:ready`; KYL verifies its application version
+   and sends one `geolibre:load-project` message. It then uses GeoLibre 2.2's
+   command bridge to fit the exact bounds against the iframe's real map size.
+
+Only **Socio-Economic Profile** starts visible. Every other layer starts hidden
+with opacity `1`, so turning it on in GeoLibre shows its intended styling rather
+than an invisible zero-opacity layer.
+
+## Native layer organization
+
+GeoLibre's own layer panel is ordered top-first as:
+
+1. Overview (Socio-Economic Profile, Administrative Boundaries)
+2. Watersheds (MWS and related hydrological layers)
+3. Other vector layers
+4. LULC Level 3, Level 2, and Level 1 by year
+5. Other raster layers
+
+The non-overview groups are collapsed where appropriate. Each LULC group shows
+2024-2025 first while retaining every available year back to 2017-2018.
+
+The project camera is calculated from the Socio-Economic geometry using a
+padded Web Mercator fit. `mapView.bbox` is also retained in project metadata,
+and the iframe receives a `fitBounds` command after loading, so the initial map
+contains the full tehsil rather than a generic India extent.
+
+## Version configuration
+
+The normal upgrade control is the `version` value in
+`../../config/geolibre.config.js`:
+
+```js
+export const GEOLIBRE_CONFIG = Object.freeze({
+  version: process.env.REACT_APP_GEOLIBRE_VERSION || "2.2.0",
+  supportedMajorVersion: 2,
+  // ...
+});
+```
+
+For a compatible GeoLibre 2.x release, change that one fallback value, or set:
+
+```dotenv
+REACT_APP_GEOLIBRE_VERSION=2.3.0
+```
+
+The hosted `https://web.geolibre.app/` URL follows GeoLibre's current web
+deployment; it is not an immutable versioned release asset. KYL therefore
+checks the version reported by the iframe and refuses to send data on a
+mismatch. For an exactly pinned self-hosted deployment, use a URL template:
+
+```dotenv
+REACT_APP_GEOLIBRE_URL_TEMPLATE=https://maps.example.org/geolibre/{version}/
+```
+
+`{version}` is replaced automatically. Set
+`REACT_APP_GEOLIBRE_STRICT_VERSION=false` only for deliberate compatibility
+testing of a newer GeoLibre 2.x viewer. A major-version update should update
+the compatibility rules and project/bridge tests, not just the version value.
+
+GeoLibre's application version (`2.2.0`) is separate from its project schema
+version (`0.2.0`). Do not change the project format merely when upgrading the
+application.
+
+## Files
+
+| File | Responsibility |
+|---|---|
+| `../../config/geolibre.config.js` | Viewer application version, URL resolution, strict handshake compatibility |
+| `../../config/geolibreLayers.js` | GeoServer names, all LULC years, QML references, WMS styles, load groups |
+| `geolibreProject.js` | Priority WFS fetching, v2.2 project construction, styles, WMS/WCS references, bbox camera |
+| `GeoLibreFrame.jsx` | Iframe lifecycle, trusted-origin bridge, version check, loading and failure overlays |
+| `../../pages/LandscapeExplorer.jsx` | Route-to-project orchestration; no duplicate map or layer UI |
+
+The current project contains 45 entries: 13 vector entries (11 distinct WFS
+requests), 24 LULC year/level rasters, and 8 other rasters.
+
+## Styling contract
+
+- Vector QML rules are translated into GeoLibre categorized or expression
+  styles. The source QML URL remains in `metadata.corestack.qmlStyleUrl`.
+- Raster QML styles are published as named GeoServer styles and rendered by
+  WMS. Their original QML URLs are also retained.
+- WCS GetCoverage URLs remain in raster metadata for data export workflows.
+
+Changing only a QML URL does not alter rendered vector symbology; update the
+matching style profile in `geolibreProject.js`. Raster appearance changes must
+be published to the named GeoServer WMS style.
+
+## Validation
+
+Focused tests:
+
+```bash
+CI=true npm test -- --watchAll=false \
+  src/config/geolibre.config.test.js \
+  src/components/geolibre/geolibreProject.test.js
+```
+
+Build:
+
+```bash
+npm run build
+```
+
+Local demo:
+
+```bash
+HOST=0.0.0.0 PORT=3000 BROWSER=none npm start
+```
+
+Open `http://localhost:3000`, select a state, district, and tehsil, and click
+**Download Layers**. The generated URL can be refreshed or shared on the same
+KYL host because it contains the selected location.
+
+For a release upgrade, verify all of the following before changing the default
+version: the ready handshake reports the expected release, the project loads
+without `geolibre:error`, Socio-Economic is the only visible layer, the full
+tehsil fits, hidden vectors can be enabled, WMS tiles appear when enabled, and
+GeoLibre can save/export the resulting project.
diff --git a/src/components/geolibre/geolibreProject.js b/src/components/geolibre/geolibreProject.js
new file mode 100644
index 00000000..cb4e34f3
--- /dev/null
+++ b/src/components/geolibre/geolibreProject.js
@@ -0,0 +1,746 @@
+import {
+  GEOLIBRE_CONFIG,
+  GEOLIBRE_PROJECT_FORMAT_VERSION,
+  resolveGeoLibreViewer,
+} from "../../config/geolibre.config";
+import {
+  GEOLIBRE_LAYERS,
+  GEOLIBRE_VECTOR_LAYERS,
+} from "../../config/geolibreLayers";
+
+const DEFAULT_GEOSERVER_URL =
+  "https://geoserver.core-stack.org:8443/geoserver/";
+const DEFAULT_BASEMAP_STYLE = "https://tiles.openfreemap.org/styles/liberty";
+const EMPTY_FEATURE_COLLECTION = Object.freeze({
+  type: "FeatureCollection",
+  features: [],
+});
+
+const BASE_STYLE = {
+  minZoom: 0,
+  maxZoom: 24,
+  fillColor: "#8b5cf6",
+  strokeColor: "#4c1d95",
+  strokeWidth: 1.5,
+  strokeWidthUnit: "pixels",
+  fillOpacity: 0.48,
+  circleRadius: 6,
+  vectorStyleMode: "single",
+  vectorStyleProperty: "",
+  vectorStyleClassCount: 1,
+  vectorStyleColorRamp: "viridis",
+  vectorStyleClassificationScheme: "unique-values",
+  vectorStyleStops: [],
+  vectorStyleExpression: "",
+  vectorRules: [],
+};
+
+const RASTER_STYLE = {
+  ...BASE_STYLE,
+  fillOpacity: 1,
+  rasterBrightnessMin: 0,
+  rasterBrightnessMax: 1,
+  rasterSaturation: 0,
+  rasterContrast: 0,
+  rasterHueRotate: 0,
+};
+
+const categoryStyle = (property, stops, overrides = {}) => ({
+  ...BASE_STYLE,
+  ...overrides,
+  vectorStyleMode: "categorized",
+  vectorStyleProperty: property,
+  vectorStyleClassCount: stops.length,
+  vectorStyleStops: stops.map(([value, color, label]) => ({
+    value,
+    color,
+    label,
+  })),
+});
+
+const expressionStyle = (expression, overrides = {}) => ({
+  ...BASE_STYLE,
+  ...overrides,
+  vectorStyleMode: "expression",
+  vectorStyleExpression: JSON.stringify(expression),
+});
+
+const numericProperty = (property, fallback = 0) => [
+  "to-number",
+  ["get", property],
+  fallback,
+];
+
+const croppingIntensityAverage = [
+  "/",
+  [
+    "+",
+    ...Array.from({ length: 8 }, (_, index) =>
+      numericProperty(`cropping_intensity_${2017 + index}`)
+    ),
+  ],
+  8,
+];
+
+const droughtOccurrences = (year, category) => [
+  "-",
+  [
+    "length",
+    ["split", ["to-string", ["get", `drlb_${year}`]], String(category)],
+  ],
+  1,
+];
+
+const droughtYearFlag = (year) => [
+  "case",
+  [
+    ">=",
+    ["+", droughtOccurrences(year, 2), droughtOccurrences(year, 3)],
+    5,
+  ],
+  1,
+  0,
+];
+
+const droughtYearCount = [
+  "+",
+  ...Array.from({ length: 8 }, (_, index) => droughtYearFlag(2017 + index)),
+];
+
+const STYLE_PROFILES = {
+  boundary: {
+    ...BASE_STYLE,
+    fillColor: "#ffffff",
+    fillOpacity: 0,
+    strokeColor: "#111827",
+    strokeWidth: 1.5,
+  },
+  demographics: expressionStyle(
+    [
+      "step",
+      [
+        "*",
+        [
+          "/",
+          numericProperty("P_LIT"),
+          ["max", numericProperty("TOT_P", 1), 1],
+        ],
+        100,
+      ],
+      "#98fb98",
+      46,
+      "#32cd32",
+      59,
+      "#228b22",
+      70,
+      "#006400",
+    ],
+    { fillColor: "#98fb98", strokeColor: "#111827", fillOpacity: 0.65 }
+  ),
+  terrain_vector: categoryStyle(
+    "terrainClu",
+    [
+      ["0", "#324a1c", "Broad Sloppy and Hilly"],
+      ["1", "#97c76b", "Mostly Plains"],
+      ["2", "#673a13", "Mostly Hills and Valleys"],
+      ["3", "#e5e059", "Broad Plains and Slopes"],
+    ],
+    { fillColor: "#e5e059", strokeColor: "#232323", fillOpacity: 0.75 }
+  ),
+  mws: expressionStyle(
+    [
+      "step",
+      numericProperty("Net2018_23"),
+      "#ff0000",
+      -5,
+      "#ffff00",
+      -1,
+      "#25b63c",
+      1,
+      "#1017f8",
+    ],
+    { fillColor: "#25b63c", strokeColor: "#232323", fillOpacity: 0.55 }
+  ),
+  drainage: categoryStyle(
+    "ORDER",
+    [
+      ["1", "#03045e", "Stream order 1"],
+      ["2", "#023e8a", "Stream order 2"],
+      ["3", "#0077b6", "Stream order 3"],
+      ["4", "#0096c7", "Stream order 4"],
+      ["5", "#00b4d8", "Stream order 5"],
+      ["6", "#48cae4", "Stream order 6"],
+      ["7", "#90e0ef", "Stream order 7"],
+      ["8", "#ade8f4", "Stream order 8"],
+    ],
+    { fillColor: "#03045e", strokeColor: "#03045e", strokeWidth: 2 }
+  ),
+  waterbodies: {
+    ...BASE_STYLE,
+    fillColor: "#6495ed",
+    fillOpacity: 0.5,
+    strokeColor: "#2563eb",
+    strokeWidth: 2,
+  },
+  soge: categoryStyle(
+    "class",
+    [
+      ["Safe", "#ffffff", "Safe"],
+      ["Semi-critical", "#e0f3f8", "Semi-critical"],
+      ["Critical", "#4575b4", "Critical"],
+      ["Over Exploited", "#313695", "Over Exploited"],
+    ],
+    { fillColor: "#9ca3af", strokeColor: "#232323", fillOpacity: 0.72 }
+  ),
+  aquifer: categoryStyle(
+    "Principal_",
+    [
+      ["Alluvium", "#fffdb5", "Alluvium"],
+      ["Laterite", "#f3a425", "Laterite"],
+      ["Basalt", "#99ecf1", "Basalt"],
+      ["Sandstone", "#a5f8c5", "Sandstone"],
+      ["Shale", "#f57c99", "Shale"],
+      ["Limestone", "#e8d52e", "Limestone"],
+      ["Granite", "#3c92f2", "Granite"],
+      ["Schist", "#d5db21", "Schist"],
+      ["Quartzite", "#cf7ff4", "Quartzite"],
+      ["Charnockite", "#f4dbff", "Charnockite"],
+      ["Khondalite", "#50c02b", "Khondalite"],
+      ["Banded Gneissic Complex", "#ffe1b5", "Banded Gneissic Complex"],
+      ["Gneiss", "#e4cff1", "Gneiss"],
+      ["Intrusive", "#57d2ff", "Intrusive"],
+    ],
+    { fillColor: "#57d2ff", strokeColor: "#232323", fillOpacity: 0.72 }
+  ),
+  cropping_intensity: expressionStyle(
+    [
+      "step",
+      croppingIntensityAverage,
+      "#ff9371",
+      1,
+      "#ffa500",
+      2,
+      "#bad93e",
+    ],
+    { fillColor: "#ffa500", strokeColor: "#232323", fillOpacity: 0.7 }
+  ),
+  drought: expressionStyle(
+    [
+      "step",
+      droughtYearCount,
+      "#f4d03f",
+      1,
+      "#eb984e",
+      2,
+      "#e74c3c",
+    ],
+    { fillColor: "#eb984e", strokeColor: "#232323", fillOpacity: 0.5 }
+  ),
+  nrega: categoryStyle(
+    "WorkCatego",
+    [
+      ["Agri Impact - HH,  Community", "#ffa500", "Land restoration"],
+      ["Household Livelihood", "#c2678d", "Off-farm livelihood assets"],
+      ["Irrigation - Site level impact", "#1a759f", "Irrigation on farms"],
+      ["Others - HH, Community", "#355070", "Community assets"],
+      ["Plantation", "#52b69a", "Plantations"],
+      [
+        "SWC - Landscape level impact",
+        "#6495ed",
+        "Soil and Water conservation",
+      ],
+      ["Un Identified", "#6d597a", "Unidentified"],
+    ],
+    {
+      fillColor: "#6d597a",
+      strokeColor: "#ffffff",
+      fillOpacity: 0.9,
+      circleRadius: 6,
+    }
+  ),
+};
+
+const GROUPS_TOP_FIRST = [
+  { id: "overview", name: "Overview", collapsed: false },
+  { id: "watersheds", name: "Watersheds", collapsed: false },
+  { id: "vectors", name: "Other vector layers", collapsed: true },
+  { id: "lulc-3", name: "LULC Level 3 by year", collapsed: true },
+  { id: "lulc-2", name: "LULC Level 2 by year", collapsed: true },
+  { id: "lulc-1", name: "LULC Level 1 by year", collapsed: true },
+  { id: "rasters", name: "Other raster layers", collapsed: true },
+];
+
+const projectPreferences = {
+  map: {
+    restrictBounds: false,
+    bounds: [-180, -85, 180, 85],
+    minZoom: 0,
+    maxZoom: 24,
+    maxPitch: 85,
+    renderWorldCopies: true,
+    projection: "globe",
+    ellipsoidId: "earth",
+    scaleUnit: "metric",
+  },
+  environmentVariables: [],
+  geocoding: { providerId: "nominatim", apiKeys: {} },
+};
+
+const normalizeBaseUrl = (url) => `${url.replace(/\/+$/, "")}/`;
+
+export const formatGeoServerName = (value) =>
+  String(value || "")
+    .replace(/[()]/g, "")
+    .replace(/\s+/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_|_$/g, "")
+    .toLowerCase();
+
+const appendQuery = (endpoint, entries) => {
+  const separator = endpoint.includes("?")
+    ? endpoint.endsWith("?") || endpoint.endsWith("&")
+      ? ""
+      : "&"
+    : "?";
+  const query = entries
+    .map(([key, value]) => {
+      const encodedValue =
+        value === "{bbox-epsg-3857}" ? value : encodeURIComponent(value);
+      return `${encodeURIComponent(key)}=${encodedValue}`;
+    })
+    .join("&");
+  return `${endpoint}${separator}${query}`;
+};
+
+const buildWfsRequest = (baseUrl, layer, layerName) => {
+  const endpoint = `${baseUrl}${layer.workspace}/ows`;
+  const typeName = `${layer.workspace}:${layerName}`;
+  return {
+    endpoint,
+    typeName,
+    version: "1.0.0",
+    outputFormat: "application/json",
+    srsName: "EPSG:4326",
+    url: appendQuery(endpoint, [
+      ["service", "WFS"],
+      ["version", "1.0.0"],
+      ["request", "GetFeature"],
+      ["typeName", typeName],
+      ["outputFormat", "application/json"],
+      ["srsName", "EPSG:4326"],
+    ]),
+  };
+};
+
+const buildWmsSource = (baseUrl, layer, layerName, bounds) => {
+  const endpoint = `${baseUrl}${layer.workspace}/wms`;
+  const qualifiedName = `${layer.workspace}:${layerName}`;
+  const source = {
+    type: "raster",
+    tiles: [
+      appendQuery(endpoint, [
+        ["SERVICE", "WMS"],
+        ["REQUEST", "GetMap"],
+        ["VERSION", "1.1.1"],
+        ["LAYERS", qualifiedName],
+        ["STYLES", layer.wmsStyle || ""],
+        ["FORMAT", "image/png"],
+        ["TRANSPARENT", "TRUE"],
+        ["SRS", "EPSG:3857"],
+        ["BBOX", "{bbox-epsg-3857}"],
+        ["WIDTH", "256"],
+        ["HEIGHT", "256"],
+      ]),
+    ],
+    tileSize: 256,
+    url: endpoint,
+    layers: qualifiedName,
+    styles: layer.wmsStyle || "",
+    format: "image/png",
+    transparent: true,
+    version: "1.1.1",
+  };
+  if (bounds) source.bounds = bounds;
+  return source;
+};
+
+const buildWcsUrl = (baseUrl, layer, layerName) =>
+  appendQuery(`${baseUrl}${layer.workspace}/wcs`, [
+    ["service", "WCS"],
+    ["version", "2.0.1"],
+    ["request", "GetCoverage"],
+    ["CoverageId", `${layer.workspace}:${layerName}`],
+    ["format", "geotiff"],
+    ["compression", "LZW"],
+  ]);
+
+const validBounds = (bounds) =>
+  Array.isArray(bounds) &&
+  bounds.length === 4 &&
+  bounds.every(Number.isFinite) &&
+  bounds[0] < bounds[2] &&
+  bounds[1] < bounds[3];
+
+export const geoJsonBounds = (featureCollection) => {
+  if (validBounds(featureCollection?.bbox)) {
+    return featureCollection.bbox.map(Number);
+  }
+
+  const bounds = [Infinity, Infinity, -Infinity, -Infinity];
+  const visitCoordinates = (coordinates) => {
+    if (!Array.isArray(coordinates)) return;
+    if (
+      coordinates.length >= 2 &&
+      Number.isFinite(Number(coordinates[0])) &&
+      Number.isFinite(Number(coordinates[1]))
+    ) {
+      const longitude = Number(coordinates[0]);
+      const latitude = Number(coordinates[1]);
+      bounds[0] = Math.min(bounds[0], longitude);
+      bounds[1] = Math.min(bounds[1], latitude);
+      bounds[2] = Math.max(bounds[2], longitude);
+      bounds[3] = Math.max(bounds[3], latitude);
+      return;
+    }
+    coordinates.forEach(visitCoordinates);
+  };
+
+  for (const feature of featureCollection?.features || []) {
+    const geometry = feature?.geometry;
+    if (geometry?.type === "GeometryCollection") {
+      geometry.geometries?.forEach((item) => visitCoordinates(item.coordinates));
+    } else {
+      visitCoordinates(geometry?.coordinates);
+    }
+  }
+
+  return validBounds(bounds) ? bounds : null;
+};
+
+const mercatorY = (latitude) => {
+  const clamped = Math.max(-85.051129, Math.min(85.051129, latitude));
+  const radians = (clamped * Math.PI) / 180;
+  return (
+    (1 -
+      Math.log(Math.tan(radians) + 1 / Math.cos(radians)) / Math.PI) /
+    2
+  );
+};
+
+export const mapViewFromBounds = (
+  bounds,
+  { width = 1100, height = 720, padding = 72 } = {}
+) => {
+  if (!validBounds(bounds)) {
+    throw new Error("A valid [west, south, east, north] extent is required.");
+  }
+  const [west, south, east, north] = bounds.map(Number);
+  const longitudeFraction = Math.max((east - west) / 360, 1e-9);
+  const latitudeFraction = Math.max(
+    Math.abs(mercatorY(north) - mercatorY(south)),
+    1e-9
+  );
+  const usableWidth = Math.max(width - padding * 2, 256);
+  const usableHeight = Math.max(height - padding * 2, 256);
+  const zoom = Math.min(
+    Math.log2(usableWidth / 256 / longitudeFraction),
+    Math.log2(usableHeight / 256 / latitudeFraction)
+  );
+
+  return {
+    center: [(west + east) / 2, (south + north) / 2],
+    zoom: Math.max(3, Math.min(16, Math.floor((zoom - 0.2) * 10) / 10)),
+    bearing: 0,
+    pitch: 0,
+    bbox: [west, south, east, north],
+  };
+};
+
+const isFeatureCollection = (value) =>
+  value?.type === "FeatureCollection" && Array.isArray(value.features);
+
+export const fetchWfsFeatureCollection = async (request, { signal } = {}) => {
+  const response = await fetch(request.url, {
+    signal,
+    headers: { Accept: "application/geo+json, application/json" },
+  });
+  if (!response.ok) {
+    throw new Error(`WFS request failed with HTTP ${response.status}.`);
+  }
+
+  let data;
+  try {
+    data = await response.json();
+  } catch (_error) {
+    throw new Error("WFS returned a response that was not JSON.");
+  }
+  if (!isFeatureCollection(data)) {
+    throw new Error("WFS response is not a GeoJSON FeatureCollection.");
+  }
+  return data;
+};
+
+const layerStyle = (layer) =>
+  layer.sourceType === "wms"
+    ? { ...RASTER_STYLE }
+    : { ...(STYLE_PROFILES[layer.styleProfile] || BASE_STYLE) };
+
+const coreStackMetadata = (layer, layerName, sourceUrl) => ({
+  domain: layer.domain,
+  geoserverWorkspace: layer.workspace,
+  geoserverLayer: layerName,
+  sourceType: layer.sourceType,
+  liveSource: sourceUrl,
+  qmlStyleUrl: layer.qmlStyleUrl,
+  year: layer.year || null,
+  styleContract:
+    layer.sourceType === "wms"
+      ? "GeoServer renders the named style published from the CoRE Stack QGIS style catalog."
+      : "The QGIS QML symbology is represented as a GeoLibre vector style.",
+});
+
+const buildVectorLayer = ({
+  catalogLayer,
+  layerName,
+  request,
+  data,
+  failure,
+}) => {
+  const style = layerStyle(catalogLayer);
+  return {
+    id: `corestack-${catalogLayer.id}`,
+    name: catalogLayer.label,
+    type: "geojson",
+    source: {
+      type: "geojson",
+      url: request.url,
+      service: "wfs",
+      typeName: request.typeName,
+      version: request.version,
+      outputFormat: request.outputFormat,
+      srsName: request.srsName,
+    },
+    visible: catalogLayer.id === "demographics",
+    opacity: 1,
+    style,
+    metadata: {
+      featureCount: data.features.length,
+      service: "wfs",
+      sourceKind: "wfs-getfeature",
+      typeName: request.typeName,
+      ...(failure ? { initialLoadError: failure.message } : {}),
+      corestack: coreStackMetadata(catalogLayer, layerName, request.url),
+    },
+    geojson: data,
+    sourcePath: request.url,
+    groupId: catalogLayer.loadGroup,
+  };
+};
+
+const buildRasterLayer = ({ catalogLayer, layerName, baseUrl, bounds }) => {
+  const source = buildWmsSource(baseUrl, catalogLayer, layerName, bounds);
+  const wcsDownloadUrl = buildWcsUrl(baseUrl, catalogLayer, layerName);
+  const style = layerStyle(catalogLayer);
+  return {
+    id: `corestack-${catalogLayer.id}`,
+    name: catalogLayer.label,
+    type: "wms",
+    source,
+    visible: false,
+    opacity: 1,
+    style,
+    metadata: {
+      service: "wms",
+      corestack: {
+        ...coreStackMetadata(catalogLayer, layerName, source.url),
+        wcsDownloadUrl,
+      },
+    },
+    sourcePath: source.url,
+    groupId: catalogLayer.loadGroup,
+  };
+};
+
+const displayOrderForGroup = (groupId, layers) => {
+  const matching = layers.filter((layer) => layer.groupId === groupId);
+  return groupId.startsWith("lulc-") ? [...matching].reverse() : matching;
+};
+
+export const orderGeoLibreLayers = (layers) => {
+  const topFirst = GROUPS_TOP_FIRST.flatMap((group) =>
+    displayOrderForGroup(group.id, layers)
+  );
+  return topFirst.reverse();
+};
+
+const readableError = (error) =>
+  error instanceof Error ? error.message : String(error);
+
+export const buildGeoLibreProject = async ({
+  state,
+  district,
+  tehsil,
+  viewport,
+  geoserverUrl = process.env.REACT_APP_GEOSERVER_URL || DEFAULT_GEOSERVER_URL,
+  signal,
+  onProgress = () => {},
+  fetchFeatureCollection = fetchWfsFeatureCollection,
+}) => {
+  if (!state || !district || !tehsil) {
+    throw new Error("Select a state, district, and tehsil first.");
+  }
+
+  const baseUrl = normalizeBaseUrl(geoserverUrl);
+  const scope = {
+    district: formatGeoServerName(district),
+    tehsil: formatGeoServerName(tehsil),
+  };
+  const requestCache = new Map();
+  const vectorResults = new Map();
+  const failures = [];
+
+  const requestFor = (catalogLayer) => {
+    const layerName = catalogLayer.layerName(scope);
+    return {
+      layerName,
+      request: buildWfsRequest(baseUrl, catalogLayer, layerName),
+    };
+  };
+
+  const loadVector = async (
+    catalogLayer,
+    required = false,
+    reportProgress = true
+  ) => {
+    const { layerName, request } = requestFor(catalogLayer);
+    if (reportProgress) {
+      onProgress({
+        phase: catalogLayer.id,
+        message: `Loading ${catalogLayer.label}…`,
+      });
+    }
+
+    if (!requestCache.has(request.url)) {
+      requestCache.set(
+        request.url,
+        fetchFeatureCollection(request, { signal })
+      );
+    }
+
+    try {
+      const data = await requestCache.get(request.url);
+      vectorResults.set(catalogLayer.id, { data, layerName, request });
+      return data;
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      const failure = {
+        layerId: catalogLayer.id,
+        layerName: catalogLayer.label,
+        sourceUrl: request.url,
+        message: readableError(error),
+      };
+      if (required) {
+        throw new Error(
+          `Could not load the Socio-Economic Profile needed to locate ${tehsil}: ${failure.message}`
+        );
+      }
+      failures.push(failure);
+      vectorResults.set(catalogLayer.id, {
+        data: EMPTY_FEATURE_COLLECTION,
+        layerName,
+        request,
+        failure,
+      });
+      return EMPTY_FEATURE_COLLECTION;
+    }
+  };
+
+  const socioeconomic = GEOLIBRE_VECTOR_LAYERS.find(
+    (layer) => layer.id === "demographics"
+  );
+  const mws = GEOLIBRE_VECTOR_LAYERS.find((layer) => layer.id === "mws_layers");
+
+  const socioeconomicData = await loadVector(socioeconomic, true);
+  const bounds = geoJsonBounds(socioeconomicData);
+  if (!bounds) {
+    throw new Error(
+      `The Socio-Economic Profile for ${tehsil} has no usable geographic extent.`
+    );
+  }
+
+  await loadVector(mws);
+  const remainingVectors = GEOLIBRE_VECTOR_LAYERS.filter(
+    (layer) => layer.id !== socioeconomic.id && layer.id !== mws.id
+  );
+  onProgress({
+    phase: "vectors",
+    message: `Loading ${remainingVectors.length} supporting vector layers…`,
+  });
+  await Promise.all(
+    remainingVectors.map((layer) => loadVector(layer, false, false))
+  );
+
+  onProgress({ phase: "project", message: "Preparing the GeoLibre project…" });
+  const layers = GEOLIBRE_LAYERS.map((catalogLayer) => {
+    const layerName = catalogLayer.layerName(scope);
+    if (catalogLayer.sourceType === "wfs") {
+      return buildVectorLayer({
+        catalogLayer,
+        layerName,
+        ...vectorResults.get(catalogLayer.id),
+      });
+    }
+    return buildRasterLayer({ catalogLayer, layerName, baseUrl, bounds });
+  });
+  const orderedLayers = orderGeoLibreLayers(layers);
+  const styles = Object.fromEntries(
+    orderedLayers.map((layer) => [layer.id, layer.style])
+  );
+  const viewer = resolveGeoLibreViewer();
+
+  return {
+    version: GEOLIBRE_PROJECT_FORMAT_VERSION,
+    name: `${tehsil}, ${district}: CoRE Stack landscape`,
+    mapView: mapViewFromBounds(bounds, viewport),
+    basemapStyleUrl: DEFAULT_BASEMAP_STYLE,
+    basemapVisible: true,
+    basemapOpacity: 1,
+    layers: orderedLayers,
+    layerGroups: GROUPS_TOP_FIRST.map((group) => ({
+      ...group,
+      visible: true,
+      opacity: 1,
+    })),
+    styles,
+    preferences: projectPreferences,
+    legend: {
+      title: `${tehsil} landscape layers`,
+      groupByLayer: true,
+      order: [...orderedLayers].reverse().map((layer) => layer.id),
+      overrides: {},
+    },
+    metadata: {
+      generatedAtUtc: new Date().toISOString(),
+      generatedBy: "Know Your Landscape",
+      scope: { level: "tehsil", state, district, tehsil, bounds },
+      geolibre: {
+        applicationVersion: GEOLIBRE_CONFIG.version,
+        projectFormatVersion: GEOLIBRE_PROJECT_FORMAT_VERSION,
+        viewerUrl: viewer.url,
+      },
+      layerLoading: {
+        order: [
+          "Socio-Economic Profile",
+          "Micro-watersheds",
+          "Other vector layers",
+          "Latest LULC layers",
+          "Historical LULC layers",
+          "Other raster layers on visibility toggle",
+        ],
+        initialLoadFailures: failures,
+      },
+      qmlStyleContract:
+        "Vector QML symbology is represented in GeoLibre styles. Raster QML symbology is rendered by named GeoServer WMS styles. Original QML URLs are retained per layer.",
+    },
+  };
+};
diff --git a/src/components/geolibre/geolibreProject.test.js b/src/components/geolibre/geolibreProject.test.js
new file mode 100644
index 00000000..fffec841
--- /dev/null
+++ b/src/components/geolibre/geolibreProject.test.js
@@ -0,0 +1,200 @@
+import {
+  buildGeoLibreProject,
+  formatGeoServerName,
+  geoJsonBounds,
+  mapViewFromBounds,
+} from "./geolibreProject";
+import { GEOLIBRE_LAYERS } from "../../config/geolibreLayers";
+
+const location = {
+  state: "Assam",
+  district: "Cachar",
+  tehsil: "Lakhipur",
+};
+
+const polygonFeatureCollection = (request) => ({
+  type: "FeatureCollection",
+  features: [
+    {
+      type: "Feature",
+      id: request.typeName,
+      properties: { P_LIT: 60, TOT_P: 100 },
+      geometry: {
+        type: "Polygon",
+        coordinates: [
+          [
+            [92.9, 24.7],
+            [93.2, 24.7],
+            [93.2, 25.0],
+            [92.9, 25.0],
+            [92.9, 24.7],
+          ],
+        ],
+      },
+    },
+  ],
+});
+
+const successfulFetch = jest.fn();
+
+beforeEach(() => {
+  successfulFetch.mockReset();
+  successfulFetch.mockImplementation(async (request) =>
+    polygonFeatureCollection(request)
+  );
+});
+
+describe("GeoLibre 2.2 project generation", () => {
+  it("normalizes KYL location labels for GeoServer layer names", () => {
+    expect(formatGeoServerName("  Banas Kantha (Palanpur) ")).toBe(
+      "banas_kantha_palanpur"
+    );
+  });
+
+  it("derives a complete bounding box and a padded map view", () => {
+    const bounds = geoJsonBounds(polygonFeatureCollection({ typeName: "test" }));
+    expect(bounds).toEqual([92.9, 24.7, 93.2, 25]);
+    expect(mapViewFromBounds(bounds, { width: 1000, height: 700 })).toEqual(
+      expect.objectContaining({
+        center: [93.05000000000001, 24.85],
+        bbox: bounds,
+        bearing: 0,
+        pitch: 0,
+      })
+    );
+  });
+
+  it("builds official embedded WFS layers and lazy hidden WMS layers", async () => {
+    const project = await buildGeoLibreProject({
+      ...location,
+      fetchFeatureCollection: successfulFetch,
+    });
+
+    expect(project.version).toBe("0.2.0");
+    expect(project.layers).toHaveLength(GEOLIBRE_LAYERS.length);
+    expect(project.layers).toHaveLength(45);
+    expect(project.mapView.bbox).toEqual([92.9, 24.7, 93.2, 25]);
+
+    const socioeconomic = project.layers.find(
+      (layer) => layer.id === "corestack-demographics"
+    );
+    expect(socioeconomic).toMatchObject({
+      type: "geojson",
+      visible: true,
+      opacity: 1,
+      source: {
+        type: "geojson",
+        service: "wfs",
+        version: "1.0.0",
+        typeName: "panchayat_boundaries:cachar_lakhipur",
+      },
+      metadata: {
+        sourceKind: "wfs-getfeature",
+        service: "wfs",
+        featureCount: 1,
+      },
+    });
+    expect(socioeconomic.geojson.type).toBe("FeatureCollection");
+
+    const visibleLayers = project.layers.filter((layer) => layer.visible);
+    expect(visibleLayers.map((layer) => layer.id)).toEqual([
+      "corestack-demographics",
+    ]);
+    expect(project.layers.every((layer) => layer.opacity === 1)).toBe(true);
+
+    const latestLulc = project.layers.find(
+      (layer) => layer.id === "corestack-lulc_level_3_24_25"
+    );
+    expect(latestLulc).toMatchObject({ type: "wms", visible: false });
+    expect(latestLulc.source.layers).toBe(
+      "LULC_level_3:LULC_24_25_cachar_lakhipur_level_3"
+    );
+    expect(latestLulc.source.tiles[0]).toContain(
+      "BBOX={bbox-epsg-3857}"
+    );
+  });
+
+  it("orders the native GeoLibre panel by overview, vectors, LULC, then rasters", async () => {
+    const project = await buildGeoLibreProject({
+      ...location,
+      fetchFeatureCollection: successfulFetch,
+    });
+    const displayIds = [...project.layers]
+      .reverse()
+      .map((layer) => layer.id);
+
+    expect(displayIds.slice(0, 5)).toEqual([
+      "corestack-demographics",
+      "corestack-administrative_boundaries",
+      "corestack-mws_layers",
+      "corestack-hydrological_boundaries",
+      "corestack-mws_layers_fortnight",
+    ]);
+    expect(displayIds.indexOf("corestack-lulc_level_3_24_25")).toBeLessThan(
+      displayIds.indexOf("corestack-lulc_level_3_23_24")
+    );
+    expect(displayIds.indexOf("corestack-lulc_level_1_24_25")).toBeLessThan(
+      displayIds.indexOf("corestack-terrain")
+    );
+    expect(project.layerGroups.map((group) => group.id)).toEqual([
+      "overview",
+      "watersheds",
+      "vectors",
+      "lulc-3",
+      "lulc-2",
+      "lulc-1",
+      "rasters",
+    ]);
+  });
+
+  it("fetches socioeconomic first, MWS second, and reuses duplicate WFS requests", async () => {
+    await buildGeoLibreProject({
+      ...location,
+      fetchFeatureCollection: successfulFetch,
+    });
+
+    expect(successfulFetch.mock.calls[0][0].typeName).toBe(
+      "panchayat_boundaries:cachar_lakhipur"
+    );
+    expect(successfulFetch.mock.calls[1][0].typeName).toBe(
+      "mws_layers:deltaG_well_depth_cachar_lakhipur"
+    );
+    expect(successfulFetch).toHaveBeenCalledTimes(11);
+  });
+
+  it("keeps an unavailable optional vector listed for GeoLibre refresh", async () => {
+    const fetchWithDrainageFailure = jest.fn(async (request) => {
+      if (request.typeName.startsWith("drainage:")) {
+        throw new Error("temporary outage");
+      }
+      return polygonFeatureCollection(request);
+    });
+
+    const project = await buildGeoLibreProject({
+      ...location,
+      fetchFeatureCollection: fetchWithDrainageFailure,
+    });
+    const drainage = project.layers.find(
+      (layer) => layer.id === "corestack-drainage"
+    );
+
+    expect(drainage.geojson.features).toEqual([]);
+    expect(drainage.metadata).toMatchObject({
+      sourceKind: "wfs-getfeature",
+      initialLoadError: "temporary outage",
+    });
+    expect(project.metadata.layerLoading.initialLoadFailures).toHaveLength(1);
+  });
+
+  it("requires the socioeconomic extent", async () => {
+    const failedFetch = jest.fn(async () => {
+      throw new Error("offline");
+    });
+    await expect(
+      buildGeoLibreProject({
+        ...location,
+        fetchFeatureCollection: failedFetch,
+      })
+    ).rejects.toThrow(/socio-economic profile.*offline/i);
+  });
+});
diff --git a/src/config/geolibre.config.js b/src/config/geolibre.config.js
new file mode 100644
index 00000000..d60b0ef3
--- /dev/null
+++ b/src/config/geolibre.config.js
@@ -0,0 +1,88 @@
+const DEFAULT_VIEWER_URL = "https://web.geolibre.app/";
+
+/**
+ * The GeoLibre application version KYL expects to embed.
+ *
+ * For a compatible GeoLibre 2.x update, this is normally the only value that
+ * needs to change. The iframe handshake verifies that the deployed viewer
+ * reports the same version before KYL sends it a project.
+ */
+export const GEOLIBRE_CONFIG = Object.freeze({
+  version: process.env.REACT_APP_GEOLIBRE_VERSION || "2.2.0",
+  minimumCompatibleVersion: "2.2.0",
+  supportedMajorVersion: 2,
+  viewerUrlTemplate:
+    process.env.REACT_APP_GEOLIBRE_URL_TEMPLATE ||
+    process.env.REACT_APP_GEOLIBRE_URL ||
+    DEFAULT_VIEWER_URL,
+  strictVersion:
+    process.env.REACT_APP_GEOLIBRE_STRICT_VERSION !== "false",
+});
+
+// GeoLibre's project schema version is independent from its application release.
+export const GEOLIBRE_PROJECT_FORMAT_VERSION = "0.2.0";
+
+const parseVersion = (value) => {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(
+    String(value || "").trim()
+  );
+  return match ? match.slice(1).map(Number) : null;
+};
+
+const compareVersions = (left, right) => {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] - right[index];
+  }
+  return 0;
+};
+
+export const resolveGeoLibreViewer = (config = GEOLIBRE_CONFIG) => {
+  const version = String(config.version).replace(/^v/, "");
+  const resolvedTemplate = config.viewerUrlTemplate.replaceAll(
+    "{version}",
+    version
+  );
+  const url = new URL(resolvedTemplate);
+  url.searchParams.set("embed", "1");
+  url.searchParams.set("welcome", "0");
+  return { url: url.toString(), origin: url.origin };
+};
+
+export const geoLibreVersionStatus = (
+  actualVersion,
+  config = GEOLIBRE_CONFIG
+) => {
+  const actual = parseVersion(actualVersion);
+  const expected = parseVersion(config.version);
+  const minimum = parseVersion(config.minimumCompatibleVersion);
+
+  if (!actual || !expected || !minimum) {
+    return {
+      compatible: false,
+      message: `GeoLibre reported an invalid version (${actualVersion || "missing"}).`,
+    };
+  }
+
+  const supportedMajorVersion = Number(
+    config.supportedMajorVersion ?? minimum[0]
+  );
+  if (
+    actual[0] !== supportedMajorVersion ||
+    expected[0] !== supportedMajorVersion ||
+    compareVersions(actual, minimum) < 0
+  ) {
+    return {
+      compatible: false,
+      message: `GeoLibre ${actualVersion} is not compatible with this KYL integration (requires ${config.minimumCompatibleVersion} or newer in major version ${supportedMajorVersion}).`,
+    };
+  }
+
+  if (config.strictVersion && compareVersions(actual, expected) !== 0) {
+    return {
+      compatible: false,
+      message: `KYL is configured for GeoLibre ${config.version}, but the iframe loaded ${actualVersion}. Update the configured version only after compatibility testing.`,
+    };
+  }
+
+  return { compatible: true, message: "" };
+};
diff --git a/src/config/geolibre.config.test.js b/src/config/geolibre.config.test.js
new file mode 100644
index 00000000..12210667
--- /dev/null
+++ b/src/config/geolibre.config.test.js
@@ -0,0 +1,48 @@
+import {
+  geoLibreVersionStatus,
+  resolveGeoLibreViewer,
+} from "./geolibre.config";
+
+const config = {
+  version: "2.2.0",
+  minimumCompatibleVersion: "2.2.0",
+  supportedMajorVersion: 2,
+  viewerUrlTemplate: "https://viewer.example/geolibre/{version}/",
+  strictVersion: true,
+};
+
+describe("GeoLibre application configuration", () => {
+  it("resolves a versioned viewer URL and embed parameters", () => {
+    expect(resolveGeoLibreViewer(config)).toEqual({
+      url: "https://viewer.example/geolibre/2.2.0/?embed=1&welcome=0",
+      origin: "https://viewer.example",
+    });
+  });
+
+  it("accepts the configured v2.2 viewer", () => {
+    expect(geoLibreVersionStatus("2.2.0", config)).toEqual({
+      compatible: true,
+      message: "",
+    });
+  });
+
+  it("rejects unexpected, older, and major-version viewers", () => {
+    expect(geoLibreVersionStatus("2.3.0", config).compatible).toBe(false);
+    expect(geoLibreVersionStatus("2.1.9", config).compatible).toBe(false);
+    expect(geoLibreVersionStatus("3.0.0", config).compatible).toBe(false);
+  });
+
+  it("can allow a compatible newer 2.x viewer for an explicit test deployment", () => {
+    expect(
+      geoLibreVersionStatus("2.4.0", { ...config, strictVersion: false })
+        .compatible
+    ).toBe(true);
+  });
+
+  it("does not treat a version-only major upgrade as compatible", () => {
+    expect(
+      geoLibreVersionStatus("3.0.0", { ...config, version: "3.0.0" })
+        .compatible
+    ).toBe(false);
+  });
+});
diff --git a/src/config/geolibreLayers.js b/src/config/geolibreLayers.js
new file mode 100644
index 00000000..a5f8c39a
--- /dev/null
+++ b/src/config/geolibreLayers.js
@@ -0,0 +1,330 @@
+const QML_RAW_BASE =
+  "https://raw.githubusercontent.com/core-stack-org/QGIS-Styles/main";
+
+const qmlStyle = (path) => `${QML_RAW_BASE}/${path}`;
+
+export const GEOLIBRE_LULC_YEARS = [
+  { label: "2017-2018", value: "17_18" },
+  { label: "2018-2019", value: "18_19" },
+  { label: "2019-2020", value: "19_20" },
+  { label: "2020-2021", value: "20_21" },
+  { label: "2021-2022", value: "21_22" },
+  { label: "2022-2023", value: "22_23" },
+  { label: "2023-2024", value: "23_24" },
+  { label: "2024-2025", value: "24_25" },
+];
+
+export const LATEST_GEOLIBRE_LULC_YEAR =
+  GEOLIBRE_LULC_YEARS[GEOLIBRE_LULC_YEARS.length - 1].value;
+
+const LAYERS = [
+  {
+    id: "demographics",
+    label: "Socio-Economic Profile",
+    domain: "Demographic",
+    loadGroup: "overview",
+    sourceType: "wfs",
+    workspace: "panchayat_boundaries",
+    geometryType: "polygon",
+    layerName: ({ district, tehsil }) => `${district}_${tehsil}`,
+    styleProfile: "demographics",
+    qmlStyleUrl: qmlStyle("Demographic/literary_rate_style.qml"),
+  },
+  {
+    id: "administrative_boundaries",
+    label: "Administrative Boundaries",
+    domain: "Demographic",
+    loadGroup: "overview",
+    sourceType: "wfs",
+    workspace: "panchayat_boundaries",
+    geometryType: "polygon",
+    layerName: ({ district, tehsil }) => `${district}_${tehsil}`,
+    styleProfile: "boundary",
+    qmlStyleUrl: qmlStyle("Demographic/Administrative-Boundary-Style.qml"),
+  },
+  {
+    id: "mws_layers",
+    label: "Micro-watersheds and Hydrological Variables",
+    domain: "Climate",
+    loadGroup: "watersheds",
+    sourceType: "wfs",
+    workspace: "mws_layers",
+    geometryType: "polygon",
+    layerName: ({ district, tehsil }) =>
+      `deltaG_well_depth_${district}_${tehsil}`,
+    styleProfile: "mws",
+    qmlStyleUrl: qmlStyle("Climate/MWS-Well-Depth-18_23.qml"),
+  },
+  {
+    id: "hydrological_boundaries",
+    label: "Hydrological Boundaries",
+    domain: "Climate",
+    loadGroup: "watersheds",
+    sourceType: "wfs",
+    workspace: "mws_layers",
+    geometryType: "polygon",
+    layerName: ({ district, tehsil }) =>
+      `deltaG_well_depth_${district}_${tehsil}`,
+    styleProfile: "boundary",
+    qmlStyleUrl: qmlStyle("Climate/MWS-Well-Depth-18_23.qml"),
+  },
+  {
+    id: "mws_layers_fortnight",
+    label: "Fortnightly Hydrological Variables",
+    domain: "Climate",
+    loadGroup: "watersheds",
+    sourceType: "wfs",
+    workspace: "mws_layers",
+    geometryType: "polygon",
+    layerName: ({ district, tehsil }) =>
+      `deltaG_fortnight_${district}_${tehsil}`,
+    styleProfile: "boundary",
+    qmlStyleUrl: qmlStyle("Hydrology/water_balance_fortnightly.qml"),
+  },
+  {
+    id: "terrain_vector",
+    label: "Terrain Vector",
+    domain: "Land",
+    loadGroup: "vectors",
+    sourceType: "wfs",
+    workspace: "terrain",
+    geometryType: "polygon",
+    layerName: ({ district, tehsil }) => `${district}_${tehsil}_cluster`,
+    styleProfile: "terrain_vector",
+    qmlStyleUrl: qmlStyle("Land/Terrain-Vector-Layer-Style.qml"),
+  },
+  {
+    id: "drainage",
+    label: "Drainage",
+    domain: "Hydrology",
+    loadGroup: "vectors",
+    sourceType: "wfs",
+    workspace: "drainage",
+    geometryType: "line",
+    layerName: ({ district, tehsil }) => `${district}_${tehsil}`,
+    styleProfile: "drainage",
+    qmlStyleUrl: qmlStyle("Hydrology/Drainage-Layer-Style.qml"),
+  },
+  {
+    id: "remote_sensed_waterbodies",
+    label: "Remote-Sensed Waterbodies",
+    domain: "Hydrology",
+    loadGroup: "vectors",
+    sourceType: "wfs",
+    workspace: "swb",
+    geometryType: "polygon",
+    layerName: ({ district, tehsil }) =>
+      `surface_waterbodies_${district}_${tehsil}`,
+    styleProfile: "waterbodies",
+    qmlStyleUrl: qmlStyle("Hydrology/Surface-Waterbody-style.qml"),
+  },
+  {
+    id: "soge",
+    label: "Stage of Groundwater Extraction",
+    domain: "Hydrology",
+    loadGroup: "vectors",
+    sourceType: "wfs",
+    workspace: "soge",
+    geometryType: "polygon",
+    layerName: ({ district, tehsil }) => `soge_vector_${district}_${tehsil}`,
+    styleProfile: "soge",
+    qmlStyleUrl: qmlStyle("Hydrology/SOGE_style.qml"),
+  },
+  {
+    id: "aquifer",
+    label: "Aquifer",
+    domain: "Hydrology",
+    loadGroup: "vectors",
+    sourceType: "wfs",
+    workspace: "aquifer",
+    geometryType: "polygon",
+    layerName: ({ district, tehsil }) =>
+      `aquifer_vector_${district}_${tehsil}`,
+    styleProfile: "aquifer",
+    qmlStyleUrl: qmlStyle("Hydrology/Aquifer_style.qml"),
+  },
+  {
+    id: "cropping_intensity",
+    label: "Cropping Intensity",
+    domain: "Agriculture",
+    loadGroup: "vectors",
+    sourceType: "wfs",
+    workspace: "crop_intensity",
+    geometryType: "polygon",
+    layerName: ({ district, tehsil }) => `${district}_${tehsil}_intensity`,
+    styleProfile: "cropping_intensity",
+    qmlStyleUrl: qmlStyle("Agriculture/Cropping_intensity.qml"),
+  },
+  {
+    id: "drought",
+    label: "Drought",
+    domain: "Agriculture",
+    loadGroup: "vectors",
+    sourceType: "wfs",
+    workspace: "drought",
+    geometryType: "polygon",
+    layerName: ({ district, tehsil }) => `${district}_${tehsil}_drought`,
+    styleProfile: "drought",
+    qmlStyleUrl: qmlStyle("Agriculture/Drought_style.qml"),
+  },
+  {
+    id: "nrega",
+    label: "NREGA Assets",
+    domain: "NREGA",
+    loadGroup: "vectors",
+    sourceType: "wfs",
+    workspace: "nrega_assets",
+    geometryType: "point",
+    layerName: ({ district, tehsil }) => `${district}_${tehsil}`,
+    styleProfile: "nrega",
+    qmlStyleUrl: qmlStyle("NREGA/NREG-Assets-Classified-Style.qml"),
+  },
+  {
+    id: "terrain",
+    label: "Terrain",
+    domain: "Land",
+    loadGroup: "rasters",
+    sourceType: "wms",
+    workspace: "terrain",
+    layerName: ({ district, tehsil }) => `${district}_${tehsil}_terrain_raster`,
+    wmsStyle: "terrain:terrain_raster",
+    qmlStyleUrl: qmlStyle("Land/terrain_1-12class.qml"),
+  },
+  {
+    id: "clart",
+    label: "CLART",
+    domain: "Hydrology",
+    loadGroup: "rasters",
+    sourceType: "wms",
+    workspace: "clart",
+    layerName: ({ district, tehsil }) => `${district}_${tehsil}_clart`,
+    wmsStyle: "clart:testClart",
+    qmlStyleUrl: qmlStyle("Hydrology/CLART-Layer-Style.qml"),
+  },
+  {
+    id: "afforestation",
+    label: "Change Detection: Afforestation",
+    domain: "Restoration",
+    loadGroup: "rasters",
+    sourceType: "wms",
+    workspace: "change_detection",
+    layerName: ({ district, tehsil }) =>
+      `change_${district}_${tehsil}_Afforestation`,
+    wmsStyle: "change_detection:afforestation",
+    qmlStyleUrl: qmlStyle("Land/change_tree_cover_gain.qml"),
+  },
+  {
+    id: "deforestation",
+    label: "Change Detection: Deforestation",
+    domain: "Restoration",
+    loadGroup: "rasters",
+    sourceType: "wms",
+    workspace: "change_detection",
+    layerName: ({ district, tehsil }) =>
+      `change_${district}_${tehsil}_Deforestation`,
+    wmsStyle: "change_detection:deforestation",
+    qmlStyleUrl: qmlStyle("Land/change_tree_cover_loss.qml"),
+  },
+  {
+    id: "degradation",
+    label: "Change Detection: Degradation",
+    domain: "Restoration",
+    loadGroup: "rasters",
+    sourceType: "wms",
+    workspace: "change_detection",
+    layerName: ({ district, tehsil }) =>
+      `change_${district}_${tehsil}_Degradation`,
+    wmsStyle: "change_detection:degradation",
+    qmlStyleUrl: qmlStyle("Land/change_cropping_reduction.qml"),
+  },
+  {
+    id: "urbanization",
+    label: "Change Detection: Urbanization",
+    domain: "Restoration",
+    loadGroup: "rasters",
+    sourceType: "wms",
+    workspace: "change_detection",
+    layerName: ({ district, tehsil }) =>
+      `change_${district}_${tehsil}_Urbanization`,
+    wmsStyle: "change_detection:urbanization",
+    qmlStyleUrl: qmlStyle("Land/change_urbanization.qml"),
+  },
+  {
+    id: "cropintensity",
+    label: "Change Detection: Crop Intensity",
+    domain: "Restoration",
+    loadGroup: "rasters",
+    sourceType: "wms",
+    workspace: "change_detection",
+    layerName: ({ district, tehsil }) =>
+      `change_${district}_${tehsil}_CropIntensity`,
+    wmsStyle: "change_detection:cropintensity",
+    qmlStyleUrl: qmlStyle("Land/change_cropping_intensity.qml"),
+  },
+  {
+    id: "restoration",
+    label: "Restoration Opportunities",
+    domain: "Restoration",
+    loadGroup: "rasters",
+    sourceType: "wms",
+    workspace: "restoration",
+    layerName: ({ district, tehsil }) =>
+      `restoration_${district}_${tehsil}_raster`,
+    wmsStyle: "restoration:restoration_style",
+    qmlStyleUrl: qmlStyle("Restoration/Restoration_style.qml"),
+  },
+];
+
+const LULC_LEVELS = [
+  {
+    id: "lulc_level_1",
+    label: "LULC Level 1",
+    domain: "Land",
+    workspace: "LULC_level_1",
+    wmsStyle: "LULC_level_1:lulc_level_1_style",
+    qmlStyleUrl: qmlStyle("Land/level-1-op.qml"),
+  },
+  {
+    id: "lulc_level_2",
+    label: "LULC Level 2",
+    domain: "Land",
+    workspace: "LULC_level_2",
+    wmsStyle: "LULC_level_2:lulc_level_2_style",
+    qmlStyleUrl: qmlStyle("Land/level-2.qml"),
+  },
+  {
+    id: "lulc_level_3",
+    label: "LULC Level 3",
+    domain: "Agriculture",
+    workspace: "LULC_level_3",
+    wmsStyle: "LULC_level_3:lulc_level_3_style",
+    qmlStyleUrl: qmlStyle("Agriculture/level-3.qml"),
+  },
+];
+
+export const GEOLIBRE_LULC_LAYERS = LULC_LEVELS.flatMap((level, index) =>
+  GEOLIBRE_LULC_YEARS.map((year) => ({
+    ...level,
+    id: `${level.id}_${year.value}`,
+    baseId: level.id,
+    label: `${level.label} · ${year.label}`,
+    loadGroup: `lulc-${index + 1}`,
+    sourceType: "wms",
+    year: year.value,
+    layerName: ({ district, tehsil }) =>
+      `LULC_${year.value}_${district}_${tehsil}_level_${index + 1}`,
+  }))
+);
+
+export const GEOLIBRE_LAYERS = Object.freeze([
+  ...LAYERS,
+  ...GEOLIBRE_LULC_LAYERS,
+]);
+
+export const GEOLIBRE_VECTOR_LAYERS = GEOLIBRE_LAYERS.filter(
+  (layer) => layer.sourceType === "wfs"
+);
+
+export const GEOLIBRE_RASTER_LAYERS = GEOLIBRE_LAYERS.filter(
+  (layer) => layer.sourceType === "wms"
+);
diff --git a/src/pages/LE_homepage.jsx b/src/pages/LE_homepage.jsx
index 2cae1c19..bd79fa99 100644
--- a/src/pages/LE_homepage.jsx
+++ b/src/pages/LE_homepage.jsx
@@ -1,4 +1,4 @@
-import React, { useState, useEffect } from "react";
+import React, { useEffect } from "react";
 import { useNavigate } from "react-router";
 import { useRecoilState } from "recoil";
 import {
@@ -38,7 +38,7 @@ export default function KYLHomePage() {
 
     fetchStates();
     setBlock(null);
-  }, []);
+  }, [setBlock, setStatesData]);
 
   const handleItemSelect = (setter, value) => {
     if (setter === setState) {
@@ -62,7 +62,16 @@ export default function KYLHomePage() {
     }
     else{
       trackEvent("Navigation", "button_click", buttonName);
-      navigate(path);
+      if (path === "/download_layers" && state && district && block) {
+        const params = new URLSearchParams({
+          state: state.label,
+          district: district.label,
+          tehsil: block.label,
+        });
+        navigate(`${path}?${params.toString()}`);
+      } else {
+        navigate(path);
+      }
     }
   };
 
@@ -160,8 +169,10 @@ export default function KYLHomePage() {
                     Know Your Landscape
                   </button>
                   <button
-                    className="bg-purple-100 hover:bg-purple-200 text-purple-800 px-4 py-2 rounded-lg w-full sm:w-auto text-base font-medium transition-colors"
+                    className="bg-purple-100 hover:bg-purple-200 text-purple-800 px-4 py-2 rounded-lg w-full sm:w-auto text-base font-medium transition-colors disabled:cursor-not-allowed disabled:bg-gray-100 disabled:text-gray-400"
                     onClick={() => handleNavigate("/download_layers", "Download Layers")}
+                    disabled={!state || !district || !block}
+                    title={!block ? "Select a state, district, and tehsil first" : undefined}
                   >
                     Download Layers
                   </button>
@@ -393,4 +404,4 @@ export default function KYLHomePage() {
       <Footer />
     </div>
   );
-}
\ No newline at end of file
+}
diff --git a/src/pages/LandscapeExplorer.jsx b/src/pages/LandscapeExplorer.jsx
index 46756a12..8968cd9e 100644
--- a/src/pages/LandscapeExplorer.jsx
+++ b/src/pages/LandscapeExplorer.jsx
@@ -1,457 +1,130 @@
-import { useState, useEffect, useRef, useCallback } from "react";
-import Map from "../components/landscape-explorer/map/Map.jsx";
-import RightSidebar from "../components/landscape-explorer/sidebar/RightSidebar.jsx";
-import { useRecoilState } from "recoil";
+import { useEffect, useMemo, useState } from "react";
+import { Link, useLocation } from "react-router-dom";
+import { useRecoilValue } from "recoil";
+import GeoLibreFrame from "../components/geolibre/GeoLibreFrame";
+import { buildGeoLibreProject } from "../components/geolibre/geolibreProject";
+import LandingNavbar from "../components/landing_navbar";
 import {
-  stateDataAtom,
-  stateAtom,
-  districtAtom,
   blockAtom,
-  filterSelectionsAtom,
-  yearAtom,
-} from "../store/locationStore.jsx";
-import getStates from "../actions/getStates.js";
-import * as downloadHelper from "../components/landscape-explorer/utils/downloadHelper";
+  districtAtom,
+  stateAtom,
+} from "../store/locationStore";
 import {
-  trackPageView,
-  trackEvent,
   initializeAnalytics,
+  trackEvent,
+  trackPageView,
 } from "../services/analytics";
-import LandingNavbar from "../components/landing_navbar.jsx";
-
-const LandscapeExplorer = () => {
-  const [showLeftSidebar, setShowLeftSidebar] = useState(false);
-  const [showRightSidebar, setShowRightSidebar] = useState(true);
-  const [isLoading, setIsLoading] = useState(false);
-
-  // Recoil state
-  const [statesData, setStatesData] = useRecoilState(stateDataAtom);
-  const [state, setState] = useRecoilState(stateAtom);
-  const [district, setDistrict] = useRecoilState(districtAtom);
-  const [block, setBlock] = useRecoilState(blockAtom);
-  const [filterSelections, setFilterSelections] =
-    useRecoilState(filterSelectionsAtom);
-  const [lulcYear1, setLulcYear1] = useState(null);
-  const [lulcYear2, setLulcYear2] = useState(null);
-  const [lulcYear3, setLulcYear3] = useState(null);
-
-  // Map ref for accessing map instance from other components
-  const mapRef = useRef(null);
-
-  // Add flag to prevent infinite recursion
-  const isUpdatingFromMap = useRef(false);
-
-  // Track which resource category is active
-  const [activeResourceCategory, setActiveResourceCategory] = useState(null);
-
-  // Set map ref with callback
-  const setMapRef = useCallback((node) => {
-    if (node !== null) {
-      mapRef.current = node;
-    }
-  }, []);
-
-  // Layer toggle state - with demographics on by default
-  const [toggledLayers, setToggledLayers] = useState({
-    // Basic layers
-    demographics: true, // Set to true by default
-    drainage: false,
-    remote_sensed_waterbodies: false,
-    hydrological_boundaries: false,
-    clart: false,
-    mws_layers: false,
-    nrega: false,
-    drought: false,
-    terrain: false,
-    administrative_boundaries: false,
-    cropping_intensity: false,
-    terrain_vector: false,
-    terrain_lulc_slope: false,
-    terrain_lulc_plain: false,
-    afforestation: false,
-    deforestation: false,
-    degradation: false,
-    urbanization: false,
-    cropintensity: false,
-    soge: false,
-    aquifer: false,
-  });
-
-  // State for map view settings
-  const [showMWS, setShowMWS] = useState(true);
-  const [showVillages, setShowVillages] = useState(true);
-
-  // Add plans state
-  const [plans, setPlans] = useState([]);
-
-  // Add internal state flag for when layers are ready
-  const [layersReady, setLayersReady] = useState(false);
-
-  // Flag to track if we need to enable the fetch button
-  const [canFetchLayers, setCanFetchLayers] = useState(block !== null);
-
-  // Handle item selection for dropdowns
-  const handleItemSelect = (setter, value) => {
-    // Handle the setState case specially if it affects parent component state
-    if (setter === setState) {
-      // Reset all dependent state values
-      if (value) {
-        trackEvent("Location", "select_state", value.label);
-      }
-      setDistrict(null);
-      setBlock(null);
-      resetAllStates();
-      setState(value);
-    } else if (setter === setDistrict) {
-      // Reset block and filters when district changes
-      if (value) {
-        trackEvent("Location", "select_district", value.label);
-      }
-      setBlock(null);
-      resetAllStates();
-      setDistrict(value);
-    } else if (setter === setBlock) {
-      resetAllStates();
-      setBlock(value);
-      // When block is selected, enable fetch button and prepare layers automatically
-      setCanFetchLayers(true);
-      trackEvent("Location", "select_tehsil", value.label);
-      // Auto-prepare layers instead of requiring Fetch Layers button
-      setTimeout(() => {
-        if (mapRef.current && mapRef.current.prepareLayers) {
-          setIsLoading(true);
-          mapRef.current.prepareLayers();
-          setLayersReady(true);
-          setToggledLayers((prev) => ({
-            ...prev,
-            demographics: true,
-          }));
-          setIsLoading(false);
-        }
-      }, 100);
-    } else {
-      // Standard case for other setters
-      setter(value);
-    }
-  };
-
-  const resetAllStates = () => {
-    // Reset filters
-    setFilterSelections({
-      selectedMWSValues: {},
-      selectedVillageValues: {},
-    });
-
-    setToggledLayers({
-      demographics: true, // Keep demographics on
-      drainage: false,
-      remote_sensed_waterbodies: false,
-      hydrological_boundaries: false,
-      clart: false,
-      mws_layers: false,
-      nrega: false,
-      drought: false,
-      terrain: false,
-      administrative_boundaries: false,
-      cropping_intensity: false,
-      terrain_vector: false,
-      terrain_lulc_slope: false,
-      terrain_lulc_plain: false,
-      settlement: false,
-      water_structure: false,
-      well_structure: false,
-      agri_structure: false,
-      livelihood_structure: false,
-      recharge_structure: false,
-      afforestation: false,
-      deforestation: false,
-      degradation: false,
-      urbanization: false,
-      cropintensity: false,
-      soge: false,
-      aquifer: false,
-    });
-
-    setLayersReady(false);
-    setCanFetchLayers(false);
-  };
-
-  // Handle layer toggle from RightSidebar
-  const handleLayerToggle = (layerName, isVisible) => {
-    // Prevent recursion if the update is coming from the map component
-    if (isUpdatingFromMap.current) {
-      return;
-    }
-
-    // Update local state immediately
-    setToggledLayers((prev) => ({
-      ...prev,
-      [layerName]: isVisible,
-    }));
-
-    // Then update the map with a slight delay
-    setTimeout(() => {
-      if (mapRef.current && mapRef.current.toggleLayer) {
-        mapRef.current.toggleLayer(layerName, isVisible);
-      }
-    }, 50);
-  };
-
-  // Handle GeoJSON download
-  const handleGeoJsonLayers = (layerName) => {
-    if (!district || !block) {
-      alert("Please select a district and block first");
-      return;
-    }
-
-    console.log(`Downloading GeoJSON for ${layerName}`);
-
-    const districtFormatted = district.label
-      .toLowerCase()
-      .replace(/\s*\(\s*/g, "_")
-      .replace(/\s*\)\s*/g, "")
-      .replace(/\s+/g, "_");
-    const blockFormatted = block.label
-      .toLowerCase()
-      .replace(/\s*\(\s*/g, "_")
-      .replace(/\s*\)\s*/g, "")
-      .replace(/\s+/g, "_");
 
-    // Create download URL based on layer name (following the original implementation's URL format)
-    let downloadUrl = "";
+const labelOf = (selection) => selection?.label || "";
 
-    switch (layerName) {
-      case "demographics":
-        downloadUrl = `https://geoserver.core-stack.org:8443/geoserver/panchayat_boundaries/ows?service=WFS&version=1.0.0&request=GetFeature&typeName=panchayat_boundaries:${districtFormatted}_${blockFormatted}&outputFormat=application/json&screen=main`;
-        break;
-      case "drainage":
-        downloadUrl = `https://geoserver.core-stack.org:8443/geoserver/drainage/ows?service=WFS&version=1.0.0&request=GetFeature&typeName=drainage:${districtFormatted}_${blockFormatted}&outputFormat=application/json&screen=main`;
-        break;
-      case "remote_sensed_waterbodies":
-        downloadUrl = `https://geoserver.core-stack.org:8443/geoserver/swb/ows?service=WFS&version=1.0.0&request=GetFeature&typeName=swb:surface_waterbodies_${districtFormatted}_${blockFormatted}&outputFormat=application/json&screen=main`;
-        break;
-      case "hydrological_boundaries":
-        downloadUrl = `https://geoserver.core-stack.org:8443/geoserver/mws_layers/ows?service=WFS&version=1.0.0&request=GetFeature&typeName=mws_layers:deltaG_well_depth_${districtFormatted}_${blockFormatted}&outputFormat=application/json&screen=main`;
-        break;
-      // Add other cases as needed
-      default:
-        downloadUrl = `https://geoserver.core-stack.org:8443/geoserver/${layerName}/ows?service=WFS&version=1.0.0&request=GetFeature&typeName=${layerName}:${districtFormatted}_${blockFormatted}&outputFormat=application/json&screen=main`;
-    }
-
-    // Use the imported helper directly
-    downloadHelper.downloadGeoJson(downloadUrl, layerName);
-  };
-
-  // Handle KML download
-  const handleKMLLayers = (layerName) => {
-    if (!district || !block) {
-      alert("Please select a district and block first");
-      return;
-    }
-
-    console.log(`Downloading KML for ${layerName}`);
-
-    const districtFormatted = district.label
-      .toLowerCase()
-      .replace(/\s*\(\s*/g, "_")
-      .replace(/\s*\)\s*/g, "")
-      .replace(/\s+/g, "_");
-    const blockFormatted = block.label
-      .toLowerCase()
-      .replace(/\s*\(\s*/g, "_")
-      .replace(/\s*\)\s*/g, "")
-      .replace(/\s+/g, "_");
-
-    // Create download URL based on layer name (following original implementation)
-    let downloadUrl = "";
-
-    switch (layerName) {
-      case "demographics":
-        downloadUrl = `https://geoserver.core-stack.org:8443/geoserver/panchayat_boundaries/ows?service=WFS&version=1.0.0&request=GetFeature&typeName=panchayat_boundaries:${districtFormatted}_${blockFormatted}&outputFormat=application/vnd.google-earth.kml+xml&screen=main`;
-        break;
-      case "drainage":
-        downloadUrl = `https://geoserver.core-stack.org:8443/geoserver/drainage/ows?service=WFS&version=1.0.0&request=GetFeature&typeName=drainage:${districtFormatted}_${blockFormatted}&outputFormat=application/vnd.google-earth.kml+xml&screen=main`;
-        break;
-      case "remote_sensed_waterbodies":
-        downloadUrl = `https://geoserver.core-stack.org:8443/geoserver/water_bodies/ows?service=WFS&version=1.0.0&request=GetFeature&typeName=water_bodies:surface_waterbodies_${districtFormatted}_${blockFormatted}&outputFormat=application/vnd.google-earth.kml+xml&screen=main`;
-        break;
-      case "hydrological_boundaries":
-        downloadUrl = `https://geoserver.core-stack.org:8443/geoserver/mws_layers/ows?service=WFS&version=1.0.0&request=GetFeature&typeName=mws_layers:deltaG_well_depth_${districtFormatted}_${blockFormatted}&outputFormat=application/vnd.google-earth.kml+xml&screen=main`;
-        break;
-      // Add other cases as needed
-      default:
-        downloadUrl = `https://geoserver.core-stack.org:8443/geoserver/${layerName}/ows?service=WFS&version=1.0.0&request=GetFeature&typeName=${layerName}:${districtFormatted}_${blockFormatted}&outputFormat=application/vnd.google-earth.kml+xml&screen=main`;
-    }
-
-    // Use the imported helper directly
-    downloadHelper.downloadKml(downloadUrl, layerName);
-  };
-
-  // Handle Excel download
-  const handleExcelDownload = () => {
-    if (!district || !block) {
-      alert("Please select a district and block first");
-      return;
-    }
-
-    setIsLoading(true);
-
-    // Using the exact URL format from the original implementation
-    fetch(
-      `https://geoserver.core-stack.org/api/v1/download_excel_layer?state=${state.label}&district=${district.label}&block=${block.label}`,
-      {
-        method: "GET",
-        headers: {
-          "ngrok-skip-browser-warning": "1",
-          "Content-Type": "blob",
-        },
-      }
-    )
-      .then((response) => response.arrayBuffer())
-      .then((arybuf) => {
-        const url = window.URL.createObjectURL(new Blob([arybuf]));
-        const link = document.createElement("a");
-
-        link.href = url;
-        link.setAttribute("download", `${block.label}_data.xlsx`);
-        document.body.appendChild(link);
-        link.click();
-
-        link.remove();
-        URL.revokeObjectURL(url);
-        setIsLoading(false);
-      })
-      .catch((error) => {
-        console.error("Error downloading Excel:", error);
-        setIsLoading(false);
-        alert("Failed to download Excel data. Please try again.");
-      });
-  };
-
-  // Track category selection for resource layers
-  const handleCategoryChange = (category) => {
-    setActiveResourceCategory(category);
-  };
+const LandscapeExplorer = () => {
+  const selectedState = useRecoilValue(stateAtom);
+  const selectedDistrict = useRecoilValue(districtAtom);
+  const selectedTehsil = useRecoilValue(blockAtom);
+  const routeLocation = useLocation();
+  const [project, setProject] = useState(null);
+  const [progress, setProgress] = useState("Starting GeoLibre…");
+  const [error, setError] = useState("");
+  const [retryKey, setRetryKey] = useState(0);
+
+  const scope = useMemo(() => {
+    const params = new URLSearchParams(routeLocation.search);
+    return {
+      state: params.get("state") || labelOf(selectedState),
+      district: params.get("district") || labelOf(selectedDistrict),
+      tehsil: params.get("tehsil") || labelOf(selectedTehsil),
+    };
+  }, [
+    routeLocation.search,
+    selectedDistrict,
+    selectedState,
+    selectedTehsil,
+  ]);
+
+  const hasLocation = Boolean(scope.state && scope.district && scope.tehsil);
 
-  // Fetch states data on component mount
   useEffect(() => {
     initializeAnalytics();
     trackPageView("/download_layers");
-    if (statesData === null) {
-      getStates().then((data) => setStatesData(data));
-    }
-  }, [statesData, setStatesData]);
-
-  // Handle map-initiated layer toggle updates
-  const handleMapToggle = (layerName, isVisible) => {
-    // Set the recursion prevention flag
-    isUpdatingFromMap.current = true;
+  }, []);
 
-    try {
-      // Special case for setState action - coming from map marker click
-      if (layerName === "setState" && typeof isVisible === "object") {
-        if (isVisible && isVisible.label && isVisible.district) {
-          setState(isVisible);
-          return;
-        }
-      }
+  useEffect(() => {
+    if (!hasLocation) return undefined;
+    const controller = new AbortController();
+    setProject(null);
+    setError("");
+    setProgress(`Loading the Socio-Economic Profile for ${scope.tehsil}…`);
+
+    buildGeoLibreProject({
+      ...scope,
+      signal: controller.signal,
+      viewport: {
+        width: Math.max(window.innerWidth - 340, 320),
+        height: Math.max(window.innerHeight - 100, 320),
+      },
+      onProgress: ({ message }) => {
+        if (!controller.signal.aborted) setProgress(message);
+      },
+    })
+      .then((nextProject) => {
+        if (controller.signal.aborted) return;
+        setProject(nextProject);
+        setProgress("Opening the tehsil project in GeoLibre…");
+        trackEvent("GeoLibre", "open_workspace", scope.tehsil);
+      })
+      .catch((buildError) => {
+        if (controller.signal.aborted) return;
+        setError(
+          buildError instanceof Error
+            ? buildError.message
+            : "The tehsil project could not be generated."
+        );
+      });
 
-      // Update the toggledLayers state
-      setToggledLayers((prev) => ({
-        ...prev,
-        [layerName]: isVisible,
-      }));
-    } finally {
-      // Reset the flag
-      isUpdatingFromMap.current = false;
-    }
-  };
+    return () => controller.abort();
+  }, [hasLocation, retryKey, scope]);
 
-  return (
-    <div className="min-h-screen bg-white flex flex-col">
-      <div className="sticky top-0 z-50 bg-white border-b border-gray-100">
+  if (!hasLocation) {
+    return (
+      <div className="flex h-screen flex-col bg-slate-100">
         <LandingNavbar />
-      </div>
-      <div className="flex h-[calc(100vh-48px)]">
-
-
-        <div className="flex-1 relative p-2">
-
-          <Map
-            ref={setMapRef}
-            isLoading={isLoading}
-            setIsLoading={setIsLoading}
-            state={state}
-            district={district}
-            block={block}
-            filterSelections={filterSelections}
-            toggledLayers={toggledLayers}
-            toggleLayer={handleMapToggle} // Use handleMapToggle to properly handle map-initiated updates
-            showMWS={showMWS}
-            setShowMWS={setShowMWS}
-            showVillages={showVillages}
-            setShowVillages={setShowVillages}
-            lulcYear1={lulcYear1}
-            lulcYear2={lulcYear2}
-            lulcYear3={lulcYear3}
-          />
-        </div>
-
-        {showRightSidebar && (
-          <RightSidebar
-            state={state}
-            district={district}
-            block={block}
-            setState={setState}
-            setDistrict={setDistrict}
-            setBlock={setBlock}
-            statesData={statesData}
-            handleItemSelect={handleItemSelect}
-            onClose={() => setShowRightSidebar(false)}
-            handleLayerToggle={handleLayerToggle}
-            handleGeoJsonLayers={handleGeoJsonLayers}
-            handleKMLLayers={handleKMLLayers}
-            toggledLayers={toggledLayers}
-            toggleLayer={handleLayerToggle}
-            handleExcelDownload={handleExcelDownload}
-            isLoading={isLoading}
-            canFetchLayers={canFetchLayers}
-            onCategoryChange={handleCategoryChange}
-            lulcYear1={lulcYear1}
-            lulcYear2={lulcYear2}
-            lulcYear3={lulcYear3}
-            setLulcYear1={setLulcYear1}
-            setLulcYear2={setLulcYear2}
-            setLulcYear3={setLulcYear3}
-          />
-        )}
-
-        {!showRightSidebar && (
-          <div className="absolute top-20 right-0 z-10 bg-white p-2 px-3 rounded-l-md shadow-md hover:bg-gray-100 transition-colors flex items-center">
-            <button
-              onClick={() => setShowRightSidebar(true)}
-              className="flex items-center"
-              aria-label="Open filters panel"
+        <main className="flex min-h-0 flex-1 items-center justify-center p-6">
+          <div className="max-w-md rounded-2xl bg-white p-7 text-center shadow-xl">
+            <h1 className="text-xl font-semibold text-slate-900">
+              Select a tehsil first
+            </h1>
+            <p className="mt-2 text-sm leading-6 text-slate-600">
+              GeoLibre projects are generated for a selected state, district,
+              and tehsil.
+            </p>
+            <Link
+              to="/"
+              className="mt-5 inline-flex rounded-lg bg-purple-700 px-4 py-2 text-sm font-semibold text-white hover:bg-purple-800"
             >
-              <span className="font-medium text-gray-700 mr-2">
-                Filters & Data
-              </span>
-              <svg
-                xmlns="http://www.w3.org/2000/svg"
-                width="16"
-                height="16"
-                fill="currentColor"
-                viewBox="0 0 16 16"
-              >
-                <path
-                  fillRule="evenodd"
-                  d="M11.354 1.646a.5.5 0 0 1 0 .708L5.707 8l5.647 5.646a.5.5 0 0 1-.708.708l-6-6a.5.5 0 0 1 0-.708l6-6a.5.5 0 0 1 .708 0z"
-                />
-              </svg>
-            </button>
+              Select location
+            </Link>
           </div>
-        )}
+        </main>
       </div>
+    );
+  }
+
+  const failures =
+    project?.metadata?.layerLoading?.initialLoadFailures?.length || 0;
+  const warning = failures
+    ? `${failures} layer${failures === 1 ? "" : "s"} could not be preloaded. They remain listed in GeoLibre and can be retried with Refresh.`
+    : "";
+
+  return (
+    <div className="flex h-screen flex-col overflow-hidden bg-white">
+      <LandingNavbar />
+      <GeoLibreFrame
+        project={project}
+        preparationMessage={progress}
+        preparationError={error}
+        warning={warning}
+        onRetry={() => setRetryKey((value) => value + 1)}
+      />
     </div>
   );
 };

From dcd72c945a96c741a9585aa5d294805f305a15d0 Mon Sep 17 00:00:00 2001
From: amit-spatial <amit.kumar@gramvaani.org>
Date: Tue, 21 Jul 2026 23:50:57 +0000
Subject: [PATCH 2/9] fix GeoLibre 2.x version compatibility

---
 .../geolibre/GeoLibreFrame.test.jsx           | 10 +++----
 src/components/geolibre/README.md             | 28 +++++++++----------
 src/config/geolibre.config.js                 | 12 ++++----
 src/config/geolibre.config.test.js            | 14 ++++++++--
 4 files changed, 37 insertions(+), 27 deletions(-)

diff --git a/src/components/geolibre/GeoLibreFrame.test.jsx b/src/components/geolibre/GeoLibreFrame.test.jsx
index 48b0b455..84769d88 100644
--- a/src/components/geolibre/GeoLibreFrame.test.jsx
+++ b/src/components/geolibre/GeoLibreFrame.test.jsx
@@ -28,12 +28,12 @@ describe("GeoLibre iframe bridge", () => {
   beforeEach(() => jest.useFakeTimers());
   afterEach(() => jest.useRealTimers());
 
-  it("loads the project and fits its bbox after a valid v2.2 handshake", () => {
+  it("loads the project and fits its bbox after a compatible v2.1 handshake", () => {
     render(<GeoLibreFrame project={project} />);
     const frame = screen.getByTitle("GeoLibre GIS workspace");
     const postMessage = jest.spyOn(frame.contentWindow, "postMessage");
 
-    act(() => announceReady(frame));
+    act(() => announceReady(frame, "2.1.0"));
 
     expect(postMessage).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -55,15 +55,15 @@ describe("GeoLibre iframe bridge", () => {
     );
   });
 
-  it("does not send a project to an unexpected viewer version", () => {
+  it("does not send a project to an incompatible major version", () => {
     render(<GeoLibreFrame project={project} />);
     const frame = screen.getByTitle("GeoLibre GIS workspace");
     const postMessage = jest.spyOn(frame.contentWindow, "postMessage");
 
-    act(() => announceReady(frame, "2.3.0"));
+    act(() => announceReady(frame, "3.0.0"));
 
     expect(screen.getByRole("alert").textContent).toMatch(
-      /configured for GeoLibre 2\.2\.0.*loaded 2\.3\.0/i
+      /GeoLibre 3\.0\.0 is not compatible.*major version 2/i
     );
     expect(postMessage).not.toHaveBeenCalledWith(
       expect.objectContaining({ type: "geolibre:load-project" }),
diff --git a/src/components/geolibre/README.md b/src/components/geolibre/README.md
index c38e33a5..8f217194 100644
--- a/src/components/geolibre/README.md
+++ b/src/components/geolibre/README.md
@@ -50,35 +50,35 @@ contains the full tehsil rather than a generic India extent.
 
 ## Version configuration
 
-The normal upgrade control is the `version` value in
-`../../config/geolibre.config.js`:
+The default hosted viewer accepts any GeoLibre release from `2.0.0` up to, but
+not including, `3.0.0`. Compatible 2.x hosted upgrades need no KYL code change.
+The compatibility range lives in `../../config/geolibre.config.js`:
 
 ```js
 export const GEOLIBRE_CONFIG = Object.freeze({
   version: process.env.REACT_APP_GEOLIBRE_VERSION || "2.2.0",
+  minimumCompatibleVersion: "2.0.0",
   supportedMajorVersion: 2,
   // ...
 });
 ```
 
-For a compatible GeoLibre 2.x release, change that one fallback value, or set:
+`version` records the preferred/tested release and fills `{version}` in a
+versioned URL template. It cannot select the release served by the unversioned
+`https://web.geolibre.app/` deployment.
 
-```dotenv
-REACT_APP_GEOLIBRE_VERSION=2.3.0
-```
-
-The hosted `https://web.geolibre.app/` URL follows GeoLibre's current web
-deployment; it is not an immutable versioned release asset. KYL therefore
-checks the version reported by the iframe and refuses to send data on a
-mismatch. For an exactly pinned self-hosted deployment, use a URL template:
+For an exactly pinned self-hosted release, set:
 
 ```dotenv
+REACT_APP_GEOLIBRE_VERSION=2.3.0
 REACT_APP_GEOLIBRE_URL_TEMPLATE=https://maps.example.org/geolibre/{version}/
+REACT_APP_GEOLIBRE_STRICT_VERSION=true
 ```
 
-`{version}` is replaced automatically. Set
-`REACT_APP_GEOLIBRE_STRICT_VERSION=false` only for deliberate compatibility
-testing of a newer GeoLibre 2.x viewer. A major-version update should update
+The hosted URL follows GeoLibre's current web deployment and may also be served
+from an existing browser cache. KYL checks its reported version, accepts the
+compatible 2.x range, and rejects other major versions. `{version}` is replaced
+automatically for versioned deployments. A major-version update should update
 the compatibility rules and project/bridge tests, not just the version value.
 
 GeoLibre's application version (`2.2.0`) is separate from its project schema
diff --git a/src/config/geolibre.config.js b/src/config/geolibre.config.js
index d60b0ef3..853926c9 100644
--- a/src/config/geolibre.config.js
+++ b/src/config/geolibre.config.js
@@ -1,22 +1,22 @@
 const DEFAULT_VIEWER_URL = "https://web.geolibre.app/";
 
 /**
- * The GeoLibre application version KYL expects to embed.
+ * The preferred GeoLibre application version for a versioned deployment.
  *
- * For a compatible GeoLibre 2.x update, this is normally the only value that
- * needs to change. The iframe handshake verifies that the deployed viewer
- * reports the same version before KYL sends it a project.
+ * The public web.geolibre.app URL is unversioned, so this value does not select
+ * what that server returns. By default KYL accepts compatible 2.x viewers and
+ * uses this value only for {version} URL templates and project metadata.
  */
 export const GEOLIBRE_CONFIG = Object.freeze({
   version: process.env.REACT_APP_GEOLIBRE_VERSION || "2.2.0",
-  minimumCompatibleVersion: "2.2.0",
+  minimumCompatibleVersion: "2.0.0",
   supportedMajorVersion: 2,
   viewerUrlTemplate:
     process.env.REACT_APP_GEOLIBRE_URL_TEMPLATE ||
     process.env.REACT_APP_GEOLIBRE_URL ||
     DEFAULT_VIEWER_URL,
   strictVersion:
-    process.env.REACT_APP_GEOLIBRE_STRICT_VERSION !== "false",
+    process.env.REACT_APP_GEOLIBRE_STRICT_VERSION === "true",
 });
 
 // GeoLibre's project schema version is independent from its application release.
diff --git a/src/config/geolibre.config.test.js b/src/config/geolibre.config.test.js
index 12210667..ef7691b8 100644
--- a/src/config/geolibre.config.test.js
+++ b/src/config/geolibre.config.test.js
@@ -1,11 +1,12 @@
 import {
+  GEOLIBRE_CONFIG,
   geoLibreVersionStatus,
   resolveGeoLibreViewer,
 } from "./geolibre.config";
 
 const config = {
   version: "2.2.0",
-  minimumCompatibleVersion: "2.2.0",
+  minimumCompatibleVersion: "2.0.0",
   supportedMajorVersion: 2,
   viewerUrlTemplate: "https://viewer.example/geolibre/{version}/",
   strictVersion: true,
@@ -26,9 +27,18 @@ describe("GeoLibre application configuration", () => {
     });
   });
 
+  it("accepts supported hosted GeoLibre 2.x releases by default", () => {
+    expect(geoLibreVersionStatus("2.1.0", GEOLIBRE_CONFIG).compatible).toBe(
+      true
+    );
+    expect(geoLibreVersionStatus("2.2.0", GEOLIBRE_CONFIG).compatible).toBe(
+      true
+    );
+  });
+
   it("rejects unexpected, older, and major-version viewers", () => {
     expect(geoLibreVersionStatus("2.3.0", config).compatible).toBe(false);
-    expect(geoLibreVersionStatus("2.1.9", config).compatible).toBe(false);
+    expect(geoLibreVersionStatus("1.9.9", config).compatible).toBe(false);
     expect(geoLibreVersionStatus("3.0.0", config).compatible).toBe(false);
   });
 

From 40f68664ac57336a94b64a891804da3e6345cd30 Mon Sep 17 00:00:00 2001
From: amit-spatial <amit.kumar@gramvaani.org>
Date: Wed, 22 Jul 2026 00:45:16 +0000
Subject: [PATCH 3/9] add full GeoTIFF raster export

---
 .env.example                                  | 10 +++++++++
 src/components/geolibre/GeoLibreFrame.jsx     | 22 ++++++++++++++++---
 .../geolibre/GeoLibreFrame.test.jsx           |  2 ++
 src/components/geolibre/README.md             | 20 ++++++++++++++---
 src/components/geolibre/geolibreProject.js    | 21 ++++++++++++++----
 .../geolibre/geolibreProject.test.js          | 21 ++++++++++++++++--
 src/config/geolibre.config.js                 |  9 ++++++--
 src/config/geolibre.config.test.js            |  5 +++++
 8 files changed, 96 insertions(+), 14 deletions(-)
 create mode 100644 .env.example

diff --git a/.env.example b/.env.example
new file mode 100644
index 00000000..c25f23a3
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,10 @@
+# GeoLibre's official web URL is a rolling deployment. This accepts compatible
+# GeoLibre 2.x releases and displays the version reported by the iframe.
+REACT_APP_GEOLIBRE_VERSION=2.2.0
+REACT_APP_GEOLIBRE_URL=https://web.geolibre.app/
+REACT_APP_GEOLIBRE_STRICT_VERSION=false
+
+# To make the version value select an exact build, deploy GeoLibre at stable
+# versioned paths and use this instead of REACT_APP_GEOLIBRE_URL:
+# REACT_APP_GEOLIBRE_URL_TEMPLATE=https://geolibre.core-stack.org/{version}/
+# REACT_APP_GEOLIBRE_STRICT_VERSION=true
diff --git a/src/components/geolibre/GeoLibreFrame.jsx b/src/components/geolibre/GeoLibreFrame.jsx
index 91447862..2c67bc12 100644
--- a/src/components/geolibre/GeoLibreFrame.jsx
+++ b/src/components/geolibre/GeoLibreFrame.jsx
@@ -18,6 +18,7 @@ const GeoLibreFrame = ({
   const sequenceRef = useRef(0);
   const [viewerState, setViewerState] = useState("loading");
   const [viewerError, setViewerError] = useState("");
+  const [viewerVersion, setViewerVersion] = useState("");
   const [readyGeneration, setReadyGeneration] = useState(0);
 
   const viewer = useMemo(() => {
@@ -66,6 +67,7 @@ const GeoLibreFrame = ({
           setViewerState("error");
           return;
         }
+        setViewerVersion(String(event.data.version));
         sentProjectRef.current = null;
         setViewerError("");
         setViewerState("ready");
@@ -153,12 +155,26 @@ const GeoLibreFrame = ({
           className="h-full w-full border-0 bg-white"
           allow="fullscreen; clipboard-read; clipboard-write"
           allowFullScreen
-          onLoad={() => setViewerState((current) =>
-            current === "loaded" ? current : "loading"
-          )}
+          data-geolibre-version={viewerVersion || undefined}
+          onLoad={() => {
+            setViewerVersion("");
+            setViewerState((current) =>
+              current === "loaded" ? current : "loading"
+            );
+          }}
         />
       )}
 
+      {!activeError && viewerVersion && (
+        <div
+          className="pointer-events-none absolute bottom-8 right-3 rounded-md border border-slate-300 bg-white/95 px-2 py-1 text-[11px] font-medium text-slate-700 shadow-sm"
+          title={`Loaded from ${viewer.url}`}
+          role="status"
+        >
+          GeoLibre {viewerVersion} · {viewer.versionPinned ? "pinned" : "rolling host"}
+        </div>
+      )}
+
       {(showProgress || activeError) && (
         <div className="absolute inset-0 flex items-center justify-center bg-slate-950/35 p-5 backdrop-blur-[1px]">
           <div
diff --git a/src/components/geolibre/GeoLibreFrame.test.jsx b/src/components/geolibre/GeoLibreFrame.test.jsx
index 84769d88..a149e031 100644
--- a/src/components/geolibre/GeoLibreFrame.test.jsx
+++ b/src/components/geolibre/GeoLibreFrame.test.jsx
@@ -35,6 +35,8 @@ describe("GeoLibre iframe bridge", () => {
 
     act(() => announceReady(frame, "2.1.0"));
 
+    expect(screen.getByText(/GeoLibre 2\.1\.0 · rolling host/i)).toBeTruthy();
+
     expect(postMessage).toHaveBeenCalledWith(
       expect.objectContaining({
         type: "geolibre:load-project",
diff --git a/src/components/geolibre/README.md b/src/components/geolibre/README.md
index 8f217194..0968766c 100644
--- a/src/components/geolibre/README.md
+++ b/src/components/geolibre/README.md
@@ -52,11 +52,14 @@ contains the full tehsil rather than a generic India extent.
 
 The default hosted viewer accepts any GeoLibre release from `2.0.0` up to, but
 not including, `3.0.0`. Compatible 2.x hosted upgrades need no KYL code change.
-The compatibility range lives in `../../config/geolibre.config.js`:
+The one source-code value to update is `DEFAULT_GEOLIBRE_VERSION` in
+`../../config/geolibre.config.js`:
 
 ```js
+export const DEFAULT_GEOLIBRE_VERSION = "2.2.0";
+
 export const GEOLIBRE_CONFIG = Object.freeze({
-  version: process.env.REACT_APP_GEOLIBRE_VERSION || "2.2.0",
+  version: process.env.REACT_APP_GEOLIBRE_VERSION || DEFAULT_GEOLIBRE_VERSION,
   minimumCompatibleVersion: "2.0.0",
   supportedMajorVersion: 2,
   // ...
@@ -80,6 +83,8 @@ from an existing browser cache. KYL checks its reported version, accepts the
 compatible 2.x range, and rejects other major versions. `{version}` is replaced
 automatically for versioned deployments. A major-version update should update
 the compatibility rules and project/bridge tests, not just the version value.
+The small badge over the iframe reports the version that actually completed the
+GeoLibre handshake and whether its deployment URL is `rolling` or `pinned`.
 
 GeoLibre's application version (`2.2.0`) is separate from its project schema
 version (`0.2.0`). Do not change the project format merely when upgrading the
@@ -104,7 +109,16 @@ requests), 24 LULC year/level rasters, and 8 other rasters.
   styles. The source QML URL remains in `metadata.corestack.qmlStyleUrl`.
 - Raster QML styles are published as named GeoServer styles and rendered by
   WMS. Their original QML URLs are also retained.
-- WCS GetCoverage URLs remain in raster metadata for data export workflows.
+- Each raster keeps its styled WMS tiles for display and exposes its complete
+  WCS GetCoverage GeoTIFF as `source.url`. This is the contract GeoLibre 2.1+
+  uses to show **Export → GeoTIFF (COG)** and save the returned bytes without
+  subset extraction or client-side re-encoding.
+
+GeoServer WCS returns the complete published coverage, matching KYL's previous
+download flow. It is not guaranteed to be byte-identical to GeoServer's private
+backing file. If immutable original COG objects are published later, place those
+direct object URLs in the raster catalogue and use them instead of the WCS
+fallback.
 
 Changing only a QML URL does not alter rendered vector symbology; update the
 matching style profile in `geolibreProject.js`. Raster appearance changes must
diff --git a/src/components/geolibre/geolibreProject.js b/src/components/geolibre/geolibreProject.js
index cb4e34f3..b3104ef8 100644
--- a/src/components/geolibre/geolibreProject.js
+++ b/src/components/geolibre/geolibreProject.js
@@ -538,13 +538,21 @@ const buildVectorLayer = ({
 };
 
 const buildRasterLayer = ({ catalogLayer, layerName, baseUrl, bounds }) => {
-  const source = buildWmsSource(baseUrl, catalogLayer, layerName, bounds);
+  const wmsSource = buildWmsSource(baseUrl, catalogLayer, layerName, bounds);
   const wcsDownloadUrl = buildWcsUrl(baseUrl, catalogLayer, layerName);
+  const source = {
+    ...wmsSource,
+    // GeoLibre exposes its byte-preserving "GeoTIFF (COG)" export for a
+    // raster layer when source.url points to a complete downloadable file.
+    // Rendering still uses the styled WMS tile template above.
+    url: wcsDownloadUrl,
+    wmsUrl: wmsSource.url,
+  };
   const style = layerStyle(catalogLayer);
   return {
     id: `corestack-${catalogLayer.id}`,
     name: catalogLayer.label,
-    type: "wms",
+    type: "raster",
     source,
     visible: false,
     opacity: 1,
@@ -552,11 +560,16 @@ const buildRasterLayer = ({ catalogLayer, layerName, baseUrl, bounds }) => {
     metadata: {
       service: "wms",
       corestack: {
-        ...coreStackMetadata(catalogLayer, layerName, source.url),
+        ...coreStackMetadata(catalogLayer, layerName, wmsSource.url),
         wcsDownloadUrl,
+        rasterDownload: {
+          kind: "full-coverage-geotiff",
+          url: wcsDownloadUrl,
+          bytePreservingInGeoLibre: true,
+        },
       },
     },
-    sourcePath: source.url,
+    sourcePath: wcsDownloadUrl,
     groupId: catalogLayer.loadGroup,
   };
 };
diff --git a/src/components/geolibre/geolibreProject.test.js b/src/components/geolibre/geolibreProject.test.js
index fffec841..90edf8f9 100644
--- a/src/components/geolibre/geolibreProject.test.js
+++ b/src/components/geolibre/geolibreProject.test.js
@@ -64,7 +64,7 @@ describe("GeoLibre 2.2 project generation", () => {
     );
   });
 
-  it("builds official embedded WFS layers and lazy hidden WMS layers", async () => {
+  it("builds embedded WFS layers and downloadable, lazy styled rasters", async () => {
     const project = await buildGeoLibreProject({
       ...location,
       fetchFeatureCollection: successfulFetch,
@@ -105,13 +105,30 @@ describe("GeoLibre 2.2 project generation", () => {
     const latestLulc = project.layers.find(
       (layer) => layer.id === "corestack-lulc_level_3_24_25"
     );
-    expect(latestLulc).toMatchObject({ type: "wms", visible: false });
+    expect(latestLulc).toMatchObject({
+      type: "raster",
+      visible: false,
+      metadata: {
+        service: "wms",
+        corestack: {
+          rasterDownload: {
+            kind: "full-coverage-geotiff",
+            bytePreservingInGeoLibre: true,
+          },
+        },
+      },
+    });
     expect(latestLulc.source.layers).toBe(
       "LULC_level_3:LULC_24_25_cachar_lakhipur_level_3"
     );
     expect(latestLulc.source.tiles[0]).toContain(
       "BBOX={bbox-epsg-3857}"
     );
+    expect(latestLulc.source.wmsUrl).toContain("/LULC_level_3/wms");
+    expect(latestLulc.source.url).toContain("request=GetCoverage");
+    expect(latestLulc.source.url).toContain(
+      "CoverageId=LULC_level_3%3ALULC_24_25_cachar_lakhipur_level_3"
+    );
   });
 
   it("orders the native GeoLibre panel by overview, vectors, LULC, then rasters", async () => {
diff --git a/src/config/geolibre.config.js b/src/config/geolibre.config.js
index 853926c9..9d1066d5 100644
--- a/src/config/geolibre.config.js
+++ b/src/config/geolibre.config.js
@@ -1,5 +1,9 @@
 const DEFAULT_VIEWER_URL = "https://web.geolibre.app/";
 
+// Change this one value when KYL moves to another tested GeoLibre release.
+// It selects the deployed build only when viewerUrlTemplate contains {version}.
+export const DEFAULT_GEOLIBRE_VERSION = "2.2.0";
+
 /**
  * The preferred GeoLibre application version for a versioned deployment.
  *
@@ -8,7 +12,7 @@ const DEFAULT_VIEWER_URL = "https://web.geolibre.app/";
  * uses this value only for {version} URL templates and project metadata.
  */
 export const GEOLIBRE_CONFIG = Object.freeze({
-  version: process.env.REACT_APP_GEOLIBRE_VERSION || "2.2.0",
+  version: process.env.REACT_APP_GEOLIBRE_VERSION || DEFAULT_GEOLIBRE_VERSION,
   minimumCompatibleVersion: "2.0.0",
   supportedMajorVersion: 2,
   viewerUrlTemplate:
@@ -38,6 +42,7 @@ const compareVersions = (left, right) => {
 
 export const resolveGeoLibreViewer = (config = GEOLIBRE_CONFIG) => {
   const version = String(config.version).replace(/^v/, "");
+  const versionPinned = config.viewerUrlTemplate.includes("{version}");
   const resolvedTemplate = config.viewerUrlTemplate.replaceAll(
     "{version}",
     version
@@ -45,7 +50,7 @@ export const resolveGeoLibreViewer = (config = GEOLIBRE_CONFIG) => {
   const url = new URL(resolvedTemplate);
   url.searchParams.set("embed", "1");
   url.searchParams.set("welcome", "0");
-  return { url: url.toString(), origin: url.origin };
+  return { url: url.toString(), origin: url.origin, versionPinned };
 };
 
 export const geoLibreVersionStatus = (
diff --git a/src/config/geolibre.config.test.js b/src/config/geolibre.config.test.js
index ef7691b8..e0667c6d 100644
--- a/src/config/geolibre.config.test.js
+++ b/src/config/geolibre.config.test.js
@@ -17,9 +17,14 @@ describe("GeoLibre application configuration", () => {
     expect(resolveGeoLibreViewer(config)).toEqual({
       url: "https://viewer.example/geolibre/2.2.0/?embed=1&welcome=0",
       origin: "https://viewer.example",
+      versionPinned: true,
     });
   });
 
+  it("marks the official unversioned deployment as rolling", () => {
+    expect(resolveGeoLibreViewer(GEOLIBRE_CONFIG).versionPinned).toBe(false);
+  });
+
   it("accepts the configured v2.2 viewer", () => {
     expect(geoLibreVersionStatus("2.2.0", config)).toEqual({
       compatible: true,

From 1b2dd14b05316a0e284a0b4a779cb4d7d5793c97 Mon Sep 17 00:00:00 2001
From: amit-spatial <amit.kumar@gramvaani.org>
Date: Wed, 22 Jul 2026 02:15:41 +0000
Subject: [PATCH 4/9] finalize staged GeoLibre integration

---
 .env.example                                  |  15 +-
 README.md                                     |  15 +-
 .../geolibre/GeoLibreFrame.test.jsx           |  23 +++
 src/components/geolibre/README.md             | 124 ++++++++----
 src/components/geolibre/geolibreProject.js    | 181 ++++++++++--------
 .../geolibre/geolibreProject.test.js          |  73 +++++--
 src/components/landing_navbar.jsx             |  51 +++--
 src/components/landing_navbar.test.jsx        |  27 +++
 src/config/geolibre.config.js                 |   6 +-
 src/config/geolibreLayers.js                  |  16 +-
 src/pages/LandscapeExplorer.jsx               |   9 +-
 11 files changed, 379 insertions(+), 161 deletions(-)
 create mode 100644 src/components/landing_navbar.test.jsx

diff --git a/.env.example b/.env.example
index c25f23a3..e0fca5c2 100644
--- a/.env.example
+++ b/.env.example
@@ -1,8 +1,13 @@
-# GeoLibre's official web URL is a rolling deployment. This accepts compatible
-# GeoLibre 2.x releases and displays the version reported by the iframe.
-REACT_APP_GEOLIBRE_VERSION=2.2.0
-REACT_APP_GEOLIBRE_URL=https://web.geolibre.app/
-REACT_APP_GEOLIBRE_STRICT_VERSION=false
+# Required by the existing KYL dashboards as well as /download_layers.
+REACT_APP_API_URL=https://geoserver.core-stack.org/api/v1
+REACT_APP_GEOSERVER_URL=https://geoserver.core-stack.org:8443/geoserver/
+
+# No GeoLibre variables are required for the official rolling deployment.
+# Its tested fallback version and URL live in src/config/geolibre.config.js.
+# Uncomment these only to override that source configuration at build time:
+# REACT_APP_GEOLIBRE_VERSION=2.2.0
+# REACT_APP_GEOLIBRE_URL=https://web.geolibre.app/
+# REACT_APP_GEOLIBRE_STRICT_VERSION=false
 
 # To make the version value select an exact build, deploy GeoLibre at stable
 # versioned paths and use this instead of REACT_APP_GEOLIBRE_URL:
diff --git a/README.md b/README.md
index 68ec8411..64368f89 100755
--- a/README.md
+++ b/README.md
@@ -37,16 +37,17 @@ npm install
 
 ### 3. Environment Variables Setup
 
-Create a .env file in the root directory of the project where the package.json is located.
+Create `.env` from the committed deployable example in the repository root:
 
 ```bash
-touch .env
+cp .env.example .env
 ```
-Add the following variables to .env
+
+The example contains the public API, GeoServer, and optional GeoLibre settings.
+Add deployment-specific keys only when the feature that uses them is required:
+
 ```env
-REACT_APP_API_URL="https://geoserver.core-stack.org/api/v1"
 REACT_APP_GOOGLE_KEY="xxx"
-REACT_APP_GEOSERVER_URL="https://geoserver.core-stack.org:8443/geoserver/"
 
 # Google Analytics
 REACT_APP_GA_MEASUREMENT_ID="xxx"
@@ -56,6 +57,10 @@ REACT_APP_WATERBODYREJ_USERNAME="xxx"
 REACT_APP_WATERBODYREJ_PASSWORD="xxx"
 REACT_APP_BASEURL="https://geoserver.core-stack.org"
 ```
+
+Restart the development server whenever `.env` changes. See
+[`src/components/geolibre/README.md`](src/components/geolibre/README.md) for the
+complete `/download_layers` test and deployment checklist.
 ### 4. Running the Application
 
 ```bash
diff --git a/src/components/geolibre/GeoLibreFrame.test.jsx b/src/components/geolibre/GeoLibreFrame.test.jsx
index a149e031..147472f5 100644
--- a/src/components/geolibre/GeoLibreFrame.test.jsx
+++ b/src/components/geolibre/GeoLibreFrame.test.jsx
@@ -72,4 +72,27 @@ describe("GeoLibre iframe bridge", () => {
       expect.any(String)
     );
   });
+
+  it("replaces the Overview project when background Watersheds are ready", () => {
+    const { rerender } = render(<GeoLibreFrame project={project} />);
+    const frame = screen.getByTitle("GeoLibre GIS workspace");
+    const postMessage = jest.spyOn(frame.contentWindow, "postMessage");
+
+    act(() => announceReady(frame));
+
+    const watershedProject = {
+      ...project,
+      metadata: { layerLoading: { stage: "watersheds" } },
+    };
+    rerender(<GeoLibreFrame project={watershedProject} />);
+
+    expect(postMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: "geolibre:load-project",
+        project: watershedProject,
+        seq: 2,
+      }),
+      "https://web.geolibre.app"
+    );
+  });
 });
diff --git a/src/components/geolibre/README.md b/src/components/geolibre/README.md
index 0968766c..41c3fcfb 100644
--- a/src/components/geolibre/README.md
+++ b/src/components/geolibre/README.md
@@ -1,8 +1,9 @@
 # KYL GeoLibre integration
 
 `/download_layers` is a thin host for GeoLibre. KYL keeps its existing header
-(including **QGIS Documentation**) and gives the rest of the page to a trusted
-GeoLibre iframe. There is no second KYL map, layer selector, or project panel.
+(including **GeoLibre User Guide**, **QGIS Documentation**, and the QML style
+repository fallback) and gives the rest of the page to a trusted GeoLibre
+iframe. There is no second KYL map, layer selector, or project panel.
 
 The implementation targets
 [GeoLibre v2.2.0](https://github.com/opengeos/GeoLibre/releases/tag/v2.2.0)
@@ -12,29 +13,26 @@ and uses its supported embed bridge and WFS project representation.
 
 1. The KYL homepage carries the selected state, district, and tehsil to
    `/download_layers` as query parameters.
-2. `geolibreProject.js` fetches the Socio-Economic WFS layer first and derives
-   the complete tehsil bounding box from its GeoJSON.
-3. It fetches MWS next, followed by the remaining vectors. Duplicate sources
-   (Socio-Economic / Administrative Boundary and MWS / Hydrological Boundary)
-   are fetched once and reused.
-4. Vector layers are represented exactly as GeoLibre 2.2 WFS layers: an
-   embedded `FeatureCollection`, a live `sourcePath`, and
-   `metadata.sourceKind = "wfs-getfeature"`.
-5. WMS layers are configured but hidden, so raster tiles are requested only
-   when a user makes a layer visible in GeoLibre.
-6. The iframe reports `geolibre:ready`; KYL verifies its application version
-   and sends one `geolibre:load-project` message. It then uses GeoLibre 2.2's
-   command bridge to fit the exact bounds against the iframe's real map size.
-
-Only **Socio-Economic Profile** starts visible. Every other layer starts hidden
-with opacity `1`, so turning it on in GeoLibre shows its intended styling rather
-than an invisible zero-opacity layer.
+2. `geolibreProject.js` fetches the shared Overview WFS source once. It creates
+   **Administrative Boundaries** and **Socio-Economic Profile** from that data,
+   derives the complete tehsil bounding box, and immediately opens GeoLibre.
+3. Both Overview layers start visible at opacity `0.8`, in that display order.
+4. While the user can already use the map, KYL downloads the three Watersheds
+   entries in the background. The MWS / Hydrological Boundary duplicate source
+   is fetched once and reused. A second project message adds the hydrated data
+   without showing another KYL loading overlay.
+5. Other vector layers remain listed, hidden, and empty. They make no initial
+   WFS request; use the layer action **Refresh** when that data is needed.
+6. Raster layers remain listed and hidden. WMS tiles are requested only when a
+   user makes a raster visible.
+7. The iframe reports `geolibre:ready`; KYL verifies its application version,
+   sends the current project stage, and fits the exact tehsil bounds.
 
 ## Native layer organization
 
 GeoLibre's own layer panel is ordered top-first as:
 
-1. Overview (Socio-Economic Profile, Administrative Boundaries)
+1. Overview (Administrative Boundaries, Socio-Economic Profile)
 2. Watersheds (MWS and related hydrological layers)
 3. Other vector layers
 4. LULC Level 3, Level 2, and Level 1 by year
@@ -52,14 +50,12 @@ contains the full tehsil rather than a generic India extent.
 
 The default hosted viewer accepts any GeoLibre release from `2.0.0` up to, but
 not including, `3.0.0`. Compatible 2.x hosted upgrades need no KYL code change.
-The one source-code value to update is `DEFAULT_GEOLIBRE_VERSION` in
+The one source-code fallback to update is the version value in
 `../../config/geolibre.config.js`:
 
 ```js
-export const DEFAULT_GEOLIBRE_VERSION = "2.2.0";
-
 export const GEOLIBRE_CONFIG = Object.freeze({
-  version: process.env.REACT_APP_GEOLIBRE_VERSION || DEFAULT_GEOLIBRE_VERSION,
+  version: process.env.REACT_APP_GEOLIBRE_VERSION || "2.2.0",
   minimumCompatibleVersion: "2.0.0",
   supportedMajorVersion: 2,
   // ...
@@ -96,17 +92,22 @@ application.
 |---|---|
 | `../../config/geolibre.config.js` | Viewer application version, URL resolution, strict handshake compatibility |
 | `../../config/geolibreLayers.js` | GeoServer names, all LULC years, QML references, WMS styles, load groups |
-| `geolibreProject.js` | Priority WFS fetching, v2.2 project construction, styles, WMS/WCS references, bbox camera |
+| `geolibreProject.js` | Staged Overview/Watersheds WFS fetching, lazy vector placeholders, styles, WMS/WCS references, bbox camera |
 | `GeoLibreFrame.jsx` | Iframe lifecycle, trusted-origin bridge, version check, loading and failure overlays |
 | `../../pages/LandscapeExplorer.jsx` | Route-to-project orchestration; no duplicate map or layer UI |
 
-The current project contains 45 entries: 13 vector entries (11 distinct WFS
-requests), 24 LULC year/level rasters, and 8 other rasters.
+The current project contains 45 entries: 13 vector entries, 24 LULC year/level
+rasters, and 8 other rasters. Initial startup performs one distinct Overview WFS
+request followed by two distinct Watersheds requests in the background. The
+remaining vector endpoints are not fetched during startup.
 
 ## Styling contract
 
 - Vector QML rules are translated into GeoLibre categorized or expression
   styles. The source QML URL remains in `metadata.corestack.qmlStyleUrl`.
+- If GeoLibre cannot download a required `.qml`, users can download it from the
+  [CoRE Stack QGIS Styles repository](https://github.com/core-stack-org/QGIS-Styles)
+  and load it through QGIS layer properties.
 - Raster QML styles are published as named GeoServer styles and rendered by
   WMS. Their original QML URLs are also retained.
 - Each raster keeps its styled WMS tiles for display and exposes its complete
@@ -124,6 +125,24 @@ Changing only a QML URL does not alter rendered vector symbology; update the
 matching style profile in `geolibreProject.js`. Raster appearance changes must
 be published to the named GeoServer WMS style.
 
+## Fresh-checkout setup
+
+No backend patch, generated project file, vendored GeoLibre bundle, or local
+`.local/` prototype is required. A tester needs this branch and one `.env` file:
+
+```bash
+git fetch origin
+git switch feat/geolibre-cog-download
+git pull --ff-only
+cp .env.example .env
+npm install
+```
+
+The committed `.env.example` provides the public API and GeoServer values needed
+by both the existing KYL dashboard and the GeoLibre route. GeoLibre uses its
+source defaults unless an operator intentionally enables the commented override
+variables. Restart the React development server after any `.env` change.
+
 ## Validation
 
 Focused tests:
@@ -131,7 +150,9 @@ Focused tests:
 ```bash
 CI=true npm test -- --watchAll=false \
   src/config/geolibre.config.test.js \
-  src/components/geolibre/geolibreProject.test.js
+  src/components/geolibre/geolibreProject.test.js \
+  src/components/geolibre/GeoLibreFrame.test.jsx \
+  src/components/landing_navbar.test.jsx
 ```
 
 Build:
@@ -146,12 +167,47 @@ Local demo:
 HOST=0.0.0.0 PORT=3000 BROWSER=none npm start
 ```
 
-Open `http://localhost:3000`, select a state, district, and tehsil, and click
-**Download Layers**. The generated URL can be refreshed or shared on the same
-KYL host because it contains the selected location.
+Check both routes:
+
+1. Open `http://localhost:3000/kyl_dashboard` and confirm there is no
+   `REACT_APP_GEOSERVER_URL is not set` runtime error.
+2. Open `http://localhost:3000`, select a state, district, and tehsil, and click
+   **Download Layers**.
+3. Confirm the GeoLibre badge reports `2.2.0`, the map fits the tehsil, and the
+   Overview panel shows Administrative Boundaries then Socio-Economic Profile,
+   both visible at `0.80`.
+4. Confirm Watersheds populate after the workspace opens while other vectors
+   remain unloaded. Use **Refresh** on a hidden vector to fetch it.
+5. Enable a raster and verify its styled WMS display and **Export → GeoTIFF
+   (COG)** full-coverage download.
+6. Open both documentation buttons and the QML repository fallback.
+
+The generated `/download_layers?state=...&district=...&tehsil=...` URL can be
+refreshed or shared on the same KYL host because the location is URL-backed.
 
 For a release upgrade, verify all of the following before changing the default
 version: the ready handshake reports the expected release, the project loads
-without `geolibre:error`, Socio-Economic is the only visible layer, the full
-tehsil fits, hidden vectors can be enabled, WMS tiles appear when enabled, and
-GeoLibre can save/export the resulting project.
+without `geolibre:error`, both Overview layers are visible at `0.8`, the full
+tehsil fits, Watersheds hydrate, lazy vectors can be refreshed, WMS tiles appear
+when enabled, and GeoLibre can save/export the resulting project.
+
+## Production deployment
+
+The deployment must set `REACT_APP_API_URL` and `REACT_APP_GEOSERVER_URL` before
+running `npm run build`. The current official viewer is a rolling URL. To pin an
+exact self-hosted build, additionally set the three version-template variables
+shown above. GeoServer WFS, WMS, and WCS endpoints must remain reachable from
+the user's browser with CORS enabled, and the site's framing policy must permit
+`https://web.geolibre.app`.
+
+## Future integration options
+
+GeoLibre 2.2 leaves room for deeper work without another KYL map implementation:
+
+- hydrate lazy vectors automatically when their visibility changes;
+- use direct object-store COG URLs for immutable original-file downloads;
+- preconfigure processing models, bookmarks, print layouts, stories, or plugins;
+- expose saved/shareable GeoLibre project files for partner workflows;
+- add direct QML import once GeoLibre's web project/style contract supports it;
+- self-host tested versioned builds so a single version change selects the
+  exact deployed application binary.
diff --git a/src/components/geolibre/geolibreProject.js b/src/components/geolibre/geolibreProject.js
index b3104ef8..bab76dc9 100644
--- a/src/components/geolibre/geolibreProject.js
+++ b/src/components/geolibre/geolibreProject.js
@@ -503,10 +503,13 @@ const buildVectorLayer = ({
   catalogLayer,
   layerName,
   request,
-  data,
+  data = EMPTY_FEATURE_COLLECTION,
   failure,
+  loaded = false,
 }) => {
   const style = layerStyle(catalogLayer);
+  const isOverview = catalogLayer.loadGroup === "overview";
+  const loadState = failure ? "error" : loaded ? "loaded" : "unloaded";
   return {
     id: `corestack-${catalogLayer.id}`,
     name: catalogLayer.label,
@@ -520,16 +523,20 @@ const buildVectorLayer = ({
       outputFormat: request.outputFormat,
       srsName: request.srsName,
     },
-    visible: catalogLayer.id === "demographics",
-    opacity: 1,
+    visible: isOverview,
+    opacity: isOverview ? 0.8 : 1,
     style,
     metadata: {
       featureCount: data.features.length,
       service: "wfs",
       sourceKind: "wfs-getfeature",
       typeName: request.typeName,
+      loadState,
       ...(failure ? { initialLoadError: failure.message } : {}),
-      corestack: coreStackMetadata(catalogLayer, layerName, request.url),
+      corestack: {
+        ...coreStackMetadata(catalogLayer, layerName, request.url),
+        loadState,
+      },
     },
     geojson: data,
     sourcePath: request.url,
@@ -597,6 +604,7 @@ export const buildGeoLibreProject = async ({
   geoserverUrl = process.env.REACT_APP_GEOSERVER_URL || DEFAULT_GEOSERVER_URL,
   signal,
   onProgress = () => {},
+  onInitialProject = () => {},
   fetchFeatureCollection = fetchWfsFeatureCollection,
 }) => {
   if (!state || !district || !tehsil) {
@@ -642,7 +650,12 @@ export const buildGeoLibreProject = async ({
 
     try {
       const data = await requestCache.get(request.url);
-      vectorResults.set(catalogLayer.id, { data, layerName, request });
+      vectorResults.set(catalogLayer.id, {
+        data,
+        layerName,
+        request,
+        loaded: true,
+      });
       return data;
     } catch (error) {
       if (signal?.aborted) throw error;
@@ -663,6 +676,7 @@ export const buildGeoLibreProject = async ({
         layerName,
         request,
         failure,
+        loaded: false,
       });
       return EMPTY_FEATURE_COLLECTION;
     }
@@ -671,9 +685,17 @@ export const buildGeoLibreProject = async ({
   const socioeconomic = GEOLIBRE_VECTOR_LAYERS.find(
     (layer) => layer.id === "demographics"
   );
-  const mws = GEOLIBRE_VECTOR_LAYERS.find((layer) => layer.id === "mws_layers");
+  const administrative = GEOLIBRE_VECTOR_LAYERS.find(
+    (layer) => layer.id === "administrative_boundaries"
+  );
+  const watershedLayers = GEOLIBRE_VECTOR_LAYERS.filter(
+    (layer) => layer.loadGroup === "watersheds"
+  );
 
   const socioeconomicData = await loadVector(socioeconomic, true);
+  // Both Overview entries use the same GeoServer source. The request cache
+  // makes this a metadata/style duplication, not a second network download.
+  await loadVector(administrative, true, false);
   const bounds = geoJsonBounds(socioeconomicData);
   if (!bounds) {
     throw new Error(
@@ -681,79 +703,86 @@ export const buildGeoLibreProject = async ({
     );
   }
 
-  await loadVector(mws);
-  const remainingVectors = GEOLIBRE_VECTOR_LAYERS.filter(
-    (layer) => layer.id !== socioeconomic.id && layer.id !== mws.id
-  );
+  const createProject = (stage) => {
+    const layers = GEOLIBRE_LAYERS.map((catalogLayer) => {
+      const layerName = catalogLayer.layerName(scope);
+      if (catalogLayer.sourceType === "wfs") {
+        const result = vectorResults.get(catalogLayer.id);
+        return buildVectorLayer({
+          catalogLayer,
+          layerName,
+          ...(result || {
+            data: EMPTY_FEATURE_COLLECTION,
+            request: buildWfsRequest(baseUrl, catalogLayer, layerName),
+            loaded: false,
+          }),
+        });
+      }
+      return buildRasterLayer({ catalogLayer, layerName, baseUrl, bounds });
+    });
+    const orderedLayers = orderGeoLibreLayers(layers);
+    const styles = Object.fromEntries(
+      orderedLayers.map((layer) => [layer.id, layer.style])
+    );
+    const viewer = resolveGeoLibreViewer();
+
+    return {
+      version: GEOLIBRE_PROJECT_FORMAT_VERSION,
+      name: `${tehsil}, ${district}: CoRE Stack landscape`,
+      mapView: mapViewFromBounds(bounds, viewport),
+      basemapStyleUrl: DEFAULT_BASEMAP_STYLE,
+      basemapVisible: true,
+      basemapOpacity: 1,
+      layers: orderedLayers,
+      layerGroups: GROUPS_TOP_FIRST.map((group) => ({
+        ...group,
+        visible: true,
+        opacity: 1,
+      })),
+      styles,
+      preferences: projectPreferences,
+      legend: {
+        title: `${tehsil} landscape layers`,
+        groupByLayer: true,
+        order: [...orderedLayers].reverse().map((layer) => layer.id),
+        overrides: {},
+      },
+      metadata: {
+        generatedAtUtc: new Date().toISOString(),
+        generatedBy: "Know Your Landscape",
+        scope: { level: "tehsil", state, district, tehsil, bounds },
+        geolibre: {
+          applicationVersion: GEOLIBRE_CONFIG.version,
+          projectFormatVersion: GEOLIBRE_PROJECT_FORMAT_VERSION,
+          viewerUrl: viewer.url,
+        },
+        layerLoading: {
+          stage,
+          order: [
+            "Administrative Boundaries and Socio-Economic Profile",
+            "Watersheds in the background",
+            "Other vector layers on manual Refresh",
+            "Raster tiles on visibility toggle",
+          ],
+          initialLoadFailures: [...failures],
+        },
+        qmlStyleContract:
+          "Vector QML symbology is represented in GeoLibre styles. Raster QML symbology is rendered by named GeoServer WMS styles. Original QML URLs are retained per layer.",
+      },
+    };
+  };
+
+  onProgress({ phase: "project", message: "Opening Overview in GeoLibre…" });
+  const initialProject = createProject("overview");
+  onInitialProject(initialProject);
+
   onProgress({
-    phase: "vectors",
-    message: `Loading ${remainingVectors.length} supporting vector layers…`,
+    phase: "watersheds",
+    message: "Loading Watersheds in the background…",
   });
   await Promise.all(
-    remainingVectors.map((layer) => loadVector(layer, false, false))
-  );
-
-  onProgress({ phase: "project", message: "Preparing the GeoLibre project…" });
-  const layers = GEOLIBRE_LAYERS.map((catalogLayer) => {
-    const layerName = catalogLayer.layerName(scope);
-    if (catalogLayer.sourceType === "wfs") {
-      return buildVectorLayer({
-        catalogLayer,
-        layerName,
-        ...vectorResults.get(catalogLayer.id),
-      });
-    }
-    return buildRasterLayer({ catalogLayer, layerName, baseUrl, bounds });
-  });
-  const orderedLayers = orderGeoLibreLayers(layers);
-  const styles = Object.fromEntries(
-    orderedLayers.map((layer) => [layer.id, layer.style])
+    watershedLayers.map((layer) => loadVector(layer, false, false))
   );
-  const viewer = resolveGeoLibreViewer();
 
-  return {
-    version: GEOLIBRE_PROJECT_FORMAT_VERSION,
-    name: `${tehsil}, ${district}: CoRE Stack landscape`,
-    mapView: mapViewFromBounds(bounds, viewport),
-    basemapStyleUrl: DEFAULT_BASEMAP_STYLE,
-    basemapVisible: true,
-    basemapOpacity: 1,
-    layers: orderedLayers,
-    layerGroups: GROUPS_TOP_FIRST.map((group) => ({
-      ...group,
-      visible: true,
-      opacity: 1,
-    })),
-    styles,
-    preferences: projectPreferences,
-    legend: {
-      title: `${tehsil} landscape layers`,
-      groupByLayer: true,
-      order: [...orderedLayers].reverse().map((layer) => layer.id),
-      overrides: {},
-    },
-    metadata: {
-      generatedAtUtc: new Date().toISOString(),
-      generatedBy: "Know Your Landscape",
-      scope: { level: "tehsil", state, district, tehsil, bounds },
-      geolibre: {
-        applicationVersion: GEOLIBRE_CONFIG.version,
-        projectFormatVersion: GEOLIBRE_PROJECT_FORMAT_VERSION,
-        viewerUrl: viewer.url,
-      },
-      layerLoading: {
-        order: [
-          "Socio-Economic Profile",
-          "Micro-watersheds",
-          "Other vector layers",
-          "Latest LULC layers",
-          "Historical LULC layers",
-          "Other raster layers on visibility toggle",
-        ],
-        initialLoadFailures: failures,
-      },
-      qmlStyleContract:
-        "Vector QML symbology is represented in GeoLibre styles. Raster QML symbology is rendered by named GeoServer WMS styles. Original QML URLs are retained per layer.",
-    },
-  };
+  return createProject("watersheds");
 };
diff --git a/src/components/geolibre/geolibreProject.test.js b/src/components/geolibre/geolibreProject.test.js
index 90edf8f9..cc8744fb 100644
--- a/src/components/geolibre/geolibreProject.test.js
+++ b/src/components/geolibre/geolibreProject.test.js
@@ -64,7 +64,7 @@ describe("GeoLibre 2.2 project generation", () => {
     );
   });
 
-  it("builds embedded WFS layers and downloadable, lazy styled rasters", async () => {
+  it("builds staged WFS layers and downloadable, lazy styled rasters", async () => {
     const project = await buildGeoLibreProject({
       ...location,
       fetchFeatureCollection: successfulFetch,
@@ -81,7 +81,7 @@ describe("GeoLibre 2.2 project generation", () => {
     expect(socioeconomic).toMatchObject({
       type: "geojson",
       visible: true,
-      opacity: 1,
+      opacity: 0.8,
       source: {
         type: "geojson",
         service: "wfs",
@@ -92,6 +92,7 @@ describe("GeoLibre 2.2 project generation", () => {
         sourceKind: "wfs-getfeature",
         service: "wfs",
         featureCount: 1,
+        loadState: "loaded",
       },
     });
     expect(socioeconomic.geojson.type).toBe("FeatureCollection");
@@ -99,8 +100,33 @@ describe("GeoLibre 2.2 project generation", () => {
     const visibleLayers = project.layers.filter((layer) => layer.visible);
     expect(visibleLayers.map((layer) => layer.id)).toEqual([
       "corestack-demographics",
+      "corestack-administrative_boundaries",
     ]);
-    expect(project.layers.every((layer) => layer.opacity === 1)).toBe(true);
+    expect(
+      visibleLayers.every((layer) => layer.opacity === 0.8)
+    ).toBe(true);
+    expect(
+      project.layers
+        .filter((layer) => !layer.visible)
+        .every((layer) => layer.opacity === 1)
+    ).toBe(true);
+
+    const mws = project.layers.find(
+      (layer) => layer.id === "corestack-mws_layers"
+    );
+    expect(mws).toMatchObject({
+      visible: false,
+      metadata: { loadState: "loaded", featureCount: 1 },
+    });
+
+    const drainage = project.layers.find(
+      (layer) => layer.id === "corestack-drainage"
+    );
+    expect(drainage).toMatchObject({
+      visible: false,
+      metadata: { loadState: "unloaded", featureCount: 0 },
+      geojson: { type: "FeatureCollection", features: [] },
+    });
 
     const latestLulc = project.layers.find(
       (layer) => layer.id === "corestack-lulc_level_3_24_25"
@@ -141,8 +167,8 @@ describe("GeoLibre 2.2 project generation", () => {
       .map((layer) => layer.id);
 
     expect(displayIds.slice(0, 5)).toEqual([
-      "corestack-demographics",
       "corestack-administrative_boundaries",
+      "corestack-demographics",
       "corestack-mws_layers",
       "corestack-hydrological_boundaries",
       "corestack-mws_layers_fortnight",
@@ -164,24 +190,42 @@ describe("GeoLibre 2.2 project generation", () => {
     ]);
   });
 
-  it("fetches socioeconomic first, MWS second, and reuses duplicate WFS requests", async () => {
+  it("opens Overview first, then loads Watersheds with duplicate WFS reuse", async () => {
+    const onInitialProject = jest.fn();
     await buildGeoLibreProject({
       ...location,
       fetchFeatureCollection: successfulFetch,
+      onInitialProject,
     });
 
+    expect(onInitialProject).toHaveBeenCalledTimes(1);
+    const initialProject = onInitialProject.mock.calls[0][0];
+    expect(initialProject.metadata.layerLoading.stage).toBe("overview");
+    expect(
+      initialProject.layers.find(
+        (layer) => layer.id === "corestack-mws_layers"
+      ).metadata.loadState
+    ).toBe("unloaded");
+    expect(
+      initialProject.layers
+        .filter((layer) => layer.visible)
+        .map((layer) => layer.id)
+    ).toEqual([
+      "corestack-demographics",
+      "corestack-administrative_boundaries",
+    ]);
     expect(successfulFetch.mock.calls[0][0].typeName).toBe(
       "panchayat_boundaries:cachar_lakhipur"
     );
     expect(successfulFetch.mock.calls[1][0].typeName).toBe(
       "mws_layers:deltaG_well_depth_cachar_lakhipur"
     );
-    expect(successfulFetch).toHaveBeenCalledTimes(11);
+    expect(successfulFetch).toHaveBeenCalledTimes(3);
   });
 
-  it("keeps an unavailable optional vector listed for GeoLibre refresh", async () => {
-    const fetchWithDrainageFailure = jest.fn(async (request) => {
-      if (request.typeName.startsWith("drainage:")) {
+  it("keeps an unavailable background Watershed listed for GeoLibre refresh", async () => {
+    const fetchWithWatershedFailure = jest.fn(async (request) => {
+      if (request.typeName.includes("deltaG_fortnight")) {
         throw new Error("temporary outage");
       }
       return polygonFeatureCollection(request);
@@ -189,15 +233,16 @@ describe("GeoLibre 2.2 project generation", () => {
 
     const project = await buildGeoLibreProject({
       ...location,
-      fetchFeatureCollection: fetchWithDrainageFailure,
+      fetchFeatureCollection: fetchWithWatershedFailure,
     });
-    const drainage = project.layers.find(
-      (layer) => layer.id === "corestack-drainage"
+    const fortnightly = project.layers.find(
+      (layer) => layer.id === "corestack-mws_layers_fortnight"
     );
 
-    expect(drainage.geojson.features).toEqual([]);
-    expect(drainage.metadata).toMatchObject({
+    expect(fortnightly.geojson.features).toEqual([]);
+    expect(fortnightly.metadata).toMatchObject({
       sourceKind: "wfs-getfeature",
+      loadState: "error",
       initialLoadError: "temporary outage",
     });
     expect(project.metadata.layerLoading.initialLoadFailures).toHaveLength(1);
diff --git a/src/components/landing_navbar.jsx b/src/components/landing_navbar.jsx
index 3765fc29..d39f6c34 100644
--- a/src/components/landing_navbar.jsx
+++ b/src/components/landing_navbar.jsx
@@ -40,17 +40,44 @@ const LandingNavbar = () => {
 
           <div className="flex flex-wrap gap-3 items-center justify-center">
             {isDownloadPage && (
-              <a
-                href="https://docs.google.com/document/d/1jet4EEBbbKgpNrPnuNJJDRuAJUiR2pIMFQp9JTlygAQ/edit?usp=sharing"
-                target="_blank"
-                rel="noopener noreferrer"
-                className="flex items-center gap-2 px-4 py-2 rounded-lg bg-purple-50 hover:bg-purple-100 transition-all duration-200 border border-purple-200 group"
-              >
-                <span className="text-sm sm:text-base font-medium text-purple-700 group-hover:text-purple-800">
-                  QGIS Documentation
-                </span>
-                <ExternalLink className="h-4 w-4 text-purple-600 group-hover:scale-110 transition-transform" />
-              </a>
+              <div className="flex flex-col items-center gap-1 sm:items-end">
+                <div className="flex flex-wrap items-center justify-center gap-2 sm:justify-end">
+                  <a
+                    href="https://geolibre.app/user-guide/interface/"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="flex items-center gap-2 rounded-lg border border-purple-200 bg-purple-50 px-4 py-2 transition-all duration-200 hover:bg-purple-100 group"
+                  >
+                    <span className="text-sm font-medium text-purple-700 group-hover:text-purple-800 sm:text-base">
+                      GeoLibre User Guide
+                    </span>
+                    <ExternalLink className="h-4 w-4 text-purple-600 transition-transform group-hover:scale-110" />
+                  </a>
+                  <a
+                    href="https://docs.google.com/document/d/1jet4EEBbbKgpNrPnuNJJDRuAJUiR2pIMFQp9JTlygAQ/edit?usp=sharing"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="flex items-center gap-2 rounded-lg border border-purple-200 bg-purple-50 px-4 py-2 transition-all duration-200 hover:bg-purple-100 group"
+                  >
+                    <span className="text-sm font-medium text-purple-700 group-hover:text-purple-800 sm:text-base">
+                      QGIS Documentation
+                    </span>
+                    <ExternalLink className="h-4 w-4 text-purple-600 transition-transform group-hover:scale-110" />
+                  </a>
+                </div>
+                <p className="text-center text-xs text-slate-600 sm:text-right">
+                  Can&apos;t download a QML style in GeoLibre? Get it from the{" "}
+                  <a
+                    href="https://github.com/core-stack-org/QGIS-Styles"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="font-medium text-purple-700 underline decoration-purple-300 underline-offset-2 hover:text-purple-900"
+                  >
+                    CoRE Stack QGIS Styles repository
+                  </a>
+                  .
+                </p>
+              </div>
             )}
 
             {isHomePage && (
@@ -111,4 +138,4 @@ const LandingNavbar = () => {
   );
 };
 
-export default LandingNavbar;
\ No newline at end of file
+export default LandingNavbar;
diff --git a/src/components/landing_navbar.test.jsx b/src/components/landing_navbar.test.jsx
new file mode 100644
index 00000000..386bcd43
--- /dev/null
+++ b/src/components/landing_navbar.test.jsx
@@ -0,0 +1,27 @@
+import { render, screen } from "@testing-library/react";
+import LandingNavbar from "./landing_navbar";
+
+jest.mock(
+  "react-router-dom",
+  () => ({ useLocation: () => ({ pathname: "/download_layers" }) }),
+  { virtual: true }
+);
+
+describe("Download Layers navigation", () => {
+  it("links to GeoLibre, QGIS, and the QML style fallback", () => {
+    render(<LandingNavbar />);
+
+    expect(
+      screen.getByRole("link", { name: /GeoLibre User Guide/i })
+        .getAttribute("href")
+    ).toBe("https://geolibre.app/user-guide/interface/");
+    expect(
+      screen.getByRole("link", { name: /QGIS Documentation/i })
+        .getAttribute("href")
+    ).toContain("docs.google.com/document");
+    expect(
+      screen.getByRole("link", { name: /CoRE Stack QGIS Styles repository/i })
+        .getAttribute("href")
+    ).toBe("https://github.com/core-stack-org/QGIS-Styles");
+  });
+});
diff --git a/src/config/geolibre.config.js b/src/config/geolibre.config.js
index 9d1066d5..2ffeba52 100644
--- a/src/config/geolibre.config.js
+++ b/src/config/geolibre.config.js
@@ -1,9 +1,5 @@
 const DEFAULT_VIEWER_URL = "https://web.geolibre.app/";
 
-// Change this one value when KYL moves to another tested GeoLibre release.
-// It selects the deployed build only when viewerUrlTemplate contains {version}.
-export const DEFAULT_GEOLIBRE_VERSION = "2.2.0";
-
 /**
  * The preferred GeoLibre application version for a versioned deployment.
  *
@@ -12,7 +8,7 @@ export const DEFAULT_GEOLIBRE_VERSION = "2.2.0";
  * uses this value only for {version} URL templates and project metadata.
  */
 export const GEOLIBRE_CONFIG = Object.freeze({
-  version: process.env.REACT_APP_GEOLIBRE_VERSION || DEFAULT_GEOLIBRE_VERSION,
+  version: process.env.REACT_APP_GEOLIBRE_VERSION || "2.2.0",
   minimumCompatibleVersion: "2.0.0",
   supportedMajorVersion: 2,
   viewerUrlTemplate:
diff --git a/src/config/geolibreLayers.js b/src/config/geolibreLayers.js
index a5f8c39a..d8647f0c 100644
--- a/src/config/geolibreLayers.js
+++ b/src/config/geolibreLayers.js
@@ -19,28 +19,28 @@ export const LATEST_GEOLIBRE_LULC_YEAR =
 
 const LAYERS = [
   {
-    id: "demographics",
-    label: "Socio-Economic Profile",
+    id: "administrative_boundaries",
+    label: "Administrative Boundaries",
     domain: "Demographic",
     loadGroup: "overview",
     sourceType: "wfs",
     workspace: "panchayat_boundaries",
     geometryType: "polygon",
     layerName: ({ district, tehsil }) => `${district}_${tehsil}`,
-    styleProfile: "demographics",
-    qmlStyleUrl: qmlStyle("Demographic/literary_rate_style.qml"),
+    styleProfile: "boundary",
+    qmlStyleUrl: qmlStyle("Demographic/Administrative-Boundary-Style.qml"),
   },
   {
-    id: "administrative_boundaries",
-    label: "Administrative Boundaries",
+    id: "demographics",
+    label: "Socio-Economic Profile",
     domain: "Demographic",
     loadGroup: "overview",
     sourceType: "wfs",
     workspace: "panchayat_boundaries",
     geometryType: "polygon",
     layerName: ({ district, tehsil }) => `${district}_${tehsil}`,
-    styleProfile: "boundary",
-    qmlStyleUrl: qmlStyle("Demographic/Administrative-Boundary-Style.qml"),
+    styleProfile: "demographics",
+    qmlStyleUrl: qmlStyle("Demographic/literary_rate_style.qml"),
   },
   {
     id: "mws_layers",
diff --git a/src/pages/LandscapeExplorer.jsx b/src/pages/LandscapeExplorer.jsx
index 8968cd9e..01dd5b70 100644
--- a/src/pages/LandscapeExplorer.jsx
+++ b/src/pages/LandscapeExplorer.jsx
@@ -65,12 +65,17 @@ const LandscapeExplorer = () => {
       onProgress: ({ message }) => {
         if (!controller.signal.aborted) setProgress(message);
       },
+      onInitialProject: (overviewProject) => {
+        if (controller.signal.aborted) return;
+        setProject(overviewProject);
+        setProgress("Loading Watersheds in the background…");
+        trackEvent("GeoLibre", "open_workspace", scope.tehsil);
+      },
     })
       .then((nextProject) => {
         if (controller.signal.aborted) return;
         setProject(nextProject);
-        setProgress("Opening the tehsil project in GeoLibre…");
-        trackEvent("GeoLibre", "open_workspace", scope.tehsil);
+        setProgress("Overview and Watersheds are ready.");
       })
       .catch((buildError) => {
         if (controller.signal.aborted) return;

From 05541683103ac04e500c81778ea5f84855da21a0 Mon Sep 17 00:00:00 2001
From: amit-spatial <amit.kumar@gramvaani.org>
Date: Wed, 22 Jul 2026 03:02:43 +0000
Subject: [PATCH 5/9] finalize lazy GeoLibre layer loading

---
 src/components/geolibre/GeoLibreFrame.jsx     |  27 +++-
 .../geolibre/GeoLibreFrame.test.jsx           |  45 ++++++-
 src/components/geolibre/README.md             |  62 +++++----
 src/components/geolibre/geolibreProject.js    | 125 +++++++++++++++---
 .../geolibre/geolibreProject.test.js          | 114 +++++++++++-----
 src/components/landing_navbar.jsx             |   2 +-
 src/components/landing_navbar.test.jsx        |   3 +
 src/pages/LandscapeExplorer.jsx               | 109 +++++++++++++--
 8 files changed, 383 insertions(+), 104 deletions(-)

diff --git a/src/components/geolibre/GeoLibreFrame.jsx b/src/components/geolibre/GeoLibreFrame.jsx
index 2c67bc12..41cb9868 100644
--- a/src/components/geolibre/GeoLibreFrame.jsx
+++ b/src/components/geolibre/GeoLibreFrame.jsx
@@ -11,9 +11,11 @@ const GeoLibreFrame = ({
   preparationError,
   warning,
   onRetry,
+  onProjectState,
 }) => {
   const frameRef = useRef(null);
   const fitTimerRef = useRef(null);
+  const fittedScopeRef = useRef("");
   const sentProjectRef = useRef(null);
   const sequenceRef = useRef(0);
   const [viewerState, setViewerState] = useState("loading");
@@ -80,6 +82,11 @@ const GeoLibreFrame = ({
           event.data.message || "GeoLibre could not load the generated project."
         );
         setViewerState("error");
+        return;
+      }
+
+      if (event.data.type === "geolibre:state" && event.data.project) {
+        onProjectState?.(event.data.project);
       }
     };
 
@@ -88,7 +95,7 @@ const GeoLibreFrame = ({
       window.removeEventListener("message", handleMessage);
       if (handshakeTimer !== null) window.clearTimeout(handshakeTimer);
     };
-  }, [viewer.origin, viewer.url]);
+  }, [onProjectState, viewer.origin, viewer.url]);
 
   useEffect(
     () => () => {
@@ -121,11 +128,20 @@ const GeoLibreFrame = ({
       viewer.origin
     );
     sentProjectRef.current = project;
-    if (fitTimerRef.current !== null) {
-      window.clearTimeout(fitTimerRef.current);
-    }
     const bounds = project.mapView?.bbox;
-    if (Array.isArray(bounds) && bounds.length === 4) {
+    const scope = project.metadata?.scope;
+    const scopeKey = scope
+      ? [scope.state, scope.district, scope.tehsil].join("|")
+      : project.name || "default";
+    if (
+      Array.isArray(bounds) &&
+      bounds.length === 4 &&
+      fittedScopeRef.current !== scopeKey
+    ) {
+      fittedScopeRef.current = scopeKey;
+      if (fitTimerRef.current !== null) {
+        window.clearTimeout(fitTimerRef.current);
+      }
       fitTimerRef.current = window.setTimeout(() => {
         target.postMessage(
           {
@@ -157,6 +173,7 @@ const GeoLibreFrame = ({
           allowFullScreen
           data-geolibre-version={viewerVersion || undefined}
           onLoad={() => {
+            fittedScopeRef.current = "";
             setViewerVersion("");
             setViewerState((current) =>
               current === "loaded" ? current : "loading"
diff --git a/src/components/geolibre/GeoLibreFrame.test.jsx b/src/components/geolibre/GeoLibreFrame.test.jsx
index 147472f5..0313bb98 100644
--- a/src/components/geolibre/GeoLibreFrame.test.jsx
+++ b/src/components/geolibre/GeoLibreFrame.test.jsx
@@ -4,6 +4,9 @@ import GeoLibreFrame from "./GeoLibreFrame";
 const project = {
   version: "0.2.0",
   name: "Lakhipur project",
+  metadata: {
+    scope: { state: "Assam", district: "Cachar", tehsil: "Lakhipur" },
+  },
   mapView: {
     center: [93.04, 24.84],
     zoom: 9.6,
@@ -73,26 +76,58 @@ describe("GeoLibre iframe bridge", () => {
     );
   });
 
-  it("replaces the Overview project when background Watersheds are ready", () => {
+  it("reloads a lazily hydrated project without fitting the tehsil again", () => {
     const { rerender } = render(<GeoLibreFrame project={project} />);
     const frame = screen.getByTitle("GeoLibre GIS workspace");
     const postMessage = jest.spyOn(frame.contentWindow, "postMessage");
 
     act(() => announceReady(frame));
+    act(() => jest.advanceTimersByTime(1500));
 
-    const watershedProject = {
+    const hydratedProject = {
       ...project,
-      metadata: { layerLoading: { stage: "watersheds" } },
+      layers: [{ id: "corestack-drainage", visible: true }],
     };
-    rerender(<GeoLibreFrame project={watershedProject} />);
+    rerender(<GeoLibreFrame project={hydratedProject} />);
 
     expect(postMessage).toHaveBeenCalledWith(
       expect.objectContaining({
         type: "geolibre:load-project",
-        project: watershedProject,
+        project: hydratedProject,
         seq: 2,
       }),
       "https://web.geolibre.app"
     );
+    act(() => jest.advanceTimersByTime(1500));
+    expect(
+      postMessage.mock.calls.filter(
+        ([message]) => message.type === "geolibre:command" && message.method === "fitBounds"
+      )
+    ).toHaveLength(1);
+  });
+
+  it("forwards viewer state snapshots for toggle-triggered loading", () => {
+    const onProjectState = jest.fn();
+    render(
+      <GeoLibreFrame project={project} onProjectState={onProjectState} />
+    );
+    const frame = screen.getByTitle("GeoLibre GIS workspace");
+    act(() => announceReady(frame));
+
+    const viewerProject = {
+      ...project,
+      layers: [{ id: "corestack-drainage", visible: true }],
+    };
+    act(() => {
+      window.dispatchEvent(
+        new MessageEvent("message", {
+          origin: "https://web.geolibre.app",
+          source: frame.contentWindow,
+          data: { type: "geolibre:state", project: viewerProject },
+        })
+      );
+    });
+
+    expect(onProjectState).toHaveBeenCalledWith(viewerProject);
   });
 });
diff --git a/src/components/geolibre/README.md b/src/components/geolibre/README.md
index 41c3fcfb..a492295b 100644
--- a/src/components/geolibre/README.md
+++ b/src/components/geolibre/README.md
@@ -17,16 +17,17 @@ and uses its supported embed bridge and WFS project representation.
    **Administrative Boundaries** and **Socio-Economic Profile** from that data,
    derives the complete tehsil bounding box, and immediately opens GeoLibre.
 3. Both Overview layers start visible at opacity `0.8`, in that display order.
-4. While the user can already use the map, KYL downloads the three Watersheds
-   entries in the background. The MWS / Hydrological Boundary duplicate source
-   is fetched once and reused. A second project message adds the hydrated data
-   without showing another KYL loading overlay.
-5. Other vector layers remain listed, hidden, and empty. They make no initial
-   WFS request; use the layer action **Refresh** when that data is needed.
-6. Raster layers remain listed and hidden. WMS tiles are requested only when a
-   user makes a raster visible.
-7. The iframe reports `geolibre:ready`; KYL verifies its application version,
-   sends the current project stage, and fits the exact tehsil bounds.
+4. Every vector outside Overview—including all Watersheds—starts listed,
+   hidden, and empty. Its first visibility toggle asks KYL to fetch that WFS
+   source and send the hydrated layer back to GeoLibre. The hydrated layer is
+   retained, so later off/on toggles do not repeat its WFS request.
+5. Raster layers also start listed and hidden. GeoLibre requests their styled
+   WMS tiles only after the first visibility toggle and retains the live raster
+   source for later toggles; normal browser and MapLibre tile caches reuse tiles
+   that have already been fetched.
+6. The iframe reports `geolibre:ready`; KYL verifies its application version,
+   sends the Overview project, and fits the exact tehsil bounds once. Lazy
+   project updates preserve the user's live map view and never fit it again.
 
 ## Native layer organization
 
@@ -38,13 +39,15 @@ GeoLibre's own layer panel is ordered top-first as:
 4. LULC Level 3, Level 2, and Level 1 by year
 5. Other raster layers
 
-The non-overview groups are collapsed where appropriate. Each LULC group shows
-2024-2025 first while retaining every available year back to 2017-2018.
+The non-overview groups are collapsed where appropriate. Every layer outside
+Overview is toggle-to-load. Each LULC group shows 2024-2025 first while
+retaining every available year back to 2017-2018.
 
 The project camera is calculated from the Socio-Economic geometry using a
 padded Web Mercator fit. `mapView.bbox` is also retained in project metadata,
-and the iframe receives a `fitBounds` command after loading, so the initial map
-contains the full tehsil rather than a generic India extent.
+and the iframe receives one `fitBounds` command after its initial load, so the
+initial map contains the full tehsil rather than a generic India extent. Layer
+toggles and lazy hydration do not issue another fit command.
 
 ## Version configuration
 
@@ -92,22 +95,23 @@ application.
 |---|---|
 | `../../config/geolibre.config.js` | Viewer application version, URL resolution, strict handshake compatibility |
 | `../../config/geolibreLayers.js` | GeoServer names, all LULC years, QML references, WMS styles, load groups |
-| `geolibreProject.js` | Staged Overview/Watersheds WFS fetching, lazy vector placeholders, styles, WMS/WCS references, bbox camera |
-| `GeoLibreFrame.jsx` | Iframe lifecycle, trusted-origin bridge, version check, loading and failure overlays |
-| `../../pages/LandscapeExplorer.jsx` | Route-to-project orchestration; no duplicate map or layer UI |
+| `geolibreProject.js` | Overview generation, single-vector hydration, lazy placeholders, styles, WMS/WCS references, bbox camera |
+| `GeoLibreFrame.jsx` | Iframe lifecycle, trusted-origin bridge, state events, one-time bbox fit, version and failure handling |
+| `../../pages/LandscapeExplorer.jsx` | Route-to-project orchestration and fetch-on-first-toggle vector cache; no duplicate map or layer UI |
 
 The current project contains 45 entries: 13 vector entries, 24 LULC year/level
-rasters, and 8 other rasters. Initial startup performs one distinct Overview WFS
-request followed by two distinct Watersheds requests in the background. The
-remaining vector endpoints are not fetched during startup.
+rasters, and 8 other rasters. Initial startup performs exactly one distinct WFS
+request for the shared Overview data and no WMS request. Each non-Overview
+vector makes its own WFS request only on its first toggle. Hidden rasters make
+no WMS tile request.
 
 ## Styling contract
 
 - Vector QML rules are translated into GeoLibre categorized or expression
   styles. The source QML URL remains in `metadata.corestack.qmlStyleUrl`.
-- If GeoLibre cannot download a required `.qml`, users can download it from the
+- To use these layers with QGIS, download layer styles from the
   [CoRE Stack QGIS Styles repository](https://github.com/core-stack-org/QGIS-Styles)
-  and load it through QGIS layer properties.
+  and load them through QGIS layer properties.
 - Raster QML styles are published as named GeoServer styles and rendered by
   WMS. Their original QML URLs are also retained.
 - Each raster keeps its styled WMS tiles for display and exposes its complete
@@ -176,9 +180,11 @@ Check both routes:
 3. Confirm the GeoLibre badge reports `2.2.0`, the map fits the tehsil, and the
    Overview panel shows Administrative Boundaries then Socio-Economic Profile,
    both visible at `0.80`.
-4. Confirm Watersheds populate after the workspace opens while other vectors
-   remain unloaded. Use **Refresh** on a hidden vector to fetch it.
-5. Enable a raster and verify its styled WMS display and **Export → GeoTIFF
+4. Confirm no Watershed or other non-Overview layer loads by itself. Toggle one
+   Watershed and one **Other vector layer** and confirm each loads. Toggle each
+   off and on again and confirm its WFS request is not repeated.
+5. Confirm the map does not refit after those vector loads. Enable a raster and
+   verify its styled WMS display and **Export → GeoTIFF
    (COG)** full-coverage download.
 6. Open both documentation buttons and the QML repository fallback.
 
@@ -188,8 +194,9 @@ refreshed or shared on the same KYL host because the location is URL-backed.
 For a release upgrade, verify all of the following before changing the default
 version: the ready handshake reports the expected release, the project loads
 without `geolibre:error`, both Overview layers are visible at `0.8`, the full
-tehsil fits, Watersheds hydrate, lazy vectors can be refreshed, WMS tiles appear
-when enabled, and GeoLibre can save/export the resulting project.
+tehsil fits exactly once, Watersheds and other vectors hydrate only when
+toggled and are then reused, WMS tiles appear only when enabled, and GeoLibre
+can save/export the resulting project.
 
 ## Production deployment
 
@@ -204,7 +211,6 @@ the user's browser with CORS enabled, and the site's framing policy must permit
 
 GeoLibre 2.2 leaves room for deeper work without another KYL map implementation:
 
-- hydrate lazy vectors automatically when their visibility changes;
 - use direct object-store COG URLs for immutable original-file downloads;
 - preconfigure processing models, bookmarks, print layouts, stories, or plugins;
 - expose saved/shareable GeoLibre project files for partner workflows;
diff --git a/src/components/geolibre/geolibreProject.js b/src/components/geolibre/geolibreProject.js
index bab76dc9..66288b8f 100644
--- a/src/components/geolibre/geolibreProject.js
+++ b/src/components/geolibre/geolibreProject.js
@@ -596,6 +596,105 @@ export const orderGeoLibreLayers = (layers) => {
 const readableError = (error) =>
   error instanceof Error ? error.message : String(error);
 
+const replaceProjectLayer = (project, layerId, replacement) => ({
+  ...project,
+  layers: project.layers.map((layer) =>
+    layer.id === layerId ? replacement : layer
+  ),
+});
+
+const withLazyLoadFailure = (project, layerId, failure) => {
+  const layerLoading = project.metadata?.layerLoading || {};
+  const remainingFailures = (layerLoading.lazyLoadFailures || []).filter(
+    (item) => item.layerId !== layerId
+  );
+  return {
+    ...project,
+    metadata: {
+      ...project.metadata,
+      layerLoading: {
+        ...layerLoading,
+        lazyLoadFailures: failure
+          ? [...remainingFailures, failure]
+          : remainingFailures,
+      },
+    },
+  };
+};
+
+export const hydrateGeoLibreVectorLayer = async ({
+  project,
+  layerId,
+  signal,
+  fetchFeatureCollection = fetchWfsFeatureCollection,
+}) => {
+  const layer = project?.layers?.find((item) => item.id === layerId);
+  if (!layer || layer.type !== "geojson") {
+    throw new Error(`GeoLibre vector layer ${layerId} is not available.`);
+  }
+  if (layer.metadata?.loadState === "loaded") return project;
+
+  const request = {
+    url: layer.source?.url,
+    typeName: layer.source?.typeName,
+    version: layer.source?.version,
+    outputFormat: layer.source?.outputFormat,
+    srsName: layer.source?.srsName,
+  };
+  if (!request.url) {
+    throw new Error(`GeoLibre vector layer ${layer.name} has no WFS URL.`);
+  }
+
+  try {
+    const data = await fetchFeatureCollection(request, { signal });
+    const { initialLoadError: _initialLoadError, ...metadata } =
+      layer.metadata || {};
+    const hydratedLayer = {
+      ...layer,
+      geojson: data,
+      metadata: {
+        ...metadata,
+        featureCount: data.features.length,
+        loadState: "loaded",
+        corestack: {
+          ...metadata.corestack,
+          loadState: "loaded",
+        },
+      },
+    };
+    return withLazyLoadFailure(
+      replaceProjectLayer(project, layerId, hydratedLayer),
+      layerId,
+      null
+    );
+  } catch (error) {
+    if (signal?.aborted) throw error;
+    const failure = {
+      layerId,
+      layerName: layer.name,
+      sourceUrl: request.url,
+      message: readableError(error),
+    };
+    const failedLayer = {
+      ...layer,
+      metadata: {
+        ...layer.metadata,
+        loadState: "error",
+        initialLoadError: failure.message,
+        corestack: {
+          ...layer.metadata?.corestack,
+          loadState: "error",
+        },
+      },
+    };
+    return withLazyLoadFailure(
+      replaceProjectLayer(project, layerId, failedLayer),
+      layerId,
+      failure
+    );
+  }
+};
+
 export const buildGeoLibreProject = async ({
   state,
   district,
@@ -604,7 +703,6 @@ export const buildGeoLibreProject = async ({
   geoserverUrl = process.env.REACT_APP_GEOSERVER_URL || DEFAULT_GEOSERVER_URL,
   signal,
   onProgress = () => {},
-  onInitialProject = () => {},
   fetchFeatureCollection = fetchWfsFeatureCollection,
 }) => {
   if (!state || !district || !tehsil) {
@@ -688,10 +786,6 @@ export const buildGeoLibreProject = async ({
   const administrative = GEOLIBRE_VECTOR_LAYERS.find(
     (layer) => layer.id === "administrative_boundaries"
   );
-  const watershedLayers = GEOLIBRE_VECTOR_LAYERS.filter(
-    (layer) => layer.loadGroup === "watersheds"
-  );
-
   const socioeconomicData = await loadVector(socioeconomic, true);
   // Both Overview entries use the same GeoServer source. The request cache
   // makes this a metadata/style duplication, not a second network download.
@@ -703,7 +797,7 @@ export const buildGeoLibreProject = async ({
     );
   }
 
-  const createProject = (stage) => {
+  const createProject = () => {
     const layers = GEOLIBRE_LAYERS.map((catalogLayer) => {
       const layerName = catalogLayer.layerName(scope);
       if (catalogLayer.sourceType === "wfs") {
@@ -757,14 +851,14 @@ export const buildGeoLibreProject = async ({
           viewerUrl: viewer.url,
         },
         layerLoading: {
-          stage,
+          stage: "overview",
           order: [
             "Administrative Boundaries and Socio-Economic Profile",
-            "Watersheds in the background",
-            "Other vector layers on manual Refresh",
+            "Other vector layers on first visibility toggle",
             "Raster tiles on visibility toggle",
           ],
           initialLoadFailures: [...failures],
+          lazyLoadFailures: [],
         },
         qmlStyleContract:
           "Vector QML symbology is represented in GeoLibre styles. Raster QML symbology is rendered by named GeoServer WMS styles. Original QML URLs are retained per layer.",
@@ -773,16 +867,5 @@ export const buildGeoLibreProject = async ({
   };
 
   onProgress({ phase: "project", message: "Opening Overview in GeoLibre…" });
-  const initialProject = createProject("overview");
-  onInitialProject(initialProject);
-
-  onProgress({
-    phase: "watersheds",
-    message: "Loading Watersheds in the background…",
-  });
-  await Promise.all(
-    watershedLayers.map((layer) => loadVector(layer, false, false))
-  );
-
-  return createProject("watersheds");
+  return createProject();
 };
diff --git a/src/components/geolibre/geolibreProject.test.js b/src/components/geolibre/geolibreProject.test.js
index cc8744fb..b82218cf 100644
--- a/src/components/geolibre/geolibreProject.test.js
+++ b/src/components/geolibre/geolibreProject.test.js
@@ -2,6 +2,7 @@ import {
   buildGeoLibreProject,
   formatGeoServerName,
   geoJsonBounds,
+  hydrateGeoLibreVectorLayer,
   mapViewFromBounds,
 } from "./geolibreProject";
 import { GEOLIBRE_LAYERS } from "../../config/geolibreLayers";
@@ -64,7 +65,7 @@ describe("GeoLibre 2.2 project generation", () => {
     );
   });
 
-  it("builds staged WFS layers and downloadable, lazy styled rasters", async () => {
+  it("builds Overview WFS layers and downloadable, lazy styled rasters", async () => {
     const project = await buildGeoLibreProject({
       ...location,
       fetchFeatureCollection: successfulFetch,
@@ -116,7 +117,8 @@ describe("GeoLibre 2.2 project generation", () => {
     );
     expect(mws).toMatchObject({
       visible: false,
-      metadata: { loadState: "loaded", featureCount: 1 },
+      metadata: { loadState: "unloaded", featureCount: 0 },
+      geojson: { type: "FeatureCollection", features: [] },
     });
 
     const drainage = project.layers.find(
@@ -155,6 +157,7 @@ describe("GeoLibre 2.2 project generation", () => {
     expect(latestLulc.source.url).toContain(
       "CoverageId=LULC_level_3%3ALULC_24_25_cachar_lakhipur_level_3"
     );
+    expect(successfulFetch).toHaveBeenCalledTimes(1);
   });
 
   it("orders the native GeoLibre panel by overview, vectors, LULC, then rasters", async () => {
@@ -190,24 +193,27 @@ describe("GeoLibre 2.2 project generation", () => {
     ]);
   });
 
-  it("opens Overview first, then loads Watersheds with duplicate WFS reuse", async () => {
-    const onInitialProject = jest.fn();
-    await buildGeoLibreProject({
+  it("loads only the shared Overview source during project creation", async () => {
+    const project = await buildGeoLibreProject({
       ...location,
       fetchFeatureCollection: successfulFetch,
-      onInitialProject,
     });
 
-    expect(onInitialProject).toHaveBeenCalledTimes(1);
-    const initialProject = onInitialProject.mock.calls[0][0];
-    expect(initialProject.metadata.layerLoading.stage).toBe("overview");
+    expect(project.metadata.layerLoading.stage).toBe("overview");
     expect(
-      initialProject.layers.find(
-        (layer) => layer.id === "corestack-mws_layers"
-      ).metadata.loadState
+      project.layers
+        .filter(
+          (layer) =>
+            layer.type === "geojson" && layer.groupId !== "overview"
+        )
+        .every((layer) => layer.metadata.loadState === "unloaded")
+    ).toBe(true);
+    expect(
+      project.layers.find((layer) => layer.id === "corestack-mws_layers")
+        .metadata.loadState
     ).toBe("unloaded");
     expect(
-      initialProject.layers
+      project.layers
         .filter((layer) => layer.visible)
         .map((layer) => layer.id)
     ).toEqual([
@@ -217,35 +223,77 @@ describe("GeoLibre 2.2 project generation", () => {
     expect(successfulFetch.mock.calls[0][0].typeName).toBe(
       "panchayat_boundaries:cachar_lakhipur"
     );
-    expect(successfulFetch.mock.calls[1][0].typeName).toBe(
-      "mws_layers:deltaG_well_depth_cachar_lakhipur"
-    );
-    expect(successfulFetch).toHaveBeenCalledTimes(3);
+    expect(successfulFetch).toHaveBeenCalledTimes(1);
   });
 
-  it("keeps an unavailable background Watershed listed for GeoLibre refresh", async () => {
-    const fetchWithWatershedFailure = jest.fn(async (request) => {
-      if (request.typeName.includes("deltaG_fortnight")) {
-        throw new Error("temporary outage");
-      }
-      return polygonFeatureCollection(request);
+  it("loads a toggled vector once and reuses its hydrated data", async () => {
+    const project = await buildGeoLibreProject({
+      ...location,
+      fetchFeatureCollection: successfulFetch,
+    });
+    const drainageId = "corestack-drainage";
+    const toggledProject = {
+      ...project,
+      layers: project.layers.map((layer) =>
+        layer.id === drainageId ? { ...layer, visible: true } : layer
+      ),
+    };
+
+    const hydratedProject = await hydrateGeoLibreVectorLayer({
+      project: toggledProject,
+      layerId: drainageId,
+      fetchFeatureCollection: successfulFetch,
+    });
+    const drainage = hydratedProject.layers.find(
+      (layer) => layer.id === drainageId
+    );
+
+    expect(drainage).toMatchObject({
+      visible: true,
+      metadata: { loadState: "loaded", featureCount: 1 },
     });
+    expect(successfulFetch.mock.calls[1][0].typeName).toContain("drainage");
+    expect(successfulFetch).toHaveBeenCalledTimes(2);
 
+    const reusedProject = await hydrateGeoLibreVectorLayer({
+      project: hydratedProject,
+      layerId: drainageId,
+      fetchFeatureCollection: successfulFetch,
+    });
+    expect(reusedProject).toBe(hydratedProject);
+    expect(successfulFetch).toHaveBeenCalledTimes(2);
+  });
+
+  it("keeps a failed lazy vector available for a later toggle retry", async () => {
     const project = await buildGeoLibreProject({
       ...location,
-      fetchFeatureCollection: fetchWithWatershedFailure,
+      fetchFeatureCollection: successfulFetch,
     });
-    const fortnightly = project.layers.find(
-      (layer) => layer.id === "corestack-mws_layers_fortnight"
-    );
+    const layerId = "corestack-mws_layers_fortnight";
+    const failedFetch = jest.fn(async () => {
+      throw new Error("temporary outage");
+    });
+
+    const failedProject = await hydrateGeoLibreVectorLayer({
+      project,
+      layerId,
+      fetchFeatureCollection: failedFetch,
+    });
+    expect(
+      failedProject.layers.find((layer) => layer.id === layerId).metadata
+    ).toMatchObject({ loadState: "error", initialLoadError: "temporary outage" });
+    expect(failedProject.metadata.layerLoading.lazyLoadFailures).toHaveLength(1);
 
-    expect(fortnightly.geojson.features).toEqual([]);
-    expect(fortnightly.metadata).toMatchObject({
-      sourceKind: "wfs-getfeature",
-      loadState: "error",
-      initialLoadError: "temporary outage",
+    const retriedProject = await hydrateGeoLibreVectorLayer({
+      project: failedProject,
+      layerId,
+      fetchFeatureCollection: successfulFetch,
     });
-    expect(project.metadata.layerLoading.initialLoadFailures).toHaveLength(1);
+    expect(
+      retriedProject.layers.find((layer) => layer.id === layerId).metadata
+        .loadState
+    ).toBe("loaded");
+    expect(retriedProject.metadata.layerLoading.lazyLoadFailures).toEqual([]);
   });
 
   it("requires the socioeconomic extent", async () => {
diff --git a/src/components/landing_navbar.jsx b/src/components/landing_navbar.jsx
index d39f6c34..23769a1d 100644
--- a/src/components/landing_navbar.jsx
+++ b/src/components/landing_navbar.jsx
@@ -66,7 +66,7 @@ const LandingNavbar = () => {
                   </a>
                 </div>
                 <p className="text-center text-xs text-slate-600 sm:text-right">
-                  Can&apos;t download a QML style in GeoLibre? Get it from the{" "}
+                  To Use these layers with QGIS, download layer styles from the{" "}
                   <a
                     href="https://github.com/core-stack-org/QGIS-Styles"
                     target="_blank"
diff --git a/src/components/landing_navbar.test.jsx b/src/components/landing_navbar.test.jsx
index 386bcd43..95592850 100644
--- a/src/components/landing_navbar.test.jsx
+++ b/src/components/landing_navbar.test.jsx
@@ -23,5 +23,8 @@ describe("Download Layers navigation", () => {
       screen.getByRole("link", { name: /CoRE Stack QGIS Styles repository/i })
         .getAttribute("href")
     ).toBe("https://github.com/core-stack-org/QGIS-Styles");
+    expect(document.body.textContent).toContain(
+      "To Use these layers with QGIS, download layer styles from the CoRE Stack QGIS Styles repository."
+    );
   });
 });
diff --git a/src/pages/LandscapeExplorer.jsx b/src/pages/LandscapeExplorer.jsx
index 01dd5b70..ef9e8325 100644
--- a/src/pages/LandscapeExplorer.jsx
+++ b/src/pages/LandscapeExplorer.jsx
@@ -1,8 +1,11 @@
-import { useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Link, useLocation } from "react-router-dom";
 import { useRecoilValue } from "recoil";
 import GeoLibreFrame from "../components/geolibre/GeoLibreFrame";
-import { buildGeoLibreProject } from "../components/geolibre/geolibreProject";
+import {
+  buildGeoLibreProject,
+  hydrateGeoLibreVectorLayer,
+} from "../components/geolibre/geolibreProject";
 import LandingNavbar from "../components/landing_navbar";
 import {
   blockAtom,
@@ -17,6 +20,31 @@ import {
 
 const labelOf = (selection) => selection?.label || "";
 
+const scopeKeyOf = (project) => {
+  const scope = project?.metadata?.scope;
+  return scope ? [scope.state, scope.district, scope.tehsil].join("|") : "";
+};
+
+const mergeHydratedVectorLayers = (viewerProject, hydratedLayers) => ({
+  ...viewerProject,
+  layers: viewerProject.layers.map((layer) => {
+    const hydrated = hydratedLayers.get(layer.id);
+    if (!hydrated) return layer;
+    return {
+      ...layer,
+      geojson: hydrated.geojson,
+      metadata: {
+        ...layer.metadata,
+        ...hydrated.metadata,
+        corestack: {
+          ...layer.metadata?.corestack,
+          ...hydrated.metadata?.corestack,
+        },
+      },
+    };
+  }),
+});
+
 const LandscapeExplorer = () => {
   const selectedState = useRecoilValue(stateAtom);
   const selectedDistrict = useRecoilValue(districtAtom);
@@ -26,6 +54,11 @@ const LandscapeExplorer = () => {
   const [progress, setProgress] = useState("Starting GeoLibre…");
   const [error, setError] = useState("");
   const [retryKey, setRetryKey] = useState(0);
+  const currentScopeKeyRef = useRef("");
+  const lazyQueueRef = useRef(Promise.resolve());
+  const lazyStateSequenceRef = useRef(0);
+  const hydratedLayersRef = useRef(new Map());
+  const hydrationDirtyRef = useRef(false);
 
   const scope = useMemo(() => {
     const params = new URLSearchParams(routeLocation.search);
@@ -42,6 +75,15 @@ const LandscapeExplorer = () => {
   ]);
 
   const hasLocation = Boolean(scope.state && scope.district && scope.tehsil);
+  const scopeKey = [scope.state, scope.district, scope.tehsil].join("|");
+
+  useEffect(() => {
+    currentScopeKeyRef.current = scopeKey;
+    lazyStateSequenceRef.current += 1;
+    lazyQueueRef.current = Promise.resolve();
+    hydratedLayersRef.current = new Map();
+    hydrationDirtyRef.current = false;
+  }, [scopeKey]);
 
   useEffect(() => {
     initializeAnalytics();
@@ -65,17 +107,12 @@ const LandscapeExplorer = () => {
       onProgress: ({ message }) => {
         if (!controller.signal.aborted) setProgress(message);
       },
-      onInitialProject: (overviewProject) => {
-        if (controller.signal.aborted) return;
-        setProject(overviewProject);
-        setProgress("Loading Watersheds in the background…");
-        trackEvent("GeoLibre", "open_workspace", scope.tehsil);
-      },
     })
       .then((nextProject) => {
         if (controller.signal.aborted) return;
         setProject(nextProject);
-        setProgress("Overview and Watersheds are ready.");
+        setProgress("Overview is ready. Toggle another layer to load it.");
+        trackEvent("GeoLibre", "open_workspace", scope.tehsil);
       })
       .catch((buildError) => {
         if (controller.signal.aborted) return;
@@ -89,6 +126,52 @@ const LandscapeExplorer = () => {
     return () => controller.abort();
   }, [hasLocation, retryKey, scope]);
 
+  const handleProjectState = useCallback((viewerProject) => {
+    const viewerScopeKey = scopeKeyOf(viewerProject);
+    const sequence = lazyStateSequenceRef.current + 1;
+    lazyStateSequenceRef.current = sequence;
+
+    lazyQueueRef.current = lazyQueueRef.current
+      .catch(() => undefined)
+      .then(async () => {
+        if (viewerScopeKey !== currentScopeKeyRef.current) return;
+
+        let nextProject = mergeHydratedVectorLayers(
+          viewerProject,
+          hydratedLayersRef.current
+        );
+        const layersToLoad = nextProject.layers.filter(
+          (layer) =>
+            layer.type === "geojson" &&
+            layer.visible &&
+            ["unloaded", "error"].includes(layer.metadata?.loadState)
+        );
+
+        for (const layer of layersToLoad) {
+          nextProject = await hydrateGeoLibreVectorLayer({
+            project: nextProject,
+            layerId: layer.id,
+          });
+          const hydrated = nextProject.layers.find(
+            (item) => item.id === layer.id
+          );
+          if (hydrated) hydratedLayersRef.current.set(layer.id, hydrated);
+          hydrationDirtyRef.current = true;
+        }
+
+        if (
+          viewerScopeKey !== currentScopeKeyRef.current ||
+          sequence !== lazyStateSequenceRef.current ||
+          (!layersToLoad.length && !hydrationDirtyRef.current)
+        ) {
+          return;
+        }
+
+        hydrationDirtyRef.current = false;
+        setProject(nextProject);
+      });
+  }, []);
+
   if (!hasLocation) {
     return (
       <div className="flex h-screen flex-col bg-slate-100">
@@ -116,8 +199,11 @@ const LandscapeExplorer = () => {
 
   const failures =
     project?.metadata?.layerLoading?.initialLoadFailures?.length || 0;
-  const warning = failures
-    ? `${failures} layer${failures === 1 ? "" : "s"} could not be preloaded. They remain listed in GeoLibre and can be retried with Refresh.`
+  const lazyFailures =
+    project?.metadata?.layerLoading?.lazyLoadFailures?.length || 0;
+  const totalFailures = failures + lazyFailures;
+  const warning = totalFailures
+    ? `${totalFailures} layer${totalFailures === 1 ? "" : "s"} could not be loaded. Toggle the layer off and on to retry.`
     : "";
 
   return (
@@ -128,6 +214,7 @@ const LandscapeExplorer = () => {
         preparationMessage={progress}
         preparationError={error}
         warning={warning}
+        onProjectState={handleProjectState}
         onRetry={() => setRetryKey((value) => value + 1)}
       />
     </div>

From c8c1f8d42c970d6bd2b8195b0d6ad54b97e16387 Mon Sep 17 00:00:00 2001
From: amit-spatial <amit.kumar@gramvaani.org>
Date: Wed, 22 Jul 2026 12:55:59 +0000
Subject: [PATCH 6/9] refine GeoLibre map presentation

---
 .env.example                                  |   3 +
 README.md                                     |  15 +-
 src/components/geolibre/GeoLibreFrame.jsx     | 162 +++++++++--
 .../geolibre/GeoLibreFrame.test.jsx           |  37 ++-
 src/components/geolibre/README.md             | 145 ++++++++--
 src/components/geolibre/geolibreProject.js    | 261 ++++++++++++++++--
 .../geolibre/geolibreProject.test.js          |  74 ++++-
 src/components/landing_navbar.jsx             |  12 +
 src/components/landing_navbar.test.jsx        |   6 +
 src/config/geolibreLayers.js                  |  44 +--
 10 files changed, 639 insertions(+), 120 deletions(-)

diff --git a/.env.example b/.env.example
index e0fca5c2..fd125b6e 100644
--- a/.env.example
+++ b/.env.example
@@ -8,6 +8,9 @@ REACT_APP_GEOSERVER_URL=https://geoserver.core-stack.org:8443/geoserver/
 # REACT_APP_GEOLIBRE_VERSION=2.2.0
 # REACT_APP_GEOLIBRE_URL=https://web.geolibre.app/
 # REACT_APP_GEOLIBRE_STRICT_VERSION=false
+# Optional MapLibre style URL. The default uses the same Google Satellite
+# Hybrid tiles as the existing KYL maps.
+# REACT_APP_GEOLIBRE_BASEMAP_STYLE_URL=https://maps.example.org/style.json
 
 # To make the version value select an exact build, deploy GeoLibre at stable
 # versioned paths and use this instead of REACT_APP_GEOLIBRE_URL:
diff --git a/README.md b/README.md
index 64368f89..68ec8411 100755
--- a/README.md
+++ b/README.md
@@ -37,17 +37,16 @@ npm install
 
 ### 3. Environment Variables Setup
 
-Create `.env` from the committed deployable example in the repository root:
+Create a .env file in the root directory of the project where the package.json is located.
 
 ```bash
-cp .env.example .env
+touch .env
 ```
-
-The example contains the public API, GeoServer, and optional GeoLibre settings.
-Add deployment-specific keys only when the feature that uses them is required:
-
+Add the following variables to .env
 ```env
+REACT_APP_API_URL="https://geoserver.core-stack.org/api/v1"
 REACT_APP_GOOGLE_KEY="xxx"
+REACT_APP_GEOSERVER_URL="https://geoserver.core-stack.org:8443/geoserver/"
 
 # Google Analytics
 REACT_APP_GA_MEASUREMENT_ID="xxx"
@@ -57,10 +56,6 @@ REACT_APP_WATERBODYREJ_USERNAME="xxx"
 REACT_APP_WATERBODYREJ_PASSWORD="xxx"
 REACT_APP_BASEURL="https://geoserver.core-stack.org"
 ```
-
-Restart the development server whenever `.env` changes. See
-[`src/components/geolibre/README.md`](src/components/geolibre/README.md) for the
-complete `/download_layers` test and deployment checklist.
 ### 4. Running the Application
 
 ```bash
diff --git a/src/components/geolibre/GeoLibreFrame.jsx b/src/components/geolibre/GeoLibreFrame.jsx
index 41cb9868..5f97700e 100644
--- a/src/components/geolibre/GeoLibreFrame.jsx
+++ b/src/components/geolibre/GeoLibreFrame.jsx
@@ -1,10 +1,40 @@
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   GEOLIBRE_CONFIG,
   geoLibreVersionStatus,
   resolveGeoLibreViewer,
 } from "../../config/geolibre.config";
 
+const MAX_TECHNICAL_LOG_ENTRIES = 40;
+
+const USER_ISSUES = {
+  preparation: {
+    title: "We couldn’t prepare this tehsil’s map",
+    message:
+      "Please try again. If the problem continues, select the tehsil again or share the technical log with the CoRE Stack team.",
+  },
+  delayed: {
+    title: "The map is taking longer than expected",
+    message:
+      "Check your internet connection and try again. If the problem continues, download the technical log and share it with the CoRE Stack team.",
+  },
+  unavailable: {
+    title: "The map is temporarily unavailable",
+    message:
+      "Please try again in a moment. If the problem continues, download the technical log and share it with the CoRE Stack team.",
+  },
+};
+
+export const formatGeoLibreLog = (entries) =>
+  [
+    "KYL GeoLibre technical log",
+    `Generated: ${new Date().toISOString()}`,
+    ...entries.map(
+      ({ timestamp, event, details }) =>
+        `${timestamp} ${event}${details ? ` ${JSON.stringify(details)}` : ""}`
+    ),
+  ].join("\n");
+
 const GeoLibreFrame = ({
   project,
   preparationMessage,
@@ -18,8 +48,9 @@ const GeoLibreFrame = ({
   const fittedScopeRef = useRef("");
   const sentProjectRef = useRef(null);
   const sequenceRef = useRef(0);
+  const technicalLogRef = useRef([]);
   const [viewerState, setViewerState] = useState("loading");
-  const [viewerError, setViewerError] = useState("");
+  const [viewerIssue, setViewerIssue] = useState("");
   const [viewerVersion, setViewerVersion] = useState("");
   const [readyGeneration, setReadyGeneration] = useState(0);
 
@@ -38,15 +69,45 @@ const GeoLibreFrame = ({
     }
   }, []);
 
+  const addTechnicalLog = useCallback((event, details) => {
+    technicalLogRef.current = [
+      ...technicalLogRef.current,
+      {
+        timestamp: new Date().toISOString(),
+        event,
+        ...(details ? { details } : {}),
+      },
+    ].slice(-MAX_TECHNICAL_LOG_ENTRIES);
+  }, []);
+
+  useEffect(() => {
+    addTechnicalLog("viewer_configured", {
+      expectedVersion: GEOLIBRE_CONFIG.version,
+      viewerUrl: viewer.url || null,
+      configurationError: viewer.error || null,
+    });
+  }, [addTechnicalLog, viewer.error, viewer.url]);
+
+  useEffect(() => {
+    if (preparationError) {
+      addTechnicalLog("project_preparation_failed", {
+        message: String(preparationError),
+      });
+    }
+  }, [addTechnicalLog, preparationError]);
+
   useEffect(() => {
     if (!viewer.url) return undefined;
     const frame = frameRef.current;
     if (!frame) return undefined;
 
     let handshakeTimer = window.setTimeout(() => {
-      setViewerError(
-        `GeoLibre ${GEOLIBRE_CONFIG.version} did not complete its iframe handshake. Check the configured viewer URL and browser console.`
-      );
+      addTechnicalLog("iframe_handshake_timeout", {
+        expectedVersion: GEOLIBRE_CONFIG.version,
+        viewerUrl: viewer.url,
+        timeoutMs: 90000,
+      });
+      setViewerIssue("delayed");
       setViewerState("error");
     }, 90000);
 
@@ -65,27 +126,39 @@ const GeoLibreFrame = ({
         handshakeTimer = null;
         const status = geoLibreVersionStatus(event.data.version);
         if (!status.compatible) {
-          setViewerError(status.message);
+          addTechnicalLog("viewer_version_rejected", {
+            actualVersion: event.data.version,
+            reason: status.message,
+          });
+          setViewerIssue("unavailable");
           setViewerState("error");
           return;
         }
+        addTechnicalLog("iframe_ready", {
+          actualVersion: event.data.version,
+        });
         setViewerVersion(String(event.data.version));
         sentProjectRef.current = null;
-        setViewerError("");
+        setViewerIssue("");
         setViewerState("ready");
         setReadyGeneration((generation) => generation + 1);
         return;
       }
 
       if (event.data.type === "geolibre:error") {
-        setViewerError(
-          event.data.message || "GeoLibre could not load the generated project."
-        );
+        addTechnicalLog("viewer_reported_error", {
+          message:
+            event.data.message || "GeoLibre could not load the generated project.",
+        });
+        setViewerIssue("unavailable");
         setViewerState("error");
         return;
       }
 
       if (event.data.type === "geolibre:state" && event.data.project) {
+        addTechnicalLog("project_state_received", {
+          layerCount: event.data.project.layers?.length || 0,
+        });
         onProjectState?.(event.data.project);
       }
     };
@@ -95,7 +168,7 @@ const GeoLibreFrame = ({
       window.removeEventListener("message", handleMessage);
       if (handshakeTimer !== null) window.clearTimeout(handshakeTimer);
     };
-  }, [onProjectState, viewer.origin, viewer.url]);
+  }, [addTechnicalLog, onProjectState, viewer.origin, viewer.url]);
 
   useEffect(
     () => () => {
@@ -127,6 +200,11 @@ const GeoLibreFrame = ({
       },
       viewer.origin
     );
+    addTechnicalLog("project_sent", {
+      sequence,
+      projectName: project.name,
+      layerCount: project.layers?.length || 0,
+    });
     sentProjectRef.current = project;
     const bounds = project.mapView?.bbox;
     const scope = project.metadata?.scope;
@@ -152,14 +230,36 @@ const GeoLibreFrame = ({
           },
           viewer.origin
         );
+        addTechnicalLog("initial_bounds_fit_requested", { bounds });
         fitTimerRef.current = null;
       }, 1500);
     }
     setViewerState("loaded");
-  }, [project, readyGeneration, viewer.origin, viewerState]);
+  }, [addTechnicalLog, project, readyGeneration, viewer.origin, viewerState]);
+
+  const activeIssue = viewer.error
+    ? "unavailable"
+    : preparationError
+      ? "preparation"
+      : viewerIssue;
+  const userIssue = activeIssue ? USER_ISSUES[activeIssue] : null;
+  const showProgress = !userIssue && (!project || viewerState === "loading");
 
-  const activeError = viewer.error || preparationError || viewerError;
-  const showProgress = !activeError && (!project || viewerState === "loading");
+  const downloadTechnicalLog = () => {
+    const blob = new Blob([formatGeoLibreLog(technicalLogRef.current)], {
+      type: "text/plain;charset=utf-8",
+    });
+    const objectUrl = window.URL.createObjectURL(blob);
+    const link = document.createElement("a");
+    link.href = objectUrl;
+    link.download = `kyl-geolibre-${new Date()
+      .toISOString()
+      .replace(/[:.]/g, "-")}.log`;
+    document.body.appendChild(link);
+    link.click();
+    link.remove();
+    window.setTimeout(() => window.URL.revokeObjectURL(objectUrl), 0);
+  };
 
   return (
     <main className="relative min-h-0 flex-1 overflow-hidden bg-slate-100">
@@ -173,6 +273,7 @@ const GeoLibreFrame = ({
           allowFullScreen
           data-geolibre-version={viewerVersion || undefined}
           onLoad={() => {
+            addTechnicalLog("iframe_loaded", { viewerUrl: viewer.url });
             fittedScopeRef.current = "";
             setViewerVersion("");
             setViewerState((current) =>
@@ -182,7 +283,7 @@ const GeoLibreFrame = ({
         />
       )}
 
-      {!activeError && viewerVersion && (
+      {!userIssue && viewerVersion && (
         <div
           className="pointer-events-none absolute bottom-8 right-3 rounded-md border border-slate-300 bg-white/95 px-2 py-1 text-[11px] font-medium text-slate-700 shadow-sm"
           title={`Loaded from ${viewer.url}`}
@@ -192,29 +293,38 @@ const GeoLibreFrame = ({
         </div>
       )}
 
-      {(showProgress || activeError) && (
+      {(showProgress || userIssue) && (
         <div className="absolute inset-0 flex items-center justify-center bg-slate-950/35 p-5 backdrop-blur-[1px]">
           <div
             className="w-full max-w-md rounded-2xl bg-white p-6 text-center shadow-2xl"
-            role={activeError ? "alert" : "status"}
+            role={userIssue ? "alert" : "status"}
           >
-            {activeError ? (
+            {userIssue ? (
               <>
                 <h1 className="text-lg font-semibold text-slate-900">
-                  GeoLibre could not be opened
+                  {userIssue.title}
                 </h1>
                 <p className="mt-2 text-sm leading-6 text-slate-600">
-                  {activeError}
+                  {userIssue.message}
                 </p>
-                {onRetry && (
+                <div className="mt-5 flex flex-wrap justify-center gap-2">
+                  {onRetry && (
+                    <button
+                      type="button"
+                      onClick={onRetry}
+                      className="rounded-lg bg-purple-700 px-4 py-2 text-sm font-semibold text-white hover:bg-purple-800"
+                    >
+                      Try again
+                    </button>
+                  )}
                   <button
                     type="button"
-                    onClick={onRetry}
-                    className="mt-5 rounded-lg bg-purple-700 px-4 py-2 text-sm font-semibold text-white hover:bg-purple-800"
+                    onClick={downloadTechnicalLog}
+                    className="rounded-lg border border-slate-300 bg-white px-4 py-2 text-sm font-semibold text-slate-700 hover:bg-slate-50"
                   >
-                    Try again
+                    Download technical log
                   </button>
-                )}
+                </div>
               </>
             ) : (
               <>
@@ -232,7 +342,7 @@ const GeoLibreFrame = ({
         </div>
       )}
 
-      {!activeError && warning && viewerState === "loaded" && (
+      {!userIssue && warning && viewerState === "loaded" && (
         <div
           className="absolute bottom-4 left-1/2 max-w-[calc(100%-2rem)] -translate-x-1/2 rounded-lg border border-amber-300 bg-amber-50/95 px-4 py-2 text-sm text-amber-950 shadow-lg"
           role="status"
diff --git a/src/components/geolibre/GeoLibreFrame.test.jsx b/src/components/geolibre/GeoLibreFrame.test.jsx
index 0313bb98..de057008 100644
--- a/src/components/geolibre/GeoLibreFrame.test.jsx
+++ b/src/components/geolibre/GeoLibreFrame.test.jsx
@@ -1,5 +1,5 @@
 import { act, render, screen } from "@testing-library/react";
-import GeoLibreFrame from "./GeoLibreFrame";
+import GeoLibreFrame, { formatGeoLibreLog } from "./GeoLibreFrame";
 
 const project = {
   version: "0.2.0",
@@ -68,14 +68,47 @@ describe("GeoLibre iframe bridge", () => {
     act(() => announceReady(frame, "3.0.0"));
 
     expect(screen.getByRole("alert").textContent).toMatch(
-      /GeoLibre 3\.0\.0 is not compatible.*major version 2/i
+      /map is temporarily unavailable.*try again in a moment/i
     );
+    expect(screen.getByRole("alert").textContent).not.toMatch(
+      /GeoLibre 3\.0\.0|major version|iframe/i
+    );
+    expect(
+      screen.getByRole("button", { name: /Download technical log/i })
+    ).toBeTruthy();
     expect(postMessage).not.toHaveBeenCalledWith(
       expect.objectContaining({ type: "geolibre:load-project" }),
       expect.any(String)
     );
   });
 
+  it("shows helpful language when the iframe handshake is delayed", () => {
+    render(<GeoLibreFrame project={project} onRetry={jest.fn()} />);
+
+    act(() => jest.advanceTimersByTime(90000));
+
+    expect(screen.getByRole("alert").textContent).toMatch(
+      /map is taking longer than expected.*internet connection.*try again/i
+    );
+    expect(screen.getByRole("alert").textContent).not.toMatch(
+      /iframe handshake|browser console/i
+    );
+  });
+
+  it("formats bounded troubleshooting entries as a plain-text log", () => {
+    const output = formatGeoLibreLog([
+      {
+        timestamp: "2026-07-22T00:00:00.000Z",
+        event: "iframe_handshake_timeout",
+        details: { expectedVersion: "2.2.0" },
+      },
+    ]);
+
+    expect(output).toContain("KYL GeoLibre technical log");
+    expect(output).toContain("iframe_handshake_timeout");
+    expect(output).toContain('"expectedVersion":"2.2.0"');
+  });
+
   it("reloads a lazily hydrated project without fitting the tehsil again", () => {
     const { rerender } = render(<GeoLibreFrame project={project} />);
     const frame = screen.getByTitle("GeoLibre GIS workspace");
diff --git a/src/components/geolibre/README.md b/src/components/geolibre/README.md
index a492295b..3b3b561c 100644
--- a/src/components/geolibre/README.md
+++ b/src/components/geolibre/README.md
@@ -5,6 +5,9 @@
 repository fallback) and gives the rest of the page to a trusted GeoLibre
 iframe. There is no second KYL map, layer selector, or project panel.
 
+CoRE Stack datasets are available under
+[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
 The implementation targets
 [GeoLibre v2.2.0](https://github.com/opengeos/GeoLibre/releases/tag/v2.2.0)
 and uses its supported embed bridge and WFS project representation.
@@ -13,11 +16,12 @@ and uses its supported embed bridge and WFS project representation.
 
 1. The KYL homepage carries the selected state, district, and tehsil to
    `/download_layers` as query parameters.
-2. `geolibreProject.js` fetches the shared Overview WFS source once. It creates
+2. `geolibreProject.js` fetches the shared Demographic WFS source once. It creates
    **Administrative Boundaries** and **Socio-Economic Profile** from that data,
    derives the complete tehsil bounding box, and immediately opens GeoLibre.
-3. Both Overview layers start visible at opacity `0.8`, in that display order.
-4. Every vector outside Overview—including all Watersheds—starts listed,
+3. Both default Demographic layers start visible at opacity `0.8`, in that
+   display order.
+4. Every vector outside the two default Demographic entries starts listed,
    hidden, and empty. Its first visibility toggle asks KYL to fetch that WFS
    source and send the hydrated layer back to GeoLibre. The hydrated layer is
    retained, so later off/on toggles do not repeat its WFS request.
@@ -26,22 +30,75 @@ and uses its supported embed bridge and WFS project representation.
    source for later toggles; normal browser and MapLibre tile caches reuse tiles
    that have already been fetched.
 6. The iframe reports `geolibre:ready`; KYL verifies its application version,
-   sends the Overview project, and fits the exact tehsil bounds once. Lazy
+   sends the initial project, and fits the exact tehsil bounds once. Lazy
    project updates preserve the user's live map view and never fit it again.
 
+```mermaid
+flowchart LR
+    A[KYL location selection] --> B[/download_layers URL]
+    B --> C[Project builder]
+    C --> D[Shared tehsil WFS]
+    D --> C
+    C --> E[GeoLibre project]
+    E --> F[Trusted iframe bridge]
+    F --> G[GeoLibre 2.x]
+    G --> H[Lazy WFS vectors]
+    G --> I[WMS display and WCS downloads]
+```
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant GeoLibre
+    participant KYL
+    participant GeoServer
+    User->>GeoLibre: Toggle a hidden vector
+    GeoLibre-->>KYL: geolibre:state
+    KYL->>GeoServer: WFS GetFeature
+    GeoServer-->>KYL: GeoJSON FeatureCollection
+    KYL-->>GeoLibre: Hydrated project state
+    User->>GeoLibre: Toggle the layer off and on
+    GeoLibre-->>KYL: geolibre:state
+    Note over KYL,GeoLibre: Reuse cached layer; no second WFS request or bbox fit
+```
+
+## Methodology
+
+1. **Scope:** state, district, and tehsil are read from the route so a project
+   is reproducible and shareable.
+2. **Extent:** the shared panchayat-boundary WFS response supplies both default
+   Demographic layers and the authoritative tehsil bbox.
+3. **Catalog:** `geolibreLayers.js` is the single layer inventory. It assigns
+   the deployed KYL domain, GeoServer source, QML reference, year, and order.
+4. **Cartography:** vector QML logic is represented in GeoLibre styles; raster
+   QML is rendered by the corresponding named GeoServer WMS style. Matching
+   color labels are also persisted in GeoLibre's native on-map legends.
+5. **Loading:** only the shared default WFS is fetched at startup. Other
+   vectors hydrate once on first toggle; rasters remain native lazy WMS layers.
+6. **Download:** vector data remains available through GeoLibre and complete
+   raster coverage is exposed through WCS for **GeoTIFF (COG)** export.
+7. **Failure handling:** users receive short recovery guidance. A bounded
+   technical trace can be downloaded as a `.log` file when support needs it.
+
 ## Native layer organization
 
-GeoLibre's own layer panel is ordered top-first as:
+GeoLibre's own layer panel follows the deployed Download Layers taxonomy,
+ordered top-first as:
 
-1. Overview (Administrative Boundaries, Socio-Economic Profile)
-2. Watersheds (MWS and related hydrological layers)
-3. Other vector layers
-4. LULC Level 3, Level 2, and Level 1 by year
-5. Other raster layers
+1. Demographic (Administrative Boundaries, Socio-Economic Profile)
+2. Hydrology
+3. LULC Level 3 by year
+4. LULC Level 2 by year
+5. LULC Level 1 by year
+6. Land
+7. Agriculture
+8. Restoration
+9. Climate
+10. NREGA
 
-The non-overview groups are collapsed where appropriate. Every layer outside
-Overview is toggle-to-load. Each LULC group shows 2024-2025 first while
-retaining every available year back to 2017-2018.
+The remaining groups are collapsed. Every layer outside the two default
+Demographic entries is toggle-to-load. Each LULC group shows 2024-2025 first
+while retaining every available year back to 2017-2018.
 
 The project camera is calculated from the Socio-Economic geometry using a
 padded Web Mercator fit. `mapView.bbox` is also retained in project metadata,
@@ -49,6 +106,22 @@ and the iframe receives one `fitBounds` command after its initial load, so the
 initial map contains the full tehsil rather than a generic India extent. Layer
 toggles and lazy hydration do not issue another fit command.
 
+## Basemap and legends
+
+The default is the same Google Satellite Hybrid tile source used by the
+existing KYL maps. It is wrapped in an inline MapLibre style with Google
+attribution. A deployment can replace it with another valid MapLibre style:
+
+```dotenv
+REACT_APP_GEOLIBRE_BASEMAP_STYLE_URL=https://maps.example.org/style.json
+```
+
+GeoLibre's built-in Components plugin provides an on-map legend in minimized
+mode by default, keeping the map clear. Socio-Economic Profile is selected
+initially when the user expands it, and the selector includes the configured
+vector, raster, and LULC palettes. The separate `legend` project field retains
+ordering and grouping for GeoLibre's Print Layout legend.
+
 ## Version configuration
 
 The default hosted viewer accepts any GeoLibre release from `2.0.0` up to, but
@@ -94,17 +167,27 @@ application.
 | File | Responsibility |
 |---|---|
 | `../../config/geolibre.config.js` | Viewer application version, URL resolution, strict handshake compatibility |
-| `../../config/geolibreLayers.js` | GeoServer names, all LULC years, QML references, WMS styles, load groups |
-| `geolibreProject.js` | Overview generation, single-vector hydration, lazy placeholders, styles, WMS/WCS references, bbox camera |
-| `GeoLibreFrame.jsx` | Iframe lifecycle, trusted-origin bridge, state events, one-time bbox fit, version and failure handling |
+| `../../config/geolibreLayers.js` | GeoServer names, deployed domains, all LULC years, QML references and WMS styles |
+| `geolibreProject.js` | Project generation, legends, Google imagery, vector hydration, WMS/WCS references and bbox camera |
+| `GeoLibreFrame.jsx` | Iframe bridge, one-time bbox fit, human error states and downloadable bounded technical log |
 | `../../pages/LandscapeExplorer.jsx` | Route-to-project orchestration and fetch-on-first-toggle vector cache; no duplicate map or layer UI |
 
 The current project contains 45 entries: 13 vector entries, 24 LULC year/level
 rasters, and 8 other rasters. Initial startup performs exactly one distinct WFS
-request for the shared Overview data and no WMS request. Each non-Overview
-vector makes its own WFS request only on its first toggle. Hidden rasters make
+request for the shared Demographic data and no WMS request. Each other vector
+makes its own WFS request only on its first toggle. Hidden rasters make
 no WMS tile request.
 
+## Error handling
+
+The page never presents iframe handshakes, version parsing, viewer URLs, or
+browser-console instructions as end-user error text. It asks the user to retry,
+check their connection where relevant, and contact the CoRE Stack team if the
+problem continues. **Download technical log** creates a small
+`kyl-geolibre-<timestamp>.log` file containing at most the latest 40 lifecycle
+events. Browsers require this explicit user download and cannot silently write
+a log file to the user's filesystem.
+
 ## Styling contract
 
 - Vector QML rules are translated into GeoLibre categorized or expression
@@ -177,25 +260,30 @@ Check both routes:
    `REACT_APP_GEOSERVER_URL is not set` runtime error.
 2. Open `http://localhost:3000`, select a state, district, and tehsil, and click
    **Download Layers**.
-3. Confirm the GeoLibre badge reports `2.2.0`, the map fits the tehsil, and the
-   Overview panel shows Administrative Boundaries then Socio-Economic Profile,
+3. Confirm the GeoLibre badge reports a compatible 2.x version, the Google
+   Satellite Hybrid basemap appears, the map fits the tehsil, and Demographic
+   shows Administrative Boundaries then Socio-Economic Profile,
    both visible at `0.80`.
-4. Confirm no Watershed or other non-Overview layer loads by itself. Toggle one
-   Watershed and one **Other vector layer** and confirm each loads. Toggle each
+4. Confirm the native legend starts minimized, expands to the Socio-Economic
+   colors, and its selector includes raster and LULC legends.
+5. Confirm no other layer loads by itself. Toggle a Climate layer and Drainage
+   under Hydrology and confirm each loads. Toggle each
    off and on again and confirm its WFS request is not repeated.
-5. Confirm the map does not refit after those vector loads. Enable a raster and
+6. Confirm the map does not refit after those vector loads. Enable a raster and
    verify its styled WMS display and **Export → GeoTIFF
    (COG)** full-coverage download.
-6. Open both documentation buttons and the QML repository fallback.
+7. Open both documentation buttons, the QML repository, and the CC BY 4.0 link.
+8. If testing a failure state, confirm it uses human recovery guidance and that
+   **Download technical log** saves a `.log` file.
 
 The generated `/download_layers?state=...&district=...&tehsil=...` URL can be
 refreshed or shared on the same KYL host because the location is URL-backed.
 
 For a release upgrade, verify all of the following before changing the default
 version: the ready handshake reports the expected release, the project loads
-without `geolibre:error`, both Overview layers are visible at `0.8`, the full
-tehsil fits exactly once, Watersheds and other vectors hydrate only when
-toggled and are then reused, WMS tiles appear only when enabled, and GeoLibre
+without `geolibre:error`, both default Demographic layers are visible at `0.8`,
+the full tehsil fits exactly once, Climate, Hydrology, and other vectors hydrate
+only when toggled and are then reused, WMS tiles appear only when enabled, and GeoLibre
 can save/export the resulting project.
 
 ## Production deployment
@@ -205,7 +293,8 @@ running `npm run build`. The current official viewer is a rolling URL. To pin an
 exact self-hosted build, additionally set the three version-template variables
 shown above. GeoServer WFS, WMS, and WCS endpoints must remain reachable from
 the user's browser with CORS enabled, and the site's framing policy must permit
-`https://web.geolibre.app`.
+`https://web.geolibre.app`. Browser policy must also permit imagery requests to
+`https://mt1.google.com`, unless the basemap override is used.
 
 ## Future integration options
 
diff --git a/src/components/geolibre/geolibreProject.js b/src/components/geolibre/geolibreProject.js
index 66288b8f..5a60cf15 100644
--- a/src/components/geolibre/geolibreProject.js
+++ b/src/components/geolibre/geolibreProject.js
@@ -10,7 +10,31 @@ import {
 
 const DEFAULT_GEOSERVER_URL =
   "https://geoserver.core-stack.org:8443/geoserver/";
-const DEFAULT_BASEMAP_STYLE = "https://tiles.openfreemap.org/styles/liberty";
+const GOOGLE_SATELLITE_HYBRID_STYLE = {
+  version: 8,
+  name: "Google Satellite Hybrid",
+  sources: {
+    "google-satellite-hybrid": {
+      type: "raster",
+      tiles: ["https://mt1.google.com/vt/lyrs=y&x={x}&y={y}&z={z}"],
+      tileSize: 256,
+      attribution: "© Google",
+      maxzoom: 20,
+    },
+  },
+  layers: [
+    {
+      id: "google-satellite-hybrid",
+      type: "raster",
+      source: "google-satellite-hybrid",
+    },
+  ],
+};
+export const DEFAULT_GEOLIBRE_BASEMAP_STYLE =
+  process.env.REACT_APP_GEOLIBRE_BASEMAP_STYLE_URL ||
+  `data:application/json;charset=utf-8,${encodeURIComponent(
+    JSON.stringify(GOOGLE_SATELLITE_HYBRID_STYLE)
+  )}`;
 const EMPTY_FEATURE_COLLECTION = Object.freeze({
   type: "FeatureCollection",
   features: [],
@@ -260,14 +284,158 @@ const STYLE_PROFILES = {
   ),
 };
 
+const LEGEND_PROFILES = {
+  boundary: [["Administrative or hydrological boundary", "#111827", "line"]],
+  demographics: [
+    ["Literacy below 46%", "#98fb98"],
+    ["Literacy 46% to below 59%", "#32cd32"],
+    ["Literacy 59% to below 70%", "#228b22"],
+    ["Literacy 70% or above", "#006400"],
+  ],
+  mws: [
+    ["Net groundwater change below -5", "#ff0000"],
+    ["Net groundwater change -5 to below -1", "#ffff00"],
+    ["Net groundwater change -1 to below 1", "#25b63c"],
+    ["Net groundwater change 1 or above", "#1017f8"],
+  ],
+  waterbodies: [["Surface waterbody", "#6495ed"]],
+  cropping_intensity: [
+    ["Average cropping intensity below 1", "#ff9371"],
+    ["Average cropping intensity 1 to below 2", "#ffa500"],
+    ["Average cropping intensity 2 or above", "#bad93e"],
+  ],
+  drought: [
+    ["No recurrent drought year", "#f4d03f"],
+    ["One recurrent drought year", "#eb984e"],
+    ["Two or more recurrent drought years", "#e74c3c"],
+  ],
+  terrain: [
+    ["V-shaped river valleys and deep narrow canyons", "#313695"],
+    ["Lateral midslope drainage and local valleys", "#4575b4"],
+    ["Upland drainage and stream headwaters", "#a50026"],
+    ["U-shaped valleys", "#e0f3f8"],
+    ["Broad flat areas", "#fffc00"],
+    ["Broad open slopes", "#feb24c"],
+    ["Mesa tops", "#f46d43"],
+    ["Upper slopes", "#d73027"],
+    ["Local ridges or hilltops", "#91bfdb"],
+    ["Midslope divides or local ridges", "#800000"],
+    ["Mountain tops or high ridges", "#4d0000"],
+  ],
+  clart: [
+    ["Good recharge", "#4ee323"],
+    ["Moderate recharge", "#f3ff33"],
+    ["Surface-water harvesting", "#f21223"],
+    ["Regeneration", "#b40f7d"],
+    ["High-runoff zone", "#1774de"],
+  ],
+  afforestation: [
+    ["Trees to trees", "#73bb53"],
+    ["Built-up to trees", "#ff0000"],
+    ["Crops to trees", "#eee05d"],
+    ["Barren to trees", "#a9a9a9"],
+    ["Shrubs and scrubs to trees", "#eaa4f0"],
+  ],
+  deforestation: [
+    ["Trees to trees", "#73bb53"],
+    ["Trees to built-up", "#ff0000"],
+    ["Trees to crops", "#eee05d"],
+    ["Trees to barren", "#a9a9a9"],
+    ["Trees to shrubs and scrubs", "#eaa4f0"],
+  ],
+  degradation: [
+    ["Crops to crops", "#eee05d"],
+    ["Crops to built-up", "#ff0000"],
+    ["Crops to barren", "#a9a9a9"],
+    ["Crops to shrubs and scrubs", "#eaa4f0"],
+  ],
+  urbanization: [
+    ["Built-up to built-up", "#ff0000"],
+    ["Water to built-up", "#1ca3ec"],
+    ["Trees or crops to built-up", "#73bb53"],
+    ["Barren or shrubs and scrubs to built-up", "#a9a9a9"],
+  ],
+  cropintensity: [
+    ["Double to single cropping", "#ff6347"],
+    ["Triple, annual or perennial to single", "#ff4500"],
+    ["Triple, annual or perennial to double", "#ff0000"],
+    ["Single to double cropping", "#00ff00"],
+    ["Single to triple, annual or perennial", "#32cd32"],
+    ["Double to triple, annual or perennial", "#228b22"],
+    ["Single to single cropping", "#4227f5"],
+    ["Double to double cropping", "#712103"],
+    ["Triple, annual or perennial unchanged", "#ad27f5"],
+  ],
+  restoration: [
+    ["Mosaic restoration", "#d79b0f"],
+    ["Wide-scale restoration", "#0f077c"],
+    ["Protection", "#4fbc14"],
+  ],
+  lulc_level_1: [
+    ["Built-up", "#ff0000"],
+    ["Water", "#1ca3ec"],
+    ["Greenery", "#73bb53"],
+    ["Barren lands", "#a9a9a9"],
+    ["Shrubs and scrubs", "#eaa4f0"],
+  ],
+  lulc_level_2: [
+    ["Trees and forests", "#73bb53"],
+    ["Crops", "#fad36f"],
+  ],
+  lulc_level_3: [
+    ["Single Kharif", "#d9f0a3"],
+    ["Single non-Kharif", "#a6d96a"],
+    ["Double cropping", "#4daf4a"],
+    ["Triple cropping", "#006d2c"],
+  ],
+};
+
+const legendShape = (catalogLayer) =>
+  catalogLayer.geometryType === "line"
+    ? "line"
+    : catalogLayer.geometryType === "point"
+      ? "circle"
+      : "square";
+
+const layerLegend = (catalogLayer, style) => {
+  const profile =
+    LEGEND_PROFILES[catalogLayer.id] ||
+    LEGEND_PROFILES[catalogLayer.baseId] ||
+    LEGEND_PROFILES[catalogLayer.styleProfile];
+  const shape = legendShape(catalogLayer);
+  const entries =
+    profile ||
+    (style.vectorStyleStops || []).map((stop) => [
+      stop.label || String(stop.value),
+      stop.color,
+    ]);
+  const items = entries.map(([label, color, itemShape]) => ({
+    label,
+    color,
+    shape: itemShape || shape,
+  }));
+  const baseTitle = catalogLayer.baseId
+    ? catalogLayer.label.split(" · ")[0]
+    : catalogLayer.label;
+  return {
+    key: catalogLayer.baseId || catalogLayer.id,
+    title: `${baseTitle} legend`,
+    items,
+    legendPosition: "bottom-left",
+  };
+};
+
 const GROUPS_TOP_FIRST = [
-  { id: "overview", name: "Overview", collapsed: false },
-  { id: "watersheds", name: "Watersheds", collapsed: false },
-  { id: "vectors", name: "Other vector layers", collapsed: true },
-  { id: "lulc-3", name: "LULC Level 3 by year", collapsed: true },
-  { id: "lulc-2", name: "LULC Level 2 by year", collapsed: true },
-  { id: "lulc-1", name: "LULC Level 1 by year", collapsed: true },
-  { id: "rasters", name: "Other raster layers", collapsed: true },
+  { id: "demographic", name: "Demographic", collapsed: false },
+  { id: "hydrology", name: "Hydrology", collapsed: true },
+  { id: "lulc-3", name: "LULC · Level 3 by year", collapsed: true },
+  { id: "lulc-2", name: "LULC · Level 2 by year", collapsed: true },
+  { id: "lulc-1", name: "LULC · Level 1 by year", collapsed: true },
+  { id: "land", name: "Land", collapsed: true },
+  { id: "agriculture", name: "Agriculture", collapsed: true },
+  { id: "restoration", name: "Restoration", collapsed: true },
+  { id: "climate", name: "Climate", collapsed: true },
+  { id: "nrega", name: "NREGA", collapsed: true },
 ];
 
 const projectPreferences = {
@@ -485,7 +653,7 @@ const layerStyle = (layer) =>
     ? { ...RASTER_STYLE }
     : { ...(STYLE_PROFILES[layer.styleProfile] || BASE_STYLE) };
 
-const coreStackMetadata = (layer, layerName, sourceUrl) => ({
+const coreStackMetadata = (layer, layerName, sourceUrl, style) => ({
   domain: layer.domain,
   geoserverWorkspace: layer.workspace,
   geoserverLayer: layerName,
@@ -493,6 +661,7 @@ const coreStackMetadata = (layer, layerName, sourceUrl) => ({
   liveSource: sourceUrl,
   qmlStyleUrl: layer.qmlStyleUrl,
   year: layer.year || null,
+  legend: layerLegend(layer, style),
   styleContract:
     layer.sourceType === "wms"
       ? "GeoServer renders the named style published from the CoRE Stack QGIS style catalog."
@@ -508,7 +677,7 @@ const buildVectorLayer = ({
   loaded = false,
 }) => {
   const style = layerStyle(catalogLayer);
-  const isOverview = catalogLayer.loadGroup === "overview";
+  const isDefaultDisplay = catalogLayer.defaultVisible === true;
   const loadState = failure ? "error" : loaded ? "loaded" : "unloaded";
   return {
     id: `corestack-${catalogLayer.id}`,
@@ -523,8 +692,8 @@ const buildVectorLayer = ({
       outputFormat: request.outputFormat,
       srsName: request.srsName,
     },
-    visible: isOverview,
-    opacity: isOverview ? 0.8 : 1,
+    visible: isDefaultDisplay,
+    opacity: isDefaultDisplay ? 0.8 : 1,
     style,
     metadata: {
       featureCount: data.features.length,
@@ -534,7 +703,7 @@ const buildVectorLayer = ({
       loadState,
       ...(failure ? { initialLoadError: failure.message } : {}),
       corestack: {
-        ...coreStackMetadata(catalogLayer, layerName, request.url),
+        ...coreStackMetadata(catalogLayer, layerName, request.url, style),
         loadState,
       },
     },
@@ -567,7 +736,7 @@ const buildRasterLayer = ({ catalogLayer, layerName, baseUrl, bounds }) => {
     metadata: {
       service: "wms",
       corestack: {
-        ...coreStackMetadata(catalogLayer, layerName, wmsSource.url),
+        ...coreStackMetadata(catalogLayer, layerName, wmsSource.url, style),
         wcsDownloadUrl,
         rasterDownload: {
           kind: "full-coverage-geotiff",
@@ -593,6 +762,51 @@ export const orderGeoLibreLayers = (layers) => {
   return topFirst.reverse();
 };
 
+const mapLegendEntries = (orderedLayers) => {
+  const seen = new Set();
+  const entries = [...orderedLayers]
+    .reverse()
+    .map((layer) => layer.metadata?.corestack?.legend)
+    .filter((entry) => {
+      if (!entry?.items?.length || seen.has(entry.key)) return false;
+      seen.add(entry.key);
+      return true;
+    });
+  const selected = entries.find((entry) => entry.key === "demographics");
+  return selected
+    ? [selected, ...entries.filter((entry) => entry !== selected)]
+    : entries;
+};
+
+const legendPluginState = (entries) => {
+  const selected = entries[0];
+  if (!selected) return undefined;
+  return {
+    manifestUrls: [],
+    activePluginIds: [
+      "maplibre-layer-control",
+      "maplibre-atmosphere-effects",
+      "maplibre-deckgl-viz",
+      "maplibre-gl-components",
+    ],
+    mapControlPositions: { "maplibre-gl-components": "top-right" },
+    settings: {
+      "maplibre-gl-components": {
+        legend: {
+          visible: true,
+          collapsed: true,
+          hasLegend: true,
+          selectedLegendIndex: 0,
+          title: selected.title,
+          items: selected.items,
+          legendPosition: selected.legendPosition,
+          legends: entries.map(({ key: _key, ...entry }) => entry),
+        },
+      },
+    },
+  };
+};
+
 const readableError = (error) =>
   error instanceof Error ? error.message : String(error);
 
@@ -787,7 +1001,7 @@ export const buildGeoLibreProject = async ({
     (layer) => layer.id === "administrative_boundaries"
   );
   const socioeconomicData = await loadVector(socioeconomic, true);
-  // Both Overview entries use the same GeoServer source. The request cache
+  // Both default Demographic entries use the same GeoServer source. The request cache
   // makes this a metadata/style duplication, not a second network download.
   await loadVector(administrative, true, false);
   const bounds = geoJsonBounds(socioeconomicData);
@@ -818,13 +1032,14 @@ export const buildGeoLibreProject = async ({
     const styles = Object.fromEntries(
       orderedLayers.map((layer) => [layer.id, layer.style])
     );
+    const mapLegends = mapLegendEntries(orderedLayers);
     const viewer = resolveGeoLibreViewer();
 
     return {
       version: GEOLIBRE_PROJECT_FORMAT_VERSION,
       name: `${tehsil}, ${district}: CoRE Stack landscape`,
       mapView: mapViewFromBounds(bounds, viewport),
-      basemapStyleUrl: DEFAULT_BASEMAP_STYLE,
+      basemapStyleUrl: DEFAULT_GEOLIBRE_BASEMAP_STYLE,
       basemapVisible: true,
       basemapOpacity: 1,
       layers: orderedLayers,
@@ -835,8 +1050,9 @@ export const buildGeoLibreProject = async ({
       })),
       styles,
       preferences: projectPreferences,
+      plugins: legendPluginState(mapLegends),
       legend: {
-        title: `${tehsil} landscape layers`,
+        title: `${tehsil} CoRE Stack layers`,
         groupByLayer: true,
         order: [...orderedLayers].reverse().map((layer) => layer.id),
         overrides: {},
@@ -844,6 +1060,11 @@ export const buildGeoLibreProject = async ({
       metadata: {
         generatedAtUtc: new Date().toISOString(),
         generatedBy: "Know Your Landscape",
+        license: {
+          name: "CC BY 4.0",
+          url: "https://creativecommons.org/licenses/by/4.0/",
+          notice: "CoRE Stack datasets are available under CC BY 4.0",
+        },
         scope: { level: "tehsil", state, district, tehsil, bounds },
         geolibre: {
           applicationVersion: GEOLIBRE_CONFIG.version,
@@ -851,10 +1072,10 @@ export const buildGeoLibreProject = async ({
           viewerUrl: viewer.url,
         },
         layerLoading: {
-          stage: "overview",
+          stage: "demographic",
           order: [
             "Administrative Boundaries and Socio-Economic Profile",
-            "Other vector layers on first visibility toggle",
+            "All other vector layers on first visibility toggle",
             "Raster tiles on visibility toggle",
           ],
           initialLoadFailures: [...failures],
@@ -866,6 +1087,6 @@ export const buildGeoLibreProject = async ({
     };
   };
 
-  onProgress({ phase: "project", message: "Opening Overview in GeoLibre…" });
+  onProgress({ phase: "project", message: "Opening this tehsil in GeoLibre…" });
   return createProject();
 };
diff --git a/src/components/geolibre/geolibreProject.test.js b/src/components/geolibre/geolibreProject.test.js
index b82218cf..0732c967 100644
--- a/src/components/geolibre/geolibreProject.test.js
+++ b/src/components/geolibre/geolibreProject.test.js
@@ -1,5 +1,6 @@
 import {
   buildGeoLibreProject,
+  DEFAULT_GEOLIBRE_BASEMAP_STYLE,
   formatGeoServerName,
   geoJsonBounds,
   hydrateGeoLibreVectorLayer,
@@ -65,7 +66,7 @@ describe("GeoLibre 2.2 project generation", () => {
     );
   });
 
-  it("builds Overview WFS layers and downloadable, lazy styled rasters", async () => {
+  it("builds default Demographic WFS layers and downloadable, lazy styled rasters", async () => {
     const project = await buildGeoLibreProject({
       ...location,
       fetchFeatureCollection: successfulFetch,
@@ -75,6 +76,14 @@ describe("GeoLibre 2.2 project generation", () => {
     expect(project.layers).toHaveLength(GEOLIBRE_LAYERS.length);
     expect(project.layers).toHaveLength(45);
     expect(project.mapView.bbox).toEqual([92.9, 24.7, 93.2, 25]);
+    expect(project.basemapStyleUrl).toBe(DEFAULT_GEOLIBRE_BASEMAP_STYLE);
+    expect(decodeURIComponent(project.basemapStyleUrl)).toContain(
+      "https://mt1.google.com/vt/lyrs=y&x={x}&y={y}&z={z}"
+    );
+    expect(project.metadata.license).toMatchObject({
+      name: "CC BY 4.0",
+      notice: "CoRE Stack datasets are available under CC BY 4.0",
+    });
 
     const socioeconomic = project.layers.find(
       (layer) => layer.id === "corestack-demographics"
@@ -160,7 +169,7 @@ describe("GeoLibre 2.2 project generation", () => {
     expect(successfulFetch).toHaveBeenCalledTimes(1);
   });
 
-  it("orders the native GeoLibre panel by overview, vectors, LULC, then rasters", async () => {
+  it("uses the deployed domain taxonomy while preserving the preferred order", async () => {
     const project = await buildGeoLibreProject({
       ...location,
       fetchFeatureCollection: successfulFetch,
@@ -172,39 +181,78 @@ describe("GeoLibre 2.2 project generation", () => {
     expect(displayIds.slice(0, 5)).toEqual([
       "corestack-administrative_boundaries",
       "corestack-demographics",
-      "corestack-mws_layers",
-      "corestack-hydrological_boundaries",
-      "corestack-mws_layers_fortnight",
+      "corestack-drainage",
+      "corestack-remote_sensed_waterbodies",
+      "corestack-soge",
     ]);
     expect(displayIds.indexOf("corestack-lulc_level_3_24_25")).toBeLessThan(
       displayIds.indexOf("corestack-lulc_level_3_23_24")
     );
-    expect(displayIds.indexOf("corestack-lulc_level_1_24_25")).toBeLessThan(
+    expect(displayIds.indexOf("corestack-lulc_level_3_24_25")).toBeLessThan(
       displayIds.indexOf("corestack-terrain")
     );
     expect(project.layerGroups.map((group) => group.id)).toEqual([
-      "overview",
-      "watersheds",
-      "vectors",
+      "demographic",
+      "hydrology",
       "lulc-3",
       "lulc-2",
       "lulc-1",
-      "rasters",
+      "land",
+      "agriculture",
+      "restoration",
+      "climate",
+      "nrega",
     ]);
   });
 
-  it("loads only the shared Overview source during project creation", async () => {
+  it("starts a minimized color legend with the configured layer palettes", async () => {
+    const project = await buildGeoLibreProject({
+      ...location,
+      fetchFeatureCollection: successfulFetch,
+    });
+    const legend =
+      project.plugins.settings["maplibre-gl-components"].legend;
+
+    expect(project.plugins.activePluginIds).toContain(
+      "maplibre-gl-components"
+    );
+    expect(legend).toMatchObject({
+      visible: true,
+      collapsed: true,
+      hasLegend: true,
+      title: "Socio-Economic Profile legend",
+    });
+    expect(legend.items).toContainEqual({
+      label: "Literacy 70% or above",
+      color: "#006400",
+      shape: "square",
+    });
+    expect(legend.legends.map((entry) => entry.title)).toEqual(
+      expect.arrayContaining([
+        "Drainage legend",
+        "Terrain legend",
+        "LULC Level 3 legend",
+        "Restoration Opportunities legend",
+      ])
+    );
+  });
+
+  it("loads only the shared Demographic source during project creation", async () => {
     const project = await buildGeoLibreProject({
       ...location,
       fetchFeatureCollection: successfulFetch,
     });
 
-    expect(project.metadata.layerLoading.stage).toBe("overview");
+    expect(project.metadata.layerLoading.stage).toBe("demographic");
     expect(
       project.layers
         .filter(
           (layer) =>
-            layer.type === "geojson" && layer.groupId !== "overview"
+            layer.type === "geojson" &&
+            ![
+              "corestack-administrative_boundaries",
+              "corestack-demographics",
+            ].includes(layer.id)
         )
         .every((layer) => layer.metadata.loadState === "unloaded")
     ).toBe(true);
diff --git a/src/components/landing_navbar.jsx b/src/components/landing_navbar.jsx
index 23769a1d..9fd99cdd 100644
--- a/src/components/landing_navbar.jsx
+++ b/src/components/landing_navbar.jsx
@@ -77,6 +77,18 @@ const LandingNavbar = () => {
                   </a>
                   .
                 </p>
+                <p className="text-center text-xs text-slate-600 sm:text-right">
+                  CoRE Stack datasets are available under{" "}
+                  <a
+                    href="https://creativecommons.org/licenses/by/4.0/"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="font-medium text-purple-700 underline decoration-purple-300 underline-offset-2 hover:text-purple-900"
+                  >
+                    CC BY 4.0
+                  </a>
+                  .
+                </p>
               </div>
             )}
 
diff --git a/src/components/landing_navbar.test.jsx b/src/components/landing_navbar.test.jsx
index 95592850..156e1fa4 100644
--- a/src/components/landing_navbar.test.jsx
+++ b/src/components/landing_navbar.test.jsx
@@ -26,5 +26,11 @@ describe("Download Layers navigation", () => {
     expect(document.body.textContent).toContain(
       "To Use these layers with QGIS, download layer styles from the CoRE Stack QGIS Styles repository."
     );
+    expect(
+      screen.getByRole("link", { name: "CC BY 4.0" }).getAttribute("href")
+    ).toBe("https://creativecommons.org/licenses/by/4.0/");
+    expect(document.body.textContent).toContain(
+      "CoRE Stack datasets are available under CC BY 4.0."
+    );
   });
 });
diff --git a/src/config/geolibreLayers.js b/src/config/geolibreLayers.js
index d8647f0c..65c3c0eb 100644
--- a/src/config/geolibreLayers.js
+++ b/src/config/geolibreLayers.js
@@ -22,7 +22,8 @@ const LAYERS = [
     id: "administrative_boundaries",
     label: "Administrative Boundaries",
     domain: "Demographic",
-    loadGroup: "overview",
+    loadGroup: "demographic",
+    defaultVisible: true,
     sourceType: "wfs",
     workspace: "panchayat_boundaries",
     geometryType: "polygon",
@@ -34,7 +35,8 @@ const LAYERS = [
     id: "demographics",
     label: "Socio-Economic Profile",
     domain: "Demographic",
-    loadGroup: "overview",
+    loadGroup: "demographic",
+    defaultVisible: true,
     sourceType: "wfs",
     workspace: "panchayat_boundaries",
     geometryType: "polygon",
@@ -46,7 +48,7 @@ const LAYERS = [
     id: "mws_layers",
     label: "Micro-watersheds and Hydrological Variables",
     domain: "Climate",
-    loadGroup: "watersheds",
+    loadGroup: "climate",
     sourceType: "wfs",
     workspace: "mws_layers",
     geometryType: "polygon",
@@ -59,7 +61,7 @@ const LAYERS = [
     id: "hydrological_boundaries",
     label: "Hydrological Boundaries",
     domain: "Climate",
-    loadGroup: "watersheds",
+    loadGroup: "climate",
     sourceType: "wfs",
     workspace: "mws_layers",
     geometryType: "polygon",
@@ -72,7 +74,7 @@ const LAYERS = [
     id: "mws_layers_fortnight",
     label: "Fortnightly Hydrological Variables",
     domain: "Climate",
-    loadGroup: "watersheds",
+    loadGroup: "climate",
     sourceType: "wfs",
     workspace: "mws_layers",
     geometryType: "polygon",
@@ -85,7 +87,7 @@ const LAYERS = [
     id: "terrain_vector",
     label: "Terrain Vector",
     domain: "Land",
-    loadGroup: "vectors",
+    loadGroup: "land",
     sourceType: "wfs",
     workspace: "terrain",
     geometryType: "polygon",
@@ -97,7 +99,7 @@ const LAYERS = [
     id: "drainage",
     label: "Drainage",
     domain: "Hydrology",
-    loadGroup: "vectors",
+    loadGroup: "hydrology",
     sourceType: "wfs",
     workspace: "drainage",
     geometryType: "line",
@@ -109,7 +111,7 @@ const LAYERS = [
     id: "remote_sensed_waterbodies",
     label: "Remote-Sensed Waterbodies",
     domain: "Hydrology",
-    loadGroup: "vectors",
+    loadGroup: "hydrology",
     sourceType: "wfs",
     workspace: "swb",
     geometryType: "polygon",
@@ -122,7 +124,7 @@ const LAYERS = [
     id: "soge",
     label: "Stage of Groundwater Extraction",
     domain: "Hydrology",
-    loadGroup: "vectors",
+    loadGroup: "hydrology",
     sourceType: "wfs",
     workspace: "soge",
     geometryType: "polygon",
@@ -134,7 +136,7 @@ const LAYERS = [
     id: "aquifer",
     label: "Aquifer",
     domain: "Hydrology",
-    loadGroup: "vectors",
+    loadGroup: "hydrology",
     sourceType: "wfs",
     workspace: "aquifer",
     geometryType: "polygon",
@@ -147,7 +149,7 @@ const LAYERS = [
     id: "cropping_intensity",
     label: "Cropping Intensity",
     domain: "Agriculture",
-    loadGroup: "vectors",
+    loadGroup: "agriculture",
     sourceType: "wfs",
     workspace: "crop_intensity",
     geometryType: "polygon",
@@ -159,7 +161,7 @@ const LAYERS = [
     id: "drought",
     label: "Drought",
     domain: "Agriculture",
-    loadGroup: "vectors",
+    loadGroup: "agriculture",
     sourceType: "wfs",
     workspace: "drought",
     geometryType: "polygon",
@@ -171,7 +173,7 @@ const LAYERS = [
     id: "nrega",
     label: "NREGA Assets",
     domain: "NREGA",
-    loadGroup: "vectors",
+    loadGroup: "nrega",
     sourceType: "wfs",
     workspace: "nrega_assets",
     geometryType: "point",
@@ -183,7 +185,7 @@ const LAYERS = [
     id: "terrain",
     label: "Terrain",
     domain: "Land",
-    loadGroup: "rasters",
+    loadGroup: "land",
     sourceType: "wms",
     workspace: "terrain",
     layerName: ({ district, tehsil }) => `${district}_${tehsil}_terrain_raster`,
@@ -194,7 +196,7 @@ const LAYERS = [
     id: "clart",
     label: "CLART",
     domain: "Hydrology",
-    loadGroup: "rasters",
+    loadGroup: "hydrology",
     sourceType: "wms",
     workspace: "clart",
     layerName: ({ district, tehsil }) => `${district}_${tehsil}_clart`,
@@ -205,7 +207,7 @@ const LAYERS = [
     id: "afforestation",
     label: "Change Detection: Afforestation",
     domain: "Restoration",
-    loadGroup: "rasters",
+    loadGroup: "restoration",
     sourceType: "wms",
     workspace: "change_detection",
     layerName: ({ district, tehsil }) =>
@@ -217,7 +219,7 @@ const LAYERS = [
     id: "deforestation",
     label: "Change Detection: Deforestation",
     domain: "Restoration",
-    loadGroup: "rasters",
+    loadGroup: "restoration",
     sourceType: "wms",
     workspace: "change_detection",
     layerName: ({ district, tehsil }) =>
@@ -229,7 +231,7 @@ const LAYERS = [
     id: "degradation",
     label: "Change Detection: Degradation",
     domain: "Restoration",
-    loadGroup: "rasters",
+    loadGroup: "restoration",
     sourceType: "wms",
     workspace: "change_detection",
     layerName: ({ district, tehsil }) =>
@@ -241,7 +243,7 @@ const LAYERS = [
     id: "urbanization",
     label: "Change Detection: Urbanization",
     domain: "Restoration",
-    loadGroup: "rasters",
+    loadGroup: "restoration",
     sourceType: "wms",
     workspace: "change_detection",
     layerName: ({ district, tehsil }) =>
@@ -253,7 +255,7 @@ const LAYERS = [
     id: "cropintensity",
     label: "Change Detection: Crop Intensity",
     domain: "Restoration",
-    loadGroup: "rasters",
+    loadGroup: "restoration",
     sourceType: "wms",
     workspace: "change_detection",
     layerName: ({ district, tehsil }) =>
@@ -265,7 +267,7 @@ const LAYERS = [
     id: "restoration",
     label: "Restoration Opportunities",
     domain: "Restoration",
-    loadGroup: "rasters",
+    loadGroup: "restoration",
     sourceType: "wms",
     workspace: "restoration",
     layerName: ({ district, tehsil }) =>

From 13efb0199fb5824fa1db14e64ce07e3d2b805ded Mon Sep 17 00:00:00 2001
From: amit-spatial <amit.kumar@gramvaani.org>
Date: Wed, 22 Jul 2026 13:06:19 +0000
Subject: [PATCH 7/9] sync legends with visible layers

---
 src/components/geolibre/README.md             |  22 ++--
 src/components/geolibre/geolibreProject.js    | 104 ++++++++++++++----
 .../geolibre/geolibreProject.test.js          |  60 ++++++++--
 src/pages/LandscapeExplorer.jsx               |   9 +-
 4 files changed, 153 insertions(+), 42 deletions(-)

diff --git a/src/components/geolibre/README.md b/src/components/geolibre/README.md
index 3b3b561c..acd2e687 100644
--- a/src/components/geolibre/README.md
+++ b/src/components/geolibre/README.md
@@ -56,7 +56,7 @@ sequenceDiagram
     GeoLibre-->>KYL: geolibre:state
     KYL->>GeoServer: WFS GetFeature
     GeoServer-->>KYL: GeoJSON FeatureCollection
-    KYL-->>GeoLibre: Hydrated project state
+    KYL-->>GeoLibre: Hydrated state and active-layer legends
     User->>GeoLibre: Toggle the layer off and on
     GeoLibre-->>KYL: geolibre:state
     Note over KYL,GeoLibre: Reuse cached layer; no second WFS request or bbox fit
@@ -72,7 +72,8 @@ sequenceDiagram
    the deployed KYL domain, GeoServer source, QML reference, year, and order.
 4. **Cartography:** vector QML logic is represented in GeoLibre styles; raster
    QML is rendered by the corresponding named GeoServer WMS style. Matching
-   color labels are also persisted in GeoLibre's native on-map legends.
+   color labels are synchronized into GeoLibre's native legend only while the
+   corresponding layer is visible.
 5. **Loading:** only the shared default WFS is fetched at startup. Other
    vectors hydrate once on first toggle; rasters remain native lazy WMS layers.
 6. **Download:** vector data remains available through GeoLibre and complete
@@ -116,11 +117,13 @@ attribution. A deployment can replace it with another valid MapLibre style:
 REACT_APP_GEOLIBRE_BASEMAP_STYLE_URL=https://maps.example.org/style.json
 ```
 
-GeoLibre's built-in Components plugin provides an on-map legend in minimized
-mode by default, keeping the map clear. Socio-Economic Profile is selected
-initially when the user expands it, and the selector includes the configured
-vector, raster, and LULC palettes. The separate `legend` project field retains
-ordering and grouping for GeoLibre's Print Layout legend.
+GeoLibre's built-in Components plugin provides one on-map legend control in
+minimized mode by default. Its rendered legend uses the bottom-right map corner,
+and its selector contains only layers that are currently visible. Toggling a
+layer on adds its symbol classes; toggling it off removes them. One selected
+layer's classes are shown at a time, so enabling several layers does not expand
+every palette across the map. The separate `legend` project field retains the
+complete layer ordering and grouping for GeoLibre's Print Layout legend.
 
 ## Version configuration
 
@@ -264,8 +267,9 @@ Check both routes:
    Satellite Hybrid basemap appears, the map fits the tehsil, and Demographic
    shows Administrative Boundaries then Socio-Economic Profile,
    both visible at `0.80`.
-4. Confirm the native legend starts minimized, expands to the Socio-Economic
-   colors, and its selector includes raster and LULC legends.
+4. Confirm the native legend starts minimized and lists only Administrative
+   Boundaries and Socio-Economic Profile. Toggle a raster or LULC layer on and
+   confirm its legend appears; toggle it off and confirm that entry disappears.
 5. Confirm no other layer loads by itself. Toggle a Climate layer and Drainage
    under Hydrology and confirm each loads. Toggle each
    off and on again and confirm its WFS request is not repeated.
diff --git a/src/components/geolibre/geolibreProject.js b/src/components/geolibre/geolibreProject.js
index 5a60cf15..28205e5d 100644
--- a/src/components/geolibre/geolibreProject.js
+++ b/src/components/geolibre/geolibreProject.js
@@ -421,7 +421,7 @@ const layerLegend = (catalogLayer, style) => {
     key: catalogLayer.baseId || catalogLayer.id,
     title: `${baseTitle} legend`,
     items,
-    legendPosition: "bottom-left",
+    legendPosition: "bottom-right",
   };
 };
 
@@ -778,35 +778,93 @@ const mapLegendEntries = (orderedLayers) => {
     : entries;
 };
 
-const legendPluginState = (entries) => {
+const legendPluginState = (entries, currentPlugins) => {
   const selected = entries[0];
-  if (!selected) return undefined;
+  const currentComponents =
+    currentPlugins?.settings?.["maplibre-gl-components"] || {};
+  const currentLegend = currentComponents.legend;
+  const selectedIndex = Math.max(
+    0,
+    entries.findIndex((entry) => entry.title === currentLegend?.title)
+  );
+  const selectedEntry = entries[selectedIndex] || selected;
+  const legend = selectedEntry
+    ? {
+        ...currentLegend,
+        visible: true,
+        collapsed: currentLegend?.collapsed ?? true,
+        hasLegend: true,
+        selectedLegendIndex: selectedIndex,
+        title: selectedEntry.title,
+        items: selectedEntry.items,
+        legendPosition: selectedEntry.legendPosition,
+        legends: entries.map(({ key: _key, ...entry }) => entry),
+      }
+    : {
+        ...currentLegend,
+        visible: false,
+        collapsed: true,
+        hasLegend: false,
+        selectedLegendIndex: 0,
+        title: "Legend",
+        items: [],
+        legendPosition: "bottom-right",
+        legends: [],
+      };
+
   return {
-    manifestUrls: [],
-    activePluginIds: [
-      "maplibre-layer-control",
-      "maplibre-atmosphere-effects",
-      "maplibre-deckgl-viz",
-      "maplibre-gl-components",
-    ],
-    mapControlPositions: { "maplibre-gl-components": "top-right" },
+    manifestUrls: currentPlugins?.manifestUrls || [],
+    activePluginIds: Array.from(
+      new Set([
+        ...(currentPlugins?.activePluginIds || [
+          "maplibre-layer-control",
+          "maplibre-atmosphere-effects",
+          "maplibre-deckgl-viz",
+        ]),
+        "maplibre-gl-components",
+      ])
+    ),
+    mapControlPositions: {
+      ...currentPlugins?.mapControlPositions,
+      "maplibre-gl-components": "top-right",
+    },
     settings: {
+      ...currentPlugins?.settings,
       "maplibre-gl-components": {
-        legend: {
-          visible: true,
-          collapsed: true,
-          hasLegend: true,
-          selectedLegendIndex: 0,
-          title: selected.title,
-          items: selected.items,
-          legendPosition: selected.legendPosition,
-          legends: entries.map(({ key: _key, ...entry }) => entry),
-        },
+        ...currentComponents,
+        legend,
       },
     },
   };
 };
 
+const legendStateSignature = (legend) =>
+  JSON.stringify({
+    visible: legend?.visible,
+    title: legend?.title,
+    items: legend?.items,
+    legendPosition: legend?.legendPosition,
+    legends: legend?.legends,
+  });
+
+export const syncGeoLibreActiveLegends = (project) => {
+  if (!project?.layers) return project;
+  const entries = mapLegendEntries(
+    project.layers.filter((layer) => layer.visible)
+  );
+  const plugins = legendPluginState(entries, project.plugins);
+  const currentLegend =
+    project.plugins?.settings?.["maplibre-gl-components"]?.legend;
+  const nextLegend = plugins.settings["maplibre-gl-components"].legend;
+
+  if (
+    legendStateSignature(currentLegend) === legendStateSignature(nextLegend)
+  ) {
+    return project;
+  }
+  return { ...project, plugins };
+};
+
 const readableError = (error) =>
   error instanceof Error ? error.message : String(error);
 
@@ -1032,7 +1090,9 @@ export const buildGeoLibreProject = async ({
     const styles = Object.fromEntries(
       orderedLayers.map((layer) => [layer.id, layer.style])
     );
-    const mapLegends = mapLegendEntries(orderedLayers);
+    const mapLegends = mapLegendEntries(
+      orderedLayers.filter((layer) => layer.visible)
+    );
     const viewer = resolveGeoLibreViewer();
 
     return {
diff --git a/src/components/geolibre/geolibreProject.test.js b/src/components/geolibre/geolibreProject.test.js
index 0732c967..df5c8b56 100644
--- a/src/components/geolibre/geolibreProject.test.js
+++ b/src/components/geolibre/geolibreProject.test.js
@@ -5,6 +5,7 @@ import {
   geoJsonBounds,
   hydrateGeoLibreVectorLayer,
   mapViewFromBounds,
+  syncGeoLibreActiveLegends,
 } from "./geolibreProject";
 import { GEOLIBRE_LAYERS } from "../../config/geolibreLayers";
 
@@ -205,7 +206,7 @@ describe("GeoLibre 2.2 project generation", () => {
     ]);
   });
 
-  it("starts a minimized color legend with the configured layer palettes", async () => {
+  it("starts a minimized legend containing only active default layers", async () => {
     const project = await buildGeoLibreProject({
       ...location,
       fetchFeatureCollection: successfulFetch,
@@ -227,14 +228,55 @@ describe("GeoLibre 2.2 project generation", () => {
       color: "#006400",
       shape: "square",
     });
-    expect(legend.legends.map((entry) => entry.title)).toEqual(
-      expect.arrayContaining([
-        "Drainage legend",
-        "Terrain legend",
-        "LULC Level 3 legend",
-        "Restoration Opportunities legend",
-      ])
-    );
+    expect(legend.legendPosition).toBe("bottom-right");
+    expect(legend.legends.map((entry) => entry.title)).toEqual([
+      "Socio-Economic Profile legend",
+      "Administrative Boundaries legend",
+    ]);
+  });
+
+  it("adds and removes legend entries when layer visibility changes", async () => {
+    const project = await buildGeoLibreProject({
+      ...location,
+      fetchFeatureCollection: successfulFetch,
+    });
+    const withVisibleLayers = {
+      ...project,
+      layers: project.layers.map((layer) =>
+        ["corestack-drainage", "corestack-terrain"].includes(layer.id)
+          ? { ...layer, visible: true }
+          : layer
+      ),
+    };
+    const synced = syncGeoLibreActiveLegends(withVisibleLayers);
+    const legend =
+      synced.plugins.settings["maplibre-gl-components"].legend;
+
+    expect(legend.legends.map((entry) => entry.title)).toEqual([
+      "Socio-Economic Profile legend",
+      "Administrative Boundaries legend",
+      "Drainage legend",
+      "Terrain legend",
+    ]);
+
+    const drainageHidden = {
+      ...synced,
+      layers: synced.layers.map((layer) =>
+        layer.id === "corestack-drainage"
+          ? { ...layer, visible: false }
+          : layer
+      ),
+    };
+    const resynced = syncGeoLibreActiveLegends(drainageHidden);
+    expect(
+      resynced.plugins.settings["maplibre-gl-components"].legend.legends.map(
+        (entry) => entry.title
+      )
+    ).toEqual([
+      "Socio-Economic Profile legend",
+      "Administrative Boundaries legend",
+      "Terrain legend",
+    ]);
   });
 
   it("loads only the shared Demographic source during project creation", async () => {
diff --git a/src/pages/LandscapeExplorer.jsx b/src/pages/LandscapeExplorer.jsx
index ef9e8325..83c6e31c 100644
--- a/src/pages/LandscapeExplorer.jsx
+++ b/src/pages/LandscapeExplorer.jsx
@@ -5,6 +5,7 @@ import GeoLibreFrame from "../components/geolibre/GeoLibreFrame";
 import {
   buildGeoLibreProject,
   hydrateGeoLibreVectorLayer,
+  syncGeoLibreActiveLegends,
 } from "../components/geolibre/geolibreProject";
 import LandingNavbar from "../components/landing_navbar";
 import {
@@ -136,10 +137,12 @@ const LandscapeExplorer = () => {
       .then(async () => {
         if (viewerScopeKey !== currentScopeKeyRef.current) return;
 
-        let nextProject = mergeHydratedVectorLayers(
+        const mergedProject = mergeHydratedVectorLayers(
           viewerProject,
           hydratedLayersRef.current
         );
+        let nextProject = syncGeoLibreActiveLegends(mergedProject);
+        const legendChanged = nextProject !== mergedProject;
         const layersToLoad = nextProject.layers.filter(
           (layer) =>
             layer.type === "geojson" &&
@@ -162,7 +165,9 @@ const LandscapeExplorer = () => {
         if (
           viewerScopeKey !== currentScopeKeyRef.current ||
           sequence !== lazyStateSequenceRef.current ||
-          (!layersToLoad.length && !hydrationDirtyRef.current)
+          (!layersToLoad.length &&
+            !hydrationDirtyRef.current &&
+            !legendChanged)
         ) {
           return;
         }

From 8391e6c7c0f0ed279454b446aead2c4b4d51fb06 Mon Sep 17 00:00:00 2001
From: amit-spatial <amit.kumar@gramvaani.org>
Date: Wed, 22 Jul 2026 13:11:14 +0000
Subject: [PATCH 8/9] move micro-watersheds to hydrology

---
 src/components/geolibre/README.md               |  6 +++---
 src/components/geolibre/geolibreProject.test.js | 17 ++++++++++++++---
 src/config/geolibreLayers.js                    | 12 ++++++------
 3 files changed, 23 insertions(+), 12 deletions(-)

diff --git a/src/components/geolibre/README.md b/src/components/geolibre/README.md
index acd2e687..927f0807 100644
--- a/src/components/geolibre/README.md
+++ b/src/components/geolibre/README.md
@@ -87,7 +87,7 @@ GeoLibre's own layer panel follows the deployed Download Layers taxonomy,
 ordered top-first as:
 
 1. Demographic (Administrative Boundaries, Socio-Economic Profile)
-2. Hydrology
+2. Hydrology (including micro-watersheds and hydrological variables)
 3. LULC Level 3 by year
 4. LULC Level 2 by year
 5. LULC Level 1 by year
@@ -270,7 +270,7 @@ Check both routes:
 4. Confirm the native legend starts minimized and lists only Administrative
    Boundaries and Socio-Economic Profile. Toggle a raster or LULC layer on and
    confirm its legend appears; toggle it off and confirm that entry disappears.
-5. Confirm no other layer loads by itself. Toggle a Climate layer and Drainage
+5. Confirm no other layer loads by itself. Toggle Micro-watersheds and Drainage
    under Hydrology and confirm each loads. Toggle each
    off and on again and confirm its WFS request is not repeated.
 6. Confirm the map does not refit after those vector loads. Enable a raster and
@@ -286,7 +286,7 @@ refreshed or shared on the same KYL host because the location is URL-backed.
 For a release upgrade, verify all of the following before changing the default
 version: the ready handshake reports the expected release, the project loads
 without `geolibre:error`, both default Demographic layers are visible at `0.8`,
-the full tehsil fits exactly once, Climate, Hydrology, and other vectors hydrate
+the full tehsil fits exactly once, Hydrology and other vectors hydrate
 only when toggled and are then reused, WMS tiles appear only when enabled, and GeoLibre
 can save/export the resulting project.
 
diff --git a/src/components/geolibre/geolibreProject.test.js b/src/components/geolibre/geolibreProject.test.js
index df5c8b56..708d076d 100644
--- a/src/components/geolibre/geolibreProject.test.js
+++ b/src/components/geolibre/geolibreProject.test.js
@@ -182,10 +182,21 @@ describe("GeoLibre 2.2 project generation", () => {
     expect(displayIds.slice(0, 5)).toEqual([
       "corestack-administrative_boundaries",
       "corestack-demographics",
-      "corestack-drainage",
-      "corestack-remote_sensed_waterbodies",
-      "corestack-soge",
+      "corestack-mws_layers",
+      "corestack-hydrological_boundaries",
+      "corestack-mws_layers_fortnight",
     ]);
+    expect(
+      project.layers
+        .filter((layer) =>
+          [
+            "corestack-mws_layers",
+            "corestack-hydrological_boundaries",
+            "corestack-mws_layers_fortnight",
+          ].includes(layer.id)
+        )
+        .every((layer) => layer.groupId === "hydrology")
+    ).toBe(true);
     expect(displayIds.indexOf("corestack-lulc_level_3_24_25")).toBeLessThan(
       displayIds.indexOf("corestack-lulc_level_3_23_24")
     );
diff --git a/src/config/geolibreLayers.js b/src/config/geolibreLayers.js
index 65c3c0eb..6d9ed637 100644
--- a/src/config/geolibreLayers.js
+++ b/src/config/geolibreLayers.js
@@ -47,8 +47,8 @@ const LAYERS = [
   {
     id: "mws_layers",
     label: "Micro-watersheds and Hydrological Variables",
-    domain: "Climate",
-    loadGroup: "climate",
+    domain: "Hydrology",
+    loadGroup: "hydrology",
     sourceType: "wfs",
     workspace: "mws_layers",
     geometryType: "polygon",
@@ -60,8 +60,8 @@ const LAYERS = [
   {
     id: "hydrological_boundaries",
     label: "Hydrological Boundaries",
-    domain: "Climate",
-    loadGroup: "climate",
+    domain: "Hydrology",
+    loadGroup: "hydrology",
     sourceType: "wfs",
     workspace: "mws_layers",
     geometryType: "polygon",
@@ -73,8 +73,8 @@ const LAYERS = [
   {
     id: "mws_layers_fortnight",
     label: "Fortnightly Hydrological Variables",
-    domain: "Climate",
-    loadGroup: "climate",
+    domain: "Hydrology",
+    loadGroup: "hydrology",
     sourceType: "wfs",
     workspace: "mws_layers",
     geometryType: "polygon",

From 9938a6d6c3779d41603f08726b520b5825ff9fdd Mon Sep 17 00:00:00 2001
From: amit-spatial <amit.kumar@gramvaani.org>
Date: Wed, 22 Jul 2026 15:33:08 +0000
Subject: [PATCH 9/9] remove header license line

---
 src/components/landing_navbar.jsx      | 12 ------------
 src/components/landing_navbar.test.jsx |  6 ------
 2 files changed, 18 deletions(-)

diff --git a/src/components/landing_navbar.jsx b/src/components/landing_navbar.jsx
index 9fd99cdd..23769a1d 100644
--- a/src/components/landing_navbar.jsx
+++ b/src/components/landing_navbar.jsx
@@ -77,18 +77,6 @@ const LandingNavbar = () => {
                   </a>
                   .
                 </p>
-                <p className="text-center text-xs text-slate-600 sm:text-right">
-                  CoRE Stack datasets are available under{" "}
-                  <a
-                    href="https://creativecommons.org/licenses/by/4.0/"
-                    target="_blank"
-                    rel="noopener noreferrer"
-                    className="font-medium text-purple-700 underline decoration-purple-300 underline-offset-2 hover:text-purple-900"
-                  >
-                    CC BY 4.0
-                  </a>
-                  .
-                </p>
               </div>
             )}
 
diff --git a/src/components/landing_navbar.test.jsx b/src/components/landing_navbar.test.jsx
index 156e1fa4..95592850 100644
--- a/src/components/landing_navbar.test.jsx
+++ b/src/components/landing_navbar.test.jsx
@@ -26,11 +26,5 @@ describe("Download Layers navigation", () => {
     expect(document.body.textContent).toContain(
       "To Use these layers with QGIS, download layer styles from the CoRE Stack QGIS Styles repository."
     );
-    expect(
-      screen.getByRole("link", { name: "CC BY 4.0" }).getAttribute("href")
-    ).toBe("https://creativecommons.org/licenses/by/4.0/");
-    expect(document.body.textContent).toContain(
-      "CoRE Stack datasets are available under CC BY 4.0."
-    );
   });
 });