Merge pull request #55 from liamgold/feature/swdm-v4-green-hosting

Upgrade to SWDM v4 and add green hosting detection

Author: liamgold

.github/RELEASE.md

@@ -15,7 +15,7 @@ A community-driven open-source NuGet package that brings sustainability insights
 - **Xperience by Kentico** (>= 30.4.2)
 - **Microsoft Playwright** (1.52.0) - Headless browser automation
 - **React + TypeScript** - Admin UI components
-- **@tgwf/co2** library - Carbon emission calculations
+- **@tgwf/co2** library (v0.16.9) - Carbon emission calculations using SWDM v4
 
 ## Project Structure
 
@@ -40,7 +40,7 @@ C:\Projects\xperience-community-sustainability\
 │   ├── Models/                             # Data structures
 │   │   ├── SustainabilityResponse.cs       # API response model
 │   │   ├── SustainabilityData.cs           # Raw data from JS (naming: lowercase for JSON mapping)
-│   │   ├── SustainabilityOptions.cs        # Configuration options (PlaywrightBrowserPath)
+│   │   ├── SustainabilityOptions.cs        # Configuration options (TimeoutMilliseconds, EnableBrowserConsoleLogging)
 │   │   ├── ExternalResource.cs             # Individual resource model
 │   │   └── ExternalResourceGroup.cs        # Resource grouping by type (Images, Scripts, CSS, etc.)
 │   ├── Extensions/                         # Extension methods
@@ -105,8 +105,9 @@ C:\Projects\xperience-community-sustainability\
 3. **Data loaded**: Displays comprehensive dashboard with hero carbon rating
 
 **Key Features**:
-- **Hero Carbon Rating Section** - Large 120px rating letter with gradient background themed by rating color
+- **Hero Carbon Rating Section** - Large 120px rating letter with gradient background themed by rating color, includes link to SWDM v4 methodology
 - **Stat Cards Grid** - 2x2 grid showing CO₂ Emissions, Page Weight, Resources count, and Efficiency rating
+- **Green Hosting Info Banner** - Displays hosting status (Green/Standard/Unknown) with color-coded badge between hero and resources
 - **Collapsible Resource Lists** - Shows 3 resources by default with "Show X more" button
 - **Resource Breakdown** - Sorted by size (largest first) with filename/path separation
 - **Percentage Badges** - Shows what % of total page weight each resource group represents
@@ -121,16 +122,28 @@ C:\Projects\xperience-community-sustainability\
 ### 4. JavaScript Analysis (src/wwwroot/scripts/resource-checker.js)
 
 **Process**:
-1. Scrolls page to trigger lazy-loaded resources (line 21)
-2. Waits 2 seconds for resources to load (line 22)
-3. Collects all resources via `performance.getEntriesByType("resource")` (line 47)
-4. Calculates total transfer size (line 51)
-5. Checks if host uses green energy via `@tgwf/co2` (line 33)
-6. Calculates CO2 emissions using SWD model (line 36)
-7. Assigns grade A+ through F (line 56-64)
-8. Outputs JSON to DOM element with `data-testid="sustainabilityData"` (line 14)
-
-**External Dependency**: `https://cdn.skypack.dev/@tgwf/co2@0.15` (line 1)
+1. Scrolls page to trigger lazy-loaded resources
+2. Waits 2 seconds for resources to load
+3. Collects all resources via `performance.getEntriesByType("resource")`
+4. Calculates total transfer size
+5. Checks if host uses green energy via `@tgwf/co2` hosting check (returns Green/NotGreen/Unknown)
+6. Calculates CO2 emissions using **SWDM v4** with `perByteTrace()` method
+7. Retrieves built-in rating (A+ through F) from `@tgwf/co2` v0.16
+8. Outputs JSON to DOM element with `data-testid="sustainabilityData"`
+
+**Key Implementation Details**:
+- Uses **SWDM v4** (`{ model: "swd", version: 4, rating: true }`)
+- Uses `perByteTrace()` instead of deprecated `perVisitTrace()`
+- Bundled library (no external CDN dependency) - webpack bundles `@tgwf/co2` locally
+- Hosting check handles both function and object patterns for compatibility
+- Rating thresholds (grams CO₂ per page view):
+  - A+: < 0.040g
+  - A: < 0.079g
+  - B: < 0.145g
+  - C: < 0.209g
+  - D: < 0.278g
+  - E: < 0.359g
+  - F: >= 0.360g
 
 ### 5. Module Installation (src/Admin/SustainabilityModuleInstaller.cs)
 
@@ -139,14 +152,15 @@ C:\Projects\xperience-community-sustainability\
 2. `InitializeModule` invoked when app initialized (line 29)
 3. `Install()` creates database table for `SustainabilityPageDataInfo` (line 15)
 
-**Database Schema** (lines 58-119):
+**Database Schema**:
 - `SustainabilityPageDataID` (PK)
 - `WebPageItemID` (Foreign key to page)
 - `LanguageName` (Language variant)
 - `DateCreated`
 - `TotalSize` (decimal)
 - `TotalEmissions` (double)
 - `CarbonRating` (string: A+, A, B, C, D, E, F)
+- `GreenHostingStatus` (string: Green, NotGreen, Unknown)
 - `ResourceGroups` (JSON serialized)
 
 ## Configuration
@@ -156,13 +170,15 @@ C:\Projects\xperience-community-sustainability\
 ```json
 {
   "Sustainability": {
-    "TimeoutMilliseconds": 60000
+    "TimeoutMilliseconds": 60000,
+    "EnableBrowserConsoleLogging": false
   }
 }
 ```
 
 **Options**:
 - `TimeoutMilliseconds`: Timeout in milliseconds for waiting for sustainability data to be collected. Default: 60000 (60 seconds)
+- `EnableBrowserConsoleLogging`: Enable browser console logging to Kentico Event Log for debugging. Default: false. When enabled, all console messages from the headless browser (including those from resource-checker.js) are logged to the Event Log with source "SustainabilityService" and event code "BrowserConsole"
 
 ### Service Registration (Program.cs)
 
@@ -175,6 +191,43 @@ This registers:
 - `ISustainabilityModuleInstaller` as Singleton
 - Binds `SustainabilityOptions` from configuration
 
+## Data Models
+
+### SustainabilityData (from JavaScript)
+
+The JavaScript returns data with a nested `Co2Result` structure:
+
+```json
+{
+  "pageWeight": 1234567,
+  "carbonRating": "B",
+  "greenHostingStatus": "Green",
+  "emissions": {
+    "co2": {
+      "total": 0.123,
+      "rating": "B"
+    },
+    "green": true
+  },
+  "resources": [...]
+}
+```
+
+### Backend Models
+
+**SustainabilityData.cs**:
+- `PageWeight` (int) - Total bytes transferred
+- `CarbonRating` (string) - Letter grade from JavaScript
+- `GreenHostingStatus` (string) - Green, NotGreen, or Unknown
+- `Emissions` (Emissions object)
+  - `Co2` (Co2Result object) - **Note: Nested structure**
+    - `Total` (double) - Grams CO₂ per page view
+    - `Rating` (string) - Built-in rating from @tgwf/co2
+  - `Green` (bool) - Whether green hosting was used in calculation
+- `Resources` (Resource array)
+
+**Important**: The backend reads `sustainabilityData.Emissions?.Co2?.Total` (nested) to get the emission value, not a flat `Co2` property.
+
 ## Data Flow
 
 ### Running a New Report
@@ -210,7 +263,6 @@ This registers:
 
 ## Known Issues & Limitations
 
-- **External CDN dependency**: Skypack CDN for @tgwf/co2 (availability risk) - see GitHub issues for planned improvements
 - **No automated tests**: Unit/integration tests needed for service and UI components
 - **Future enhancements**: See GitHub issues for planned features (global dashboard, historical trends, etc.)
 
@@ -249,9 +301,7 @@ npm run build
 - `@kentico/xperience-admin-base` (30.4.2) - Base admin framework
 - `@kentico/xperience-admin-components` (30.4.2) - Native XbyK UI components
 - React (18.3.1) and React DOM (18.3.1)
-
-### External Runtime
-- `@tgwf/co2` (v0.15) via Skypack CDN
+- `@tgwf/co2` (v0.16.9) - Bundled locally via webpack (no external CDN)
 
 ## Common Tasks
 
@@ -264,7 +314,11 @@ npm run build
 
 ### Modifying Carbon Rating Thresholds
 
-Edit `resource-checker.js` line 56-64 (grades) and update React component's `ratingDescriptions` (SustainabilityTabTemplate.tsx:41-49).
+**Note**: Carbon ratings now come from the built-in `@tgwf/co2` library using SWDM v4 official thresholds. The library automatically assigns ratings based on grams CO₂ per page view.
+
+If you need to customize rating descriptions or UI display:
+- Update React component's `ratingDescriptions` (SustainabilityTabTemplate.tsx)
+- Update `getHostingStatusDisplay()` helper for hosting status colors and text
 
 ### Changing Resource Categories
 
@@ -278,8 +332,10 @@ Update `ResourceGroupType` enum (ExternalResourceGroup.cs:43-55) and `GetInitiat
 
 ## Debugging Tips
 
-1. **Playwright issues**: Check event log in Kentico admin for logged errors
-2. **Script not loading**: Verify `/_content/XperienceCommunity.Sustainability/scripts/resource-checker.js` is accessible
-3. **Timeout errors**: Increase timeout in SustainabilityService.cs:60 or check if page loads slowly
-4. **CSP errors**: Ensure `BypassCSP = true` is set (line 45)
-5. **Browser not found**: Playwright requires browser installation (`playwright install chromium`)
+1. **Enable console logging**: Set `EnableBrowserConsoleLogging: true` in appsettings.json to log all browser console messages to Kentico Event Log. View logs in Admin → System → Event log (source: `SustainabilityService`, event code: `BrowserConsole`)
+2. **Playwright issues**: Check event log in Kentico admin for logged errors
+3. **Script not loading**: Verify `/_content/XperienceCommunity.Sustainability/scripts/resource-checker.js` is accessible
+4. **Timeout errors**: Increase `TimeoutMilliseconds` in appsettings.json or check if page loads slowly
+5. **CSP errors**: Ensure `BypassCSP = true` is set in SustainabilityService.cs
+6. **Browser not found**: Playwright requires browser installation (`playwright install chromium`)
+7. **Hosting status Unknown**: Check Event Log with console logging enabled to see if Green Web Foundation API is accessible

CLAUDE.md

@@ -55,6 +55,36 @@ dotnet add package XperienceCommunity.Sustainability
 
 > **Note**: Playwright browsers (Chromium) are automatically installed on first application startup. The installation path defaults to `App_Data/playwright` unless you're hosting on a UNC path.
 
+## Features
+
+### Carbon Emissions Calculation
+
+The package uses the **Sustainable Web Design Model v4 (SWDM v4)** from [The Green Web Foundation](https://www.thegreenwebfoundation.org/) to calculate carbon emissions. Carbon ratings (A+ through F) follow the [official Digital Carbon Ratings](https://sustainablewebdesign.org/digital-carbon-ratings/) methodology.
+
+### Green Hosting Detection
+
+The package automatically checks if your website is hosted on a green energy provider using The Green Web Foundation's database. This affects the carbon calculation:
+
+- **Green hosting**: Uses renewable energy intensity values (lower emissions)
+- **Standard hosting**: Uses global grid intensity values
+- **Unknown**: When verification fails, conservative estimates are used
+
+The hosting status is displayed in the Sustainability report with three possible states:
+
+- ● **Green hosting** - Site uses renewable/green energy
+- ● **Standard hosting** - Site uses standard grid energy
+- ● **Unknown hosting** - Unable to verify hosting provider
+
+### Sustainability Report
+
+Each report includes:
+
+- **Carbon Rating**: Letter grade (A+ through F) based on grams CO₂ per page view
+- **CO₂ Emissions**: Total carbon emissions with hosting status indicator
+- **Page Weight**: Total size of all resources loaded
+- **Resource Breakdown**: Categorized by type (Images, Scripts, CSS, etc.) with individual file sizes
+- **Optimization Tips**: Xperience-specific recommendations for reducing page weight
+
 ## Configuration
 
 The package can be configured using the `Sustainability` section in your `appsettings.json` file.
@@ -63,7 +93,8 @@ The package can be configured using the `Sustainability` section in your `appset
 {
   "Sustainability": {
     "TimeoutMilliseconds": 60000,
-    "PlaywrightBrowserPath": "/custom/path/to/playwright/browsers"
+    "PlaywrightBrowserPath": "/custom/path/to/playwright/browsers",
+    "EnableBrowserConsoleLogging": false
   }
 }
 ```
@@ -74,6 +105,7 @@ The package can be configured using the `Sustainability` section in your `appset
 | ------ | ----------- | ------- |
 | `TimeoutMilliseconds` | Timeout in milliseconds for waiting for sustainability data to be collected from the page. | `60000` (60 seconds) |
 | `PlaywrightBrowserPath` | Custom path where Playwright browsers should be installed. **Only required when hosting on UNC paths (network shares starting with `\\`)**. For standard hosting, browsers are automatically installed in `App_Data/playwright`. | `null` |
+| `EnableBrowserConsoleLogging` | Enable browser console logging to Kentico Event Log for debugging purposes. When enabled, all console messages from the headless browser are logged to help troubleshoot issues. | `false` |
 
 > **Note on UNC Hosting**: When hosting on UNC paths (network shares), you **must** configure `PlaywrightBrowserPath` or the application will throw an error during startup. This setting is ignored for standard hosting scenarios.
 

README.md

@@ -19,6 +19,6 @@
   "CMSHashStringSalt": "792155e3-6bc0-4eb3-ae03-47db9331b540",
   "Sustainability": {
     "PlaywrightBrowserPath": "#{WebsitePath}#\\App_Data\\playwright",
-    "TimeoutMilliseconds": 6000
+    "TimeoutMilliseconds": 60000
   }
 }

examples/DancingGoat/appsettings.json

@@ -118,6 +118,15 @@ private static void InstallSustainabilityPageDataClass(ResourceInfo resourceInfo
         };
         formInfo.AddFormItem(formItem);
 
+        formItem = new FormFieldInfo
+        {
+            Name = nameof(SustainabilityPageDataInfo.GreenHostingStatus),
+            Visible = false,
+            DataType = FieldDataType.Text,
+            Enabled = true,
+        };
+        formInfo.AddFormItem(formItem);
+
         SetFormDefinition(info, formInfo);
 
         if (info.HasChanged)

src/Admin/SustainabilityModuleInstaller.cs

@@ -118,6 +118,17 @@ public virtual string ResourceGroups
         }
 
 
+        /// <summary>
+        /// Green hosting status.
+        /// </summary>
+        [DatabaseField]
+        public virtual string GreenHostingStatus
+        {
+            get => ValidationHelper.GetString(GetValue(nameof(GreenHostingStatus)), String.Empty);
+            set => SetValue(nameof(GreenHostingStatus), value);
+        }
+
+
         /// <summary>
         /// Deletes the object using appropriate provider.
         /// </summary>