From 3f893674abbca1c1bec17d22eb8986b393f2121f Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:37:31 -0400
Subject: [PATCH 01/41] fix: add inner right-side padding to dropdown chevrons

The native browser chevron in <select> elements was crowding the
option text. Replaced px-2 with pl-2 pr-7 across all filter dropdowns
to give the chevron breathing room.
---
 app/(shell)/ev-charging/page.tsx                     | 10 +++++-----
 app/(shell)/grid-operators/page.tsx                  |  6 +++---
 app/(shell)/power-plants/page.tsx                    |  6 +++---
 app/(shell)/pricing-nodes/page.tsx                   |  6 +++---
 app/(shell)/transmission-lines/page.tsx              |  4 ++--
 components/explorer/panels/GridOperatorListPanel.tsx |  2 +-
 components/explorer/panels/PowerPlantListPanel.tsx   |  2 +-
 components/explorer/panels/ProgramListPanel.tsx      |  2 +-
 components/explorer/panels/TransmissionListPanel.tsx |  2 +-
 9 files changed, 20 insertions(+), 20 deletions(-)

diff --git a/app/(shell)/ev-charging/page.tsx b/app/(shell)/ev-charging/page.tsx
index 66720287..2427174c 100644
--- a/app/(shell)/ev-charging/page.tsx
+++ b/app/(shell)/ev-charging/page.tsx
@@ -292,7 +292,7 @@ export default function EVChargingPage() {
               <select
                 value={networkFilter}
                 onChange={(e) => setNetworkFilter(e.target.value)}
-                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface px-2 text-base sm:text-sm text-text-body"
+                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface pl-2 pr-7 text-base sm:text-sm text-text-body"
               >
                 <option value="all">All Networks</option>
                 {networks.slice(0, 20).map((net) => (
@@ -304,7 +304,7 @@ export default function EVChargingPage() {
               <select
                 value={levelFilter}
                 onChange={(e) => setLevelFilter(e.target.value)}
-                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface px-2 text-base sm:text-sm text-text-body"
+                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface pl-2 pr-7 text-base sm:text-sm text-text-body"
               >
                 <option value="all">All Charging Levels</option>
                 <option value="dcfast">DC Fast Only</option>
@@ -313,7 +313,7 @@ export default function EVChargingPage() {
               <select
                 value={accessFilter}
                 onChange={(e) => setAccessFilter(e.target.value)}
-                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface px-2 text-base sm:text-sm text-text-body"
+                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface pl-2 pr-7 text-base sm:text-sm text-text-body"
               >
                 <option value="all">All Access Types</option>
                 <option value="public">Public</option>
@@ -323,7 +323,7 @@ export default function EVChargingPage() {
               <select
                 value={statusFilter}
                 onChange={(e) => setStatusFilter(e.target.value)}
-                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface px-2 text-base sm:text-sm text-text-body"
+                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface pl-2 pr-7 text-base sm:text-sm text-text-body"
               >
                 <option value="all">All Statuses</option>
                 <option value="E">Open</option>
@@ -333,7 +333,7 @@ export default function EVChargingPage() {
               <select
                 value={stateFilter}
                 onChange={(e) => setStateFilter(e.target.value)}
-                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface px-2 text-base sm:text-sm text-text-body"
+                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface pl-2 pr-7 text-base sm:text-sm text-text-body"
               >
                 <option value="all">All States</option>
                 {states.map((s) => (
diff --git a/app/(shell)/grid-operators/page.tsx b/app/(shell)/grid-operators/page.tsx
index 678d75db..53c3c580 100644
--- a/app/(shell)/grid-operators/page.tsx
+++ b/app/(shell)/grid-operators/page.tsx
@@ -240,7 +240,7 @@ function GridOperatorsPageInner() {
               <select
                 value={segmentFilter}
                 onChange={(e) => setSegmentFilter(e.target.value)}
-                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface px-2 text-base sm:text-sm text-text-body"
+                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface pl-2 pr-7 text-base sm:text-sm text-text-body"
               >
                 {segmentFilterOptions.map((opt) => (
                   <option key={opt.id} value={opt.value}>
@@ -251,7 +251,7 @@ function GridOperatorsPageInner() {
               <select
                 value={statusFilter}
                 onChange={(e) => setStatusFilter(e.target.value)}
-                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface px-2 text-base sm:text-sm text-text-body"
+                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface pl-2 pr-7 text-base sm:text-sm text-text-body"
               >
                 {statusFilterOptions.map((opt) => (
                   <option key={opt.id} value={opt.value}>
@@ -262,7 +262,7 @@ function GridOperatorsPageInner() {
               <select
                 value={jurisdictionFilter}
                 onChange={(e) => setJurisdictionFilter(e.target.value)}
-                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface px-2 text-base sm:text-sm text-text-body"
+                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface pl-2 pr-7 text-base sm:text-sm text-text-body"
               >
                 <option value="all">All Jurisdictions</option>
                 {jurisdictions.map((j) => (
diff --git a/app/(shell)/power-plants/page.tsx b/app/(shell)/power-plants/page.tsx
index 28b44244..4b706f8b 100644
--- a/app/(shell)/power-plants/page.tsx
+++ b/app/(shell)/power-plants/page.tsx
@@ -257,7 +257,7 @@ export default function PowerPlantsPage() {
               <select
                 value={fuelFilter}
                 onChange={(e) => setFuelFilter(e.target.value)}
-                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface px-2 text-base sm:text-sm text-text-body"
+                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface pl-2 pr-7 text-base sm:text-sm text-text-body"
               >
                 {fuelFilterOptions.map((opt) => (
                   <option key={opt.id} value={opt.value}>
@@ -268,7 +268,7 @@ export default function PowerPlantsPage() {
               <select
                 value={statusFilter}
                 onChange={(e) => setStatusFilter(e.target.value)}
-                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface px-2 text-base sm:text-sm text-text-body"
+                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface pl-2 pr-7 text-base sm:text-sm text-text-body"
               >
                 {statusFilterOptions.map((opt) => (
                   <option key={opt.id} value={opt.value}>
@@ -279,7 +279,7 @@ export default function PowerPlantsPage() {
               <select
                 value={stateFilter}
                 onChange={(e) => setStateFilter(e.target.value)}
-                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface px-2 text-base sm:text-sm text-text-body"
+                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface pl-2 pr-7 text-base sm:text-sm text-text-body"
               >
                 <option value="all">All States</option>
                 {states.map((s) => (
diff --git a/app/(shell)/pricing-nodes/page.tsx b/app/(shell)/pricing-nodes/page.tsx
index 9bd6d4b1..63992b47 100644
--- a/app/(shell)/pricing-nodes/page.tsx
+++ b/app/(shell)/pricing-nodes/page.tsx
@@ -241,7 +241,7 @@ export default function PricingNodesPage() {
             <select
               value={isoFilter}
               onChange={(e) => setIsoFilter(e.target.value)}
-              className="h-9 rounded-lg border border-border-default bg-background-surface px-3 text-sm text-text-body"
+              className="h-9 rounded-lg border border-border-default bg-background-surface pl-3 pr-7 text-sm text-text-body"
             >
               <option value="all">All ISOs</option>
               {isos.map((iso) => (
@@ -253,7 +253,7 @@ export default function PricingNodesPage() {
             <select
               value={typeFilter}
               onChange={(e) => setTypeFilter(e.target.value)}
-              className="h-9 rounded-lg border border-border-default bg-background-surface px-3 text-sm text-text-body"
+              className="h-9 rounded-lg border border-border-default bg-background-surface pl-3 pr-7 text-sm text-text-body"
             >
               <option value="all">All Types</option>
               {nodeTypes.map((type) => (
@@ -265,7 +265,7 @@ export default function PricingNodesPage() {
             <select
               value={stateFilter}
               onChange={(e) => setStateFilter(e.target.value)}
-              className="h-9 rounded-lg border border-border-default bg-background-surface px-3 text-sm text-text-body"
+              className="h-9 rounded-lg border border-border-default bg-background-surface pl-3 pr-7 text-sm text-text-body"
             >
               <option value="all">All States</option>
               {states.map((s) => (
diff --git a/app/(shell)/transmission-lines/page.tsx b/app/(shell)/transmission-lines/page.tsx
index 5de4064e..d139fa3e 100644
--- a/app/(shell)/transmission-lines/page.tsx
+++ b/app/(shell)/transmission-lines/page.tsx
@@ -268,7 +268,7 @@ export default function TransmissionLinesPage() {
               <select
                 value={voltageFilter}
                 onChange={(e) => setVoltageFilter(e.target.value)}
-                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface px-2 text-base sm:text-sm text-text-body"
+                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface pl-2 pr-7 text-base sm:text-sm text-text-body"
               >
                 {voltageClassFilterOptions.map((opt) => (
                   <option key={opt.id} value={opt.value}>
@@ -279,7 +279,7 @@ export default function TransmissionLinesPage() {
               <select
                 value={statusFilter}
                 onChange={(e) => setStatusFilter(e.target.value)}
-                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface px-2 text-base sm:text-sm text-text-body"
+                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface pl-2 pr-7 text-base sm:text-sm text-text-body"
               >
                 {statusFilterOptions.map((opt) => (
                   <option key={opt.id} value={opt.value}>
diff --git a/components/explorer/panels/GridOperatorListPanel.tsx b/components/explorer/panels/GridOperatorListPanel.tsx
index 3549536a..041f3727 100644
--- a/components/explorer/panels/GridOperatorListPanel.tsx
+++ b/components/explorer/panels/GridOperatorListPanel.tsx
@@ -167,7 +167,7 @@ export function GridOperatorListPanel() {
             <select
               value={state.type}
               onChange={(e) => setTypeFilter(e.target.value)}
-              className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface px-2 text-base sm:text-sm text-text-body"
+              className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface pl-2 pr-7 text-base sm:text-sm text-text-body"
             >
               {typeFilterOptions.map((opt) => (
                 <option key={opt.id} value={opt.value}>
diff --git a/components/explorer/panels/PowerPlantListPanel.tsx b/components/explorer/panels/PowerPlantListPanel.tsx
index dd703bc5..24d4dc8c 100644
--- a/components/explorer/panels/PowerPlantListPanel.tsx
+++ b/components/explorer/panels/PowerPlantListPanel.tsx
@@ -179,7 +179,7 @@ export function PowerPlantListPanel() {
             <select
               value={state.type}
               onChange={(e) => setTypeFilter(e.target.value)}
-              className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface px-2 text-base sm:text-sm text-text-body"
+              className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface pl-2 pr-7 text-base sm:text-sm text-text-body"
             >
               {fuelFilterOptions.map((opt) => (
                 <option key={opt.id} value={opt.value}>
diff --git a/components/explorer/panels/ProgramListPanel.tsx b/components/explorer/panels/ProgramListPanel.tsx
index c394a54e..e69f4019 100644
--- a/components/explorer/panels/ProgramListPanel.tsx
+++ b/components/explorer/panels/ProgramListPanel.tsx
@@ -166,7 +166,7 @@ export function ProgramListPanel() {
             <select
               value={state.type}
               onChange={(e) => setTypeFilter(e.target.value)}
-              className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface px-2 text-base sm:text-sm text-text-body"
+              className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface pl-2 pr-7 text-base sm:text-sm text-text-body"
             >
               {assetTypeFilterOptions.map((opt) => (
                 <option key={opt.id} value={opt.value}>
diff --git a/components/explorer/panels/TransmissionListPanel.tsx b/components/explorer/panels/TransmissionListPanel.tsx
index 9b969cd8..64e53507 100644
--- a/components/explorer/panels/TransmissionListPanel.tsx
+++ b/components/explorer/panels/TransmissionListPanel.tsx
@@ -207,7 +207,7 @@ export function TransmissionListPanel() {
             <select
               value={state.type}
               onChange={(e) => setTypeFilter(e.target.value)}
-              className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface px-2 text-base sm:text-sm text-text-body"
+              className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface pl-2 pr-7 text-base sm:text-sm text-text-body"
             >
               {voltageClassFilterOptions.map((opt) => (
                 <option key={opt.id} value={opt.value}>

From b7e25b2e446d56f75a65bb0fd13a133fed3d4fdc Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:38:28 -0400
Subject: [PATCH 02/41] fix: add CSS hyphenation breakpoints for long entity
 names

Added hyphens-auto utility class so the browser can hyphenate long
utility/plant names at narrow viewports instead of overflowing or
truncating mid-word.
---
 app/(shell)/ev-charging/page.tsx    | 2 +-
 app/(shell)/grid-operators/page.tsx | 2 +-
 app/(shell)/power-plants/page.tsx   | 2 +-
 app/(shell)/pricing-nodes/page.tsx  | 2 +-
 app/globals.css                     | 8 ++++++++
 5 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/app/(shell)/ev-charging/page.tsx b/app/(shell)/ev-charging/page.tsx
index 2427174c..6e06d34c 100644
--- a/app/(shell)/ev-charging/page.tsx
+++ b/app/(shell)/ev-charging/page.tsx
@@ -183,7 +183,7 @@ export default function EVChargingPage() {
               className="w-2.5 h-2.5 rounded-full flex-shrink-0"
               style={{ backgroundColor: getNetworkColor(row.evNetwork) }}
             />
-            {row.stationName}
+            <span className="hyphens-auto">{row.stationName}</span>
           </Link>
         ),
         mobile: { priority: 1, format: "primary" },
diff --git a/app/(shell)/grid-operators/page.tsx b/app/(shell)/grid-operators/page.tsx
index 53c3c580..bd77984f 100644
--- a/app/(shell)/grid-operators/page.tsx
+++ b/app/(shell)/grid-operators/page.tsx
@@ -164,7 +164,7 @@ function GridOperatorsPageInner() {
               shape="square"
               variant="organization"
             />
-            <span className="truncate">{row.name}</span>
+            <span className="truncate hyphens-auto">{row.name}</span>
           </Link>
         ),
         mobile: { priority: 1, format: "primary" },
diff --git a/app/(shell)/power-plants/page.tsx b/app/(shell)/power-plants/page.tsx
index 4b706f8b..6aae698d 100644
--- a/app/(shell)/power-plants/page.tsx
+++ b/app/(shell)/power-plants/page.tsx
@@ -157,7 +157,7 @@ export default function PowerPlantsPage() {
               className="w-2.5 h-2.5 rounded-full flex-shrink-0"
               style={{ backgroundColor: getFuelCategoryColor(row.fuelCategory) }}
             />
-            {row.name}
+            <span className="hyphens-auto">{row.name}</span>
           </Link>
         ),
         mobile: { priority: 1, format: "primary" },
diff --git a/app/(shell)/pricing-nodes/page.tsx b/app/(shell)/pricing-nodes/page.tsx
index 63992b47..a37f9e85 100644
--- a/app/(shell)/pricing-nodes/page.tsx
+++ b/app/(shell)/pricing-nodes/page.tsx
@@ -158,7 +158,7 @@ export default function PricingNodesPage() {
               className="w-2.5 h-2.5 rounded-full flex-shrink-0"
               style={{ backgroundColor: getIsoColor(row.iso) }}
             />
-            {row.name}
+            <span className="hyphens-auto">{row.name}</span>
           </Link>
         ),
       },
diff --git a/app/globals.css b/app/globals.css
index c963350d..29af0874 100644
--- a/app/globals.css
+++ b/app/globals.css
@@ -22,6 +22,14 @@ html, body {
   /* Dark mode brand handled by BrandProvider darkVariables in Providers.tsx (@texturehq/edges@1.28.2) */
 }
 
+/* Hyphenation support for long entity names at narrow viewports */
+.hyphens-auto {
+  -webkit-hyphens: auto;
+  hyphens: auto;
+  overflow-wrap: break-word;
+  word-break: break-word;
+}
+
 @layer utilities {
   @media (min-width: 768px) {
     .md\:hidden {

From 111ef3fcf0615e54aebb7d363a868de8c210f0cd Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:39:11 -0400
Subject: [PATCH 03/41] fix: complete badge variant mapping for all utility
 segments

Ensured every UtilitySegment enum value has an intentional badge
variant assignment instead of falling through to default. Coops
get success, municipals get warning, CCAs get neutral, etc.
---
 explorer/lib/formatting.ts | 18 +++++++++---------
 lib/formatting.ts          | 18 +++++++++---------
 2 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/explorer/lib/formatting.ts b/explorer/lib/formatting.ts
index 7ec440a8..16a96593 100644
--- a/explorer/lib/formatting.ts
+++ b/explorer/lib/formatting.ts
@@ -23,16 +23,16 @@ export function getSegmentLabel(segment: string): string {
   return UtilitySegmentLabel[segment as UtilitySegment] ?? segment;
 }
 
-export function getSegmentBadgeVariant(segment: string): "info" | "success" | "warning" | "default" {
-  const variants: Record<string, "info" | "success" | "warning" | "default"> = {
+export function getSegmentBadgeVariant(segment: string): "info" | "success" | "warning" | "neutral" | "default" {
+  const variants: Record<string, "info" | "success" | "warning" | "neutral" | "default"> = {
     [UtilitySegment.INVESTOR_OWNED_UTILITY]: "info",
-    [UtilitySegment.DISTRIBUTION_COOPERATIVE]: "warning",
-    [UtilitySegment.GENERATION_AND_TRANSMISSION]: "default",
-    [UtilitySegment.MUNICIPAL_UTILITY]: "success",
-    [UtilitySegment.COMMUNITY_CHOICE_AGGREGATOR]: "success",
-    [UtilitySegment.POLITICAL_SUBDIVISION]: "success",
-    [UtilitySegment.TRANSMISSION_OPERATOR]: "default",
-    [UtilitySegment.JOINT_ACTION_AGENCY]: "default",
+    [UtilitySegment.DISTRIBUTION_COOPERATIVE]: "success",
+    [UtilitySegment.GENERATION_AND_TRANSMISSION]: "success",
+    [UtilitySegment.MUNICIPAL_UTILITY]: "warning",
+    [UtilitySegment.COMMUNITY_CHOICE_AGGREGATOR]: "neutral",
+    [UtilitySegment.POLITICAL_SUBDIVISION]: "warning",
+    [UtilitySegment.TRANSMISSION_OPERATOR]: "info",
+    [UtilitySegment.JOINT_ACTION_AGENCY]: "success",
     [UtilitySegment.FEDERAL]: "info",
   };
   return variants[segment] ?? "default";
diff --git a/lib/formatting.ts b/lib/formatting.ts
index 441a50c4..802f9e6e 100644
--- a/lib/formatting.ts
+++ b/lib/formatting.ts
@@ -31,16 +31,16 @@ export function getSegmentLabel(segment: string): string {
   return UtilitySegmentLabel[segment as UtilitySegment] ?? segment;
 }
 
-export function getSegmentBadgeVariant(segment: string): "info" | "success" | "warning" | "default" {
-  const variants: Record<string, "info" | "success" | "warning" | "default"> = {
+export function getSegmentBadgeVariant(segment: string): "info" | "success" | "warning" | "neutral" | "default" {
+  const variants: Record<string, "info" | "success" | "warning" | "neutral" | "default"> = {
     [UtilitySegment.INVESTOR_OWNED_UTILITY]: "info",
-    [UtilitySegment.DISTRIBUTION_COOPERATIVE]: "warning",
-    [UtilitySegment.GENERATION_AND_TRANSMISSION]: "default",
-    [UtilitySegment.MUNICIPAL_UTILITY]: "success",
-    [UtilitySegment.COMMUNITY_CHOICE_AGGREGATOR]: "success",
-    [UtilitySegment.POLITICAL_SUBDIVISION]: "success",
-    [UtilitySegment.TRANSMISSION_OPERATOR]: "default",
-    [UtilitySegment.JOINT_ACTION_AGENCY]: "default",
+    [UtilitySegment.DISTRIBUTION_COOPERATIVE]: "success",
+    [UtilitySegment.GENERATION_AND_TRANSMISSION]: "success",
+    [UtilitySegment.MUNICIPAL_UTILITY]: "warning",
+    [UtilitySegment.COMMUNITY_CHOICE_AGGREGATOR]: "neutral",
+    [UtilitySegment.POLITICAL_SUBDIVISION]: "warning",
+    [UtilitySegment.TRANSMISSION_OPERATOR]: "info",
+    [UtilitySegment.JOINT_ACTION_AGENCY]: "success",
     [UtilitySegment.FEDERAL]: "info",
   };
   return variants[segment] ?? "default";

From 106f6417cfafa3d388d3b15c881dfc83163b5246 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:40:18 -0400
Subject: [PATCH 04/41] style: overhaul header spacing and nav alignment

Tightened header from h-14 to h-12, adjusted padding rhythm,
increased logo-to-nav gap, and updated content offset to match.
Creates a denser, more intentional header layout.
---
 components/GlobalSearch.tsx      |  2 +-
 components/ShellLayoutClient.tsx |  2 +-
 components/TopBar.tsx            | 14 +++++++-------
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/components/GlobalSearch.tsx b/components/GlobalSearch.tsx
index a79b482e..7f700850 100644
--- a/components/GlobalSearch.tsx
+++ b/components/GlobalSearch.tsx
@@ -589,7 +589,7 @@ export function GlobalSearchModal() {
     <>
       {/* Backdrop — tap outside to close; starts below fixed nav on mobile */}
       <div
-        className="fixed inset-0 top-14 sm:top-0 z-50"
+        className="fixed inset-0 top-12 sm:top-0 z-50"
         style={{ background: "rgba(0,0,0,0.5)", backdropFilter: "blur(6px)", WebkitBackdropFilter: "blur(6px)" }}
         onMouseDown={close}
         onTouchStart={close}
diff --git a/components/ShellLayoutClient.tsx b/components/ShellLayoutClient.tsx
index 409bf164..5d31925f 100644
--- a/components/ShellLayoutClient.tsx
+++ b/components/ShellLayoutClient.tsx
@@ -31,7 +31,7 @@ function ShellInner({ children, navigation }: ShellLayoutClientProps) {
   return (
     <div className="flex flex-col h-dvh">
       <TopBar navigation={navigation} />
-      <main className="flex-1 min-h-0 pt-14">{children}</main>
+      <main className="flex-1 min-h-0 pt-12">{children}</main>
       <GlobalSearchModal />
     </div>
   );
diff --git a/components/TopBar.tsx b/components/TopBar.tsx
index 32d971ae..ed2a6d22 100644
--- a/components/TopBar.tsx
+++ b/components/TopBar.tsx
@@ -46,9 +46,9 @@ export function TopBar({ navigation }: TopBarProps) {
 
   return (
     <header className="fixed top-0 left-0 right-0 z-60 bg-[var(--color-background-subtle)] border-b border-border-default">
-      <div className="flex items-center h-14 px-5">
+      <div className="flex items-center h-12 px-4 lg:px-6">
         {/* Left: logo + nav */}
-        <div className="flex items-center gap-6">
+        <div className="flex items-center gap-8">
           <Link href="/" className="flex items-center gap-2">
             <svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg" className="h-6 w-6 text-text-heading">
               {/* Top row */}
@@ -70,7 +70,7 @@ export function TopBar({ navigation }: TopBarProps) {
               {/* Solid center square */}
               <rect x="11" y="11" width="10" height="10" rx="1.5" fill="currentColor"/>
             </svg>
-            <span className="text-[15px] font-semibold text-text-heading tracking-tight">
+            <span className="text-sm font-semibold text-text-heading tracking-tight">
               CommonGrid
             </span>
           </Link>
@@ -83,7 +83,7 @@ export function TopBar({ navigation }: TopBarProps) {
                   href={item.href}
                   target="_blank"
                   rel="noopener noreferrer"
-                  className="px-3 py-1.5 rounded-md text-sm transition-colors text-text-muted hover:text-text-body"
+                  className="px-2.5 py-1 rounded-md text-sm transition-colors text-text-muted hover:text-text-body"
                 >
                   {item.label}
                 </a>
@@ -91,7 +91,7 @@ export function TopBar({ navigation }: TopBarProps) {
                 <Link
                   key={item.id}
                   href={item.href}
-                  className={`px-3 py-1.5 rounded-md text-sm transition-colors ${
+                  className={`px-2.5 py-1 rounded-md text-sm transition-colors ${
                     isActive(item)
                       ? "text-text-body font-medium"
                       : "text-text-muted hover:text-text-body"
@@ -105,7 +105,7 @@ export function TopBar({ navigation }: TopBarProps) {
         </div>
 
         {/* Right: icons */}
-        <div className="ml-auto hidden sm:flex items-center gap-1">
+        <div className="ml-auto hidden sm:flex items-center gap-1.5">
           <Button
             variant="icon"
             href="https://github.com/TextureHQ/commongrid"
@@ -128,7 +128,7 @@ export function TopBar({ navigation }: TopBarProps) {
         </div>
 
         {/* Mobile: theme toggle + hamburger */}
-        <div className="ml-auto flex items-center gap-1 sm:hidden">
+        <div className="ml-auto flex items-center gap-1.5 sm:hidden">
           {mounted && (
             <Button
               variant="icon"

From 7c9de2f45b284038f7f12a4c1384f9434000638c Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:44:04 -0400
Subject: [PATCH 05/41] style: conditional name clamping in grid-operators
 table

Allow utility names to wrap to 2 lines at narrow viewports instead
of truncating to one line, preserving single-line clamp on desktop.
---
 app/(shell)/grid-operators/page.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/app/(shell)/grid-operators/page.tsx b/app/(shell)/grid-operators/page.tsx
index bd77984f..fc6d5d20 100644
--- a/app/(shell)/grid-operators/page.tsx
+++ b/app/(shell)/grid-operators/page.tsx
@@ -164,7 +164,7 @@ function GridOperatorsPageInner() {
               shape="square"
               variant="organization"
             />
-            <span className="truncate hyphens-auto">{row.name}</span>
+            <span className="line-clamp-2 sm:line-clamp-1 hyphens-auto">{row.name}</span>
           </Link>
         ),
         mobile: { priority: 1, format: "primary" },

From 37b1abc43b574a7250c0d14054220310e7d771e8 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:46:20 -0400
Subject: [PATCH 06/41] feat: add sort-direction chevrons to sort dropdown
 labels
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Sort options now show ▲/▼ arrows indicating direction, making the
current sort order immediately visible across all table pages.
---
 app/(shell)/ev-charging/page.tsx        | 10 +++++-----
 app/(shell)/grid-operators/page.tsx     |  8 ++++----
 app/(shell)/power-plants/page.tsx       |  8 ++++----
 app/(shell)/pricing-nodes/page.tsx      |  8 ++++----
 app/(shell)/transmission-lines/page.tsx | 10 +++++-----
 5 files changed, 22 insertions(+), 22 deletions(-)

diff --git a/app/(shell)/ev-charging/page.tsx b/app/(shell)/ev-charging/page.tsx
index 6e06d34c..76025210 100644
--- a/app/(shell)/ev-charging/page.tsx
+++ b/app/(shell)/ev-charging/page.tsx
@@ -37,11 +37,11 @@ interface EVStationRow extends Record<string, unknown> {
 }
 
 const sortOptions = [
-  { id: "name:asc", label: "Name A-Z", value: "name:asc" },
-  { id: "name:desc", label: "Name Z-A", value: "name:desc" },
-  { id: "connectors:desc", label: "Most Connectors", value: "connectors:desc" },
-  { id: "dcfast:desc", label: "Most DC Fast", value: "dcfast:desc" },
-  { id: "state:asc", label: "State A-Z", value: "state:asc" },
+  { id: "name:asc", label: "Name ▲", value: "name:asc" },
+  { id: "name:desc", label: "Name ▼", value: "name:desc" },
+  { id: "connectors:desc", label: "Connectors ▼", value: "connectors:desc" },
+  { id: "dcfast:desc", label: "DC Fast ▼", value: "dcfast:desc" },
+  { id: "state:asc", label: "State ▲", value: "state:asc" },
 ];
 
 function getStatusBadgeVariant(status: string): "success" | "info" | "warning" | "neutral" {
diff --git a/app/(shell)/grid-operators/page.tsx b/app/(shell)/grid-operators/page.tsx
index fc6d5d20..5673c106 100644
--- a/app/(shell)/grid-operators/page.tsx
+++ b/app/(shell)/grid-operators/page.tsx
@@ -41,10 +41,10 @@ interface UtilityRow extends Record<string, unknown> {
 }
 
 const sortOptions = [
-  { id: "name:asc", label: "Name A-Z", value: "name:asc" },
-  { id: "name:desc", label: "Name Z-A", value: "name:desc" },
-  { id: "customers:desc", label: "Customers (High to Low)", value: "customers:desc" },
-  { id: "customers:asc", label: "Customers (Low to High)", value: "customers:asc" },
+  { id: "name:asc", label: "Name ▲", value: "name:asc" },
+  { id: "name:desc", label: "Name ▼", value: "name:desc" },
+  { id: "customers:desc", label: "Customers ▼", value: "customers:desc" },
+  { id: "customers:asc", label: "Customers ▲", value: "customers:asc" },
 ];
 
 const segmentFilterOptions = [
diff --git a/app/(shell)/power-plants/page.tsx b/app/(shell)/power-plants/page.tsx
index 6aae698d..42b8eab0 100644
--- a/app/(shell)/power-plants/page.tsx
+++ b/app/(shell)/power-plants/page.tsx
@@ -39,10 +39,10 @@ interface PowerPlantRow extends Record<string, unknown> {
 }
 
 const sortOptions = [
-  { id: "name:asc", label: "Name A-Z", value: "name:asc" },
-  { id: "name:desc", label: "Name Z-A", value: "name:desc" },
-  { id: "capacity:desc", label: "Capacity (High to Low)", value: "capacity:desc" },
-  { id: "capacity:asc", label: "Capacity (Low to High)", value: "capacity:asc" },
+  { id: "name:asc", label: "Name ▲", value: "name:asc" },
+  { id: "name:desc", label: "Name ▼", value: "name:desc" },
+  { id: "capacity:desc", label: "Capacity ▼", value: "capacity:desc" },
+  { id: "capacity:asc", label: "Capacity ▲", value: "capacity:asc" },
 ];
 
 const fuelFilterOptions = [
diff --git a/app/(shell)/pricing-nodes/page.tsx b/app/(shell)/pricing-nodes/page.tsx
index a37f9e85..a43a1f12 100644
--- a/app/(shell)/pricing-nodes/page.tsx
+++ b/app/(shell)/pricing-nodes/page.tsx
@@ -38,10 +38,10 @@ interface PricingNodeRow extends Record<string, unknown> {
 }
 
 const sortOptions = [
-  { id: "name:asc", label: "Name A-Z", value: "name:asc" },
-  { id: "name:desc", label: "Name Z-A", value: "name:desc" },
-  { id: "iso:asc", label: "ISO A-Z", value: "iso:asc" },
-  { id: "state:asc", label: "State A-Z", value: "state:asc" },
+  { id: "name:asc", label: "Name ▲", value: "name:asc" },
+  { id: "name:desc", label: "Name ▼", value: "name:desc" },
+  { id: "iso:asc", label: "ISO ▲", value: "iso:asc" },
+  { id: "state:asc", label: "State ▲", value: "state:asc" },
 ];
 
 function getNodeTypeBadgeVariant(type: PricingNodeType): "success" | "info" | "warning" | "neutral" {
diff --git a/app/(shell)/transmission-lines/page.tsx b/app/(shell)/transmission-lines/page.tsx
index d139fa3e..abdd1845 100644
--- a/app/(shell)/transmission-lines/page.tsx
+++ b/app/(shell)/transmission-lines/page.tsx
@@ -31,11 +31,11 @@ interface TransmissionLineRow extends Record<string, unknown> {
 }
 
 const sortOptions = [
-  { id: "voltage:desc", label: "Voltage (High to Low)", value: "voltage:desc" },
-  { id: "voltage:asc", label: "Voltage (Low to High)", value: "voltage:asc" },
-  { id: "length:desc", label: "Length (Longest First)", value: "length:desc" },
-  { id: "length:asc", label: "Length (Shortest First)", value: "length:asc" },
-  { id: "owner:asc", label: "Owner A-Z", value: "owner:asc" },
+  { id: "voltage:desc", label: "Voltage ▼", value: "voltage:desc" },
+  { id: "voltage:asc", label: "Voltage ▲", value: "voltage:asc" },
+  { id: "length:desc", label: "Length ▼", value: "length:desc" },
+  { id: "length:asc", label: "Length ▲", value: "length:asc" },
+  { id: "owner:asc", label: "Owner ▲", value: "owner:asc" },
 ];
 
 const voltageClassFilterOptions = [

From 791740db1663e2a05f2ba50ebc153a47aa8ac766 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:47:33 -0400
Subject: [PATCH 07/41] feat: add more fields to power-plants and
 transmission-lines tables

Power plants now show County, Operating Year, and Generator Count
columns. Transmission lines substation labels clarified to From/To.
All new columns hidden on mobile.
---
 app/(shell)/power-plants/page.tsx       | 33 +++++++++++++++++++++++++
 app/(shell)/transmission-lines/page.tsx |  4 +--
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/app/(shell)/power-plants/page.tsx b/app/(shell)/power-plants/page.tsx
index 42b8eab0..75c8d542 100644
--- a/app/(shell)/power-plants/page.tsx
+++ b/app/(shell)/power-plants/page.tsx
@@ -33,9 +33,12 @@ interface PowerPlantRow extends Record<string, unknown> {
   fuelCategory: string;
   totalCapacityMw: number;
   state: string;
+  county: string | null;
   utilityName: string;
   status: string;
   proposedCapacityMw: number | null;
+  operatingYear: number | null;
+  generatorCount: number;
 }
 
 const sortOptions = [
@@ -128,9 +131,12 @@ export default function PowerPlantsPage() {
         fuelCategory: p.fuelCategory,
         totalCapacityMw: p.totalCapacityMw,
         state: p.state,
+        county: p.county,
         utilityName: p.utilityName,
         status: p.status,
         proposedCapacityMw: p.proposedCapacityMw,
+        operatingYear: p.operatingYear,
+        generatorCount: p.generatorCount,
       })),
     [filtered]
   );
@@ -211,6 +217,33 @@ export default function PowerPlantsPage() {
         ),
         mobile: false,
       },
+      {
+        id: "county",
+        label: "County",
+        accessor: "county",
+        render: (_value: unknown, row: PowerPlantRow) => (
+          <span className="text-text-body">{row.county ?? "—"}</span>
+        ),
+        mobile: false,
+      },
+      {
+        id: "operatingYear",
+        label: "Year",
+        accessor: "operatingYear",
+        render: (_value: unknown, row: PowerPlantRow) => (
+          <span className="text-text-body tabular-nums">{row.operatingYear ?? "—"}</span>
+        ),
+        mobile: false,
+      },
+      {
+        id: "generatorCount",
+        label: "Generators",
+        accessor: "generatorCount",
+        render: (_value: unknown, row: PowerPlantRow) => (
+          <span className="text-text-body tabular-nums">{row.generatorCount}</span>
+        ),
+        mobile: false,
+      },
     ],
     []
   );
diff --git a/app/(shell)/transmission-lines/page.tsx b/app/(shell)/transmission-lines/page.tsx
index abdd1845..c8658c26 100644
--- a/app/(shell)/transmission-lines/page.tsx
+++ b/app/(shell)/transmission-lines/page.tsx
@@ -199,14 +199,14 @@ export default function TransmissionLinesPage() {
       },
       {
         id: "sub1",
-        label: "Substation 1",
+        label: "From",
         accessor: "sub1",
         cell: TextCell,
         mobile: false,
       },
       {
         id: "sub2",
-        label: "Substation 2",
+        label: "To",
         accessor: "sub2",
         cell: TextCell,
         mobile: false,

From ece78d0910c475ad3733cefa3f4ece27f166ad12 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:48:08 -0400
Subject: [PATCH 08/41] feat: jurisdiction state-based highlighting in
 grid-operators table

When a jurisdiction filter is active, matching jurisdiction cells are
highlighted with brand color and bold text for visual distinction.
---
 app/(shell)/grid-operators/page.tsx | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/app/(shell)/grid-operators/page.tsx b/app/(shell)/grid-operators/page.tsx
index 5673c106..47212209 100644
--- a/app/(shell)/grid-operators/page.tsx
+++ b/app/(shell)/grid-operators/page.tsx
@@ -193,7 +193,17 @@ function GridOperatorsPageInner() {
         id: "jurisdiction",
         label: "Jurisdiction",
         accessor: "jurisdiction",
-        cell: TextCell,
+        render: (_value: unknown, row: UtilityRow) => (
+          <span
+            className={`text-text-body ${
+              jurisdictionFilter !== "all" && row.jurisdiction === jurisdictionFilter
+                ? "font-semibold text-brand-primary"
+                : ""
+            }`}
+          >
+            {row.jurisdiction ?? "—"}
+          </span>
+        ),
         mobile: false,
       },
       {
@@ -208,7 +218,7 @@ function GridOperatorsPageInner() {
         mobile: false,
       },
     ],
-    []
+    [jurisdictionFilter]
   );
 
   return (

From ea227b52307b7a20c99151bea2a75bef07932627 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:50:18 -0400
Subject: [PATCH 09/41] feat: distinguish site changelog from industry data
 changelog
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Added tab UI separating "Data Changes" (live industry updates) from
"Site Updates" (product changes). Added entity-type filter chips
and pulse animation on sync indicator. Emphasized that the data
changelog is the core product — streaming changes from the industry.
---
 app/(shell)/changelog/page.tsx | 100 +++++++++++++++++++++++++++++++--
 1 file changed, 94 insertions(+), 6 deletions(-)

diff --git a/app/(shell)/changelog/page.tsx b/app/(shell)/changelog/page.tsx
index 77cb8a20..1492281e 100644
--- a/app/(shell)/changelog/page.tsx
+++ b/app/(shell)/changelog/page.tsx
@@ -1,6 +1,7 @@
 "use client";
 
 import { Badge, Card, Icon, PageLayout, Section } from "@texturehq/edges";
+import { useMemo, useState } from "react";
 import { getChangelog } from "@/lib/data";
 import type { ChangelogEntry } from "@/types/changelog";
 
@@ -120,13 +121,31 @@ function DateGroup({ date, entries }: { date: string; entries: ChangelogEntry[]
 
 export default function ChangelogPage() {
   const changelog = getChangelog();
+  const [tab, setTab] = useState<"data" | "site">("data");
+  const [entityTypeFilter, setEntityTypeFilter] = useState<string>("all");
 
   // Merge and sort all entries newest-first
-  const allEntries = [...changelog.recentlyUpdated, ...changelog.newlyAdded].sort(
-    (a, b) => new Date(b.isoTimestamp).getTime() - new Date(a.isoTimestamp).getTime(),
+  const allEntries = useMemo(
+    () =>
+      [...changelog.recentlyUpdated, ...changelog.newlyAdded].sort(
+        (a, b) => new Date(b.isoTimestamp).getTime() - new Date(a.isoTimestamp).getTime(),
+      ),
+    [changelog],
   );
 
-  const groups = groupByDate(allEntries);
+  // Unique entity types for filter chips
+  const uniqueEntityTypes = useMemo(() => {
+    const types = new Set(allEntries.map((e) => e.entityType));
+    return Array.from(types).sort();
+  }, [allEntries]);
+
+  // Filtered entries
+  const filteredEntries = useMemo(() => {
+    if (entityTypeFilter === "all") return allEntries;
+    return allEntries.filter((e) => e.entityType === entityTypeFilter);
+  }, [allEntries, entityTypeFilter]);
+
+  const groups = groupByDate(filteredEntries);
 
   const lastUpdated = changelog.updatedAt
     ? new Date(changelog.updatedAt).toLocaleDateString("en-US", {
@@ -140,14 +159,62 @@ export default function ChangelogPage() {
     <PageLayout maxWidth={900}>
       <PageLayout.Header
         title="Changelog"
-        description="Every update to the CommonGrid dataset — new entities added and existing records updated from authoritative sources."
+        description="Live changes streaming from the energy industry — new entities added and existing records updated from authoritative sources."
       />
       <PageLayout.Content>
+        {/* Tab bar */}
+        <div className="flex gap-1 border-b border-border-default mb-6">
+          <button
+            type="button"
+            onClick={() => setTab("data")}
+            className={`px-4 py-2.5 text-sm font-medium border-b-2 transition-colors ${
+              tab === "data"
+                ? "border-brand-primary text-brand-primary"
+                : "border-transparent text-text-muted hover:text-text-body"
+            }`}
+          >
+            Data Changes
+          </button>
+          <button
+            type="button"
+            onClick={() => setTab("site")}
+            className={`px-4 py-2.5 text-sm font-medium border-b-2 transition-colors ${
+              tab === "site"
+                ? "border-brand-primary text-brand-primary"
+                : "border-transparent text-text-muted hover:text-text-body"
+            }`}
+          >
+            Site Updates
+          </button>
+        </div>
+
+        {tab === "site" && (
+          <Card variant="outlined">
+            <Card.Content className="py-12 text-center">
+              <Icon name="Code" size={32} className="text-text-muted mx-auto mb-3" />
+              <p className="text-sm font-medium text-text-heading mb-1">Product Updates</p>
+              <p className="text-sm text-text-muted max-w-md mx-auto">
+                Changes to the CommonGrid website and tools. Visit our{" "}
+                <a
+                  href="https://github.com/TextureHQ/commongrid/releases"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="text-brand-primary hover:underline"
+                >
+                  GitHub releases
+                </a>{" "}
+                for the full history of site updates.
+              </p>
+            </Card.Content>
+          </Card>
+        )}
+
+        {tab === "data" && (
         <Section id="feed" navLabel="Changes" withDivider={false}>
           {/* Meta bar */}
           <div className="flex items-center justify-between mb-6">
             <div className="flex items-center gap-2">
-              <span className="inline-block w-2 h-2 rounded-full bg-green-500" />
+              <span className="inline-block w-2 h-2 rounded-full bg-green-500 animate-pulse" />
               <span className="text-sm text-text-muted">
                 Synced from authoritative sources daily
               </span>
@@ -198,8 +265,28 @@ export default function ChangelogPage() {
             ))}
           </div>
 
+          {/* Entity type filters */}
+          {uniqueEntityTypes.length > 1 && (
+            <div className="flex flex-wrap gap-2 mb-6">
+              {["all", ...uniqueEntityTypes].map((type) => (
+                <button
+                  key={type}
+                  type="button"
+                  onClick={() => setEntityTypeFilter(type)}
+                  className={`px-3 py-1 rounded-full text-xs font-medium transition-colors ${
+                    entityTypeFilter === type
+                      ? "bg-brand-primary text-white"
+                      : "bg-background-subtle text-text-muted hover:text-text-body"
+                  }`}
+                >
+                  {type === "all" ? "All" : type.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase())}
+                </button>
+              ))}
+            </div>
+          )}
+
           {/* Feed */}
-          {allEntries.length === 0 ? (
+          {filteredEntries.length === 0 ? (
             <Card variant="outlined">
               <Card.Content className="py-12 text-center">
                 <Icon name="Clock" size={32} className="text-text-muted mx-auto mb-3" />
@@ -218,6 +305,7 @@ export default function ChangelogPage() {
             ))
           )}
         </Section>
+        )}
       </PageLayout.Content>
     </PageLayout>
   );

From c9e343a9eeb702146d0142bcfee69387dc2e85d5 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:51:24 -0400
Subject: [PATCH 10/41] fix: stabilize Mapbox component mount/unmount lifecycle

Replaced fragile 100ms setTimeout resize with ResizeObserver for
reliable map sizing on layout changes. Added containerRef for
observing resize events via requestAnimationFrame.
---
 components/explorer/ExplorerMap.tsx | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/components/explorer/ExplorerMap.tsx b/components/explorer/ExplorerMap.tsx
index 86d9784a..5f62c49f 100644
--- a/components/explorer/ExplorerMap.tsx
+++ b/components/explorer/ExplorerMap.tsx
@@ -9,9 +9,9 @@ import { getAllIsos, getAllBalancingAuthorities, getAllUtilities, searchEntities
 import { getSegmentLabel } from "@/lib/formatting";
 import { computeViewStateFromGeoJSON } from "@/lib/geo";
 
-function getTileUrl() {
+function getTileUrl(layerType = "territories") {
   const origin = typeof window !== "undefined" ? window.location.origin : "";
-  return `${origin}/api/tiles/territories/{z}/{x}/{y}`;
+  return `${origin}/api/tiles/${layerType}/{z}/{x}/{y}`;
 }
 
 const segmentColorMapping = {
@@ -233,14 +233,19 @@ export function ExplorerMap({ mapboxAccessToken }: ExplorerMapProps = {}) {
 
   const hasHighlight = !!state.highlightGeoJSON;
 
-  // Trigger map resize after mount (fixes blank map on client-side navigation)
+  // Trigger map resize on container size changes (fixes blank map on layout transitions)
+  const containerRef = useRef<HTMLDivElement | null>(null);
   useEffect(() => {
-    const timer = setTimeout(() => {
-      const map = mapRef.current?.getMap?.();
-      if (!map) return;
-      map.resize();
-    }, 100);
-    return () => clearTimeout(timer);
+    const container = containerRef.current;
+    if (!container) return;
+    const observer = new ResizeObserver(() => {
+      requestAnimationFrame(() => {
+        const map = mapRef.current?.getMap?.();
+        if (map) map.resize();
+      });
+    });
+    observer.observe(container);
+    return () => observer.disconnect();
   }, []);
 
   // Build Mapbox filter expression for utility territory tiles
@@ -684,7 +689,7 @@ export function ExplorerMap({ mapboxAccessToken }: ExplorerMapProps = {}) {
   }
 
   return (
-    <div className="h-full w-full relative">
+    <div ref={containerRef} className="h-full w-full relative">
       <InteractiveMap
         ref={mapRef as React.Ref<any>}
         mapboxAccessToken={effectiveToken!}

From ecdc89b6874c645df16fc176ffb46a9de4a61f6c Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:53:14 -0400
Subject: [PATCH 11/41] =?UTF-8?q?feat:=20redesign=20CommonGrid=20logo=20?=
 =?UTF-8?q?=E2=80=94=20G-in-C=20with=20dendritic=20graph?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New mark shows G inscribed in C with tree-graph network connections
radiating from center to the arc boundary. Evokes grid topology
meets letterform. Ships as inline SVG + standalone public/logo.svg.
---
 components/TopBar.tsx | 38 ++++++++++++++++++++------------------
 public/logo.svg       | 38 ++++++++++++++++++++------------------
 2 files changed, 40 insertions(+), 36 deletions(-)

diff --git a/components/TopBar.tsx b/components/TopBar.tsx
index ed2a6d22..768a6c47 100644
--- a/components/TopBar.tsx
+++ b/components/TopBar.tsx
@@ -51,24 +51,26 @@ export function TopBar({ navigation }: TopBarProps) {
         <div className="flex items-center gap-8">
           <Link href="/" className="flex items-center gap-2">
             <svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg" className="h-6 w-6 text-text-heading">
-              {/* Top row */}
-              <circle cx="4" cy="4" r="1.8" fill="currentColor"/>
-              <circle cx="12" cy="4" r="1.8" fill="currentColor"/>
-              <circle cx="20" cy="4" r="1.8" fill="currentColor"/>
-              <circle cx="28" cy="4" r="1.8" fill="currentColor"/>
-              {/* Left col */}
-              <circle cx="4" cy="12" r="1.8" fill="currentColor"/>
-              <circle cx="4" cy="20" r="1.8" fill="currentColor"/>
-              {/* Right col */}
-              <circle cx="28" cy="12" r="1.8" fill="currentColor"/>
-              <circle cx="28" cy="20" r="1.8" fill="currentColor"/>
-              {/* Bottom row */}
-              <circle cx="4" cy="28" r="1.8" fill="currentColor"/>
-              <circle cx="12" cy="28" r="1.8" fill="currentColor"/>
-              <circle cx="20" cy="28" r="1.8" fill="currentColor"/>
-              <circle cx="28" cy="28" r="1.8" fill="currentColor"/>
-              {/* Solid center square */}
-              <rect x="11" y="11" width="10" height="10" rx="1.5" fill="currentColor"/>
+              {/* C arc — open on the right */}
+              <path d="M22 10 A10 10 0 1 0 22 22" stroke="currentColor" strokeWidth="2" strokeLinecap="round" fill="none" />
+              {/* G crossbar */}
+              <line x1="22" y1="16" x2="16" y2="16" stroke="currentColor" strokeWidth="2" strokeLinecap="round" />
+              {/* Dendritic edges — tree-graph connections */}
+              <line x1="16" y1="16" x2="10" y2="8" stroke="currentColor" strokeWidth="0.8" opacity="0.5" />
+              <line x1="16" y1="16" x2="7" y2="14" stroke="currentColor" strokeWidth="0.8" opacity="0.5" />
+              <line x1="16" y1="16" x2="7" y2="20" stroke="currentColor" strokeWidth="0.8" opacity="0.5" />
+              <line x1="16" y1="16" x2="10" y2="25" stroke="currentColor" strokeWidth="0.8" opacity="0.5" />
+              <line x1="10" y1="8" x2="14" y2="6" stroke="currentColor" strokeWidth="0.8" opacity="0.5" />
+              <line x1="10" y1="25" x2="14" y2="27" stroke="currentColor" strokeWidth="0.8" opacity="0.5" />
+              {/* Network nodes */}
+              <circle cx="16" cy="16" r="1.8" fill="currentColor" />
+              <circle cx="10" cy="8" r="1.3" fill="currentColor" />
+              <circle cx="7" cy="14" r="1.3" fill="currentColor" />
+              <circle cx="7" cy="20" r="1.3" fill="currentColor" />
+              <circle cx="10" cy="25" r="1.3" fill="currentColor" />
+              <circle cx="14" cy="6" r="1.0" fill="currentColor" />
+              <circle cx="14" cy="27" r="1.0" fill="currentColor" />
+              <circle cx="22" cy="16" r="1.3" fill="currentColor" />
             </svg>
             <span className="text-sm font-semibold text-text-heading tracking-tight">
               CommonGrid
diff --git a/public/logo.svg b/public/logo.svg
index 7a829826..270a049f 100644
--- a/public/logo.svg
+++ b/public/logo.svg
@@ -1,20 +1,22 @@
 <svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
-  <!-- Top row -->
-  <circle cx="4" cy="4" r="1.8" fill="#111111"/>
-  <circle cx="12" cy="4" r="1.8" fill="#111111"/>
-  <circle cx="20" cy="4" r="1.8" fill="#111111"/>
-  <circle cx="28" cy="4" r="1.8" fill="#111111"/>
-  <!-- Left col -->
-  <circle cx="4" cy="12" r="1.8" fill="#111111"/>
-  <circle cx="4" cy="20" r="1.8" fill="#111111"/>
-  <!-- Right col -->
-  <circle cx="28" cy="12" r="1.8" fill="#111111"/>
-  <circle cx="28" cy="20" r="1.8" fill="#111111"/>
-  <!-- Bottom row -->
-  <circle cx="4" cy="28" r="1.8" fill="#111111"/>
-  <circle cx="12" cy="28" r="1.8" fill="#111111"/>
-  <circle cx="20" cy="28" r="1.8" fill="#111111"/>
-  <circle cx="28" cy="28" r="1.8" fill="#111111"/>
-  <!-- Solid center square -->
-  <rect x="11" y="11" width="10" height="10" rx="1.5" fill="#111111"/>
+  <!-- C arc — open on the right -->
+  <path d="M22 10 A10 10 0 1 0 22 22" stroke="#111111" stroke-width="2" stroke-linecap="round" fill="none" />
+  <!-- G crossbar -->
+  <line x1="22" y1="16" x2="16" y2="16" stroke="#111111" stroke-width="2" stroke-linecap="round" />
+  <!-- Dendritic edges — tree-graph connections -->
+  <line x1="16" y1="16" x2="10" y2="8" stroke="#111111" stroke-width="0.8" opacity="0.5" />
+  <line x1="16" y1="16" x2="7" y2="14" stroke="#111111" stroke-width="0.8" opacity="0.5" />
+  <line x1="16" y1="16" x2="7" y2="20" stroke="#111111" stroke-width="0.8" opacity="0.5" />
+  <line x1="16" y1="16" x2="10" y2="25" stroke="#111111" stroke-width="0.8" opacity="0.5" />
+  <line x1="10" y1="8" x2="14" y2="6" stroke="#111111" stroke-width="0.8" opacity="0.5" />
+  <line x1="10" y1="25" x2="14" y2="27" stroke="#111111" stroke-width="0.8" opacity="0.5" />
+  <!-- Network nodes -->
+  <circle cx="16" cy="16" r="1.8" fill="#111111" />
+  <circle cx="10" cy="8" r="1.3" fill="#111111" />
+  <circle cx="7" cy="14" r="1.3" fill="#111111" />
+  <circle cx="7" cy="20" r="1.3" fill="#111111" />
+  <circle cx="10" cy="25" r="1.3" fill="#111111" />
+  <circle cx="14" cy="6" r="1.0" fill="#111111" />
+  <circle cx="14" cy="27" r="1.0" fill="#111111" />
+  <circle cx="22" cy="16" r="1.3" fill="#111111" />
 </svg>

From 049d059d1cc993f74645285664c126babff63563 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:54:00 -0400
Subject: [PATCH 12/41] style: stack filter dropdowns vertically at narrow
 breakpoints

Filter controls now flex-col below sm breakpoint across all table
pages, preventing horizontal overflow on phone-width viewports.
---
 app/(shell)/ev-charging/page.tsx        | 2 +-
 app/(shell)/grid-operators/page.tsx     | 2 +-
 app/(shell)/power-plants/page.tsx       | 2 +-
 app/(shell)/pricing-nodes/page.tsx      | 2 +-
 app/(shell)/transmission-lines/page.tsx | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/app/(shell)/ev-charging/page.tsx b/app/(shell)/ev-charging/page.tsx
index 76025210..3ccd2fa7 100644
--- a/app/(shell)/ev-charging/page.tsx
+++ b/app/(shell)/ev-charging/page.tsx
@@ -288,7 +288,7 @@ export default function EVChargingPage() {
             onChange: setSortValue,
           }}
           customControls={
-            <div className="flex flex-wrap gap-2">
+            <div className="flex flex-col sm:flex-row flex-wrap gap-2">
               <select
                 value={networkFilter}
                 onChange={(e) => setNetworkFilter(e.target.value)}
diff --git a/app/(shell)/grid-operators/page.tsx b/app/(shell)/grid-operators/page.tsx
index 47212209..b478ddc0 100644
--- a/app/(shell)/grid-operators/page.tsx
+++ b/app/(shell)/grid-operators/page.tsx
@@ -246,7 +246,7 @@ function GridOperatorsPageInner() {
             onChange: setSortValue,
           }}
           customControls={
-            <div className="flex flex-wrap gap-2">
+            <div className="flex flex-col sm:flex-row flex-wrap gap-2">
               <select
                 value={segmentFilter}
                 onChange={(e) => setSegmentFilter(e.target.value)}
diff --git a/app/(shell)/power-plants/page.tsx b/app/(shell)/power-plants/page.tsx
index 75c8d542..70d42310 100644
--- a/app/(shell)/power-plants/page.tsx
+++ b/app/(shell)/power-plants/page.tsx
@@ -286,7 +286,7 @@ export default function PowerPlantsPage() {
             onChange: setSortValue,
           }}
           customControls={
-            <div className="flex flex-wrap gap-2">
+            <div className="flex flex-col sm:flex-row flex-wrap gap-2">
               <select
                 value={fuelFilter}
                 onChange={(e) => setFuelFilter(e.target.value)}
diff --git a/app/(shell)/pricing-nodes/page.tsx b/app/(shell)/pricing-nodes/page.tsx
index a43a1f12..6e38251d 100644
--- a/app/(shell)/pricing-nodes/page.tsx
+++ b/app/(shell)/pricing-nodes/page.tsx
@@ -229,7 +229,7 @@ export default function PricingNodesPage() {
       <PageLayout.Content>
         <div className="px-4 sm:px-6 py-4 flex flex-col gap-4">
           {/* Filters */}
-          <div className="flex flex-wrap items-center gap-3">
+          <div className="flex flex-col sm:flex-row flex-wrap items-stretch sm:items-center gap-3">
             <SearchInput
               value={searchQuery}
               onChange={setSearchQuery}
diff --git a/app/(shell)/transmission-lines/page.tsx b/app/(shell)/transmission-lines/page.tsx
index c8658c26..d681ba20 100644
--- a/app/(shell)/transmission-lines/page.tsx
+++ b/app/(shell)/transmission-lines/page.tsx
@@ -264,7 +264,7 @@ export default function TransmissionLinesPage() {
             onChange: setSortValue,
           }}
           customControls={
-            <div className="flex flex-wrap gap-2">
+            <div className="flex flex-col sm:flex-row flex-wrap gap-2">
               <select
                 value={voltageFilter}
                 onChange={(e) => setVoltageFilter(e.target.value)}

From ba4b06dd0c60ec0e0b99754348c615108796f87b Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:54:57 -0400
Subject: [PATCH 13/41] feat: add EIA ID, BA Code, NERC, and website fields to
 grid-operators table

Grid operators table now surfaces EIA ID, Balancing Authority code,
NERC region, and external website link columns. All hidden on mobile.
---
 app/(shell)/grid-operators/page.tsx | 57 +++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/app/(shell)/grid-operators/page.tsx b/app/(shell)/grid-operators/page.tsx
index b478ddc0..c3daad56 100644
--- a/app/(shell)/grid-operators/page.tsx
+++ b/app/(shell)/grid-operators/page.tsx
@@ -38,6 +38,9 @@ interface UtilityRow extends Record<string, unknown> {
   jurisdiction: string | null;
   website: string | null;
   logo: string | null;
+  eiaId: string | null;
+  baCode: string | null;
+  nercRegion: string | null;
 }
 
 const sortOptions = [
@@ -135,6 +138,9 @@ function GridOperatorsPageInner() {
         jurisdiction: u.jurisdiction,
         website: u.website,
         logo: u.logo,
+        eiaId: u.eiaId,
+        baCode: u.baCode,
+        nercRegion: u.nercRegion,
       })),
     [filtered]
   );
@@ -217,6 +223,57 @@ function GridOperatorsPageInner() {
         ),
         mobile: false,
       },
+      {
+        id: "eiaId",
+        label: "EIA ID",
+        accessor: "eiaId",
+        render: (_value: unknown, row: UtilityRow) => (
+          <span className="text-text-muted tabular-nums text-xs">{row.eiaId ?? "—"}</span>
+        ),
+        mobile: false,
+      },
+      {
+        id: "baCode",
+        label: "BA Code",
+        accessor: "baCode",
+        render: (_value: unknown, row: UtilityRow) => (
+          <span className="text-text-muted text-xs">{row.baCode ?? "—"}</span>
+        ),
+        mobile: false,
+      },
+      {
+        id: "nercRegion",
+        label: "NERC",
+        accessor: "nercRegion",
+        render: (_value: unknown, row: UtilityRow) => (
+          <span className="text-text-muted text-xs">{row.nercRegion ?? "—"}</span>
+        ),
+        mobile: false,
+      },
+      {
+        id: "website",
+        label: "Web",
+        accessor: "website",
+        render: (_value: unknown, row: UtilityRow) =>
+          row.website ? (
+            <a
+              href={row.website}
+              target="_blank"
+              rel="noopener noreferrer"
+              onClick={(e) => e.stopPropagation()}
+              className="text-text-muted hover:text-brand-primary transition-colors"
+              title={row.website}
+            >
+              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor" className="w-3.5 h-3.5">
+                <path d="M6.22 8.72a.75.75 0 0 0 1.06 1.06l5.22-5.22v1.69a.75.75 0 0 0 1.5 0v-3.5a.75.75 0 0 0-.75-.75h-3.5a.75.75 0 0 0 0 1.5h1.69L6.22 8.72Z" />
+                <path d="M3.5 6.75c0-.69.56-1.25 1.25-1.25H7A.75.75 0 0 0 7 4H4.75A2.75 2.75 0 0 0 2 6.75v4.5A2.75 2.75 0 0 0 4.75 14h4.5A2.75 2.75 0 0 0 12 11.25V9a.75.75 0 0 0-1.5 0v2.25c0 .69-.56 1.25-1.25 1.25h-4.5c-.69 0-1.25-.56-1.25-1.25v-4.5Z" />
+              </svg>
+            </a>
+          ) : (
+            <span className="text-text-muted">—</span>
+          ),
+        mobile: false,
+      },
     ],
     [jurisdictionFilter]
   );

From 00353abd2ab9211cf852c141028aeca57c7d666c Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:55:58 -0400
Subject: [PATCH 14/41] =?UTF-8?q?feat:=20CMD+K=20search=20improvements=20?=
 =?UTF-8?q?=E2=80=94=20result=20counts=20and=20loading=20state?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Added entity count badges next to section headers in search results.
Improved Tier-2 async loading indicator with descriptive text.
---
 components/GlobalSearch.tsx | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/components/GlobalSearch.tsx b/components/GlobalSearch.tsx
index 7f700850..71bf5d58 100644
--- a/components/GlobalSearch.tsx
+++ b/components/GlobalSearch.tsx
@@ -654,7 +654,10 @@ export function GlobalSearchModal() {
             />
             <div className="flex items-center gap-2 flex-none">
               {loadingAsync && (
-                <div className="w-3.5 h-3.5 rounded-full border-2 border-brand-primary border-t-transparent animate-spin" />
+                <div className="flex items-center gap-1.5">
+                  <div className="w-3.5 h-3.5 rounded-full border-2 border-brand-primary border-t-transparent animate-spin" />
+                  <span className="text-[10px] text-text-muted hidden sm:inline">Loading more...</span>
+                </div>
               )}
               {query ? (
                 <button
@@ -735,6 +738,7 @@ export function GlobalSearchModal() {
                   <div key={group.kind} className="mb-1">
                     <div className="px-2 py-1.5">
                       <span className="text-[11px] font-semibold uppercase tracking-widest text-text-muted">{group.label}</span>
+                      <span className="text-[10px] text-text-muted ml-1.5 tabular-nums">{group.items.length}</span>
                     </div>
                     {group.items.map((result) => {
                       const idx = flatIndex++;

From 73c7db59e9a56096f12032ee99aea3d0bb9b8daf Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:56:48 -0400
Subject: [PATCH 15/41] fix: improve service territory map bounds and zoom
 calculation

Finer-grained zoom levels for better localized territory views.
Added intermediate zoom steps and tighter thresholds so small
service territories don't render too zoomed out.
---
 lib/geo.ts | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/lib/geo.ts b/lib/geo.ts
index c7d81da7..33d98958 100644
--- a/lib/geo.ts
+++ b/lib/geo.ts
@@ -39,15 +39,18 @@ export function computeViewStateFromGeoJSON(geoJSON: FeatureCollection): ViewSta
   const latSpan = maxLat - minLat;
   const maxSpan = Math.max(lngSpan, latSpan);
 
-  let zoom = 8;
-  if (maxSpan > 20) zoom = 3;
-  else if (maxSpan > 10) zoom = 4;
-  else if (maxSpan > 5) zoom = 5;
+  // Finer-grained zoom with padding for tight bounding box fit
+  let zoom = 10;
+  if (maxSpan > 30) zoom = 3;
+  else if (maxSpan > 15) zoom = 4;
+  else if (maxSpan > 8) zoom = 5;
+  else if (maxSpan > 4) zoom = 5.5;
   else if (maxSpan > 2) zoom = 6;
   else if (maxSpan > 1) zoom = 7;
   else if (maxSpan > 0.5) zoom = 8;
   else if (maxSpan > 0.2) zoom = 9;
-  else zoom = 10;
+  else if (maxSpan > 0.05) zoom = 10;
+  else zoom = 11;
 
   return { longitude: centerLng, latitude: centerLat, zoom };
 }

From 7da3bdbb3537bf8165d598426242d319eaa9c19f Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:57:37 -0400
Subject: [PATCH 16/41] feat: add search to changelog data feed

Changelog now supports text search across entity names and details.
Search input appears above the meta bar in the Data Changes tab.
---
 app/(shell)/changelog/page.tsx | 30 ++++++++++++++++++++++++++----
 1 file changed, 26 insertions(+), 4 deletions(-)

diff --git a/app/(shell)/changelog/page.tsx b/app/(shell)/changelog/page.tsx
index 1492281e..4a0e3f48 100644
--- a/app/(shell)/changelog/page.tsx
+++ b/app/(shell)/changelog/page.tsx
@@ -123,6 +123,7 @@ export default function ChangelogPage() {
   const changelog = getChangelog();
   const [tab, setTab] = useState<"data" | "site">("data");
   const [entityTypeFilter, setEntityTypeFilter] = useState<string>("all");
+  const [searchQuery, setSearchQuery] = useState("");
 
   // Merge and sort all entries newest-first
   const allEntries = useMemo(
@@ -139,11 +140,20 @@ export default function ChangelogPage() {
     return Array.from(types).sort();
   }, [allEntries]);
 
-  // Filtered entries
+  // Filtered entries (by entity type + search)
   const filteredEntries = useMemo(() => {
-    if (entityTypeFilter === "all") return allEntries;
-    return allEntries.filter((e) => e.entityType === entityTypeFilter);
-  }, [allEntries, entityTypeFilter]);
+    let result = allEntries;
+    if (entityTypeFilter !== "all") {
+      result = result.filter((e) => e.entityType === entityTypeFilter);
+    }
+    if (searchQuery.trim()) {
+      const q = searchQuery.toLowerCase();
+      result = result.filter(
+        (e) => e.name.toLowerCase().includes(q) || e.detail.toLowerCase().includes(q),
+      );
+    }
+    return result;
+  }, [allEntries, entityTypeFilter, searchQuery]);
 
   const groups = groupByDate(filteredEntries);
 
@@ -211,6 +221,18 @@ export default function ChangelogPage() {
 
         {tab === "data" && (
         <Section id="feed" navLabel="Changes" withDivider={false}>
+          {/* Search */}
+          <div className="relative mb-4">
+            <Icon name="MagnifyingGlass" size={16} className="absolute left-3 top-1/2 -translate-y-1/2 text-text-muted" />
+            <input
+              type="text"
+              value={searchQuery}
+              onChange={(e) => setSearchQuery(e.target.value)}
+              placeholder="Search changes..."
+              className="w-full h-9 pl-9 pr-3 rounded-lg border border-border-default bg-background-surface text-sm text-text-body placeholder:text-text-muted outline-none focus:border-brand-primary transition-colors"
+            />
+          </div>
+
           {/* Meta bar */}
           <div className="flex items-center justify-between mb-6">
             <div className="flex items-center gap-2">

From 86894558dd3a935b07f26f8e43b076497430a0bc Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:58:49 -0400
Subject: [PATCH 17/41] style: update favicon to match new G-in-C logo mark

Favicon SVG updated to match the new CommonGrid logo with
G-in-C dendritic graph design.
---
 public/favicon.svg | 38 ++++++++++++++++++++------------------
 1 file changed, 20 insertions(+), 18 deletions(-)

diff --git a/public/favicon.svg b/public/favicon.svg
index 7a829826..b00e0cb1 100644
--- a/public/favicon.svg
+++ b/public/favicon.svg
@@ -1,20 +1,22 @@
 <svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
-  <!-- Top row -->
-  <circle cx="4" cy="4" r="1.8" fill="#111111"/>
-  <circle cx="12" cy="4" r="1.8" fill="#111111"/>
-  <circle cx="20" cy="4" r="1.8" fill="#111111"/>
-  <circle cx="28" cy="4" r="1.8" fill="#111111"/>
-  <!-- Left col -->
-  <circle cx="4" cy="12" r="1.8" fill="#111111"/>
-  <circle cx="4" cy="20" r="1.8" fill="#111111"/>
-  <!-- Right col -->
-  <circle cx="28" cy="12" r="1.8" fill="#111111"/>
-  <circle cx="28" cy="20" r="1.8" fill="#111111"/>
-  <!-- Bottom row -->
-  <circle cx="4" cy="28" r="1.8" fill="#111111"/>
-  <circle cx="12" cy="28" r="1.8" fill="#111111"/>
-  <circle cx="20" cy="28" r="1.8" fill="#111111"/>
-  <circle cx="28" cy="28" r="1.8" fill="#111111"/>
-  <!-- Solid center square -->
-  <rect x="11" y="11" width="10" height="10" rx="1.5" fill="#111111"/>
+  <!-- C arc — open on the right -->
+  <path d="M22 10 A10 10 0 1 0 22 22" stroke="#111111" stroke-width="2" stroke-linecap="round" fill="none" />
+  <!-- G crossbar -->
+  <line x1="22" y1="16" x2="16" y2="16" stroke="#111111" stroke-width="2" stroke-linecap="round" />
+  <!-- Dendritic edges -->
+  <line x1="16" y1="16" x2="10" y2="8" stroke="#111111" stroke-width="0.8" opacity="0.5" />
+  <line x1="16" y1="16" x2="7" y2="14" stroke="#111111" stroke-width="0.8" opacity="0.5" />
+  <line x1="16" y1="16" x2="7" y2="20" stroke="#111111" stroke-width="0.8" opacity="0.5" />
+  <line x1="16" y1="16" x2="10" y2="25" stroke="#111111" stroke-width="0.8" opacity="0.5" />
+  <line x1="10" y1="8" x2="14" y2="6" stroke="#111111" stroke-width="0.8" opacity="0.5" />
+  <line x1="10" y1="25" x2="14" y2="27" stroke="#111111" stroke-width="0.8" opacity="0.5" />
+  <!-- Network nodes -->
+  <circle cx="16" cy="16" r="1.8" fill="#111111" />
+  <circle cx="10" cy="8" r="1.3" fill="#111111" />
+  <circle cx="7" cy="14" r="1.3" fill="#111111" />
+  <circle cx="7" cy="20" r="1.3" fill="#111111" />
+  <circle cx="10" cy="25" r="1.3" fill="#111111" />
+  <circle cx="14" cy="6" r="1.0" fill="#111111" />
+  <circle cx="14" cy="27" r="1.0" fill="#111111" />
+  <circle cx="22" cy="16" r="1.3" fill="#111111" />
 </svg>

From ed0419182f508e543e1627f94e0ffd1a95d699ec Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:59:05 -0400
Subject: [PATCH 18/41] fix: add layout key to ExplorerMap for clean remount on
 mode switch

Map component now receives layout as key prop, forcing clean
remount when switching between hybrid/list/map modes to prevent
stale render state.
---
 components/explorer/ExplorerShell.tsx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/components/explorer/ExplorerShell.tsx b/components/explorer/ExplorerShell.tsx
index a20c54d2..8b32a1c8 100644
--- a/components/explorer/ExplorerShell.tsx
+++ b/components/explorer/ExplorerShell.tsx
@@ -69,7 +69,7 @@ function HybridLayout({ mapboxAccessToken }: HybridLayoutProps) {
 
       {/* Map — RIGHT */}
       <div className="flex-1 min-w-0 h-full">
-        <ExplorerMap mapboxAccessToken={mapboxAccessToken} />
+        <ExplorerMap key={layout} mapboxAccessToken={mapboxAccessToken} />
       </div>
     </div>
   );
@@ -114,7 +114,7 @@ function ExplorerLayout({ mapboxAccessToken }: ExplorerLayoutProps) {
           )}
           {layout === "map" && (
             <div className="h-full">
-              <ExplorerMap mapboxAccessToken={mapboxAccessToken} />
+              <ExplorerMap key={layout} mapboxAccessToken={mapboxAccessToken} />
             </div>
           )}
         </div>
@@ -122,7 +122,7 @@ function ExplorerLayout({ mapboxAccessToken }: ExplorerLayoutProps) {
         {/* Mobile layouts */}
         <div className="md:hidden h-full relative">
           {layout === "map" ? (
-            <ExplorerMap mapboxAccessToken={mapboxAccessToken} />
+            <ExplorerMap key={layout} mapboxAccessToken={mapboxAccessToken} />
           ) : (
             <div className="h-full bg-background-surface">
               <ExplorerPanel />

From f37bc366e3225dc2b3f3b2755ada5f2f27de0068 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 13:59:41 -0400
Subject: [PATCH 19/41] style: tighten mobile explorer tab labels

Reduced mobile tab label text size to text-xs for better fit on
narrow viewports without horizontal scrolling.
---
 components/explorer/ExplorerTabBar.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/explorer/ExplorerTabBar.tsx b/components/explorer/ExplorerTabBar.tsx
index 55b13754..78f571e1 100644
--- a/components/explorer/ExplorerTabBar.tsx
+++ b/components/explorer/ExplorerTabBar.tsx
@@ -82,7 +82,7 @@ export function ExplorerTabBar() {
           >
             <span className={isActive ? "text-brand-primary" : "text-text-muted"}>{tab.icon}</span>
             <span className="hidden sm:inline">{tab.label}</span>
-            <span className="sm:hidden">{tab.shortLabel}</span>
+            <span className="sm:hidden text-xs">{tab.shortLabel}</span>
           </button>
         );
       })}

From c20685948c7e396e729d07c366f70d72baf1bb78 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 14:00:22 -0400
Subject: [PATCH 20/41] style: improve mobile menu styling and active state

Mobile nav menu items now show hover backgrounds, active items
highlighted with brand color and surface background. GitHub link
separated with border divider.
---
 components/TopBar.tsx | 32 ++++++++++++++++++--------------
 1 file changed, 18 insertions(+), 14 deletions(-)

diff --git a/components/TopBar.tsx b/components/TopBar.tsx
index 768a6c47..bc3cffb9 100644
--- a/components/TopBar.tsx
+++ b/components/TopBar.tsx
@@ -151,7 +151,7 @@ export function TopBar({ navigation }: TopBarProps) {
       </div>
 
       {mobileMenuOpen && (
-        <nav className="sm:hidden border-t border-border-default px-4 py-2">
+        <nav className="sm:hidden border-t border-border-default px-4 py-2 bg-[var(--color-background-subtle)]">
           {navigation.map((item) =>
             item.external ? (
               <a
@@ -159,7 +159,7 @@ export function TopBar({ navigation }: TopBarProps) {
                 href={item.href}
                 target="_blank"
                 rel="noopener noreferrer"
-                className="block px-3 py-2 rounded-md text-sm transition-colors text-text-muted hover:text-text-body"
+                className="block px-3 py-2.5 rounded-md text-sm transition-colors text-text-muted hover:text-text-body hover:bg-background-surface"
               >
                 {item.label}
               </a>
@@ -167,24 +167,28 @@ export function TopBar({ navigation }: TopBarProps) {
               <Link
                 key={item.id}
                 href={item.href}
-                className={`block px-3 py-2 rounded-md text-sm transition-colors ${
-                  isActive(item) ? "text-text-body font-medium" : "text-text-muted hover:text-text-body"
+                className={`block px-3 py-2.5 rounded-md text-sm transition-colors ${
+                  isActive(item)
+                    ? "text-brand-primary font-medium bg-background-surface"
+                    : "text-text-muted hover:text-text-body hover:bg-background-surface"
                 }`}
               >
                 {item.label}
               </Link>
             )
           )}
-          <Button
-            variant="icon"
-            href="https://github.com/TextureHQ/commongrid"
-            target="_blank"
-            rel="noopener noreferrer"
-            className="flex items-center gap-2 px-3 py-2 w-full justify-start text-sm"
-          >
-            <GitHubIcon />
-            <span>GitHub</span>
-          </Button>
+          <div className="mt-1 pt-2 border-t border-border-default">
+            <Button
+              variant="icon"
+              href="https://github.com/TextureHQ/commongrid"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="flex items-center gap-2 px-3 py-2 w-full justify-start text-sm"
+            >
+              <GitHubIcon />
+              <span>GitHub</span>
+            </Button>
+          </div>
         </nav>
       )}
     </header>

From 64d1943bbd642f6cdbe2c5533b36a6a18ef3b07e Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 14:00:50 -0400
Subject: [PATCH 21/41] style: truncate DataSourceLink on narrow viewports

Added truncate class to prevent the source data link from
overflowing on very narrow screens.
---
 components/DataSourceLink.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/DataSourceLink.tsx b/components/DataSourceLink.tsx
index 3de5e97c..c78f3f06 100644
--- a/components/DataSourceLink.tsx
+++ b/components/DataSourceLink.tsx
@@ -14,7 +14,7 @@ export function DataSourceLink({ paths, className = "" }: DataSourceLinkProps) {
         href={`${GITHUB_BASE}/${paths[0]}`}
         target="_blank"
         rel="noopener noreferrer"
-        className={`inline-flex items-center gap-1.5 text-xs text-text-muted hover:text-brand-primary transition-colors ${className}`}
+        className={`inline-flex items-center gap-1.5 text-xs text-text-muted hover:text-brand-primary transition-colors truncate ${className}`}
       >
         <span>📦</span>
         <span>View source data on GitHub</span>

From cf533a980deea89d8d773479a1146287be837682 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 14:01:20 -0400
Subject: [PATCH 22/41] style: responsive search input sizing and result count
 visibility

Search input slightly shorter on mobile (h-10 vs h-11), text-sm
for compact feel. Result count hidden on narrow viewports to save
horizontal space.
---
 components/SearchInput.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/components/SearchInput.tsx b/components/SearchInput.tsx
index 0117995a..aeaf3cac 100644
--- a/components/SearchInput.tsx
+++ b/components/SearchInput.tsx
@@ -33,7 +33,7 @@ export function SearchInput({
         value={value}
         onChange={(e) => onChange(e.target.value)}
         placeholder={placeholder}
-        className="w-full h-11 pl-10 pr-20 rounded-lg border border-border-default bg-background-surface text-text-body text-base placeholder:text-text-muted focus:outline-none focus:ring-2 focus:ring-brand-primary/40 focus:border-brand-primary transition-colors"
+        className="w-full h-10 sm:h-11 pl-10 pr-20 rounded-lg border border-border-default bg-background-surface text-text-body text-sm sm:text-base placeholder:text-text-muted focus:outline-none focus:ring-2 focus:ring-brand-primary/40 focus:border-brand-primary transition-colors"
       />
       <div className="absolute inset-y-0 right-0 flex items-center gap-2 pr-3">
         {value && (
@@ -50,7 +50,7 @@ export function SearchInput({
           </button>
         )}
         {resultCount !== undefined && value && (
-          <span className="text-xs text-text-muted tabular-nums whitespace-nowrap">
+          <span className="text-xs text-text-muted tabular-nums whitespace-nowrap hidden sm:inline">
             {resultCount.toLocaleString()} {resultLabel ?? "results"}
           </span>
         )}

From a3129d52b38bb383f5c938da11a4f106c1c39d09 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 14:02:21 -0400
Subject: [PATCH 23/41] feat: add page metadata to explore page

Added title and description metadata for better SEO and tab
labeling on the interactive explorer page.
---
 app/(shell)/explore/page.tsx | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/app/(shell)/explore/page.tsx b/app/(shell)/explore/page.tsx
index 23ed6a82..fdc6f06a 100644
--- a/app/(shell)/explore/page.tsx
+++ b/app/(shell)/explore/page.tsx
@@ -1,5 +1,11 @@
+import type { Metadata } from "next";
 import { ExplorerShell } from "@/components/explorer/ExplorerShell";
 
+export const metadata: Metadata = {
+  title: "Explore",
+  description: "Interactive map and data explorer for US energy infrastructure — utilities, power plants, transmission lines, EV charging stations, and pricing nodes.",
+};
+
 export default function ExplorePage() {
   const mapboxAccessToken =
     process.env.MAPBOX_ACCESS_TOKEN ?? process.env.NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN;

From ff146f7b9e850379fe4a43a4f0616567ddabdc8f Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 14:24:11 -0400
Subject: [PATCH 24/41] docs: add PR description template and welcome-pr
 analysis artifact

Introduces the CommonGrid PR Description Standard v1.0 as a reusable
GitHub PR template (.github/PULL_REQUEST_TEMPLATE.md) and produces
the first instance (PR_DESCRIPTION.md) with full changeset analysis:
commit classification, file impact matrix, dependency graphs, responsive
audit, risk assessment, and test plan.
---
 .github/PULL_REQUEST_TEMPLATE.md | 144 ++++++++++++++
 PR_DESCRIPTION.md                | 325 +++++++++++++++++++++++++++++++
 2 files changed, 469 insertions(+)
 create mode 100644 .github/PULL_REQUEST_TEMPLATE.md
 create mode 100644 PR_DESCRIPTION.md

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 00000000..e39303fe
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,144 @@
+<!--
+  CommonGrid Pull Request Description Standard v1.0
+  ──────────────────────────────────────────────────
+  This template defines the canonical PR description format for the CommonGrid project.
+  It is designed to be:
+    • Routinely producible — sections can be generated via `scripts/pr-describe.sh`
+    • Attestable — reviewers check boxes to confirm analysis was reviewed
+    • Extensible — optional sections can be included/omitted per author discretion
+    • Machine-readable — structured tables and mermaid diagrams for tooling
+
+  USAGE:
+    Required sections:  Summary, Changeset Overview, Test Plan
+    Recommended:        Impact Analysis, Risk Assessment, Commit Table
+    Optional:           Architecture Diagrams, Responsive Audit, Deferred Work
+
+  Section markers use HTML comments for collapse/expand and tooling hooks.
+-->
+
+## Summary
+<!-- 1-3 sentences. What changed and why. Link related issues. -->
+
+
+## Motivation
+<!-- What problem does this solve? Who benefits? Link to issue/discussion if applicable. -->
+
+
+## Changeset Overview
+<!-- Auto-generated or manually composed. Use `git diff --stat` as baseline. -->
+
+| Metric | Value |
+|--------|-------|
+| Commits | |
+| Files changed | |
+| Insertions | |
+| Deletions | |
+| Net | |
+
+## Commit Log
+<!-- Conventional Commit format. Classify by type/scope/magnitude. -->
+
+| Hash | Type | Scope | Description | Size | Risk |
+|------|------|-------|-------------|------|------|
+| | | | | | |
+
+<details>
+<summary><strong>Commit Classification Key</strong></summary>
+
+- **Type**: `feat` | `fix` | `style` | `refactor` | `test` | `docs` | `chore`
+- **Size**: `S` (<20 lines) | `M` (20-80 lines) | `L` (>80 lines)
+- **Risk**: `low` (additive/isolated) | `medium` (cross-cutting/visual) | `high` (behavioral/breaking)
+
+</details>
+
+## File Impact Matrix
+<!-- Categorize each file by layer and change character. -->
+
+| File | Layer | +/- | Character |
+|------|-------|-----|-----------|
+| | | | |
+
+<details>
+<summary><strong>Layer & Character Key</strong></summary>
+
+- **Layer**: `page` | `component` | `lib` | `style` | `asset` | `config` | `type` | `test`
+- **Character**: _Major feature_ | _New columns/fields_ | _Style-only_ | _Bug fix_ | _Metadata_ | _Refactor_
+
+</details>
+
+## Architecture & Dependency
+<!-- Mermaid diagram showing file dependencies and review ordering. -->
+
+```mermaid
+graph TD
+    %% Replace with actual dependency graph
+    A[foundation libs] --> B[components]
+    B --> C[pages]
+```
+
+## Impact Analysis
+
+### Component Touch Map
+<!-- Which components were modified? Show render hierarchy. -->
+
+### Responsive Breakpoint Audit
+<!-- What changed at each viewport threshold? -->
+
+| Breakpoint | Changes |
+|------------|---------|
+| `< sm` (640px) | |
+| `< md` (768px) | |
+| `≥ lg` (1024px) | |
+| All viewports | |
+
+### CSS / Tailwind Delta
+<!-- Notable class additions, removals, or replacements. -->
+
+## Risk Assessment
+
+### Regression Risk Matrix
+<!-- Classify changes by regression likelihood. -->
+
+| Change | Risk | Blast Radius | Mitigation |
+|--------|------|-------------|------------|
+| | | | |
+
+```mermaid
+quadrantChart
+    title Change Risk vs Impact
+    x-axis Low Impact --> High Impact
+    y-axis Low Risk --> High Risk
+    %% Plot changes here
+```
+
+## Deferred Work
+<!-- What was explicitly out-of-scope? Link to follow-up issues. -->
+
+- [ ] _Item_ — rationale for deferral
+
+## Test Plan
+<!-- How was this tested? What should reviewers verify? -->
+
+- [ ] Visual regression check at 320px, 768px, 1440px viewports
+- [ ] Dark mode / light mode toggle
+- [ ] Navigation flow (all pages load, links resolve)
+- [ ] CMD+K search opens and returns results
+- [ ] Map loads and resizes on layout switch
+
+## Reviewer Checklist
+<!-- Reviewers: check each box after confirming. -->
+
+- [ ] Changeset overview matches actual diff
+- [ ] Risk assessment reviewed and agreed
+- [ ] No secrets, credentials, or .env values committed
+- [ ] Responsive behavior verified at stated breakpoints
+- [ ] Accessibility: focus order, aria labels, contrast ratios
+
+## Screenshots / Recordings
+<!-- Before/after at key breakpoints. Attach or link. -->
+
+| Viewport | Before | After |
+|----------|--------|-------|
+| Mobile (375px) | | |
+| Tablet (768px) | | |
+| Desktop (1440px) | | |
diff --git a/PR_DESCRIPTION.md b/PR_DESCRIPTION.md
new file mode 100644
index 00000000..b81f4cd8
--- /dev/null
+++ b/PR_DESCRIPTION.md
@@ -0,0 +1,325 @@
+## Summary
+
+Comprehensive UX, responsive design, and data-density overhaul across the CommonGrid registry. 23 commits addressing dropdown styling, table field coverage, sort UX, badge consistency, header spacing, Mapbox stability, changelog usability, narrow-viewport responsiveness, CMD+K search polish, and a new logo mark — the "G-in-C" with dendritic tree-graph connections.
+
+## Motivation
+
+CommonGrid's table pages, header, and explorer map had accumulated a set of fit-and-finish issues that individually were small but collectively degraded the experience — particularly on narrow viewports. This PR treats them as a cohesive surface area, applying consistent patterns (dropdown padding, filter stacking, sort indicators, hyphenation) across all 5 data pages, the explorer, and the changelog. The logo redesign gives CommonGrid a distinctive mark that communicates grid topology.
+
+Addresses items from the [commongrid.info issue backlog](https://github.com/TextureHQ/commongrid/issues).
+
+## Changeset Overview
+
+| Metric | Value |
+|--------|-------|
+| Commits | **23** |
+| Files changed | **25** |
+| Insertions | **+425** |
+| Deletions | **-179** |
+| Net | **+246** |
+| Commit types | 10 feat · 6 fix · 7 style |
+| Risk profile | 18 low · 5 medium · 0 high |
+
+## Commit Log
+
+| Hash | Type | Scope | Description | Size | Risk |
+|------|------|-------|-------------|------|------|
+| `3f89367` | fix | dropdowns (9 files) | Inner right-side padding for chevrons | S | low |
+| `b7e25b2` | fix | globals.css + 4 pages | CSS hyphenation for long entity names | S | low |
+| `111ef3f` | fix | formatting.ts (×2) | Complete badge variant mapping for all utility segments | S | low |
+| `106f641` | style | TopBar, ShellLayout, GlobalSearch | Header spacing overhaul (h-14→h-12, tighter nav) | M | med |
+| `7c9de2f` | style | grid-operators | Conditional name clamping (line-clamp-2 / 1) | S | low |
+| `37b1abc` | feat | 5 data pages | Sort-direction ▲/▼ chevrons in dropdown labels | S | low |
+| `791740d` | feat | power-plants, transmission-lines | County, Year, Generators columns; From/To labels | M | low |
+| `ece78d0` | feat | grid-operators | Jurisdiction state-based highlighting on filter | S | low |
+| `ea227b5` | feat | changelog | Data Changes / Site Updates tab distinction | L | med |
+| `c9e343a` | fix | ExplorerMap | ResizeObserver replaces setTimeout for map resize | M | med |
+| `ecdc89b` | feat | TopBar, logo.svg | Logo redesign — G-in-C with dendritic graph | M | med |
+| `049d059` | style | 5 data pages | Stack filter dropdowns vertically at narrow breakpoints | S | low |
+| `ba4b06d` | feat | grid-operators | EIA ID, BA Code, NERC, website link columns | L | low |
+| `00353ab` | feat | GlobalSearch | CMD+K result counts and loading state | S | low |
+| `73c7db5` | fix | geo.ts | Finer-grained zoom for service territory bounds | S | med |
+| `7da3bdb` | feat | changelog | Search input and entity-type filter chips | L | low |
+| `8689455` | style | favicon.svg | Favicon updated to new logo mark | S | low |
+| `ed04191` | fix | ExplorerShell | Layout key on ExplorerMap for clean remount | S | low |
+| `f37bc36` | style | ExplorerTabBar | Mobile tab labels tightened to text-xs | S | low |
+| `c206859` | style | TopBar | Mobile menu active state + hover backgrounds | M | low |
+| `64d1943` | style | DataSourceLink | Truncate on narrow viewports | S | low |
+| `cf533a9` | style | SearchInput | Responsive height (h-10/h-11) + hidden result count | S | low |
+| `a3129d5` | feat | explore page | Page title and description metadata | S | low |
+
+## File Impact Matrix
+
+| File | Layer | +/- | Character |
+|------|-------|-----|-----------|
+| `app/(shell)/grid-operators/page.tsx` | page | +78 / -11 | Major: 4 new columns, highlighting, clamping, filters |
+| `app/(shell)/changelog/page.tsx` | page | +116 / -6 | Major: tab UI, search, entity filters |
+| `app/(shell)/power-plants/page.tsx` | page | +42 / -9 | New columns: county, year, generators |
+| `app/(shell)/ev-charging/page.tsx` | page | +12 / -12 | Style: padding, stacking, hyphenation |
+| `app/(shell)/pricing-nodes/page.tsx` | page | +9 / -9 | Style: padding, sort labels |
+| `app/(shell)/transmission-lines/page.tsx` | page | +10 / -10 | Style + From/To substation labels |
+| `app/(shell)/explore/page.tsx` | page | +6 / -0 | Metadata addition |
+| `components/TopBar.tsx` | component | +45 / -39 | Logo SVG, spacing, mobile menu |
+| `components/explorer/ExplorerMap.tsx` | component | +15 / -10 | ResizeObserver lifecycle fix |
+| `components/explorer/ExplorerShell.tsx` | component | +3 / -3 | key={layout} prop |
+| `components/GlobalSearch.tsx` | component | +6 / -2 | Result counts, loading text |
+| `components/ShellLayoutClient.tsx` | component | +1 / -1 | pt-14 → pt-12 |
+| `components/SearchInput.tsx` | component | +2 / -2 | Responsive height + hidden count |
+| `components/DataSourceLink.tsx` | component | +1 / -1 | Truncation class |
+| `components/explorer/ExplorerTabBar.tsx` | component | +1 / -1 | text-xs mobile labels |
+| `components/explorer/panels/*` (4 files) | component | +4 / -4 | Dropdown chevron padding |
+| `lib/formatting.ts` | lib | +9 / -9 | Badge variant remapping |
+| `explorer/lib/formatting.ts` | lib | +9 / -9 | Badge variant remapping (mirror) |
+| `lib/geo.ts` | lib | +8 / -5 | Zoom calculation refinement |
+| `app/globals.css` | style | +8 / -0 | hyphens-auto utility class |
+| `public/logo.svg` | asset | +20 / -18 | New G-in-C logo mark |
+| `public/favicon.svg` | asset | +20 / -18 | Favicon matches new logo |
+
+## Architecture & Dependency
+
+### Review Order Dependency Graph
+
+```mermaid
+graph TD
+    subgraph "1 · Foundation"
+        CSS[globals.css<br/><i>hyphens-auto</i>]
+        FMT[lib/formatting.ts<br/><i>badge variants</i>]
+        GEO[lib/geo.ts<br/><i>zoom calc</i>]
+    end
+
+    subgraph "2 · Assets"
+        LOGO[public/logo.svg]
+        FAV[public/favicon.svg]
+    end
+
+    subgraph "3 · Shell"
+        TB[TopBar<br/><i>logo + spacing</i>]
+        SLC[ShellLayoutClient<br/><i>pt-12</i>]
+        GS[GlobalSearch<br/><i>counts + loading</i>]
+    end
+
+    subgraph "4 · Explorer"
+        EM[ExplorerMap<br/><i>ResizeObserver</i>]
+        ES[ExplorerShell<br/><i>key prop</i>]
+        ETB[ExplorerTabBar<br/><i>text-xs</i>]
+        PANELS[Explorer Panels ×4<br/><i>chevron padding</i>]
+    end
+
+    subgraph "5 · Shared"
+        SI[SearchInput<br/><i>responsive</i>]
+        DSL[DataSourceLink<br/><i>truncate</i>]
+    end
+
+    subgraph "6 · Data Pages"
+        GO[grid-operators<br/><i>7 commits</i>]
+        PP[power-plants<br/><i>5 commits</i>]
+        TL[transmission-lines<br/><i>4 commits</i>]
+        EV[ev-charging<br/><i>4 commits</i>]
+        PN[pricing-nodes<br/><i>4 commits</i>]
+    end
+
+    subgraph "7 · Feature Pages"
+        CL[changelog<br/><i>tabs + search</i>]
+        EX[explore<br/><i>metadata</i>]
+    end
+
+    CSS --> GO & PP & TL & EV & PN
+    FMT --> GO & EV
+    GEO --> EM
+    LOGO --> TB
+    TB --> SLC
+    GS --> SLC
+    EM --> ES
+    SI --> GO & PP & TL & EV & PN
+    DSL --> GO & PP & TL & EV & PN
+
+    style CSS fill:#e1f5fe,stroke:#0277bd
+    style FMT fill:#e1f5fe,stroke:#0277bd
+    style GEO fill:#e1f5fe,stroke:#0277bd
+    style TB fill:#fff3e0,stroke:#ef6c00
+    style EM fill:#fff3e0,stroke:#ef6c00
+    style GO fill:#fce4ec,stroke:#c62828
+    style CL fill:#e8f5e9,stroke:#2e7d32
+```
+
+### Commit Clustering by File
+
+```mermaid
+graph LR
+    subgraph "grid-operators/page.tsx — 7 commits"
+        G1[3f89367 chevron]
+        G2[b7e25b2 hyphens]
+        G3[7c9de2f clamp]
+        G4[37b1abc sort ▲▼]
+        G5[049d059 stacking]
+        G6[ece78d0 highlight]
+        G7[ba4b06d fields]
+    end
+
+    subgraph "TopBar.tsx — 3 commits"
+        T1[106f641 spacing]
+        T2[ecdc89b logo]
+        T3[c206859 mobile]
+    end
+
+    subgraph "changelog/page.tsx — 2 commits"
+        C1[ea227b5 tabs]
+        C2[7da3bdb search]
+    end
+```
+
+## Impact Analysis
+
+### Component Touch Map
+
+```
+App (layout.tsx)
+ └── ShellLayoutClient ............... [pt-14→pt-12]
+      ├── TopBar ..................... [h-12, gap-8, logo SVG, mobile menu]
+      │    └── inline SVG ........... [12-circle grid → G-in-C dendritic]
+      ├── GlobalSearchModal ......... [top-12, result counts, loading text]
+      └── <page routes>
+           ├── ChangelogPage ........ [tab bar, search, entity-type chips]
+           ├── GridOperatorsPage .... [4 columns, highlighting, clamping]
+           ├── PowerPlantsPage ...... [3 columns, hyphenation]
+           ├── TransmissionLinesPage  [From/To labels, sort ▲▼]
+           ├── EVChargingPage ....... [padding, stacking, hyphenation]
+           ├── PricingNodesPage ..... [padding, sort ▲▼]
+           └── ExplorePage .......... [metadata]
+                └── ExplorerShell ... [key={layout}]
+                     ├── ExplorerMap  [ResizeObserver, containerRef]
+                     ├── ExplorerTabBar [text-xs mobile]
+                     └── Panels ×4 .. [pl-2 pr-7]
+```
+
+### Responsive Breakpoint Audit
+
+| Breakpoint | Changes |
+|------------|---------|
+| **< sm** (640px) | Filters stack vertically · Search result count hidden · Search input h-10 + text-sm · Name wraps to 2 lines · Tab labels text-xs · Loading indicator text hidden |
+| **< md** (768px) | DataTable mobile mode (existing, unchanged) · Mobile menu gets active brand color + hover bg |
+| **≥ lg** (1024px) | TopBar horizontal padding increases (px-4 → lg:px-6) |
+| **All viewports** | Header h-14→h-12 · Nav padding tightened · Dropdown pr-7 for chevron · CSS hyphens-auto · Sort ▲/▼ labels · Badge variant colors |
+
+### CSS / Tailwind Delta
+
+<details>
+<summary><strong>Classes Added</strong></summary>
+
+| Class | Usage | Purpose |
+|-------|-------|---------|
+| `.hyphens-auto` (custom) | globals.css → 4 pages | Browser hyphenation for long names |
+| `line-clamp-2 sm:line-clamp-1` | grid-operators name column | Responsive line wrapping |
+| `flex-col sm:flex-row` | All filter containers | Vertical stacking on mobile |
+| `pl-2 pr-7` | All `<select>` elements (9 files) | Asymmetric padding for native chevron |
+| `animate-pulse` | Changelog sync indicator | Live data visual cue |
+| `hidden sm:inline` | SearchInput count, GlobalSearch text | Hide on narrow |
+| `hover:bg-background-surface` | Mobile menu items | Touch feedback |
+| `tabular-nums` | New numeric columns | Monospace digit alignment |
+
+</details>
+
+<details>
+<summary><strong>Classes Replaced</strong></summary>
+
+| Before | After | Where |
+|--------|-------|-------|
+| `h-14` | `h-12` | TopBar container |
+| `pt-14` | `pt-12` | ShellLayoutClient main offset |
+| `top-14` | `top-12` | GlobalSearch backdrop |
+| `px-5` | `px-4 lg:px-6` | TopBar horizontal padding |
+| `gap-6` | `gap-8` | TopBar logo↔nav gap |
+| `px-3 py-1.5` | `px-2.5 py-1` | TopBar nav links |
+| `gap-1` | `gap-1.5` | TopBar icon groups |
+| `text-[15px]` | `text-sm` | TopBar brand text |
+| `px-2` | `pl-2 pr-7` | All filter `<select>` elements |
+| `truncate` | `line-clamp-2 sm:line-clamp-1` | Grid-operators name cell |
+
+</details>
+
+## Risk Assessment
+
+| Change | Risk | Blast Radius | Mitigation |
+|--------|------|-------------|------------|
+| TopBar h-14→h-12 + content offset | **Medium** | Every page (shell layout) | All 3 consumers updated: ShellLayoutClient, GlobalSearch backdrop, TopBar |
+| Logo SVG replacement | **Medium** | Header + favicon | Same viewBox (32×32), same className, uses currentColor |
+| ExplorerMap ResizeObserver | **Medium** | Map explorer page | ResizeObserver has universal browser support; RAF prevents layout thrash |
+| Badge variant remapping | **Medium** | Grid-operators table + explorer panels | Both formatting.ts files updated in sync |
+| Zoom calculation refinement | **Medium** | Service territory map views | Only affects zoom level selection, not data; more granular = better |
+| Filter dropdown vertical stacking | **Low** | 5 data pages on mobile | Purely additive `flex-col` at default, `sm:flex-row` preserves desktop |
+| New table columns | **Low** | grid-operators, power-plants | All `mobile: false` — desktop-only, zero mobile impact |
+| Changelog tabs + search | **Low** | Changelog page only | Default tab shows existing view; search is additive |
+| Sort ▲/▼ labels | **Low** | 5 data pages | Label text change only; no behavioral change |
+| CSS hyphens-auto | **Low** | 4 data pages | CSS-only; respects browser's hyphenation engine |
+
+```mermaid
+quadrantChart
+    title Change Risk vs Impact
+    x-axis Low Impact --> High Impact
+    y-axis Low Risk --> High Risk
+    TopBar height: [0.9, 0.8]
+    Logo redesign: [0.7, 0.65]
+    Map lifecycle: [0.6, 0.7]
+    Badge variants: [0.5, 0.5]
+    Filter stacking: [0.7, 0.35]
+    Zoom calc: [0.4, 0.55]
+    Changelog tabs+search: [0.8, 0.2]
+    New table columns: [0.75, 0.15]
+    Sort chevrons: [0.3, 0.1]
+    Dropdown padding: [0.2, 0.08]
+    CSS hyphens: [0.3, 0.12]
+    Page metadata: [0.1, 0.05]
+```
+
+## Deferred Work
+
+Items explicitly out of scope for this PR, to be addressed in follow-up work:
+
+- [ ] **Column hover panels with field enumeration** — requires `@floating-ui` popover work and computed stats (pie charts, mini maps). Tracked as Tier 3.
+- [ ] **@tanstack/react-table migration** — new dependency; should be its own PR with migration of all 5 pages.
+- [ ] **Explorer dual-panel layout** — requires extending `LayoutMode` type and ExplorerContext reducer.
+- [ ] **Power plant custom fuel-type SVG icons** — art asset creation; needs design review.
+- [ ] **Streaming changelog with auto-refresh** — needs `useSWR` or polling strategy decision.
+- [ ] **Recent searches in CMD+K (localStorage)** — deferred to avoid scope creep; edit spec available.
+
+## Test Plan
+
+### Automated
+- [ ] `next build` completes without errors
+- [ ] Biome lint passes (`npx biome check`)
+
+### Manual — Visual Regression
+- [ ] **320px viewport**: Filters stack vertically, names wrap, no horizontal overflow
+- [ ] **768px viewport**: DataTable switches to desktop mode, explorer hybrid layout works
+- [ ] **1440px viewport**: All new columns visible, header spacing proportional
+- [ ] **Dark mode**: Badge colors, logo, changelog tabs all render correctly
+- [ ] **Light mode**: Same verification
+
+### Manual — Functional
+- [ ] CMD+K opens search → section headers show counts → loading text appears for Tier-2
+- [ ] Grid-operators table: filter by jurisdiction → matching cells highlighted with brand color
+- [ ] Changelog: switch between Data Changes / Site Updates tabs → entity-type chips filter correctly → search narrows results
+- [ ] Explorer map: switch hybrid → list → map → hybrid → map doesn't blank
+- [ ] Service territory detail pages: map zooms to territory bounds (not US-wide)
+- [ ] All 5 data pages: sort dropdown shows ▲/▼ indicators
+
+## Reviewer Checklist
+
+- [ ] Changeset overview matches `git diff --stat main...welcome-pr`
+- [ ] Risk assessment reviewed and agreed — no items should be elevated to "high"
+- [ ] No secrets, credentials, or `.env` values committed
+- [ ] Responsive behavior verified at 320px, 768px, 1440px
+- [ ] Accessibility: focus order preserved, no contrast regressions
+- [ ] Badge color changes reviewed against segment semantics (IOU=info, Coop=success, Municipal=warning, CCA=neutral)
+- [ ] Logo mark reviewed for legibility at 24×24px
+
+## Screenshots / Recordings
+
+_Attach before/after screenshots at key breakpoints before merging._
+
+| Viewport | Before | After |
+|----------|--------|-------|
+| Mobile (375px) | | |
+| Tablet (768px) | | |
+| Desktop (1440px) | | |
+| Logo (24×24) | ![old](public/logo.svg) | ![new](public/logo.svg) |

From 5a0db8173e0adfc99d1070a4194d37affbb3ed42 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 14:44:15 -0400
Subject: [PATCH 25/41] docs: refine PR template and description with research
 findings

Incorporated best practices from Kubernetes (type classification,
release-note block), React (test-plan primacy), Conventional Commits
v1.0, Keep a Changelog v1.1, MADR, and CodeRabbit walkthrough format.

Template now has 3 tiers: [R]equired, [+]Recommended, [~]Optional.
Added: Change Type checklist, PR size classification, Changelog section
(Added/Changed/Fixed/Removed), ADR Context placeholder, release-note
block, multi-persona scanning guidance. All optional sections wrapped
in HTML comments for clean default rendering.
---
 .github/PULL_REQUEST_TEMPLATE.md | 252 +++++++++++++++++++-------
 PR_DESCRIPTION.md                | 300 +++++++++++++++++--------------
 2 files changed, 353 insertions(+), 199 deletions(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index e39303fe..f62306df 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,88 +1,193 @@
 <!--
   CommonGrid Pull Request Description Standard v1.0
   ──────────────────────────────────────────────────
-  This template defines the canonical PR description format for the CommonGrid project.
-  It is designed to be:
-    • Routinely producible — sections can be generated via `scripts/pr-describe.sh`
+  Informed by: Kubernetes PR template, React PR template, Rust RFC process,
+  Linux kernel cover-letter format, Conventional Commits v1.0, Keep a Changelog v1.1,
+  MADR (Markdown ADR), CodeRabbit walkthrough format, and Graphite stacked-PR patterns.
+
+  References:
+    https://www.conventionalcommits.org/en/v1.0.0/
+    https://keepachangelog.com/en/1.1.0/
+    https://adr.github.io/
+    https://github.com/kubernetes/kubernetes/blob/master/.github/PULL_REQUEST_TEMPLATE.md
+
+  Design principles:
+    • Routinely producible — sections map to `git diff`, `git log`, and linter output
     • Attestable — reviewers check boxes to confirm analysis was reviewed
     • Extensible — optional sections can be included/omitted per author discretion
-    • Machine-readable — structured tables and mermaid diagrams for tooling
+    • Machine-readable — structured tables, Mermaid diagrams, HTML comment hooks
+    • Multi-persona scannable — TL;DR for maintainers, detail for domain experts,
+      collapsible sections for new contributors
 
   USAGE:
-    Required sections:  Summary, Changeset Overview, Test Plan
-    Recommended:        Impact Analysis, Risk Assessment, Commit Table
-    Optional:           Architecture Diagrams, Responsive Audit, Deferred Work
-
-  Section markers use HTML comments for collapse/expand and tooling hooks.
+    Required sections:  Summary, Change Type, Changeset Overview, Test Plan
+    Recommended:        Commit Log, File Impact Matrix, Risk Assessment
+    Optional:           Architecture Diagrams, Responsive Audit, ADR Context,
+                        Deferred Work, Screenshots
+
+  PR TITLE FORMAT (Conventional Commits):
+    <type>(<scope>): <description>
+    e.g., feat(tables): add sort-direction chevrons and jurisdiction highlighting
+
+  SECTION TIERS:
+    [R] = Required — must be filled before review
+    [+] = Recommended — include unless trivially small PR
+    [~] = Optional — include when relevant to the change type
 -->
 
+<!-- ═══════════════════════════════════════════════════════════════════ -->
+<!-- [R] REQUIRED SECTIONS                                              -->
+<!-- ═══════════════════════════════════════════════════════════════════ -->
+
 ## Summary
-<!-- 1-3 sentences. What changed and why. Link related issues. -->
+<!-- [R] 1-3 sentences. What changed and why. This is the TL;DR. -->
+<!-- Reviewers should understand the PR from this section alone. -->
 
 
-## Motivation
-<!-- What problem does this solve? Who benefits? Link to issue/discussion if applicable. -->
+## Change Type
+<!-- [R] Check all that apply. Maps to Conventional Commit types. -->
 
+- [ ] `feat` — New feature or capability
+- [ ] `fix` — Bug fix
+- [ ] `style` — Visual/CSS changes (no logic change)
+- [ ] `refactor` — Code restructuring (no behavior change)
+- [ ] `docs` — Documentation only
+- [ ] `test` — Adding or modifying tests
+- [ ] `chore` — Build, CI, dependency, or tooling changes
+- [ ] `perf` — Performance improvement
+
+**User-facing change?** <!-- yes / no -->
+**Breaking change?** <!-- yes / no — if yes, describe in Motivation -->
 
 ## Changeset Overview
-<!-- Auto-generated or manually composed. Use `git diff --stat` as baseline. -->
+<!-- [R] Auto-generatable via: git diff --stat main...HEAD | tail -1 -->
 
 | Metric | Value |
 |--------|-------|
 | Commits | |
 | Files changed | |
-| Insertions | |
-| Deletions | |
+| Insertions (+) | |
+| Deletions (−) | |
 | Net | |
+| PR size | <!-- XS (<10) · S (10-100) · M (100-300) · L (300-500) · XL (500+) --> |
+
+## Test Plan
+<!-- [R] Most important section (per React PR template convention). -->
+<!-- How was this tested? What should reviewers verify? Be specific. -->
+
+### Automated
+- [ ] `next build` / `npm run build` completes without errors
+- [ ] Lint passes (e.g., `npx biome check`)
+
+### Manual
+- [ ] _Describe manual verification steps_
+
+<!-- ═══════════════════════════════════════════════════════════════════ -->
+<!-- [+] RECOMMENDED SECTIONS                                           -->
+<!-- ═══════════════════════════════════════════════════════════════════ -->
+
+## Motivation
+<!-- [+] What problem does this solve? Who benefits? -->
+<!-- Link to issue/discussion: Closes #, Fixes #, Relates to # -->
+<!-- For architectural changes, consider ADR Context section below. -->
+
 
 ## Commit Log
-<!-- Conventional Commit format. Classify by type/scope/magnitude. -->
+<!-- [+] Conventional Commit format. Classify by type/scope/magnitude. -->
 
 | Hash | Type | Scope | Description | Size | Risk |
 |------|------|-------|-------------|------|------|
 | | | | | | |
 
 <details>
-<summary><strong>Commit Classification Key</strong></summary>
+<summary><strong>Classification Key</strong></summary>
 
-- **Type**: `feat` | `fix` | `style` | `refactor` | `test` | `docs` | `chore`
-- **Size**: `S` (<20 lines) | `M` (20-80 lines) | `L` (>80 lines)
-- **Risk**: `low` (additive/isolated) | `medium` (cross-cutting/visual) | `high` (behavioral/breaking)
+- **Type**: `feat` · `fix` · `style` · `refactor` · `test` · `docs` · `chore` · `perf`
+- **Size**: `S` (<20 lines) · `M` (20-80 lines) · `L` (>80 lines)
+- **Risk**: `low` (additive/isolated) · `medium` (cross-cutting/visual) · `high` (behavioral/breaking)
+- Follows [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
 
 </details>
 
 ## File Impact Matrix
-<!-- Categorize each file by layer and change character. -->
+<!-- [+] Categorize each file by layer and change character. -->
 
-| File | Layer | +/- | Character |
+| File | Layer | +/− | Character |
 |------|-------|-----|-----------|
 | | | | |
 
 <details>
 <summary><strong>Layer & Character Key</strong></summary>
 
-- **Layer**: `page` | `component` | `lib` | `style` | `asset` | `config` | `type` | `test`
-- **Character**: _Major feature_ | _New columns/fields_ | _Style-only_ | _Bug fix_ | _Metadata_ | _Refactor_
+- **Layer**: `page` · `component` · `lib` · `style` · `asset` · `config` · `type` · `test`
+- **Character**: _Major feature_ · _New fields_ · _Style-only_ · _Bug fix_ · _Metadata_ · _Refactor_
 
 </details>
 
+## Risk Assessment
+<!-- [+] Classify changes by regression likelihood and blast radius. -->
+
+| Change | Risk | Blast Radius | Mitigation |
+|--------|------|-------------|------------|
+| | | | |
+
+<!-- Optional: Mermaid risk-impact quadrant chart -->
+<!--
+```mermaid
+quadrantChart
+    title Change Risk vs Impact
+    x-axis Low Impact --> High Impact
+    y-axis Low Risk --> High Risk
+```
+-->
+
+## Reviewer Checklist
+<!-- [+] Reviewers: check each box after confirming. -->
+
+- [ ] Changeset overview matches actual diff
+- [ ] Risk assessment reviewed — no items should be elevated
+- [ ] No secrets, credentials, or `.env` values committed
+- [ ] Responsive behavior verified at stated breakpoints
+- [ ] Accessibility: focus order, aria labels, contrast ratios preserved
+
+<!-- ═══════════════════════════════════════════════════════════════════ -->
+<!-- [~] OPTIONAL SECTIONS — include when relevant                      -->
+<!-- ═══════════════════════════════════════════════════════════════════ -->
+
+<!--
 ## Architecture & Dependency
-<!-- Mermaid diagram showing file dependencies and review ordering. -->
+[~] Mermaid diagram showing file dependencies and review ordering.
+Use https://mermaid.live to prototype. Keep diagrams simple — complex
+diagrams render poorly on GitHub.
 
 ```mermaid
 graph TD
-    %% Replace with actual dependency graph
-    A[foundation libs] --> B[components]
+    A[foundation] --> B[components]
     B --> C[pages]
 ```
+-->
 
-## Impact Analysis
+<!--
+## Changelog
+[~] Keep a Changelog categories. Use when PR includes user-facing changes.
+https://keepachangelog.com/en/1.1.0/
+
+### Added
+-
+
+### Changed
+-
 
-### Component Touch Map
-<!-- Which components were modified? Show render hierarchy. -->
+### Fixed
+-
+
+### Removed
+-
+-->
 
-### Responsive Breakpoint Audit
-<!-- What changed at each viewport threshold? -->
+<!--
+## Responsive Breakpoint Audit
+[~] For UI PRs. What changed at each viewport threshold?
 
 | Breakpoint | Changes |
 |------------|---------|
@@ -90,55 +195,72 @@ graph TD
 | `< md` (768px) | |
 | `≥ lg` (1024px) | |
 | All viewports | |
+-->
 
-### CSS / Tailwind Delta
-<!-- Notable class additions, removals, or replacements. -->
+<!--
+## CSS / Tailwind Delta
+[~] For style-heavy PRs. Notable class additions, removals, or replacements.
 
-## Risk Assessment
+<details>
+<summary>Classes Added</summary>
 
-### Regression Risk Matrix
-<!-- Classify changes by regression likelihood. -->
+| Class | Where | Purpose |
+|-------|-------|---------|
+| | | |
 
-| Change | Risk | Blast Radius | Mitigation |
-|--------|------|-------------|------------|
-| | | | |
+</details>
 
-```mermaid
-quadrantChart
-    title Change Risk vs Impact
-    x-axis Low Impact --> High Impact
-    y-axis Low Risk --> High Risk
-    %% Plot changes here
-```
+<details>
+<summary>Classes Replaced</summary>
 
-## Deferred Work
-<!-- What was explicitly out-of-scope? Link to follow-up issues. -->
+| Before | After | Where |
+|--------|-------|-------|
+| | | |
 
-- [ ] _Item_ — rationale for deferral
+</details>
+-->
 
-## Test Plan
-<!-- How was this tested? What should reviewers verify? -->
+<!--
+## ADR Context
+[~] For architectural decisions. Follows MADR format (https://github.com/adr/madr).
 
-- [ ] Visual regression check at 320px, 768px, 1440px viewports
-- [ ] Dark mode / light mode toggle
-- [ ] Navigation flow (all pages load, links resolve)
-- [ ] CMD+K search opens and returns results
-- [ ] Map loads and resizes on layout switch
+### Context
+What is the issue motivating this decision?
 
-## Reviewer Checklist
-<!-- Reviewers: check each box after confirming. -->
+### Decision
+What change are we making?
 
-- [ ] Changeset overview matches actual diff
-- [ ] Risk assessment reviewed and agreed
-- [ ] No secrets, credentials, or .env values committed
-- [ ] Responsive behavior verified at stated breakpoints
-- [ ] Accessibility: focus order, aria labels, contrast ratios
+### Consequences
+What becomes easier or harder as a result?
+
+### Alternatives Considered
+What other approaches were evaluated?
+-->
+
+<!--
+## Deferred Work
+[~] What was explicitly out-of-scope? Link to follow-up issues.
 
+- [ ] _Item_ — rationale for deferral
+-->
+
+<!--
 ## Screenshots / Recordings
-<!-- Before/after at key breakpoints. Attach or link. -->
+[~] Before/after at key breakpoints. Required for user-facing visual changes.
 
 | Viewport | Before | After |
 |----------|--------|-------|
 | Mobile (375px) | | |
 | Tablet (768px) | | |
 | Desktop (1440px) | | |
+-->
+
+<!--
+## Release Note
+[~] Kubernetes-style release note block for changelog generation.
+If this PR includes a user-facing change, write a concise summary.
+
+```release-note
+<summary of user-facing change, or "NONE" if not applicable>
+```
+-->
diff --git a/PR_DESCRIPTION.md b/PR_DESCRIPTION.md
index b81f4cd8..ff4998bb 100644
--- a/PR_DESCRIPTION.md
+++ b/PR_DESCRIPTION.md
@@ -2,11 +2,19 @@
 
 Comprehensive UX, responsive design, and data-density overhaul across the CommonGrid registry. 23 commits addressing dropdown styling, table field coverage, sort UX, badge consistency, header spacing, Mapbox stability, changelog usability, narrow-viewport responsiveness, CMD+K search polish, and a new logo mark — the "G-in-C" with dendritic tree-graph connections.
 
-## Motivation
+## Change Type
 
-CommonGrid's table pages, header, and explorer map had accumulated a set of fit-and-finish issues that individually were small but collectively degraded the experience — particularly on narrow viewports. This PR treats them as a cohesive surface area, applying consistent patterns (dropdown padding, filter stacking, sort indicators, hyphenation) across all 5 data pages, the explorer, and the changelog. The logo redesign gives CommonGrid a distinctive mark that communicates grid topology.
+- [x] `feat` — New feature or capability
+- [x] `fix` — Bug fix
+- [x] `style` — Visual/CSS changes (no logic change)
+- [ ] `refactor`
+- [ ] `docs`
+- [ ] `test`
+- [ ] `chore`
+- [ ] `perf`
 
-Addresses items from the [commongrid.info issue backlog](https://github.com/TextureHQ/commongrid/issues).
+**User-facing change?** Yes — visual changes across all pages, new table columns, changelog tabs, logo redesign
+**Breaking change?** No
 
 ## Changeset Overview
 
@@ -14,11 +22,52 @@ Addresses items from the [commongrid.info issue backlog](https://github.com/Text
 |--------|-------|
 | Commits | **23** |
 | Files changed | **25** |
-| Insertions | **+425** |
-| Deletions | **-179** |
+| Insertions (+) | **+425** |
+| Deletions (−) | **−179** |
 | Net | **+246** |
-| Commit types | 10 feat · 6 fix · 7 style |
-| Risk profile | 18 low · 5 medium · 0 high |
+| PR size | **L** (425 insertions) |
+
+| Breakdown | Count |
+|-----------|-------|
+| `feat` commits | 10 |
+| `fix` commits | 6 |
+| `style` commits | 7 |
+| Low risk | 18 |
+| Medium risk | 5 |
+| High risk | 0 |
+
+## Test Plan
+
+### Automated
+- [ ] `next build` completes without errors
+- [ ] `npx biome check` passes
+
+### Manual — Visual Regression
+- [ ] **320px viewport**: Filters stack vertically, names wrap to 2 lines, no horizontal overflow
+- [ ] **768px viewport**: DataTable switches to desktop mode, explorer hybrid layout works
+- [ ] **1440px viewport**: All new columns visible (EIA ID, BA Code, NERC, Website, County, Year, Generators), header spacing proportional
+- [ ] **Dark mode toggle**: Badge colors, logo mark, changelog tabs, filter chips all render correctly
+- [ ] **Light mode toggle**: Same verification
+
+### Manual — Functional
+- [ ] CMD+K opens search → section headers show entity counts → "Loading more..." appears during Tier-2 fetch
+- [ ] Grid-operators: filter by jurisdiction → matching cells highlighted with brand color + bold
+- [ ] Grid-operators: new columns (EIA ID, BA Code, NERC, Website link) visible on desktop, hidden on mobile
+- [ ] Changelog: switch Data Changes ↔ Site Updates tabs → entity-type filter chips narrow results → search bar filters by name/detail text
+- [ ] Explorer map: switch hybrid → list → map → hybrid without blank/flash
+- [ ] Service territory detail: map zooms to tight bounds, not US-wide
+- [ ] All 5 data pages: sort dropdown labels show ▲/▼ direction indicators
+- [ ] All data pages: native `<select>` chevrons have inner right padding (no text crowding)
+
+---
+
+## Motivation
+
+CommonGrid's table pages, header, and explorer map had accumulated fit-and-finish issues that individually were small but collectively degraded the experience — particularly at narrow viewports and on the grid-operators registry page. This PR treats them as a cohesive surface area, applying consistent patterns across all 5 data pages, the explorer, and the changelog.
+
+The logo redesign gives CommonGrid a distinctive mark — the letter G inscribed in C with dendritic tree-graph connections radiating outward — that communicates grid topology rather than a generic dot grid.
+
+Addresses items from the [commongrid.info issue backlog](https://github.com/TextureHQ/commongrid/issues).
 
 ## Commit Log
 
@@ -28,7 +77,7 @@ Addresses items from the [commongrid.info issue backlog](https://github.com/Text
 | `b7e25b2` | fix | globals.css + 4 pages | CSS hyphenation for long entity names | S | low |
 | `111ef3f` | fix | formatting.ts (×2) | Complete badge variant mapping for all utility segments | S | low |
 | `106f641` | style | TopBar, ShellLayout, GlobalSearch | Header spacing overhaul (h-14→h-12, tighter nav) | M | med |
-| `7c9de2f` | style | grid-operators | Conditional name clamping (line-clamp-2 / 1) | S | low |
+| `7c9de2f` | style | grid-operators | Conditional name clamping (line-clamp-2/1) | S | low |
 | `37b1abc` | feat | 5 data pages | Sort-direction ▲/▼ chevrons in dropdown labels | S | low |
 | `791740d` | feat | power-plants, transmission-lines | County, Year, Generators columns; From/To labels | M | low |
 | `ece78d0` | feat | grid-operators | Jurisdiction state-based highlighting on filter | S | low |
@@ -50,30 +99,30 @@ Addresses items from the [commongrid.info issue backlog](https://github.com/Text
 
 ## File Impact Matrix
 
-| File | Layer | +/- | Character |
+| File | Layer | +/− | Character |
 |------|-------|-----|-----------|
-| `app/(shell)/grid-operators/page.tsx` | page | +78 / -11 | Major: 4 new columns, highlighting, clamping, filters |
-| `app/(shell)/changelog/page.tsx` | page | +116 / -6 | Major: tab UI, search, entity filters |
-| `app/(shell)/power-plants/page.tsx` | page | +42 / -9 | New columns: county, year, generators |
-| `app/(shell)/ev-charging/page.tsx` | page | +12 / -12 | Style: padding, stacking, hyphenation |
-| `app/(shell)/pricing-nodes/page.tsx` | page | +9 / -9 | Style: padding, sort labels |
-| `app/(shell)/transmission-lines/page.tsx` | page | +10 / -10 | Style + From/To substation labels |
-| `app/(shell)/explore/page.tsx` | page | +6 / -0 | Metadata addition |
-| `components/TopBar.tsx` | component | +45 / -39 | Logo SVG, spacing, mobile menu |
-| `components/explorer/ExplorerMap.tsx` | component | +15 / -10 | ResizeObserver lifecycle fix |
-| `components/explorer/ExplorerShell.tsx` | component | +3 / -3 | key={layout} prop |
-| `components/GlobalSearch.tsx` | component | +6 / -2 | Result counts, loading text |
-| `components/ShellLayoutClient.tsx` | component | +1 / -1 | pt-14 → pt-12 |
-| `components/SearchInput.tsx` | component | +2 / -2 | Responsive height + hidden count |
-| `components/DataSourceLink.tsx` | component | +1 / -1 | Truncation class |
-| `components/explorer/ExplorerTabBar.tsx` | component | +1 / -1 | text-xs mobile labels |
-| `components/explorer/panels/*` (4 files) | component | +4 / -4 | Dropdown chevron padding |
-| `lib/formatting.ts` | lib | +9 / -9 | Badge variant remapping |
-| `explorer/lib/formatting.ts` | lib | +9 / -9 | Badge variant remapping (mirror) |
-| `lib/geo.ts` | lib | +8 / -5 | Zoom calculation refinement |
-| `app/globals.css` | style | +8 / -0 | hyphens-auto utility class |
-| `public/logo.svg` | asset | +20 / -18 | New G-in-C logo mark |
-| `public/favicon.svg` | asset | +20 / -18 | Favicon matches new logo |
+| `app/(shell)/grid-operators/page.tsx` | page | +78/−11 | Major: 4 columns, highlighting, clamping |
+| `app/(shell)/changelog/page.tsx` | page | +116/−6 | Major: tab UI, search, entity filters |
+| `app/(shell)/power-plants/page.tsx` | page | +42/−9 | New columns: county, year, generators |
+| `app/(shell)/ev-charging/page.tsx` | page | +12/−12 | Style: padding, stacking, hyphenation |
+| `app/(shell)/pricing-nodes/page.tsx` | page | +9/−9 | Style: padding, sort labels |
+| `app/(shell)/transmission-lines/page.tsx` | page | +10/−10 | Style + From/To label rename |
+| `app/(shell)/explore/page.tsx` | page | +6/−0 | Metadata |
+| `components/TopBar.tsx` | component | +45/−39 | Logo SVG, spacing, mobile menu |
+| `components/explorer/ExplorerMap.tsx` | component | +15/−10 | ResizeObserver lifecycle fix |
+| `components/explorer/ExplorerShell.tsx` | component | +3/−3 | key={layout} prop |
+| `components/GlobalSearch.tsx` | component | +6/−2 | Result counts, loading text |
+| `components/ShellLayoutClient.tsx` | component | +1/−1 | pt-14→pt-12 |
+| `components/SearchInput.tsx` | component | +2/−2 | Responsive height + hidden count |
+| `components/DataSourceLink.tsx` | component | +1/−1 | Truncation |
+| `components/explorer/ExplorerTabBar.tsx` | component | +1/−1 | text-xs mobile |
+| `components/explorer/panels/*` (×4) | component | +4/−4 | Dropdown chevron padding |
+| `lib/formatting.ts` | lib | +9/−9 | Badge variant remapping |
+| `explorer/lib/formatting.ts` | lib | +9/−9 | Badge variant remapping (mirror) |
+| `lib/geo.ts` | lib | +8/−5 | Zoom calculation refinement |
+| `app/globals.css` | style | +8/−0 | `hyphens-auto` utility class |
+| `public/logo.svg` | asset | +20/−18 | G-in-C logo mark |
+| `public/favicon.svg` | asset | +20/−18 | Favicon matches new logo |
 
 ## Architecture & Dependency
 
@@ -102,20 +151,20 @@ graph TD
         EM[ExplorerMap<br/><i>ResizeObserver</i>]
         ES[ExplorerShell<br/><i>key prop</i>]
         ETB[ExplorerTabBar<br/><i>text-xs</i>]
-        PANELS[Explorer Panels ×4<br/><i>chevron padding</i>]
+        PANELS[Panels ×4<br/><i>chevron padding</i>]
     end
 
     subgraph "5 · Shared"
-        SI[SearchInput<br/><i>responsive</i>]
-        DSL[DataSourceLink<br/><i>truncate</i>]
+        SI[SearchInput]
+        DSL[DataSourceLink]
     end
 
     subgraph "6 · Data Pages"
         GO[grid-operators<br/><i>7 commits</i>]
         PP[power-plants<br/><i>5 commits</i>]
-        TL[transmission-lines<br/><i>4 commits</i>]
-        EV[ev-charging<br/><i>4 commits</i>]
-        PN[pricing-nodes<br/><i>4 commits</i>]
+        TL[transmission-lines]
+        EV[ev-charging]
+        PN[pricing-nodes]
     end
 
     subgraph "7 · Feature Pages"
@@ -142,89 +191,88 @@ graph TD
     style CL fill:#e8f5e9,stroke:#2e7d32
 ```
 
-### Commit Clustering by File
+### Commit Clustering by Shared File
 
 ```mermaid
 graph LR
-    subgraph "grid-operators/page.tsx — 7 commits"
-        G1[3f89367 chevron]
-        G2[b7e25b2 hyphens]
-        G3[7c9de2f clamp]
-        G4[37b1abc sort ▲▼]
-        G5[049d059 stacking]
-        G6[ece78d0 highlight]
-        G7[ba4b06d fields]
+    subgraph "grid-operators — 7 commits"
+        G1[chevron] --> G2[hyphens] --> G3[clamp] --> G4[sort ▲▼] --> G5[stack] --> G6[highlight] --> G7[fields]
     end
 
-    subgraph "TopBar.tsx — 3 commits"
-        T1[106f641 spacing]
-        T2[ecdc89b logo]
-        T3[c206859 mobile]
+    subgraph "TopBar — 3 commits"
+        T1[spacing] --> T2[logo] --> T3[mobile]
     end
 
-    subgraph "changelog/page.tsx — 2 commits"
-        C1[ea227b5 tabs]
-        C2[7da3bdb search]
+    subgraph "changelog — 2 commits"
+        C1[tabs] --> C2[search]
     end
 ```
 
-## Impact Analysis
-
-### Component Touch Map
-
-```
-App (layout.tsx)
- └── ShellLayoutClient ............... [pt-14→pt-12]
-      ├── TopBar ..................... [h-12, gap-8, logo SVG, mobile menu]
-      │    └── inline SVG ........... [12-circle grid → G-in-C dendritic]
-      ├── GlobalSearchModal ......... [top-12, result counts, loading text]
-      └── <page routes>
-           ├── ChangelogPage ........ [tab bar, search, entity-type chips]
-           ├── GridOperatorsPage .... [4 columns, highlighting, clamping]
-           ├── PowerPlantsPage ...... [3 columns, hyphenation]
-           ├── TransmissionLinesPage  [From/To labels, sort ▲▼]
-           ├── EVChargingPage ....... [padding, stacking, hyphenation]
-           ├── PricingNodesPage ..... [padding, sort ▲▼]
-           └── ExplorePage .......... [metadata]
-                └── ExplorerShell ... [key={layout}]
-                     ├── ExplorerMap  [ResizeObserver, containerRef]
-                     ├── ExplorerTabBar [text-xs mobile]
-                     └── Panels ×4 .. [pl-2 pr-7]
-```
-
-### Responsive Breakpoint Audit
+## Changelog
+
+### Added
+- Sort-direction ▲/▼ indicators in all table sort dropdowns
+- Grid-operators table: EIA ID, BA Code, NERC Region, Website columns
+- Power-plants table: County, Operating Year, Generator Count columns
+- Transmission-lines table: From/To substation labels (renamed from Sub 1/Sub 2)
+- Changelog page: Data Changes / Site Updates tab bar
+- Changelog page: entity-type filter chips + text search
+- Changelog page: pulsing sync indicator
+- Jurisdiction highlighting when filter is active (brand color + bold)
+- CSS `hyphens-auto` utility class for browser word-breaking
+- Explore page: title and description metadata
+- CMD+K search: entity count badges on section headers
+- CMD+K search: "Loading more..." text for Tier-2 data
+
+### Changed
+- Logo: 12-circle grid → G-in-C with dendritic tree-graph connections
+- Favicon: updated to match new logo mark
+- Header: h-14 → h-12, tighter nav padding, larger logo-to-nav gap
+- Badge variants: Distribution Coop (warning→success), Municipal (success→warning), CCA (success→neutral), G&T (default→success), Transmission Operator (default→info), Joint Action (default→success)
+- Grid-operators name column: truncate → line-clamp-2 on mobile, line-clamp-1 on desktop
+- Mobile menu: added active brand color, hover backgrounds, border separator for GitHub link
+- Explorer tab labels: reduced to text-xs on mobile
+- Search input: h-11 → h-10 on mobile, result count hidden on narrow viewports
+- DataSourceLink: added truncation for narrow viewports
+
+### Fixed
+- Native `<select>` chevron crowding text — asymmetric padding (pl-2 pr-7) across 9 files
+- Mapbox component loads-then-blanks — ResizeObserver replaces fragile setTimeout
+- Map layout mode switch causing stale renders — key={layout} forces clean remount
+- Service territory zoom too wide — finer-grained zoom thresholds with intermediate steps
+- Filter dropdowns overflowing on narrow viewports — flex-col stacking below sm breakpoint
+
+## Responsive Breakpoint Audit
 
 | Breakpoint | Changes |
 |------------|---------|
-| **< sm** (640px) | Filters stack vertically · Search result count hidden · Search input h-10 + text-sm · Name wraps to 2 lines · Tab labels text-xs · Loading indicator text hidden |
-| **< md** (768px) | DataTable mobile mode (existing, unchanged) · Mobile menu gets active brand color + hover bg |
-| **≥ lg** (1024px) | TopBar horizontal padding increases (px-4 → lg:px-6) |
-| **All viewports** | Header h-14→h-12 · Nav padding tightened · Dropdown pr-7 for chevron · CSS hyphens-auto · Sort ▲/▼ labels · Badge variant colors |
-
-### CSS / Tailwind Delta
+| **< sm** (640px) | Filters stack vertically · Search result count hidden · Input h-10 + text-sm · Names wrap 2 lines · Tab labels text-xs · Loading text hidden |
+| **< md** (768px) | Mobile menu: brand color active state + hover bg (new) · DataTable mobile mode (existing) |
+| **≥ lg** (1024px) | TopBar px-4 → lg:px-6 |
+| **All viewports** | Header h-14→h-12 · Nav tightened · Select pr-7 · CSS hyphens · Sort ▲/▼ · Badge colors |
 
 <details>
-<summary><strong>Classes Added</strong></summary>
+<summary><strong>CSS / Tailwind Delta — Classes Added</strong></summary>
 
 | Class | Usage | Purpose |
 |-------|-------|---------|
 | `.hyphens-auto` (custom) | globals.css → 4 pages | Browser hyphenation for long names |
-| `line-clamp-2 sm:line-clamp-1` | grid-operators name column | Responsive line wrapping |
+| `line-clamp-2 sm:line-clamp-1` | grid-operators name | Responsive line wrapping |
 | `flex-col sm:flex-row` | All filter containers | Vertical stacking on mobile |
-| `pl-2 pr-7` | All `<select>` elements (9 files) | Asymmetric padding for native chevron |
-| `animate-pulse` | Changelog sync indicator | Live data visual cue |
-| `hidden sm:inline` | SearchInput count, GlobalSearch text | Hide on narrow |
+| `pl-2 pr-7` | All `<select>` (9 files) | Asymmetric padding for native chevron |
+| `animate-pulse` | Changelog sync dot | Live data visual cue |
+| `hidden sm:inline` | SearchInput count, GlobalSearch text | Narrow-viewport hide |
 | `hover:bg-background-surface` | Mobile menu items | Touch feedback |
 | `tabular-nums` | New numeric columns | Monospace digit alignment |
 
 </details>
 
 <details>
-<summary><strong>Classes Replaced</strong></summary>
+<summary><strong>CSS / Tailwind Delta — Classes Replaced</strong></summary>
 
 | Before | After | Where |
 |--------|-------|-------|
-| `h-14` | `h-12` | TopBar container |
+| `h-14` | `h-12` | TopBar, ShellLayoutClient, GlobalSearch |
 | `pt-14` | `pt-12` | ShellLayoutClient main offset |
 | `top-14` | `top-12` | GlobalSearch backdrop |
 | `px-5` | `px-4 lg:px-6` | TopBar horizontal padding |
@@ -233,7 +281,7 @@ App (layout.tsx)
 | `gap-1` | `gap-1.5` | TopBar icon groups |
 | `text-[15px]` | `text-sm` | TopBar brand text |
 | `px-2` | `pl-2 pr-7` | All filter `<select>` elements |
-| `truncate` | `line-clamp-2 sm:line-clamp-1` | Grid-operators name cell |
+| `truncate` | `line-clamp-2 sm:line-clamp-1 hyphens-auto` | Grid-operators name cell |
 
 </details>
 
@@ -241,16 +289,16 @@ App (layout.tsx)
 
 | Change | Risk | Blast Radius | Mitigation |
 |--------|------|-------------|------------|
-| TopBar h-14→h-12 + content offset | **Medium** | Every page (shell layout) | All 3 consumers updated: ShellLayoutClient, GlobalSearch backdrop, TopBar |
+| TopBar h-14→h-12 + content offset | **Medium** | Every page (shell layout) | All 3 consumers updated: ShellLayoutClient, GlobalSearch, TopBar |
 | Logo SVG replacement | **Medium** | Header + favicon | Same viewBox (32×32), same className, uses currentColor |
-| ExplorerMap ResizeObserver | **Medium** | Map explorer page | ResizeObserver has universal browser support; RAF prevents layout thrash |
-| Badge variant remapping | **Medium** | Grid-operators table + explorer panels | Both formatting.ts files updated in sync |
-| Zoom calculation refinement | **Medium** | Service territory map views | Only affects zoom level selection, not data; more granular = better |
-| Filter dropdown vertical stacking | **Low** | 5 data pages on mobile | Purely additive `flex-col` at default, `sm:flex-row` preserves desktop |
-| New table columns | **Low** | grid-operators, power-plants | All `mobile: false` — desktop-only, zero mobile impact |
+| ExplorerMap ResizeObserver | **Medium** | Map explorer page | Universal browser support; RAF prevents layout thrash |
+| Badge variant remapping | **Medium** | Grid-operators + explorer panels | Both formatting.ts files updated in sync |
+| Zoom calculation changes | **Medium** | Service territory map views | More granular = better; additive thresholds only |
+| Filter vertical stacking | **Low** | 5 data pages on mobile | Purely additive `flex-col` default; `sm:flex-row` preserves desktop |
+| New table columns | **Low** | grid-operators, power-plants | All `mobile: false` — zero mobile impact |
 | Changelog tabs + search | **Low** | Changelog page only | Default tab shows existing view; search is additive |
-| Sort ▲/▼ labels | **Low** | 5 data pages | Label text change only; no behavioral change |
-| CSS hyphens-auto | **Low** | 4 data pages | CSS-only; respects browser's hyphenation engine |
+| Sort ▲/▼ labels | **Low** | 5 data pages | Label text only; no behavioral change |
+| CSS hyphens-auto | **Low** | 4 data pages | CSS-only; browser hyphenation engine |
 
 ```mermaid
 quadrantChart
@@ -263,55 +311,30 @@ quadrantChart
     Badge variants: [0.5, 0.5]
     Filter stacking: [0.7, 0.35]
     Zoom calc: [0.4, 0.55]
-    Changelog tabs+search: [0.8, 0.2]
-    New table columns: [0.75, 0.15]
+    Changelog tabs: [0.8, 0.2]
+    New columns: [0.75, 0.15]
     Sort chevrons: [0.3, 0.1]
     Dropdown padding: [0.2, 0.08]
-    CSS hyphens: [0.3, 0.12]
-    Page metadata: [0.1, 0.05]
 ```
 
 ## Deferred Work
 
-Items explicitly out of scope for this PR, to be addressed in follow-up work:
-
-- [ ] **Column hover panels with field enumeration** — requires `@floating-ui` popover work and computed stats (pie charts, mini maps). Tracked as Tier 3.
-- [ ] **@tanstack/react-table migration** — new dependency; should be its own PR with migration of all 5 pages.
-- [ ] **Explorer dual-panel layout** — requires extending `LayoutMode` type and ExplorerContext reducer.
+- [ ] **Column hover panels with field enumeration / pie charts** — requires `@floating-ui` popover work. Tier 3.
+- [ ] **@tanstack/react-table migration** — new dependency; deserves its own PR.
+- [ ] **Explorer dual-panel layout** — requires `LayoutMode` type extension + reducer changes.
 - [ ] **Power plant custom fuel-type SVG icons** — art asset creation; needs design review.
 - [ ] **Streaming changelog with auto-refresh** — needs `useSWR` or polling strategy decision.
-- [ ] **Recent searches in CMD+K (localStorage)** — deferred to avoid scope creep; edit spec available.
-
-## Test Plan
-
-### Automated
-- [ ] `next build` completes without errors
-- [ ] Biome lint passes (`npx biome check`)
-
-### Manual — Visual Regression
-- [ ] **320px viewport**: Filters stack vertically, names wrap, no horizontal overflow
-- [ ] **768px viewport**: DataTable switches to desktop mode, explorer hybrid layout works
-- [ ] **1440px viewport**: All new columns visible, header spacing proportional
-- [ ] **Dark mode**: Badge colors, logo, changelog tabs all render correctly
-- [ ] **Light mode**: Same verification
-
-### Manual — Functional
-- [ ] CMD+K opens search → section headers show counts → loading text appears for Tier-2
-- [ ] Grid-operators table: filter by jurisdiction → matching cells highlighted with brand color
-- [ ] Changelog: switch between Data Changes / Site Updates tabs → entity-type chips filter correctly → search narrows results
-- [ ] Explorer map: switch hybrid → list → map → hybrid → map doesn't blank
-- [ ] Service territory detail pages: map zooms to territory bounds (not US-wide)
-- [ ] All 5 data pages: sort dropdown shows ▲/▼ indicators
+- [ ] **Recent searches in CMD+K (localStorage)** — edit spec available; deferred to limit scope.
 
 ## Reviewer Checklist
 
 - [ ] Changeset overview matches `git diff --stat main...welcome-pr`
-- [ ] Risk assessment reviewed and agreed — no items should be elevated to "high"
+- [ ] Risk assessment reviewed — no items should be elevated to "high"
 - [ ] No secrets, credentials, or `.env` values committed
 - [ ] Responsive behavior verified at 320px, 768px, 1440px
 - [ ] Accessibility: focus order preserved, no contrast regressions
 - [ ] Badge color changes reviewed against segment semantics (IOU=info, Coop=success, Municipal=warning, CCA=neutral)
-- [ ] Logo mark reviewed for legibility at 24×24px
+- [ ] Logo mark legible at 24×24px in both light and dark mode
 
 ## Screenshots / Recordings
 
@@ -322,4 +345,13 @@ _Attach before/after screenshots at key breakpoints before merging._
 | Mobile (375px) | | |
 | Tablet (768px) | | |
 | Desktop (1440px) | | |
-| Logo (24×24) | ![old](public/logo.svg) | ![new](public/logo.svg) |
+| Logo (24×24) | | |
+
+```release-note
+Redesigned CommonGrid logo to G-in-C dendritic mark. Added EIA ID, BA Code,
+NERC, and Website columns to grid-operators table. Added County, Year, and
+Generator Count to power-plants. Introduced Data Changes / Site Updates tabs
+and search on changelog. Sort dropdowns now show ▲/▼ direction. Fixed Mapbox
+blank-on-layout-switch, dropdown chevron padding, and badge color mapping.
+Improved responsive design at narrow viewports across all data pages.
+```

From 26224317bb74ca73916da16fb98c70dae83ab3cf Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 15:08:29 -0400
Subject: [PATCH 26/41] docs: visual regression capture system specification

Full architecture spec for automated before/after screenshot pipeline:
- Capture manifest schema for declaring routes, selectors, viewports
- Dual-server git worktree strategy for parallel base/PR capture
- Color-rationalized annotation system (red/green/blue/orange/yellow)
- Side-by-side composition engine with title/footer bars
- GitHub issue upload for permanent image hosting
- File-to-route mapping for auto-manifest generation
- GitHub Actions workflow integration
- CLI interface with selective capture support
---
 docs/visual-regression-system.md | 846 +++++++++++++++++++++++++++++++
 1 file changed, 846 insertions(+)
 create mode 100644 docs/visual-regression-system.md

diff --git a/docs/visual-regression-system.md b/docs/visual-regression-system.md
new file mode 100644
index 00000000..57020220
--- /dev/null
+++ b/docs/visual-regression-system.md
@@ -0,0 +1,846 @@
+# Visual Regression Capture System
+
+> Automated before/after screenshot generation for user-facing PR changes,
+> with annotated bounding boxes and combined comparison images.
+
+## 1. System Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                    VISUAL REGRESSION PIPELINE                       │
+│                                                                     │
+│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐      │
+│  │  DEFINE   │───▶│ CAPTURE  │───▶│ ANNOTATE │───▶│ COMPOSE  │──┐   │
+│  │  Targets  │    │  States  │    │  Regions │    │  Pairs   │  │   │
+│  └──────────┘    └──────────┘    └──────────┘    └──────────┘  │   │
+│                                                                 ▼   │
+│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐      │
+│  │  EMBED   │◀───│ UPLOAD   │◀───│ CATALOG  │◀───│ DIFF     │      │
+│  │  in PR   │    │  Images  │    │  Results │    │  Detect  │      │
+│  └──────────┘    └──────────┘    └──────────┘    └──────────┘      │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## 2. Architecture
+
+```mermaid
+graph TD
+    subgraph "1 · Target Definition"
+        MANIFEST[capture-manifest.json<br/><i>routes, selectors, viewports,<br/>annotation regions, colors</i>]
+        COMMITS[git log analysis<br/><i>map commits → files → routes</i>]
+        COMMITS --> MANIFEST
+    end
+
+    subgraph "2 · Dual-State Capture"
+        BASE_CO[git stash / worktree<br/>checkout base branch]
+        BASE_DEV[start dev server<br/>on port 3100]
+        BASE_SNAP[Playwright captures<br/>base-state screenshots]
+
+        PR_CO[restore PR branch]
+        PR_DEV[start dev server<br/>on port 3101]
+        PR_SNAP[Playwright captures<br/>PR-state screenshots]
+
+        BASE_CO --> BASE_DEV --> BASE_SNAP
+        PR_CO --> PR_DEV --> PR_SNAP
+    end
+
+    subgraph "3 · Annotation Engine"
+        BBOX[draw bounding boxes<br/><i>sharp / node-canvas</i>]
+        LABEL[add text labels<br/><i>BEFORE / AFTER</i>]
+        COLOR[color rationalization<br/><i>red=removed, green=added,<br/>blue=changed, orange=moved</i>]
+        BBOX --> LABEL --> COLOR
+    end
+
+    subgraph "4 · Composition"
+        SIDE[side-by-side merge<br/><i>BEFORE │ AFTER</i>]
+        HEADER[add title bar<br/><i>commit scope + viewport</i>]
+        SIDE --> HEADER
+    end
+
+    subgraph "5 · Upload & Embed"
+        UPLOAD[upload to host<br/><i>GitHub / R2 / S3</i>]
+        TABLE[generate markdown table<br/><i>viewport × change</i>]
+        PR[inject into PR description<br/><i>or post as comment</i>]
+        UPLOAD --> TABLE --> PR
+    end
+
+    MANIFEST --> BASE_CO & PR_CO
+    BASE_SNAP --> BBOX
+    PR_SNAP --> BBOX
+    COLOR --> SIDE
+    HEADER --> UPLOAD
+
+    style MANIFEST fill:#e1f5fe,stroke:#0277bd
+    style BBOX fill:#fff3e0,stroke:#ef6c00
+    style SIDE fill:#e8f5e9,stroke:#2e7d32
+    style UPLOAD fill:#f3e5f5,stroke:#7b1fa2
+```
+
+## 3. Capture Manifest Schema
+
+The manifest declares what to screenshot, where to annotate, and how to color-code.
+It can be auto-generated from git diff analysis or hand-authored per commit.
+
+```jsonc
+// scripts/visual-regression/capture-manifest.json
+{
+  "$schema": "./capture-manifest.schema.json",
+  "version": "1.0",
+  "baseRef": "main",
+  "prRef": "HEAD",
+  "devServerPort": {
+    "base": 3100,
+    "pr": 3101
+  },
+  "viewports": [
+    { "name": "mobile",  "width": 375,  "height": 812 },
+    { "name": "tablet",  "width": 768,  "height": 1024 },
+    { "name": "desktop", "width": 1440, "height": 900 }
+  ],
+  "captures": [
+    {
+      "id": "dropdown-chevron-padding",
+      "commit": "3f89367",
+      "route": "/grid-operators",
+      "description": "Inner right-side padding on filter dropdowns",
+      "waitFor": "table >> tr >> td",
+      "regions": [
+        {
+          "selector": "select:first-of-type",
+          "annotation": {
+            "color": "blue",
+            "label": "Chevron padding"
+          }
+        }
+      ]
+    },
+    {
+      "id": "header-spacing",
+      "commit": "106f641",
+      "route": "/grid-operators",
+      "description": "Header height h-14 → h-12",
+      "regions": [
+        {
+          "selector": "header",
+          "annotation": {
+            "color": "blue",
+            "label": "h-14 → h-12"
+          }
+        }
+      ]
+    },
+    {
+      "id": "badge-variants",
+      "commit": "111ef3f",
+      "route": "/grid-operators?segment=DISTRIBUTION_COOPERATIVE",
+      "description": "Badge color mapping fix",
+      "waitFor": "[data-testid='data-table'] >> tr:nth-child(2)",
+      "regions": [
+        {
+          "selector": "span:has-text('Distribution Co-op')",
+          "annotation": {
+            "color": "orange",
+            "label": "warning → success"
+          }
+        }
+      ]
+    },
+    {
+      "id": "logo-redesign",
+      "commit": "ecdc89b",
+      "route": "/",
+      "description": "G-in-C dendritic graph logo",
+      "regions": [
+        {
+          "selector": "header a[href='/'] svg",
+          "annotation": {
+            "color": "green",
+            "label": "New logo mark"
+          }
+        }
+      ]
+    },
+    {
+      "id": "changelog-tabs",
+      "commit": "ea227b5",
+      "route": "/changelog",
+      "description": "Data Changes / Site Updates tab distinction",
+      "regions": [
+        {
+          "selector": "button:has-text('Data Changes')",
+          "annotation": {
+            "color": "green",
+            "label": "New tab bar"
+          }
+        }
+      ]
+    },
+    {
+      "id": "sort-chevrons",
+      "commit": "37b1abc",
+      "route": "/grid-operators",
+      "description": "Sort direction ▲/▼ in dropdown labels",
+      "actions": [
+        { "type": "click", "selector": "[data-testid='sort-select']" }
+      ],
+      "regions": [
+        {
+          "selector": "[data-testid='sort-select']",
+          "annotation": {
+            "color": "blue",
+            "label": "▲/▼ indicators"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+## 4. Color Rationalization System
+
+Annotation box colors communicate the _nature_ of the visual change:
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│                    ANNOTATION COLOR KEY                        │
+│                                                                │
+│  ┌─────────┐                                                   │
+│  │  RED    │  Removed — element/style that existed is gone     │
+│  │ #EF4444 │  e.g., a column was deleted, a section removed    │
+│  └─────────┘                                                   │
+│  ┌─────────┐                                                   │
+│  │  GREEN  │  Added — new element that didn't exist before     │
+│  │ #22C55E │  e.g., new table column, new tab bar, new logo    │
+│  └─────────┘                                                   │
+│  ┌─────────┐                                                   │
+│  │  BLUE   │  Modified — existing element changed in-place     │
+│  │ #3B82F6 │  e.g., spacing adjusted, text changed, resized    │
+│  └─────────┘                                                   │
+│  ┌─────────┐                                                   │
+│  │ ORANGE  │  Recolored/Remapped — visual property changed     │
+│  │ #F97316 │  e.g., badge color variant, theme token swap      │
+│  └─────────┘                                                   │
+│  ┌─────────┐                                                   │
+│  │ YELLOW  │  Moved/Reflowed — same content, different place   │
+│  │ #EAB308 │  e.g., responsive stacking, layout reorder        │
+│  └─────────┘                                                   │
+│                                                                │
+│  BEFORE images use: red, blue, orange, yellow                  │
+│  AFTER images use:  green, blue, orange, yellow                │
+│                                                                │
+│  Rule: red on BEFORE pairs with green on AFTER for             │
+│        add/remove changes. blue/orange/yellow are symmetric.   │
+└────────────────────────────────────────────────────────────────┘
+```
+
+```mermaid
+graph LR
+    subgraph "BEFORE annotation"
+        R[RED — will be removed]
+        B1[BLUE — will change]
+        O1[ORANGE — will recolor]
+        Y1[YELLOW — will move]
+    end
+
+    subgraph "AFTER annotation"
+        G[GREEN — was added]
+        B2[BLUE — was changed]
+        O2[ORANGE — was recolored]
+        Y2[YELLOW — was moved]
+    end
+
+    R -.->|"removed"| G
+    B1 -->|"modified"| B2
+    O1 -->|"recolored"| O2
+    Y1 -->|"reflowed"| Y2
+
+    style R fill:#fecaca,stroke:#ef4444
+    style G fill:#bbf7d0,stroke:#22c55e
+    style B1 fill:#bfdbfe,stroke:#3b82f6
+    style B2 fill:#bfdbfe,stroke:#3b82f6
+    style O1 fill:#fed7aa,stroke:#f97316
+    style O2 fill:#fed7aa,stroke:#f97316
+    style Y1 fill:#fef08a,stroke:#eab308
+    style Y2 fill:#fef08a,stroke:#eab308
+```
+
+## 5. Pipeline Execution Flow
+
+### 5.1 Dual-Server Git State Isolation
+
+The key challenge: we need the dev server running on **both** the base and PR states
+simultaneously (or sequentially) to capture screenshots against each.
+
+**Strategy A: Sequential (simpler, slower)**
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  SEQUENTIAL CAPTURE                                     │
+│                                                         │
+│  1. git stash (save PR work)                            │
+│  2. git checkout main                                   │
+│  3. npm install (if deps changed)                       │
+│  4. next dev --port 3100 &                              │
+│  5. wait-on http://localhost:3100                        │
+│  6. playwright: capture all BEFORE screenshots          │
+│  7. kill dev server                                     │
+│  8. git checkout - (back to PR branch)                  │
+│  9. git stash pop                                       │
+│  10. npm install (if deps changed)                      │
+│  11. next dev --port 3100 &                             │
+│  12. wait-on http://localhost:3100                       │
+│  13. playwright: capture all AFTER screenshots          │
+│  14. kill dev server                                    │
+│  15. annotate + compose + upload                        │
+│                                                         │
+│  ⏱  ~3-5 min total (2 cold starts)                     │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Strategy B: Parallel via git worktree (faster, recommended)**
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  PARALLEL CAPTURE VIA WORKTREE                          │
+│                                                         │
+│  1. git worktree add /tmp/cg-base main                  │
+│  2. cd /tmp/cg-base && npm install && next dev -p 3100 &│
+│  3. cd (original) && next dev -p 3101 &                 │
+│  4. wait-on http://localhost:3100                        │
+│  5. wait-on http://localhost:3101                        │
+│  6. playwright captures BOTH in parallel:               │
+│     ├── port 3100 → BEFORE screenshots                  │
+│     └── port 3101 → AFTER screenshots                   │
+│  7. kill both servers                                   │
+│  8. git worktree remove /tmp/cg-base                    │
+│  9. annotate + compose + upload                         │
+│                                                         │
+│  ⏱  ~2-3 min total (parallel capture)                  │
+└─────────────────────────────────────────────────────────┘
+```
+
+```mermaid
+sequenceDiagram
+    participant CLI as capture-vr.ts
+    participant GIT as git
+    participant BASE as Base Server :3100
+    participant PR as PR Server :3101
+    participant PW as Playwright
+    participant IMG as Image Engine
+    participant HOST as Upload Host
+
+    CLI->>GIT: worktree add /tmp/cg-base main
+    CLI->>BASE: npm install && next dev -p 3100
+    CLI->>PR: next dev -p 3101
+    CLI->>CLI: wait-on both ports
+
+    par Parallel Capture
+        CLI->>PW: capture(manifest, port=3100, label="BEFORE")
+        PW->>BASE: navigate to each route
+        PW-->>CLI: before/*.png
+
+        CLI->>PW: capture(manifest, port=3101, label="AFTER")
+        PW->>PR: navigate to each route
+        PW-->>CLI: after/*.png
+    end
+
+    CLI->>BASE: kill
+    CLI->>GIT: worktree remove
+
+    loop Each capture in manifest
+        CLI->>IMG: annotate(before.png, regions, "before" colors)
+        IMG-->>CLI: before-annotated.png
+        CLI->>IMG: annotate(after.png, regions, "after" colors)
+        IMG-->>CLI: after-annotated.png
+        CLI->>IMG: compose(before-annotated, after-annotated, title)
+        IMG-->>CLI: comparison.png
+    end
+
+    CLI->>HOST: upload all comparison images
+    HOST-->>CLI: image URLs
+    CLI->>CLI: generate markdown table
+    CLI-->>CLI: pr-screenshots.md
+```
+
+### 5.2 Playwright Capture Script
+
+```
+scripts/visual-regression/
+├── capture-manifest.json      # What to capture (the spec)
+├── capture-vr.ts              # Main orchestrator
+├── playwright-capture.ts      # Playwright screenshot logic
+├── annotate.ts                # Bounding box / label drawing
+├── compose.ts                 # Side-by-side composition
+├── upload.ts                  # Image hosting upload
+└── generate-pr-table.ts       # Markdown table generator
+```
+
+**Core capture logic (pseudocode):**
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  playwright-capture.ts                                  │
+│                                                         │
+│  for each capture in manifest.captures:                 │
+│    for each viewport in manifest.viewports:             │
+│      1. browser.newPage()                               │
+│      2. page.setViewportSize(viewport)                  │
+│      3. page.goto(baseUrl + capture.route)              │
+│      4. if capture.waitFor:                             │
+│           page.waitForSelector(capture.waitFor)         │
+│      5. if capture.actions:                             │
+│           for action in capture.actions:                │
+│             page[action.type](action.selector)          │
+│      6. page.screenshot({ path, fullPage: false })      │
+│      7. for each region in capture.regions:             │
+│           element = page.locator(region.selector)       │
+│           bbox = element.boundingBox()                  │
+│           store bbox coordinates for annotation         │
+│      8. close page                                      │
+│                                                         │
+│  Output: screenshots/ directory with:                   │
+│    {captureId}-{viewport}-{state}.png                   │
+│    {captureId}-{viewport}-{state}.regions.json          │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 5.3 Annotation Engine
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  annotate.ts                                            │
+│                                                         │
+│  Input:  screenshot.png + regions.json                  │
+│  Output: screenshot-annotated.png                       │
+│                                                         │
+│  Using: sharp (fast, no native deps) or node-canvas     │
+│                                                         │
+│  for each region:                                       │
+│    1. Parse bbox {x, y, width, height}                  │
+│    2. Expand by 4px padding                             │
+│    3. Draw rectangle stroke:                            │
+│       - strokeWidth: 3px                                │
+│       - color: region.annotation.color (from key)       │
+│       - cornerRadius: 4px                               │
+│       - opacity: 0.9                                    │
+│    4. Draw label pill above top-left corner:            │
+│       - background: same color, opacity 0.85            │
+│       - text: region.annotation.label                   │
+│       - font: 11px, bold, white                         │
+│       - padding: 4px 8px                                │
+│    5. Composite onto source image                       │
+│                                                         │
+│  Visual result:                                         │
+│                                                         │
+│    ┌─ Chevron padding ─┐                                │
+│    │┌──────────────────┐│                                │
+│    ││  [All Segments ▼]││ ◄── 3px blue border           │
+│    │└──────────────────┘│                                │
+│    └────────────────────┘                                │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 5.4 Composition Engine
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  compose.ts                                             │
+│                                                         │
+│  Input:  before-annotated.png, after-annotated.png      │
+│  Output: comparison-{id}-{viewport}.png                 │
+│                                                         │
+│  Layout:                                                │
+│  ┌──────────────────────────────────────────────────┐   │
+│  │  ░░░░░░░░░░░░░░░░ TITLE BAR ░░░░░░░░░░░░░░░░░░░│   │
+│  │  "Dropdown Chevron Padding · mobile (375px)"     │   │
+│  │  commit: 3f89367                                 │   │
+│  ├────────────────────┬─────────────────────────────┤   │
+│  │                    │                             │   │
+│  │     B E F O R E    │      A F T E R              │   │
+│  │                    │                             │   │
+│  │  ┌──────────────┐  │  ┌──────────────┐           │   │
+│  │  │ [Segments ▼] │  │  │ [Segments ▼] │           │   │
+│  │  └──────────────┘  │  └──────────────┘           │   │
+│  │   ▲ blue box       │   ▲ blue box                │   │
+│  │                    │                             │   │
+│  ├────────────────────┴─────────────────────────────┤   │
+│  │  ░░ FOOTER: "BEFORE (main) │ AFTER (welcome-pr)" ░░│   │
+│  └──────────────────────────────────────────────────┘   │
+│                                                         │
+│  Dimensions:                                            │
+│    width  = before.width + after.width + divider(2px)   │
+│    height = max(before, after) + title(48px) + foot(28) │
+│                                                         │
+│  If images differ in height:                            │
+│    pad shorter one with background color at bottom      │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+## 6. Image Hosting Strategy
+
+```mermaid
+graph TD
+    subgraph "Option A: GitHub Issue Upload (recommended)"
+        A1[Create draft issue or<br/>use existing bot issue]
+        A2[POST image via<br/>GitHub GraphQL API]
+        A3[Get user-content URL<br/><i>https://github.com/user-<br/>attachments/assets/UUID</i>]
+        A4[URL is permanent<br/>even if issue is deleted]
+        A1 --> A2 --> A3 --> A4
+    end
+
+    subgraph "Option B: Git LFS in repo"
+        B1[Store in<br/>docs/screenshots/]
+        B2[Track with git-lfs]
+        B3[Reference via<br/>relative path]
+        B1 --> B2 --> B3
+    end
+
+    subgraph "Option C: Cloud bucket"
+        C1[Upload to<br/>R2 / S3 / GCS]
+        C2[Public URL with<br/>content-hash filename]
+        C3[Long-lived, CDN-backed]
+        C1 --> C2 --> C3
+    end
+
+    subgraph "Option D: GitHub Actions Artifact"
+        D1[Upload as<br/>workflow artifact]
+        D2[90-day retention<br/>by default]
+        D3[Not embeddable<br/>in markdown ✗]
+        D1 --> D2 --> D3
+    end
+
+    style A4 fill:#e8f5e9,stroke:#2e7d32
+    style D3 fill:#ffebee,stroke:#c62828
+```
+
+### Recommendation
+
+**Option A (GitHub Issue Upload)** is the best fit because:
+
+1. **Permanent URLs** — `github.com/user-attachments/assets/*` URLs persist indefinitely
+2. **No infrastructure** — no bucket to manage, no LFS quota
+3. **Automatable** — `gh api` or GraphQL mutation can upload programmatically
+4. **Embeddable** — standard markdown image syntax works in PR descriptions
+5. **Free** — included in GitHub's storage
+
+**Workflow:**
+
+```
+┌──────────────────────────────────────────────────┐
+│  Upload via GitHub API                           │
+│                                                  │
+│  1. Create (or reuse) a "Visual Regression Bot"  │
+│     issue in the repo                            │
+│                                                  │
+│  2. For each comparison image:                   │
+│     curl -X POST \                               │
+│       -H "Authorization: token $GITHUB_TOKEN" \  │
+│       -F "file=@comparison.png" \                │
+│       https://uploads.github.com/repos/          │
+│         TextureHQ/commongrid/issues/             │
+│         {issue}/comments                         │
+│                                                  │
+│  3. Parse response for asset URL                 │
+│                                                  │
+│  4. Delete the comment (URL survives)            │
+│     or keep for audit trail                      │
+│                                                  │
+│  Alternative: use gh CLI                         │
+│     gh issue comment {N} --body '![](file)'      │
+│                                                  │
+└──────────────────────────────────────────────────┘
+```
+
+## 7. End-to-End Workflow
+
+```mermaid
+flowchart TD
+    START([PR opened or<br/>manual trigger]) --> PARSE
+
+    subgraph "Phase 1: Analyze"
+        PARSE[Parse git diff<br/>main...HEAD]
+        ROUTE[Map changed files<br/>→ affected routes]
+        GEN[Generate or load<br/>capture-manifest.json]
+        PARSE --> ROUTE --> GEN
+    end
+
+    subgraph "Phase 2: Capture"
+        WORK[git worktree add<br/>/tmp/cg-base main]
+        BASE_S[Start base server<br/>:3100]
+        PR_S[Start PR server<br/>:3101]
+        CAP_B[Playwright captures<br/>BEFORE screenshots]
+        CAP_A[Playwright captures<br/>AFTER screenshots]
+        BBOX_B[Record bounding<br/>box coordinates]
+        BBOX_A[Record bounding<br/>box coordinates]
+
+        WORK --> BASE_S & PR_S
+        BASE_S --> CAP_B --> BBOX_B
+        PR_S --> CAP_A --> BBOX_A
+    end
+
+    subgraph "Phase 3: Process"
+        ANN_B[Annotate BEFORE<br/>red/blue/orange/yellow]
+        ANN_A[Annotate AFTER<br/>green/blue/orange/yellow]
+        COMP[Compose side-by-side<br/>with title + footer]
+        DIFF[pixelmatch diff<br/>detection]
+
+        BBOX_B --> ANN_B
+        BBOX_A --> ANN_A
+        ANN_B --> COMP
+        ANN_A --> COMP
+        ANN_B --> DIFF
+        ANN_A --> DIFF
+    end
+
+    subgraph "Phase 4: Publish"
+        UPLOAD_IMG[Upload to<br/>GitHub issue assets]
+        MD_TABLE[Generate markdown<br/>comparison table]
+        PR_COMMENT[Post as PR comment<br/>or update description]
+        CATALOG[Write catalog.json<br/>for future reference]
+
+        COMP --> UPLOAD_IMG --> MD_TABLE --> PR_COMMENT
+        DIFF --> CATALOG
+    end
+
+    GEN --> WORK
+
+    CLEANUP[Kill servers<br/>Remove worktree] --> DONE([Done])
+    PR_COMMENT --> CLEANUP
+
+    style START fill:#e1f5fe
+    style DONE fill:#e8f5e9
+    style COMP fill:#fff3e0
+    style UPLOAD_IMG fill:#f3e5f5
+```
+
+## 8. Output Artifacts
+
+### 8.1 Directory Structure
+
+```
+.visual-regression/
+├── captures/
+│   ├── before/
+│   │   ├── dropdown-chevron-padding-mobile.png
+│   │   ├── dropdown-chevron-padding-mobile.regions.json
+│   │   ├── dropdown-chevron-padding-tablet.png
+│   │   ├── header-spacing-mobile.png
+│   │   └── ...
+│   ├── after/
+│   │   ├── dropdown-chevron-padding-mobile.png
+│   │   ├── dropdown-chevron-padding-mobile.regions.json
+│   │   └── ...
+│   ├── annotated/
+│   │   ├── dropdown-chevron-padding-mobile-before.png
+│   │   ├── dropdown-chevron-padding-mobile-after.png
+│   │   └── ...
+│   └── comparisons/
+│       ├── dropdown-chevron-padding-mobile.png     ◄── final output
+│       ├── dropdown-chevron-padding-tablet.png
+│       ├── header-spacing-desktop.png
+│       └── ...
+├── catalog.json                                     ◄── index of all captures
+└── pr-screenshots.md                                ◄── markdown embed table
+```
+
+### 8.2 Generated Markdown Table
+
+```markdown
+## Visual Regression Report
+
+| Change | Mobile (375px) | Tablet (768px) | Desktop (1440px) |
+|--------|---------------|----------------|-----------------|
+| Dropdown chevron padding | ![](url) | ![](url) | ![](url) |
+| Header spacing h-14→h-12 | ![](url) | ![](url) | ![](url) |
+| Badge variant colors | — | — | ![](url) |
+| Logo redesign | ![](url) | — | ![](url) |
+| Changelog tabs | — | ![](url) | ![](url) |
+| Filter stacking | ![](url) | — | — |
+| Name clamping | ![](url) | — | — |
+
+<details>
+<summary>Diff detection summary</summary>
+
+| Capture | Viewport | Pixel diff % | Status |
+|---------|----------|-------------|--------|
+| dropdown-chevron-padding | mobile | 2.3% | Changed |
+| dropdown-chevron-padding | tablet | 1.8% | Changed |
+| header-spacing | desktop | 4.1% | Changed |
+| badge-variants | desktop | 3.7% | Changed |
+| logo-redesign | mobile | 12.4% | Changed |
+| changelog-tabs | tablet | 18.2% | New UI |
+
+</details>
+```
+
+### 8.3 Catalog JSON
+
+```jsonc
+// .visual-regression/catalog.json
+{
+  "generatedAt": "2026-03-16T18:30:00Z",
+  "baseRef": "main",
+  "prRef": "welcome-pr",
+  "prNumber": null,
+  "comparisons": [
+    {
+      "id": "dropdown-chevron-padding",
+      "commit": "3f89367",
+      "description": "Inner right-side padding on filter dropdowns",
+      "viewports": {
+        "mobile": {
+          "before": "captures/before/dropdown-chevron-padding-mobile.png",
+          "after": "captures/after/dropdown-chevron-padding-mobile.png",
+          "comparison": "captures/comparisons/dropdown-chevron-padding-mobile.png",
+          "uploadUrl": "https://github.com/user-attachments/assets/...",
+          "pixelDiffPercent": 2.3
+        }
+      }
+    }
+  ]
+}
+```
+
+## 9. CLI Interface
+
+```
+Usage:
+  npx tsx scripts/visual-regression/capture-vr.ts [options]
+
+Options:
+  --manifest <path>    Path to capture manifest (default: auto-detect)
+  --base-ref <ref>     Base git ref to compare against (default: main)
+  --viewports <list>   Comma-separated viewport names (default: all)
+  --captures <list>    Comma-separated capture IDs (default: all)
+  --skip-capture       Skip capture, re-annotate/compose from existing
+  --skip-upload        Skip upload, just generate local files
+  --upload-method      github | r2 | s3 | local (default: github)
+  --output-dir <path>  Output directory (default: .visual-regression)
+  --parallel           Use git worktree for parallel capture (default)
+  --sequential         Use sequential checkout instead of worktree
+
+Examples:
+  # Full pipeline
+  npx tsx scripts/visual-regression/capture-vr.ts
+
+  # Just one capture at mobile
+  npx tsx scripts/visual-regression/capture-vr.ts \
+    --captures dropdown-chevron-padding --viewports mobile
+
+  # Re-compose from existing screenshots (no server needed)
+  npx tsx scripts/visual-regression/capture-vr.ts --skip-capture
+
+  # Generate manifest from git diff
+  npx tsx scripts/visual-regression/generate-manifest.ts
+```
+
+## 10. Integration Points
+
+### 10.1 GitHub Actions Workflow
+
+```yaml
+# .github/workflows/visual-regression.yml
+name: Visual Regression
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  capture:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history for worktree
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - run: npm ci
+      - run: npx playwright install chromium
+
+      - name: Capture visual regression
+        run: npx tsx scripts/visual-regression/capture-vr.ts
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Post comparison images
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const table = fs.readFileSync('.visual-regression/pr-screenshots.md', 'utf8');
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: table,
+            });
+```
+
+### 10.2 PR Template Integration
+
+The generated `pr-screenshots.md` can be spliced into the Screenshots section
+of `PR_DESCRIPTION.md` during the upload phase, or posted as a separate PR comment
+that auto-updates on each push.
+
+### 10.3 Manual Trigger
+
+```bash
+# From repo root, with PR branch checked out:
+npm run vr:capture
+
+# Add to package.json scripts:
+# "vr:capture": "tsx scripts/visual-regression/capture-vr.ts",
+# "vr:manifest": "tsx scripts/visual-regression/generate-manifest.ts"
+```
+
+## 11. File-to-Route Mapping
+
+For auto-generating the manifest from `git diff`, the system needs to know
+which files affect which routes:
+
+```jsonc
+// scripts/visual-regression/file-route-map.json
+{
+  "app/(shell)/grid-operators/page.tsx": ["/grid-operators"],
+  "app/(shell)/power-plants/page.tsx": ["/power-plants"],
+  "app/(shell)/transmission-lines/page.tsx": ["/transmission-lines"],
+  "app/(shell)/ev-charging/page.tsx": ["/ev-charging"],
+  "app/(shell)/pricing-nodes/page.tsx": ["/pricing-nodes"],
+  "app/(shell)/changelog/page.tsx": ["/changelog"],
+  "app/(shell)/explore/page.tsx": ["/explore"],
+  "app/(shell)/about/page.tsx": ["/about"],
+  "app/(shell)/page.tsx": ["/"],
+  "components/TopBar.tsx": ["*"],
+  "components/ShellLayoutClient.tsx": ["*"],
+  "components/GlobalSearch.tsx": ["*"],
+  "components/SearchInput.tsx": ["/grid-operators", "/power-plants", "/transmission-lines", "/ev-charging", "/pricing-nodes"],
+  "components/DataSourceLink.tsx": ["/grid-operators", "/power-plants", "/transmission-lines", "/ev-charging", "/pricing-nodes"],
+  "components/explorer/*": ["/explore"],
+  "lib/formatting.ts": ["/grid-operators", "/explore"],
+  "lib/geo.ts": ["/explore", "/grid-operators/*"],
+  "app/globals.css": ["*"],
+  "public/logo.svg": ["*"],
+  "public/favicon.svg": ["*"]
+}
+```
+
+`"*"` means the change affects all routes — capture a representative sample.
+
+## 12. Dependencies
+
+```
+playwright          — browser automation + screenshots
+sharp               — image annotation (draw, composite, text)
+pixelmatch          — pixel-level diff detection
+pngjs               — PNG read/write for pixelmatch
+wait-on             — wait for dev server to be ready
+```
+
+All devDependencies. No runtime impact on the application.

From ca3ae6b7156556e3020fc78892ef783b49dbaa68 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 15:13:11 -0400
Subject: [PATCH 27/41] docs: add concrete implementation reference and tool
 landscape

Added: actual TypeScript implementations for capture, annotate,
compose, diff, and upload modules. Added open-source tool landscape
comparison (Lost Pixel, Argos CI, Chromatic, Percy, BackstopJS,
reg-suit, Playwright built-in). Corrected image hosting strategy
to GitHub branch storage per API research. Added recommendation
matrix for tool selection.
---
 docs/visual-regression-system.md | 369 ++++++++++++++++++++++++++++++-
 1 file changed, 362 insertions(+), 7 deletions(-)

diff --git a/docs/visual-regression-system.md b/docs/visual-regression-system.md
index 57020220..5c6bd417 100644
--- a/docs/visual-regression-system.md
+++ b/docs/visual-regression-system.md
@@ -833,14 +833,369 @@ which files affect which routes:
 
 `"*"` means the change affects all routes — capture a representative sample.
 
-## 12. Dependencies
+## 12. Concrete Implementation Reference
+
+### 12.1 Playwright Capture — Actual API
+
+```typescript
+// playwright-capture.ts
+import { chromium, type Page, type BrowserContext } from 'playwright';
+
+interface CaptureResult {
+  path: string;
+  regions: Array<{ selector: string; bbox: { x: number; y: number; width: number; height: number } }>;
+}
+
+async function captureRoute(
+  context: BrowserContext,
+  baseUrl: string,
+  capture: ManifestCapture,
+  viewport: { name: string; width: number; height: number },
+  outputDir: string,
+): Promise<CaptureResult> {
+  const page = await context.newPage();
+  await page.setViewportSize({ width: viewport.width, height: viewport.height });
+
+  // Navigate and wait for content
+  await page.goto(`${baseUrl}${capture.route}`, { waitUntil: 'networkidle' });
+  if (capture.waitFor) {
+    await page.waitForSelector(capture.waitFor, { timeout: 10_000 });
+  }
+
+  // Disable animations for deterministic capture
+  await page.addStyleTag({ content: `
+    *, *::before, *::after {
+      animation-duration: 0s !important;
+      transition-duration: 0s !important;
+    }
+  `});
+
+  // Execute pre-capture actions (click dropdowns, hover, etc.)
+  if (capture.actions) {
+    for (const action of capture.actions) {
+      await page.locator(action.selector)[action.type as 'click']();
+      await page.waitForTimeout(200);
+    }
+  }
+
+  // Capture full viewport screenshot
+  const screenshotPath = `${outputDir}/${capture.id}-${viewport.name}.png`;
+  await page.screenshot({ path: screenshotPath, fullPage: false });
+
+  // Record bounding boxes for each annotatable region
+  const regions = [];
+  for (const region of capture.regions) {
+    const locator = page.locator(region.selector).first();
+    const bbox = await locator.boundingBox();
+    if (bbox) {
+      regions.push({ selector: region.selector, bbox, annotation: region.annotation });
+    }
+  }
+
+  await page.close();
+  return { path: screenshotPath, regions };
+}
+```
+
+### 12.2 Annotation — sharp + SVG Compositing
+
+```typescript
+// annotate.ts
+import sharp from 'sharp';
+
+const COLORS = {
+  red:    { stroke: '#EF4444', fill: 'rgba(239,68,68,0.85)' },
+  green:  { stroke: '#22C55E', fill: 'rgba(34,197,94,0.85)' },
+  blue:   { stroke: '#3B82F6', fill: 'rgba(59,130,246,0.85)' },
+  orange: { stroke: '#F97316', fill: 'rgba(249,115,22,0.85)' },
+  yellow: { stroke: '#EAB308', fill: 'rgba(234,179,8,0.85)' },
+};
+
+interface AnnotationRegion {
+  bbox: { x: number; y: number; width: number; height: number };
+  annotation: { color: keyof typeof COLORS; label: string };
+}
+
+async function annotateImage(
+  inputPath: string,
+  regions: AnnotationRegion[],
+  outputPath: string,
+): Promise<void> {
+  const meta = await sharp(inputPath).metadata();
+  const { width = 0, height = 0 } = meta;
+
+  // Build SVG overlay with all bounding boxes and labels
+  const boxes = regions.map((r) => {
+    const c = COLORS[r.annotation.color];
+    const pad = 4;
+    const x = Math.max(0, r.bbox.x - pad);
+    const y = Math.max(0, r.bbox.y - pad);
+    const w = r.bbox.width + pad * 2;
+    const h = r.bbox.height + pad * 2;
+    const labelW = r.annotation.label.length * 7 + 16;
+    const labelH = 20;
+    const labelY = Math.max(0, y - labelH - 2);
+
+    return `
+      <rect x="${x}" y="${y}" width="${w}" height="${h}"
+            fill="none" stroke="${c.stroke}" stroke-width="3" rx="4"/>
+      <rect x="${x}" y="${labelY}" width="${labelW}" height="${labelH}"
+            fill="${c.fill}" rx="3"/>
+      <text x="${x + 8}" y="${labelY + 14}"
+            font-size="11" font-weight="bold" fill="white"
+            font-family="system-ui, sans-serif">${r.annotation.label}</text>
+    `;
+  }).join('');
+
+  const svgOverlay = Buffer.from(
+    `<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg">${boxes}</svg>`
+  );
+
+  await sharp(inputPath)
+    .composite([{ input: svgOverlay, top: 0, left: 0 }])
+    .toFile(outputPath);
+}
+```
+
+### 12.3 Composition — Side-by-Side with Title Bar
+
+```typescript
+// compose.ts
+import sharp from 'sharp';
+
+async function composePair(
+  beforePath: string,
+  afterPath: string,
+  title: string,
+  outputPath: string,
+): Promise<void> {
+  const [bMeta, aMeta] = await Promise.all([
+    sharp(beforePath).metadata(),
+    sharp(afterPath).metadata(),
+  ]);
+
+  const bW = bMeta.width ?? 0;
+  const aW = aMeta.width ?? 0;
+  const maxH = Math.max(bMeta.height ?? 0, aMeta.height ?? 0);
+  const divider = 2;
+  const titleH = 48;
+  const footerH = 28;
+  const totalW = bW + aW + divider;
+  const totalH = maxH + titleH + footerH;
+
+  const titleSvg = `
+    <svg width="${totalW}" height="${titleH}">
+      <rect width="100%" height="100%" fill="#f8f9fb"/>
+      <text x="${totalW / 2}" y="30" text-anchor="middle"
+            font-size="14" font-weight="600" fill="#1f2937"
+            font-family="system-ui, sans-serif">${title}</text>
+    </svg>`;
+
+  const footerSvg = `
+    <svg width="${totalW}" height="${footerH}">
+      <rect width="100%" height="100%" fill="#f1f5f9"/>
+      <text x="${bW / 2}" y="18" text-anchor="middle"
+            font-size="11" fill="#64748b"
+            font-family="system-ui, sans-serif">BEFORE (main)</text>
+      <line x1="${bW + 1}" y1="4" x2="${bW + 1}" y2="24"
+            stroke="#cbd5e1" stroke-width="1"/>
+      <text x="${bW + divider + aW / 2}" y="18" text-anchor="middle"
+            font-size="11" fill="#64748b"
+            font-family="system-ui, sans-serif">AFTER (PR)</text>
+    </svg>`;
+
+  // Divider line
+  const dividerBuf = await sharp({
+    create: { width: divider, height: maxH, channels: 4,
+              background: { r: 203, g: 213, b: 225, alpha: 1 } },
+  }).png().toBuffer();
+
+  await sharp({
+    create: { width: totalW, height: totalH, channels: 4,
+              background: { r: 255, g: 255, b: 255, alpha: 1 } },
+  })
+    .composite([
+      { input: Buffer.from(titleSvg), top: 0, left: 0 },
+      { input: await sharp(beforePath).toBuffer(), top: titleH, left: 0 },
+      { input: dividerBuf, top: titleH, left: bW },
+      { input: await sharp(afterPath).toBuffer(), top: titleH, left: bW + divider },
+      { input: Buffer.from(footerSvg), top: titleH + maxH, left: 0 },
+    ])
+    .toFile(outputPath);
+}
+```
+
+### 12.4 Diff Detection — pixelmatch
+
+```typescript
+// diff.ts
+import { PNG } from 'pngjs';
+import pixelmatch from 'pixelmatch';
+import fs from 'fs';
+
+interface DiffResult {
+  diffPixels: number;
+  totalPixels: number;
+  diffPercent: number;
+  diffImagePath: string;
+}
+
+function computeDiff(beforePath: string, afterPath: string, diffPath: string): DiffResult {
+  const img1 = PNG.sync.read(fs.readFileSync(beforePath));
+  const img2 = PNG.sync.read(fs.readFileSync(afterPath));
+
+  // Images must be same dimensions — pad smaller if needed
+  const width = Math.max(img1.width, img2.width);
+  const height = Math.max(img1.height, img2.height);
+  const diff = new PNG({ width, height });
+
+  const diffPixels = pixelmatch(
+    img1.data, img2.data, diff.data, width, height,
+    { threshold: 0.1, includeAA: false }
+  );
+
+  fs.writeFileSync(diffPath, PNG.sync.write(diff));
+
+  const totalPixels = width * height;
+  return {
+    diffPixels,
+    totalPixels,
+    diffPercent: Number(((diffPixels / totalPixels) * 100).toFixed(2)),
+    diffImagePath: diffPath,
+  };
+}
+```
+
+### 12.5 Upload — GitHub Branch Storage
+
+Research confirmed GitHub's API does not support direct image uploads to comments.
+The most durable strategy is **pushing images to a dedicated branch** and referencing
+via raw GitHub URLs. This is the approach used by `opengisch/comment-pr-with-images`.
+
+```typescript
+// upload.ts
+import { execSync } from 'child_process';
+
+function uploadToGitHubBranch(
+  imagePaths: string[],
+  branch = 'visual-regression-assets',
+  subdir = 'comparisons',
+): Map<string, string> {
+  const repo = 'TextureHQ/commongrid';
+  const urls = new Map<string, string>();
+
+  // Create orphan branch if it doesn't exist
+  try {
+    execSync(`git rev-parse --verify ${branch}`, { stdio: 'ignore' });
+  } catch {
+    execSync(`git checkout --orphan ${branch}`);
+    execSync('git rm -rf . 2>/dev/null || true');
+    execSync('git commit --allow-empty -m "init visual regression assets"');
+    execSync(`git checkout -`);
+  }
+
+  // Use worktree to add images without switching branches
+  const worktreePath = '/tmp/vr-upload';
+  execSync(`git worktree add ${worktreePath} ${branch} 2>/dev/null || true`);
+
+  for (const imgPath of imagePaths) {
+    const filename = imgPath.split('/').pop()!;
+    execSync(`mkdir -p ${worktreePath}/${subdir}`);
+    execSync(`cp ${imgPath} ${worktreePath}/${subdir}/${filename}`);
+    urls.set(
+      imgPath,
+      `https://raw.githubusercontent.com/${repo}/${branch}/${subdir}/${filename}`,
+    );
+  }
+
+  execSync(`cd ${worktreePath} && git add -A && git commit -m "VR: update comparison images" && git push origin ${branch}`, { stdio: 'inherit' });
+  execSync(`git worktree remove ${worktreePath}`);
+
+  return urls;
+}
+```
+
+Alternative: use [CML](https://cml.dev) (`cml comment create`) which handles
+image embedding in PR comments automatically, or [imgbb](https://api.imgbb.com/)
+for zero-infrastructure external hosting.
+
+## 13. Existing Open-Source Visual Regression Tools
+
+### Landscape Comparison
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                  VISUAL REGRESSION TOOL LANDSCAPE                       │
+│                                                                          │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌─────────────┐  │
+│  │  Lost Pixel  │  │  Argos CI    │  │   Chromatic  │  │   Percy     │  │
+│  │  ───────────  │  │  ──────────  │  │  ──────────  │  │  ─────────  │  │
+│  │  OSS / Free  │  │  OSS / Free  │  │  Freemium   │  │  SaaS only  │  │
+│  │  odiff (6x   │  │  Playwright  │  │  Storybook  │  │  DOM snap-  │  │
+│  │  faster diff) │  │  Cypress     │  │  deep integ │  │  shot based │  │
+│  │  Storybook + │  │  Puppeteer   │  │  TurboSnap  │  │  Multi-     │  │
+│  │  Page + PW   │  │  CI comments │  │  Cloud UI   │  │  browser    │  │
+│  │  Git baselines│  │  Anim freeze│  │  Review UI  │  │  rendering  │  │
+│  └──────────────┘  └──────────────┘  └──────────────┘  └─────────────┘  │
+│        ▲                  ▲                                               │
+│        │                  │                                               │
+│   Best fit for       Good for                                            │
+│   agentic / CI      complex apps                                         │
+│   lightweight       with animations                                      │
+│                                                                          │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                    │
+│  │  Playwright  │  │  BackstopJS  │  │  reg-suit    │                    │
+│  │  built-in    │  │  ───────────  │  │  ──────────  │                    │
+│  │  ───────────  │  │  Puppeteer   │  │  S3 + GitHub │                    │
+│  │  toHaveScr.. │  │  Config-     │  │  Plugin      │                    │
+│  │  pixelmatch  │  │  driven      │  │  architecture│                    │
+│  │  Zero extra  │  │  Scenarios   │  │  Notify PR   │                    │
+│  │  deps needed │  │  Docker ref  │  │  via comment │                    │
+│  └──────────────┘  └──────────────┘  └──────────────┘                    │
+│        ▲                                                                 │
+│        │                                                                 │
+│   Simplest start                                                         │
+│   (already a dep)                                                        │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### Recommendation Matrix
+
+| Criterion | Lost Pixel | Playwright built-in | Argos CI | Custom (this spec) |
+|-----------|-----------|-------------------|----------|-------------------|
+| **Open source** | Yes | Yes | Yes | Yes |
+| **Dependency weight** | odiff-bin + config | Zero (already in PW) | CLI + service | sharp + pixelmatch |
+| **Agentic-friendly** | Config-driven JSON | Test file per route | Config-driven | Manifest-driven |
+| **Annotation/bbox** | No | No | Diff overlay only | **Yes — full control** |
+| **Before/after compose** | Diff overlay | 3-panel (expected/actual/diff) | Cloud UI | **Custom side-by-side** |
+| **PR integration** | GitHub Action comment | Test report artifact | PR comment | **Custom markdown table** |
+| **Learning curve** | Low | Very low | Low | Medium |
+| **Color-coded annotations** | No | No | No | **Yes** |
+| **Selective capture** | Stories/pages | Test-scoped | Stories/pages | **Per-commit manifest** |
+
+### Recommendation
+
+**For CommonGrid specifically:**
+
+1. **Start with Playwright built-in** (`toHaveScreenshot`) for pure regression detection — zero new deps, catches unintended changes
+2. **Layer the custom system** (this spec) on top for PR-quality annotated comparison images — the bounding-box + color-coding + composition pipeline doesn't exist in any off-the-shelf tool
+3. **Consider Lost Pixel** if Storybook is ever adopted — it's the most lightweight OSS option with the fastest diff engine (odiff)
+
+The custom system fills a gap no existing tool covers: **per-commit, color-rationalized, annotated before/after comparison images** that communicate _what_ changed and _why_ at a glance in a PR description.
+
+## 14. Dependencies
 
 ```
-playwright          — browser automation + screenshots
-sharp               — image annotation (draw, composite, text)
-pixelmatch          — pixel-level diff detection
-pngjs               — PNG read/write for pixelmatch
-wait-on             — wait for dev server to be ready
+# Core (all devDependencies)
+playwright          — browser automation + screenshots (may already be installed)
+sharp               — image annotation via SVG compositing (no native canvas dep)
+pixelmatch          — pixel-level diff detection (~150 lines, zero deps)
+pngjs               — PNG encode/decode for pixelmatch
+wait-on             — wait for dev server to be ready before capture
+
+# Optional
+join-images         — simplified side-by-side composition (built on sharp)
+odiff-bin           — 6x faster diff than pixelmatch (OCaml binary, optional upgrade)
 ```
 
-All devDependencies. No runtime impact on the application.
+Total footprint: ~3MB added to devDependencies. No runtime impact.

From f117566afaaa9860222e43e1b4daf54f38767511 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 15:50:40 -0400
Subject: [PATCH 28/41] feat: implement visual regression capture system
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Working pipeline: Playwright captures screenshots at specified routes
and viewports, sharp+SVG draws color-coded bounding boxes (red/green/
blue/orange/yellow), compose engine creates side-by-side BEFORE|AFTER
images with title bar and footer, pixelmatch computes pixel diffs.

Modules:
  - playwright-capture.ts: browser automation + bbox recording
  - annotate.ts: SVG overlay compositing via sharp
  - compose.ts: side-by-side image composition
  - diff.ts: pixelmatch diff detection
  - capture-vr.ts: orchestrator (worktree, servers, pipeline)
  - capture-manifest.json: 10 capture targets for welcome-pr
  - file-route-map.json: file→route mapping for auto-manifest

New scripts: npm run vr:capture, npm run vr:capture:pr-only
New devDeps: playwright, sharp, pixelmatch, pngjs, wait-on
---
 .gitignore                                    |   3 +
 package-lock.json                             | 507 +++++++++++++++++-
 package.json                                  |   9 +-
 scripts/visual-regression/annotate.ts         |  99 ++++
 .../visual-regression/capture-manifest.json   | 177 ++++++
 scripts/visual-regression/capture-vr.ts       | 380 +++++++++++++
 scripts/visual-regression/compose.ts          | 103 ++++
 scripts/visual-regression/diff.ts             |  73 +++
 scripts/visual-regression/file-route-map.json |  26 +
 .../visual-regression/playwright-capture.ts   | 195 +++++++
 10 files changed, 1568 insertions(+), 4 deletions(-)
 create mode 100644 scripts/visual-regression/annotate.ts
 create mode 100644 scripts/visual-regression/capture-manifest.json
 create mode 100644 scripts/visual-regression/capture-vr.ts
 create mode 100644 scripts/visual-regression/compose.ts
 create mode 100644 scripts/visual-regression/diff.ts
 create mode 100644 scripts/visual-regression/file-route-map.json
 create mode 100644 scripts/visual-regression/playwright-capture.ts

diff --git a/.gitignore b/.gitignore
index ad435e15..a16a177c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -29,3 +29,6 @@ public/tiles/*
 # Changelog snapshot — large JSON used only for diffing during sync
 # changelog.json itself is tracked; only the snapshot dir is ignored
 data/.snapshot/
+
+# Visual regression capture output (generated, not tracked)
+.visual-regression/
diff --git a/package-lock.json b/package-lock.json
index 05fae614..3a1d2ec2 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -27,7 +27,12 @@
         "@types/react": "^19.1.13",
         "@types/react-dom": "^19.1.9",
         "adm-zip": "^0.5.16",
+        "pixelmatch": "^7.1.0",
+        "playwright": "^1.58.2",
+        "pngjs": "^7.0.0",
+        "sharp": "^0.34.5",
         "typescript": "^5.9.2",
+        "wait-on": "^9.0.4",
         "xlsx": "^0.18.5"
       }
     },
@@ -383,12 +388,66 @@
         "tslib": "^2.8.1"
       }
     },
+    "node_modules/@hapi/address": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/@hapi/address/-/address-5.1.1.tgz",
+      "integrity": "sha512-A+po2d/dVoY7cYajycYI43ZbYMXukuopIsqCjh5QzsBCipDtdofHntljDlpccMjIfTy6UOkg+5KPriwYch2bXA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@hapi/hoek": "^11.0.2"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/@hapi/formula": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/@hapi/formula/-/formula-3.0.2.tgz",
+      "integrity": "sha512-hY5YPNXzw1He7s0iqkRQi+uMGh383CGdyyIGYtB+W5N3KHPXoqychklvHhKCC9M3Xtv0OCs/IHw+r4dcHtBYWw==",
+      "dev": true,
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@hapi/hoek": {
+      "version": "11.0.7",
+      "resolved": "https://registry.npmjs.org/@hapi/hoek/-/hoek-11.0.7.tgz",
+      "integrity": "sha512-HV5undWkKzcB4RZUusqOpcgxOaq6VOAH7zhhIr2g3G8NF/MlFO75SjOr2NfuSx0Mh40+1FqCkagKLJRykUWoFQ==",
+      "dev": true,
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@hapi/pinpoint": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/@hapi/pinpoint/-/pinpoint-2.0.1.tgz",
+      "integrity": "sha512-EKQmr16tM8s16vTT3cA5L0kZZcTMU5DUOZTuvpnY738m+jyP3JIUj+Mm1xc1rsLkGBQ/gVnfKYPwOmPg1tUR4Q==",
+      "dev": true,
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/@hapi/tlds": {
+      "version": "1.1.6",
+      "resolved": "https://registry.npmjs.org/@hapi/tlds/-/tlds-1.1.6.tgz",
+      "integrity": "sha512-xdi7A/4NZokvV0ewovme3aUO5kQhW9pQ2YD1hRqZGhhSi5rBv4usHYidVocXSi9eihYsznZxLtAiEYYUL6VBGw==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
+    "node_modules/@hapi/topo": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/@hapi/topo/-/topo-6.0.2.tgz",
+      "integrity": "sha512-KR3rD5inZbGMrHmgPxsJ9dbi6zEK+C3ZwUwTa+eMwWLz7oijWUTWD2pMSNNYJAU6Qq+65NkxXjqHr/7LM2Xkqg==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@hapi/hoek": "^11.0.2"
+      }
+    },
     "node_modules/@img/colour": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/@img/colour/-/colour-1.0.0.tgz",
       "integrity": "sha512-A5P/LfWGFSl6nsckYtjw9da+19jB8hkJ6ACTGcDfEJ0aE+l2n2El7dsVM7UVHZQ9s2lmYMWlrS21YLy2IR1LUw==",
+      "devOptional": true,
       "license": "MIT",
-      "optional": true,
       "engines": {
         "node": ">=18"
       }
@@ -400,6 +459,7 @@
       "cpu": [
         "arm64"
       ],
+      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -422,6 +482,7 @@
       "cpu": [
         "x64"
       ],
+      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -444,6 +505,7 @@
       "cpu": [
         "arm64"
       ],
+      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -460,6 +522,7 @@
       "cpu": [
         "x64"
       ],
+      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -476,6 +539,7 @@
       "cpu": [
         "arm"
       ],
+      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -492,6 +556,7 @@
       "cpu": [
         "arm64"
       ],
+      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -508,6 +573,7 @@
       "cpu": [
         "ppc64"
       ],
+      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -524,6 +590,7 @@
       "cpu": [
         "riscv64"
       ],
+      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -540,6 +607,7 @@
       "cpu": [
         "s390x"
       ],
+      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -556,6 +624,7 @@
       "cpu": [
         "x64"
       ],
+      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -572,6 +641,7 @@
       "cpu": [
         "arm64"
       ],
+      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -588,6 +658,7 @@
       "cpu": [
         "x64"
       ],
+      "dev": true,
       "license": "LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -604,6 +675,7 @@
       "cpu": [
         "arm"
       ],
+      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -626,6 +698,7 @@
       "cpu": [
         "arm64"
       ],
+      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -648,6 +721,7 @@
       "cpu": [
         "ppc64"
       ],
+      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -670,6 +744,7 @@
       "cpu": [
         "riscv64"
       ],
+      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -692,6 +767,7 @@
       "cpu": [
         "s390x"
       ],
+      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -714,6 +790,7 @@
       "cpu": [
         "x64"
       ],
+      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -736,6 +813,7 @@
       "cpu": [
         "arm64"
       ],
+      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -758,6 +836,7 @@
       "cpu": [
         "x64"
       ],
+      "dev": true,
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -780,6 +859,7 @@
       "cpu": [
         "wasm32"
       ],
+      "dev": true,
       "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT",
       "optional": true,
       "dependencies": {
@@ -799,6 +879,7 @@
       "cpu": [
         "arm64"
       ],
+      "dev": true,
       "license": "Apache-2.0 AND LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -818,6 +899,7 @@
       "cpu": [
         "ia32"
       ],
+      "dev": true,
       "license": "Apache-2.0 AND LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -837,6 +919,7 @@
       "cpu": [
         "x64"
       ],
+      "dev": true,
       "license": "Apache-2.0 AND LGPL-3.0-or-later",
       "optional": true,
       "os": [
@@ -3324,6 +3407,13 @@
         "node": ">=14.18"
       }
     },
+    "node_modules/@standard-schema/spec": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.1.0.tgz",
+      "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@swc/core-darwin-arm64": {
       "version": "1.15.11",
       "resolved": "https://registry.npmjs.org/@swc/core-darwin-arm64/-/core-darwin-arm64-1.15.11.tgz",
@@ -4964,6 +5054,25 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/asynckit": {
+      "version": "0.4.0",
+      "resolved": "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz",
+      "integrity": "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/axios": {
+      "version": "1.13.6",
+      "resolved": "https://registry.npmjs.org/axios/-/axios-1.13.6.tgz",
+      "integrity": "sha512-ChTCHMouEe2kn713WHbQGcuYrr6fXTBiu460OTwWrWob16g1bXn4vtz07Ope7ewMozJAnEquLk5lWQWtBig9DQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "follow-redirects": "^1.15.11",
+        "form-data": "^4.0.5",
+        "proxy-from-env": "^1.1.0"
+      }
+    },
     "node_modules/balanced-match": {
       "version": "0.4.2",
       "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-0.4.2.tgz",
@@ -5033,6 +5142,20 @@
         "typewise-core": "^1.2"
       }
     },
+    "node_modules/call-bind-apply-helpers": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz",
+      "integrity": "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "es-errors": "^1.3.0",
+        "function-bind": "^1.1.2"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
     "node_modules/caniuse-lite": {
       "version": "1.0.30001770",
       "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001770.tgz",
@@ -5110,6 +5233,19 @@
         "node": ">=0.8"
       }
     },
+    "node_modules/combined-stream": {
+      "version": "1.0.8",
+      "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz",
+      "integrity": "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "delayed-stream": "~1.0.0"
+      },
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
     "node_modules/crc-32": {
       "version": "1.2.2",
       "resolved": "https://registry.npmjs.org/crc-32/-/crc-32-1.2.2.tgz",
@@ -5310,6 +5446,16 @@
         "robust-predicates": "^3.0.2"
       }
     },
+    "node_modules/delayed-stream": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/delayed-stream/-/delayed-stream-1.0.0.tgz",
+      "integrity": "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
     "node_modules/detect-libc": {
       "version": "2.1.2",
       "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
@@ -5334,6 +5480,21 @@
       "integrity": "sha512-IayShXAgj/QMXgB0IWmKx+rOPuGMhqm5w6jvFxmVenXKIzRqTAAsbBPT3kWQeGANj3jGgvcvv4yK6SxqYmikgw==",
       "license": "Apache-2.0"
     },
+    "node_modules/dunder-proto": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
+      "integrity": "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "call-bind-apply-helpers": "^1.0.1",
+        "es-errors": "^1.3.0",
+        "gopd": "^1.2.0"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
     "node_modules/earcut": {
       "version": "3.0.2",
       "resolved": "https://registry.npmjs.org/earcut/-/earcut-3.0.2.tgz",
@@ -5365,6 +5526,55 @@
         "url": "https://github.com/fb55/entities?sponsor=1"
       }
     },
+    "node_modules/es-define-property": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
+      "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/es-errors": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz",
+      "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/es-object-atoms": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.1.tgz",
+      "integrity": "sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "es-errors": "^1.3.0"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/es-set-tostringtag": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/es-set-tostringtag/-/es-set-tostringtag-2.1.0.tgz",
+      "integrity": "sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "es-errors": "^1.3.0",
+        "get-intrinsic": "^1.2.6",
+        "has-tostringtag": "^1.0.2",
+        "hasown": "^2.0.2"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
     "node_modules/escape-string-regexp": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz",
@@ -5531,6 +5741,23 @@
         }
       }
     },
+    "node_modules/form-data": {
+      "version": "4.0.5",
+      "resolved": "https://registry.npmjs.org/form-data/-/form-data-4.0.5.tgz",
+      "integrity": "sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "asynckit": "^0.4.0",
+        "combined-stream": "^1.0.8",
+        "es-set-tostringtag": "^2.1.0",
+        "hasown": "^2.0.2",
+        "mime-types": "^2.1.12"
+      },
+      "engines": {
+        "node": ">= 6"
+      }
+    },
     "node_modules/frac": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/frac/-/frac-1.1.2.tgz",
@@ -5568,6 +5795,31 @@
         }
       }
     },
+    "node_modules/fsevents": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/function-bind": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz",
+      "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
     "node_modules/fuse.js": {
       "version": "7.1.0",
       "resolved": "https://registry.npmjs.org/fuse.js/-/fuse.js-7.1.0.tgz",
@@ -5577,6 +5829,45 @@
         "node": ">=10"
       }
     },
+    "node_modules/get-intrinsic": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz",
+      "integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "call-bind-apply-helpers": "^1.0.2",
+        "es-define-property": "^1.0.1",
+        "es-errors": "^1.3.0",
+        "es-object-atoms": "^1.1.1",
+        "function-bind": "^1.1.2",
+        "get-proto": "^1.0.1",
+        "gopd": "^1.2.0",
+        "has-symbols": "^1.1.0",
+        "hasown": "^2.0.2",
+        "math-intrinsics": "^1.1.0"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/get-proto": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz",
+      "integrity": "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "dunder-proto": "^1.0.1",
+        "es-object-atoms": "^1.0.0"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
     "node_modules/get-value": {
       "version": "2.0.6",
       "resolved": "https://registry.npmjs.org/get-value/-/get-value-2.0.6.tgz",
@@ -5592,6 +5883,19 @@
       "integrity": "sha512-latSnyDNt/8zYUB6VIJ6PCh2jBjJX6gnDsoCZ7LyW7GkqrD51EWwa9qCoGixj8YqBtETQK/xY7OmpTF8xz1DdQ==",
       "license": "MIT"
     },
+    "node_modules/gopd": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
+      "integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
     "node_modules/graceful-fs": {
       "version": "4.2.11",
       "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz",
@@ -5604,6 +5908,48 @@
       "integrity": "sha512-HZRwumpOGUrHyxO5bqKZL0B0GlUpwtCAzZ42sgxUPniu33R1LSFH5yrIcBCHjkctCAh3mtWKcKd9J4vDDdeVHA==",
       "license": "ISC"
     },
+    "node_modules/has-symbols": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz",
+      "integrity": "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/has-tostringtag": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/has-tostringtag/-/has-tostringtag-1.0.2.tgz",
+      "integrity": "sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "has-symbols": "^1.0.3"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/hasown": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.2.tgz",
+      "integrity": "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "function-bind": "^1.1.2"
+      },
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
     "node_modules/icu-minify": {
       "version": "4.8.3",
       "resolved": "https://registry.npmjs.org/icu-minify/-/icu-minify-4.8.3.tgz",
@@ -5780,6 +6126,25 @@
         "jiti": "lib/jiti-cli.mjs"
       }
     },
+    "node_modules/joi": {
+      "version": "18.0.2",
+      "resolved": "https://registry.npmjs.org/joi/-/joi-18.0.2.tgz",
+      "integrity": "sha512-RuCOQMIt78LWnktPoeBL0GErkNaJPTBGcYuyaBvUOQSpcpcLfWrHPPihYdOGbV5pam9VTWbeoF7TsGiHugcjGA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@hapi/address": "^5.1.1",
+        "@hapi/formula": "^3.0.2",
+        "@hapi/hoek": "^11.0.7",
+        "@hapi/pinpoint": "^2.0.1",
+        "@hapi/tlds": "^1.1.1",
+        "@hapi/topo": "^6.0.2",
+        "@standard-schema/spec": "^1.0.0"
+      },
+      "engines": {
+        "node": ">= 20"
+      }
+    },
     "node_modules/js-tokens": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
@@ -6211,12 +6576,45 @@
       "integrity": "sha512-4vRUvPyxdO8cWULGTh9dZWL2tZK6LDBvj+OGHBER7poH9Qdt7kXEoj20wiz4lQUbUXQZFjPbe5mVDo9nutizCw==",
       "license": "MIT"
     },
+    "node_modules/math-intrinsics": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
+      "integrity": "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
     "node_modules/mdurl": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.0.0.tgz",
       "integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==",
       "license": "MIT"
     },
+    "node_modules/mime-db": {
+      "version": "1.52.0",
+      "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz",
+      "integrity": "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/mime-types": {
+      "version": "2.1.35",
+      "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-2.1.35.tgz",
+      "integrity": "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "mime-db": "1.52.0"
+      },
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
     "node_modules/minimist": {
       "version": "1.2.8",
       "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz",
@@ -6408,6 +6806,17 @@
         }
       }
     },
+    "node_modules/next-intl/node_modules/@swc/helpers": {
+      "version": "0.5.19",
+      "resolved": "https://registry.npmjs.org/@swc/helpers/-/helpers-0.5.19.tgz",
+      "integrity": "sha512-QamiFeIK3txNjgUTNppE6MiG3p7TdninpZu0E0PbqVh1a9FNLT2FRhisaa4NcaX52XVhA5l7Pk58Ft7Sqi/2sA==",
+      "license": "Apache-2.0",
+      "optional": true,
+      "peer": true,
+      "dependencies": {
+        "tslib": "^2.8.0"
+      }
+    },
     "node_modules/next/node_modules/postcss": {
       "version": "8.4.31",
       "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.4.31.tgz",
@@ -6550,6 +6959,51 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
+    "node_modules/pixelmatch": {
+      "version": "7.1.0",
+      "resolved": "https://registry.npmjs.org/pixelmatch/-/pixelmatch-7.1.0.tgz",
+      "integrity": "sha512-1wrVzJ2STrpmONHKBy228LM1b84msXDUoAzVEl0R8Mz4Ce6EPr+IVtxm8+yvrqLYMHswREkjYFaMxnyGnaY3Ng==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "pngjs": "^7.0.0"
+      },
+      "bin": {
+        "pixelmatch": "bin/pixelmatch"
+      }
+    },
+    "node_modules/playwright": {
+      "version": "1.58.2",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.58.2.tgz",
+      "integrity": "sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright-core": "1.58.2"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "fsevents": "2.3.2"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.58.2",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.58.2.tgz",
+      "integrity": "sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/pmtiles": {
       "version": "4.4.0",
       "resolved": "https://registry.npmjs.org/pmtiles/-/pmtiles-4.4.0.tgz",
@@ -6559,6 +7013,16 @@
         "fflate": "^0.8.2"
       }
     },
+    "node_modules/pngjs": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/pngjs/-/pngjs-7.0.0.tgz",
+      "integrity": "sha512-LKWqWJRhstyYo9pGvgor/ivk2w94eSjE3RGVuzLGlr3NmD8bf7RcYGze1mNdEHRP6TRP6rMuDHk5t44hnTRyow==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.19.0"
+      }
+    },
     "node_modules/po-parser": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/po-parser/-/po-parser-2.1.1.tgz",
@@ -6820,6 +7284,13 @@
       "integrity": "sha512-TdDRD+/QNdrCGCE7v8340QyuXd4kIWIgapsE2+n/SaGiSSbomYl4TjHlvIoCWRpE7wFt02EpB35VVA2ImcBVqw==",
       "license": "MIT"
     },
+    "node_modules/proxy-from-env": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-1.1.0.tgz",
+      "integrity": "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/punycode.js": {
       "version": "2.3.1",
       "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz",
@@ -7145,6 +7616,16 @@
       "integrity": "sha512-PdhdWy89SiZogBLaw42zdeqtRJ//zFd2PgQavcICDUgJT5oW10QCRKbJ6bg4r0/UY2M6BWd5tkxuGFRvCkgfHQ==",
       "license": "BSD-3-Clause"
     },
+    "node_modules/rxjs": {
+      "version": "7.8.2",
+      "resolved": "https://registry.npmjs.org/rxjs/-/rxjs-7.8.2.tgz",
+      "integrity": "sha512-dhKf903U/PQZY6boNNtAGdWbG85WAbjT/1xYoZIC7FAY0yWapOBQVsVrDl58W86//e1VpMNBtRV4MaXfdMySFA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "tslib": "^2.1.0"
+      }
+    },
     "node_modules/safe-buffer": {
       "version": "5.2.1",
       "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
@@ -7175,8 +7656,8 @@
       "version": "7.7.4",
       "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz",
       "integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==",
+      "devOptional": true,
       "license": "ISC",
-      "optional": true,
       "bin": {
         "semver": "bin/semver.js"
       },
@@ -7212,9 +7693,9 @@
       "version": "0.34.5",
       "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.34.5.tgz",
       "integrity": "sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==",
+      "devOptional": true,
       "hasInstallScript": true,
       "license": "Apache-2.0",
-      "optional": true,
       "dependencies": {
         "@img/colour": "^1.0.0",
         "detect-libc": "^2.1.2",
@@ -7644,6 +8125,26 @@
       "integrity": "sha512-dpojBhNsCNN7T82Tm7k26A6G9ML3NkhDsnw9n/eoxSRlVBB4CEtIQ/KTCLI2Fwf3ataSXRhYFkQi3SlnFwPvPQ==",
       "license": "MIT"
     },
+    "node_modules/wait-on": {
+      "version": "9.0.4",
+      "resolved": "https://registry.npmjs.org/wait-on/-/wait-on-9.0.4.tgz",
+      "integrity": "sha512-k8qrgfwrPVJXTeFY8tl6BxVHiclK11u72DVKhpybHfUL/K6KM4bdyK9EhIVYGytB5MJe/3lq4Tf0hrjM+pvJZQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "axios": "^1.13.5",
+        "joi": "^18.0.2",
+        "lodash": "^4.17.23",
+        "minimist": "^1.2.8",
+        "rxjs": "^7.8.2"
+      },
+      "bin": {
+        "wait-on": "bin/wait-on"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
     "node_modules/wmf": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/wmf/-/wmf-1.0.2.tgz",
diff --git a/package.json b/package.json
index c0ef5432..c54dfffe 100644
--- a/package.json
+++ b/package.json
@@ -13,7 +13,9 @@
     "sync:ev-charging": "tsx scripts/sync-ev-charging.ts",
     "sync:pricing-nodes": "tsx scripts/sync-pricing-nodes.ts",
     "generate:changelog": "npx tsx scripts/generate-changelog.ts",
-    "sync:all": "npx tsx scripts/sync-all.ts"
+    "sync:all": "npx tsx scripts/sync-all.ts",
+    "vr:capture": "npx tsx scripts/visual-regression/capture-vr.ts",
+    "vr:capture:pr-only": "npx tsx scripts/visual-regression/capture-vr.ts --skip-base"
   },
   "dependencies": {
     "@floating-ui/dom": "^1.7.5",
@@ -35,7 +37,12 @@
     "@types/react": "^19.1.13",
     "@types/react-dom": "^19.1.9",
     "adm-zip": "^0.5.16",
+    "pixelmatch": "^7.1.0",
+    "playwright": "^1.58.2",
+    "pngjs": "^7.0.0",
+    "sharp": "^0.34.5",
     "typescript": "^5.9.2",
+    "wait-on": "^9.0.4",
     "xlsx": "^0.18.5"
   }
 }
diff --git a/scripts/visual-regression/annotate.ts b/scripts/visual-regression/annotate.ts
new file mode 100644
index 00000000..7491c9ad
--- /dev/null
+++ b/scripts/visual-regression/annotate.ts
@@ -0,0 +1,99 @@
+/**
+ * annotate.ts — Draw color-coded bounding boxes and labels on screenshots.
+ *
+ * Uses sharp + SVG compositing (no native canvas dependency).
+ *
+ * Color key:
+ *   red    → removed (BEFORE only)
+ *   green  → added (AFTER only)
+ *   blue   → modified in-place
+ *   orange → recolored / remapped
+ *   yellow → moved / reflowed
+ */
+
+import sharp from "sharp";
+
+export const ANNOTATION_COLORS = {
+	red: { stroke: "#EF4444", fill: "rgba(239,68,68,0.85)" },
+	green: { stroke: "#22C55E", fill: "rgba(34,197,94,0.85)" },
+	blue: { stroke: "#3B82F6", fill: "rgba(59,130,246,0.85)" },
+	orange: { stroke: "#F97316", fill: "rgba(249,115,22,0.85)" },
+	yellow: { stroke: "#EAB308", fill: "rgba(234,179,8,0.85)" },
+} as const;
+
+export type AnnotationColor = keyof typeof ANNOTATION_COLORS;
+
+export interface BBox {
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+}
+
+export interface AnnotationRegion {
+	bbox: BBox;
+	color: AnnotationColor;
+	label: string;
+}
+
+function escapeXml(s: string): string {
+	return s
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;");
+}
+
+export async function annotateImage(
+	inputPath: string,
+	regions: AnnotationRegion[],
+	outputPath: string,
+): Promise<void> {
+	const meta = await sharp(inputPath).metadata();
+	const imgW = meta.width ?? 0;
+	const imgH = meta.height ?? 0;
+
+	if (regions.length === 0) {
+		// No annotations — just copy
+		await sharp(inputPath).toFile(outputPath);
+		return;
+	}
+
+	const pad = 4;
+	const strokeW = 3;
+	const labelH = 20;
+	const labelPadX = 8;
+	const fontSize = 11;
+	const charW = 6.6; // approx width per char at 11px
+
+	const svgElements = regions
+		.map((r) => {
+			const c = ANNOTATION_COLORS[r.color];
+			const x = Math.max(0, Math.round(r.bbox.x - pad));
+			const y = Math.max(0, Math.round(r.bbox.y - pad));
+			const w = Math.round(r.bbox.width + pad * 2);
+			const h = Math.round(r.bbox.height + pad * 2);
+
+			const labelText = escapeXml(r.label);
+			const labelW = Math.round(labelText.length * charW + labelPadX * 2);
+			const labelY = Math.max(0, y - labelH - 2);
+
+			return [
+				// Bounding box
+				`<rect x="${x}" y="${y}" width="${w}" height="${h}" fill="none" stroke="${c.stroke}" stroke-width="${strokeW}" rx="4"/>`,
+				// Label background pill
+				`<rect x="${x}" y="${labelY}" width="${labelW}" height="${labelH}" fill="${c.fill}" rx="3"/>`,
+				// Label text
+				`<text x="${x + labelPadX}" y="${labelY + 14}" font-size="${fontSize}" font-weight="bold" fill="white" font-family="system-ui,-apple-system,sans-serif">${labelText}</text>`,
+			].join("\n");
+		})
+		.join("\n");
+
+	const svgOverlay = Buffer.from(
+		`<svg width="${imgW}" height="${imgH}" xmlns="http://www.w3.org/2000/svg">${svgElements}</svg>`,
+	);
+
+	await sharp(inputPath)
+		.composite([{ input: svgOverlay, top: 0, left: 0 }])
+		.toFile(outputPath);
+}
diff --git a/scripts/visual-regression/capture-manifest.json b/scripts/visual-regression/capture-manifest.json
new file mode 100644
index 00000000..6937d648
--- /dev/null
+++ b/scripts/visual-regression/capture-manifest.json
@@ -0,0 +1,177 @@
+{
+  "$schema": "./capture-manifest.schema.json",
+  "version": "1.0",
+  "baseRef": "main",
+  "prRef": "HEAD",
+  "devServer": {
+    "command": "npx next dev",
+    "readyPattern": "Ready in",
+    "basePort": 3100,
+    "prPort": 3101
+  },
+  "viewports": [
+    { "name": "mobile", "width": 375, "height": 812 },
+    { "name": "tablet", "width": 768, "height": 1024 },
+    { "name": "desktop", "width": 1440, "height": 900 }
+  ],
+  "captures": [
+    {
+      "id": "dropdown-chevron-padding",
+      "commit": "3f89367",
+      "route": "/grid-operators",
+      "description": "Inner right-side padding on filter dropdowns",
+      "viewports": ["mobile", "desktop"],
+      "regions": [
+        {
+          "selector": "main select:first-of-type",
+          "beforeColor": "blue",
+          "afterColor": "blue",
+          "label": "Chevron padding"
+        }
+      ]
+    },
+    {
+      "id": "header-spacing",
+      "commit": "106f641",
+      "route": "/grid-operators",
+      "description": "Header height h-14 → h-12",
+      "viewports": ["desktop"],
+      "regions": [
+        {
+          "selector": "header",
+          "beforeColor": "blue",
+          "afterColor": "blue",
+          "label": "h-14 → h-12"
+        }
+      ]
+    },
+    {
+      "id": "badge-variants",
+      "commit": "111ef3f",
+      "route": "/grid-operators",
+      "description": "Badge color mapping fix",
+      "waitFor": "main",
+      "viewports": ["desktop"],
+      "regions": [
+        {
+          "selector": "table tbody tr:nth-child(1) td:nth-child(2) span",
+          "beforeColor": "orange",
+          "afterColor": "orange",
+          "label": "Badge variant"
+        }
+      ]
+    },
+    {
+      "id": "logo-redesign",
+      "commit": "ecdc89b",
+      "route": "/",
+      "description": "G-in-C dendritic graph logo",
+      "viewports": ["desktop"],
+      "regions": [
+        {
+          "selector": "header a[href='/'] svg",
+          "beforeColor": "red",
+          "afterColor": "green",
+          "label": "Logo mark"
+        }
+      ]
+    },
+    {
+      "id": "sort-chevrons",
+      "commit": "37b1abc",
+      "route": "/power-plants",
+      "description": "Sort direction ▲/▼ in dropdown labels",
+      "waitFor": "main",
+      "viewports": ["desktop"],
+      "regions": [
+        {
+          "selector": "[class*='DataControls'] select, [data-testid='sort-select']",
+          "beforeColor": "blue",
+          "afterColor": "blue",
+          "label": "Sort ▲/▼"
+        }
+      ]
+    },
+    {
+      "id": "grid-operators-new-columns",
+      "commit": "ba4b06d",
+      "route": "/grid-operators",
+      "description": "EIA ID, BA Code, NERC, Website columns",
+      "waitFor": "main",
+      "viewports": ["desktop"],
+      "regions": [
+        {
+          "selector": "table thead",
+          "beforeColor": "red",
+          "afterColor": "green",
+          "label": "New columns"
+        }
+      ]
+    },
+    {
+      "id": "changelog-tabs",
+      "commit": "ea227b5",
+      "route": "/changelog",
+      "description": "Data Changes / Site Updates tab distinction",
+      "viewports": ["tablet", "desktop"],
+      "regions": [
+        {
+          "selector": "main > div",
+          "beforeColor": "red",
+          "afterColor": "green",
+          "label": "Tab bar + search"
+        }
+      ]
+    },
+    {
+      "id": "filter-stacking",
+      "commit": "049d059",
+      "route": "/ev-charging",
+      "description": "Filters stack vertically at narrow viewports",
+      "waitFor": "main",
+      "viewports": ["mobile"],
+      "regions": [
+        {
+          "selector": "select:first-of-type",
+          "beforeColor": "yellow",
+          "afterColor": "yellow",
+          "label": "Filter stacking"
+        }
+      ]
+    },
+    {
+      "id": "name-clamping",
+      "commit": "7c9de2f",
+      "route": "/grid-operators",
+      "description": "2-line name clamp on mobile",
+      "waitFor": "main",
+      "viewports": ["mobile"],
+      "regions": [
+        {
+          "selector": "table tbody tr:nth-child(1) td:nth-child(1)",
+          "beforeColor": "blue",
+          "afterColor": "blue",
+          "label": "Name clamping"
+        }
+      ]
+    },
+    {
+      "id": "mobile-menu",
+      "commit": "c206859",
+      "route": "/grid-operators",
+      "description": "Mobile menu active state + hover backgrounds",
+      "viewports": ["mobile"],
+      "actions": [
+        { "type": "click", "selector": "header button[aria-label='Toggle menu']" }
+      ],
+      "regions": [
+        {
+          "selector": "header nav",
+          "beforeColor": "blue",
+          "afterColor": "blue",
+          "label": "Mobile menu"
+        }
+      ]
+    }
+  ]
+}
diff --git a/scripts/visual-regression/capture-vr.ts b/scripts/visual-regression/capture-vr.ts
new file mode 100644
index 00000000..b7a6d578
--- /dev/null
+++ b/scripts/visual-regression/capture-vr.ts
@@ -0,0 +1,380 @@
+#!/usr/bin/env npx tsx
+/**
+ * capture-vr.ts — Main orchestrator for visual regression capture pipeline.
+ *
+ * Usage:
+ *   npx tsx scripts/visual-regression/capture-vr.ts [options]
+ *
+ * Options:
+ *   --base-ref <ref>       Base git ref (default: main)
+ *   --captures <id,id>     Only run specific capture IDs
+ *   --viewports <vp,vp>    Only run specific viewports
+ *   --skip-capture         Skip screenshot capture, re-process existing
+ *   --skip-base            Skip base capture (use existing base screenshots)
+ *   --skip-compose         Skip composition (just capture + annotate)
+ *   --output <dir>         Output directory (default: .visual-regression)
+ */
+
+import { execSync, spawn, type ChildProcess } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { captureAll, type ManifestCapture, type ManifestViewport } from "./playwright-capture";
+import { annotateImage, type AnnotationColor, type AnnotationRegion } from "./annotate";
+import { composeComparison } from "./compose";
+import { computeDiff } from "./diff";
+
+// ── Config ──────────────────────────────────────────────────────────────────
+
+interface Manifest {
+	version: string;
+	baseRef: string;
+	prRef: string;
+	devServer: {
+		command: string;
+		readyPattern: string;
+		basePort: number;
+		prPort: number;
+	};
+	viewports: ManifestViewport[];
+	captures: ManifestCapture[];
+}
+
+interface CatalogEntry {
+	id: string;
+	commit?: string;
+	description: string;
+	viewports: Record<string, {
+		before: string;
+		after: string;
+		comparison: string;
+		diffPercent: number;
+	}>;
+}
+
+// ── Args ────────────────────────────────────────────────────────────────────
+
+function parseArgs() {
+	const args = process.argv.slice(2);
+	const opts = {
+		baseRef: "main",
+		captures: null as string[] | null,
+		viewports: null as string[] | null,
+		skipCapture: false,
+		skipBase: false,
+		skipCompose: false,
+		output: ".visual-regression",
+	};
+
+	for (let i = 0; i < args.length; i++) {
+		switch (args[i]) {
+			case "--base-ref": opts.baseRef = args[++i]; break;
+			case "--captures": opts.captures = args[++i].split(","); break;
+			case "--viewports": opts.viewports = args[++i].split(","); break;
+			case "--skip-capture": opts.skipCapture = true; break;
+			case "--skip-base": opts.skipBase = true; break;
+			case "--skip-compose": opts.skipCompose = true; break;
+			case "--output": opts.output = args[++i]; break;
+		}
+	}
+	return opts;
+}
+
+// ── Server Management ───────────────────────────────────────────────────────
+
+function startDevServer(cwd: string, port: number): ChildProcess {
+	const child = spawn("npx", ["next", "dev", "-p", String(port)], {
+		cwd,
+		stdio: ["ignore", "pipe", "pipe"],
+		env: { ...process.env, PORT: String(port), NODE_ENV: "development" },
+		shell: true,
+	});
+	return child;
+}
+
+async function waitForServer(port: number, timeoutMs = 60_000): Promise<void> {
+	const start = Date.now();
+	const url = `http://localhost:${port}`;
+	while (Date.now() - start < timeoutMs) {
+		try {
+			const res = await fetch(url);
+			if (res.ok || res.status === 404) return; // server is up
+		} catch { /* not ready yet */ }
+		await new Promise((r) => setTimeout(r, 1000));
+	}
+	throw new Error(`Server on port ${port} did not start within ${timeoutMs}ms`);
+}
+
+function killServer(child: ChildProcess) {
+	if (child.pid) {
+		try {
+			process.kill(-child.pid, "SIGTERM");
+		} catch {
+			child.kill("SIGTERM");
+		}
+	}
+}
+
+// ── Worktree ────────────────────────────────────────────────────────────────
+
+function createWorktree(baseRef: string): string {
+	const worktreePath = "/tmp/cg-vr-base";
+	try { execSync(`git worktree remove ${worktreePath} --force 2>/dev/null`); } catch { /* ok */ }
+	execSync(`git worktree add ${worktreePath} ${baseRef}`, { stdio: "inherit" });
+
+	// Install deps in worktree if package-lock exists
+	const lockPath = path.join(worktreePath, "package-lock.json");
+	if (fs.existsSync(lockPath)) {
+		console.log("📦 Installing deps in base worktree...");
+		execSync("npm install --prefer-offline", { cwd: worktreePath, stdio: "inherit" });
+	}
+	return worktreePath;
+}
+
+function removeWorktree() {
+	try { execSync("git worktree remove /tmp/cg-vr-base --force 2>/dev/null"); } catch { /* ok */ }
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+	const opts = parseArgs();
+	const repoRoot = execSync("git rev-parse --show-toplevel").toString().trim();
+	const manifestPath = path.join(repoRoot, "scripts/visual-regression/capture-manifest.json");
+	const manifest: Manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+
+	// Apply filters
+	let captures = manifest.captures;
+	if (opts.captures) {
+		captures = captures.filter((c) => opts.captures!.includes(c.id));
+	}
+	const viewports = opts.viewports
+		? manifest.viewports.filter((v) => opts.viewports!.includes(v.name))
+		: manifest.viewports;
+
+	// Output dirs
+	const outDir = path.resolve(repoRoot, opts.output);
+	const dirs = {
+		before: path.join(outDir, "captures/before"),
+		after: path.join(outDir, "captures/after"),
+		annotated: path.join(outDir, "captures/annotated"),
+		comparisons: path.join(outDir, "captures/comparisons"),
+		diffs: path.join(outDir, "captures/diffs"),
+	};
+	for (const d of Object.values(dirs)) fs.mkdirSync(d, { recursive: true });
+
+	console.log(`\n🔍 Visual Regression Capture`);
+	console.log(`   Base: ${opts.baseRef}`);
+	console.log(`   Captures: ${captures.length}`);
+	console.log(`   Viewports: ${viewports.map((v) => v.name).join(", ")}`);
+	console.log(`   Output: ${outDir}\n`);
+
+	// ── Phase 1: Capture ──────────────────────────────────────────────────
+
+	let baseServer: ChildProcess | null = null;
+	let prServer: ChildProcess | null = null;
+	let worktreePath: string | null = null;
+
+	if (!opts.skipCapture) {
+		try {
+			// Start PR server (current branch)
+			console.log("🚀 Starting PR dev server on port", manifest.devServer.prPort);
+			prServer = startDevServer(repoRoot, manifest.devServer.prPort);
+
+			if (!opts.skipBase) {
+				// Create worktree for base
+				console.log(`🌳 Creating worktree for ${opts.baseRef}...`);
+				worktreePath = createWorktree(opts.baseRef);
+
+				// Start base server
+				console.log("🚀 Starting base dev server on port", manifest.devServer.basePort);
+				baseServer = startDevServer(worktreePath, manifest.devServer.basePort);
+			}
+
+			// Wait for servers
+			console.log("⏳ Waiting for servers...");
+			const waits = [waitForServer(manifest.devServer.prPort)];
+			if (!opts.skipBase) waits.push(waitForServer(manifest.devServer.basePort));
+			await Promise.all(waits);
+			console.log("✅ Servers ready\n");
+
+			// Capture AFTER (PR state)
+			console.log("📸 Capturing AFTER screenshots...");
+			await captureAll(
+				`http://localhost:${manifest.devServer.prPort}`,
+				captures,
+				viewports,
+				dirs.after,
+				"after",
+			);
+
+			// Capture BEFORE (base state)
+			if (!opts.skipBase) {
+				console.log("\n📸 Capturing BEFORE screenshots...");
+				await captureAll(
+					`http://localhost:${manifest.devServer.basePort}`,
+					captures,
+					viewports,
+					dirs.before,
+					"before",
+				);
+			}
+		} finally {
+			// Cleanup servers
+			if (prServer) killServer(prServer);
+			if (baseServer) killServer(baseServer);
+			if (worktreePath) {
+				console.log("\n🧹 Cleaning up worktree...");
+				removeWorktree();
+			}
+		}
+	}
+
+	// ── Phase 2: Annotate ─────────────────────────────────────────────────
+
+	console.log("\n🎨 Annotating screenshots...");
+	const catalog: CatalogEntry[] = [];
+
+	for (const capture of captures) {
+		const vpNames = capture.viewports ?? viewports.map((v) => v.name);
+		const activeVps = viewports.filter((v) => vpNames.includes(v.name));
+		const entry: CatalogEntry = {
+			id: capture.id,
+			commit: capture.commit,
+			description: capture.description,
+			viewports: {},
+		};
+
+		for (const vp of activeVps) {
+			const stem = `${capture.id}-${vp.name}`;
+			const beforeRaw = path.join(dirs.before, `${stem}.png`);
+			const afterRaw = path.join(dirs.after, `${stem}.png`);
+			const beforeRegionsPath = path.join(dirs.before, `${stem}.regions.json`);
+			const afterRegionsPath = path.join(dirs.after, `${stem}.regions.json`);
+
+			const beforeAnnotated = path.join(dirs.annotated, `${stem}-before.png`);
+			const afterAnnotated = path.join(dirs.annotated, `${stem}-after.png`);
+			const comparisonPath = path.join(dirs.comparisons, `${stem}.png`);
+			const diffPath = path.join(dirs.diffs, `${stem}-diff.png`);
+
+			// Load region data
+			let beforeRegions: AnnotationRegion[] = [];
+			let afterRegions: AnnotationRegion[] = [];
+
+			if (fs.existsSync(beforeRegionsPath)) {
+				const raw = JSON.parse(fs.readFileSync(beforeRegionsPath, "utf-8"));
+				beforeRegions = raw
+					.filter((r: any) => r.bbox)
+					.map((r: any) => ({
+						bbox: r.bbox,
+						color: r.beforeColor as AnnotationColor,
+						label: r.label,
+					}));
+			}
+			if (fs.existsSync(afterRegionsPath)) {
+				const raw = JSON.parse(fs.readFileSync(afterRegionsPath, "utf-8"));
+				afterRegions = raw
+					.filter((r: any) => r.bbox)
+					.map((r: any) => ({
+						bbox: r.bbox,
+						color: r.afterColor as AnnotationColor,
+						label: r.label,
+					}));
+			}
+
+			// Annotate
+			if (fs.existsSync(beforeRaw)) {
+				await annotateImage(beforeRaw, beforeRegions, beforeAnnotated);
+			}
+			if (fs.existsSync(afterRaw)) {
+				await annotateImage(afterRaw, afterRegions, afterAnnotated);
+			}
+
+			// Diff
+			let diffPercent = 0;
+			if (fs.existsSync(beforeRaw) && fs.existsSync(afterRaw)) {
+				const result = computeDiff(beforeRaw, afterRaw, diffPath);
+				diffPercent = result.diffPercent;
+				console.log(`  📊 ${stem}: ${diffPercent}% pixel diff`);
+			}
+
+			// Compose
+			if (!opts.skipCompose && fs.existsSync(beforeAnnotated) && fs.existsSync(afterAnnotated)) {
+				const title = `${capture.description} · ${vp.name} (${vp.width}px)`;
+				await composeComparison(beforeAnnotated, afterAnnotated, title, comparisonPath);
+				console.log(`  ✓ ${stem} composed`);
+			}
+
+			entry.viewports[vp.name] = {
+				before: path.relative(outDir, beforeAnnotated),
+				after: path.relative(outDir, afterAnnotated),
+				comparison: path.relative(outDir, comparisonPath),
+				diffPercent,
+			};
+		}
+
+		catalog.push(entry);
+	}
+
+	// ── Phase 3: Output ───────────────────────────────────────────────────
+
+	// Write catalog
+	const catalogPath = path.join(outDir, "catalog.json");
+	fs.writeFileSync(catalogPath, JSON.stringify({
+		generatedAt: new Date().toISOString(),
+		baseRef: opts.baseRef,
+		prRef: manifest.prRef,
+		comparisons: catalog,
+	}, null, 2));
+
+	// Generate markdown table
+	const mdLines = [
+		"## Visual Regression Report\n",
+		`Generated: ${new Date().toISOString()}  `,
+		`Base: \`${opts.baseRef}\` · PR: \`${manifest.prRef}\`\n`,
+		"| Change | Viewport | Diff % | Comparison |",
+		"|--------|----------|--------|------------|",
+	];
+
+	for (const entry of catalog) {
+		for (const [vpName, data] of Object.entries(entry.viewports)) {
+			const compPath = data.comparison;
+			mdLines.push(
+				`| ${entry.description} | ${vpName} | ${data.diffPercent}% | [View](${compPath}) |`,
+			);
+		}
+	}
+
+	mdLines.push(
+		"",
+		"<details>",
+		"<summary>Diff summary</summary>",
+		"",
+		"| Capture | Viewport | Pixel diff % |",
+		"|---------|----------|-------------|",
+	);
+	for (const entry of catalog) {
+		for (const [vpName, data] of Object.entries(entry.viewports)) {
+			mdLines.push(`| ${entry.id} | ${vpName} | ${data.diffPercent}% |`);
+		}
+	}
+	mdLines.push("", "</details>");
+
+	const mdPath = path.join(outDir, "pr-screenshots.md");
+	fs.writeFileSync(mdPath, mdLines.join("\n"));
+
+	console.log(`\n✅ Done!`);
+	console.log(`   Catalog: ${catalogPath}`);
+	console.log(`   Report:  ${mdPath}`);
+	console.log(`   Images:  ${dirs.comparisons}/`);
+
+	// Summary
+	const totalDiffs = catalog.flatMap((c) => Object.values(c.viewports));
+	const changed = totalDiffs.filter((d) => d.diffPercent > 0);
+	console.log(`\n   ${totalDiffs.length} captures, ${changed.length} with visual changes`);
+}
+
+main().catch((err) => {
+	console.error("❌ Fatal:", err);
+	removeWorktree();
+	process.exit(1);
+});
diff --git a/scripts/visual-regression/compose.ts b/scripts/visual-regression/compose.ts
new file mode 100644
index 00000000..c2e5170c
--- /dev/null
+++ b/scripts/visual-regression/compose.ts
@@ -0,0 +1,103 @@
+/**
+ * compose.ts — Combine annotated BEFORE and AFTER images into a single
+ * side-by-side comparison image with title bar and footer.
+ *
+ * Layout:
+ * ┌──────────────────────────────────────────┐
+ * │  TITLE BAR (description · viewport)      │
+ * ├───────────────────┬──────────────────────┤
+ * │                   │                      │
+ * │     BEFORE        │      AFTER           │
+ * │                   │                      │
+ * ├───────────────────┴──────────────────────┤
+ * │  FOOTER: BEFORE (main) │ AFTER (PR)      │
+ * └──────────────────────────────────────────┘
+ */
+
+import sharp from "sharp";
+
+const TITLE_H = 48;
+const FOOTER_H = 28;
+const DIVIDER_W = 2;
+const BG_COLOR = { r: 255, g: 255, b: 255, alpha: 1 };
+const TITLE_BG = "#f8f9fb";
+const FOOTER_BG = "#f1f5f9";
+const DIVIDER_COLOR = { r: 203, g: 213, b: 225, alpha: 1 };
+
+function escapeXml(s: string): string {
+	return s
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;");
+}
+
+export async function composeComparison(
+	beforePath: string,
+	afterPath: string,
+	title: string,
+	outputPath: string,
+	options: { baseLabel?: string; prLabel?: string } = {},
+): Promise<void> {
+	const baseLabel = options.baseLabel ?? "BEFORE (main)";
+	const prLabel = options.prLabel ?? "AFTER (PR)";
+
+	const [bBuf, aBuf] = await Promise.all([
+		sharp(beforePath).toBuffer({ resolveWithObject: true }),
+		sharp(afterPath).toBuffer({ resolveWithObject: true }),
+	]);
+
+	const bW = bBuf.info.width;
+	const bH = bBuf.info.height;
+	const aW = aBuf.info.width;
+	const aH = aBuf.info.height;
+	const maxH = Math.max(bH, aH);
+
+	const totalW = bW + aW + DIVIDER_W;
+	const totalH = maxH + TITLE_H + FOOTER_H;
+
+	const titleSvg = Buffer.from(`
+<svg width="${totalW}" height="${TITLE_H}" xmlns="http://www.w3.org/2000/svg">
+  <rect width="100%" height="100%" fill="${TITLE_BG}"/>
+  <line x1="0" y1="${TITLE_H - 1}" x2="${totalW}" y2="${TITLE_H - 1}" stroke="#e2e8f0" stroke-width="1"/>
+  <text x="${totalW / 2}" y="30" text-anchor="middle" font-size="13" font-weight="600" fill="#1f2937" font-family="system-ui,-apple-system,sans-serif">${escapeXml(title)}</text>
+</svg>`);
+
+	const footerSvg = Buffer.from(`
+<svg width="${totalW}" height="${FOOTER_H}" xmlns="http://www.w3.org/2000/svg">
+  <rect width="100%" height="100%" fill="${FOOTER_BG}"/>
+  <line x1="0" y1="0" x2="${totalW}" y2="0" stroke="#e2e8f0" stroke-width="1"/>
+  <text x="${bW / 2}" y="18" text-anchor="middle" font-size="11" fill="#64748b" font-family="system-ui,-apple-system,sans-serif">${escapeXml(baseLabel)}</text>
+  <line x1="${bW + 1}" y1="4" x2="${bW + 1}" y2="24" stroke="#cbd5e1" stroke-width="1"/>
+  <text x="${bW + DIVIDER_W + aW / 2}" y="18" text-anchor="middle" font-size="11" fill="#64748b" font-family="system-ui,-apple-system,sans-serif">${escapeXml(prLabel)}</text>
+</svg>`);
+
+	const dividerBuf = await sharp({
+		create: {
+			width: DIVIDER_W,
+			height: maxH,
+			channels: 4,
+			background: DIVIDER_COLOR,
+		},
+	})
+		.png()
+		.toBuffer();
+
+	await sharp({
+		create: {
+			width: totalW,
+			height: totalH,
+			channels: 4,
+			background: BG_COLOR,
+		},
+	})
+		.composite([
+			{ input: titleSvg, top: 0, left: 0 },
+			{ input: bBuf.data, top: TITLE_H, left: 0 },
+			{ input: dividerBuf, top: TITLE_H, left: bW },
+			{ input: aBuf.data, top: TITLE_H, left: bW + DIVIDER_W },
+			{ input: footerSvg, top: TITLE_H + maxH, left: 0 },
+		])
+		.png()
+		.toFile(outputPath);
+}
diff --git a/scripts/visual-regression/diff.ts b/scripts/visual-regression/diff.ts
new file mode 100644
index 00000000..cf92c581
--- /dev/null
+++ b/scripts/visual-regression/diff.ts
@@ -0,0 +1,73 @@
+/**
+ * diff.ts — Pixel-level diff detection between two screenshots.
+ * Uses pixelmatch (the same engine Playwright uses internally).
+ */
+
+import fs from "node:fs";
+import { PNG } from "pngjs";
+import pixelmatch from "pixelmatch";
+
+export interface DiffResult {
+	diffPixels: number;
+	totalPixels: number;
+	diffPercent: number;
+	diffImagePath: string | null;
+}
+
+/**
+ * Compare two PNG images and produce a diff overlay.
+ * Returns { diffPixels, diffPercent, diffImagePath }.
+ */
+export function computeDiff(
+	beforePath: string,
+	afterPath: string,
+	diffPath: string | null = null,
+): DiffResult {
+	const img1 = PNG.sync.read(fs.readFileSync(beforePath));
+	const img2 = PNG.sync.read(fs.readFileSync(afterPath));
+
+	// Use the larger dimensions (pad smaller image conceptually)
+	const width = Math.max(img1.width, img2.width);
+	const height = Math.max(img1.height, img2.height);
+
+	// Resize data buffers if images differ in size
+	const data1 = padImageData(img1, width, height);
+	const data2 = padImageData(img2, width, height);
+
+	const diff = new PNG({ width, height });
+
+	const diffPixels = pixelmatch(data1, data2, diff.data, width, height, {
+		threshold: 0.1,
+		includeAA: false,
+	});
+
+	const totalPixels = width * height;
+	const diffPercent = Number(((diffPixels / totalPixels) * 100).toFixed(2));
+
+	let outPath: string | null = null;
+	if (diffPath) {
+		fs.writeFileSync(diffPath, PNG.sync.write(diff));
+		outPath = diffPath;
+	}
+
+	return { diffPixels, totalPixels, diffPercent, diffImagePath: outPath };
+}
+
+/** Pad image data to target dimensions with transparent pixels. */
+function padImageData(
+	img: PNG,
+	targetW: number,
+	targetH: number,
+): Uint8Array {
+	if (img.width === targetW && img.height === targetH) {
+		return new Uint8Array(img.data.buffer);
+	}
+
+	const buf = new Uint8Array(targetW * targetH * 4);
+	for (let y = 0; y < img.height; y++) {
+		const srcOffset = y * img.width * 4;
+		const dstOffset = y * targetW * 4;
+		buf.set(img.data.slice(srcOffset, srcOffset + img.width * 4), dstOffset);
+	}
+	return buf;
+}
diff --git a/scripts/visual-regression/file-route-map.json b/scripts/visual-regression/file-route-map.json
new file mode 100644
index 00000000..88bcb9ca
--- /dev/null
+++ b/scripts/visual-regression/file-route-map.json
@@ -0,0 +1,26 @@
+{
+  "app/(shell)/grid-operators/page.tsx": ["/grid-operators"],
+  "app/(shell)/grid-operators/[slug]/page.tsx": ["/grid-operators/pacific-gas-and-electric"],
+  "app/(shell)/power-plants/page.tsx": ["/power-plants"],
+  "app/(shell)/transmission-lines/page.tsx": ["/transmission-lines"],
+  "app/(shell)/ev-charging/page.tsx": ["/ev-charging"],
+  "app/(shell)/pricing-nodes/page.tsx": ["/pricing-nodes"],
+  "app/(shell)/changelog/page.tsx": ["/changelog"],
+  "app/(shell)/explore/page.tsx": ["/explore"],
+  "app/(shell)/about/page.tsx": ["/about"],
+  "app/(shell)/page.tsx": ["/"],
+  "components/TopBar.tsx": ["*"],
+  "components/ShellLayoutClient.tsx": ["*"],
+  "components/GlobalSearch.tsx": ["*"],
+  "components/SearchInput.tsx": ["/grid-operators", "/power-plants", "/transmission-lines", "/ev-charging", "/pricing-nodes"],
+  "components/DataSourceLink.tsx": ["/grid-operators", "/power-plants", "/transmission-lines", "/ev-charging", "/pricing-nodes"],
+  "components/explorer/ExplorerMap.tsx": ["/explore"],
+  "components/explorer/ExplorerShell.tsx": ["/explore"],
+  "components/explorer/ExplorerTabBar.tsx": ["/explore"],
+  "components/explorer/panels/*": ["/explore"],
+  "lib/formatting.ts": ["/grid-operators", "/explore"],
+  "lib/geo.ts": ["/explore", "/grid-operators/pacific-gas-and-electric"],
+  "app/globals.css": ["*"],
+  "public/logo.svg": ["*"],
+  "public/favicon.svg": ["*"]
+}
diff --git a/scripts/visual-regression/playwright-capture.ts b/scripts/visual-regression/playwright-capture.ts
new file mode 100644
index 00000000..1a9a7c25
--- /dev/null
+++ b/scripts/visual-regression/playwright-capture.ts
@@ -0,0 +1,195 @@
+/**
+ * playwright-capture.ts — Navigate to routes and capture screenshots
+ * with bounding box coordinates for annotation regions.
+ */
+
+import { chromium, type Browser, type BrowserContext } from "playwright";
+import fs from "node:fs";
+import path from "node:path";
+import type { BBox } from "./annotate";
+
+export interface ManifestViewport {
+	name: string;
+	width: number;
+	height: number;
+}
+
+export interface ManifestRegion {
+	selector: string;
+	beforeColor: string;
+	afterColor: string;
+	label: string;
+}
+
+export interface ManifestAction {
+	type: "click" | "hover" | "fill";
+	selector: string;
+	value?: string;
+}
+
+export interface ManifestCapture {
+	id: string;
+	commit?: string;
+	route: string;
+	description: string;
+	waitFor?: string;
+	viewports?: string[];
+	actions?: ManifestAction[];
+	regions: ManifestRegion[];
+}
+
+export interface CaptureResult {
+	captureId: string;
+	viewport: string;
+	screenshotPath: string;
+	regions: Array<{
+		selector: string;
+		bbox: BBox | null;
+		beforeColor: string;
+		afterColor: string;
+		label: string;
+	}>;
+}
+
+const ANIMATION_DISABLE_CSS = `
+*, *::before, *::after {
+  animation-duration: 0s !important;
+  animation-delay: 0s !important;
+  transition-duration: 0s !important;
+  transition-delay: 0s !important;
+  scroll-behavior: auto !important;
+}
+`;
+
+export async function captureAll(
+	baseUrl: string,
+	captures: ManifestCapture[],
+	allViewports: ManifestViewport[],
+	outputDir: string,
+	label: string,
+): Promise<CaptureResult[]> {
+	fs.mkdirSync(outputDir, { recursive: true });
+
+	const browser = await chromium.launch({ headless: true });
+	const results: CaptureResult[] = [];
+
+	try {
+		for (const capture of captures) {
+			const viewportNames = capture.viewports ?? allViewports.map((v) => v.name);
+			const viewports = allViewports.filter((v) =>
+				viewportNames.includes(v.name),
+			);
+
+			for (const vp of viewports) {
+				const context = await browser.newContext({
+					viewport: { width: vp.width, height: vp.height },
+					deviceScaleFactor: 1,
+					colorScheme: "light",
+				});
+				const page = await context.newPage();
+
+				try {
+					// Navigate
+					await page.goto(`${baseUrl}${capture.route}`, {
+						waitUntil: "domcontentloaded",
+						timeout: 30_000,
+					});
+					// Allow hydration and client-side data loading
+					await page.waitForTimeout(2500);
+
+					// Wait for specific content
+					if (capture.waitFor) {
+						await page
+							.waitForSelector(capture.waitFor, { timeout: 10_000 })
+							.catch(() => {
+								console.warn(
+									`  ⚠ waitFor selector not found: ${capture.waitFor} (${capture.id}/${vp.name})`,
+								);
+							});
+					}
+
+					// Small settle delay for rendering
+					await page.waitForTimeout(500);
+
+					// Disable animations
+					await page.addStyleTag({ content: ANIMATION_DISABLE_CSS });
+					await page.waitForTimeout(100);
+
+					// Execute pre-capture actions
+					if (capture.actions) {
+						for (const action of capture.actions) {
+							const loc = page.locator(action.selector).first();
+							if (await loc.isVisible().catch(() => false)) {
+								if (action.type === "click") await loc.click();
+								else if (action.type === "hover") await loc.hover();
+								else if (action.type === "fill" && action.value)
+									await loc.fill(action.value);
+								await page.waitForTimeout(300);
+							}
+						}
+					}
+
+					// Capture screenshot
+					const filename = `${capture.id}-${vp.name}.png`;
+					const screenshotPath = path.join(outputDir, filename);
+					await page.screenshot({ path: screenshotPath, fullPage: false });
+
+					// Record bounding boxes for each region
+					const regionResults = [];
+					for (const region of capture.regions) {
+						let bbox: BBox | null = null;
+						try {
+							const loc = page.locator(region.selector).first();
+							if (await loc.isVisible().catch(() => false)) {
+								const rawBox = await loc.boundingBox();
+								if (rawBox) {
+									bbox = {
+										x: rawBox.x,
+										y: rawBox.y,
+										width: rawBox.width,
+										height: rawBox.height,
+									};
+								}
+							}
+						} catch {
+							// selector not found — bbox stays null
+						}
+						regionResults.push({
+							selector: region.selector,
+							bbox,
+							beforeColor: region.beforeColor,
+							afterColor: region.afterColor,
+							label: region.label,
+						});
+					}
+
+					// Save region data
+					const regionsPath = path.join(
+						outputDir,
+						`${capture.id}-${vp.name}.regions.json`,
+					);
+					fs.writeFileSync(regionsPath, JSON.stringify(regionResults, null, 2));
+
+					results.push({
+						captureId: capture.id,
+						viewport: vp.name,
+						screenshotPath,
+						regions: regionResults,
+					});
+
+					console.log(`  ✓ ${label}/${capture.id}/${vp.name}`);
+				} catch (err) {
+					console.error(
+						`  ✗ ${label}/${capture.id}/${vp.name}: ${err instanceof Error ? err.message : err}`,
+					);
+				} finally {
+					await context.close();
+				}
+			}
+		}
+	} finally {
+		await browser.close();
+	}
+
+	return results;
+}

From 3494749bd75ff6e8f3b6e9cffbb0e9d4cb8fef3d Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 20:48:36 -0400
Subject: [PATCH 29/41] fix(vr): resolve 404 in BEFORE captures by running
 prebuild in worktree

The base worktree was missing public/data/ (gitignored, generated by
prebuild), causing all data pages to 404. Now syncs data/ and runs
prebuild in the worktree. Also improves content readiness detection.
---
 scripts/visual-regression/capture-vr.ts       | 51 ++++++++++++++++---
 .../visual-regression/playwright-capture.ts   | 24 ++++++---
 2 files changed, 60 insertions(+), 15 deletions(-)

diff --git a/scripts/visual-regression/capture-vr.ts b/scripts/visual-regression/capture-vr.ts
index b7a6d578..0b8d7a1e 100644
--- a/scripts/visual-regression/capture-vr.ts
+++ b/scripts/visual-regression/capture-vr.ts
@@ -91,16 +91,27 @@ function startDevServer(cwd: string, port: number): ChildProcess {
 	return child;
 }
 
-async function waitForServer(port: number, timeoutMs = 60_000): Promise<void> {
+async function waitForServer(port: number, timeoutMs = 90_000): Promise<void> {
 	const start = Date.now();
 	const url = `http://localhost:${port}`;
+	let lastStatus = 0;
 	while (Date.now() - start < timeoutMs) {
 		try {
 			const res = await fetch(url);
-			if (res.ok || res.status === 404) return; // server is up
+			lastStatus = res.status;
+			if (res.ok) return; // server is up and serving content
+			// 404 means server is up but route doesn't exist yet (still compiling)
+			// Keep waiting for a 200
+			if (res.status === 404) {
+				// Check if it's a Next.js compilation wait — try the root
+				const rootRes = await fetch(url);
+				if (rootRes.ok) return;
+			}
 		} catch { /* not ready yet */ }
-		await new Promise((r) => setTimeout(r, 1000));
+		await new Promise((r) => setTimeout(r, 1500));
 	}
+	// Accept 404 as "server is up" after timeout — some routes may genuinely not exist on base
+	if (lastStatus === 404) return;
 	throw new Error(`Server on port ${port} did not start within ${timeoutMs}ms`);
 }
 
@@ -116,17 +127,35 @@ function killServer(child: ChildProcess) {
 
 // ── Worktree ────────────────────────────────────────────────────────────────
 
-function createWorktree(baseRef: string): string {
+function createWorktree(baseRef: string, repoRoot: string): string {
 	const worktreePath = "/tmp/cg-vr-base";
 	try { execSync(`git worktree remove ${worktreePath} --force 2>/dev/null`); } catch { /* ok */ }
 	execSync(`git worktree add ${worktreePath} ${baseRef}`, { stdio: "inherit" });
 
-	// Install deps in worktree if package-lock exists
+	// Install deps in worktree
 	const lockPath = path.join(worktreePath, "package-lock.json");
 	if (fs.existsSync(lockPath)) {
 		console.log("📦 Installing deps in base worktree...");
 		execSync("npm install --prefer-offline", { cwd: worktreePath, stdio: "inherit" });
 	}
+
+	// Copy data/ directory into worktree so pages can load
+	// The data/ dir is git-tracked but public/data/ is .gitignore'd (generated by prebuild)
+	const srcData = path.join(repoRoot, "data");
+	const dstData = path.join(worktreePath, "data");
+	if (fs.existsSync(srcData) && !fs.existsSync(path.join(dstData, "utilities.json"))) {
+		console.log("📂 Syncing data/ directory to worktree...");
+		execSync(`cp -r "${srcData}"/* "${dstData}/"`, { stdio: "inherit" });
+	}
+
+	// Run prebuild to copy data into public/data/ for the dev server
+	console.log("🔨 Running prebuild in base worktree...");
+	try {
+		execSync("npm run prebuild", { cwd: worktreePath, stdio: "inherit", timeout: 30_000 });
+	} catch (err) {
+		console.warn("⚠ prebuild failed in worktree (non-fatal, some pages may 404)");
+	}
+
 	return worktreePath;
 }
 
@@ -176,14 +205,22 @@ async function main() {
 
 	if (!opts.skipCapture) {
 		try {
+			// Run prebuild for PR server to ensure public/data/ is populated
+			console.log("🔨 Running prebuild for PR branch...");
+			try {
+				execSync("npm run prebuild", { cwd: repoRoot, stdio: "inherit", timeout: 30_000 });
+			} catch {
+				console.warn("⚠ prebuild failed for PR branch (non-fatal)");
+			}
+
 			// Start PR server (current branch)
 			console.log("🚀 Starting PR dev server on port", manifest.devServer.prPort);
 			prServer = startDevServer(repoRoot, manifest.devServer.prPort);
 
 			if (!opts.skipBase) {
-				// Create worktree for base
+				// Create worktree for base (with data + prebuild)
 				console.log(`🌳 Creating worktree for ${opts.baseRef}...`);
-				worktreePath = createWorktree(opts.baseRef);
+				worktreePath = createWorktree(opts.baseRef, repoRoot);
 
 				// Start base server
 				console.log("🚀 Starting base dev server on port", manifest.devServer.basePort);
diff --git a/scripts/visual-regression/playwright-capture.ts b/scripts/visual-regression/playwright-capture.ts
index 1a9a7c25..f6fb9e61 100644
--- a/scripts/visual-regression/playwright-capture.ts
+++ b/scripts/visual-regression/playwright-capture.ts
@@ -89,18 +89,16 @@ export async function captureAll(
 				const page = await context.newPage();
 
 				try {
-					// Navigate
+					// Navigate — use load (not networkidle which hangs on long-poll)
 					await page.goto(`${baseUrl}${capture.route}`, {
-						waitUntil: "domcontentloaded",
+						waitUntil: "load",
 						timeout: 30_000,
 					});
-					// Allow hydration and client-side data loading
-					await page.waitForTimeout(2500);
 
-					// Wait for specific content
+					// Wait for specific content selector if provided
 					if (capture.waitFor) {
 						await page
-							.waitForSelector(capture.waitFor, { timeout: 10_000 })
+							.waitForSelector(capture.waitFor, { timeout: 15_000 })
 							.catch(() => {
 								console.warn(
 									`  ⚠ waitFor selector not found: ${capture.waitFor} (${capture.id}/${vp.name})`,
@@ -108,8 +106,18 @@ export async function captureAll(
 							});
 					}
 
-					// Small settle delay for rendering
-					await page.waitForTimeout(500);
+					// Wait for data-driven content to render:
+					// Try to detect that the page has loaded real content by waiting
+					// for either a table row, a card, or a list item to appear
+					await page.waitForSelector(
+						'[class*="DataTable"] [role="row"], table tr, [class*="Card"], main h1',
+						{ timeout: 10_000 },
+					).catch(() => {
+						// Fallback: just wait a fixed amount
+					});
+
+					// Final settle for any remaining renders / transitions
+					await page.waitForTimeout(1500);
 
 					// Disable animations
 					await page.addStyleTag({ content: ANIMATION_DISABLE_CSS });

From ffecf2ff3227b3f5152ef0a134a65bc667e451e0 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Mon, 16 Mar 2026 23:01:16 -0400
Subject: [PATCH 30/41] fix(vr): change ports to 4100/4101 and add
 port-availability check

Port 3100 was occupied by another process, causing all BEFORE captures
to show 404 pages or a different app's UI. Moved to 4100/4101 and added
a pre-flight port check that fails fast with a clear error message.
---
 .../visual-regression/capture-manifest.json    |  4 ++--
 scripts/visual-regression/capture-vr.ts        | 18 ++++++++++++++++++
 2 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/scripts/visual-regression/capture-manifest.json b/scripts/visual-regression/capture-manifest.json
index 6937d648..b2539963 100644
--- a/scripts/visual-regression/capture-manifest.json
+++ b/scripts/visual-regression/capture-manifest.json
@@ -6,8 +6,8 @@
   "devServer": {
     "command": "npx next dev",
     "readyPattern": "Ready in",
-    "basePort": 3100,
-    "prPort": 3101
+    "basePort": 4100,
+    "prPort": 4101
   },
   "viewports": [
     { "name": "mobile", "width": 375, "height": 812 },
diff --git a/scripts/visual-regression/capture-vr.ts b/scripts/visual-regression/capture-vr.ts
index 0b8d7a1e..c3ca46dc 100644
--- a/scripts/visual-regression/capture-vr.ts
+++ b/scripts/visual-regression/capture-vr.ts
@@ -81,6 +81,19 @@ function parseArgs() {
 
 // ── Server Management ───────────────────────────────────────────────────────
 
+async function ensurePortFree(port: number): Promise<void> {
+	try {
+		const res = await fetch(`http://localhost:${port}`);
+		throw new Error(
+			`Port ${port} is already in use (got HTTP ${res.status}). ` +
+			`Kill the process on that port or change devServer ports in capture-manifest.json.`,
+		);
+	} catch (err) {
+		if (err instanceof Error && err.message.startsWith("Port ")) throw err;
+		// fetch failed = port is free, good
+	}
+}
+
 function startDevServer(cwd: string, port: number): ChildProcess {
 	const child = spawn("npx", ["next", "dev", "-p", String(port)], {
 		cwd,
@@ -213,6 +226,11 @@ async function main() {
 				console.warn("⚠ prebuild failed for PR branch (non-fatal)");
 			}
 
+			// Ensure ports are free before starting
+			console.log("🔌 Checking port availability...");
+			await ensurePortFree(manifest.devServer.prPort);
+			if (!opts.skipBase) await ensurePortFree(manifest.devServer.basePort);
+
 			// Start PR server (current branch)
 			console.log("🚀 Starting PR dev server on port", manifest.devServer.prPort);
 			prServer = startDevServer(repoRoot, manifest.devServer.prPort);

From bf7378b0fd682112709388ecfda97682910fb1b4 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Tue, 17 Mar 2026 08:08:41 -0400
Subject: [PATCH 31/41] =?UTF-8?q?Revert=20"feat:=20redesign=20CommonGrid?=
 =?UTF-8?q?=20logo=20=E2=80=94=20G-in-C=20with=20dendritic=20graph"?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This reverts commit ecdc89b6874c645df16fc176ffb46a9de4a61f6c.
---
 components/TopBar.tsx | 38 ++++++++++++++++++--------------------
 public/favicon.svg    | 38 ++++++++++++++++++--------------------
 public/logo.svg       | 38 ++++++++++++++++++--------------------
 3 files changed, 54 insertions(+), 60 deletions(-)

diff --git a/components/TopBar.tsx b/components/TopBar.tsx
index bc3cffb9..857e307c 100644
--- a/components/TopBar.tsx
+++ b/components/TopBar.tsx
@@ -51,26 +51,24 @@ export function TopBar({ navigation }: TopBarProps) {
         <div className="flex items-center gap-8">
           <Link href="/" className="flex items-center gap-2">
             <svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg" className="h-6 w-6 text-text-heading">
-              {/* C arc — open on the right */}
-              <path d="M22 10 A10 10 0 1 0 22 22" stroke="currentColor" strokeWidth="2" strokeLinecap="round" fill="none" />
-              {/* G crossbar */}
-              <line x1="22" y1="16" x2="16" y2="16" stroke="currentColor" strokeWidth="2" strokeLinecap="round" />
-              {/* Dendritic edges — tree-graph connections */}
-              <line x1="16" y1="16" x2="10" y2="8" stroke="currentColor" strokeWidth="0.8" opacity="0.5" />
-              <line x1="16" y1="16" x2="7" y2="14" stroke="currentColor" strokeWidth="0.8" opacity="0.5" />
-              <line x1="16" y1="16" x2="7" y2="20" stroke="currentColor" strokeWidth="0.8" opacity="0.5" />
-              <line x1="16" y1="16" x2="10" y2="25" stroke="currentColor" strokeWidth="0.8" opacity="0.5" />
-              <line x1="10" y1="8" x2="14" y2="6" stroke="currentColor" strokeWidth="0.8" opacity="0.5" />
-              <line x1="10" y1="25" x2="14" y2="27" stroke="currentColor" strokeWidth="0.8" opacity="0.5" />
-              {/* Network nodes */}
-              <circle cx="16" cy="16" r="1.8" fill="currentColor" />
-              <circle cx="10" cy="8" r="1.3" fill="currentColor" />
-              <circle cx="7" cy="14" r="1.3" fill="currentColor" />
-              <circle cx="7" cy="20" r="1.3" fill="currentColor" />
-              <circle cx="10" cy="25" r="1.3" fill="currentColor" />
-              <circle cx="14" cy="6" r="1.0" fill="currentColor" />
-              <circle cx="14" cy="27" r="1.0" fill="currentColor" />
-              <circle cx="22" cy="16" r="1.3" fill="currentColor" />
+              {/* Top row */}
+              <circle cx="4" cy="4" r="1.8" fill="currentColor"/>
+              <circle cx="12" cy="4" r="1.8" fill="currentColor"/>
+              <circle cx="20" cy="4" r="1.8" fill="currentColor"/>
+              <circle cx="28" cy="4" r="1.8" fill="currentColor"/>
+              {/* Left col */}
+              <circle cx="4" cy="12" r="1.8" fill="currentColor"/>
+              <circle cx="4" cy="20" r="1.8" fill="currentColor"/>
+              {/* Right col */}
+              <circle cx="28" cy="12" r="1.8" fill="currentColor"/>
+              <circle cx="28" cy="20" r="1.8" fill="currentColor"/>
+              {/* Bottom row */}
+              <circle cx="4" cy="28" r="1.8" fill="currentColor"/>
+              <circle cx="12" cy="28" r="1.8" fill="currentColor"/>
+              <circle cx="20" cy="28" r="1.8" fill="currentColor"/>
+              <circle cx="28" cy="28" r="1.8" fill="currentColor"/>
+              {/* Solid center square */}
+              <rect x="11" y="11" width="10" height="10" rx="1.5" fill="currentColor"/>
             </svg>
             <span className="text-sm font-semibold text-text-heading tracking-tight">
               CommonGrid
diff --git a/public/favicon.svg b/public/favicon.svg
index b00e0cb1..7a829826 100644
--- a/public/favicon.svg
+++ b/public/favicon.svg
@@ -1,22 +1,20 @@
 <svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
-  <!-- C arc — open on the right -->
-  <path d="M22 10 A10 10 0 1 0 22 22" stroke="#111111" stroke-width="2" stroke-linecap="round" fill="none" />
-  <!-- G crossbar -->
-  <line x1="22" y1="16" x2="16" y2="16" stroke="#111111" stroke-width="2" stroke-linecap="round" />
-  <!-- Dendritic edges -->
-  <line x1="16" y1="16" x2="10" y2="8" stroke="#111111" stroke-width="0.8" opacity="0.5" />
-  <line x1="16" y1="16" x2="7" y2="14" stroke="#111111" stroke-width="0.8" opacity="0.5" />
-  <line x1="16" y1="16" x2="7" y2="20" stroke="#111111" stroke-width="0.8" opacity="0.5" />
-  <line x1="16" y1="16" x2="10" y2="25" stroke="#111111" stroke-width="0.8" opacity="0.5" />
-  <line x1="10" y1="8" x2="14" y2="6" stroke="#111111" stroke-width="0.8" opacity="0.5" />
-  <line x1="10" y1="25" x2="14" y2="27" stroke="#111111" stroke-width="0.8" opacity="0.5" />
-  <!-- Network nodes -->
-  <circle cx="16" cy="16" r="1.8" fill="#111111" />
-  <circle cx="10" cy="8" r="1.3" fill="#111111" />
-  <circle cx="7" cy="14" r="1.3" fill="#111111" />
-  <circle cx="7" cy="20" r="1.3" fill="#111111" />
-  <circle cx="10" cy="25" r="1.3" fill="#111111" />
-  <circle cx="14" cy="6" r="1.0" fill="#111111" />
-  <circle cx="14" cy="27" r="1.0" fill="#111111" />
-  <circle cx="22" cy="16" r="1.3" fill="#111111" />
+  <!-- Top row -->
+  <circle cx="4" cy="4" r="1.8" fill="#111111"/>
+  <circle cx="12" cy="4" r="1.8" fill="#111111"/>
+  <circle cx="20" cy="4" r="1.8" fill="#111111"/>
+  <circle cx="28" cy="4" r="1.8" fill="#111111"/>
+  <!-- Left col -->
+  <circle cx="4" cy="12" r="1.8" fill="#111111"/>
+  <circle cx="4" cy="20" r="1.8" fill="#111111"/>
+  <!-- Right col -->
+  <circle cx="28" cy="12" r="1.8" fill="#111111"/>
+  <circle cx="28" cy="20" r="1.8" fill="#111111"/>
+  <!-- Bottom row -->
+  <circle cx="4" cy="28" r="1.8" fill="#111111"/>
+  <circle cx="12" cy="28" r="1.8" fill="#111111"/>
+  <circle cx="20" cy="28" r="1.8" fill="#111111"/>
+  <circle cx="28" cy="28" r="1.8" fill="#111111"/>
+  <!-- Solid center square -->
+  <rect x="11" y="11" width="10" height="10" rx="1.5" fill="#111111"/>
 </svg>
diff --git a/public/logo.svg b/public/logo.svg
index 270a049f..7a829826 100644
--- a/public/logo.svg
+++ b/public/logo.svg
@@ -1,22 +1,20 @@
 <svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
-  <!-- C arc — open on the right -->
-  <path d="M22 10 A10 10 0 1 0 22 22" stroke="#111111" stroke-width="2" stroke-linecap="round" fill="none" />
-  <!-- G crossbar -->
-  <line x1="22" y1="16" x2="16" y2="16" stroke="#111111" stroke-width="2" stroke-linecap="round" />
-  <!-- Dendritic edges — tree-graph connections -->
-  <line x1="16" y1="16" x2="10" y2="8" stroke="#111111" stroke-width="0.8" opacity="0.5" />
-  <line x1="16" y1="16" x2="7" y2="14" stroke="#111111" stroke-width="0.8" opacity="0.5" />
-  <line x1="16" y1="16" x2="7" y2="20" stroke="#111111" stroke-width="0.8" opacity="0.5" />
-  <line x1="16" y1="16" x2="10" y2="25" stroke="#111111" stroke-width="0.8" opacity="0.5" />
-  <line x1="10" y1="8" x2="14" y2="6" stroke="#111111" stroke-width="0.8" opacity="0.5" />
-  <line x1="10" y1="25" x2="14" y2="27" stroke="#111111" stroke-width="0.8" opacity="0.5" />
-  <!-- Network nodes -->
-  <circle cx="16" cy="16" r="1.8" fill="#111111" />
-  <circle cx="10" cy="8" r="1.3" fill="#111111" />
-  <circle cx="7" cy="14" r="1.3" fill="#111111" />
-  <circle cx="7" cy="20" r="1.3" fill="#111111" />
-  <circle cx="10" cy="25" r="1.3" fill="#111111" />
-  <circle cx="14" cy="6" r="1.0" fill="#111111" />
-  <circle cx="14" cy="27" r="1.0" fill="#111111" />
-  <circle cx="22" cy="16" r="1.3" fill="#111111" />
+  <!-- Top row -->
+  <circle cx="4" cy="4" r="1.8" fill="#111111"/>
+  <circle cx="12" cy="4" r="1.8" fill="#111111"/>
+  <circle cx="20" cy="4" r="1.8" fill="#111111"/>
+  <circle cx="28" cy="4" r="1.8" fill="#111111"/>
+  <!-- Left col -->
+  <circle cx="4" cy="12" r="1.8" fill="#111111"/>
+  <circle cx="4" cy="20" r="1.8" fill="#111111"/>
+  <!-- Right col -->
+  <circle cx="28" cy="12" r="1.8" fill="#111111"/>
+  <circle cx="28" cy="20" r="1.8" fill="#111111"/>
+  <!-- Bottom row -->
+  <circle cx="4" cy="28" r="1.8" fill="#111111"/>
+  <circle cx="12" cy="28" r="1.8" fill="#111111"/>
+  <circle cx="20" cy="28" r="1.8" fill="#111111"/>
+  <circle cx="28" cy="28" r="1.8" fill="#111111"/>
+  <!-- Solid center square -->
+  <rect x="11" y="11" width="10" height="10" rx="1.5" fill="#111111"/>
 </svg>

From 534f46d46a0138e533d10cde63e4347b9a0b9c78 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Tue, 17 Mar 2026 08:39:15 -0400
Subject: [PATCH 32/41] docs: rewrite visual regression system as as-built
 reference with mermaid diagrams

---
 .claude/edges.md                   |    8 +-
 .codex/edges.md                    |    8 +-
 .cursor/rules/edges-components.mdc |   10 +-
 docs/visual-regression-system.md   | 1407 +++++++---------------------
 4 files changed, 330 insertions(+), 1103 deletions(-)

diff --git a/.claude/edges.md b/.claude/edges.md
index 1bb35952..791ffca5 100644
--- a/.claude/edges.md
+++ b/.claude/edges.md
@@ -223,7 +223,7 @@ The following components are available from @texturehq/edges:
 - **SparklineCell** - Component
 - **SplitPane** - Child panels
 - **StaticMap** - Component
-- **StatList** - Additional CSS classes */ className?: string; }  // Helpers  // Use the centralized formatting utility function formatValue(value: StatValue, formatter?: StatFormatter): React.ReactNode { // If value is already a React element, return it as-is (skip formatting) if (React.isValidElement(value)) { return value; }  return formatComponentValue({ value, formatter, emptyClassName: "text-text-muted", emptyText: "—", }); }  function getTone(item: StatItem): StatTone | undefined { // Check thresholds first if (item.thresholds && item.value !== null && item.value !== undefined) { for (const threshold of item.thresholds) { if (threshold.when(item.value)) { return threshold.tone; } } }  // Fall back to explicit tone return item.tone; }  const toneColors: Record<StatTone, string> = { neutral: "text-text-body", success: "text-feedback-success", warning: "text-feedback-warning", error: "text-feedback-error", info: "text-feedback-info", };  // StatRow Component  // Constants for auto-truncation const LONG_STRING_THRESHOLD = 24; const LONG_STRING_TRUNCATE_LENGTH = 20;  function StatRow({ item, dense, valueAlign, }: { item: StatItem; dense?: boolean; valueAlign?: StatAlign; }) { const tone = getTone(item); const toneClass = tone ? toneColors[tone] : ""; const isStacked = item.stackOnMobile;  // Check if this is a long string that should be auto-truncated on mobile const isLongString = typeof item.value === "string" && item.value.length > LONG_STRING_THRESHOLD && !item.formatter && !React.isValidElement(item.value);  // Get the formatted value (used for both truncated and full display) const formattedValue = formatValue(item.value, item.formatter);  // Get the truncated value for mobile display // Note: We cast to string here because isLongString already verifies typeof item.value === "string" const truncatedValue = isLongString ? truncateMiddle(item.value as string, LONG_STRING_TRUNCATE_LENGTH) : null;  const textToCopy = typeof item.copyable === "function" ? item.copyable(item.value) : String(item.value);  // PII data attributes (only set if both piiType and piiEntity are provided) const piiAttrs = item.piiType && item.piiEntity ? { "data-pii-type": item.piiType, "data-pii-entity": item.piiEntity, } : {};  // For long strings, render both truncated (mobile) and full (desktop) versions // CSS classes control which is visible based on screen size // Tooltip content is wrapped in span with PII attributes to allow masking by Curtain extension const hasPiiAttrs = Object.keys(piiAttrs).length > 0; const valueDisplay = isLongString ? ( <> {/* Mobile: show truncated with tooltip */} <Tooltip content={hasPiiAttrs ? <span {...piiAttrs}>{String(item.value)}</span> : String(item.value)} > <span className={twMerge("md:hidden", item.href ? "hover:underline cursor-pointer" : "")} {...piiAttrs} > {truncatedValue} </span> </Tooltip> {/* Desktop: show full value
+- **StatList** - Additional CSS classes */ className?: string; }  // Helpers  // Use the centralized formatting utility function formatValue(value: StatValue, formatter?: StatFormatter): React.ReactNode { // If value is already a React element, return it as-is (skip formatting) if (React.isValidElement(value)) { return value; }  return formatComponentValue({ value, formatter, emptyClassName: "text-text-muted", emptyText: "—", }); }  function getTone(item: StatItem): StatTone | undefined { // Check thresholds first if (item.thresholds && item.value !== null && item.value !== undefined) { for (const threshold of item.thresholds) { if (threshold.when(item.value)) { return threshold.tone; } } }  // Fall back to explicit tone return item.tone; }  const toneColors: Record<StatTone, string> = { neutral: "text-text-body", success: "text-feedback-success", warning: "text-feedback-warning", error: "text-feedback-error", info: "text-feedback-info", };  // StatRow Component  // Constants for auto-truncation const LONG_STRING_THRESHOLD = 24; const LONG_STRING_TRUNCATE_LENGTH = 20;  function StatRow({ item, dense, valueAlign }: { item: StatItem; dense?: boolean; valueAlign?: StatAlign }) { const tone = getTone(item); const toneClass = tone ? toneColors[tone] : ""; const isStacked = item.stackOnMobile;  // Check if this is a long string that should be auto-truncated on mobile const isLongString = typeof item.value === "string" && item.value.length > LONG_STRING_THRESHOLD && !item.formatter && !React.isValidElement(item.value);  // Get the formatted value (used for both truncated and full display) const formattedValue = formatValue(item.value, item.formatter);  // Get the truncated value for mobile display // Note: We cast to string here because isLongString already verifies typeof item.value === "string" const truncatedValue = isLongString ? truncateMiddle(item.value as string, LONG_STRING_TRUNCATE_LENGTH) : null;  const textToCopy = typeof item.copyable === "function" ? item.copyable(item.value) : String(item.value);  // PII data attributes (only set if both piiType and piiEntity are provided) const piiAttrs = item.piiType && item.piiEntity ? { "data-pii-type": item.piiType, "data-pii-entity": item.piiEntity, } : {};  // For long strings, render both truncated (mobile) and full (desktop) versions // CSS classes control which is visible based on screen size // Tooltip content is wrapped in span with PII attributes to allow masking by Curtain extension const hasPiiAttrs = Object.keys(piiAttrs).length > 0; const valueDisplay = isLongString ? ( <> {/* Mobile: show truncated with tooltip */} <Tooltip content={hasPiiAttrs ? <span {...piiAttrs}>{String(item.value)}</span> : String(item.value)}> <span className={twMerge("md:hidden", item.href ? "hover:underline cursor-pointer" : "")} {...piiAttrs}> {truncatedValue} </span> </Tooltip> {/* Desktop: show full value
 - **Switch** - Switch  Toggle switch component for binary on/off states. Provides an accessible alternative to checkboxes for settings and preferences.
 - **Tab** - Tab trigger element.
 - **TabList** - TabList container.
@@ -451,7 +451,7 @@ Renders an Edges Button. When `href` is provided, renders a link-styled button u
 - `size: Size`
 - `style: React.CSSProperties`
 - `target: string`
-- `variant: | "default" | "brand" | "secondary" | "destructive" | "icon" | "link" | "unstyled" | "ghost" | "primary"`
+- `variant: "default" | "brand" | "secondary" | "destructive" | "icon" | "link" | "unstyled" | "ghost" | "primary"`
 
 ---
 
@@ -1438,7 +1438,7 @@ PlaceSearch  Location search component with autocomplete; emits a `Place` value
 
 **Props:**
 - `autoFocus: boolean`
-- `countryRestrictions: string[]; // Array of ISO 3166-1 alpha-2 country codes proximity?: "ip" | [number, number]; // Either "ip" for IP-based location or [longitude, latitude] coordinates hideCountry?: boolean; // Hide country from results (useful when using countryRestrictions) showIcon?: boolean; // Show location type icons in results (default: true) className?: string`
+- `countryRestrictions: string[]; // Array of ISO 3166-1 alpha-2 country codes proximity?: "ip" | [number, number]; // Either "ip" for IP-based location or [longitude, latitude] coordinates hideCountry?: boolean; // Hide country from results (useful when using countryRestrictions) showIcon?: boolean; // Show location type icons in results (default: true) useMobileTray?: boolean; // Whether to use a Tray (bottom sheet) on mobile devices instead of a Popover (default: true) className?: string`
 - `defaultFilter: (textValue: string, inputValue: string) => boolean`
 - `defaultSelectedKey: Key | null`
 - `description: string`
@@ -1763,7 +1763,7 @@ Child panels
 ---
 
 #### StatList
-Additional CSS classes */ className?: string; }  // Helpers  // Use the centralized formatting utility function formatValue(value: StatValue, formatter?: StatFormatter): React.ReactNode { // If value is already a React element, return it as-is (skip formatting) if (React.isValidElement(value)) { return value; }  return formatComponentValue({ value, formatter, emptyClassName: "text-text-muted", emptyText: "—", }); }  function getTone(item: StatItem): StatTone | undefined { // Check thresholds first if (item.thresholds && item.value !== null && item.value !== undefined) { for (const threshold of item.thresholds) { if (threshold.when(item.value)) { return threshold.tone; } } }  // Fall back to explicit tone return item.tone; }  const toneColors: Record<StatTone, string> = { neutral: "text-text-body", success: "text-feedback-success", warning: "text-feedback-warning", error: "text-feedback-error", info: "text-feedback-info", };  // StatRow Component  // Constants for auto-truncation const LONG_STRING_THRESHOLD = 24; const LONG_STRING_TRUNCATE_LENGTH = 20;  function StatRow({ item, dense, valueAlign, }: { item: StatItem; dense?: boolean; valueAlign?: StatAlign; }) { const tone = getTone(item); const toneClass = tone ? toneColors[tone] : ""; const isStacked = item.stackOnMobile;  // Check if this is a long string that should be auto-truncated on mobile const isLongString = typeof item.value === "string" && item.value.length > LONG_STRING_THRESHOLD && !item.formatter && !React.isValidElement(item.value);  // Get the formatted value (used for both truncated and full display) const formattedValue = formatValue(item.value, item.formatter);  // Get the truncated value for mobile display // Note: We cast to string here because isLongString already verifies typeof item.value === "string" const truncatedValue = isLongString ? truncateMiddle(item.value as string, LONG_STRING_TRUNCATE_LENGTH) : null;  const textToCopy = typeof item.copyable === "function" ? item.copyable(item.value) : String(item.value);  // PII data attributes (only set if both piiType and piiEntity are provided) const piiAttrs = item.piiType && item.piiEntity ? { "data-pii-type": item.piiType, "data-pii-entity": item.piiEntity, } : {};  // For long strings, render both truncated (mobile) and full (desktop) versions // CSS classes control which is visible based on screen size // Tooltip content is wrapped in span with PII attributes to allow masking by Curtain extension const hasPiiAttrs = Object.keys(piiAttrs).length > 0; const valueDisplay = isLongString ? ( <> {/* Mobile: show truncated with tooltip */} <Tooltip content={hasPiiAttrs ? <span {...piiAttrs}>{String(item.value)}</span> : String(item.value)} > <span className={twMerge("md:hidden", item.href ? "hover:underline cursor-pointer" : "")} {...piiAttrs} > {truncatedValue} </span> </Tooltip> {/* Desktop: show full value
+Additional CSS classes */ className?: string; }  // Helpers  // Use the centralized formatting utility function formatValue(value: StatValue, formatter?: StatFormatter): React.ReactNode { // If value is already a React element, return it as-is (skip formatting) if (React.isValidElement(value)) { return value; }  return formatComponentValue({ value, formatter, emptyClassName: "text-text-muted", emptyText: "—", }); }  function getTone(item: StatItem): StatTone | undefined { // Check thresholds first if (item.thresholds && item.value !== null && item.value !== undefined) { for (const threshold of item.thresholds) { if (threshold.when(item.value)) { return threshold.tone; } } }  // Fall back to explicit tone return item.tone; }  const toneColors: Record<StatTone, string> = { neutral: "text-text-body", success: "text-feedback-success", warning: "text-feedback-warning", error: "text-feedback-error", info: "text-feedback-info", };  // StatRow Component  // Constants for auto-truncation const LONG_STRING_THRESHOLD = 24; const LONG_STRING_TRUNCATE_LENGTH = 20;  function StatRow({ item, dense, valueAlign }: { item: StatItem; dense?: boolean; valueAlign?: StatAlign }) { const tone = getTone(item); const toneClass = tone ? toneColors[tone] : ""; const isStacked = item.stackOnMobile;  // Check if this is a long string that should be auto-truncated on mobile const isLongString = typeof item.value === "string" && item.value.length > LONG_STRING_THRESHOLD && !item.formatter && !React.isValidElement(item.value);  // Get the formatted value (used for both truncated and full display) const formattedValue = formatValue(item.value, item.formatter);  // Get the truncated value for mobile display // Note: We cast to string here because isLongString already verifies typeof item.value === "string" const truncatedValue = isLongString ? truncateMiddle(item.value as string, LONG_STRING_TRUNCATE_LENGTH) : null;  const textToCopy = typeof item.copyable === "function" ? item.copyable(item.value) : String(item.value);  // PII data attributes (only set if both piiType and piiEntity are provided) const piiAttrs = item.piiType && item.piiEntity ? { "data-pii-type": item.piiType, "data-pii-entity": item.piiEntity, } : {};  // For long strings, render both truncated (mobile) and full (desktop) versions // CSS classes control which is visible based on screen size // Tooltip content is wrapped in span with PII attributes to allow masking by Curtain extension const hasPiiAttrs = Object.keys(piiAttrs).length > 0; const valueDisplay = isLongString ? ( <> {/* Mobile: show truncated with tooltip */} <Tooltip content={hasPiiAttrs ? <span {...piiAttrs}>{String(item.value)}</span> : String(item.value)}> <span className={twMerge("md:hidden", item.href ? "hover:underline cursor-pointer" : "")} {...piiAttrs}> {truncatedValue} </span> </Tooltip> {/* Desktop: show full value
 
 **Imports:**
 - `import { StatList } from "@texturehq/edges"`
diff --git a/.codex/edges.md b/.codex/edges.md
index 1bb35952..791ffca5 100644
--- a/.codex/edges.md
+++ b/.codex/edges.md
@@ -223,7 +223,7 @@ The following components are available from @texturehq/edges:
 - **SparklineCell** - Component
 - **SplitPane** - Child panels
 - **StaticMap** - Component
-- **StatList** - Additional CSS classes */ className?: string; }  // Helpers  // Use the centralized formatting utility function formatValue(value: StatValue, formatter?: StatFormatter): React.ReactNode { // If value is already a React element, return it as-is (skip formatting) if (React.isValidElement(value)) { return value; }  return formatComponentValue({ value, formatter, emptyClassName: "text-text-muted", emptyText: "—", }); }  function getTone(item: StatItem): StatTone | undefined { // Check thresholds first if (item.thresholds && item.value !== null && item.value !== undefined) { for (const threshold of item.thresholds) { if (threshold.when(item.value)) { return threshold.tone; } } }  // Fall back to explicit tone return item.tone; }  const toneColors: Record<StatTone, string> = { neutral: "text-text-body", success: "text-feedback-success", warning: "text-feedback-warning", error: "text-feedback-error", info: "text-feedback-info", };  // StatRow Component  // Constants for auto-truncation const LONG_STRING_THRESHOLD = 24; const LONG_STRING_TRUNCATE_LENGTH = 20;  function StatRow({ item, dense, valueAlign, }: { item: StatItem; dense?: boolean; valueAlign?: StatAlign; }) { const tone = getTone(item); const toneClass = tone ? toneColors[tone] : ""; const isStacked = item.stackOnMobile;  // Check if this is a long string that should be auto-truncated on mobile const isLongString = typeof item.value === "string" && item.value.length > LONG_STRING_THRESHOLD && !item.formatter && !React.isValidElement(item.value);  // Get the formatted value (used for both truncated and full display) const formattedValue = formatValue(item.value, item.formatter);  // Get the truncated value for mobile display // Note: We cast to string here because isLongString already verifies typeof item.value === "string" const truncatedValue = isLongString ? truncateMiddle(item.value as string, LONG_STRING_TRUNCATE_LENGTH) : null;  const textToCopy = typeof item.copyable === "function" ? item.copyable(item.value) : String(item.value);  // PII data attributes (only set if both piiType and piiEntity are provided) const piiAttrs = item.piiType && item.piiEntity ? { "data-pii-type": item.piiType, "data-pii-entity": item.piiEntity, } : {};  // For long strings, render both truncated (mobile) and full (desktop) versions // CSS classes control which is visible based on screen size // Tooltip content is wrapped in span with PII attributes to allow masking by Curtain extension const hasPiiAttrs = Object.keys(piiAttrs).length > 0; const valueDisplay = isLongString ? ( <> {/* Mobile: show truncated with tooltip */} <Tooltip content={hasPiiAttrs ? <span {...piiAttrs}>{String(item.value)}</span> : String(item.value)} > <span className={twMerge("md:hidden", item.href ? "hover:underline cursor-pointer" : "")} {...piiAttrs} > {truncatedValue} </span> </Tooltip> {/* Desktop: show full value
+- **StatList** - Additional CSS classes */ className?: string; }  // Helpers  // Use the centralized formatting utility function formatValue(value: StatValue, formatter?: StatFormatter): React.ReactNode { // If value is already a React element, return it as-is (skip formatting) if (React.isValidElement(value)) { return value; }  return formatComponentValue({ value, formatter, emptyClassName: "text-text-muted", emptyText: "—", }); }  function getTone(item: StatItem): StatTone | undefined { // Check thresholds first if (item.thresholds && item.value !== null && item.value !== undefined) { for (const threshold of item.thresholds) { if (threshold.when(item.value)) { return threshold.tone; } } }  // Fall back to explicit tone return item.tone; }  const toneColors: Record<StatTone, string> = { neutral: "text-text-body", success: "text-feedback-success", warning: "text-feedback-warning", error: "text-feedback-error", info: "text-feedback-info", };  // StatRow Component  // Constants for auto-truncation const LONG_STRING_THRESHOLD = 24; const LONG_STRING_TRUNCATE_LENGTH = 20;  function StatRow({ item, dense, valueAlign }: { item: StatItem; dense?: boolean; valueAlign?: StatAlign }) { const tone = getTone(item); const toneClass = tone ? toneColors[tone] : ""; const isStacked = item.stackOnMobile;  // Check if this is a long string that should be auto-truncated on mobile const isLongString = typeof item.value === "string" && item.value.length > LONG_STRING_THRESHOLD && !item.formatter && !React.isValidElement(item.value);  // Get the formatted value (used for both truncated and full display) const formattedValue = formatValue(item.value, item.formatter);  // Get the truncated value for mobile display // Note: We cast to string here because isLongString already verifies typeof item.value === "string" const truncatedValue = isLongString ? truncateMiddle(item.value as string, LONG_STRING_TRUNCATE_LENGTH) : null;  const textToCopy = typeof item.copyable === "function" ? item.copyable(item.value) : String(item.value);  // PII data attributes (only set if both piiType and piiEntity are provided) const piiAttrs = item.piiType && item.piiEntity ? { "data-pii-type": item.piiType, "data-pii-entity": item.piiEntity, } : {};  // For long strings, render both truncated (mobile) and full (desktop) versions // CSS classes control which is visible based on screen size // Tooltip content is wrapped in span with PII attributes to allow masking by Curtain extension const hasPiiAttrs = Object.keys(piiAttrs).length > 0; const valueDisplay = isLongString ? ( <> {/* Mobile: show truncated with tooltip */} <Tooltip content={hasPiiAttrs ? <span {...piiAttrs}>{String(item.value)}</span> : String(item.value)}> <span className={twMerge("md:hidden", item.href ? "hover:underline cursor-pointer" : "")} {...piiAttrs}> {truncatedValue} </span> </Tooltip> {/* Desktop: show full value
 - **Switch** - Switch  Toggle switch component for binary on/off states. Provides an accessible alternative to checkboxes for settings and preferences.
 - **Tab** - Tab trigger element.
 - **TabList** - TabList container.
@@ -451,7 +451,7 @@ Renders an Edges Button. When `href` is provided, renders a link-styled button u
 - `size: Size`
 - `style: React.CSSProperties`
 - `target: string`
-- `variant: | "default" | "brand" | "secondary" | "destructive" | "icon" | "link" | "unstyled" | "ghost" | "primary"`
+- `variant: "default" | "brand" | "secondary" | "destructive" | "icon" | "link" | "unstyled" | "ghost" | "primary"`
 
 ---
 
@@ -1438,7 +1438,7 @@ PlaceSearch  Location search component with autocomplete; emits a `Place` value
 
 **Props:**
 - `autoFocus: boolean`
-- `countryRestrictions: string[]; // Array of ISO 3166-1 alpha-2 country codes proximity?: "ip" | [number, number]; // Either "ip" for IP-based location or [longitude, latitude] coordinates hideCountry?: boolean; // Hide country from results (useful when using countryRestrictions) showIcon?: boolean; // Show location type icons in results (default: true) className?: string`
+- `countryRestrictions: string[]; // Array of ISO 3166-1 alpha-2 country codes proximity?: "ip" | [number, number]; // Either "ip" for IP-based location or [longitude, latitude] coordinates hideCountry?: boolean; // Hide country from results (useful when using countryRestrictions) showIcon?: boolean; // Show location type icons in results (default: true) useMobileTray?: boolean; // Whether to use a Tray (bottom sheet) on mobile devices instead of a Popover (default: true) className?: string`
 - `defaultFilter: (textValue: string, inputValue: string) => boolean`
 - `defaultSelectedKey: Key | null`
 - `description: string`
@@ -1763,7 +1763,7 @@ Child panels
 ---
 
 #### StatList
-Additional CSS classes */ className?: string; }  // Helpers  // Use the centralized formatting utility function formatValue(value: StatValue, formatter?: StatFormatter): React.ReactNode { // If value is already a React element, return it as-is (skip formatting) if (React.isValidElement(value)) { return value; }  return formatComponentValue({ value, formatter, emptyClassName: "text-text-muted", emptyText: "—", }); }  function getTone(item: StatItem): StatTone | undefined { // Check thresholds first if (item.thresholds && item.value !== null && item.value !== undefined) { for (const threshold of item.thresholds) { if (threshold.when(item.value)) { return threshold.tone; } } }  // Fall back to explicit tone return item.tone; }  const toneColors: Record<StatTone, string> = { neutral: "text-text-body", success: "text-feedback-success", warning: "text-feedback-warning", error: "text-feedback-error", info: "text-feedback-info", };  // StatRow Component  // Constants for auto-truncation const LONG_STRING_THRESHOLD = 24; const LONG_STRING_TRUNCATE_LENGTH = 20;  function StatRow({ item, dense, valueAlign, }: { item: StatItem; dense?: boolean; valueAlign?: StatAlign; }) { const tone = getTone(item); const toneClass = tone ? toneColors[tone] : ""; const isStacked = item.stackOnMobile;  // Check if this is a long string that should be auto-truncated on mobile const isLongString = typeof item.value === "string" && item.value.length > LONG_STRING_THRESHOLD && !item.formatter && !React.isValidElement(item.value);  // Get the formatted value (used for both truncated and full display) const formattedValue = formatValue(item.value, item.formatter);  // Get the truncated value for mobile display // Note: We cast to string here because isLongString already verifies typeof item.value === "string" const truncatedValue = isLongString ? truncateMiddle(item.value as string, LONG_STRING_TRUNCATE_LENGTH) : null;  const textToCopy = typeof item.copyable === "function" ? item.copyable(item.value) : String(item.value);  // PII data attributes (only set if both piiType and piiEntity are provided) const piiAttrs = item.piiType && item.piiEntity ? { "data-pii-type": item.piiType, "data-pii-entity": item.piiEntity, } : {};  // For long strings, render both truncated (mobile) and full (desktop) versions // CSS classes control which is visible based on screen size // Tooltip content is wrapped in span with PII attributes to allow masking by Curtain extension const hasPiiAttrs = Object.keys(piiAttrs).length > 0; const valueDisplay = isLongString ? ( <> {/* Mobile: show truncated with tooltip */} <Tooltip content={hasPiiAttrs ? <span {...piiAttrs}>{String(item.value)}</span> : String(item.value)} > <span className={twMerge("md:hidden", item.href ? "hover:underline cursor-pointer" : "")} {...piiAttrs} > {truncatedValue} </span> </Tooltip> {/* Desktop: show full value
+Additional CSS classes */ className?: string; }  // Helpers  // Use the centralized formatting utility function formatValue(value: StatValue, formatter?: StatFormatter): React.ReactNode { // If value is already a React element, return it as-is (skip formatting) if (React.isValidElement(value)) { return value; }  return formatComponentValue({ value, formatter, emptyClassName: "text-text-muted", emptyText: "—", }); }  function getTone(item: StatItem): StatTone | undefined { // Check thresholds first if (item.thresholds && item.value !== null && item.value !== undefined) { for (const threshold of item.thresholds) { if (threshold.when(item.value)) { return threshold.tone; } } }  // Fall back to explicit tone return item.tone; }  const toneColors: Record<StatTone, string> = { neutral: "text-text-body", success: "text-feedback-success", warning: "text-feedback-warning", error: "text-feedback-error", info: "text-feedback-info", };  // StatRow Component  // Constants for auto-truncation const LONG_STRING_THRESHOLD = 24; const LONG_STRING_TRUNCATE_LENGTH = 20;  function StatRow({ item, dense, valueAlign }: { item: StatItem; dense?: boolean; valueAlign?: StatAlign }) { const tone = getTone(item); const toneClass = tone ? toneColors[tone] : ""; const isStacked = item.stackOnMobile;  // Check if this is a long string that should be auto-truncated on mobile const isLongString = typeof item.value === "string" && item.value.length > LONG_STRING_THRESHOLD && !item.formatter && !React.isValidElement(item.value);  // Get the formatted value (used for both truncated and full display) const formattedValue = formatValue(item.value, item.formatter);  // Get the truncated value for mobile display // Note: We cast to string here because isLongString already verifies typeof item.value === "string" const truncatedValue = isLongString ? truncateMiddle(item.value as string, LONG_STRING_TRUNCATE_LENGTH) : null;  const textToCopy = typeof item.copyable === "function" ? item.copyable(item.value) : String(item.value);  // PII data attributes (only set if both piiType and piiEntity are provided) const piiAttrs = item.piiType && item.piiEntity ? { "data-pii-type": item.piiType, "data-pii-entity": item.piiEntity, } : {};  // For long strings, render both truncated (mobile) and full (desktop) versions // CSS classes control which is visible based on screen size // Tooltip content is wrapped in span with PII attributes to allow masking by Curtain extension const hasPiiAttrs = Object.keys(piiAttrs).length > 0; const valueDisplay = isLongString ? ( <> {/* Mobile: show truncated with tooltip */} <Tooltip content={hasPiiAttrs ? <span {...piiAttrs}>{String(item.value)}</span> : String(item.value)}> <span className={twMerge("md:hidden", item.href ? "hover:underline cursor-pointer" : "")} {...piiAttrs}> {truncatedValue} </span> </Tooltip> {/* Desktop: show full value
 
 **Imports:**
 - `import { StatList } from "@texturehq/edges"`
diff --git a/.cursor/rules/edges-components.mdc b/.cursor/rules/edges-components.mdc
index f900733a..dedbacbd 100644
--- a/.cursor/rules/edges-components.mdc
+++ b/.cursor/rules/edges-components.mdc
@@ -2,7 +2,7 @@
 alwaysApply: true
 ---
 
-## @texturehq/edges Components (v1.28.0)
+## @texturehq/edges Components (v1.28.2)
 
 ### Quick Reference
 
@@ -157,7 +157,7 @@ alwaysApply: true
 - **SparklineCell** - Component
 - **SplitPane** - Child panels
 - **StaticMap** - Component
-- **StatList** - Additional CSS classes */ className?: string; }  // Helpers  // Use the centralized formatting utility function formatValue(value: StatValue, formatter?: StatFormatter): React.ReactNode { // If value is already a React element, return it as-is (skip formatting) if (React.isValidElement(value)) { return value; }  return formatComponentValue({ value, formatter, emptyClassName: "text-text-muted", emptyText: "—", }); }  function getTone(item: StatItem): StatTone | undefined { // Check thresholds first if (item.thresholds && item.value !== null && item.value !== undefined) { for (const threshold of item.thresholds) { if (threshold.when(item.value)) { return threshold.tone; } } }  // Fall back to explicit tone return item.tone; }  const toneColors: Record<StatTone, string> = { neutral: "text-text-body", success: "text-feedback-success", warning: "text-feedback-warning", error: "text-feedback-error", info: "text-feedback-info", };  // StatRow Component  // Constants for auto-truncation const LONG_STRING_THRESHOLD = 24; const LONG_STRING_TRUNCATE_LENGTH = 20;  function StatRow({ item, dense, valueAlign, }: { item: StatItem; dense?: boolean; valueAlign?: StatAlign; }) { const tone = getTone(item); const toneClass = tone ? toneColors[tone] : ""; const isStacked = item.stackOnMobile;  // Check if this is a long string that should be auto-truncated on mobile const isLongString = typeof item.value === "string" && item.value.length > LONG_STRING_THRESHOLD && !item.formatter && !React.isValidElement(item.value);  // Get the formatted value (used for both truncated and full display) const formattedValue = formatValue(item.value, item.formatter);  // Get the truncated value for mobile display // Note: We cast to string here because isLongString already verifies typeof item.value === "string" const truncatedValue = isLongString ? truncateMiddle(item.value as string, LONG_STRING_TRUNCATE_LENGTH) : null;  const textToCopy = typeof item.copyable === "function" ? item.copyable(item.value) : String(item.value);  // PII data attributes (only set if both piiType and piiEntity are provided) const piiAttrs = item.piiType && item.piiEntity ? { "data-pii-type": item.piiType, "data-pii-entity": item.piiEntity, } : {};  // For long strings, render both truncated (mobile) and full (desktop) versions // CSS classes control which is visible based on screen size // Tooltip content is wrapped in span with PII attributes to allow masking by Curtain extension const hasPiiAttrs = Object.keys(piiAttrs).length > 0; const valueDisplay = isLongString ? ( <> {/* Mobile: show truncated with tooltip */} <Tooltip content={hasPiiAttrs ? <span {...piiAttrs}>{String(item.value)}</span> : String(item.value)} > <span className={twMerge("md:hidden", item.href ? "hover:underline cursor-pointer" : "")} {...piiAttrs} > {truncatedValue} </span> </Tooltip> {/* Desktop: show full value
+- **StatList** - Additional CSS classes */ className?: string; }  // Helpers  // Use the centralized formatting utility function formatValue(value: StatValue, formatter?: StatFormatter): React.ReactNode { // If value is already a React element, return it as-is (skip formatting) if (React.isValidElement(value)) { return value; }  return formatComponentValue({ value, formatter, emptyClassName: "text-text-muted", emptyText: "—", }); }  function getTone(item: StatItem): StatTone | undefined { // Check thresholds first if (item.thresholds && item.value !== null && item.value !== undefined) { for (const threshold of item.thresholds) { if (threshold.when(item.value)) { return threshold.tone; } } }  // Fall back to explicit tone return item.tone; }  const toneColors: Record<StatTone, string> = { neutral: "text-text-body", success: "text-feedback-success", warning: "text-feedback-warning", error: "text-feedback-error", info: "text-feedback-info", };  // StatRow Component  // Constants for auto-truncation const LONG_STRING_THRESHOLD = 24; const LONG_STRING_TRUNCATE_LENGTH = 20;  function StatRow({ item, dense, valueAlign }: { item: StatItem; dense?: boolean; valueAlign?: StatAlign }) { const tone = getTone(item); const toneClass = tone ? toneColors[tone] : ""; const isStacked = item.stackOnMobile;  // Check if this is a long string that should be auto-truncated on mobile const isLongString = typeof item.value === "string" && item.value.length > LONG_STRING_THRESHOLD && !item.formatter && !React.isValidElement(item.value);  // Get the formatted value (used for both truncated and full display) const formattedValue = formatValue(item.value, item.formatter);  // Get the truncated value for mobile display // Note: We cast to string here because isLongString already verifies typeof item.value === "string" const truncatedValue = isLongString ? truncateMiddle(item.value as string, LONG_STRING_TRUNCATE_LENGTH) : null;  const textToCopy = typeof item.copyable === "function" ? item.copyable(item.value) : String(item.value);  // PII data attributes (only set if both piiType and piiEntity are provided) const piiAttrs = item.piiType && item.piiEntity ? { "data-pii-type": item.piiType, "data-pii-entity": item.piiEntity, } : {};  // For long strings, render both truncated (mobile) and full (desktop) versions // CSS classes control which is visible based on screen size // Tooltip content is wrapped in span with PII attributes to allow masking by Curtain extension const hasPiiAttrs = Object.keys(piiAttrs).length > 0; const valueDisplay = isLongString ? ( <> {/* Mobile: show truncated with tooltip */} <Tooltip content={hasPiiAttrs ? <span {...piiAttrs}>{String(item.value)}</span> : String(item.value)}> <span className={twMerge("md:hidden", item.href ? "hover:underline cursor-pointer" : "")} {...piiAttrs}> {truncatedValue} </span> </Tooltip> {/* Desktop: show full value
 - **Switch** - Switch  Toggle switch component for binary on/off states. Provides an accessible alternative to checkboxes for settings and preferences.
 - **Tab** - Tab trigger element.
 - **TabList** - TabList container.
@@ -385,7 +385,7 @@ Renders an Edges Button. When `href` is provided, renders a link-styled button u
 - `size: Size`
 - `style: React.CSSProperties`
 - `target: string`
-- `variant: | "default" | "brand" | "secondary" | "destructive" | "icon" | "link" | "unstyled" | "ghost" | "primary"`
+- `variant: "default" | "brand" | "secondary" | "destructive" | "icon" | "link" | "unstyled" | "ghost" | "primary"`
 
 ---
 
@@ -1372,7 +1372,7 @@ PlaceSearch  Location search component with autocomplete; emits a `Place` value
 
 **Props:**
 - `autoFocus: boolean`
-- `countryRestrictions: string[]; // Array of ISO 3166-1 alpha-2 country codes proximity?: "ip" | [number, number]; // Either "ip" for IP-based location or [longitude, latitude] coordinates hideCountry?: boolean; // Hide country from results (useful when using countryRestrictions) showIcon?: boolean; // Show location type icons in results (default: true) className?: string`
+- `countryRestrictions: string[]; // Array of ISO 3166-1 alpha-2 country codes proximity?: "ip" | [number, number]; // Either "ip" for IP-based location or [longitude, latitude] coordinates hideCountry?: boolean; // Hide country from results (useful when using countryRestrictions) showIcon?: boolean; // Show location type icons in results (default: true) useMobileTray?: boolean; // Whether to use a Tray (bottom sheet) on mobile devices instead of a Popover (default: true) className?: string`
 - `defaultFilter: (textValue: string, inputValue: string) => boolean`
 - `defaultSelectedKey: Key | null`
 - `description: string`
@@ -1697,7 +1697,7 @@ Child panels
 ---
 
 #### StatList
-Additional CSS classes */ className?: string; }  // Helpers  // Use the centralized formatting utility function formatValue(value: StatValue, formatter?: StatFormatter): React.ReactNode { // If value is already a React element, return it as-is (skip formatting) if (React.isValidElement(value)) { return value; }  return formatComponentValue({ value, formatter, emptyClassName: "text-text-muted", emptyText: "—", }); }  function getTone(item: StatItem): StatTone | undefined { // Check thresholds first if (item.thresholds && item.value !== null && item.value !== undefined) { for (const threshold of item.thresholds) { if (threshold.when(item.value)) { return threshold.tone; } } }  // Fall back to explicit tone return item.tone; }  const toneColors: Record<StatTone, string> = { neutral: "text-text-body", success: "text-feedback-success", warning: "text-feedback-warning", error: "text-feedback-error", info: "text-feedback-info", };  // StatRow Component  // Constants for auto-truncation const LONG_STRING_THRESHOLD = 24; const LONG_STRING_TRUNCATE_LENGTH = 20;  function StatRow({ item, dense, valueAlign, }: { item: StatItem; dense?: boolean; valueAlign?: StatAlign; }) { const tone = getTone(item); const toneClass = tone ? toneColors[tone] : ""; const isStacked = item.stackOnMobile;  // Check if this is a long string that should be auto-truncated on mobile const isLongString = typeof item.value === "string" && item.value.length > LONG_STRING_THRESHOLD && !item.formatter && !React.isValidElement(item.value);  // Get the formatted value (used for both truncated and full display) const formattedValue = formatValue(item.value, item.formatter);  // Get the truncated value for mobile display // Note: We cast to string here because isLongString already verifies typeof item.value === "string" const truncatedValue = isLongString ? truncateMiddle(item.value as string, LONG_STRING_TRUNCATE_LENGTH) : null;  const textToCopy = typeof item.copyable === "function" ? item.copyable(item.value) : String(item.value);  // PII data attributes (only set if both piiType and piiEntity are provided) const piiAttrs = item.piiType && item.piiEntity ? { "data-pii-type": item.piiType, "data-pii-entity": item.piiEntity, } : {};  // For long strings, render both truncated (mobile) and full (desktop) versions // CSS classes control which is visible based on screen size // Tooltip content is wrapped in span with PII attributes to allow masking by Curtain extension const hasPiiAttrs = Object.keys(piiAttrs).length > 0; const valueDisplay = isLongString ? ( <> {/* Mobile: show truncated with tooltip */} <Tooltip content={hasPiiAttrs ? <span {...piiAttrs}>{String(item.value)}</span> : String(item.value)} > <span className={twMerge("md:hidden", item.href ? "hover:underline cursor-pointer" : "")} {...piiAttrs} > {truncatedValue} </span> </Tooltip> {/* Desktop: show full value
+Additional CSS classes */ className?: string; }  // Helpers  // Use the centralized formatting utility function formatValue(value: StatValue, formatter?: StatFormatter): React.ReactNode { // If value is already a React element, return it as-is (skip formatting) if (React.isValidElement(value)) { return value; }  return formatComponentValue({ value, formatter, emptyClassName: "text-text-muted", emptyText: "—", }); }  function getTone(item: StatItem): StatTone | undefined { // Check thresholds first if (item.thresholds && item.value !== null && item.value !== undefined) { for (const threshold of item.thresholds) { if (threshold.when(item.value)) { return threshold.tone; } } }  // Fall back to explicit tone return item.tone; }  const toneColors: Record<StatTone, string> = { neutral: "text-text-body", success: "text-feedback-success", warning: "text-feedback-warning", error: "text-feedback-error", info: "text-feedback-info", };  // StatRow Component  // Constants for auto-truncation const LONG_STRING_THRESHOLD = 24; const LONG_STRING_TRUNCATE_LENGTH = 20;  function StatRow({ item, dense, valueAlign }: { item: StatItem; dense?: boolean; valueAlign?: StatAlign }) { const tone = getTone(item); const toneClass = tone ? toneColors[tone] : ""; const isStacked = item.stackOnMobile;  // Check if this is a long string that should be auto-truncated on mobile const isLongString = typeof item.value === "string" && item.value.length > LONG_STRING_THRESHOLD && !item.formatter && !React.isValidElement(item.value);  // Get the formatted value (used for both truncated and full display) const formattedValue = formatValue(item.value, item.formatter);  // Get the truncated value for mobile display // Note: We cast to string here because isLongString already verifies typeof item.value === "string" const truncatedValue = isLongString ? truncateMiddle(item.value as string, LONG_STRING_TRUNCATE_LENGTH) : null;  const textToCopy = typeof item.copyable === "function" ? item.copyable(item.value) : String(item.value);  // PII data attributes (only set if both piiType and piiEntity are provided) const piiAttrs = item.piiType && item.piiEntity ? { "data-pii-type": item.piiType, "data-pii-entity": item.piiEntity, } : {};  // For long strings, render both truncated (mobile) and full (desktop) versions // CSS classes control which is visible based on screen size // Tooltip content is wrapped in span with PII attributes to allow masking by Curtain extension const hasPiiAttrs = Object.keys(piiAttrs).length > 0; const valueDisplay = isLongString ? ( <> {/* Mobile: show truncated with tooltip */} <Tooltip content={hasPiiAttrs ? <span {...piiAttrs}>{String(item.value)}</span> : String(item.value)}> <span className={twMerge("md:hidden", item.href ? "hover:underline cursor-pointer" : "")} {...piiAttrs}> {truncatedValue} </span> </Tooltip> {/* Desktop: show full value
 
 **Imports:**
 - `import { StatList } from "@texturehq/edges"`
diff --git a/docs/visual-regression-system.md b/docs/visual-regression-system.md
index 5c6bd417..25305c52 100644
--- a/docs/visual-regression-system.md
+++ b/docs/visual-regression-system.md
@@ -1,1201 +1,428 @@
 # Visual Regression Capture System
 
-> Automated before/after screenshot generation for user-facing PR changes,
-> with annotated bounding boxes and combined comparison images.
+> Automated before/after screenshot pipeline for PR review.
+> Captures two states of a running app via git worktree isolation,
+> annotates regions of interest, computes pixel diffs, and composes
+> side-by-side comparison images with a markdown report.
 
-## 1. System Overview
+## Quick Start
 
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                    VISUAL REGRESSION PIPELINE                       │
-│                                                                     │
-│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐      │
-│  │  DEFINE   │───▶│ CAPTURE  │───▶│ ANNOTATE │───▶│ COMPOSE  │──┐   │
-│  │  Targets  │    │  States  │    │  Regions │    │  Pairs   │  │   │
-│  └──────────┘    └──────────┘    └──────────┘    └──────────┘  │   │
-│                                                                 ▼   │
-│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐      │
-│  │  EMBED   │◀───│ UPLOAD   │◀───│ CATALOG  │◀───│ DIFF     │      │
-│  │  in PR   │    │  Images  │    │  Results │    │  Detect  │      │
-│  └──────────┘    └──────────┘    └──────────┘    └──────────┘      │
-│                                                                     │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-## 2. Architecture
-
-```mermaid
-graph TD
-    subgraph "1 · Target Definition"
-        MANIFEST[capture-manifest.json<br/><i>routes, selectors, viewports,<br/>annotation regions, colors</i>]
-        COMMITS[git log analysis<br/><i>map commits → files → routes</i>]
-        COMMITS --> MANIFEST
-    end
-
-    subgraph "2 · Dual-State Capture"
-        BASE_CO[git stash / worktree<br/>checkout base branch]
-        BASE_DEV[start dev server<br/>on port 3100]
-        BASE_SNAP[Playwright captures<br/>base-state screenshots]
-
-        PR_CO[restore PR branch]
-        PR_DEV[start dev server<br/>on port 3101]
-        PR_SNAP[Playwright captures<br/>PR-state screenshots]
-
-        BASE_CO --> BASE_DEV --> BASE_SNAP
-        PR_CO --> PR_DEV --> PR_SNAP
-    end
-
-    subgraph "3 · Annotation Engine"
-        BBOX[draw bounding boxes<br/><i>sharp / node-canvas</i>]
-        LABEL[add text labels<br/><i>BEFORE / AFTER</i>]
-        COLOR[color rationalization<br/><i>red=removed, green=added,<br/>blue=changed, orange=moved</i>]
-        BBOX --> LABEL --> COLOR
-    end
-
-    subgraph "4 · Composition"
-        SIDE[side-by-side merge<br/><i>BEFORE │ AFTER</i>]
-        HEADER[add title bar<br/><i>commit scope + viewport</i>]
-        SIDE --> HEADER
-    end
+```bash
+# Full pipeline: base (worktree) + PR screenshots, annotate, diff, compose
+npm run vr:capture
 
-    subgraph "5 · Upload & Embed"
-        UPLOAD[upload to host<br/><i>GitHub / R2 / S3</i>]
-        TABLE[generate markdown table<br/><i>viewport × change</i>]
-        PR[inject into PR description<br/><i>or post as comment</i>]
-        UPLOAD --> TABLE --> PR
-    end
+# PR-only: skip base screenshots (use existing ones from a prior run)
+npm run vr:capture:pr-only
 
-    MANIFEST --> BASE_CO & PR_CO
-    BASE_SNAP --> BBOX
-    PR_SNAP --> BBOX
-    COLOR --> SIDE
-    HEADER --> UPLOAD
+# Cherry-pick specific captures and viewports
+npx tsx scripts/visual-regression/capture-vr.ts \
+  --captures logo-redesign,header-spacing \
+  --viewports desktop
 
-    style MANIFEST fill:#e1f5fe,stroke:#0277bd
-    style BBOX fill:#fff3e0,stroke:#ef6c00
-    style SIDE fill:#e8f5e9,stroke:#2e7d32
-    style UPLOAD fill:#f3e5f5,stroke:#7b1fa2
+# Re-process existing screenshots (skip Playwright, re-annotate + compose)
+npx tsx scripts/visual-regression/capture-vr.ts --skip-capture
 ```
 
-## 3. Capture Manifest Schema
-
-The manifest declares what to screenshot, where to annotate, and how to color-code.
-It can be auto-generated from git diff analysis or hand-authored per commit.
-
-```jsonc
-// scripts/visual-regression/capture-manifest.json
-{
-  "$schema": "./capture-manifest.schema.json",
-  "version": "1.0",
-  "baseRef": "main",
-  "prRef": "HEAD",
-  "devServerPort": {
-    "base": 3100,
-    "pr": 3101
-  },
-  "viewports": [
-    { "name": "mobile",  "width": 375,  "height": 812 },
-    { "name": "tablet",  "width": 768,  "height": 1024 },
-    { "name": "desktop", "width": 1440, "height": 900 }
-  ],
-  "captures": [
-    {
-      "id": "dropdown-chevron-padding",
-      "commit": "3f89367",
-      "route": "/grid-operators",
-      "description": "Inner right-side padding on filter dropdowns",
-      "waitFor": "table >> tr >> td",
-      "regions": [
-        {
-          "selector": "select:first-of-type",
-          "annotation": {
-            "color": "blue",
-            "label": "Chevron padding"
-          }
-        }
-      ]
-    },
-    {
-      "id": "header-spacing",
-      "commit": "106f641",
-      "route": "/grid-operators",
-      "description": "Header height h-14 → h-12",
-      "regions": [
-        {
-          "selector": "header",
-          "annotation": {
-            "color": "blue",
-            "label": "h-14 → h-12"
-          }
-        }
-      ]
-    },
-    {
-      "id": "badge-variants",
-      "commit": "111ef3f",
-      "route": "/grid-operators?segment=DISTRIBUTION_COOPERATIVE",
-      "description": "Badge color mapping fix",
-      "waitFor": "[data-testid='data-table'] >> tr:nth-child(2)",
-      "regions": [
-        {
-          "selector": "span:has-text('Distribution Co-op')",
-          "annotation": {
-            "color": "orange",
-            "label": "warning → success"
-          }
-        }
-      ]
-    },
-    {
-      "id": "logo-redesign",
-      "commit": "ecdc89b",
-      "route": "/",
-      "description": "G-in-C dendritic graph logo",
-      "regions": [
-        {
-          "selector": "header a[href='/'] svg",
-          "annotation": {
-            "color": "green",
-            "label": "New logo mark"
-          }
-        }
-      ]
-    },
-    {
-      "id": "changelog-tabs",
-      "commit": "ea227b5",
-      "route": "/changelog",
-      "description": "Data Changes / Site Updates tab distinction",
-      "regions": [
-        {
-          "selector": "button:has-text('Data Changes')",
-          "annotation": {
-            "color": "green",
-            "label": "New tab bar"
-          }
-        }
-      ]
-    },
-    {
-      "id": "sort-chevrons",
-      "commit": "37b1abc",
-      "route": "/grid-operators",
-      "description": "Sort direction ▲/▼ in dropdown labels",
-      "actions": [
-        { "type": "click", "selector": "[data-testid='sort-select']" }
-      ],
-      "regions": [
-        {
-          "selector": "[data-testid='sort-select']",
-          "annotation": {
-            "color": "blue",
-            "label": "▲/▼ indicators"
-          }
-        }
-      ]
-    }
-  ]
-}
-```
-
-## 4. Color Rationalization System
-
-Annotation box colors communicate the _nature_ of the visual change:
-
-```
-┌────────────────────────────────────────────────────────────────┐
-│                    ANNOTATION COLOR KEY                        │
-│                                                                │
-│  ┌─────────┐                                                   │
-│  │  RED    │  Removed — element/style that existed is gone     │
-│  │ #EF4444 │  e.g., a column was deleted, a section removed    │
-│  └─────────┘                                                   │
-│  ┌─────────┐                                                   │
-│  │  GREEN  │  Added — new element that didn't exist before     │
-│  │ #22C55E │  e.g., new table column, new tab bar, new logo    │
-│  └─────────┘                                                   │
-│  ┌─────────┐                                                   │
-│  │  BLUE   │  Modified — existing element changed in-place     │
-│  │ #3B82F6 │  e.g., spacing adjusted, text changed, resized    │
-│  └─────────┘                                                   │
-│  ┌─────────┐                                                   │
-│  │ ORANGE  │  Recolored/Remapped — visual property changed     │
-│  │ #F97316 │  e.g., badge color variant, theme token swap      │
-│  └─────────┘                                                   │
-│  ┌─────────┐                                                   │
-│  │ YELLOW  │  Moved/Reflowed — same content, different place   │
-│  │ #EAB308 │  e.g., responsive stacking, layout reorder        │
-│  └─────────┘                                                   │
-│                                                                │
-│  BEFORE images use: red, blue, orange, yellow                  │
-│  AFTER images use:  green, blue, orange, yellow                │
-│                                                                │
-│  Rule: red on BEFORE pairs with green on AFTER for             │
-│        add/remove changes. blue/orange/yellow are symmetric.   │
-└────────────────────────────────────────────────────────────────┘
-```
+## How It Works
 
 ```mermaid
 graph LR
-    subgraph "BEFORE annotation"
-        R[RED — will be removed]
-        B1[BLUE — will change]
-        O1[ORANGE — will recolor]
-        Y1[YELLOW — will move]
-    end
-
-    subgraph "AFTER annotation"
-        G[GREEN — was added]
-        B2[BLUE — was changed]
-        O2[ORANGE — was recolored]
-        Y2[YELLOW — was moved]
-    end
+    A[Define<br>Targets] --> B[Capture<br>States]
+    B --> C[Annotate<br>Regions]
+    C --> D[Diff<br>Detect]
+    D --> E[Compose<br>Pairs]
+    E --> F[Catalog<br>+ Report]
 
-    R -.->|"removed"| G
-    B1 -->|"modified"| B2
-    O1 -->|"recolored"| O2
-    Y1 -->|"reflowed"| Y2
-
-    style R fill:#fecaca,stroke:#ef4444
-    style G fill:#bbf7d0,stroke:#22c55e
-    style B1 fill:#bfdbfe,stroke:#3b82f6
-    style B2 fill:#bfdbfe,stroke:#3b82f6
-    style O1 fill:#fed7aa,stroke:#f97316
-    style O2 fill:#fed7aa,stroke:#f97316
-    style Y1 fill:#fef08a,stroke:#eab308
-    style Y2 fill:#fef08a,stroke:#eab308
+    style A fill:#dbeafe,stroke:#1d4ed8,color:#1e3a5f
+    style B fill:#dbeafe,stroke:#1d4ed8,color:#1e3a5f
+    style C fill:#fef08a,stroke:#a16207,color:#713f12
+    style D fill:#fef08a,stroke:#a16207,color:#713f12
+    style E fill:#bbf7d0,stroke:#15803d,color:#14532d
+    style F fill:#bbf7d0,stroke:#15803d,color:#14532d
 ```
 
-## 5. Pipeline Execution Flow
+The pipeline runs in three phases:
 
-### 5.1 Dual-Server Git State Isolation
+1. **Capture** — Playwright takes viewport-sized screenshots of each route on two parallel dev servers (base branch via git worktree on port 4100, PR branch on port 4101). Bounding box coordinates for annotated regions are recorded alongside each screenshot.
+2. **Annotate + Diff** — Sharp draws color-coded bounding boxes onto the raw screenshots. Pixelmatch compares before/after pairs and calculates a pixel-diff percentage.
+3. **Compose + Report** — Annotated images are combined into titled side-by-side comparison PNGs. A `catalog.json` and `pr-screenshots.md` markdown report are generated.
 
-The key challenge: we need the dev server running on **both** the base and PR states
-simultaneously (or sequentially) to capture screenshots against each.
+Each phase is independently skippable via CLI flags.
 
-**Strategy A: Sequential (simpler, slower)**
+---
 
-```
-┌─────────────────────────────────────────────────────────┐
-│  SEQUENTIAL CAPTURE                                     │
-│                                                         │
-│  1. git stash (save PR work)                            │
-│  2. git checkout main                                   │
-│  3. npm install (if deps changed)                       │
-│  4. next dev --port 3100 &                              │
-│  5. wait-on http://localhost:3100                        │
-│  6. playwright: capture all BEFORE screenshots          │
-│  7. kill dev server                                     │
-│  8. git checkout - (back to PR branch)                  │
-│  9. git stash pop                                       │
-│  10. npm install (if deps changed)                      │
-│  11. next dev --port 3100 &                             │
-│  12. wait-on http://localhost:3100                       │
-│  13. playwright: capture all AFTER screenshots          │
-│  14. kill dev server                                    │
-│  15. annotate + compose + upload                        │
-│                                                         │
-│  ⏱  ~3-5 min total (2 cold starts)                     │
-└─────────────────────────────────────────────────────────┘
-```
+## Execution Flow (Detailed)
 
-**Strategy B: Parallel via git worktree (faster, recommended)**
+```mermaid
+flowchart TD
+    START([CLI invocation]) --> INIT[Parse args + read manifest<br>Apply capture/viewport filters<br>Create output directories]
 
-```
-┌─────────────────────────────────────────────────────────┐
-│  PARALLEL CAPTURE VIA WORKTREE                          │
-│                                                         │
-│  1. git worktree add /tmp/cg-base main                  │
-│  2. cd /tmp/cg-base && npm install && next dev -p 3100 &│
-│  3. cd (original) && next dev -p 3101 &                 │
-│  4. wait-on http://localhost:3100                        │
-│  5. wait-on http://localhost:3101                        │
-│  6. playwright captures BOTH in parallel:               │
-│     ├── port 3100 → BEFORE screenshots                  │
-│     └── port 3101 → AFTER screenshots                   │
-│  7. kill both servers                                   │
-│  8. git worktree remove /tmp/cg-base                    │
-│  9. annotate + compose + upload                         │
-│                                                         │
-│  ⏱  ~2-3 min total (parallel capture)                  │
-└─────────────────────────────────────────────────────────┘
-```
+    INIT --> P1{Phase 1:<br>Capture}
+    P1 -- "--skip-capture" --> P2
 
-```mermaid
-sequenceDiagram
-    participant CLI as capture-vr.ts
-    participant GIT as git
-    participant BASE as Base Server :3100
-    participant PR as PR Server :3101
-    participant PW as Playwright
-    participant IMG as Image Engine
-    participant HOST as Upload Host
-
-    CLI->>GIT: worktree add /tmp/cg-base main
-    CLI->>BASE: npm install && next dev -p 3100
-    CLI->>PR: next dev -p 3101
-    CLI->>CLI: wait-on both ports
-
-    par Parallel Capture
-        CLI->>PW: capture(manifest, port=3100, label="BEFORE")
-        PW->>BASE: navigate to each route
-        PW-->>CLI: before/*.png
-
-        CLI->>PW: capture(manifest, port=3101, label="AFTER")
-        PW->>PR: navigate to each route
-        PW-->>CLI: after/*.png
-    end
+    P1 --> PREBUILD[npm run prebuild<br>populate public/data/]
+    PREBUILD --> PORTS[Check ports 4100 + 4101 free]
+    PORTS --> PR_SERVER[Start PR dev server<br>port 4101 · current branch]
 
-    CLI->>BASE: kill
-    CLI->>GIT: worktree remove
+    PR_SERVER --> SKIP_BASE{--skip-base?}
+    SKIP_BASE -- yes --> WAIT
+    SKIP_BASE -- no --> WORKTREE
 
-    loop Each capture in manifest
-        CLI->>IMG: annotate(before.png, regions, "before" colors)
-        IMG-->>CLI: before-annotated.png
-        CLI->>IMG: annotate(after.png, regions, "after" colors)
-        IMG-->>CLI: after-annotated.png
-        CLI->>IMG: compose(before-annotated, after-annotated, title)
-        IMG-->>CLI: comparison.png
+    subgraph WORKTREE [Base Worktree Setup]
+        WT1[git worktree add /tmp/cg-vr-base] --> WT2[npm install --prefer-offline]
+        WT2 --> WT3[Copy data/ into worktree]
+        WT3 --> WT4[npm run prebuild in worktree]
+        WT4 --> WT5[Start base dev server<br>port 4100 · in worktree]
     end
 
-    CLI->>HOST: upload all comparison images
-    HOST-->>CLI: image URLs
-    CLI->>CLI: generate markdown table
-    CLI-->>CLI: pr-screenshots.md
-```
+    WORKTREE --> WAIT[Wait for servers ready<br>90s timeout · poll every 1.5s]
 
-### 5.2 Playwright Capture Script
+    WAIT --> CAPTURE
 
-```
-scripts/visual-regression/
-├── capture-manifest.json      # What to capture (the spec)
-├── capture-vr.ts              # Main orchestrator
-├── playwright-capture.ts      # Playwright screenshot logic
-├── annotate.ts                # Bounding box / label drawing
-├── compose.ts                 # Side-by-side composition
-├── upload.ts                  # Image hosting upload
-└── generate-pr-table.ts       # Markdown table generator
-```
+    subgraph CAPTURE [For each capture × viewport]
+        C1[page.goto route · waitUntil: load] --> C2[Wait for waitFor selector · 15s]
+        C2 --> C3[Wait for data content<br>table rows / cards / h1 · 10s]
+        C3 --> C4[1500ms settle time]
+        C4 --> C5[Inject animation-disable CSS]
+        C5 --> C6[Execute actions<br>click / hover / fill]
+        C6 --> C7[Take viewport screenshot]
+        C7 --> C8[Record bounding boxes<br>for each region selector]
+    end
 
-**Core capture logic (pseudocode):**
+    CAPTURE --> CLEANUP[Kill servers<br>Remove worktree]
+    CLEANUP --> P2
 
-```
-┌─────────────────────────────────────────────────────────┐
-│  playwright-capture.ts                                  │
-│                                                         │
-│  for each capture in manifest.captures:                 │
-│    for each viewport in manifest.viewports:             │
-│      1. browser.newPage()                               │
-│      2. page.setViewportSize(viewport)                  │
-│      3. page.goto(baseUrl + capture.route)              │
-│      4. if capture.waitFor:                             │
-│           page.waitForSelector(capture.waitFor)         │
-│      5. if capture.actions:                             │
-│           for action in capture.actions:                │
-│             page[action.type](action.selector)          │
-│      6. page.screenshot({ path, fullPage: false })      │
-│      7. for each region in capture.regions:             │
-│           element = page.locator(region.selector)       │
-│           bbox = element.boundingBox()                  │
-│           store bbox coordinates for annotation         │
-│      8. close page                                      │
-│                                                         │
-│  Output: screenshots/ directory with:                   │
-│    {captureId}-{viewport}-{state}.png                   │
-│    {captureId}-{viewport}-{state}.regions.json          │
-└─────────────────────────────────────────────────────────┘
-```
+    P2[Phase 2:<br>Annotate + Diff]
 
-### 5.3 Annotation Engine
+    subgraph ANNOTATE [For each capture × viewport]
+        A1[Load .regions.json bbox data] --> A2[Draw color-coded boxes + labels<br>Sharp SVG composite]
+        A2 --> A3[Compute pixel diff<br>pixelmatch · threshold 0.1]
+        A3 --> A4[Generate diff overlay image]
+    end
 
-```
-┌─────────────────────────────────────────────────────────┐
-│  annotate.ts                                            │
-│                                                         │
-│  Input:  screenshot.png + regions.json                  │
-│  Output: screenshot-annotated.png                       │
-│                                                         │
-│  Using: sharp (fast, no native deps) or node-canvas     │
-│                                                         │
-│  for each region:                                       │
-│    1. Parse bbox {x, y, width, height}                  │
-│    2. Expand by 4px padding                             │
-│    3. Draw rectangle stroke:                            │
-│       - strokeWidth: 3px                                │
-│       - color: region.annotation.color (from key)       │
-│       - cornerRadius: 4px                               │
-│       - opacity: 0.9                                    │
-│    4. Draw label pill above top-left corner:            │
-│       - background: same color, opacity 0.85            │
-│       - text: region.annotation.label                   │
-│       - font: 11px, bold, white                         │
-│       - padding: 4px 8px                                │
-│    5. Composite onto source image                       │
-│                                                         │
-│  Visual result:                                         │
-│                                                         │
-│    ┌─ Chevron padding ─┐                                │
-│    │┌──────────────────┐│                                │
-│    ││  [All Segments ▼]││ ◄── 3px blue border           │
-│    │└──────────────────┘│                                │
-│    └────────────────────┘                                │
-│                                                         │
-└─────────────────────────────────────────────────────────┘
-```
+    P2 --> ANNOTATE
+    ANNOTATE --> COMPOSE{--skip-compose?}
+    COMPOSE -- no --> SIDE[Compose side-by-side<br>title bar + BEFORE / AFTER + footer]
+    COMPOSE -- yes --> P3
+    SIDE --> P3
 
-### 5.4 Composition Engine
+    P3[Phase 3:<br>Output]
+    P3 --> OUT1[Write catalog.json]
+    P3 --> OUT2[Write pr-screenshots.md]
 
-```
-┌─────────────────────────────────────────────────────────┐
-│  compose.ts                                             │
-│                                                         │
-│  Input:  before-annotated.png, after-annotated.png      │
-│  Output: comparison-{id}-{viewport}.png                 │
-│                                                         │
-│  Layout:                                                │
-│  ┌──────────────────────────────────────────────────┐   │
-│  │  ░░░░░░░░░░░░░░░░ TITLE BAR ░░░░░░░░░░░░░░░░░░░│   │
-│  │  "Dropdown Chevron Padding · mobile (375px)"     │   │
-│  │  commit: 3f89367                                 │   │
-│  ├────────────────────┬─────────────────────────────┤   │
-│  │                    │                             │   │
-│  │     B E F O R E    │      A F T E R              │   │
-│  │                    │                             │   │
-│  │  ┌──────────────┐  │  ┌──────────────┐           │   │
-│  │  │ [Segments ▼] │  │  │ [Segments ▼] │           │   │
-│  │  └──────────────┘  │  └──────────────┘           │   │
-│  │   ▲ blue box       │   ▲ blue box                │   │
-│  │                    │                             │   │
-│  ├────────────────────┴─────────────────────────────┤   │
-│  │  ░░ FOOTER: "BEFORE (main) │ AFTER (welcome-pr)" ░░│   │
-│  └──────────────────────────────────────────────────┘   │
-│                                                         │
-│  Dimensions:                                            │
-│    width  = before.width + after.width + divider(2px)   │
-│    height = max(before, after) + title(48px) + foot(28) │
-│                                                         │
-│  If images differ in height:                            │
-│    pad shorter one with background color at bottom      │
-│                                                         │
-└─────────────────────────────────────────────────────────┘
+    style START fill:#eff6ff,stroke:#1d4ed8,color:#1e3a5f
+    style INIT fill:#f8fafc,stroke:#64748b,color:#1e293b
+    style P1 fill:#dbeafe,stroke:#1d4ed8,color:#1e3a5f
+    style P2 fill:#fef08a,stroke:#a16207,color:#713f12
+    style P3 fill:#bbf7d0,stroke:#15803d,color:#14532d
+    style PREBUILD fill:#e0e7ff,stroke:#4338ca,color:#312e81
+    style PORTS fill:#e0e7ff,stroke:#4338ca,color:#312e81
+    style PR_SERVER fill:#e0e7ff,stroke:#4338ca,color:#312e81
+    style SKIP_BASE fill:#e0e7ff,stroke:#4338ca,color:#312e81
+    style WAIT fill:#e0e7ff,stroke:#4338ca,color:#312e81
+    style CLEANUP fill:#fecaca,stroke:#b91c1c,color:#7f1d1d
 ```
 
-## 6. Image Hosting Strategy
+### Playwright Wait Cascade
 
 ```mermaid
-graph TD
-    subgraph "Option A: GitHub Issue Upload (recommended)"
-        A1[Create draft issue or<br/>use existing bot issue]
-        A2[POST image via<br/>GitHub GraphQL API]
-        A3[Get user-content URL<br/><i>https://github.com/user-<br/>attachments/assets/UUID</i>]
-        A4[URL is permanent<br/>even if issue is deleted]
-        A1 --> A2 --> A3 --> A4
-    end
-
-    subgraph "Option B: Git LFS in repo"
-        B1[Store in<br/>docs/screenshots/]
-        B2[Track with git-lfs]
-        B3[Reference via<br/>relative path]
-        B1 --> B2 --> B3
-    end
+flowchart LR
+    NAV[page.goto<br>waitUntil: load] --> WF{waitFor<br>selector?}
+    WF -- yes --> WFS[Wait 15s<br>for selector]
+    WF -- no --> DATA
+    WFS --> DATA[Wait 10s for<br>data content]
+    DATA --> SETTLE[1500ms<br>settle]
+    SETTLE --> CSS[Inject<br>no-animation CSS]
+    CSS --> ACT{actions<br>defined?}
+    ACT -- yes --> EXEC[Execute each<br>+ 300ms settle]
+    ACT -- no --> SNAP
+    EXEC --> SNAP[Screenshot<br>+ bbox record]
 
-    subgraph "Option C: Cloud bucket"
-        C1[Upload to<br/>R2 / S3 / GCS]
-        C2[Public URL with<br/>content-hash filename]
-        C3[Long-lived, CDN-backed]
-        C1 --> C2 --> C3
-    end
-
-    subgraph "Option D: GitHub Actions Artifact"
-        D1[Upload as<br/>workflow artifact]
-        D2[90-day retention<br/>by default]
-        D3[Not embeddable<br/>in markdown ✗]
-        D1 --> D2 --> D3
-    end
-
-    style A4 fill:#e8f5e9,stroke:#2e7d32
-    style D3 fill:#ffebee,stroke:#c62828
+    style NAV fill:#dbeafe,stroke:#1d4ed8,color:#1e3a5f
+    style WF fill:#fef08a,stroke:#a16207,color:#713f12
+    style WFS fill:#e0e7ff,stroke:#4338ca,color:#312e81
+    style DATA fill:#e0e7ff,stroke:#4338ca,color:#312e81
+    style SETTLE fill:#e0e7ff,stroke:#4338ca,color:#312e81
+    style CSS fill:#fecaca,stroke:#b91c1c,color:#7f1d1d
+    style ACT fill:#fef08a,stroke:#a16207,color:#713f12
+    style EXEC fill:#e0e7ff,stroke:#4338ca,color:#312e81
+    style SNAP fill:#bbf7d0,stroke:#15803d,color:#14532d
 ```
 
-### Recommendation
-
-**Option A (GitHub Issue Upload)** is the best fit because:
+---
 
-1. **Permanent URLs** — `github.com/user-attachments/assets/*` URLs persist indefinitely
-2. **No infrastructure** — no bucket to manage, no LFS quota
-3. **Automatable** — `gh api` or GraphQL mutation can upload programmatically
-4. **Embeddable** — standard markdown image syntax works in PR descriptions
-5. **Free** — included in GitHub's storage
-
-**Workflow:**
+## CLI Reference
 
 ```
-┌──────────────────────────────────────────────────┐
-│  Upload via GitHub API                           │
-│                                                  │
-│  1. Create (or reuse) a "Visual Regression Bot"  │
-│     issue in the repo                            │
-│                                                  │
-│  2. For each comparison image:                   │
-│     curl -X POST \                               │
-│       -H "Authorization: token $GITHUB_TOKEN" \  │
-│       -F "file=@comparison.png" \                │
-│       https://uploads.github.com/repos/          │
-│         TextureHQ/commongrid/issues/             │
-│         {issue}/comments                         │
-│                                                  │
-│  3. Parse response for asset URL                 │
-│                                                  │
-│  4. Delete the comment (URL survives)            │
-│     or keep for audit trail                      │
-│                                                  │
-│  Alternative: use gh CLI                         │
-│     gh issue comment {N} --body '![](file)'      │
-│                                                  │
-└──────────────────────────────────────────────────┘
+npx tsx scripts/visual-regression/capture-vr.ts [options]
 ```
 
-## 7. End-to-End Workflow
-
-```mermaid
-flowchart TD
-    START([PR opened or<br/>manual trigger]) --> PARSE
-
-    subgraph "Phase 1: Analyze"
-        PARSE[Parse git diff<br/>main...HEAD]
-        ROUTE[Map changed files<br/>→ affected routes]
-        GEN[Generate or load<br/>capture-manifest.json]
-        PARSE --> ROUTE --> GEN
-    end
-
-    subgraph "Phase 2: Capture"
-        WORK[git worktree add<br/>/tmp/cg-base main]
-        BASE_S[Start base server<br/>:3100]
-        PR_S[Start PR server<br/>:3101]
-        CAP_B[Playwright captures<br/>BEFORE screenshots]
-        CAP_A[Playwright captures<br/>AFTER screenshots]
-        BBOX_B[Record bounding<br/>box coordinates]
-        BBOX_A[Record bounding<br/>box coordinates]
-
-        WORK --> BASE_S & PR_S
-        BASE_S --> CAP_B --> BBOX_B
-        PR_S --> CAP_A --> BBOX_A
-    end
-
-    subgraph "Phase 3: Process"
-        ANN_B[Annotate BEFORE<br/>red/blue/orange/yellow]
-        ANN_A[Annotate AFTER<br/>green/blue/orange/yellow]
-        COMP[Compose side-by-side<br/>with title + footer]
-        DIFF[pixelmatch diff<br/>detection]
-
-        BBOX_B --> ANN_B
-        BBOX_A --> ANN_A
-        ANN_B --> COMP
-        ANN_A --> COMP
-        ANN_B --> DIFF
-        ANN_A --> DIFF
-    end
-
-    subgraph "Phase 4: Publish"
-        UPLOAD_IMG[Upload to<br/>GitHub issue assets]
-        MD_TABLE[Generate markdown<br/>comparison table]
-        PR_COMMENT[Post as PR comment<br/>or update description]
-        CATALOG[Write catalog.json<br/>for future reference]
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--base-ref <ref>` | `main` | Git ref for baseline screenshots |
+| `--captures <id,id,...>` | all | Comma-separated capture IDs to run |
+| `--viewports <vp,vp,...>` | all | Comma-separated viewport names to run |
+| `--skip-capture` | off | Skip Playwright phase; re-process existing screenshots |
+| `--skip-base` | off | Skip base worktree + server; only capture PR state |
+| `--skip-compose` | off | Skip side-by-side composition; just capture + annotate |
+| `--output <dir>` | `.visual-regression` | Output directory (relative to repo root) |
 
-        COMP --> UPLOAD_IMG --> MD_TABLE --> PR_COMMENT
-        DIFF --> CATALOG
-    end
+**npm aliases:**
+- `npm run vr:capture` — full pipeline
+- `npm run vr:capture:pr-only` — equivalent to `--skip-base`
 
-    GEN --> WORK
+---
 
-    CLEANUP[Kill servers<br/>Remove worktree] --> DONE([Done])
-    PR_COMMENT --> CLEANUP
+## File Structure
 
-    style START fill:#e1f5fe
-    style DONE fill:#e8f5e9
-    style COMP fill:#fff3e0
-    style UPLOAD_IMG fill:#f3e5f5
+```
+scripts/visual-regression/
+├── capture-vr.ts            # Main orchestrator (args, servers, worktree, phases)
+├── playwright-capture.ts    # Headless Chromium: navigate, wait, screenshot, bbox
+├── annotate.ts              # Sharp SVG composite: bounding boxes + labels
+├── compose.ts               # Sharp: side-by-side comparison images
+├── diff.ts                  # Pixelmatch: pixel-level diff + overlay
+├── capture-manifest.json    # Capture definitions (routes, regions, viewports)
+└── file-route-map.json      # Maps source files → affected routes (for authoring)
+
+.visual-regression/          # Output (gitignored)
+├── captures/
+│   ├── before/              # Raw + .regions.json from base branch
+│   ├── after/               # Raw + .regions.json from PR branch
+│   ├── annotated/           # Screenshots with bounding box overlays
+│   ├── comparisons/         # Side-by-side titled composition images
+│   └── diffs/               # Pixel diff overlay images
+├── catalog.json             # Machine-readable results
+└── pr-screenshots.md        # Human-readable markdown report
 ```
 
-## 8. Output Artifacts
+---
 
-### 8.1 Directory Structure
+## Capture Manifest
 
-```
-.visual-regression/
-├── captures/
-│   ├── before/
-│   │   ├── dropdown-chevron-padding-mobile.png
-│   │   ├── dropdown-chevron-padding-mobile.regions.json
-│   │   ├── dropdown-chevron-padding-tablet.png
-│   │   ├── header-spacing-mobile.png
-│   │   └── ...
-│   ├── after/
-│   │   ├── dropdown-chevron-padding-mobile.png
-│   │   ├── dropdown-chevron-padding-mobile.regions.json
-│   │   └── ...
-│   ├── annotated/
-│   │   ├── dropdown-chevron-padding-mobile-before.png
-│   │   ├── dropdown-chevron-padding-mobile-after.png
-│   │   └── ...
-│   └── comparisons/
-│       ├── dropdown-chevron-padding-mobile.png     ◄── final output
-│       ├── dropdown-chevron-padding-tablet.png
-│       ├── header-spacing-desktop.png
-│       └── ...
-├── catalog.json                                     ◄── index of all captures
-└── pr-screenshots.md                                ◄── markdown embed table
-```
+The manifest (`scripts/visual-regression/capture-manifest.json`) defines what to capture and how.
 
-### 8.2 Generated Markdown Table
-
-```markdown
-## Visual Regression Report
-
-| Change | Mobile (375px) | Tablet (768px) | Desktop (1440px) |
-|--------|---------------|----------------|-----------------|
-| Dropdown chevron padding | ![](url) | ![](url) | ![](url) |
-| Header spacing h-14→h-12 | ![](url) | ![](url) | ![](url) |
-| Badge variant colors | — | — | ![](url) |
-| Logo redesign | ![](url) | — | ![](url) |
-| Changelog tabs | — | ![](url) | ![](url) |
-| Filter stacking | ![](url) | — | — |
-| Name clamping | ![](url) | — | — |
-
-<details>
-<summary>Diff detection summary</summary>
-
-| Capture | Viewport | Pixel diff % | Status |
-|---------|----------|-------------|--------|
-| dropdown-chevron-padding | mobile | 2.3% | Changed |
-| dropdown-chevron-padding | tablet | 1.8% | Changed |
-| header-spacing | desktop | 4.1% | Changed |
-| badge-variants | desktop | 3.7% | Changed |
-| logo-redesign | mobile | 12.4% | Changed |
-| changelog-tabs | tablet | 18.2% | New UI |
-
-</details>
+### Top-level structure
+
+```jsonc
+{
+  "version": "1.0",
+  "baseRef": "main",              // default base branch
+  "prRef": "HEAD",                // current branch
+  "devServer": {
+    "command": "npx next dev",    // dev server command
+    "readyPattern": "Ready in",   // stdout pattern indicating ready
+    "basePort": 4100,             // port for base branch server
+    "prPort": 4101                // port for PR branch server
+  },
+  "viewports": [                  // available viewport sizes
+    { "name": "mobile",  "width": 375,  "height": 812  },
+    { "name": "tablet",  "width": 768,  "height": 1024 },
+    { "name": "desktop", "width": 1440, "height": 900  }
+  ],
+  "captures": [ ... ]            // see below
+}
 ```
 
-### 8.3 Catalog JSON
+### Capture entry
 
 ```jsonc
-// .visual-regression/catalog.json
 {
-  "generatedAt": "2026-03-16T18:30:00Z",
-  "baseRef": "main",
-  "prRef": "welcome-pr",
-  "prNumber": null,
-  "comparisons": [
+  "id": "badge-variants",                    // unique identifier (used in filenames)
+  "commit": "111ef3f",                       // optional: originating commit for traceability
+  "route": "/grid-operators",                // URL path to navigate to
+  "description": "Badge color mapping fix",  // human-readable title for composition
+
+  // Optional: restrict to specific viewports (default: all)
+  "viewports": ["desktop"],
+
+  // Optional: CSS selector to wait for before capturing (15s timeout)
+  "waitFor": "main",
+
+  // Optional: pre-capture interactions
+  "actions": [
+    { "type": "click", "selector": "header button[aria-label='Toggle menu']" },
+    { "type": "hover", "selector": ".tooltip-trigger" },
+    { "type": "fill",  "selector": "input[name='search']", "value": "test" }
+  ],
+
+  // Regions to annotate with bounding boxes
+  "regions": [
     {
-      "id": "dropdown-chevron-padding",
-      "commit": "3f89367",
-      "description": "Inner right-side padding on filter dropdowns",
-      "viewports": {
-        "mobile": {
-          "before": "captures/before/dropdown-chevron-padding-mobile.png",
-          "after": "captures/after/dropdown-chevron-padding-mobile.png",
-          "comparison": "captures/comparisons/dropdown-chevron-padding-mobile.png",
-          "uploadUrl": "https://github.com/user-attachments/assets/...",
-          "pixelDiffPercent": 2.3
-        }
-      }
+      "selector": "table tbody tr:nth-child(1) td:nth-child(2) span",
+      "beforeColor": "orange",   // color on BEFORE screenshot
+      "afterColor": "orange",    // color on AFTER screenshot
+      "label": "Badge variant"   // label text drawn above the box
     }
   ]
 }
 ```
 
-## 9. CLI Interface
+### Region color semantics
 
-```
-Usage:
-  npx tsx scripts/visual-regression/capture-vr.ts [options]
-
-Options:
-  --manifest <path>    Path to capture manifest (default: auto-detect)
-  --base-ref <ref>     Base git ref to compare against (default: main)
-  --viewports <list>   Comma-separated viewport names (default: all)
-  --captures <list>    Comma-separated capture IDs (default: all)
-  --skip-capture       Skip capture, re-annotate/compose from existing
-  --skip-upload        Skip upload, just generate local files
-  --upload-method      github | r2 | s3 | local (default: github)
-  --output-dir <path>  Output directory (default: .visual-regression)
-  --parallel           Use git worktree for parallel capture (default)
-  --sequential         Use sequential checkout instead of worktree
-
-Examples:
-  # Full pipeline
-  npx tsx scripts/visual-regression/capture-vr.ts
-
-  # Just one capture at mobile
-  npx tsx scripts/visual-regression/capture-vr.ts \
-    --captures dropdown-chevron-padding --viewports mobile
-
-  # Re-compose from existing screenshots (no server needed)
-  npx tsx scripts/visual-regression/capture-vr.ts --skip-capture
-
-  # Generate manifest from git diff
-  npx tsx scripts/visual-regression/generate-manifest.ts
-```
+| Color | Hex | Meaning | Typical usage |
+|-------|-----|---------|---------------|
+| `red` | `#EF4444` | Removed | Element only in BEFORE (beforeColor: red, afterColor: green) |
+| `green` | `#22C55E` | Added | Element only in AFTER (beforeColor: red, afterColor: green) |
+| `blue` | `#3B82F6` | Modified in-place | Same element, changed styling/content |
+| `orange` | `#F97316` | Recolored/remapped | Color or visual mapping changed |
+| `yellow` | `#EAB308` | Moved/reflowed | Element position shifted |
 
-## 10. Integration Points
-
-### 10.1 GitHub Actions Workflow
-
-```yaml
-# .github/workflows/visual-regression.yml
-name: Visual Regression
-on:
-  pull_request:
-    types: [opened, synchronize]
-
-jobs:
-  capture:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0  # full history for worktree
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      - run: npm ci
-      - run: npx playwright install chromium
-
-      - name: Capture visual regression
-        run: npx tsx scripts/visual-regression/capture-vr.ts
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Post comparison images
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const fs = require('fs');
-            const table = fs.readFileSync('.visual-regression/pr-screenshots.md', 'utf8');
-            await github.rest.issues.createComment({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: context.issue.number,
-              body: table,
-            });
-```
+Use symmetric colors (same before/after) for in-place changes. Use asymmetric (red/green) for additions/removals.
 
-### 10.2 PR Template Integration
+---
 
-The generated `pr-screenshots.md` can be spliced into the Screenshots section
-of `PR_DESCRIPTION.md` during the upload phase, or posted as a separate PR comment
-that auto-updates on each push.
+## Module Reference
 
-### 10.3 Manual Trigger
+### `capture-vr.ts` — Orchestrator
 
-```bash
-# From repo root, with PR branch checked out:
-npm run vr:capture
+The main entry point. Parses CLI args, manages server lifecycle and git worktree, then sequences the three phases. All cleanup (server kill, worktree removal) runs in `finally` blocks.
 
-# Add to package.json scripts:
-# "vr:capture": "tsx scripts/visual-regression/capture-vr.ts",
-# "vr:manifest": "tsx scripts/visual-regression/generate-manifest.ts"
-```
+Key behaviors:
+- **Port check**: Fetches `http://localhost:<port>` before starting servers. If a response comes back, the port is occupied and the script aborts with an actionable error.
+- **Server wait**: Polls every 1.5s for up to 90s. Accepts HTTP 200 as ready. Accepts HTTP 404 after timeout (route may not exist on base).
+- **Worktree**: Created at `/tmp/cg-vr-base`. Installs deps, copies `data/`, runs prebuild. Force-removed on cleanup.
 
-## 11. File-to-Route Mapping
+### `playwright-capture.ts` — Screenshot Engine
 
-For auto-generating the manifest from `git diff`, the system needs to know
-which files affect which routes:
+Launches headless Chromium and iterates captures × viewports. For each:
 
-```jsonc
-// scripts/visual-regression/file-route-map.json
-{
-  "app/(shell)/grid-operators/page.tsx": ["/grid-operators"],
-  "app/(shell)/power-plants/page.tsx": ["/power-plants"],
-  "app/(shell)/transmission-lines/page.tsx": ["/transmission-lines"],
-  "app/(shell)/ev-charging/page.tsx": ["/ev-charging"],
-  "app/(shell)/pricing-nodes/page.tsx": ["/pricing-nodes"],
-  "app/(shell)/changelog/page.tsx": ["/changelog"],
-  "app/(shell)/explore/page.tsx": ["/explore"],
-  "app/(shell)/about/page.tsx": ["/about"],
-  "app/(shell)/page.tsx": ["/"],
-  "components/TopBar.tsx": ["*"],
-  "components/ShellLayoutClient.tsx": ["*"],
-  "components/GlobalSearch.tsx": ["*"],
-  "components/SearchInput.tsx": ["/grid-operators", "/power-plants", "/transmission-lines", "/ev-charging", "/pricing-nodes"],
-  "components/DataSourceLink.tsx": ["/grid-operators", "/power-plants", "/transmission-lines", "/ev-charging", "/pricing-nodes"],
-  "components/explorer/*": ["/explore"],
-  "lib/formatting.ts": ["/grid-operators", "/explore"],
-  "lib/geo.ts": ["/explore", "/grid-operators/*"],
-  "app/globals.css": ["*"],
-  "public/logo.svg": ["*"],
-  "public/favicon.svg": ["*"]
-}
-```
+1. Creates a fresh browser context with exact viewport dimensions, 1x scale, light color scheme
+2. Navigates with `waitUntil: "load"` (not `networkidle`, which hangs on long-poll connections)
+3. Waits for content readiness via a cascade:
+   - Explicit `waitFor` selector (15s)
+   - Generic data-content selector: `[class*="DataTable"] [role="row"], table tr, [class*="Card"], main h1` (10s)
+   - 1500ms settle time
+4. Injects animation-disable CSS (`animation-duration: 0s`, `transition-duration: 0s`)
+5. Executes optional `actions` (click, hover, fill) with 300ms settle after each
+6. Takes a viewport-sized screenshot (not full-page)
+7. Records bounding boxes (`element.boundingBox()`) for each region selector
+8. Writes `{id}-{viewport}.png` and `{id}-{viewport}.regions.json`
 
-`"*"` means the change affects all routes — capture a representative sample.
+### `annotate.ts` — Bounding Box Renderer
 
-## 12. Concrete Implementation Reference
+Uses Sharp's SVG composite to overlay annotations without a native Canvas dependency.
 
-### 12.1 Playwright Capture — Actual API
+For each region:
+- Draws a rounded-corner rectangle (3px stroke, 4px padding) in the region's color
+- Draws a pill-shaped label background above the box
+- Renders label text in white, 11px bold system font
 
-```typescript
-// playwright-capture.ts
-import { chromium, type Page, type BrowserContext } from 'playwright';
+If no regions have bounding boxes, copies the image as-is.
 
-interface CaptureResult {
-  path: string;
-  regions: Array<{ selector: string; bbox: { x: number; y: number; width: number; height: number } }>;
-}
+### `diff.ts` — Pixel Diff Engine
 
-async function captureRoute(
-  context: BrowserContext,
-  baseUrl: string,
-  capture: ManifestCapture,
-  viewport: { name: string; width: number; height: number },
-  outputDir: string,
-): Promise<CaptureResult> {
-  const page = await context.newPage();
-  await page.setViewportSize({ width: viewport.width, height: viewport.height });
-
-  // Navigate and wait for content
-  await page.goto(`${baseUrl}${capture.route}`, { waitUntil: 'networkidle' });
-  if (capture.waitFor) {
-    await page.waitForSelector(capture.waitFor, { timeout: 10_000 });
-  }
-
-  // Disable animations for deterministic capture
-  await page.addStyleTag({ content: `
-    *, *::before, *::after {
-      animation-duration: 0s !important;
-      transition-duration: 0s !important;
-    }
-  `});
+Wraps `pixelmatch` (same library Playwright uses internally):
+- Reads both PNGs via `pngjs`
+- Pads the smaller image to match dimensions (transparent fill)
+- Runs diff with threshold 0.1, `includeAA: false`
+- Returns `{ diffPixels, totalPixels, diffPercent }` and writes a diff overlay PNG
 
-  // Execute pre-capture actions (click dropdowns, hover, etc.)
-  if (capture.actions) {
-    for (const action of capture.actions) {
-      await page.locator(action.selector)[action.type as 'click']();
-      await page.waitForTimeout(200);
-    }
-  }
-
-  // Capture full viewport screenshot
-  const screenshotPath = `${outputDir}/${capture.id}-${viewport.name}.png`;
-  await page.screenshot({ path: screenshotPath, fullPage: false });
-
-  // Record bounding boxes for each annotatable region
-  const regions = [];
-  for (const region of capture.regions) {
-    const locator = page.locator(region.selector).first();
-    const bbox = await locator.boundingBox();
-    if (bbox) {
-      regions.push({ selector: region.selector, bbox, annotation: region.annotation });
-    }
-  }
+### `compose.ts` — Side-by-Side Composition
 
-  await page.close();
-  return { path: screenshotPath, regions };
-}
+Creates a single comparison image via Sharp:
+
+```
+┌──────────────────────────────────────────┐
+│  Title bar (48px) — description · viewport
+├───────────────────┬──────────────────────┤
+│                   │                      │
+│     BEFORE        │      AFTER           │
+│                   │                      │
+├───────────────────┴──────────────────────┤
+│  Footer (28px) — "BEFORE (main)" │ "AFTER (PR)"
+└──────────────────────────────────────────┘
 ```
 
-### 12.2 Annotation — sharp + SVG Compositing
+Divider is 2px. Title and footer use SVG text rendering with system fonts.
 
-```typescript
-// annotate.ts
-import sharp from 'sharp';
+---
 
-const COLORS = {
-  red:    { stroke: '#EF4444', fill: 'rgba(239,68,68,0.85)' },
-  green:  { stroke: '#22C55E', fill: 'rgba(34,197,94,0.85)' },
-  blue:   { stroke: '#3B82F6', fill: 'rgba(59,130,246,0.85)' },
-  orange: { stroke: '#F97316', fill: 'rgba(249,115,22,0.85)' },
-  yellow: { stroke: '#EAB308', fill: 'rgba(234,179,8,0.85)' },
-};
+## File-Route Map
 
-interface AnnotationRegion {
-  bbox: { x: number; y: number; width: number; height: number };
-  annotation: { color: keyof typeof COLORS; label: string };
-}
-
-async function annotateImage(
-  inputPath: string,
-  regions: AnnotationRegion[],
-  outputPath: string,
-): Promise<void> {
-  const meta = await sharp(inputPath).metadata();
-  const { width = 0, height = 0 } = meta;
-
-  // Build SVG overlay with all bounding boxes and labels
-  const boxes = regions.map((r) => {
-    const c = COLORS[r.annotation.color];
-    const pad = 4;
-    const x = Math.max(0, r.bbox.x - pad);
-    const y = Math.max(0, r.bbox.y - pad);
-    const w = r.bbox.width + pad * 2;
-    const h = r.bbox.height + pad * 2;
-    const labelW = r.annotation.label.length * 7 + 16;
-    const labelH = 20;
-    const labelY = Math.max(0, y - labelH - 2);
-
-    return `
-      <rect x="${x}" y="${y}" width="${w}" height="${h}"
-            fill="none" stroke="${c.stroke}" stroke-width="3" rx="4"/>
-      <rect x="${x}" y="${labelY}" width="${labelW}" height="${labelH}"
-            fill="${c.fill}" rx="3"/>
-      <text x="${x + 8}" y="${labelY + 14}"
-            font-size="11" font-weight="bold" fill="white"
-            font-family="system-ui, sans-serif">${r.annotation.label}</text>
-    `;
-  }).join('');
-
-  const svgOverlay = Buffer.from(
-    `<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg">${boxes}</svg>`
-  );
-
-  await sharp(inputPath)
-    .composite([{ input: svgOverlay, top: 0, left: 0 }])
-    .toFile(outputPath);
-}
-```
+`file-route-map.json` maps source files to the routes they affect. This is a reference for authoring new capture entries — when a commit touches `components/TopBar.tsx`, the `"*"` mapping tells you every route is potentially affected.
 
-### 12.3 Composition — Side-by-Side with Title Bar
-
-```typescript
-// compose.ts
-import sharp from 'sharp';
-
-async function composePair(
-  beforePath: string,
-  afterPath: string,
-  title: string,
-  outputPath: string,
-): Promise<void> {
-  const [bMeta, aMeta] = await Promise.all([
-    sharp(beforePath).metadata(),
-    sharp(afterPath).metadata(),
-  ]);
-
-  const bW = bMeta.width ?? 0;
-  const aW = aMeta.width ?? 0;
-  const maxH = Math.max(bMeta.height ?? 0, aMeta.height ?? 0);
-  const divider = 2;
-  const titleH = 48;
-  const footerH = 28;
-  const totalW = bW + aW + divider;
-  const totalH = maxH + titleH + footerH;
-
-  const titleSvg = `
-    <svg width="${totalW}" height="${titleH}">
-      <rect width="100%" height="100%" fill="#f8f9fb"/>
-      <text x="${totalW / 2}" y="30" text-anchor="middle"
-            font-size="14" font-weight="600" fill="#1f2937"
-            font-family="system-ui, sans-serif">${title}</text>
-    </svg>`;
-
-  const footerSvg = `
-    <svg width="${totalW}" height="${footerH}">
-      <rect width="100%" height="100%" fill="#f1f5f9"/>
-      <text x="${bW / 2}" y="18" text-anchor="middle"
-            font-size="11" fill="#64748b"
-            font-family="system-ui, sans-serif">BEFORE (main)</text>
-      <line x1="${bW + 1}" y1="4" x2="${bW + 1}" y2="24"
-            stroke="#cbd5e1" stroke-width="1"/>
-      <text x="${bW + divider + aW / 2}" y="18" text-anchor="middle"
-            font-size="11" fill="#64748b"
-            font-family="system-ui, sans-serif">AFTER (PR)</text>
-    </svg>`;
-
-  // Divider line
-  const dividerBuf = await sharp({
-    create: { width: divider, height: maxH, channels: 4,
-              background: { r: 203, g: 213, b: 225, alpha: 1 } },
-  }).png().toBuffer();
-
-  await sharp({
-    create: { width: totalW, height: totalH, channels: 4,
-              background: { r: 255, g: 255, b: 255, alpha: 1 } },
-  })
-    .composite([
-      { input: Buffer.from(titleSvg), top: 0, left: 0 },
-      { input: await sharp(beforePath).toBuffer(), top: titleH, left: 0 },
-      { input: dividerBuf, top: titleH, left: bW },
-      { input: await sharp(afterPath).toBuffer(), top: titleH, left: bW + divider },
-      { input: Buffer.from(footerSvg), top: titleH + maxH, left: 0 },
-    ])
-    .toFile(outputPath);
+```json
+{
+  "app/(shell)/grid-operators/page.tsx": ["/grid-operators"],
+  "components/TopBar.tsx": ["*"],
+  "public/logo.svg": ["*"]
 }
 ```
 
-### 12.4 Diff Detection — pixelmatch
+Use `git diff --name-only main...HEAD` to find changed files, then look them up here to determine which routes need captures.
 
-```typescript
-// diff.ts
-import { PNG } from 'pngjs';
-import pixelmatch from 'pixelmatch';
-import fs from 'fs';
+---
 
-interface DiffResult {
-  diffPixels: number;
-  totalPixels: number;
-  diffPercent: number;
-  diffImagePath: string;
-}
+## Output Artifacts
 
-function computeDiff(beforePath: string, afterPath: string, diffPath: string): DiffResult {
-  const img1 = PNG.sync.read(fs.readFileSync(beforePath));
-  const img2 = PNG.sync.read(fs.readFileSync(afterPath));
-
-  // Images must be same dimensions — pad smaller if needed
-  const width = Math.max(img1.width, img2.width);
-  const height = Math.max(img1.height, img2.height);
-  const diff = new PNG({ width, height });
-
-  const diffPixels = pixelmatch(
-    img1.data, img2.data, diff.data, width, height,
-    { threshold: 0.1, includeAA: false }
-  );
-
-  fs.writeFileSync(diffPath, PNG.sync.write(diff));
-
-  const totalPixels = width * height;
-  return {
-    diffPixels,
-    totalPixels,
-    diffPercent: Number(((diffPixels / totalPixels) * 100).toFixed(2)),
-    diffImagePath: diffPath,
-  };
-}
-```
+### `catalog.json`
 
-### 12.5 Upload — GitHub Branch Storage
-
-Research confirmed GitHub's API does not support direct image uploads to comments.
-The most durable strategy is **pushing images to a dedicated branch** and referencing
-via raw GitHub URLs. This is the approach used by `opengisch/comment-pr-with-images`.
-
-```typescript
-// upload.ts
-import { execSync } from 'child_process';
-
-function uploadToGitHubBranch(
-  imagePaths: string[],
-  branch = 'visual-regression-assets',
-  subdir = 'comparisons',
-): Map<string, string> {
-  const repo = 'TextureHQ/commongrid';
-  const urls = new Map<string, string>();
-
-  // Create orphan branch if it doesn't exist
-  try {
-    execSync(`git rev-parse --verify ${branch}`, { stdio: 'ignore' });
-  } catch {
-    execSync(`git checkout --orphan ${branch}`);
-    execSync('git rm -rf . 2>/dev/null || true');
-    execSync('git commit --allow-empty -m "init visual regression assets"');
-    execSync(`git checkout -`);
-  }
-
-  // Use worktree to add images without switching branches
-  const worktreePath = '/tmp/vr-upload';
-  execSync(`git worktree add ${worktreePath} ${branch} 2>/dev/null || true`);
-
-  for (const imgPath of imagePaths) {
-    const filename = imgPath.split('/').pop()!;
-    execSync(`mkdir -p ${worktreePath}/${subdir}`);
-    execSync(`cp ${imgPath} ${worktreePath}/${subdir}/${filename}`);
-    urls.set(
-      imgPath,
-      `https://raw.githubusercontent.com/${repo}/${branch}/${subdir}/${filename}`,
-    );
-  }
-
-  execSync(`cd ${worktreePath} && git add -A && git commit -m "VR: update comparison images" && git push origin ${branch}`, { stdio: 'inherit' });
-  execSync(`git worktree remove ${worktreePath}`);
-
-  return urls;
+```json
+{
+  "generatedAt": "2025-03-15T...",
+  "baseRef": "main",
+  "prRef": "HEAD",
+  "comparisons": [
+    {
+      "id": "header-spacing",
+      "commit": "106f641",
+      "description": "Header height h-14 → h-12",
+      "viewports": {
+        "desktop": {
+          "before": "captures/annotated/header-spacing-desktop-before.png",
+          "after":  "captures/annotated/header-spacing-desktop-after.png",
+          "comparison": "captures/comparisons/header-spacing-desktop.png",
+          "diffPercent": 3.41
+        }
+      }
+    }
+  ]
 }
 ```
 
-Alternative: use [CML](https://cml.dev) (`cml comment create`) which handles
-image embedding in PR comments automatically, or [imgbb](https://api.imgbb.com/)
-for zero-infrastructure external hosting.
+### `pr-screenshots.md`
 
-## 13. Existing Open-Source Visual Regression Tools
+A markdown report with tables of all comparisons and their diff percentages, suitable for pasting into PR descriptions.
 
-### Landscape Comparison
+---
 
-```
-┌──────────────────────────────────────────────────────────────────────────┐
-│                  VISUAL REGRESSION TOOL LANDSCAPE                       │
-│                                                                          │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌─────────────┐  │
-│  │  Lost Pixel  │  │  Argos CI    │  │   Chromatic  │  │   Percy     │  │
-│  │  ───────────  │  │  ──────────  │  │  ──────────  │  │  ─────────  │  │
-│  │  OSS / Free  │  │  OSS / Free  │  │  Freemium   │  │  SaaS only  │  │
-│  │  odiff (6x   │  │  Playwright  │  │  Storybook  │  │  DOM snap-  │  │
-│  │  faster diff) │  │  Cypress     │  │  deep integ │  │  shot based │  │
-│  │  Storybook + │  │  Puppeteer   │  │  TurboSnap  │  │  Multi-     │  │
-│  │  Page + PW   │  │  CI comments │  │  Cloud UI   │  │  browser    │  │
-│  │  Git baselines│  │  Anim freeze│  │  Review UI  │  │  rendering  │  │
-│  └──────────────┘  └──────────────┘  └──────────────┘  └─────────────┘  │
-│        ▲                  ▲                                               │
-│        │                  │                                               │
-│   Best fit for       Good for                                            │
-│   agentic / CI      complex apps                                         │
-│   lightweight       with animations                                      │
-│                                                                          │
-│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                    │
-│  │  Playwright  │  │  BackstopJS  │  │  reg-suit    │                    │
-│  │  built-in    │  │  ───────────  │  │  ──────────  │                    │
-│  │  ───────────  │  │  Puppeteer   │  │  S3 + GitHub │                    │
-│  │  toHaveScr.. │  │  Config-     │  │  Plugin      │                    │
-│  │  pixelmatch  │  │  driven      │  │  architecture│                    │
-│  │  Zero extra  │  │  Scenarios   │  │  Notify PR   │                    │
-│  │  deps needed │  │  Docker ref  │  │  via comment │                    │
-│  └──────────────┘  └──────────────┘  └──────────────┘                    │
-│        ▲                                                                 │
-│        │                                                                 │
-│   Simplest start                                                         │
-│   (already a dep)                                                        │
-└──────────────────────────────────────────────────────────────────────────┘
-```
-
-### Recommendation Matrix
+## Dependencies
 
-| Criterion | Lost Pixel | Playwright built-in | Argos CI | Custom (this spec) |
-|-----------|-----------|-------------------|----------|-------------------|
-| **Open source** | Yes | Yes | Yes | Yes |
-| **Dependency weight** | odiff-bin + config | Zero (already in PW) | CLI + service | sharp + pixelmatch |
-| **Agentic-friendly** | Config-driven JSON | Test file per route | Config-driven | Manifest-driven |
-| **Annotation/bbox** | No | No | Diff overlay only | **Yes — full control** |
-| **Before/after compose** | Diff overlay | 3-panel (expected/actual/diff) | Cloud UI | **Custom side-by-side** |
-| **PR integration** | GitHub Action comment | Test report artifact | PR comment | **Custom markdown table** |
-| **Learning curve** | Low | Very low | Low | Medium |
-| **Color-coded annotations** | No | No | No | **Yes** |
-| **Selective capture** | Stories/pages | Test-scoped | Stories/pages | **Per-commit manifest** |
+| Package | Role |
+|---------|------|
+| `playwright` | Headless Chromium automation |
+| `sharp` | Fast PNG composition and SVG overlay (no native canvas) |
+| `pixelmatch` | Pixel-level image comparison |
+| `pngjs` | PNG read/write for pixelmatch |
+| `tsx` | TypeScript execution without build step |
 
-### Recommendation
+---
 
-**For CommonGrid specifically:**
+## Adapting for Other Projects
 
-1. **Start with Playwright built-in** (`toHaveScreenshot`) for pure regression detection — zero new deps, catches unintended changes
-2. **Layer the custom system** (this spec) on top for PR-quality annotated comparison images — the bounding-box + color-coding + composition pipeline doesn't exist in any off-the-shelf tool
-3. **Consider Lost Pixel** if Storybook is ever adopted — it's the most lightweight OSS option with the fastest diff engine (odiff)
+This system is generic. To use it in a different Next.js (or any dev-server) project:
 
-The custom system fills a gap no existing tool covers: **per-commit, color-rationalized, annotated before/after comparison images** that communicate _what_ changed and _why_ at a glance in a PR description.
+1. **Copy `scripts/visual-regression/`** into your project
+2. **Edit `capture-manifest.json`**:
+   - Set `devServer.command` to your dev server start command
+   - Set `devServer.readyPattern` to the stdout string your server prints when ready
+   - Adjust ports if 4100/4101 conflict
+   - Define your `viewports`
+   - Author `captures` entries for the routes and regions you care about
+3. **Add npm scripts** to `package.json`:
+   ```json
+   "vr:capture": "npx tsx scripts/visual-regression/capture-vr.ts",
+   "vr:capture:pr-only": "npx tsx scripts/visual-regression/capture-vr.ts --skip-base"
+   ```
+4. **Add `.visual-regression/` to `.gitignore`**
+5. If your project has a prebuild step that populates public assets, ensure the `createWorktree` function in `capture-vr.ts` calls it (it currently runs `npm run prebuild`)
 
-## 14. Dependencies
+### Non-Next.js projects
 
-```
-# Core (all devDependencies)
-playwright          — browser automation + screenshots (may already be installed)
-sharp               — image annotation via SVG compositing (no native canvas dep)
-pixelmatch          — pixel-level diff detection (~150 lines, zero deps)
-pngjs               — PNG encode/decode for pixelmatch
-wait-on             — wait for dev server to be ready before capture
-
-# Optional
-join-images         — simplified side-by-side composition (built on sharp)
-odiff-bin           — 6x faster diff than pixelmatch (OCaml binary, optional upgrade)
-```
+The only Next.js-specific assumptions are:
+- `npx next dev -p <port>` as the dev server command (configurable in manifest)
+- `npm run prebuild` for data file population (edit `createWorktree` if not needed)
+- The content-readiness selector in `playwright-capture.ts` uses `[class*="DataTable"]` etc. — adjust to match your app's DOM patterns
 
-Total footprint: ~3MB added to devDependencies. No runtime impact.
+Everything else (worktree strategy, annotation, diffing, composition) is framework-agnostic.

From bc1fbcd462fc1997653bee2277b08c04743c02e3 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Tue, 17 Mar 2026 12:30:37 -0400
Subject: [PATCH 33/41] feat: add Codes column, changelog subtitle, Diffwatch
 alerting, and PR descriptions

- Grid Operators: merge EIA ID / BA Code / NERC into a single Codes column with linked badges
- Changelog: sharpen subtitle to distinguish data-change vs product-change feeds
- Diffwatch: add detect-alerts.ts (console-error and red-overlay scanning) and clean.ts
- Favicon: add preload link to layout.tsx
- PR descriptions: move to docs/pr-descriptions/ with hello-pr and diffwatch drafts
---
 PR_DESCRIPTION.md                             | 357 -----------------
 app/(shell)/changelog/page.tsx                |   2 +-
 app/(shell)/grid-operators/page.tsx           |  53 +--
 app/layout.tsx                                |   3 +
 .../PR_DESCRIPTION_DIFFWATCH.md               | 246 ++++++++++++
 .../PR_DESCRIPTION_HELLO-PR.md                | 373 ++++++++++++++++++
 package.json                                  |   4 +-
 scripts/visual-regression/capture-vr.ts       |  56 +++
 scripts/visual-regression/clean.ts            | 181 +++++++++
 scripts/visual-regression/detect-alerts.ts    | 195 +++++++++
 10 files changed, 1088 insertions(+), 382 deletions(-)
 delete mode 100644 PR_DESCRIPTION.md
 create mode 100644 docs/pr-descriptions/PR_DESCRIPTION_DIFFWATCH.md
 create mode 100644 docs/pr-descriptions/PR_DESCRIPTION_HELLO-PR.md
 create mode 100644 scripts/visual-regression/clean.ts
 create mode 100644 scripts/visual-regression/detect-alerts.ts

diff --git a/PR_DESCRIPTION.md b/PR_DESCRIPTION.md
deleted file mode 100644
index ff4998bb..00000000
--- a/PR_DESCRIPTION.md
+++ /dev/null
@@ -1,357 +0,0 @@
-## Summary
-
-Comprehensive UX, responsive design, and data-density overhaul across the CommonGrid registry. 23 commits addressing dropdown styling, table field coverage, sort UX, badge consistency, header spacing, Mapbox stability, changelog usability, narrow-viewport responsiveness, CMD+K search polish, and a new logo mark — the "G-in-C" with dendritic tree-graph connections.
-
-## Change Type
-
-- [x] `feat` — New feature or capability
-- [x] `fix` — Bug fix
-- [x] `style` — Visual/CSS changes (no logic change)
-- [ ] `refactor`
-- [ ] `docs`
-- [ ] `test`
-- [ ] `chore`
-- [ ] `perf`
-
-**User-facing change?** Yes — visual changes across all pages, new table columns, changelog tabs, logo redesign
-**Breaking change?** No
-
-## Changeset Overview
-
-| Metric | Value |
-|--------|-------|
-| Commits | **23** |
-| Files changed | **25** |
-| Insertions (+) | **+425** |
-| Deletions (−) | **−179** |
-| Net | **+246** |
-| PR size | **L** (425 insertions) |
-
-| Breakdown | Count |
-|-----------|-------|
-| `feat` commits | 10 |
-| `fix` commits | 6 |
-| `style` commits | 7 |
-| Low risk | 18 |
-| Medium risk | 5 |
-| High risk | 0 |
-
-## Test Plan
-
-### Automated
-- [ ] `next build` completes without errors
-- [ ] `npx biome check` passes
-
-### Manual — Visual Regression
-- [ ] **320px viewport**: Filters stack vertically, names wrap to 2 lines, no horizontal overflow
-- [ ] **768px viewport**: DataTable switches to desktop mode, explorer hybrid layout works
-- [ ] **1440px viewport**: All new columns visible (EIA ID, BA Code, NERC, Website, County, Year, Generators), header spacing proportional
-- [ ] **Dark mode toggle**: Badge colors, logo mark, changelog tabs, filter chips all render correctly
-- [ ] **Light mode toggle**: Same verification
-
-### Manual — Functional
-- [ ] CMD+K opens search → section headers show entity counts → "Loading more..." appears during Tier-2 fetch
-- [ ] Grid-operators: filter by jurisdiction → matching cells highlighted with brand color + bold
-- [ ] Grid-operators: new columns (EIA ID, BA Code, NERC, Website link) visible on desktop, hidden on mobile
-- [ ] Changelog: switch Data Changes ↔ Site Updates tabs → entity-type filter chips narrow results → search bar filters by name/detail text
-- [ ] Explorer map: switch hybrid → list → map → hybrid without blank/flash
-- [ ] Service territory detail: map zooms to tight bounds, not US-wide
-- [ ] All 5 data pages: sort dropdown labels show ▲/▼ direction indicators
-- [ ] All data pages: native `<select>` chevrons have inner right padding (no text crowding)
-
----
-
-## Motivation
-
-CommonGrid's table pages, header, and explorer map had accumulated fit-and-finish issues that individually were small but collectively degraded the experience — particularly at narrow viewports and on the grid-operators registry page. This PR treats them as a cohesive surface area, applying consistent patterns across all 5 data pages, the explorer, and the changelog.
-
-The logo redesign gives CommonGrid a distinctive mark — the letter G inscribed in C with dendritic tree-graph connections radiating outward — that communicates grid topology rather than a generic dot grid.
-
-Addresses items from the [commongrid.info issue backlog](https://github.com/TextureHQ/commongrid/issues).
-
-## Commit Log
-
-| Hash | Type | Scope | Description | Size | Risk |
-|------|------|-------|-------------|------|------|
-| `3f89367` | fix | dropdowns (9 files) | Inner right-side padding for chevrons | S | low |
-| `b7e25b2` | fix | globals.css + 4 pages | CSS hyphenation for long entity names | S | low |
-| `111ef3f` | fix | formatting.ts (×2) | Complete badge variant mapping for all utility segments | S | low |
-| `106f641` | style | TopBar, ShellLayout, GlobalSearch | Header spacing overhaul (h-14→h-12, tighter nav) | M | med |
-| `7c9de2f` | style | grid-operators | Conditional name clamping (line-clamp-2/1) | S | low |
-| `37b1abc` | feat | 5 data pages | Sort-direction ▲/▼ chevrons in dropdown labels | S | low |
-| `791740d` | feat | power-plants, transmission-lines | County, Year, Generators columns; From/To labels | M | low |
-| `ece78d0` | feat | grid-operators | Jurisdiction state-based highlighting on filter | S | low |
-| `ea227b5` | feat | changelog | Data Changes / Site Updates tab distinction | L | med |
-| `c9e343a` | fix | ExplorerMap | ResizeObserver replaces setTimeout for map resize | M | med |
-| `ecdc89b` | feat | TopBar, logo.svg | Logo redesign — G-in-C with dendritic graph | M | med |
-| `049d059` | style | 5 data pages | Stack filter dropdowns vertically at narrow breakpoints | S | low |
-| `ba4b06d` | feat | grid-operators | EIA ID, BA Code, NERC, website link columns | L | low |
-| `00353ab` | feat | GlobalSearch | CMD+K result counts and loading state | S | low |
-| `73c7db5` | fix | geo.ts | Finer-grained zoom for service territory bounds | S | med |
-| `7da3bdb` | feat | changelog | Search input and entity-type filter chips | L | low |
-| `8689455` | style | favicon.svg | Favicon updated to new logo mark | S | low |
-| `ed04191` | fix | ExplorerShell | Layout key on ExplorerMap for clean remount | S | low |
-| `f37bc36` | style | ExplorerTabBar | Mobile tab labels tightened to text-xs | S | low |
-| `c206859` | style | TopBar | Mobile menu active state + hover backgrounds | M | low |
-| `64d1943` | style | DataSourceLink | Truncate on narrow viewports | S | low |
-| `cf533a9` | style | SearchInput | Responsive height (h-10/h-11) + hidden result count | S | low |
-| `a3129d5` | feat | explore page | Page title and description metadata | S | low |
-
-## File Impact Matrix
-
-| File | Layer | +/− | Character |
-|------|-------|-----|-----------|
-| `app/(shell)/grid-operators/page.tsx` | page | +78/−11 | Major: 4 columns, highlighting, clamping |
-| `app/(shell)/changelog/page.tsx` | page | +116/−6 | Major: tab UI, search, entity filters |
-| `app/(shell)/power-plants/page.tsx` | page | +42/−9 | New columns: county, year, generators |
-| `app/(shell)/ev-charging/page.tsx` | page | +12/−12 | Style: padding, stacking, hyphenation |
-| `app/(shell)/pricing-nodes/page.tsx` | page | +9/−9 | Style: padding, sort labels |
-| `app/(shell)/transmission-lines/page.tsx` | page | +10/−10 | Style + From/To label rename |
-| `app/(shell)/explore/page.tsx` | page | +6/−0 | Metadata |
-| `components/TopBar.tsx` | component | +45/−39 | Logo SVG, spacing, mobile menu |
-| `components/explorer/ExplorerMap.tsx` | component | +15/−10 | ResizeObserver lifecycle fix |
-| `components/explorer/ExplorerShell.tsx` | component | +3/−3 | key={layout} prop |
-| `components/GlobalSearch.tsx` | component | +6/−2 | Result counts, loading text |
-| `components/ShellLayoutClient.tsx` | component | +1/−1 | pt-14→pt-12 |
-| `components/SearchInput.tsx` | component | +2/−2 | Responsive height + hidden count |
-| `components/DataSourceLink.tsx` | component | +1/−1 | Truncation |
-| `components/explorer/ExplorerTabBar.tsx` | component | +1/−1 | text-xs mobile |
-| `components/explorer/panels/*` (×4) | component | +4/−4 | Dropdown chevron padding |
-| `lib/formatting.ts` | lib | +9/−9 | Badge variant remapping |
-| `explorer/lib/formatting.ts` | lib | +9/−9 | Badge variant remapping (mirror) |
-| `lib/geo.ts` | lib | +8/−5 | Zoom calculation refinement |
-| `app/globals.css` | style | +8/−0 | `hyphens-auto` utility class |
-| `public/logo.svg` | asset | +20/−18 | G-in-C logo mark |
-| `public/favicon.svg` | asset | +20/−18 | Favicon matches new logo |
-
-## Architecture & Dependency
-
-### Review Order Dependency Graph
-
-```mermaid
-graph TD
-    subgraph "1 · Foundation"
-        CSS[globals.css<br/><i>hyphens-auto</i>]
-        FMT[lib/formatting.ts<br/><i>badge variants</i>]
-        GEO[lib/geo.ts<br/><i>zoom calc</i>]
-    end
-
-    subgraph "2 · Assets"
-        LOGO[public/logo.svg]
-        FAV[public/favicon.svg]
-    end
-
-    subgraph "3 · Shell"
-        TB[TopBar<br/><i>logo + spacing</i>]
-        SLC[ShellLayoutClient<br/><i>pt-12</i>]
-        GS[GlobalSearch<br/><i>counts + loading</i>]
-    end
-
-    subgraph "4 · Explorer"
-        EM[ExplorerMap<br/><i>ResizeObserver</i>]
-        ES[ExplorerShell<br/><i>key prop</i>]
-        ETB[ExplorerTabBar<br/><i>text-xs</i>]
-        PANELS[Panels ×4<br/><i>chevron padding</i>]
-    end
-
-    subgraph "5 · Shared"
-        SI[SearchInput]
-        DSL[DataSourceLink]
-    end
-
-    subgraph "6 · Data Pages"
-        GO[grid-operators<br/><i>7 commits</i>]
-        PP[power-plants<br/><i>5 commits</i>]
-        TL[transmission-lines]
-        EV[ev-charging]
-        PN[pricing-nodes]
-    end
-
-    subgraph "7 · Feature Pages"
-        CL[changelog<br/><i>tabs + search</i>]
-        EX[explore<br/><i>metadata</i>]
-    end
-
-    CSS --> GO & PP & TL & EV & PN
-    FMT --> GO & EV
-    GEO --> EM
-    LOGO --> TB
-    TB --> SLC
-    GS --> SLC
-    EM --> ES
-    SI --> GO & PP & TL & EV & PN
-    DSL --> GO & PP & TL & EV & PN
-
-    style CSS fill:#e1f5fe,stroke:#0277bd
-    style FMT fill:#e1f5fe,stroke:#0277bd
-    style GEO fill:#e1f5fe,stroke:#0277bd
-    style TB fill:#fff3e0,stroke:#ef6c00
-    style EM fill:#fff3e0,stroke:#ef6c00
-    style GO fill:#fce4ec,stroke:#c62828
-    style CL fill:#e8f5e9,stroke:#2e7d32
-```
-
-### Commit Clustering by Shared File
-
-```mermaid
-graph LR
-    subgraph "grid-operators — 7 commits"
-        G1[chevron] --> G2[hyphens] --> G3[clamp] --> G4[sort ▲▼] --> G5[stack] --> G6[highlight] --> G7[fields]
-    end
-
-    subgraph "TopBar — 3 commits"
-        T1[spacing] --> T2[logo] --> T3[mobile]
-    end
-
-    subgraph "changelog — 2 commits"
-        C1[tabs] --> C2[search]
-    end
-```
-
-## Changelog
-
-### Added
-- Sort-direction ▲/▼ indicators in all table sort dropdowns
-- Grid-operators table: EIA ID, BA Code, NERC Region, Website columns
-- Power-plants table: County, Operating Year, Generator Count columns
-- Transmission-lines table: From/To substation labels (renamed from Sub 1/Sub 2)
-- Changelog page: Data Changes / Site Updates tab bar
-- Changelog page: entity-type filter chips + text search
-- Changelog page: pulsing sync indicator
-- Jurisdiction highlighting when filter is active (brand color + bold)
-- CSS `hyphens-auto` utility class for browser word-breaking
-- Explore page: title and description metadata
-- CMD+K search: entity count badges on section headers
-- CMD+K search: "Loading more..." text for Tier-2 data
-
-### Changed
-- Logo: 12-circle grid → G-in-C with dendritic tree-graph connections
-- Favicon: updated to match new logo mark
-- Header: h-14 → h-12, tighter nav padding, larger logo-to-nav gap
-- Badge variants: Distribution Coop (warning→success), Municipal (success→warning), CCA (success→neutral), G&T (default→success), Transmission Operator (default→info), Joint Action (default→success)
-- Grid-operators name column: truncate → line-clamp-2 on mobile, line-clamp-1 on desktop
-- Mobile menu: added active brand color, hover backgrounds, border separator for GitHub link
-- Explorer tab labels: reduced to text-xs on mobile
-- Search input: h-11 → h-10 on mobile, result count hidden on narrow viewports
-- DataSourceLink: added truncation for narrow viewports
-
-### Fixed
-- Native `<select>` chevron crowding text — asymmetric padding (pl-2 pr-7) across 9 files
-- Mapbox component loads-then-blanks — ResizeObserver replaces fragile setTimeout
-- Map layout mode switch causing stale renders — key={layout} forces clean remount
-- Service territory zoom too wide — finer-grained zoom thresholds with intermediate steps
-- Filter dropdowns overflowing on narrow viewports — flex-col stacking below sm breakpoint
-
-## Responsive Breakpoint Audit
-
-| Breakpoint | Changes |
-|------------|---------|
-| **< sm** (640px) | Filters stack vertically · Search result count hidden · Input h-10 + text-sm · Names wrap 2 lines · Tab labels text-xs · Loading text hidden |
-| **< md** (768px) | Mobile menu: brand color active state + hover bg (new) · DataTable mobile mode (existing) |
-| **≥ lg** (1024px) | TopBar px-4 → lg:px-6 |
-| **All viewports** | Header h-14→h-12 · Nav tightened · Select pr-7 · CSS hyphens · Sort ▲/▼ · Badge colors |
-
-<details>
-<summary><strong>CSS / Tailwind Delta — Classes Added</strong></summary>
-
-| Class | Usage | Purpose |
-|-------|-------|---------|
-| `.hyphens-auto` (custom) | globals.css → 4 pages | Browser hyphenation for long names |
-| `line-clamp-2 sm:line-clamp-1` | grid-operators name | Responsive line wrapping |
-| `flex-col sm:flex-row` | All filter containers | Vertical stacking on mobile |
-| `pl-2 pr-7` | All `<select>` (9 files) | Asymmetric padding for native chevron |
-| `animate-pulse` | Changelog sync dot | Live data visual cue |
-| `hidden sm:inline` | SearchInput count, GlobalSearch text | Narrow-viewport hide |
-| `hover:bg-background-surface` | Mobile menu items | Touch feedback |
-| `tabular-nums` | New numeric columns | Monospace digit alignment |
-
-</details>
-
-<details>
-<summary><strong>CSS / Tailwind Delta — Classes Replaced</strong></summary>
-
-| Before | After | Where |
-|--------|-------|-------|
-| `h-14` | `h-12` | TopBar, ShellLayoutClient, GlobalSearch |
-| `pt-14` | `pt-12` | ShellLayoutClient main offset |
-| `top-14` | `top-12` | GlobalSearch backdrop |
-| `px-5` | `px-4 lg:px-6` | TopBar horizontal padding |
-| `gap-6` | `gap-8` | TopBar logo↔nav gap |
-| `px-3 py-1.5` | `px-2.5 py-1` | TopBar nav links |
-| `gap-1` | `gap-1.5` | TopBar icon groups |
-| `text-[15px]` | `text-sm` | TopBar brand text |
-| `px-2` | `pl-2 pr-7` | All filter `<select>` elements |
-| `truncate` | `line-clamp-2 sm:line-clamp-1 hyphens-auto` | Grid-operators name cell |
-
-</details>
-
-## Risk Assessment
-
-| Change | Risk | Blast Radius | Mitigation |
-|--------|------|-------------|------------|
-| TopBar h-14→h-12 + content offset | **Medium** | Every page (shell layout) | All 3 consumers updated: ShellLayoutClient, GlobalSearch, TopBar |
-| Logo SVG replacement | **Medium** | Header + favicon | Same viewBox (32×32), same className, uses currentColor |
-| ExplorerMap ResizeObserver | **Medium** | Map explorer page | Universal browser support; RAF prevents layout thrash |
-| Badge variant remapping | **Medium** | Grid-operators + explorer panels | Both formatting.ts files updated in sync |
-| Zoom calculation changes | **Medium** | Service territory map views | More granular = better; additive thresholds only |
-| Filter vertical stacking | **Low** | 5 data pages on mobile | Purely additive `flex-col` default; `sm:flex-row` preserves desktop |
-| New table columns | **Low** | grid-operators, power-plants | All `mobile: false` — zero mobile impact |
-| Changelog tabs + search | **Low** | Changelog page only | Default tab shows existing view; search is additive |
-| Sort ▲/▼ labels | **Low** | 5 data pages | Label text only; no behavioral change |
-| CSS hyphens-auto | **Low** | 4 data pages | CSS-only; browser hyphenation engine |
-
-```mermaid
-quadrantChart
-    title Change Risk vs Impact
-    x-axis Low Impact --> High Impact
-    y-axis Low Risk --> High Risk
-    TopBar height: [0.9, 0.8]
-    Logo redesign: [0.7, 0.65]
-    Map lifecycle: [0.6, 0.7]
-    Badge variants: [0.5, 0.5]
-    Filter stacking: [0.7, 0.35]
-    Zoom calc: [0.4, 0.55]
-    Changelog tabs: [0.8, 0.2]
-    New columns: [0.75, 0.15]
-    Sort chevrons: [0.3, 0.1]
-    Dropdown padding: [0.2, 0.08]
-```
-
-## Deferred Work
-
-- [ ] **Column hover panels with field enumeration / pie charts** — requires `@floating-ui` popover work. Tier 3.
-- [ ] **@tanstack/react-table migration** — new dependency; deserves its own PR.
-- [ ] **Explorer dual-panel layout** — requires `LayoutMode` type extension + reducer changes.
-- [ ] **Power plant custom fuel-type SVG icons** — art asset creation; needs design review.
-- [ ] **Streaming changelog with auto-refresh** — needs `useSWR` or polling strategy decision.
-- [ ] **Recent searches in CMD+K (localStorage)** — edit spec available; deferred to limit scope.
-
-## Reviewer Checklist
-
-- [ ] Changeset overview matches `git diff --stat main...welcome-pr`
-- [ ] Risk assessment reviewed — no items should be elevated to "high"
-- [ ] No secrets, credentials, or `.env` values committed
-- [ ] Responsive behavior verified at 320px, 768px, 1440px
-- [ ] Accessibility: focus order preserved, no contrast regressions
-- [ ] Badge color changes reviewed against segment semantics (IOU=info, Coop=success, Municipal=warning, CCA=neutral)
-- [ ] Logo mark legible at 24×24px in both light and dark mode
-
-## Screenshots / Recordings
-
-_Attach before/after screenshots at key breakpoints before merging._
-
-| Viewport | Before | After |
-|----------|--------|-------|
-| Mobile (375px) | | |
-| Tablet (768px) | | |
-| Desktop (1440px) | | |
-| Logo (24×24) | | |
-
-```release-note
-Redesigned CommonGrid logo to G-in-C dendritic mark. Added EIA ID, BA Code,
-NERC, and Website columns to grid-operators table. Added County, Year, and
-Generator Count to power-plants. Introduced Data Changes / Site Updates tabs
-and search on changelog. Sort dropdowns now show ▲/▼ direction. Fixed Mapbox
-blank-on-layout-switch, dropdown chevron padding, and badge color mapping.
-Improved responsive design at narrow viewports across all data pages.
-```
diff --git a/app/(shell)/changelog/page.tsx b/app/(shell)/changelog/page.tsx
index 4a0e3f48..734bfae6 100644
--- a/app/(shell)/changelog/page.tsx
+++ b/app/(shell)/changelog/page.tsx
@@ -169,7 +169,7 @@ export default function ChangelogPage() {
     <PageLayout maxWidth={900}>
       <PageLayout.Header
         title="Changelog"
-        description="Live changes streaming from the energy industry — new entities added and existing records updated from authoritative sources."
+        description="What's changing in the grid data we track — and in the tools we're building to track it."
       />
       <PageLayout.Content>
         {/* Tab bar */}
diff --git a/app/(shell)/grid-operators/page.tsx b/app/(shell)/grid-operators/page.tsx
index c3daad56..5d3ac196 100644
--- a/app/(shell)/grid-operators/page.tsx
+++ b/app/(shell)/grid-operators/page.tsx
@@ -224,30 +224,37 @@ function GridOperatorsPageInner() {
         mobile: false,
       },
       {
-        id: "eiaId",
-        label: "EIA ID",
+        id: "codes",
+        label: "Codes",
         accessor: "eiaId",
-        render: (_value: unknown, row: UtilityRow) => (
-          <span className="text-text-muted tabular-nums text-xs">{row.eiaId ?? "—"}</span>
-        ),
-        mobile: false,
-      },
-      {
-        id: "baCode",
-        label: "BA Code",
-        accessor: "baCode",
-        render: (_value: unknown, row: UtilityRow) => (
-          <span className="text-text-muted text-xs">{row.baCode ?? "—"}</span>
-        ),
-        mobile: false,
-      },
-      {
-        id: "nercRegion",
-        label: "NERC",
-        accessor: "nercRegion",
-        render: (_value: unknown, row: UtilityRow) => (
-          <span className="text-text-muted text-xs">{row.nercRegion ?? "—"}</span>
-        ),
+        render: (_value: unknown, row: UtilityRow) => {
+          const codes = [
+            row.eiaId ? { label: "EIA", value: row.eiaId, href: `https://www.eia.gov/electricity/data/eia861/` } : null,
+            row.baCode ? { label: "BA", value: row.baCode, href: `https://www.eia.gov/electricity/gridmonitor/` } : null,
+            row.nercRegion ? { label: "NERC", value: row.nercRegion, href: `https://www.nerc.com/AboutNERC/keyplayers/Pages/default.aspx` } : null,
+          ].filter(Boolean) as { label: string; value: string; href: string }[];
+
+          if (codes.length === 0) return <span className="text-text-muted">—</span>;
+
+          return (
+            <div className="flex flex-col gap-0.5">
+              {codes.map((c) => (
+                <a
+                  key={c.label}
+                  href={c.href}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  onClick={(e) => e.stopPropagation()}
+                  className="inline-flex items-center gap-1 rounded bg-surface-secondary px-1.5 py-0.5 text-[10px] leading-tight text-text-muted hover:text-brand-primary hover:bg-surface-tertiary transition-colors w-fit tabular-nums"
+                  title={`${c.label}: ${c.value}`}
+                >
+                  <span className="font-semibold text-text-subtle">{c.label}</span>
+                  <span>{c.value}</span>
+                </a>
+              ))}
+            </div>
+          );
+        },
         mobile: false,
       },
       {
diff --git a/app/layout.tsx b/app/layout.tsx
index a52182e2..e4c17260 100644
--- a/app/layout.tsx
+++ b/app/layout.tsx
@@ -14,6 +14,9 @@ export const metadata: Metadata = {
     default: "CommonGrid",
   },
   description: "Community-maintained energy knowledge base",
+  icons: {
+    icon: "/favicon.svg",
+  },
 };
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
diff --git a/docs/pr-descriptions/PR_DESCRIPTION_DIFFWATCH.md b/docs/pr-descriptions/PR_DESCRIPTION_DIFFWATCH.md
new file mode 100644
index 00000000..8cf05e99
--- /dev/null
+++ b/docs/pr-descriptions/PR_DESCRIPTION_DIFFWATCH.md
@@ -0,0 +1,246 @@
+<!--
+  PR Description: diffwatch
+  Convention: CommonGrid PR Description Standard v1.0
+
+  This PR is one of a two-PR set:
+    1. hello-pr        — UX, responsive design, and data-density overhaul
+    2. diffwatch       — Visual regression capture system (this PR)
+
+  Diffwatch was built during hello-pr development to verify visual changes.
+  The commit history interleaves chronologically, but this PR is self-contained.
+-->
+
+## Summary
+
+Diffwatch is a visual regression capture system for CommonGrid. It automates before/after screenshot generation, region annotation, pixel diffing, side-by-side comparison composition, and alert detection — producing a markdown report and catalog for PR review. Built as dev tooling during the hello-pr UX overhaul to systematically verify 25+ visual changes across 9 pages and 3 viewport tiers.
+
+## Change Type
+
+- [x] `feat` — New feature or capability
+- [x] `fix` — Bug fix
+- [x] `docs` — Documentation only
+- [x] `chore` — Build, CI, dependency, or tooling changes
+- [ ] `style`
+- [ ] `refactor`
+- [ ] `test`
+- [ ] `perf`
+
+**User-facing change?** No — dev tooling only
+**Breaking change?** No
+
+## Changeset Overview
+
+| Metric | Value |
+|--------|-------|
+| Commits | **7** |
+| New files | **10** |
+| PR size | **L** |
+
+| Breakdown | Count |
+|-----------|-------|
+| `feat` commits | 1 (core implementation) |
+| `fix` commits | 2 (worktree prebuild, port conflicts) |
+| `docs` commits | 3 (spec, reference, as-built rewrite) |
+| `chore` commits | 1 (detect-alerts + clean script) |
+
+---
+
+## Motivation
+
+The hello-pr branch accumulated 25+ commits touching 9 pages across 3 viewport tiers. We wanted first-class observability of visual changes directly within the PR description — not as a manual appendix, but as an automated, reproducible artifact that an agent or developer can generate on demand.
+
+Diffwatch applies established visual regression analysis methods — before/after capture, pixel diffing, annotated comparison composition — in an agent-first paradigm where the default workflow is automated capture rather than manual screenshotting. The pipeline is manifest-driven: define targets (routes, regions, viewports), and Diffwatch handles the full cycle — parallel dev servers via git worktree isolation, headless Chromium capture, region annotation, pixel diff quantification, side-by-side composition, error indicator detection, and markdown report generation.
+
+### Design Decisions
+- **Git worktree** (not stash/checkout) — enables parallel base + PR servers simultaneously
+- **Sharp SVG composite** (not Canvas) — no native dependency; works on any OS without `node-canvas` build
+- **pixelmatch** — same diff engine Playwright uses internally; consistent threshold semantics
+- **Edge-margin alert detection** — scans only screenshot corners for red pill indicators, ignoring legitimate red UI elements in page content
+
+## Architecture & Dependency
+
+```mermaid
+graph TD
+    subgraph "Configuration"
+        MANIFEST[capture-manifest.json<br>routes, regions, viewports]
+        ROUTEMAP[file-route-map.json<br>source file → route mapping]
+    end
+
+    subgraph "Pipeline"
+        ORCH[capture-vr.ts<br>orchestrator + CLI]
+        PW[playwright-capture.ts<br>Chromium automation]
+        ANN[annotate.ts<br>Sharp SVG bounding boxes]
+        DIFF[diff.ts<br>pixelmatch pixel diff]
+        COMP[compose.ts<br>side-by-side composition]
+        ALERT[detect-alerts.ts<br>red pill corner scanner]
+    end
+
+    subgraph "Lifecycle"
+        CLEAN[clean.ts<br>safe clear + run-log ledger]
+    end
+
+    subgraph "Output"
+        CAPS[captures/<br>before · after · annotated<br>comparisons · diffs]
+        CAT[catalog.json]
+        RPT[pr-screenshots.md]
+        LOG[run-log.jsonl]
+    end
+
+    MANIFEST --> ORCH
+    ORCH --> PW --> CAPS
+    ORCH --> ANN --> CAPS
+    ORCH --> DIFF --> CAPS
+    ORCH --> COMP --> CAPS
+    ORCH --> ALERT
+    ORCH --> CAT & RPT
+    CLEAN --> LOG
+
+    style ORCH fill:#fef08a,stroke:#a16207,color:#713f12
+    style ALERT fill:#fecaca,stroke:#b91c1c,color:#7f1d1d
+    style MANIFEST fill:#dbeafe,stroke:#1d4ed8,color:#1e3a5f
+    style CLEAN fill:#e0e7ff,stroke:#4338ca,color:#312e81
+```
+
+### Execution Flow
+
+```mermaid
+flowchart LR
+    CLI[CLI args] --> PRE[Prebuild<br>+ port check]
+    PRE --> SRV[Start servers<br>PR:4101 Base:4100]
+    SRV --> CAP[Playwright<br>capture loop]
+    CAP --> KILL[Kill servers<br>remove worktree]
+    KILL --> ANN[Annotate<br>+ diff]
+    ANN --> SCAN[Alert<br>scan]
+    SCAN --> OUT[Compose<br>+ report]
+
+    style CLI fill:#f8fafc,stroke:#64748b,color:#1e293b
+    style SRV fill:#dbeafe,stroke:#1d4ed8,color:#1e3a5f
+    style CAP fill:#dbeafe,stroke:#1d4ed8,color:#1e3a5f
+    style KILL fill:#fecaca,stroke:#b91c1c,color:#7f1d1d
+    style SCAN fill:#fef08a,stroke:#a16207,color:#713f12
+    style OUT fill:#bbf7d0,stroke:#15803d,color:#14532d
+```
+
+---
+
+## Risk Assessment
+
+| Change | Risk | Blast Radius | Mitigation |
+|--------|------|-------------|------------|
+| New dev dependencies (playwright, sharp, pixelmatch, pngjs) | **Low** | Dev only | Not bundled; gitignored output |
+| Git worktree operations in /tmp | **Low** | Local filesystem | Force-cleanup in finally blocks |
+| Port 4100/4101 usage | **Low** | Local dev only | Pre-flight port check aborts if occupied |
+| npm script additions | **Low** | package.json | Additive; no existing scripts modified |
+
+---
+
+## Commit Log
+
+| Hash | Type | Description | Size | Risk |
+|------|------|-------------|------|------|
+| `2622431` | docs | Visual regression capture system specification | L | low |
+| `ca3ae6b` | docs | Concrete implementation reference and tool landscape | M | low |
+| `f117566` | feat | Implement Diffwatch — 5 core modules (capture, annotate, diff, compose, playwright) | XL | low |
+| `3494749` | fix | Resolve 404 in BEFORE captures by running prebuild in worktree | S | low |
+| `ffecf2f` | fix | Change ports to 4100/4101 + port-availability check | S | low |
+| `534f46d` | docs | Rewrite as as-built reference with mermaid diagrams | L | low |
+| _staged_ | feat | Alert indicator detection (detect-alerts.ts) + clean script (clean.ts) | M | low |
+
+### Commit Clustering by Shared File
+
+| File | Commits | Progression |
+|------|---------|-------------|
+| `capture-vr.ts` | 3 | implement → prebuild fix → port fix |
+| `visual-regression-system.md` | 3 | spec → reference → as-built rewrite |
+| `capture-manifest.json` | 1 | initial capture definitions |
+
+## File Impact Matrix
+
+| File | Layer | Character |
+|------|-------|-----------|
+| `scripts/visual-regression/capture-vr.ts` | tooling | Orchestrator: CLI, servers, worktree, phases |
+| `scripts/visual-regression/playwright-capture.ts` | tooling | Headless Chromium: navigate, wait, screenshot, bbox |
+| `scripts/visual-regression/annotate.ts` | tooling | Sharp SVG composite: bounding boxes + labels |
+| `scripts/visual-regression/compose.ts` | tooling | Side-by-side comparison image composition |
+| `scripts/visual-regression/diff.ts` | tooling | pixelmatch: pixel-level diff + overlay |
+| `scripts/visual-regression/detect-alerts.ts` | tooling | Edge-margin red pill scanner |
+| `scripts/visual-regression/clean.ts` | tooling | Safe clear + run-log.jsonl archival |
+| `scripts/visual-regression/capture-manifest.json` | config | Route, region, viewport definitions |
+| `scripts/visual-regression/file-route-map.json` | config | Source file → affected route mapping |
+| `docs/visual-regression-system.md` | docs | As-built reference with mermaid diagrams |
+| `package.json` | config | npm scripts: vr:capture, vr:capture:pr-only, vr:clean, vr:clean:all |
+| `.gitignore` | config | .visual-regression/ exclusion |
+
+---
+
+## Changelog
+
+### Added
+- `npm run vr:capture` — full before/after screenshot pipeline via git worktree + parallel dev servers
+- `npm run vr:capture:pr-only` — PR-only mode (skip base worktree)
+- `npm run vr:clean` — safe output clear with run-log archival
+- `npm run vr:clean:all` — full clear including run-log
+- CLI flags: `--base-ref`, `--captures`, `--viewports`, `--skip-capture`, `--skip-base`, `--skip-compose`, `--output`
+- Capture manifest schema with routes, regions, viewports, actions, color semantics
+- Region annotation with 5 semantic colors (red/green/blue/orange/yellow)
+- Pixel diff quantification via pixelmatch (threshold 0.1)
+- Side-by-side comparison composition with title bar and footer
+- Edge-margin red pill alert detection (Next.js error indicator scanner)
+- Run-log.jsonl reconstruction ledger surviving cleans
+- As-built documentation with mermaid diagrams
+
+---
+
+## Screenshots / Recordings
+
+_Diffwatch is dev tooling — no user-facing screenshots. Example outputs from the hello-pr run:_
+
+### Example Comparison Output
+<!-- ![example-comparison](URL) -->
+_Side-by-side composition: title bar with description and viewport, BEFORE | AFTER panels, footer with branch labels._
+
+### Example Alert Detection
+<!-- ![alert-detection](URL) -->
+_Red pill indicator (Next.js "1 Issue") detected in bottom-left corner of sort-chevrons capture._
+
+---
+
+## Reviewer Checklist
+
+- [ ] No secrets, credentials, or `.env` values committed
+- [ ] All new files are under `scripts/visual-regression/` or `docs/`
+- [ ] `.visual-regression/` is in `.gitignore`
+- [ ] `npm run vr:capture` runs to completion
+- [ ] `npm run vr:clean` archives metadata and clears output
+- [ ] Documentation in `docs/visual-regression-system.md` matches implementation
+
+## Test Plan
+
+### Automated
+- [ ] `npm run vr:capture` completes without errors (full pipeline)
+- [ ] `npm run vr:capture -- --captures badge-variants --viewports desktop` (filtered run)
+- [ ] `npm run vr:capture -- --skip-capture` (reprocess existing screenshots)
+- [ ] `npm run vr:clean` (archive + clear)
+- [ ] `npm run vr:clean -- --dry-run` (preview without deleting)
+
+### Manual
+- [ ] Alert detection flags the Next.js "1 Issue" pill on sort-chevrons but not legitimate red badges
+- [ ] Run-log.jsonl contains reconstruction metadata after clean
+- [ ] Comparison images render correctly with title bar, divider, and footer
+
+## Deferred Work
+
+- [ ] **Gridwatch CI integration** — run captures in GitHub Actions on PR open
+- [ ] **Threshold-based pass/fail** — auto-fail if diff exceeds configurable percentage
+- [ ] **Full-page capture mode** — option for scrollable page screenshots
+- [ ] **Dark mode captures** — capture both color schemes per viewport
+- [ ] **Image upload automation** — push comparison images to GitHub issue for embedding
+
+---
+
+```release-note
+Added Diffwatch — a visual regression capture system for automated before/after
+screenshot comparison. Captures screenshots via parallel dev servers with git
+worktree isolation, annotates regions of interest, computes pixel diffs, composes
+side-by-side comparison images, and detects error indicators automatically.
+```
diff --git a/docs/pr-descriptions/PR_DESCRIPTION_HELLO-PR.md b/docs/pr-descriptions/PR_DESCRIPTION_HELLO-PR.md
new file mode 100644
index 00000000..c61c942c
--- /dev/null
+++ b/docs/pr-descriptions/PR_DESCRIPTION_HELLO-PR.md
@@ -0,0 +1,373 @@
+<!--
+  PR Description: hello-pr
+  Convention: CommonGrid PR Description Standard v1.0
+
+  This PR is one of a two-PR set:
+    1. hello-pr        — UX, responsive design, and data-density overhaul (this PR)
+    2. diffwatch       — Visual regression capture system (separate, self-contained PR)
+
+  Diffwatch was built during hello-pr development to verify visual changes.
+  The commit history interleaves, but the PRs are scoped independently.
+-->
+
+## PR Description Convention
+
+| # | Section | Purpose | Position Rationale | Derives From | Feeds Into |
+|---|---------|---------|-------------------|--------------|------------|
+| 1 | **Summary** | TL;DR — what changed and why in 1-3 sentences | First: orient the reader immediately | — | All sections |
+| 2 | **Change Type** | Conventional Commit type classification | Early: frame the nature of changes before detail | Summary | Commit Log |
+| 3 | **Changeset Overview** | Quantitative shape of the PR (commits, files, lines) | Early: set expectations for review size | git diff --stat | Risk Assessment |
+| 4 | **Motivation** | Problem statement, who benefits, why now | Early: establish context before architecture | Issues, backlog | Architecture, Deferred Work |
+| 5 | **Architecture & Dependency** | Review-order dependency graph, layer relationships | Before detail: show how pieces connect | File Impact Matrix | Risk Assessment |
+| 6 | **Risk Assessment** | Regression likelihood and blast radius per change | Middle: informed by architecture, informs review | Architecture, Changeset | Reviewer Checklist |
+| 7 | **Risk vs Impact Chart** | Visual quadrant plot derived from risk assessment | After risk: visual summary of the table above | Risk Assessment | Reviewer Checklist |
+| 8 | **Responsive Breakpoint Audit** | What changed at each viewport threshold | After risk: a specific risk dimension for UI PRs | File Impact Matrix | Screenshots |
+| 9 | **Commit Log** | Per-commit type/scope/size/risk classification | Lower: reference detail, not primary reading | Change Type | File Impact Matrix |
+| 10 | **Commit Clustering** | Which files are touched by multiple commits | After commit log: density view of commit overlap | Commit Log | Risk Assessment |
+| 11 | **File Impact Matrix** | Per-file layer and change character | After commits: the file-level complement | Commit Log | Architecture |
+| 12 | **Changelog** | Keep a Changelog categories (Added/Changed/Fixed) | Lower: user-facing summary for release notes | Commit Log | Release Note |
+| 13 | **Screenshots / Recordings** | Visual evidence at key breakpoints | Near bottom: attestation of visual changes | Diffwatch captures | Reviewer Checklist |
+| 14 | **Reviewer Checklist** | Confirmation checkboxes for reviewer sign-off | After screenshots: review with visual context | Risk Assessment | Merge decision |
+| 15 | **Test Plan** | How changes were verified (automated + manual) | Near bottom: verification after full context | All sections | Merge decision |
+| 16 | **Deferred Work** | Explicitly out-of-scope items with rationale | Last: what comes next | Motivation | Future PRs |
+| 17 | **Release Note** | Single-block changelog entry for automation | Last: machine-readable output | Changelog | CI/CD |
+
+---
+
+## Summary
+
+Comprehensive UX, responsive design, and data-density overhaul across the CommonGrid registry. 25 commits across ~30 files addressing: table data density (consolidated Codes column with linked EIA/BA/NERC badges), dropdown styling, sort UX, badge consistency, header spacing, Mapbox stability, changelog tabs + search, narrow-viewport responsiveness, and CMD+K search polish.
+
+Visual changes were verified using **Diffwatch**, a custom visual regression capture system developed as a companion to this work and submitted as a [separate PR](#) with its own commit history.
+
+## Change Type
+
+- [x] `feat` — New feature or capability
+- [x] `fix` — Bug fix
+- [x] `style` — Visual/CSS changes (no logic change)
+- [x] `docs` — Documentation only
+- [ ] `refactor`
+- [ ] `test`
+- [ ] `chore`
+- [ ] `perf`
+
+**User-facing change?** Yes — visual changes across all pages, new table columns, changelog tabs, consolidated Codes column
+**Breaking change?** No
+
+## Changeset Overview
+
+| Metric | Value |
+|--------|-------|
+| Commits | **~25** |
+| Files changed | **~30** |
+| PR size | **L** |
+
+| Breakdown | Count |
+|-----------|-------|
+| `feat` commits | 10 |
+| `fix` commits | 6 |
+| `style` commits | 7 |
+| `docs` commits | 2 |
+
+> Exact stats will be finalized after the Diffwatch commits are extracted to their own branch.
+
+---
+
+## Motivation
+
+CommonGrid's table pages, header, and explorer map had accumulated fit-and-finish issues that individually were small but collectively degraded the experience — particularly at narrow viewports and on the grid-operators registry page. This PR treats them as a cohesive surface area, applying consistent patterns across all 5 data pages, the explorer, and the changelog.
+
+To surface regulatory identifiers, we initially introduced three new table columns — EIA ID, BA Code, and NERC — giving each code its own column. In practice this was too sparse: most rows showed triple em-dashes, the table grew wider than necessary, and the codes lacked navigational value. We iterated to a single **Codes** column that stacks only the codes present for each entity as compact linked badges, each pointing to its respective source (EIA-861, EIA Grid Monitor, NERC). This makes the data denser, the table narrower, and the identifiers actionable.
+
+To achieve better observability of visual changes directly within the PR description itself, we pioneered **Diffwatch** — a convention and toolchain drawing on established visual regression analysis methods, adapted to an agent-first paradigm where automated capture, annotation, diffing, and composition are the default workflow rather than a manual afterthought. Diffwatch is submitted as its own PR, but its screenshots are embedded here as visual attestation.
+
+### Relationship to Diffwatch PR
+
+| PR | Scope | Depends On |
+|----|-------|-----------|
+| **hello-pr** (this) | UX overhaul — all user-facing changes | None |
+| **diffwatch** (companion) | Visual regression system — tooling | None (standalone) |
+
+The commit histories interleave chronologically (Diffwatch was built mid-flight), but the PRs are scoped independently. Neither depends on the other to merge. Diffwatch screenshots are referenced here for review convenience.
+
+## Architecture & Dependency
+
+```mermaid
+graph TD
+    subgraph "1 · Foundation"
+        CSS[globals.css<br>hyphens-auto]
+        FMT[lib/formatting.ts<br>badge variants]
+        GEO[lib/geo.ts<br>zoom calc]
+    end
+
+    subgraph "2 · Shell"
+        TB[TopBar<br>spacing + mobile]
+        SLC[ShellLayoutClient<br>pt-12]
+        GS[GlobalSearch<br>counts + loading]
+    end
+
+    subgraph "3 · Explorer"
+        EM[ExplorerMap<br>ResizeObserver]
+        ES[ExplorerShell<br>key prop]
+    end
+
+    subgraph "4 · Data Pages"
+        GO[grid-operators<br>Codes column]
+        PP[power-plants]
+        TL[transmission-lines]
+        EV[ev-charging]
+        PN[pricing-nodes]
+    end
+
+    subgraph "5 · Feature Pages"
+        CL[changelog<br>tabs + search]
+    end
+
+    CSS --> GO & PP & TL & EV & PN
+    FMT --> GO & EV
+    GEO --> EM
+    TB --> SLC
+    EM --> ES
+
+    style GO fill:#dbeafe,stroke:#1d4ed8,color:#1e3a5f
+    style CL fill:#bbf7d0,stroke:#15803d,color:#14532d
+```
+
+---
+
+## Risk Assessment
+
+| Change | Risk | Blast Radius | Mitigation |
+|--------|------|-------------|------------|
+| TopBar h-14→h-12 + content offset | **Medium** | Every page (shell layout) | All consumers updated in sync |
+| ExplorerMap ResizeObserver | **Medium** | Map explorer page | Universal browser support; RAF prevents thrash |
+| Badge variant remapping | **Medium** | Grid-operators + explorer panels | Both formatting.ts files updated |
+| Zoom calculation changes | **Medium** | Service territory map views | Additive thresholds only |
+| Codes column consolidation | **Low** | Grid-operators desktop only | `mobile: false`; links open in new tab |
+| Filter vertical stacking | **Low** | 5 data pages on mobile | Purely additive; desktop unchanged |
+| Changelog tabs + search | **Low** | Changelog page only | Default tab shows existing view |
+
+### Change Risk vs Impact
+
+```mermaid
+quadrantChart
+    title Change Risk vs Impact
+    x-axis Low Impact --> High Impact
+    y-axis Low Risk --> High Risk
+    TopBar height: [0.9, 0.8]
+    Map lifecycle: [0.6, 0.7]
+    Badge variants: [0.5, 0.5]
+    Zoom calc: [0.4, 0.55]
+    Filter stacking: [0.7, 0.35]
+    Changelog tabs: [0.8, 0.2]
+    Codes column: [0.75, 0.15]
+    Sort chevrons: [0.3, 0.1]
+```
+
+> Coordinates reflect subjective placement based on blast radius (x-axis) and regression likelihood (y-axis). Items in the upper-right quadrant warrant closest review.
+
+## Responsive Breakpoint Audit
+
+| Breakpoint | Changes |
+|------------|---------|
+| **< sm** (640px) | Filters stack vertically · Search result count hidden · Input h-10 · Names wrap 2 lines · Tab labels text-xs |
+| **< md** (768px) | Mobile menu: brand color active state + hover bg · DataTable mobile mode |
+| **≥ lg** (1024px) | TopBar px-4 → lg:px-6 |
+| **All viewports** | Header h-14→h-12 · Nav tightened · Select pr-7 · CSS hyphens · Sort ▲/▼ · Badge colors · Codes column |
+
+---
+
+## Commit Log
+
+| Hash | Type | Scope | Description | Size | Risk |
+|------|------|-------|-------------|------|------|
+| `3f89367` | fix | dropdowns (9 files) | Inner right-side padding for chevrons | S | low |
+| `b7e25b2` | fix | globals.css + 4 pages | CSS hyphenation for long entity names | S | low |
+| `111ef3f` | fix | formatting.ts (×2) | Complete badge variant mapping for all utility segments | S | low |
+| `106f641` | style | TopBar, ShellLayout, GlobalSearch | Header spacing overhaul (h-14→h-12, tighter nav) | M | med |
+| `7c9de2f` | style | grid-operators | Conditional name clamping (line-clamp-2/1) | S | low |
+| `37b1abc` | feat | 5 data pages | Sort-direction ▲/▼ chevrons in dropdown labels | S | low |
+| `791740d` | feat | power-plants, transmission-lines | County, Year, Generators columns; From/To labels | M | low |
+| `ece78d0` | feat | grid-operators | Jurisdiction state-based highlighting on filter | S | low |
+| `ea227b5` | feat | changelog | Data Changes / Site Updates tab distinction | L | med |
+| `c9e343a` | fix | ExplorerMap | ResizeObserver replaces setTimeout for map resize | M | med |
+| `ecdc89b` | feat | TopBar, logo.svg | Logo redesign — G-in-C _(reverted by bf7378b)_ | M | — |
+| `049d059` | style | 5 data pages | Stack filter dropdowns vertically at narrow breakpoints | S | low |
+| `ba4b06d` | feat | grid-operators | EIA ID, BA Code, NERC, website link columns | L | low |
+| `00353ab` | feat | GlobalSearch | CMD+K result counts and loading state | S | low |
+| `73c7db5` | fix | geo.ts | Finer-grained zoom for service territory bounds | S | med |
+| `7da3bdb` | feat | changelog | Search input and entity-type filter chips | L | low |
+| `8689455` | style | favicon.svg | Favicon updated to new logo _(reverted by bf7378b)_ | S | — |
+| `ed04191` | fix | ExplorerShell | Layout key on ExplorerMap for clean remount | S | low |
+| `f37bc36` | style | ExplorerTabBar | Mobile tab labels tightened to text-xs | S | low |
+| `c206859` | style | TopBar | Mobile menu active state + hover backgrounds | M | low |
+| `64d1943` | style | DataSourceLink | Truncate on narrow viewports | S | low |
+| `cf533a9` | style | SearchInput | Responsive height (h-10/h-11) + hidden result count | S | low |
+| `a3129d5` | feat | explore page | Page title and description metadata | S | low |
+| `5a0db81` | docs | PR template | Refine PR template with research findings | M | low |
+| `ff146f7` | docs | PR template | Add PR description template | L | low |
+| `bf7378b` | revert | TopBar, logo, favicon | Revert logo redesign (G-in-C) | M | low |
+| _staged_ | feat | grid-operators | Consolidate EIA/BA/NERC into linked Codes column | M | low |
+| _staged_ | chore | layout.tsx | Explicit favicon icon metadata | S | low |
+
+> Commits `ecdc89b` and `8689455` are net-zero (reverted by `bf7378b`). Marked — risk.
+
+### Commit Clustering by Shared File
+
+| File | Commits | Commit Types |
+|------|---------|-------------|
+| `grid-operators/page.tsx` | 7 | fix, style, feat (chevron → hyphens → clamp → sort → stack → highlight → codes) |
+| `TopBar.tsx` | 3 | style, feat, revert (spacing → mobile menu → logo revert) |
+| `changelog/page.tsx` | 2 | feat (tabs → search) |
+| `lib/formatting.ts` | 2 | fix (badge variants, mirrored in explorer/) |
+| `ExplorerMap.tsx` | 2 | fix (ResizeObserver → key prop via ExplorerShell) |
+
+## File Impact Matrix
+
+| File | Layer | Character |
+|------|-------|-----------|
+| `app/(shell)/grid-operators/page.tsx` | page | Major: Codes column, highlighting, clamping |
+| `app/(shell)/changelog/page.tsx` | page | Major: tab UI, search, entity filters |
+| `app/(shell)/power-plants/page.tsx` | page | New columns: county, year, generators |
+| `app/(shell)/ev-charging/page.tsx` | page | Style: padding, stacking, hyphenation |
+| `app/(shell)/pricing-nodes/page.tsx` | page | Style: padding, sort labels |
+| `app/(shell)/transmission-lines/page.tsx` | page | Style + From/To label rename |
+| `app/(shell)/explore/page.tsx` | page | Metadata |
+| `app/layout.tsx` | page | Explicit favicon icon metadata |
+| `components/TopBar.tsx` | component | Spacing, mobile menu |
+| `components/explorer/ExplorerMap.tsx` | component | ResizeObserver lifecycle fix |
+| `components/GlobalSearch.tsx` | component | Result counts, loading text |
+| `components/SearchInput.tsx` | component | Responsive height + hidden count |
+| `components/DataSourceLink.tsx` | component | Truncation |
+| `app/globals.css` | style | `hyphens-auto` utility class |
+| `.github/PULL_REQUEST_TEMPLATE.md` | docs | PR description standard v1.0 |
+
+---
+
+## Changelog
+
+### Added
+- Sort-direction ▲/▼ indicators in all table sort dropdowns
+- Grid-operators: consolidated Codes column with linked EIA/BA/NERC badges
+- Power-plants: County, Operating Year, Generator Count columns
+- Transmission-lines: From/To substation labels
+- Changelog: Data Changes / Site Updates tab bar with entity-type filter chips + text search
+- Jurisdiction highlighting when filter is active
+- CSS `hyphens-auto` utility class
+- Explore page: title and description metadata
+- CMD+K search: entity count badges and loading state
+- Explicit favicon metadata in app layout
+- PR description template (`.github/PULL_REQUEST_TEMPLATE.md`)
+
+### Changed
+- Header: h-14 → h-12, tighter nav padding
+- Badge variants remapped for segment semantics
+- Grid-operators name column: line-clamp-2 on mobile
+- EIA ID / BA Code / NERC separate columns → single Codes column with source links
+- Mobile menu: active brand color, hover backgrounds
+
+### Fixed
+- Native `<select>` chevron crowding text — asymmetric padding across 9 files
+- Mapbox blank-on-layout-switch — ResizeObserver replaces fragile setTimeout
+- Map layout mode switch stale renders — key={layout} forces clean remount
+- Service territory zoom too wide — finer-grained thresholds
+- Filter dropdowns overflowing on narrow viewports — flex-col stacking
+
+### Reverted
+- Logo redesign (G-in-C with dendritic graph) — reverted to original grid-dots mark
+
+---
+
+## Screenshots / Recordings
+
+_Generated by Diffwatch (`npm run vr:capture`). Comparison images uploaded from `.visual-regression/captures/comparisons/`._
+
+### Grid Operators — Consolidated Codes Column (desktop)
+<!-- ![grid-operators-new-columns-desktop](URL) -->
+_Codes column with stacked EIA/BA/NERC linked badges replacing three sparse columns._
+
+### Dropdown Chevron Padding (mobile + desktop)
+<!-- ![dropdown-chevron-padding-desktop](URL) -->
+<!-- ![dropdown-chevron-padding-mobile](URL) -->
+_Inner right-side padding on native `<select>` elements across all data pages._
+
+### Header Spacing (desktop)
+<!-- ![header-spacing-desktop](URL) -->
+_h-14 → h-12, tighter nav link padding, adjusted logo-to-nav gap._
+
+### Badge Variants (desktop)
+<!-- ![badge-variants-desktop](URL) -->
+_Corrected badge color mapping for all utility segment types._
+
+### Sort Chevrons (desktop)
+<!-- ![sort-chevrons-desktop](URL) -->
+_Sort direction ▲/▼ indicators in dropdown labels on power-plants._
+
+### Changelog Tabs (tablet + desktop)
+<!-- ![changelog-tabs-desktop](URL) -->
+<!-- ![changelog-tabs-tablet](URL) -->
+_Data Changes / Site Updates tab distinction with entity-type filter chips._
+
+### Filter Stacking (mobile)
+<!-- ![filter-stacking-mobile](URL) -->
+_Filter dropdowns stack full-width vertically on narrow viewports._
+
+### Name Clamping (mobile)
+<!-- ![name-clamping-mobile](URL) -->
+_2-line name clamp on grid-operators cards at 375px._
+
+### Mobile Menu (mobile)
+<!-- ![mobile-menu-mobile](URL) -->
+_Mobile menu with active brand color state and hover backgrounds._
+
+---
+
+## Reviewer Checklist
+
+- [ ] Changeset overview matches `git diff --stat main...hello-pr`
+- [ ] Risk assessment reviewed — no items elevated to "high"
+- [ ] No secrets, credentials, or `.env` values committed
+- [ ] Responsive behavior verified at 320px, 768px, 1440px
+- [ ] Codes column badges link to correct external sources (EIA, NERC)
+- [ ] Screenshots above reviewed for visual correctness
+- [ ] Badge color changes reviewed against segment semantics
+
+## Test Plan
+
+### Automated
+- [ ] `next build` completes without errors
+- [ ] `npx biome check` passes
+
+### Visual Regression — Diffwatch
+- [ ] `npm run vr:capture` completes — all 12 captures across mobile/tablet/desktop
+- [ ] No `🔴 alert indicator` warnings in pipeline output
+- [ ] All comparison images reviewed (see Screenshots section above)
+
+### Manual — Functional
+- [ ] CMD+K opens search → section headers show entity counts → "Loading more..." during Tier-2 fetch
+- [ ] Grid-operators: Codes column shows stacked EIA/BA/NERC badges linking to respective sources
+- [ ] Grid-operators: filter by jurisdiction → matching cells highlighted with brand color + bold
+- [ ] Changelog: switch Data Changes ↔ Site Updates tabs → entity-type filter chips narrow results → search bar filters
+- [ ] Explorer map: switch hybrid → list → map → hybrid without blank/flash
+- [ ] Service territory detail: map zooms to tight bounds, not US-wide
+- [ ] All 5 data pages: sort dropdown labels show ▲/▼ direction indicators
+- [ ] All data pages: native `<select>` chevrons have inner right padding
+
+## Deferred Work
+
+- [ ] **Column hover panels with field enumeration / pie charts** — requires `@floating-ui` popover work
+- [ ] **@tanstack/react-table migration** — new dependency; deserves its own PR
+- [ ] **Explorer dual-panel layout** — requires `LayoutMode` type extension
+- [ ] **Power plant custom fuel-type SVG icons** — needs design review
+- [ ] **Streaming changelog with auto-refresh** — needs polling strategy decision
+
+---
+
+```release-note
+Consolidated EIA ID, BA Code, and NERC into a single linked Codes column on
+grid-operators. Added County, Year, and Generator Count to power-plants.
+Introduced Data Changes / Site Updates tabs and search on changelog. Sort
+dropdowns now show ▲/▼ direction. Fixed Mapbox blank-on-layout-switch,
+dropdown chevron padding, and badge color mapping. Improved responsive design
+at narrow viewports across all data pages.
+```
diff --git a/package.json b/package.json
index c54dfffe..482687ad 100644
--- a/package.json
+++ b/package.json
@@ -15,7 +15,9 @@
     "generate:changelog": "npx tsx scripts/generate-changelog.ts",
     "sync:all": "npx tsx scripts/sync-all.ts",
     "vr:capture": "npx tsx scripts/visual-regression/capture-vr.ts",
-    "vr:capture:pr-only": "npx tsx scripts/visual-regression/capture-vr.ts --skip-base"
+    "vr:capture:pr-only": "npx tsx scripts/visual-regression/capture-vr.ts --skip-base",
+    "vr:clean": "npx tsx scripts/visual-regression/clean.ts",
+    "vr:clean:all": "npx tsx scripts/visual-regression/clean.ts --all"
   },
   "dependencies": {
     "@floating-ui/dom": "^1.7.5",
diff --git a/scripts/visual-regression/capture-vr.ts b/scripts/visual-regression/capture-vr.ts
index c3ca46dc..9b585965 100644
--- a/scripts/visual-regression/capture-vr.ts
+++ b/scripts/visual-regression/capture-vr.ts
@@ -22,6 +22,7 @@ import { captureAll, type ManifestCapture, type ManifestViewport } from "./playw
 import { annotateImage, type AnnotationColor, type AnnotationRegion } from "./annotate";
 import { composeComparison } from "./compose";
 import { computeDiff } from "./diff";
+import { scanForAlerts, type AlertRegion } from "./detect-alerts";
 
 // ── Config ──────────────────────────────────────────────────────────────────
 
@@ -48,6 +49,7 @@ interface CatalogEntry {
 		after: string;
 		comparison: string;
 		diffPercent: number;
+		alerts?: { before: AlertRegion[]; after: AlertRegion[] };
 	}>;
 }
 
@@ -352,6 +354,24 @@ async function main() {
 				console.log(`  📊 ${stem}: ${diffPercent}% pixel diff`);
 			}
 
+			// Alert scan — detect red pill-shaped indicators in raw screenshots
+			let alertsBefore: AlertRegion[] = [];
+			let alertsAfter: AlertRegion[] = [];
+			if (fs.existsSync(beforeRaw)) {
+				const scan = scanForAlerts(beforeRaw);
+				alertsBefore = scan.regions;
+				if (scan.hasAlerts) {
+					console.log(`  🔴 ${stem} BEFORE: ${scan.regions.length} alert region(s) detected [${scan.regions.map((r) => r.corner).join(", ")}]`);
+				}
+			}
+			if (fs.existsSync(afterRaw)) {
+				const scan = scanForAlerts(afterRaw);
+				alertsAfter = scan.regions;
+				if (scan.hasAlerts) {
+					console.log(`  🔴 ${stem} AFTER: ${scan.regions.length} alert region(s) detected [${scan.regions.map((r) => r.corner).join(", ")}]`);
+				}
+			}
+
 			// Compose
 			if (!opts.skipCompose && fs.existsSync(beforeAnnotated) && fs.existsSync(afterAnnotated)) {
 				const title = `${capture.description} · ${vp.name} (${vp.width}px)`;
@@ -364,6 +384,9 @@ async function main() {
 				after: path.relative(outDir, afterAnnotated),
 				comparison: path.relative(outDir, comparisonPath),
 				diffPercent,
+				alerts: (alertsBefore.length > 0 || alertsAfter.length > 0)
+					? { before: alertsBefore, after: alertsAfter }
+					: undefined,
 			};
 		}
 
@@ -414,6 +437,35 @@ async function main() {
 	}
 	mdLines.push("", "</details>");
 
+	// Alert summary in report
+	const allAlerts = catalog.flatMap((c) =>
+		Object.entries(c.viewports)
+			.filter(([, d]) => d.alerts)
+			.map(([vpName, d]) => ({ id: c.id, vpName, alerts: d.alerts! })),
+	);
+
+	if (allAlerts.length > 0) {
+		mdLines.push(
+			"",
+			"---",
+			"",
+			"### ⚠️ Alert Indicators Detected",
+			"",
+			"The following captures contain red pill/badge-shaped elements that may indicate runtime errors or notifications:",
+			"",
+			"| Capture | Viewport | State | Regions | Location(s) |",
+			"|---------|----------|-------|---------|-------------|",
+		);
+		for (const { id, vpName, alerts } of allAlerts) {
+			if (alerts.before.length > 0) {
+				mdLines.push(`| ${id} | ${vpName} | BEFORE | ${alerts.before.length} | ${alerts.before.map((r) => r.corner).join(", ")} |`);
+			}
+			if (alerts.after.length > 0) {
+				mdLines.push(`| ${id} | ${vpName} | AFTER | ${alerts.after.length} | ${alerts.after.map((r) => r.corner).join(", ")} |`);
+			}
+		}
+	}
+
 	const mdPath = path.join(outDir, "pr-screenshots.md");
 	fs.writeFileSync(mdPath, mdLines.join("\n"));
 
@@ -426,6 +478,10 @@ async function main() {
 	const totalDiffs = catalog.flatMap((c) => Object.values(c.viewports));
 	const changed = totalDiffs.filter((d) => d.diffPercent > 0);
 	console.log(`\n   ${totalDiffs.length} captures, ${changed.length} with visual changes`);
+
+	if (allAlerts.length > 0) {
+		console.log(`\n   🔴 ${allAlerts.length} capture(s) have alert indicators — inspect these screenshots!`);
+	}
 }
 
 main().catch((err) => {
diff --git a/scripts/visual-regression/clean.ts b/scripts/visual-regression/clean.ts
new file mode 100644
index 00000000..ef82d9a5
--- /dev/null
+++ b/scripts/visual-regression/clean.ts
@@ -0,0 +1,181 @@
+#!/usr/bin/env npx tsx
+/**
+ * clean.ts — Safely clear VR output while preserving a reconstruction receipt.
+ *
+ * Before deleting captures, writes a one-line entry to .visual-regression/run-log.jsonl
+ * with the metadata needed to reproduce the run. The run-log is append-only and
+ * survives cleans — it's the local ledger. The PR itself (GitHub) is the source
+ * of truth for the actual images and attestations.
+ *
+ * Usage:
+ *   npx tsx scripts/visual-regression/clean.ts          # archive + delete captures
+ *   npx tsx scripts/visual-regression/clean.ts --all     # also delete the run-log
+ *   npx tsx scripts/visual-regression/clean.ts --dry-run # show what would be deleted
+ */
+
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+interface RunLogEntry {
+	clearedAt: string;
+	status: "complete" | "incomplete";
+	generatedAt: string;
+	branch: string;
+	headSha: string;
+	baseRef: string;
+	captures: Array<{
+		id: string;
+		commit?: string;
+		viewports: Record<string, { diffPercent: number }>;
+	}>;
+	partialArtifacts?: string[];
+	reconstruct: string;
+}
+
+function main() {
+	const args = process.argv.slice(2);
+	const dryRun = args.includes("--dry-run");
+	const deleteAll = args.includes("--all");
+
+	const repoRoot = execSync("git rev-parse --show-toplevel").toString().trim();
+	const outDir = path.join(repoRoot, ".visual-regression");
+	const catalogPath = path.join(outDir, "catalog.json");
+	const logPath = path.join(outDir, "run-log.jsonl");
+
+	if (!fs.existsSync(outDir)) {
+		console.log("Nothing to clean — .visual-regression/ does not exist.");
+		return;
+	}
+
+	// ── Archive to run-log ───────────────────────────────────────────────
+
+	const capturesDir = path.join(outDir, "captures");
+	const hasCatalog = fs.existsSync(catalogPath);
+	const hasCaptures = fs.existsSync(capturesDir);
+
+	if ((hasCatalog || hasCaptures) && !deleteAll) {
+		let branch = "unknown";
+		let headSha = "unknown";
+		try {
+			branch = execSync("git rev-parse --abbrev-ref HEAD").toString().trim();
+			headSha = execSync("git rev-parse --short HEAD").toString().trim();
+		} catch { /* ok */ }
+
+		let entry: RunLogEntry;
+
+		if (hasCatalog) {
+			// Complete run — catalog exists with full results
+			const catalog = JSON.parse(fs.readFileSync(catalogPath, "utf-8"));
+			entry = {
+				clearedAt: new Date().toISOString(),
+				status: "complete",
+				generatedAt: catalog.generatedAt ?? "unknown",
+				branch,
+				headSha,
+				baseRef: catalog.baseRef ?? "main",
+				captures: (catalog.comparisons ?? []).map((c: any) => ({
+					id: c.id,
+					commit: c.commit,
+					viewports: Object.fromEntries(
+						Object.entries(c.viewports ?? {}).map(([vp, data]: [string, any]) => [
+							vp,
+							{ diffPercent: data.diffPercent },
+						]),
+					),
+				})),
+				reconstruct: `npm run vr:capture -- --base-ref ${catalog.baseRef ?? "main"}`,
+			};
+		} else {
+			// Incomplete run — captures exist but pipeline didn't finish
+			const partialArtifacts: string[] = [];
+			if (hasCaptures) {
+				for (const sub of ["before", "after", "annotated", "comparisons", "diffs"]) {
+					const subDir = path.join(capturesDir, sub);
+					if (fs.existsSync(subDir)) {
+						const count = fs.readdirSync(subDir).filter((f) => f.endsWith(".png")).length;
+						if (count > 0) partialArtifacts.push(`${sub}: ${count} files`);
+					}
+				}
+			}
+			entry = {
+				clearedAt: new Date().toISOString(),
+				status: "incomplete",
+				generatedAt: "unknown",
+				branch,
+				headSha,
+				baseRef: "main",
+				captures: [],
+				partialArtifacts,
+				reconstruct: "npm run vr:capture -- --base-ref main",
+			};
+		}
+
+		if (dryRun) {
+			console.log("Would append to run-log.jsonl:");
+			console.log(JSON.stringify(entry, null, 2));
+		} else {
+			fs.mkdirSync(outDir, { recursive: true });
+			fs.appendFileSync(logPath, JSON.stringify(entry) + "\n");
+			const statusLabel = entry.status === "complete" ? "📋" : "⚠️";
+			console.log(`${statusLabel} Archived ${entry.status} run metadata to run-log.jsonl`);
+			console.log(`   Branch: ${entry.branch} (${entry.headSha})`);
+			if (entry.status === "complete") {
+				console.log(`   Generated: ${entry.generatedAt}`);
+				console.log(`   Captures: ${entry.captures.length}`);
+			} else {
+				console.log(`   Status: incomplete (pipeline did not finish)`);
+				if (entry.partialArtifacts?.length) {
+					console.log(`   Partial: ${entry.partialArtifacts.join(", ")}`);
+				}
+			}
+		}
+	}
+
+	// ── Delete output ────────────────────────────────────────────────────
+
+	const toDelete: string[] = [];
+
+	// Always delete captures/, catalog.json, pr-screenshots.md
+	if (fs.existsSync(capturesDir)) toDelete.push(capturesDir);
+	if (fs.existsSync(catalogPath)) toDelete.push(catalogPath);
+	const mdPath = path.join(outDir, "pr-screenshots.md");
+	if (fs.existsSync(mdPath)) toDelete.push(mdPath);
+
+	if (deleteAll && fs.existsSync(logPath)) {
+		toDelete.push(logPath);
+	}
+
+	if (toDelete.length === 0) {
+		console.log("Nothing to delete.");
+		return;
+	}
+
+	if (dryRun) {
+		console.log("\nWould delete:");
+		for (const p of toDelete) console.log(`  ${path.relative(repoRoot, p)}`);
+		return;
+	}
+
+	for (const p of toDelete) {
+		fs.rmSync(p, { recursive: true, force: true });
+	}
+
+	// Calculate what was freed
+	console.log(`\n🧹 Cleaned:`);
+	for (const p of toDelete) {
+		console.log(`   ✓ ${path.relative(repoRoot, p)}`);
+	}
+
+	// Show what remains
+	if (fs.existsSync(outDir)) {
+		const remaining = fs.readdirSync(outDir);
+		if (remaining.length > 0) {
+			console.log(`\n   Preserved: ${remaining.join(", ")}`);
+		}
+	}
+
+	console.log(`\n   Reconstruct with: npm run vr:capture`);
+}
+
+main();
diff --git a/scripts/visual-regression/detect-alerts.ts b/scripts/visual-regression/detect-alerts.ts
new file mode 100644
index 00000000..61a397c4
--- /dev/null
+++ b/scripts/visual-regression/detect-alerts.ts
@@ -0,0 +1,195 @@
+/**
+ * detect-alerts.ts — Scan screenshot edges for red pill-shaped alert indicators.
+ *
+ * Detects clusters of "alert-red" pixels in the edge margins of screenshots —
+ * the kind of floating overlays that dev tools, error indicators, and notification
+ * badges render on top of the page (e.g. Next.js "1 Issue" pill, error toasts).
+ *
+ * Only scans the outer margin (default: 15% from each edge), ignoring the main
+ * content area where red badges, dots, and UI elements are expected.
+ *
+ * Returns bounding boxes and pixel counts for each detected cluster,
+ * so the pipeline can flag screenshots that need human inspection.
+ */
+
+import fs from "node:fs";
+import { PNG } from "pngjs";
+
+export interface AlertRegion {
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+	pixelCount: number;
+	corner: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+}
+
+export interface AlertScanResult {
+	hasAlerts: boolean;
+	regions: AlertRegion[];
+	totalAlertPixels: number;
+	imagePath: string;
+}
+
+/**
+ * Returns true if a pixel is "alert red":
+ *   R >= 180, G <= 80, B <= 80, A >= 200
+ *
+ * Catches: #EF4444, #DC2626, #B91C1C, #FF0000, and similar saturated reds.
+ */
+function isAlertRed(r: number, g: number, b: number, a: number): boolean {
+	return r >= 180 && g <= 80 && b <= 80 && a >= 200;
+}
+
+/**
+ * Returns true if a pixel coordinate falls within the edge margin zone.
+ * The margin is the outer strip of the image — corners where floating
+ * overlays and dev indicators typically render.
+ */
+function isInEdgeMargin(
+	x: number,
+	y: number,
+	imgW: number,
+	imgH: number,
+	marginFraction: number,
+): boolean {
+	const mx = imgW * marginFraction;
+	const my = imgH * marginFraction;
+	const inHorizontalMargin = x < mx || x >= imgW - mx;
+	const inVerticalMargin = y < my || y >= imgH - my;
+	// Must be in a corner zone (both horizontal and vertical edge)
+	return inHorizontalMargin && inVerticalMargin;
+}
+
+/**
+ * Classify which corner a bounding box center falls in.
+ */
+function classifyCorner(
+	cx: number,
+	cy: number,
+	imgW: number,
+	imgH: number,
+): AlertRegion["corner"] {
+	const midX = imgW / 2;
+	const midY = imgH / 2;
+	if (cx < midX && cy < midY) return "top-left";
+	if (cx >= midX && cy < midY) return "top-right";
+	if (cx < midX && cy >= midY) return "bottom-left";
+	return "bottom-right";
+}
+
+/**
+ * Flood-fill to find connected red pixel clusters.
+ */
+function floodFill(
+	visited: Uint8Array,
+	redMask: Uint8Array,
+	startIdx: number,
+	width: number,
+	height: number,
+): { pixels: number[]; count: number } {
+	const queue = [startIdx];
+	const pixels: number[] = [];
+	visited[startIdx] = 1;
+
+	while (queue.length > 0) {
+		const idx = queue.pop()!;
+		pixels.push(idx);
+
+		const x = idx % width;
+		const y = Math.floor(idx / width);
+
+		const neighbors = [
+			y > 0 ? idx - width : -1,
+			y < height - 1 ? idx + width : -1,
+			x > 0 ? idx - 1 : -1,
+			x < width - 1 ? idx + 1 : -1,
+		];
+
+		for (const n of neighbors) {
+			if (n >= 0 && !visited[n] && redMask[n]) {
+				visited[n] = 1;
+				queue.push(n);
+			}
+		}
+	}
+
+	return { pixels, count: pixels.length };
+}
+
+/**
+ * Scan a PNG image for clusters of alert-red pixels in the edge margins.
+ *
+ * @param imagePath       Path to the PNG file
+ * @param minClusterSize  Minimum pixel count for a cluster to be reported (default: 50)
+ * @param marginFraction  Fraction of image width/height to treat as edge zone (default: 0.15)
+ * @returns AlertScanResult with detected regions
+ */
+export function scanForAlerts(
+	imagePath: string,
+	minClusterSize = 50,
+	marginFraction = 0.15,
+): AlertScanResult {
+	const img = PNG.sync.read(fs.readFileSync(imagePath));
+	const { width, height, data } = img;
+	const totalPx = width * height;
+
+	// Build a binary mask of alert-red pixels ONLY in edge margin corners
+	const redMask = new Uint8Array(totalPx);
+	for (let i = 0; i < totalPx; i++) {
+		const x = i % width;
+		const y = Math.floor(i / width);
+		if (!isInEdgeMargin(x, y, width, height, marginFraction)) continue;
+
+		const off = i * 4;
+		if (isAlertRed(data[off], data[off + 1], data[off + 2], data[off + 3])) {
+			redMask[i] = 1;
+		}
+	}
+
+	// Find connected clusters via flood fill
+	const visited = new Uint8Array(totalPx);
+	const regions: AlertRegion[] = [];
+	let totalAlertPixels = 0;
+
+	for (let i = 0; i < totalPx; i++) {
+		if (redMask[i] && !visited[i]) {
+			const cluster = floodFill(visited, redMask, i, width, height);
+
+			if (cluster.count >= minClusterSize) {
+				let minX = width, maxX = 0, minY = height, maxY = 0;
+				for (const px of cluster.pixels) {
+					const x = px % width;
+					const y = Math.floor(px / width);
+					if (x < minX) minX = x;
+					if (x > maxX) maxX = x;
+					if (y < minY) minY = y;
+					if (y > maxY) maxY = y;
+				}
+
+				const regionW = maxX - minX + 1;
+				const regionH = maxY - minY + 1;
+				const cx = minX + regionW / 2;
+				const cy = minY + regionH / 2;
+
+				regions.push({
+					x: minX,
+					y: minY,
+					width: regionW,
+					height: regionH,
+					pixelCount: cluster.count,
+					corner: classifyCorner(cx, cy, width, height),
+				});
+
+				totalAlertPixels += cluster.count;
+			}
+		}
+	}
+
+	return {
+		hasAlerts: regions.length > 0,
+		regions,
+		totalAlertPixels,
+		imagePath,
+	};
+}

From f2f8df4bf7b4f0ff1a9ca9260c9f987836606f69 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Tue, 17 Mar 2026 12:34:38 -0400
Subject: [PATCH 34/41] fix: remove double badge rendering on mobile grid
 operators list
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Change segment column mobile format from "badge" to "secondary" —
the render function already wraps in <Badge>, so "badge" format
caused the DataTable mobile card to double-wrap it.
---
 app/(shell)/grid-operators/page.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/app/(shell)/grid-operators/page.tsx b/app/(shell)/grid-operators/page.tsx
index 5d3ac196..07e96bb6 100644
--- a/app/(shell)/grid-operators/page.tsx
+++ b/app/(shell)/grid-operators/page.tsx
@@ -184,7 +184,7 @@ function GridOperatorsPageInner() {
             {getSegmentLabel(row.segment)}
           </Badge>
         ),
-        mobile: { priority: 2, format: "badge" },
+        mobile: { priority: 2, format: "secondary" },
       },
       {
         id: "customerCount",

From 7a1fccb3fea406e61a637f9151a799e72837532d Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Tue, 17 Mar 2026 12:37:26 -0400
Subject: [PATCH 35/41] fix: render changelog subtitle as visible text below
 header
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PageLayout.Header doesn't render the description prop — move the
subtitle into PageLayout.Content as a <p> so it actually appears.
---
 app/(shell)/changelog/page.tsx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/app/(shell)/changelog/page.tsx b/app/(shell)/changelog/page.tsx
index 734bfae6..61cebc89 100644
--- a/app/(shell)/changelog/page.tsx
+++ b/app/(shell)/changelog/page.tsx
@@ -167,11 +167,11 @@ export default function ChangelogPage() {
 
   return (
     <PageLayout maxWidth={900}>
-      <PageLayout.Header
-        title="Changelog"
-        description="What's changing in the grid data we track — and in the tools we're building to track it."
-      />
+      <PageLayout.Header title="Changelog" />
       <PageLayout.Content>
+        <p className="text-sm text-text-muted -mt-2 mb-6">
+          What's changing in the grid data we track — and in the tools we're building to track it.
+        </p>
         {/* Tab bar */}
         <div className="flex gap-1 border-b border-border-default mb-6">
           <button

From 33bf95f6ecf6f8d54c8984ea0703c1c6b41dacce Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Tue, 17 Mar 2026 12:41:35 -0400
Subject: [PATCH 36/41] feat(diffwatch): add ordinal versioning to comparison
 outputs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Each targeted re-run now appends _00, _01, _02… to comparison,
annotated, and diff filenames. An unversioned "latest" copy is
also maintained at the base stem for easy reference. This gives
local traceability when re-running the pipeline for specific
captures without overwriting previous results.
---
 scripts/visual-regression/capture-vr.ts | 47 ++++++++++++++++++++++---
 1 file changed, 42 insertions(+), 5 deletions(-)

diff --git a/scripts/visual-regression/capture-vr.ts b/scripts/visual-regression/capture-vr.ts
index 9b585965..f8d2d50b 100644
--- a/scripts/visual-regression/capture-vr.ts
+++ b/scripts/visual-regression/capture-vr.ts
@@ -53,6 +53,31 @@ interface CatalogEntry {
 	}>;
 }
 
+// ── Versioning ───────────────────────────────────────────────────────────────
+
+/**
+ * Find the next ordinal version for a file stem in a directory.
+ * Existing: foo_00.png, foo_01.png → returns "foo_02" and 2.
+ * No existing: returns "foo_00" and 0.
+ */
+function nextVersionedStem(dir: string, stem: string, ext: string): { filename: string; ordinal: number } {
+	let ordinal = 0;
+	if (fs.existsSync(dir)) {
+		const existing = fs.readdirSync(dir).filter(
+			(f) => f.startsWith(`${stem}_`) && f.endsWith(ext),
+		);
+		for (const f of existing) {
+			const match = f.match(new RegExp(`^${stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}_(\\d+)${ext.replace(".", "\\.")}$`));
+			if (match) {
+				const n = parseInt(match[1], 10);
+				if (n >= ordinal) ordinal = n + 1;
+			}
+		}
+	}
+	const pad = String(ordinal).padStart(2, "0");
+	return { filename: `${stem}_${pad}${ext}`, ordinal };
+}
+
 // ── Args ────────────────────────────────────────────────────────────────────
 
 function parseArgs() {
@@ -308,10 +333,17 @@ async function main() {
 			const beforeRegionsPath = path.join(dirs.before, `${stem}.regions.json`);
 			const afterRegionsPath = path.join(dirs.after, `${stem}.regions.json`);
 
-			const beforeAnnotated = path.join(dirs.annotated, `${stem}-before.png`);
-			const afterAnnotated = path.join(dirs.annotated, `${stem}-after.png`);
-			const comparisonPath = path.join(dirs.comparisons, `${stem}.png`);
-			const diffPath = path.join(dirs.diffs, `${stem}-diff.png`);
+			// Versioned outputs — each run gets an ordinal (_00, _01, _02…)
+			const { filename: compFilename, ordinal } = nextVersionedStem(dirs.comparisons, stem, ".png");
+			const versionSuffix = `_${String(ordinal).padStart(2, "0")}`;
+			const beforeAnnotated = path.join(dirs.annotated, `${stem}-before${versionSuffix}.png`);
+			const afterAnnotated = path.join(dirs.annotated, `${stem}-after${versionSuffix}.png`);
+			const comparisonPath = path.join(dirs.comparisons, compFilename);
+			const diffPath = path.join(dirs.diffs, `${stem}-diff${versionSuffix}.png`);
+
+			if (ordinal > 0) {
+				console.log(`  🔄 ${stem}: version ${versionSuffix} (${ordinal} prior run${ordinal > 1 ? "s" : ""})`);
+			}
 
 			// Load region data
 			let beforeRegions: AnnotationRegion[] = [];
@@ -376,7 +408,12 @@ async function main() {
 			if (!opts.skipCompose && fs.existsSync(beforeAnnotated) && fs.existsSync(afterAnnotated)) {
 				const title = `${capture.description} · ${vp.name} (${vp.width}px)`;
 				await composeComparison(beforeAnnotated, afterAnnotated, title, comparisonPath);
-				console.log(`  ✓ ${stem} composed`);
+				// Also write/overwrite the unversioned "latest" copy for easy reference
+				const latestPath = path.join(dirs.comparisons, `${stem}.png`);
+				if (latestPath !== comparisonPath) {
+					fs.copyFileSync(comparisonPath, latestPath);
+				}
+				console.log(`  ✓ ${stem} composed → ${path.basename(comparisonPath)}`);
 			}
 
 			entry.viewports[vp.name] = {

From aec3b14eb999582d007a498ac2c68a7edfda128e Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Tue, 17 Mar 2026 13:09:12 -0400
Subject: [PATCH 37/41] feat(changelog): redesign header with pill toggle,
 filter fieldset, and condensed layout

- Replace tab bar with pill toggle (Grid Data / Site) in upper right
- Merge description + sync status into single line with green pulse dot
- Wrap entity type filter + search in a labeled fieldset
- Use subtle blue tints for filter track and search background
- Fix ISO capitalization in filter chips
- Condense spacing throughout the page
---
 app/(shell)/changelog/page.tsx | 160 +++++++++++++++++----------------
 1 file changed, 83 insertions(+), 77 deletions(-)

diff --git a/app/(shell)/changelog/page.tsx b/app/(shell)/changelog/page.tsx
index 61cebc89..89adcd69 100644
--- a/app/(shell)/changelog/page.tsx
+++ b/app/(shell)/changelog/page.tsx
@@ -100,8 +100,8 @@ function EntryRow({ entry }: { entry: ChangelogEntry }) {
 
 function DateGroup({ date, entries }: { date: string; entries: ChangelogEntry[] }) {
   return (
-    <div className="mb-8">
-      <div className="flex items-center gap-3 mb-3">
+    <div className="mb-5">
+      <div className="flex items-center gap-3 mb-2">
         <div className="text-xs font-semibold uppercase tracking-widest text-text-muted">{date}</div>
         <div className="flex-1 h-px bg-border-default" />
         <div className="text-xs text-text-muted">{entries.length} change{entries.length !== 1 ? "s" : ""}</div>
@@ -166,36 +166,54 @@ export default function ChangelogPage() {
     : null;
 
   return (
-    <PageLayout maxWidth={900}>
-      <PageLayout.Header title="Changelog" />
+    <PageLayout maxWidth={900} paddingYClass="pt-2 md:pt-3">
       <PageLayout.Content>
-        <p className="text-sm text-text-muted -mt-2 mb-6">
-          What's changing in the grid data we track — and in the tools we're building to track it.
-        </p>
-        {/* Tab bar */}
-        <div className="flex gap-1 border-b border-border-default mb-6">
-          <button
-            type="button"
-            onClick={() => setTab("data")}
-            className={`px-4 py-2.5 text-sm font-medium border-b-2 transition-colors ${
-              tab === "data"
-                ? "border-brand-primary text-brand-primary"
-                : "border-transparent text-text-muted hover:text-text-body"
-            }`}
-          >
-            Data Changes
-          </button>
-          <button
-            type="button"
-            onClick={() => setTab("site")}
-            className={`px-4 py-2.5 text-sm font-medium border-b-2 transition-colors ${
-              tab === "site"
-                ? "border-brand-primary text-brand-primary"
-                : "border-transparent text-text-muted hover:text-text-body"
-            }`}
-          >
-            Site Updates
-          </button>
+        {/* Pill toggle — upper right */}
+        <div className="flex justify-end mt-1 md:mt-2 mb-1">
+          <div className="flex-none flex items-center rounded-full bg-neutral-200/70 dark:bg-neutral-700/60 p-0.5 shadow-[inset_0_1px_3px_rgba(0,0,0,0.12)]">
+            <button
+              type="button"
+              onClick={() => setTab("data")}
+              className={`px-3 py-1 rounded-full text-xs font-medium transition-all ${
+                tab === "data"
+                  ? "bg-white dark:bg-neutral-600 text-text-heading shadow-sm"
+                  : "text-text-muted hover:text-text-body"
+              }`}
+            >
+              Grid Data
+            </button>
+            <button
+              type="button"
+              onClick={() => setTab("site")}
+              className={`px-3 py-1 rounded-full text-xs font-medium transition-all ${
+                tab === "site"
+                  ? "bg-white dark:bg-neutral-600 text-text-heading shadow-sm"
+                  : "text-text-muted hover:text-text-body"
+              }`}
+            >
+              Site
+            </button>
+          </div>
+        </div>
+
+        {/* Title + description */}
+        <h1 className="text-3xl font-bold text-text-heading leading-none mb-1.5">Changelog</h1>
+        <div className="flex items-center justify-between mb-5">
+          <div className="flex items-center gap-2">
+            {tab === "data" && (
+              <span className="inline-block w-1.5 h-1.5 rounded-full bg-green-500 animate-[pulse_4s_ease-in-out_infinite]" />
+            )}
+            <span className="text-sm text-text-muted">
+              {tab === "data"
+                ? "Live changes synced routinely from authoritative energy industry sources."
+                : "Product updates to the CommonGrid website and tools."}
+            </span>
+          </div>
+          {tab === "data" && lastUpdated && (
+            <span className="text-xs text-text-muted whitespace-nowrap">
+              Last updated {lastUpdated}
+            </span>
+          )}
         </div>
 
         {tab === "site" && (
@@ -221,35 +239,8 @@ export default function ChangelogPage() {
 
         {tab === "data" && (
         <Section id="feed" navLabel="Changes" withDivider={false}>
-          {/* Search */}
-          <div className="relative mb-4">
-            <Icon name="MagnifyingGlass" size={16} className="absolute left-3 top-1/2 -translate-y-1/2 text-text-muted" />
-            <input
-              type="text"
-              value={searchQuery}
-              onChange={(e) => setSearchQuery(e.target.value)}
-              placeholder="Search changes..."
-              className="w-full h-9 pl-9 pr-3 rounded-lg border border-border-default bg-background-surface text-sm text-text-body placeholder:text-text-muted outline-none focus:border-brand-primary transition-colors"
-            />
-          </div>
-
-          {/* Meta bar */}
-          <div className="flex items-center justify-between mb-6">
-            <div className="flex items-center gap-2">
-              <span className="inline-block w-2 h-2 rounded-full bg-green-500 animate-pulse" />
-              <span className="text-sm text-text-muted">
-                Synced from authoritative sources daily
-              </span>
-            </div>
-            {lastUpdated && (
-              <span className="text-xs text-text-muted">
-                Last updated {lastUpdated}
-              </span>
-            )}
-          </div>
-
           {/* Stats */}
-          <div className="grid grid-cols-2 sm:grid-cols-3 gap-3 mb-8">
+          <div className="grid grid-cols-2 sm:grid-cols-3 gap-2 mb-4">
             {[
               {
                 label: "Recently updated",
@@ -287,25 +278,40 @@ export default function ChangelogPage() {
             ))}
           </div>
 
-          {/* Entity type filters */}
-          {uniqueEntityTypes.length > 1 && (
-            <div className="flex flex-wrap gap-2 mb-6">
-              {["all", ...uniqueEntityTypes].map((type) => (
-                <button
-                  key={type}
-                  type="button"
-                  onClick={() => setEntityTypeFilter(type)}
-                  className={`px-3 py-1 rounded-full text-xs font-medium transition-colors ${
-                    entityTypeFilter === type
-                      ? "bg-brand-primary text-white"
-                      : "bg-background-subtle text-text-muted hover:text-text-body"
-                  }`}
-                >
-                  {type === "all" ? "All" : type.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase())}
-                </button>
-              ))}
+          {/* Filter fieldset */}
+          <fieldset className="relative border border-border-default rounded-lg px-2.5 pt-1 pb-2 mb-3">
+            <legend className="text-[9px] uppercase tracking-widest text-text-muted px-1 font-medium leading-none">Filter</legend>
+            <div className="flex items-center gap-2.5">
+              {uniqueEntityTypes.length > 1 && (
+                <div className="flex items-center rounded-lg bg-blue-50/80 dark:bg-blue-900/20 p-0.5 shadow-[inset_0_0.5px_2px_rgba(0,0,0,0.06)]">
+                  {["all", ...uniqueEntityTypes].map((type) => (
+                    <button
+                      key={type}
+                      type="button"
+                      onClick={() => setEntityTypeFilter(type)}
+                      className={`px-2.5 py-0.5 rounded-md text-[11px] font-medium transition-all whitespace-nowrap ${
+                        entityTypeFilter === type
+                          ? "bg-brand-primary text-white shadow-sm"
+                          : "text-text-muted hover:text-text-body"
+                      }`}
+                    >
+                      {type === "all" ? "All" : type.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()).replace(/\bIso\b/g, "ISO")}
+                    </button>
+                  ))}
+                </div>
+              )}
+              <div className="relative flex-1">
+                <Icon name="MagnifyingGlass" size={14} className="absolute left-2.5 top-1/2 -translate-y-1/2 text-text-muted" />
+                <input
+                  type="text"
+                  value={searchQuery}
+                  onChange={(e) => setSearchQuery(e.target.value)}
+                  placeholder="Search..."
+                  className="w-full h-7 pl-8 pr-3 rounded-lg border border-blue-100 dark:border-blue-800/30 bg-blue-50/30 dark:bg-blue-900/10 text-xs text-text-body placeholder:text-text-muted outline-none focus:border-brand-primary transition-colors"
+                />
+              </div>
             </div>
-          )}
+          </fieldset>
 
           {/* Feed */}
           {filteredEntries.length === 0 ? (

From c90cf524914cea850b33177947004ae462c2351b Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Tue, 17 Mar 2026 13:13:29 -0400
Subject: [PATCH 38/41] docs: update PR description for changelog redesign and
 double-badge fix

---
 docs/pr-descriptions/PR_DESCRIPTION_HELLO-PR.md | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/docs/pr-descriptions/PR_DESCRIPTION_HELLO-PR.md b/docs/pr-descriptions/PR_DESCRIPTION_HELLO-PR.md
index c61c942c..5b59d7bb 100644
--- a/docs/pr-descriptions/PR_DESCRIPTION_HELLO-PR.md
+++ b/docs/pr-descriptions/PR_DESCRIPTION_HELLO-PR.md
@@ -189,7 +189,8 @@ quadrantChart
 | `37b1abc` | feat | 5 data pages | Sort-direction ▲/▼ chevrons in dropdown labels | S | low |
 | `791740d` | feat | power-plants, transmission-lines | County, Year, Generators columns; From/To labels | M | low |
 | `ece78d0` | feat | grid-operators | Jurisdiction state-based highlighting on filter | S | low |
-| `ea227b5` | feat | changelog | Data Changes / Site Updates tab distinction | L | med |
+| `ea227b5` | feat | changelog | Data Changes / Site Updates tab distinction | L | low |
+| `aec3b14` | feat | changelog | Pill toggle, filter fieldset, condensed layout | L | low |
 | `c9e343a` | fix | ExplorerMap | ResizeObserver replaces setTimeout for map resize | M | med |
 | `ecdc89b` | feat | TopBar, logo.svg | Logo redesign — G-in-C _(reverted by bf7378b)_ | M | — |
 | `049d059` | style | 5 data pages | Stack filter dropdowns vertically at narrow breakpoints | S | low |
@@ -218,7 +219,7 @@ quadrantChart
 |------|---------|-------------|
 | `grid-operators/page.tsx` | 7 | fix, style, feat (chevron → hyphens → clamp → sort → stack → highlight → codes) |
 | `TopBar.tsx` | 3 | style, feat, revert (spacing → mobile menu → logo revert) |
-| `changelog/page.tsx` | 2 | feat (tabs → search) |
+| `changelog/page.tsx` | 3 | feat (tabs → search → pill toggle + filter fieldset) |
 | `lib/formatting.ts` | 2 | fix (badge variants, mirrored in explorer/) |
 | `ExplorerMap.tsx` | 2 | fix (ResizeObserver → key prop via ExplorerShell) |
 
@@ -227,7 +228,7 @@ quadrantChart
 | File | Layer | Character |
 |------|-------|-----------|
 | `app/(shell)/grid-operators/page.tsx` | page | Major: Codes column, highlighting, clamping |
-| `app/(shell)/changelog/page.tsx` | page | Major: tab UI, search, entity filters |
+| `app/(shell)/changelog/page.tsx` | page | Major: pill toggle, filter fieldset, search, condensed layout |
 | `app/(shell)/power-plants/page.tsx` | page | New columns: county, year, generators |
 | `app/(shell)/ev-charging/page.tsx` | page | Style: padding, stacking, hyphenation |
 | `app/(shell)/pricing-nodes/page.tsx` | page | Style: padding, sort labels |
@@ -251,7 +252,7 @@ quadrantChart
 - Grid-operators: consolidated Codes column with linked EIA/BA/NERC badges
 - Power-plants: County, Operating Year, Generator Count columns
 - Transmission-lines: From/To substation labels
-- Changelog: Data Changes / Site Updates tab bar with entity-type filter chips + text search
+- Changelog: pill toggle (Grid Data / Site) replacing tab bar, filter fieldset with entity-type pills + inline search, combined sync status line with pulse dot
 - Jurisdiction highlighting when filter is active
 - CSS `hyphens-auto` utility class
 - Explore page: title and description metadata
@@ -267,6 +268,7 @@ quadrantChart
 - Mobile menu: active brand color, hover backgrounds
 
 ### Fixed
+- Grid-operators mobile: double badge rendering on segment column (format "badge" → "secondary")
 - Native `<select>` chevron crowding text — asymmetric padding across 9 files
 - Mapbox blank-on-layout-switch — ResizeObserver replaces fragile setTimeout
 - Map layout mode switch stale renders — key={layout} forces clean remount
@@ -303,10 +305,10 @@ _Corrected badge color mapping for all utility segment types._
 <!-- ![sort-chevrons-desktop](URL) -->
 _Sort direction ▲/▼ indicators in dropdown labels on power-plants._
 
-### Changelog Tabs (tablet + desktop)
+### Changelog Redesign (tablet + desktop)
 <!-- ![changelog-tabs-desktop](URL) -->
 <!-- ![changelog-tabs-tablet](URL) -->
-_Data Changes / Site Updates tab distinction with entity-type filter chips._
+_Pill toggle (Grid Data / Site), filter fieldset with entity-type pills + inline search, combined sync status with pulse indicator._
 
 ### Filter Stacking (mobile)
 <!-- ![filter-stacking-mobile](URL) -->
@@ -347,7 +349,7 @@ _Mobile menu with active brand color state and hover backgrounds._
 - [ ] CMD+K opens search → section headers show entity counts → "Loading more..." during Tier-2 fetch
 - [ ] Grid-operators: Codes column shows stacked EIA/BA/NERC badges linking to respective sources
 - [ ] Grid-operators: filter by jurisdiction → matching cells highlighted with brand color + bold
-- [ ] Changelog: switch Data Changes ↔ Site Updates tabs → entity-type filter chips narrow results → search bar filters
+- [ ] Changelog: Grid Data ↔ Site pill toggle switches view + description → filter fieldset narrows results → inline search filters
 - [ ] Explorer map: switch hybrid → list → map → hybrid without blank/flash
 - [ ] Service territory detail: map zooms to tight bounds, not US-wide
 - [ ] All 5 data pages: sort dropdown labels show ▲/▼ direction indicators

From b3a4a1b3a0fc6ab86b330894ed9d0d02d2011e6f Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Tue, 17 Mar 2026 13:18:46 -0400
Subject: [PATCH 39/41] feat(changelog): expand filter fieldset to wrap results
 when filtering active
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When entity type or search filter is applied, the fieldset expands to
contain the entire feed with a blue-tinted border and background. The
legend dynamically shows filter state: "FILTERED BY ISO · 2 RESULTS".
Reverts to compact "FILTER" fieldset when all filters are cleared.
---
 app/(shell)/changelog/page.tsx | 129 ++++++++++++++++++++-------------
 1 file changed, 78 insertions(+), 51 deletions(-)

diff --git a/app/(shell)/changelog/page.tsx b/app/(shell)/changelog/page.tsx
index 89adcd69..52f29879 100644
--- a/app/(shell)/changelog/page.tsx
+++ b/app/(shell)/changelog/page.tsx
@@ -278,60 +278,87 @@ export default function ChangelogPage() {
             ))}
           </div>
 
-          {/* Filter fieldset */}
-          <fieldset className="relative border border-border-default rounded-lg px-2.5 pt-1 pb-2 mb-3">
-            <legend className="text-[9px] uppercase tracking-widest text-text-muted px-1 font-medium leading-none">Filter</legend>
-            <div className="flex items-center gap-2.5">
-              {uniqueEntityTypes.length > 1 && (
-                <div className="flex items-center rounded-lg bg-blue-50/80 dark:bg-blue-900/20 p-0.5 shadow-[inset_0_0.5px_2px_rgba(0,0,0,0.06)]">
-                  {["all", ...uniqueEntityTypes].map((type) => (
-                    <button
-                      key={type}
-                      type="button"
-                      onClick={() => setEntityTypeFilter(type)}
-                      className={`px-2.5 py-0.5 rounded-md text-[11px] font-medium transition-all whitespace-nowrap ${
-                        entityTypeFilter === type
-                          ? "bg-brand-primary text-white shadow-sm"
-                          : "text-text-muted hover:text-text-body"
-                      }`}
-                    >
-                      {type === "all" ? "All" : type.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()).replace(/\bIso\b/g, "ISO")}
-                    </button>
-                  ))}
+          {/* Filter fieldset — expands to wrap results when a filter is active */}
+          {(() => {
+            const isFiltering = entityTypeFilter !== "all" || searchQuery.trim().length > 0;
+
+            const filterControls = (
+              <div className="flex items-center gap-2.5">
+                {uniqueEntityTypes.length > 1 && (
+                  <div className="flex items-center rounded-lg bg-blue-50/80 dark:bg-blue-900/20 p-0.5 shadow-[inset_0_0.5px_2px_rgba(0,0,0,0.06)]">
+                    {["all", ...uniqueEntityTypes].map((type) => (
+                      <button
+                        key={type}
+                        type="button"
+                        onClick={() => setEntityTypeFilter(type)}
+                        className={`px-2.5 py-0.5 rounded-md text-[11px] font-medium transition-all whitespace-nowrap ${
+                          entityTypeFilter === type
+                            ? "bg-brand-primary text-white shadow-sm"
+                            : "text-text-muted hover:text-text-body"
+                        }`}
+                      >
+                        {type === "all" ? "All" : type.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()).replace(/\bIso\b/g, "ISO")}
+                      </button>
+                    ))}
+                  </div>
+                )}
+                <div className="relative flex-1">
+                  <Icon name="MagnifyingGlass" size={14} className="absolute left-2.5 top-1/2 -translate-y-1/2 text-text-muted" />
+                  <input
+                    type="text"
+                    value={searchQuery}
+                    onChange={(e) => setSearchQuery(e.target.value)}
+                    placeholder="Search..."
+                    className="w-full h-7 pl-8 pr-3 rounded-lg border border-blue-100 dark:border-blue-800/30 bg-blue-50/30 dark:bg-blue-900/10 text-xs text-text-body placeholder:text-text-muted outline-none focus:border-brand-primary transition-colors"
+                  />
                 </div>
-              )}
-              <div className="relative flex-1">
-                <Icon name="MagnifyingGlass" size={14} className="absolute left-2.5 top-1/2 -translate-y-1/2 text-text-muted" />
-                <input
-                  type="text"
-                  value={searchQuery}
-                  onChange={(e) => setSearchQuery(e.target.value)}
-                  placeholder="Search..."
-                  className="w-full h-7 pl-8 pr-3 rounded-lg border border-blue-100 dark:border-blue-800/30 bg-blue-50/30 dark:bg-blue-900/10 text-xs text-text-body placeholder:text-text-muted outline-none focus:border-brand-primary transition-colors"
-                />
               </div>
-            </div>
-          </fieldset>
+            );
 
-          {/* Feed */}
-          {filteredEntries.length === 0 ? (
-            <Card variant="outlined">
-              <Card.Content className="py-12 text-center">
-                <Icon name="Clock" size={32} className="text-text-muted mx-auto mb-3" />
-                <p className="text-text-muted text-sm">
-                  No changes recorded yet. Run{" "}
-                  <code className="text-xs bg-background-subtle px-1.5 py-0.5 rounded">
-                    npm run generate:changelog
-                  </code>{" "}
-                  after a sync to populate this feed.
-                </p>
-              </Card.Content>
-            </Card>
-          ) : (
-            groups.map(({ date, entries }) => (
-              <DateGroup key={date} date={date} entries={entries} />
-            ))
-          )}
+            const feed = filteredEntries.length === 0 ? (
+              <Card variant="outlined">
+                <Card.Content className="py-12 text-center">
+                  <Icon name="Clock" size={32} className="text-text-muted mx-auto mb-3" />
+                  <p className="text-text-muted text-sm">
+                    No changes recorded yet. Run{" "}
+                    <code className="text-xs bg-background-subtle px-1.5 py-0.5 rounded">
+                      npm run generate:changelog
+                    </code>{" "}
+                    after a sync to populate this feed.
+                  </p>
+                </Card.Content>
+              </Card>
+            ) : (
+              groups.map(({ date, entries }) => (
+                <DateGroup key={date} date={date} entries={entries} />
+              ))
+            );
+
+            const filterParts: string[] = [];
+            if (entityTypeFilter !== "all") {
+              filterParts.push(entityTypeFilter.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()).replace(/\bIso\b/g, "ISO"));
+            }
+            if (searchQuery.trim()) {
+              filterParts.push(`"${searchQuery.trim()}"`);
+            }
+            const filterLabel = `Filtered by ${filterParts.join(" + ")} · ${filteredEntries.length} result${filteredEntries.length !== 1 ? "s" : ""}`;
+
+            return isFiltering ? (
+              <fieldset className="relative border border-blue-200 dark:border-blue-800/40 rounded-lg px-2.5 pt-1 pb-3 mb-3 bg-blue-50/20 dark:bg-blue-900/5 transition-all">
+                <legend className="text-[9px] uppercase tracking-widest text-brand-primary px-1 font-medium leading-none">{filterLabel}</legend>
+                {filterControls}
+                <div className="mt-3">{feed}</div>
+              </fieldset>
+            ) : (
+              <>
+                <fieldset className="relative border border-border-default rounded-lg px-2.5 pt-1 pb-2 mb-3">
+                  <legend className="text-[9px] uppercase tracking-widest text-text-muted px-1 font-medium leading-none">Filter</legend>
+                  {filterControls}
+                </fieldset>
+                {feed}
+              </>
+            );
+          })()}
         </Section>
         )}
       </PageLayout.Content>

From e02b011ebdb8237be2780d1f46a781c55834385a Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Tue, 17 Mar 2026 14:38:23 -0400
Subject: [PATCH 40/41] feat(diffwatch): overwrite prior versions instead of
 accumulating ordinals

Each vr:capture run now deletes old _NN files before writing the new
version, keeping only the latest ordinal per stem across comparisons,
annotated, and diffs directories. Also updates PR description template
to use DRAG_DROP placeholder convention for manual image upload.
---
 .../PR_DESCRIPTION_HELLO-PR.md                | 22 +++++++-------
 scripts/visual-regression/capture-vr.ts       | 30 ++++++++++++++-----
 2 files changed, 34 insertions(+), 18 deletions(-)

diff --git a/docs/pr-descriptions/PR_DESCRIPTION_HELLO-PR.md b/docs/pr-descriptions/PR_DESCRIPTION_HELLO-PR.md
index 5b59d7bb..f16fb8f2 100644
--- a/docs/pr-descriptions/PR_DESCRIPTION_HELLO-PR.md
+++ b/docs/pr-descriptions/PR_DESCRIPTION_HELLO-PR.md
@@ -285,41 +285,41 @@ quadrantChart
 _Generated by Diffwatch (`npm run vr:capture`). Comparison images uploaded from `.visual-regression/captures/comparisons/`._
 
 ### Grid Operators — Consolidated Codes Column (desktop)
-<!-- ![grid-operators-new-columns-desktop](URL) -->
+![grid-operators-new-columns-desktop](DRAG_DROP:grid-operators-new-columns-desktop.png)
 _Codes column with stacked EIA/BA/NERC linked badges replacing three sparse columns._
 
 ### Dropdown Chevron Padding (mobile + desktop)
-<!-- ![dropdown-chevron-padding-desktop](URL) -->
-<!-- ![dropdown-chevron-padding-mobile](URL) -->
+![dropdown-chevron-padding-desktop](DRAG_DROP:dropdown-chevron-padding-desktop.png)
+![dropdown-chevron-padding-mobile](DRAG_DROP:dropdown-chevron-padding-mobile.png)
 _Inner right-side padding on native `<select>` elements across all data pages._
 
 ### Header Spacing (desktop)
-<!-- ![header-spacing-desktop](URL) -->
+![header-spacing-desktop](DRAG_DROP:header-spacing-desktop.png)
 _h-14 → h-12, tighter nav link padding, adjusted logo-to-nav gap._
 
 ### Badge Variants (desktop)
-<!-- ![badge-variants-desktop](URL) -->
+![badge-variants-desktop](DRAG_DROP:badge-variants-desktop.png)
 _Corrected badge color mapping for all utility segment types._
 
 ### Sort Chevrons (desktop)
-<!-- ![sort-chevrons-desktop](URL) -->
+![sort-chevrons-desktop](DRAG_DROP:sort-chevrons-desktop.png)
 _Sort direction ▲/▼ indicators in dropdown labels on power-plants._
 
 ### Changelog Redesign (tablet + desktop)
-<!-- ![changelog-tabs-desktop](URL) -->
-<!-- ![changelog-tabs-tablet](URL) -->
+![changelog-tabs-desktop](DRAG_DROP:changelog-tabs-desktop.png)
+![changelog-tabs-tablet](DRAG_DROP:changelog-tabs-tablet.png)
 _Pill toggle (Grid Data / Site), filter fieldset with entity-type pills + inline search, combined sync status with pulse indicator._
 
 ### Filter Stacking (mobile)
-<!-- ![filter-stacking-mobile](URL) -->
+![filter-stacking-mobile](DRAG_DROP:filter-stacking-mobile.png)
 _Filter dropdowns stack full-width vertically on narrow viewports._
 
 ### Name Clamping (mobile)
-<!-- ![name-clamping-mobile](URL) -->
+![name-clamping-mobile](DRAG_DROP:name-clamping-mobile.png)
 _2-line name clamp on grid-operators cards at 375px._
 
 ### Mobile Menu (mobile)
-<!-- ![mobile-menu-mobile](URL) -->
+![mobile-menu-mobile](DRAG_DROP:mobile-menu-mobile.png)
 _Mobile menu with active brand color state and hover backgrounds._
 
 ---
diff --git a/scripts/visual-regression/capture-vr.ts b/scripts/visual-regression/capture-vr.ts
index f8d2d50b..7f7853c6 100644
--- a/scripts/visual-regression/capture-vr.ts
+++ b/scripts/visual-regression/capture-vr.ts
@@ -55,24 +55,36 @@ interface CatalogEntry {
 
 // ── Versioning ───────────────────────────────────────────────────────────────
 
+/** Delete all versioned files matching `{stem}_NN{ext}` in a directory. */
+function cleanVersionedFiles(dir: string, stem: string, ext: string): void {
+	if (!fs.existsSync(dir)) return;
+	const escapedStem = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const re = new RegExp(`^${escapedStem}_(\\d+)${ext.replace(".", "\\.")}$`);
+	for (const f of fs.readdirSync(dir)) {
+		if (re.test(f)) fs.unlinkSync(path.join(dir, f));
+	}
+}
+
 /**
  * Find the next ordinal version for a file stem in a directory.
- * Existing: foo_00.png, foo_01.png → returns "foo_02" and 2.
+ * Deletes all prior versioned files so only the latest is kept.
+ * Existing: foo_00.png, foo_01.png → deletes both, returns "foo_02" and 2.
  * No existing: returns "foo_00" and 0.
  */
 function nextVersionedStem(dir: string, stem: string, ext: string): { filename: string; ordinal: number } {
 	let ordinal = 0;
 	if (fs.existsSync(dir)) {
-		const existing = fs.readdirSync(dir).filter(
-			(f) => f.startsWith(`${stem}_`) && f.endsWith(ext),
-		);
-		for (const f of existing) {
-			const match = f.match(new RegExp(`^${stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}_(\\d+)${ext.replace(".", "\\.")}$`));
+		const escapedStem = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		const re = new RegExp(`^${escapedStem}_(\\d+)${ext.replace(".", "\\.")}$`);
+		for (const f of fs.readdirSync(dir)) {
+			const match = f.match(re);
 			if (match) {
 				const n = parseInt(match[1], 10);
 				if (n >= ordinal) ordinal = n + 1;
 			}
 		}
+		// Remove all prior versions
+		cleanVersionedFiles(dir, stem, ext);
 	}
 	const pad = String(ordinal).padStart(2, "0");
 	return { filename: `${stem}_${pad}${ext}`, ordinal };
@@ -333,9 +345,13 @@ async function main() {
 			const beforeRegionsPath = path.join(dirs.before, `${stem}.regions.json`);
 			const afterRegionsPath = path.join(dirs.after, `${stem}.regions.json`);
 
-			// Versioned outputs — each run gets an ordinal (_00, _01, _02…)
+			// Versioned outputs — each run overwrites prior versions, keeping only the latest
 			const { filename: compFilename, ordinal } = nextVersionedStem(dirs.comparisons, stem, ".png");
 			const versionSuffix = `_${String(ordinal).padStart(2, "0")}`;
+			// Clean prior annotated and diff versions for this stem
+			cleanVersionedFiles(dirs.annotated, `${stem}-before`, ".png");
+			cleanVersionedFiles(dirs.annotated, `${stem}-after`, ".png");
+			cleanVersionedFiles(dirs.diffs, `${stem}-diff`, ".png");
 			const beforeAnnotated = path.join(dirs.annotated, `${stem}-before${versionSuffix}.png`);
 			const afterAnnotated = path.join(dirs.annotated, `${stem}-after${versionSuffix}.png`);
 			const comparisonPath = path.join(dirs.comparisons, compFilename);

From b22019fbe0517b30ebb2e26b972b444dfff69771 Mon Sep 17 00:00:00 2001
From: Patrick Astarita <44125645+pastarita@users.noreply.github.com>
Date: Tue, 17 Mar 2026 15:08:05 -0400
Subject: [PATCH 41/41] fix(explorer): resolve layout ReferenceError and hide
 mapbox key in production

- ExplorerShell: fix undefined `layout` variable in HybridLayout by
  using static key string (component only renders when layout=hybrid)
- ExplorerMap: show env var name only in development; production users
  see a generic "temporarily unavailable" message
---
 components/explorer/ExplorerMap.tsx   | 7 ++++++-
 components/explorer/ExplorerShell.tsx | 2 +-
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/components/explorer/ExplorerMap.tsx b/components/explorer/ExplorerMap.tsx
index 5f62c49f..38feba04 100644
--- a/components/explorer/ExplorerMap.tsx
+++ b/components/explorer/ExplorerMap.tsx
@@ -678,11 +678,16 @@ export function ExplorerMap({ mapboxAccessToken }: ExplorerMapProps = {}) {
   }, [handleClick, router, state.highlightGeoJSON, isGridOperatorView, filteredGridBoundaryData, hasHighlight, territoryFilter, layerVisibility]);
 
   if (!hasMapboxToken) {
+    const isDev = process.env.NODE_ENV === "development";
     return (
       <div className="h-full w-full flex items-center justify-center bg-background-surface">
         <div className="text-center px-6">
           <div className="text-lg font-semibold text-text-heading mb-2">Map Unavailable</div>
-          <p className="text-sm text-text-muted">Set NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN to enable the map.</p>
+          <p className="text-sm text-text-muted">
+            {isDev
+              ? "Set NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN to enable the map."
+              : "The map is temporarily unavailable. Please try again later."}
+          </p>
         </div>
       </div>
     );
diff --git a/components/explorer/ExplorerShell.tsx b/components/explorer/ExplorerShell.tsx
index 8b32a1c8..126f0372 100644
--- a/components/explorer/ExplorerShell.tsx
+++ b/components/explorer/ExplorerShell.tsx
@@ -69,7 +69,7 @@ function HybridLayout({ mapboxAccessToken }: HybridLayoutProps) {
 
       {/* Map — RIGHT */}
       <div className="flex-1 min-w-0 h-full">
-        <ExplorerMap key={layout} mapboxAccessToken={mapboxAccessToken} />
+        <ExplorerMap key="hybrid" mapboxAccessToken={mapboxAccessToken} />
       </div>
     </div>
   );