Download the readout as a PDF report and an XLSX workbook

package.json

@@ -13,12 +13,15 @@
   "dependencies": {
     "@deck.gl/react": "^9.3.3",
     "deck.gl": "^9.3.7",
+    "fflate": "^0.8.3",
+    "jspdf": "^4.2.1",
     "maplibre-gl": "^5.24.0",
     "next": "16.2.12",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "react-map-gl": "^8.1.2",
     "recharts": "^3.10.1",
+    "write-excel-file": "^4.1.1",
     "zarrita": "^0.7.3"
   },
   "devDependencies": {

src/components/map/DownloadButton.tsx

@@ -0,0 +1,133 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { DownloadIcon } from "@/icons/DownloadIcon";
+import { captureMapForExport } from "@/components/map/ExportMapStage";
+import { capturePlotsForExport } from "@/components/map/ExportStage";
+import { buildSeriesCsv } from "@/lib/export/csv";
+import { downloadBlob } from "@/lib/export/download";
+import { buildReportPdf, type ReportAssets } from "@/lib/export/pdf";
+import { buildProvenance, exportFileBaseName } from "@/lib/export/provenance";
+import { buildSeriesRows } from "@/lib/export/rows";
+import { buildSeriesWorkbook } from "@/lib/export/xlsx";
+import { blobToBytes, buildZip, dataUrlToBytes } from "@/lib/export/zip";
+import type { GridSpec, MapSelection } from "@/types/map";
+
+type DownloadButtonProps = {
+  selection: MapSelection;
+  gridSpec: GridSpec;
+  historyYears: number;
+  values: Float32Array | null;
+  units: string | null;
+};
+
+export function DownloadButton({
+  selection,
+  gridSpec,
+  historyYears,
+  values,
+  units,
+}: DownloadButtonProps) {
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const runExport = useCallback(async () => {
+    if (!values) return;
+
+    setError(null);
+    setBusy(true);
+    try {
+      const prov = buildProvenance({
+        selection,
+        historyYears,
+        valueCount: values.length,
+        units,
+      });
+      const base = exportFileBaseName(prov);
+
+      // Both stages mount offscreen and are independent, so the map's tiles
+      // download while the plots lay out.
+      const [mapCapture, plots] = await Promise.all([
+        captureMapForExport({ cell: selection.grid, gridSpec }),
+        capturePlotsForExport({
+          values,
+          units,
+          hoursPerDay: prov.hoursPerDay,
+        }),
+      ]);
+      const assets: ReportAssets = {
+        map: mapCapture.image,
+        timeSeries: plots.timeSeries,
+        fingerprint: plots.fingerprint,
+      };
+
+      const rows = buildSeriesRows(values, prov);
+      const [pdf, workbook] = await Promise.all([
+        buildReportPdf({
+          prov,
+          assets,
+          values,
+          attribution: mapCapture.attribution,
+        }),
+        buildSeriesWorkbook(rows, prov),
+      ]);
+
+      // Everything but the CSV is compressed already, so only it is worth
+      // deflating. Every name carries the full stem: extracted loose among
+      // other downloads they still say which pixel and window they came from.
+      const archive = await buildZip([
+        { name: `${base}.pdf`, data: await blobToBytes(pdf), stored: true },
+        {
+          name: `${base}.xlsx`,
+          data: await blobToBytes(workbook),
+          stored: true,
+        },
+        {
+          name: `${base}.csv`,
+          data: new TextEncoder().encode(buildSeriesCsv(rows, prov)),
+        },
+        {
+          name: `${base}_fingerprint.png`,
+          data: dataUrlToBytes(plots.fingerprintStandalone.dataUrl),
+          stored: true,
+        },
+        {
+          name: `${base}_timeseries.png`,
+          data: dataUrlToBytes(plots.timeSeries.dataUrl),
+          stored: true,
+        },
+      ]);
+
+      downloadBlob(archive, `${base}.zip`);
+    } catch (cause) {
+      console.error("Export failed", cause);
+      setError("Export failed. Try again.");
+    } finally {
+      setBusy(false);
+    }
+  }, [gridSpec, historyYears, selection, units, values]);
+
+  return (
+    <div className="relative">
+      <button
+        type="button"
+        disabled={!values || busy}
+        onClick={() => void runExport()}
+        title="Downloads a zip: PDF report, Excel and CSV tables, and both plots as images"
+        className="inline-flex items-center gap-1.5 rounded-md border border-editor-border px-2 py-1 text-[11.5px] font-semibold text-editor-fg-secondary transition-colors hover:border-editor-border-strong hover:text-editor-fg-primary disabled:cursor-not-allowed disabled:opacity-40"
+      >
+        <DownloadIcon />
+        {busy ? "Preparing…" : "Download"}
+      </button>
+
+      {error ? (
+        <p
+          role="status"
+          className="absolute right-0 top-full mt-1.5 whitespace-nowrap text-[11.5px] text-editor-fg-tertiary"
+        >
+          {error}
+        </p>
+      ) : null}
+    </div>
+  );
+}

src/components/map/ExportMapStage.tsx

@@ -0,0 +1,170 @@
+"use client";
+
+import { createRoot } from "react-dom/client";
+import Map from "react-map-gl/maplibre";
+import type { Map as MapLibreMap, MapLibreEvent } from "maplibre-gl";
+import "maplibre-gl/dist/maplibre-gl.css";
+import { GlobeSelectionOverlay } from "@/components/map/GlobeSelectionOverlay";
+import {
+  MAP_BASE_STYLES,
+  SELECTION_FOCUS_ZOOM,
+} from "@/lib/map/viewState";
+import {
+  canvasToPng,
+  createOffscreenHost,
+  whenVisible,
+  type CapturedImage,
+} from "@/lib/export/capture";
+import { collectAttribution } from "@/lib/export/mapSnapshot";
+import type { GridCell, GridSpec, MapViewState } from "@/types/map";
+
+/**
+ * Stage size in CSS px, at the aspect ratio of the report's map box (88mm x
+ * 47mm). Matching it means the panel prints the whole frame instead of a
+ * centre crop of one shaped like the screen.
+ */
+const EXPORT_MAP_WIDTH = 704;
+const EXPORT_MAP_HEIGHT = 376;
+
+/**
+ * Fixed rather than inherited from the display, so the printed map has the same
+ * ~400dpi on every machine. 2 is where the labels stay crisp in print without
+ * the PNG dominating the file size.
+ */
+const EXPORT_MAP_PIXEL_RATIO = 2;
+
+/** Style, glyphs and the first tiles, over the network. */
+const LOAD_TIMEOUT_MS = 8000;
+
+/** Extra grace for the remaining tiles once the map itself is up. */
+const TILE_TIMEOUT_MS = 6000;
+
+const MAP_CANVAS_ATTRIBUTES = { preserveDrawingBuffer: true } as const;
+
+export type MapCapture = {
+  /** Null when the offscreen map could not be drawn; the report prints a note. */
+  image: CapturedImage | null;
+  /** Basemap credit, which the on-screen map hides but a distributed file must carry. */
+  attribution: string;
+};
+
+type CaptureOptions = {
+  cell: GridCell;
+  gridSpec: GridSpec;
+};
+
+/**
+ * The map as the report wants it, which is not the map on screen: always plan
+ * view, always the light basemap, always framed on the selected cell. The live
+ * map can be a dark globe tilted off its axis, and printing that into a light
+ * A4 report gives a black sphere floating in a white page.
+ */
+function ExportMapStage({
+  cell,
+  gridSpec,
+  onReady,
+}: CaptureOptions & { onReady: (map: MapLibreMap) => void }) {
+  const viewState: MapViewState = {
+    longitude: cell.lon,
+    latitude: cell.lat,
+    zoom: SELECTION_FOCUS_ZOOM,
+    bearing: 0,
+    pitch: 0,
+  };
+
+  return (
+    <Map
+      mapStyle={MAP_BASE_STYLES.light}
+      initialViewState={viewState}
+      interactive={false}
+      attributionControl={false}
+      // Without it the drawing buffer is cleared after each paint, and there is
+      // nothing left to read back.
+      canvasContextAttributes={MAP_CANVAS_ATTRIBUTES}
+      onLoad={(event: MapLibreEvent) => onReady(event.target)}
+      style={{ width: EXPORT_MAP_WIDTH, height: EXPORT_MAP_HEIGHT }}
+    >
+      <GlobeSelectionOverlay
+        cell={cell}
+        gridSpec={gridSpec}
+        viewState={viewState}
+        mapSize={{ width: EXPORT_MAP_WIDTH, height: EXPORT_MAP_HEIGHT }}
+        isLight
+        isSphere={false}
+      />
+    </Map>
+  );
+}
+
+/**
+ * Resolve once the map has nothing left to draw, or once the grace period runs
+ * out. A timeout is not a failure: a map missing its outermost tiles still
+ * prints usefully, so whatever has painted by then is what gets captured.
+ */
+function waitForIdle(map: MapLibreMap, timeoutMs: number): Promise<void> {
+  if (map.areTilesLoaded() && map.isStyleLoaded()) return Promise.resolve();
+
+  return new Promise((resolve) => {
+    const finish = () => {
+      clearTimeout(timer);
+      map.off("idle", finish);
+      resolve();
+    };
+    const timer = setTimeout(finish, timeoutMs);
+    map.on("idle", finish);
+  });
+}
+
+/**
+ * Mount a map offscreen, wait for it to settle, and rasterise it for the
+ * report. The stage is torn down before this resolves.
+ *
+ * Never throws: the report treats a missing map as a layout case, and a failed
+ * basemap is not a reason to lose the data the user asked to download.
+ */
+export async function captureMapForExport({
+  cell,
+  gridSpec,
+}: CaptureOptions): Promise<MapCapture> {
+  // A hidden tab paints nothing and fetches no tiles, so the load and idle
+  // budgets below would run out on a map that never had a chance to draw.
+  await whenVisible();
+
+  const host = createOffscreenHost(EXPORT_MAP_WIDTH, EXPORT_MAP_HEIGHT);
+  const root = createRoot(host);
+
+  try {
+    const map = await new Promise<MapLibreMap | null>((resolve) => {
+      const timer = setTimeout(() => resolve(null), LOAD_TIMEOUT_MS);
+      root.render(
+        <ExportMapStage
+          cell={cell}
+          gridSpec={gridSpec}
+          onReady={(instance) => {
+            clearTimeout(timer);
+            resolve(instance);
+          }}
+        />,
+      );
+    });
+
+    if (!map) return { image: null, attribution: "" };
+
+    map.setPixelRatio(EXPORT_MAP_PIXEL_RATIO);
+    await waitForIdle(map, TILE_TIMEOUT_MS);
+    // The buffer holds the last painted frame, and the pixel-ratio resize may
+    // still be pending, so force one more frame before reading it back.
+    map.redraw();
+
+    return {
+      image: canvasToPng(map.getCanvas()),
+      attribution: collectAttribution(map.getStyle()?.sources),
+    };
+  } catch (cause) {
+    console.error("Map capture failed", cause);
+    return { image: null, attribution: "" };
+  } finally {
+    root.unmount();
+    host.remove();
+  }
+}