From 49a24973fa8c8ca5d89cee604ab1647b0ad45353 Mon Sep 17 00:00:00 2001
From: Corbin Crutchley <git@crutchcorn.dev>
Date: Mon, 4 May 2026 01:51:05 -0700
Subject: [PATCH] feat: add `client` rendering strategy for islands

---
 Island.cfm                           | 52 ++++++++++++++++++----------
 README.md                            | 13 +++++++
 coldspa/renderers/React.cfm          |  5 +--
 coldspa/renderers/Vue.cfm            |  5 +--
 coldspa/vite/clients/react-client.js | 14 ++++++--
 coldspa/vite/clients/vue-client.js   | 11 +++---
 6 files changed, 69 insertions(+), 31 deletions(-)

diff --git a/Island.cfm b/Island.cfm
index be6b8d2..3ddd27f 100644
--- a/Island.cfm
+++ b/Island.cfm
@@ -8,7 +8,8 @@
         framework  (struct, required)  - renderer struct from /coldspa/renderers/*
         path       (string, required)  - component path (e.g. "./App.vue")
         props      (struct, optional)  - props passed to the component (default {})
-        strategy   (string, optional)  - "load" | "idle" | "visible" (default "load")
+        strategy   (string, optional)  - "load" | "idle" | "visible" | "client" (default "load")
+                                         "client" skips SSR entirely (no server HTML, no CSS pre-render)
 --->
 <cfparam name="attributes.framework" type="struct">
 <cfparam name="attributes.path" type="string">
@@ -22,14 +23,17 @@ if (thisTag.executionMode neq "start") {
 }
 
 // --- validate strategy
-validStrategies = ["load", "idle", "visible"];
+validStrategies = ["load", "idle", "visible", "client"];
 if (!arrayFindNoCase(validStrategies, attributes.strategy)) {
     throw(
         type    = "Coldspa.InvalidStrategy",
-        message = "Invalid hydration strategy '#attributes.strategy#'. Must be one of: load, idle, visible."
+        message = "Invalid hydration strategy '#attributes.strategy#'. Must be one of: load, idle, visible, client."
     );
 }
 
+// "client" strategy is client-only: skip SSR entirely.
+clientOnly = (attributes.strategy == "client");
+
 // --- validate renderer shape
 if (!structKeyExists(attributes.framework, "render") || !isCustomFunction(attributes.framework.render)) {
     throw(
@@ -92,24 +96,15 @@ if (structKeyExists(attributes.framework, "clientEntry")) {
     resolvedClientEntry = resolveAsset(attributes.framework.clientEntry);
 }
 
-rendered = attributes.framework.render(mountId, componentGlobKey, propsJson, resolvedClientEntry);
-
-// Backwards-compat: allow renderers that still return a plain string (treated as body, no imports)
-if (isSimpleValue(rendered)) {
-    rendered = { "imports": "", "body": rendered };
-}
-bootImports = rendered.imports;
-bootBody    = rendered.body;
-
 // Server-side rendering. If the renderer supports ssrRender(), call the SSR
-// sidecar and embed the returned HTML inside the mount div. The client's
-// createSSRApp().mount() will hydrate it on load. If SSR fails or isn't
-// available, we just emit an empty div and the client mounts fresh -- so the
-// page works either way (just no JS-off rendering in that case).
+// sidecar and embed the returned HTML inside the mount div. The client uses
+// the hydrate flag (computed from whether SSR actually produced HTML) to pick
+// between hydrate-mode and fresh client-mount APIs. If SSR fails or isn't
+// available, the page still works -- just no pre-rendered markup.
 ssrHtml  = "";
 ssrCss   = "";
 ssrError = "";
-if (structKeyExists(attributes.framework, "ssrRender")) {
+if (!clientOnly && structKeyExists(attributes.framework, "ssrRender")) {
     ssrResult = attributes.framework.ssrRender(componentGlobKey, attributes.props);
     // Tolerate older renderers that returned a plain string.
     if (isStruct(ssrResult)) {
@@ -121,6 +116,23 @@ if (structKeyExists(attributes.framework, "ssrRender")) {
     }
 }
 
+// Build the options object passed to the client's mount() function. The
+// client uses `strategy` to decide between hydrate-mode and fresh-mount APIs;
+// SSR is skipped entirely above when strategy="client", so anything else
+// implies SSR markup is present.
+mountOptionsJson = serializeJSON({
+    "strategy": attributes.strategy
+});
+
+rendered = attributes.framework.render(mountId, componentGlobKey, propsJson, resolvedClientEntry, mountOptionsJson);
+
+// Backwards-compat: allow renderers that still return a plain string (treated as body, no imports)
+if (isSimpleValue(rendered)) {
+    rendered = { "imports": "", "body": rendered };
+}
+bootImports = rendered.imports;
+bootBody    = rendered.body;
+
 // In prod the SSR sidecar can't easily inline component CSS (the SSR build
 // doesn't emit CSS), so we surface it as <link> tags from the client manifest.
 // Each chunk in the manifest carries a `css` array of hashed asset filenames.
@@ -144,7 +156,9 @@ if (!cfg.isDev && len(ssrHtml) && structKeyExists(attributes.framework, "clientE
 </cfscript>
 
 <!--- Surface SSR failures so they aren't silently swallowed. --->
-<cfif len(ssrError)>
+<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>
@@ -166,7 +180,7 @@ if (!cfg.isDev && len(ssrHtml) && structKeyExists(attributes.framework, "clientE
 
 <cfoutput>
 <cfswitch expression="#attributes.strategy#">
-    <cfcase value="load">
+    <cfcase value="load,client" delimiters=",">
 <script type="module">
 #bootImports#
 #bootBody#
diff --git a/README.md b/README.md
index a5ba989..ac7c13d 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,19 @@ npm run build      # builds client + SSR bundles
 npm run ssr:prod   # runs the sidecar against the built bundle
 ```
 
+## Hydration strategies
+
+`strategy=` controls when (and whether) the component renders.
+
+| Strategy  | SSR'd HTML? | Client boots when…                                  |
+|-----------|-------------|-----------------------------------------------------|
+| `load`    | yes         | the module loads (default)                          |
+| `idle`    | yes         | `requestIdleCallback` fires                         |
+| `visible` | yes         | the mount enters the viewport (`IntersectionObserver`) |
+| `client`  | **no**      | the module loads (no SSR HTML or CSS is emitted)    |
+
+Use `client` for components that depend on browser-only APIs (window, IndexedDB, etc.) or where SSR isn't worth the round-trip.
+
 ## Configuration
 
 Coldspa resolves config in this order (highest priority first):
diff --git a/coldspa/renderers/React.cfm b/coldspa/renderers/React.cfm
index 48bd883..7259171 100644
--- a/coldspa/renderers/React.cfm
+++ b/coldspa/renderers/React.cfm
@@ -6,7 +6,7 @@
 React = {
     "name": "React",
     "clientEntry": "./coldspa/vite/clients/react-client.js",
-    "render": function(mountId, componentGlobKey, propsJson, resolvedClientEntry) {
+    "render": function(mountId, componentGlobKey, propsJson, resolvedClientEntry, optionsJson) {
         var jsId = arguments.mountId.replace('-', '_', 'all');
         return {
             "imports": "
@@ -16,7 +16,8 @@ React = {
                 __coldspa_mount_#jsId#(
                     '#arguments.componentGlobKey#',
                     document.getElementById('#arguments.mountId#'),
-                    #arguments.propsJson#
+                    #arguments.propsJson#,
+                    #arguments.optionsJson#
                 );
             "
         };
diff --git a/coldspa/renderers/Vue.cfm b/coldspa/renderers/Vue.cfm
index 6840f64..f862fb8 100644
--- a/coldspa/renderers/Vue.cfm
+++ b/coldspa/renderers/Vue.cfm
@@ -42,7 +42,7 @@ Vue = {
         }
     },
 
-    "render": function(mountId, componentGlobKey, propsJson, resolvedClientEntry) {
+    "render": function(mountId, componentGlobKey, propsJson, resolvedClientEntry, optionsJson) {
         var jsId = arguments.mountId.replace('-', '_', 'all');
         return {
             "imports": "
@@ -52,7 +52,8 @@ Vue = {
                 __coldspa_mount_#jsId#(
                     '#arguments.componentGlobKey#',
                     document.getElementById('#arguments.mountId#'),
-                    #arguments.propsJson#
+                    #arguments.propsJson#,
+                    #arguments.optionsJson#
                 );
             "
         };
diff --git a/coldspa/vite/clients/react-client.js b/coldspa/vite/clients/react-client.js
index 53f4006..f51c7d1 100644
--- a/coldspa/vite/clients/react-client.js
+++ b/coldspa/vite/clients/react-client.js
@@ -1,11 +1,14 @@
 // Coldspa React client entry. Bundled by Vite via the coldspa plugin.
 // __COLDSPA_GLOB__ is replaced at build time by the plugin's transform hook.
+//
+// `options.strategy === 'client'` -> createRoot   (fresh client render)
+// otherwise                        -> hydrateRoot (hydrates SSR markup)
 import React from 'react';
-import { createRoot } from 'react-dom/client';
+import { createRoot, hydrateRoot } from 'react-dom/client';
 
 const components = import.meta.glob('__COLDSPA_GLOB__');
 
-export async function mount(componentPath, el, props) {
+export async function mount(componentPath, el, props, options) {
     if (!el) return;
     const loader = components[componentPath];
     if (!loader) {
@@ -16,5 +19,10 @@ export async function mount(componentPath, el, props) {
         return;
     }
     const mod = await loader();
-    createRoot(el).render(React.createElement(mod.default, props));
+    const node = React.createElement(mod.default, props);
+    if (options && options.strategy === 'client') {
+        createRoot(el).render(node);
+    } else {
+        hydrateRoot(el, node);
+    }
 }
diff --git a/coldspa/vite/clients/vue-client.js b/coldspa/vite/clients/vue-client.js
index 432e93a..f794dd4 100644
--- a/coldspa/vite/clients/vue-client.js
+++ b/coldspa/vite/clients/vue-client.js
@@ -1,13 +1,13 @@
 // Coldspa Vue client entry. Bundled by Vite via the coldspa plugin.
 // __COLDSPA_GLOB__ is replaced at build time by the plugin's transform hook.
 //
-// Uses createSSRApp so .mount(el) HYDRATES if `el` already contains
-// server-rendered HTML, or mounts fresh if the SSR sidecar wasn't available.
-import { createSSRApp } from 'vue';
+// `options.strategy === 'client'` -> createApp    (fresh client render)
+// otherwise                        -> createSSRApp (hydrates SSR markup)
+import { createApp, createSSRApp } from 'vue';
 
 const components = import.meta.glob('__COLDSPA_GLOB__');
 
-export async function mount(componentPath, el, props) {
+export async function mount(componentPath, el, props, options) {
     if (!el) return;
     const loader = components[componentPath];
     if (!loader) {
@@ -18,5 +18,6 @@ export async function mount(componentPath, el, props) {
         return;
     }
     const mod = await loader();
-    createSSRApp(mod.default, props).mount(el);
+    const factory = options && options.strategy === 'client' ? createApp : createSSRApp;
+    factory(mod.default, props).mount(el);
 }
-- 
2.51.2