From 41141c76f74d6c5e47c0198335bab0c3e32aabed Mon Sep 17 00:00:00 2001
From: Corbin Crutchley <git@crutchcorn.dev>
Date: Mon, 4 May 2026 01:53:13 -0700
Subject: [PATCH] feat: make debug comments optional

---
 Island.cfm               | 20 +++++++++++---------
 README.md                |  3 +++
 coldspa/IslandConfig.cfc |  9 ++++++++-
 3 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/Island.cfm b/Island.cfm
index 3ddd27f..cfca7c5 100644
--- a/Island.cfm
+++ b/Island.cfm
@@ -155,15 +155,17 @@ if (!cfg.isDev && len(ssrHtml) && structKeyExists(attributes.framework, "clientE
 }
 </cfscript>
 
-<!--- Surface SSR failures so they aren't silently swallowed. --->
-<cfif clientOnly>
-    <cfoutput><!-- coldspa SSR: skipped (strategy="client") --></cfoutput>
-<cfelseif len(ssrError)>
-    <cfoutput><!-- coldspa SSR error: #encodeForHTML(ssrError)# --></cfoutput>
-<cfelseif not len(ssrHtml)>
-    <cfoutput><!-- coldspa SSR: empty html, no error reported (renderer may not implement ssrRender) --></cfoutput>
-<cfelse>
-    <cfoutput><!-- coldspa SSR: ok (#len(ssrHtml)# bytes, #len(ssrCss)# css bytes) --></cfoutput>
+<!--- Surface SSR failures so they aren't silently swallowed (debug only). --->
+<cfif (cfg.debug ?: false)>
+    <cfif clientOnly>
+        <cfoutput><!-- coldspa SSR: skipped (strategy="client") --></cfoutput>
+    <cfelseif len(ssrError)>
+        <cfoutput><!-- coldspa SSR error: #encodeForHTML(ssrError)# --></cfoutput>
+    <cfelseif not len(ssrHtml)>
+        <cfoutput><!-- coldspa SSR: empty html, no error reported (renderer may not implement ssrRender) --></cfoutput>
+    <cfelse>
+        <cfoutput><!-- coldspa SSR: ok (#len(ssrHtml)# bytes, #len(ssrCss)# css bytes) --></cfoutput>
+    </cfif>
 </cfif>
 
 <!--- Inline scoped/component CSS (dev) so styles are present pre-hydration. --->
diff --git a/README.md b/README.md
index ac7c13d..0672e0b 100644
--- a/README.md
+++ b/README.md
@@ -56,6 +56,7 @@ Coldspa resolves config in this order (highest priority first):
 | `CF_ENV`            | `development` / `dev` switches Coldspa to dev mode                       |
 | `COLDSPA_SSR_URL`   | Where **CF** reaches the SSR sidecar (server-to-server)                  |
 | `COLDSPA_VITE_URL`  | Where the **browser** reaches the Vite dev server (used for asset URLs)  |
+| `COLDSPA_DEBUG`     | `1` / `true` emits diagnostic HTML comments per island                   |
 | `COLDSPA_SSR_PORT`  | (sidecar) Port to listen on. Default `5174`                              |
 | `COLDSPA_SSR_HOST`  | (sidecar) Bind address. Default `0.0.0.0`. Use `127.0.0.1` to lock down  |
 | `NODE_ENV`          | (sidecar) `production` switches sidecar to use built bundle              |
@@ -67,6 +68,7 @@ Lives in the webroot. Should be `.gitignore`d (it can be edited via the CF Admin
 ```json
 {
     "isDev": true,
+    "debug": false,
     "ssrUrl":  "http://127.0.0.1:5174",
     "viteUrl": "http://localhost:5173",
     "vitePort": "5173"
@@ -76,6 +78,7 @@ Lives in the webroot. Should be `.gitignore`d (it can be edited via the CF Admin
 | Key        | Default                  | Description                                                 |
 |------------|--------------------------|-------------------------------------------------------------|
 | `isDev`    | `false`                  | Dev mode (uses Vite dev server) vs prod (uses `dist/`)      |
+| `debug`    | `false`                  | Emit `<!-- coldspa SSR: ... -->` diagnostic comments        |
 | `ssrUrl`   | `http://127.0.0.1:5174`  | SSR sidecar URL (server-to-server)                          |
 | `viteUrl`  | unset                    | Browser-facing Vite URL. Falls back to `localhost:vitePort` |
 | `vitePort` | `"5173"`                 | Used to build the default `viteUrl` if `viteUrl` is unset   |
diff --git a/coldspa/IslandConfig.cfc b/coldspa/IslandConfig.cfc
index 7502acc..4ea0e06 100644
--- a/coldspa/IslandConfig.cfc
+++ b/coldspa/IslandConfig.cfc
@@ -27,7 +27,7 @@
     <!--- ===== private ===== --->
 
     <cffunction name="resolve" access="private" returntype="struct" output="false">
-        <cfset var defaults = { "isDev": false, "vitePort": "5173", "ssrUrl": "http://127.0.0.1:5174" }>
+        <cfset var defaults = { "isDev": false, "debug": false, "vitePort": "5173", "ssrUrl": "http://127.0.0.1:5174" }>
         <cfset var resolved = duplicate(defaults)>
 
         <!--- 2nd priority: /island-config.json --->
@@ -76,6 +76,13 @@
             <cfif len(envViteUrl)>
                 <cfset resolved.viteUrl = envViteUrl>
             </cfif>
+
+            <!--- COLDSPA_DEBUG: when truthy ("1", "true", "yes"), Island.cfm
+                  emits diagnostic HTML comments about SSR status / byte counts. --->
+            <cfset var envDebug = envSys.getenv("COLDSPA_DEBUG") ?: "">
+            <cfif len(envDebug)>
+                <cfset resolved.debug = listFindNoCase("1,true,yes,on", envDebug) gt 0>
+            </cfif>
         </cfif>
 
         <cfreturn resolved>
-- 
2.51.2