Support preloading a previous-month comparison report

Author: BenDutton

CONTRIBUTING.md

@@ -53,6 +53,10 @@ uploaded, replaced, or cleared. If the file is absent the fetch 404s and the app
 falls back to the normal upload flow. This keeps the client-only constraint
 intact: the CSV is served as a static asset and parsed entirely in the browser.
 
+Optionally drop a second CSV at `public/preloaded-report-previous.csv` to also
+preload the previous-month comparison report. It is fetched and locked only when
+the primary preloaded report is present.
+
 ## Development guidelines
 
 - Keep the **client-only data** constraint inviolable.

README.md

@@ -84,6 +84,16 @@ immediately, with uploading/replacing/clearing disabled. Everything still runs
 in the browser - the CSV is served as a static asset and parsed client-side.
 Remove the file for the normal upload experience.
 
+To also preload a previous month for month-over-month comparison, drop a second
+CSV at `public/preloaded-report-previous.csv`. It is loaded (and locked) only
+when the primary preloaded report is present:
+
+```bash
+cp ./this-month.csv public/preloaded-report.csv
+cp ./last-month.csv public/preloaded-report-previous.csv
+npm run build
+```
+
 > Note: a file in `public/` is publicly downloadable, so only preload reports
 > you are comfortable sharing with anyone who can reach the site.
 

docs/tools.md

@@ -30,7 +30,9 @@ decrease in green; plain counts stay neutral. Covered cards include:
 
 Like the main report, the comparison CSV is parsed and held **in memory in your
 browser only**; it is never persisted or sent anywhere. Clearing or replacing the main
-report also clears the comparison.
+report also clears the comparison. A previous-month report can also be preloaded with
+the build (see the README's "Preloading a report" section), in which case it is locked
+alongside the main report.
 
 - [Usage Forecast](#usage-forecast) — _Forecasting_
 - [Team Insights](#team-insights) — _Breakdowns_

src/components/report-provider.tsx

@@ -8,9 +8,15 @@ import { parseUsageCsvText, type ParsedReport } from "@/lib/report";
  * `public/preloaded-report.csv` and it is fetched on load, parsed, and locked
  * so users cannot upload, replace, or clear it. Absent the file, the app
  * behaves normally. The base path keeps the URL correct under GitHub Pages.
+ *
+ * A second optional CSV at `public/preloaded-report-previous.csv` is loaded as
+ * the previous-month comparison report when (and only when) the primary
+ * preloaded report is present; it is locked the same way.
  */
 const PRELOADED_REPORT_FILE = "preloaded-report.csv";
 const PRELOADED_REPORT_URL = `${process.env.NEXT_PUBLIC_BASE_PATH ?? ""}/${PRELOADED_REPORT_FILE}`;
+const PRELOADED_COMPARISON_FILE = "preloaded-report-previous.csv";
+const PRELOADED_COMPARISON_URL = `${process.env.NEXT_PUBLIC_BASE_PATH ?? ""}/${PRELOADED_COMPARISON_FILE}`;
 
 interface ReportContextValue {
   report: ParsedReport | null;
@@ -61,6 +67,19 @@ export function ReportProvider({ children }: { children: React.ReactNode }) {
         const parsed = parseUsageCsvText(text, PRELOADED_REPORT_FILE);
         setReport(parsed);
         setLocked(true);
+
+        // Only probe for the optional previous-month report once the primary
+        // preloaded report is in place; a comparison without a primary report
+        // has nothing to compare against.
+        try {
+          const cmp = await fetch(PRELOADED_COMPARISON_URL, { signal: controller.signal });
+          if (cmp.ok && !(cmp.headers.get("content-type") ?? "").includes("text/html")) {
+            const cmpText = await cmp.text();
+            setComparisonReport(parseUsageCsvText(cmpText, PRELOADED_COMPARISON_FILE));
+          }
+        } catch {
+          // No preloaded comparison, or it could not be parsed: leave it unset.
+        }
       } catch {
         // No preloaded report, or it could not be parsed: normal upload mode.
       } finally {