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();
+ }
+}

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();
+ }
+}

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();
+ }
+}

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();
+ }
+}

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();
+ }
+}

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();
+ }
+}

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();
+ }
+}

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();
+ }
+}