From 1f66d7f5780c341873b0c1f7c59b056b72105d44 Mon Sep 17 00:00:00 2001
From: Anastasiia Ivanchenko <a.ivanchenko.eu@gmai.com>
Date: Tue, 7 Jul 2026 01:09:57 +0300
Subject: [PATCH 1/2] Draw the downloaded 40x40 patch extent on click, with a
 show/hide toggle
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A click does not download a single pixel: it pulls the whole native chunk
(40x40 cells = 2° x 2°). This outlines that patch on the map so the user
can see what was actually fetched.

- New geogrid helper `chunkPatchBounds` computes the geographic box of the
  native chunk containing the clicked cell; the store's chunk footprint is
  recorded in `ZARR_STORE.nativeChunks`.
- The selection overlay draws the patch as a faint fill with a dashed
  accent outline, beneath the precise cell marker, in both 2D and globe.
- A toggle button in the nav (with a pressed/active state) shows or hides
  the patch; it is on by default when a point is selected.
---
 src/components/layout/Nav.tsx                | 19 ++++++
 src/components/map/EarthMap.tsx              |  8 +++
 src/components/map/GlobeSelectionOverlay.tsx | 41 +++++++++++-
 src/components/ui/IconButton.tsx             | 18 ++++-
 src/icons/PatchIcon.tsx                      | 21 ++++++
 src/lib/constants/store.ts                   |  9 +++
 src/lib/map/geogrid.test.ts                  | 20 ++++++
 src/lib/map/geogrid.ts                       | 70 +++++++++++++++++---
 src/lib/map/selectionStyle.ts                | 12 ++++
 9 files changed, 205 insertions(+), 13 deletions(-)
 create mode 100644 src/icons/PatchIcon.tsx

diff --git a/src/components/layout/Nav.tsx b/src/components/layout/Nav.tsx
index 5b300f6..fa1f637 100644
--- a/src/components/layout/Nav.tsx
+++ b/src/components/layout/Nav.tsx
@@ -5,6 +5,7 @@ import { EditorViewTabs } from "@/components/layout/EditorViewTabs";
 import { NavActions } from "@/components/nav/NavActions";
 import { IconButton } from "@/components/ui/IconButton";
 import { CrosshairIcon } from "@/icons/CrosshairIcon";
+import { PatchIcon } from "@/icons/PatchIcon";
 import type { MapViewMode } from "@/types/map";
 
 type NavProps = {
@@ -12,6 +13,8 @@ type NavProps = {
   onViewModeChange?: (mode: MapViewMode) => void;
   hasSelection?: boolean;
   onZoomToSelection?: () => void;
+  showPatch?: boolean;
+  onTogglePatch?: () => void;
 };
 
 export function Nav({
@@ -19,6 +22,8 @@ export function Nav({
   onViewModeChange,
   hasSelection = false,
   onZoomToSelection,
+  showPatch = false,
+  onTogglePatch,
 }: NavProps) {
   return (
     <nav className="relative z-[100] flex w-full flex-col gap-0 overflow-visible">
@@ -40,6 +45,20 @@ export function Nav({
                 <CrosshairIcon />
               </IconButton>
             ) : null}
+            {hasSelection && onTogglePatch ? (
+              <IconButton
+                className="animate-[zoomToSelectionIn_0.18s_cubic-bezier(0.16,1,0.3,1)]"
+                aria-label={
+                  showPatch
+                    ? "Hide downloaded patch extent"
+                    : "Show downloaded patch extent"
+                }
+                aria-pressed={showPatch}
+                onClick={onTogglePatch}
+              >
+                <PatchIcon />
+              </IconButton>
+            ) : null}
           </div>
           <NavActions />
         </div>
diff --git a/src/components/map/EarthMap.tsx b/src/components/map/EarthMap.tsx
index 5267ac2..2694731 100644
--- a/src/components/map/EarthMap.tsx
+++ b/src/components/map/EarthMap.tsx
@@ -57,6 +57,7 @@ export function EarthMap() {
   const [viewMode, setViewMode] = useState<MapViewMode>("2d");
   const [mapSize, setMapSize] = useState({ width: 0, height: 0 });
   const [selection, setSelection] = useState<MapSelection | null>(null);
+  const [showPatch, setShowPatch] = useState(true);
   const [historyYears, setHistoryYears] = useState(DEFAULT_HISTORY_YEARS);
   const [loadingSeries, setLoadingSeries] = useState(false);
   const [seriesError, setSeriesError] = useState<string | null>(null);
@@ -184,6 +185,10 @@ export function EarthMap() {
     flyToView(focused, SELECTION_FOCUS_TRANSITION_MS);
   }, [flyToView, selection, viewMode, viewState]);
 
+  const handleTogglePatch = useCallback(() => {
+    setShowPatch((previous) => !previous);
+  }, []);
+
   const handleMove = useCallback(
     (event: ViewStateChangeEvent) => {
       setViewState(toMapViewState(event.viewState, viewMode));
@@ -226,6 +231,8 @@ export function EarthMap() {
           onViewModeChange={handleViewModeChange}
           hasSelection={selection !== null}
           onZoomToSelection={handleZoomToSelection}
+          showPatch={showPatch}
+          onTogglePatch={handleTogglePatch}
         />
       }
       sidebar={
@@ -276,6 +283,7 @@ export function EarthMap() {
                 mapSize={mapSize}
                 isLight={isLight}
                 isSphere={isSphere}
+                showPatch={showPatch}
               />
             ) : null}
           </Map>
diff --git a/src/components/map/GlobeSelectionOverlay.tsx b/src/components/map/GlobeSelectionOverlay.tsx
index 0cab83c..23a2108 100644
--- a/src/components/map/GlobeSelectionOverlay.tsx
+++ b/src/components/map/GlobeSelectionOverlay.tsx
@@ -3,11 +3,18 @@
 import { useMemo } from "react";
 import { Layer, Source } from "react-map-gl/maplibre";
 import {
+  chunkPatchBounds,
   gridCellToBounds,
   gridCellToGuidePaths,
   selectionGuideGeoJson,
 } from "@/lib/map/geogrid";
-import { rgba, SELECTION_CELL_COLOR, SELECTION_GUIDE_COLOR } from "@/lib/map/selectionStyle";
+import { ZARR_STORE } from "@/lib/constants/store";
+import {
+  rgba,
+  SELECTION_CELL_COLOR,
+  SELECTION_GUIDE_COLOR,
+  SELECTION_PATCH_COLOR,
+} from "@/lib/map/selectionStyle";
 import { viewportToGeoBounds } from "@/lib/map/viewportBounds";
 import type { GridCell, MapViewState } from "@/types/map";
 
@@ -17,6 +24,7 @@ type GlobeSelectionOverlayProps = {
   mapSize: { width: number; height: number };
   isLight: boolean;
   isSphere?: boolean;
+  showPatch?: boolean;
 };
 
 export function GlobeSelectionOverlay({
@@ -25,19 +33,28 @@ export function GlobeSelectionOverlay({
   mapSize,
   isLight,
   isSphere = false,
+  showPatch = false,
 }: GlobeSelectionOverlayProps) {
   const data = useMemo(() => {
     const guidePaths = gridCellToGuidePaths(
       gridCellToBounds(cell),
       viewportToGeoBounds(viewState, mapSize.width, mapSize.height),
     );
-    return selectionGuideGeoJson(cell, guidePaths, { densifyGuides: isSphere });
-  }, [cell, isSphere, mapSize.height, mapSize.width, viewState]);
+    return selectionGuideGeoJson(cell, guidePaths, {
+      densifyGuides: isSphere,
+      patchBounds: showPatch
+        ? chunkPatchBounds(cell, ZARR_STORE.nativeChunks.lat, ZARR_STORE.nativeChunks.lon)
+        : null,
+    });
+  }, [cell, isSphere, mapSize.height, mapSize.width, showPatch, viewState]);
 
   const guideColor = rgba(
     isLight ? SELECTION_GUIDE_COLOR.light : SELECTION_GUIDE_COLOR.dark,
   );
   const cellColor = isLight ? SELECTION_CELL_COLOR.light : SELECTION_CELL_COLOR.dark;
+  const patchColor = isLight
+    ? SELECTION_PATCH_COLOR.light
+    : SELECTION_PATCH_COLOR.dark;
 
   return (
     <Source id="map-selection" type="geojson" data={data}>
@@ -51,6 +68,24 @@ export function GlobeSelectionOverlay({
           "line-dasharray": [6, 5],
         }}
       />
+      <Layer
+        id="map-selection-patch-fill"
+        type="fill"
+        filter={["==", ["get", "kind"], "patch"]}
+        paint={{
+          "fill-color": rgba(patchColor.fill),
+        }}
+      />
+      <Layer
+        id="map-selection-patch-line"
+        type="line"
+        filter={["==", ["get", "kind"], "patch"]}
+        paint={{
+          "line-color": rgba(patchColor.line),
+          "line-width": 1.5,
+          "line-dasharray": [3, 3],
+        }}
+      />
       <Layer
         id="map-selection-cell-fill"
         type="fill"
diff --git a/src/components/ui/IconButton.tsx b/src/components/ui/IconButton.tsx
index 53e034b..f27a219 100644
--- a/src/components/ui/IconButton.tsx
+++ b/src/components/ui/IconButton.tsx
@@ -5,6 +5,7 @@ type IconButtonProps = {
   "aria-label": string;
   "aria-expanded"?: boolean;
   "aria-controls"?: string;
+  "aria-pressed"?: boolean;
 };
 
 // Every IconButton renders inside the editor nav, so the editor sizing/colour
@@ -14,6 +15,13 @@ const ICON_BUTTON_CLASS =
   "bg-editor-bg-primary text-editor-fg-secondary transition-all duration-200 " +
   "hover:border-editor-border hover:bg-editor-bg-primary hover:text-editor-fg-primary hover:shadow-editor";
 
+// Toggle buttons highlight with the accent when pressed.
+const ICON_BUTTON_PRESSED_CLASS =
+  "border-[color-mix(in_srgb,var(--accent)_45%,transparent)] " +
+  "bg-[color-mix(in_srgb,var(--accent)_16%,transparent)] text-accent " +
+  "hover:text-accent hover:border-[color-mix(in_srgb,var(--accent)_45%,transparent)] " +
+  "hover:bg-[color-mix(in_srgb,var(--accent)_16%,transparent)]";
+
 export function IconButton({
   children,
   onClick,
@@ -21,15 +29,23 @@ export function IconButton({
   "aria-label": ariaLabel,
   "aria-expanded": ariaExpanded,
   "aria-controls": ariaControls,
+  "aria-pressed": ariaPressed,
 }: IconButtonProps) {
   return (
     <button
       type="button"
-      className={[ICON_BUTTON_CLASS, className].filter(Boolean).join(" ")}
+      className={[
+        ICON_BUTTON_CLASS,
+        ariaPressed ? ICON_BUTTON_PRESSED_CLASS : null,
+        className,
+      ]
+        .filter(Boolean)
+        .join(" ")}
       onClick={onClick}
       aria-label={ariaLabel}
       aria-expanded={ariaExpanded}
       aria-controls={ariaControls}
+      aria-pressed={ariaPressed}
     >
       {children}
     </button>
diff --git a/src/icons/PatchIcon.tsx b/src/icons/PatchIcon.tsx
new file mode 100644
index 0000000..9e03747
--- /dev/null
+++ b/src/icons/PatchIcon.tsx
@@ -0,0 +1,21 @@
+export function PatchIcon() {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.7"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <rect x="3" y="3" width="18" height="18" rx="2" />
+      <path d="M9 3v18" />
+      <path d="M15 3v18" />
+      <path d="M3 9h18" />
+      <path d="M3 15h18" />
+    </svg>
+  );
+}
diff --git a/src/lib/constants/store.ts b/src/lib/constants/store.ts
index fd0bd90..954f049 100644
--- a/src/lib/constants/store.ts
+++ b/src/lib/constants/store.ts
@@ -19,6 +19,15 @@ export const ZARR_STORE = {
     latStart: 89.975,
     latStep: -0.05,
   },
+  /**
+   * On-disk chunk footprint along lat/lon. A click downloads this whole
+   * patch (40 x 40 cells = 2° x 2°), not a single pixel. Matches the store's
+   * `chunks` metadata `[1461, 24, 40, 40]`.
+   */
+  nativeChunks: {
+    lat: 40,
+    lon: 40,
+  },
   defaultVariable: "NEE",
 } as const;
 
diff --git a/src/lib/map/geogrid.test.ts b/src/lib/map/geogrid.test.ts
index 452ca41..189295a 100644
--- a/src/lib/map/geogrid.test.ts
+++ b/src/lib/map/geogrid.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import {
+  chunkPatchBounds,
   geoPointToZarrGrid,
   gridCellToBounds,
   gridCellToGuidePaths,
@@ -39,6 +40,25 @@ describe("gridCellToPolygon", () => {
   });
 });
 
+describe("chunkPatchBounds", () => {
+  it("spans the 40x40 native chunk that contains the cell", () => {
+    const { lat, lon } = ZARR_STORE.nativeChunks;
+    const cell = geoPointToZarrGrid({ lon: 10.012, lat: 51.998 });
+    const bounds = chunkPatchBounds(cell, lat, lon);
+
+    // 40 cells of 0.05° = 2° on each side.
+    expect(bounds.east - bounds.west).toBeCloseTo(lon * ZARR_STORE.spatialResolutionDeg);
+    expect(bounds.north - bounds.south).toBeCloseTo(lat * ZARR_STORE.spatialResolutionDeg);
+
+    // The clicked cell sits inside the patch.
+    const cellBounds = gridCellToBounds(cell);
+    expect(bounds.west).toBeLessThanOrEqual(cellBounds.west);
+    expect(bounds.east).toBeGreaterThanOrEqual(cellBounds.east);
+    expect(bounds.south).toBeLessThanOrEqual(cellBounds.south);
+    expect(bounds.north).toBeGreaterThanOrEqual(cellBounds.north);
+  });
+});
+
 describe("gridCellToGuidePaths", () => {
   it("extends a line from each cell edge to the viewport border", () => {
     const cell = {
diff --git a/src/lib/map/geogrid.ts b/src/lib/map/geogrid.ts
index 18e9d61..e58772f 100644
--- a/src/lib/map/geogrid.ts
+++ b/src/lib/map/geogrid.ts
@@ -51,9 +51,9 @@ export function gridCellToBounds(cell: GridCell): GridCellBounds {
   };
 }
 
-/** Closed lon/lat ring for the cell footprint (counter-clockwise). */
-export function gridCellToPolygon(cell: GridCell): GeoPoint[] {
-  const { west, east, south, north } = gridCellToBounds(cell);
+/** Closed lon/lat ring for the given bounds (counter-clockwise). */
+export function boundsToPolygon(bounds: GridCellBounds): GeoPoint[] {
+  const { west, east, south, north } = bounds;
 
   return [
     { lon: west, lat: north },
@@ -63,6 +63,42 @@ export function gridCellToPolygon(cell: GridCell): GeoPoint[] {
   ];
 }
 
+/** Closed lon/lat ring for the cell footprint (counter-clockwise). */
+export function gridCellToPolygon(cell: GridCell): GeoPoint[] {
+  return boundsToPolygon(gridCellToBounds(cell));
+}
+
+/**
+ * Geographic bounds of the on-disk chunk (patch) that contains a cell. A
+ * click downloads this whole patch, so this is what the "downloaded extent"
+ * box outlines.
+ */
+export function chunkPatchBounds(
+  cell: GridCell,
+  chunkLat: number,
+  chunkLon: number,
+): GridCellBounds {
+  const firstLatIdx = Math.floor(cell.latIndex / chunkLat) * chunkLat;
+  const lastLatIdx = Math.min(firstLatIdx + chunkLat, dimensions.lat) - 1;
+  const firstLonIdx = Math.floor(cell.lonIndex / chunkLon) * chunkLon;
+  const lastLonIdx = Math.min(firstLonIdx + chunkLon, dimensions.lon) - 1;
+
+  const latEdgeA = grid.latStart + firstLatIdx * grid.latStep;
+  const latEdgeB = grid.latStart + lastLatIdx * grid.latStep;
+  const lonEdgeA = grid.lonStart + firstLonIdx * grid.lonStep;
+  const lonEdgeB = grid.lonStart + lastLonIdx * grid.lonStep;
+
+  const halfLon = Math.abs(grid.lonStep) / 2;
+  const halfLat = Math.abs(grid.latStep) / 2;
+
+  return {
+    west: Math.min(lonEdgeA, lonEdgeB) - halfLon,
+    east: Math.max(lonEdgeA, lonEdgeB) + halfLon,
+    south: Math.min(latEdgeA, latEdgeB) - halfLat,
+    north: Math.max(latEdgeA, latEdgeB) + halfLat,
+  };
+}
+
 export type LonLatPath = [lon: number, lat: number][];
 
 /** Dotted guide lines from each cell edge to the viewport border. */
@@ -126,23 +162,27 @@ export type SelectionGuideGeoJson = {
   type: "FeatureCollection";
   features: Array<{
     type: "Feature";
-    properties: { kind: "guide" | "cell" };
+    properties: { kind: "guide" | "cell" | "patch" };
     geometry:
       | { type: "LineString"; coordinates: LonLatPath }
       | { type: "Polygon"; coordinates: LonLatPath[] };
   }>;
 };
 
+function closedRing(corners: GeoPoint[]): LonLatPath {
+  const ring: LonLatPath = corners.map((point) => [point.lon, point.lat]);
+  ring.push(ring[0]);
+  return ring;
+}
+
 /** GeoJSON for MapLibre selection overlays that drape on the globe surface. */
 export function selectionGuideGeoJson(
   cell: GridCell,
   guidePaths: LonLatPath[],
-  options?: { densifyGuides?: boolean },
+  options?: { densifyGuides?: boolean; patchBounds?: GridCellBounds | null },
 ): SelectionGuideGeoJson {
   const densifyGuides = options?.densifyGuides ?? true;
-  const corners = gridCellToPolygon(cell);
-  const ring: LonLatPath = corners.map((point) => [point.lon, point.lat]);
-  ring.push(ring[0]);
+  const patchBounds = options?.patchBounds ?? null;
 
   return {
     type: "FeatureCollection",
@@ -155,10 +195,22 @@ export function selectionGuideGeoJson(
           coordinates: densifyGuides ? densifyLonLatPath(path) : path,
         },
       })),
+      ...(patchBounds
+        ? [
+            {
+              type: "Feature" as const,
+              properties: { kind: "patch" as const },
+              geometry: {
+                type: "Polygon" as const,
+                coordinates: [closedRing(boundsToPolygon(patchBounds))],
+              },
+            },
+          ]
+        : []),
       {
         type: "Feature",
         properties: { kind: "cell" },
-        geometry: { type: "Polygon", coordinates: [ring] },
+        geometry: { type: "Polygon", coordinates: [closedRing(gridCellToPolygon(cell))] },
       },
     ],
   };
diff --git a/src/lib/map/selectionStyle.ts b/src/lib/map/selectionStyle.ts
index 6753d28..716e1cd 100644
--- a/src/lib/map/selectionStyle.ts
+++ b/src/lib/map/selectionStyle.ts
@@ -16,6 +16,18 @@ export const SELECTION_CELL_COLOR = {
   },
 };
 
+/** The downloaded 40x40 patch: a faint fill with a dashed outline. */
+export const SELECTION_PATCH_COLOR = {
+  light: {
+    fill: [...TEAL_RGB, 14] as const,
+    line: [...TEAL_RGB, 150] as const,
+  },
+  dark: {
+    fill: [...TEAL_ON_DARK_RGB, 20] as const,
+    line: [...TEAL_ON_DARK_RGB, 170] as const,
+  },
+};
+
 export function rgba(
   [r, g, b, a]: readonly [number, number, number, number],
 ): string {

From 63ebc35e9e8b3cc06957159a0a1e163a0f5b1d3e Mon Sep 17 00:00:00 2001
From: Anastasiia Ivanchenko <a.ivanchenko.eu@gmai.com>
Date: Tue, 7 Jul 2026 07:36:43 +0300
Subject: [PATCH 2/2] Explain the downloaded patch in the pixel readout panel

---
 src/components/map/MapReadout.tsx | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/components/map/MapReadout.tsx b/src/components/map/MapReadout.tsx
index 09c218d..9be94ad 100644
--- a/src/components/map/MapReadout.tsx
+++ b/src/components/map/MapReadout.tsx
@@ -34,6 +34,9 @@ export function MapReadout({
   const historyLabel =
     historyYears === 1 ? "Last 1 year" : `Last ${historyYears} years`;
 
+  const patchCells = ZARR_STORE.nativeChunks.lon;
+  const patchDeg = patchCells * ZARR_STORE.spatialResolutionDeg;
+
   return (
     <>
       <section className={PANEL_CLASS}>
@@ -48,6 +51,11 @@ export function MapReadout({
         <p className={HINT_CLASS}>
           Click the map to sample a {ZARR_STORE.spatialResolutionDeg}° cell.
         </p>
+        <p className={HINT_CLASS}>
+          Each click downloads a {patchCells}×{patchCells} patch ({patchDeg}° ×{" "}
+          {patchDeg}°), drawn as the dashed box. Toggle it with the patch button
+          in the top bar.
+        </p>
       </section>
 
       <section className={PANEL_CLASS}>