@brightsideoy/kama 1.0.0-alpha.2 → 1.0.0-alpha.21

package/templates/astro-starter/src/middleware.ts

@@ -84,8 +84,25 @@ export const onRequest = defineMiddleware(async (context, next) => {
         return new Response("Not Found", { status: 404 });
     }
 
-    // 🎯 0B. DIRECT MEDIA PROXY VIA SERVICE BINDING
+    // 🎯 0B. DIRECT MEDIA PROXY VIA SERVICE BINDING WITH SURGICAL WORKER CACHING
     if (pathname.startsWith("/media/")) {
+        const cache = typeof caches !== "undefined" && caches.default ? caches.default : null;
+        // Construct a clean cache key ignoring session headers
+        const cacheKey = new Request(context.url.toString(), { method: "GET" });
+
+        // 1. Check surgical Worker Edge Cache for pre-encoded media (15ms HIT)
+        if (!isDev && cache) {
+            try {
+                const cachedResponse = await cache.match(cacheKey);
+                if (cachedResponse) {
+                    return cachedResponse;
+                }
+            } catch (e) {
+                // Fall back to fetch if cache read fails
+            }
+        }
+
+        // 2. Cold Fetch: Pass to CMS worker for AVIF transformation
         const cmsWorker = workerEnv?.CMS_WORKER;
         const envApiUrl = import.meta.env?.PUBLIC_API_URL;
         const workerApiUrl = workerEnv?.PUBLIC_API_URL;
@@ -93,12 +110,9 @@ export const onRequest = defineMiddleware(async (context, next) => {
         const cleanApiUrl = baseApiUrl.endsWith("/") ? baseApiUrl.slice(0, -1) : baseApiUrl;
 
         const mediaUrl = `${cleanApiUrl}${pathname}${context.url.search}`;
-        const mediaReq = new Request(mediaUrl, {
-            headers: context.request.headers
-        });
+        const mediaReq = new Request(mediaUrl, { headers: context.request.headers });
 
         let mediaResponse: Response;
-
         if (cmsWorker && typeof cmsWorker.fetch === "function") {
             mediaResponse = await cmsWorker.fetch(mediaReq);
         } else {
@@ -107,17 +121,27 @@ export const onRequest = defineMiddleware(async (context, next) => {
 
         const newHeaders = new Headers(mediaResponse.headers);
 
-        // 🎯 DEV FIX: Only apply 1-year cache on media in Production
         if (!isDev) {
             newHeaders.set("Cache-Control", "public, max-age=31536000, s-maxage=31536000, immutable");
         }
         newHeaders.set("Access-Control-Allow-Origin", "*");
 
-        return new Response(mediaResponse.body, {
+        const finalResponse = new Response(mediaResponse.body, {
             status: mediaResponse.status,
             statusText: mediaResponse.statusText,
             headers: newHeaders
         });
+
+        // 3. Store ONLY successful image transformations in Worker Edge Cache
+        if (!isDev && cache && mediaResponse.status === 200) {
+            if (cfContext && typeof cfContext.waitUntil === 'function') {
+                cfContext.waitUntil(cache.put(cacheKey, finalResponse.clone()));
+            } else {
+                cache.put(cacheKey, finalResponse.clone()).catch(() => { });
+            }
+        }
+
+        return finalResponse;
     }
 
     // 🎯 0C. DIRECT EDGE INTERCEPT FOR CACHE PURGE ENDPOINT
@@ -130,7 +154,7 @@ export const onRequest = defineMiddleware(async (context, next) => {
         }
 
         const authHeader = context.request.headers.get("Authorization");
-        const expectedToken = workerEnv.CLOUDFLARE_API_TOKEN;
+        const expectedToken = workerEnv.FRONTEND_API_SECRET || workerEnv.CLOUDFLARE_API_TOKEN;
 
         if (!expectedToken || authHeader !== `Bearer ${expectedToken}`) {
             return new Response(JSON.stringify({ error: "Unauthorized Token Mismatch" }), {
@@ -144,11 +168,21 @@ export const onRequest = defineMiddleware(async (context, next) => {
             const cache = typeof caches !== "undefined" && caches.default ? caches.default : null;
             const origin = context.url.origin;
 
+            if (body.purge_everything && !HTML_CACHE) {
+                return new Response(JSON.stringify({ success: false, error: "HTML_CACHE binding is unavailable" }), {
+                    status: 503,
+                    headers: { "Content-Type": "application/json" },
+                });
+            }
+
             // A. Purge Workers Caching Layer (Astro cfContext)
             if (typeof cfContext?.cache?.purge === 'function') {
                 try {
-                    await cfContext.cache.purge({ purgeEverything: true });
-                    console.log("✅ New Cloudflare Workers Cache Engine Purged");
+                    // 🎯 FIX: Only execute global purge if the CMS explicitly requested it!
+                    if (body.purge_everything) {
+                        await cfContext.cache.purge({ purgeEverything: true });
+                        console.log("✅ New Cloudflare Workers Cache Engine Purged (Global)");
+                    }
                 } catch (e) {
                     console.error("❌ Failed to purge new Workers Cache Engine", e);
                 }
@@ -161,30 +195,34 @@ export const onRequest = defineMiddleware(async (context, next) => {
 
                     if (body.purge_everything) {
                         // 🎯 GLOBAL PURGE: Bumping site_version instantly invalidates ALL KV pages globally!
+                        try {
+                            await HTML_CACHE.put("site_version", now);
+                            await HTML_CACHE.put("v:/", now);
+                            console.log(`✅ [Version Tagging] Global site_version updated to ${now}`);
+                        } catch (kvLimitErr: any) {
+                            console.error(`[KV Error] Global version bump failed: ${kvLimitErr.message}`);
+                            return new Response(JSON.stringify({ success: false, error: "Failed to invalidate HTML KV cache" }), {
+                                status: 503,
+                                headers: { "Content-Type": "application/json" },
+                            });
+                        }
+                    } else if (Array.isArray(body.urls) && body.urls.length > 0) {
+                        // Shared fragments and cross-page content depend on the site version too.
                         await HTML_CACHE.put("site_version", now);
 
-                        // 🎯 FIX: Force clear alias keys during global purge
-                        await HTML_CACHE.put("v:/", now);
-                        await HTML_CACHE.put("v:/index", now);
-
-                        console.log(`✅ [Version Tagging] Global site_version updated to ${now}`);
-                    } else if (Array.isArray(body.urls) && body.urls.length > 0) {
-                        // 🎯 SURGICAL PURGE: Parallel execution for page version bumps
-                        const purgeTasks = [];
-                        for (const targetUrl of body.urls) {
+                        // 🎯 SURGICAL PURGE: Parallel execution for page version bumps safely wrapped for quota
+                        const purgeTasks = body.urls.map(async (targetUrl: string) => {
                             const urlPath = new URL(targetUrl).pathname;
                             const cleanPath = urlPath.replace(/\/$/, "") || "/";
-
-                            purgeTasks.push(HTML_CACHE.put(`v:${cleanPath}`, now));
-
-                            // 🎯 FIX: Always sync / and /index aliases together
-                            if (cleanPath === "/" || cleanPath === "/index") {
-                                purgeTasks.push(HTML_CACHE.put("v:/", now));
-                                purgeTasks.push(HTML_CACHE.put("v:/index", now));
+                            try {
+                                await HTML_CACHE.put(`v:${cleanPath}`, now);
+                            } catch (kvLimitErr: any) {
+                                console.warn(`[KV Warning] Skipped version tag for ${cleanPath}: ${kvLimitErr.message}`);
                             }
-                        }
+                        });
                         await Promise.all(purgeTasks);
                         console.log(`✅ [Version Tagging] Updated versions for ${body.urls.length} URLs`);
+                        // CMS CacheManager will automatically send the X-Cache-Warmer requests now!
                     }
                 } catch (kvErr) {
                     console.error("❌ KV Version Tagging Error:", kvErr);
@@ -196,11 +234,8 @@ export const onRequest = defineMiddleware(async (context, next) => {
                 if (cache) {
                     const rootUrls = [
                         origin,
-                        `${origin}/`,
-                        `${origin}/index`,
-                        `${origin}/index/`
+                        `${origin}/`
                     ];
-
                     for (const url of rootUrls) {
                         await cache.delete(new Request(url));
                     }
@@ -215,7 +250,7 @@ export const onRequest = defineMiddleware(async (context, next) => {
                 });
             }
 
-            // D. Surgical Legacy Worker Cache Purge (For Updated Pages)
+            // D. Surgical Legacy Worker Cache Purge
             if (Array.isArray(body.urls) && body.urls.length > 0) {
                 const results = [];
 
@@ -223,17 +258,7 @@ export const onRequest = defineMiddleware(async (context, next) => {
                     const cleanUrl = targetUrl.split('?')[0];
                     const urlNoSlash = cleanUrl.replace(/\/$/, "");
                     const urlWithSlash = urlNoSlash + "/";
-
                     const pathsToClear = [urlNoSlash, urlWithSlash];
-                    const urlPath = new URL(targetUrl).pathname;
-
-                    // 🎯 FIX: Clear legacy cache alias if it's the home page
-                    if (urlPath === "/" || urlPath === "/index") {
-                        pathsToClear.push(`${origin}/`);
-                        pathsToClear.push(`${origin}/index`);
-                        pathsToClear.push(`${origin}/index/`);
-                        pathsToClear.push(`${origin}`);
-                    }
 
                     let purged = false;
                     if (cache) {
@@ -267,37 +292,27 @@ export const onRequest = defineMiddleware(async (context, next) => {
                     let purgedKv = false;
 
                     if (HTML_CACHE) {
-                        const [siteVer, pageVer] = await Promise.all([
-                            HTML_CACHE.get("site_version"),
-                            HTML_CACHE.get(`v:${cleanPath}`)
-                        ]);
-
-                        if (siteVer || pageVer) {
-                            const activeCacheKey = `${cleanPath}:v:${siteVer || "1"}:${pageVer || "1"}`;
-                            await HTML_CACHE.delete(activeCacheKey);
-                            purgedKv = true;
-                        }
-
-                        await HTML_CACHE.delete(`v:${cleanPath}`);
-
-                        // 🎯 FIX: Delete aliases from KV if applicable
-                        if (cleanPath === "/" || cleanPath === "/index") {
-                            await HTML_CACHE.delete("v:/");
-                            await HTML_CACHE.delete("v:/index");
+                        try {
+                            const [siteVer, pageVer] = await Promise.all([
+                                HTML_CACHE.get("site_version"),
+                                HTML_CACHE.get(`v:${cleanPath}`)
+                            ]);
+
+                            if (siteVer || pageVer) {
+                                const activeCacheKey = `${cleanPath}:v:${siteVer || "1"}:${pageVer || "1"}`;
+                                await HTML_CACHE.delete(activeCacheKey);
+                                purgedKv = true;
+                            }
+                            await HTML_CACHE.delete(`v:${cleanPath}`);
+                        } catch (kvLimitErr: any) {
+                            console.warn(`[KV Warning] Skipped deletion for ${cleanPath}: ${kvLimitErr.message}`);
                         }
                     }
 
                     const cleanUrl = targetUrl.split('?')[0];
                     const urlNoSlash = cleanUrl.replace(/\/$/, "");
                     const urlWithSlash = urlNoSlash + "/";
-
                     const pathsToClear = [urlNoSlash, urlWithSlash];
-                    if (urlPath === "/" || urlPath === "/index") {
-                        pathsToClear.push(`${origin}/`);
-                        pathsToClear.push(`${origin}/index`);
-                        pathsToClear.push(`${origin}/index/`);
-                        pathsToClear.push(`${origin}`);
-                    }
 
                     let purgedLegacy = false;
                     if (cache) {
@@ -337,32 +352,60 @@ export const onRequest = defineMiddleware(async (context, next) => {
 
     // 🎯 1. KV STATIC "FILE" CACHE READ WITH VERSION TAGGING
     const isWarmer = context.request.headers.get("X-Cache-Warmer") === "true";
-    const isHtmlPage = !pathname.includes('.') && !pathname.startsWith('/api/');
-    const cleanLookupPath = pathname.replace(/\/$/, "") || "/";
+
+    // 🎯 ARCHITECTURE FIX: Allow HTML partials to be edge-cached alongside regular HTML
+    const isHtmlPage = !pathname.includes('.') && (!pathname.startsWith('/api/') || pathname.startsWith('/api/partials/'));
+
+    // 🎯 ARCHITECTURE FIX: Include query string for partials so offset=6 and offset=12 have distinct cache keys
+    const cleanLookupPath = pathname === "/index" || pathname === "/index/"
+        ? "/"
+        : (pathname.replace(/\/$/, "") || "/") + (pathname.startsWith('/api/partials/') ? context.url.search : "");
 
     let activeCacheKey = cleanLookupPath;
 
-    // 🎯 FIX: Bypass KV Read in local dev OR if we are time traveling (previewing drafts/snapshots)
-    if (!isDev && isHtmlPage && HTML_CACHE && !isWarmer && !isTimeTraveling) {
+    // 🎯 FIX: Retrieve the activeCacheKey versions even if it's a warmer request, so it doesn't overwrite them!
+    if (!isDev && isHtmlPage && HTML_CACHE && !isTimeTraveling) {
         try {
+            // 🎯 Partials inherit the global site_version so they automatically purge when the CMS publishes
+            const pageVersionKey = pathname.startsWith('/api/partials/') ? "site_version" : `v:${pathname.replace(/\/$/, "") || "/"}`;
+
             const [siteVer, pageVer] = await Promise.all([
                 HTML_CACHE.get("site_version"),
-                HTML_CACHE.get(`v:${cleanLookupPath}`)
+                HTML_CACHE.get(pageVersionKey)
             ]);
 
+            // 🎯 Combine versions deterministically
             activeCacheKey = `${cleanLookupPath}:v:${siteVer || "1"}:${pageVer || "1"}`;
 
-            const cachedHtml = await HTML_CACHE.get(activeCacheKey);
-            if (cachedHtml) {
-                return new Response(cachedHtml, {
-                    status: 200,
-                    headers: {
-                        "Content-Type": "text/html; charset=utf-8",
-                        "X-Cache-Status": "HIT-KV-STATICFILE",
-                        "X-Cache-Key": activeCacheKey,
-                        "Cache-Control": "no-store, no-cache, must-revalidate, proxy-revalidate"
+            // 🎯 Only serve cached HTML if it is NOT a warmer request
+            if (!isWarmer) {
+                const cachedData = await HTML_CACHE.get(activeCacheKey);
+                if (cachedData) {
+                    let finalHtml = cachedData;
+
+                    try {
+                        if (cachedData.startsWith("{")) {
+                            const parsed = JSON.parse(cachedData);
+                            if (parsed.html) {
+                                finalHtml = parsed.html;
+                            }
+                        }
+                    } catch (jsonErr) {
+                        // Fallback to raw HTML
                     }
-                });
+
+                    return new Response(finalHtml, {
+                        status: 200,
+                        headers: {
+                            "Content-Type": "text/html; charset=utf-8",
+                            "X-Cache-Status": "HIT-KV-STATICFILE",
+                            "X-Cache-Key": activeCacheKey,
+                            // Prevent Cloudflare Edge from locking stale HTML in RAM.
+                            // Force Edge to revalidate with Worker logic while keeping browser cache fresh.
+                            "Cache-Control": "public, max-age=0, must-revalidate"
+                        }
+                    });
+                }
             }
         } catch (e) {
             console.warn("[Middleware] KV lookup bypass:", e);
@@ -373,36 +416,54 @@ export const onRequest = defineMiddleware(async (context, next) => {
     const response = await next();
 
     // 🎯 2. KV STATIC "FILE" CACHE WRITE (Save HTML under active Version Key)
-    // 🎯 FIX: Bypass KV Write in local dev OR if we are time traveling (never save drafts to public cache)
     if (
         !isDev &&
-        isHtmlPage &&
-        HTML_CACHE &&
+        isHtmlPage && HTML_CACHE &&
         !isTimeTraveling &&
         response.status === 200 &&
         response.headers.get("content-type")?.includes("text/html")
     ) {
         const htmlText = await response.clone().text();
 
-        const writeTask = (async () => {
-            if (activeCacheKey === cleanLookupPath || isWarmer) {
-                const forcedVersion = Date.now().toString();
+        // Extract the TTL injected by Astro SSR
+        const kvTtlHeader = response.headers.get("X-KV-Expiration");
+        const kvTtl = kvTtlHeader ? parseInt(kvTtlHeader, 10) : undefined;
 
-                await HTML_CACHE.put(`v:${cleanLookupPath}`, forcedVersion);
+        // Clean up the internal header so it doesn't leak to the public browser
+        response.headers.delete("X-KV-Expiration");
 
-                // 🎯 FIX: Sync both aliases when saving the homepage
-                if (cleanLookupPath === "/" || cleanLookupPath === "/index") {
-                    await HTML_CACHE.put(`v:/`, forcedVersion);
-                    await HTML_CACHE.put(`v:/index`, forcedVersion);
+        const writeTask = (async () => {
+            // 🎯 FIX: Removed `|| isWarmer` here so warmer requests safely write to the existing activeCacheKey
+            if (activeCacheKey === cleanLookupPath) {
+                const forcedVersion = Date.now().toString();
+                try {
+                    // 🎯 FIX: Do NOT overwrite global site_version from a frontend partial cache miss
+                    if (!pathname.startsWith('/api/partials/')) {
+                        await HTML_CACHE.put(`v:${pathname.replace(/\/$/, "") || "/"}`, forcedVersion);
+                    }
+                    const siteVer = await HTML_CACHE.get("site_version") || "1";
+                    const pageVer = pathname.startsWith('/api/partials/') ? siteVer : forcedVersion;
+                    activeCacheKey = `${cleanLookupPath}:v:${siteVer}:${pageVer}`;
+                } catch (kvLimitErr: any) {
+                    console.warn(`[KV Warning] Skipped prewarm version bump: ${kvLimitErr.message}`);
                 }
+            }
 
-                const siteVer = await HTML_CACHE.get("site_version") || "1";
+            // Save TTL alongside HTML so CDN can properly cache reads
+            const storedTtl = kvTtl !== undefined ? Math.max(60, kvTtl) : 31536000;
+            const payload = JSON.stringify({ html: htmlText, ttl: storedTtl });
 
-                activeCacheKey = `${cleanLookupPath}:v:${siteVer}:${forcedVersion}`;
+            try {
+                if (kvTtl !== undefined) {
+                    await HTML_CACHE.put(activeCacheKey, payload, { expirationTtl: storedTtl });
+                    console.log(`✅ [Middleware] Saved HTML to KV under key: ${activeCacheKey} (Expires in ${storedTtl}s)`);
+                } else {
+                    await HTML_CACHE.put(activeCacheKey, payload);
+                    console.log(`✅ [Middleware] Saved HTML to KV under key: ${activeCacheKey} (Infinite TTL)`);
+                }
+            } catch (kvLimitErr: any) {
+                console.warn(`[KV Warning] Skipped HTML cache save (Quota limit exceeded): ${kvLimitErr.message}`);
             }
-
-            await HTML_CACHE.put(activeCacheKey, htmlText);
-            console.log(`✅ [Middleware] Saved HTML to KV under key: ${activeCacheKey}`);
         })();
 
         if (cfContext && typeof cfContext.waitUntil === 'function') {
@@ -428,7 +489,6 @@ export const onRequest = defineMiddleware(async (context, next) => {
     }
 
     // 🎯 4. STATIC ASSET CACHING FOR COMPRESSED BUNDLES / ASSETS
-    // 🎯 DEV FIX: Do not apply max-age=31536000 locally to prevent breaking Vite HMR
     if (!isDev) {
         if (
             pathname.startsWith("/_image") ||
@@ -465,8 +525,6 @@ export const onRequest = defineMiddleware(async (context, next) => {
         } else {
             // Production headers
             response.headers.set("Cross-Origin-Opener-Policy", "same-origin-allow-popups");
-            // 🎯 FIX: Remove X-Frame-Options entirely since it breaks cross-subdomain framing.
-            // Rely completely on CSP frame-ancestors to whitelist ALL kamaengine subdomains + your env URL.
             response.headers.set(
                 "Content-Security-Policy",
                 `default-src 'self' https: data: 'unsafe-inline' 'unsafe-eval'; img-src 'self' https: data: blob:; connect-src 'self' https:; frame-ancestors 'self' https://*.kamaengine.com https://kama.kamaengine.com ${cmsOrigin};`

package/templates/astro-starter/src/pages/[...slug].astro

@@ -59,6 +59,10 @@ const envApiUrl = import.meta.env.PUBLIC_API_URL;
 const workerApiUrl = safeEnv.PUBLIC_API_URL;
 const baseApiUrl = String(envApiUrl || workerApiUrl || "http://localhost:8787");
 
+// 🎯 Safely extract the secret across both environments
+const frontendApiSecret =
+  import.meta.env.FRONTEND_API_SECRET || safeEnv.FRONTEND_API_SECRET;
+
 const cleanApiUrl = baseApiUrl.endsWith("/")
   ? baseApiUrl.slice(0, -1)
   : baseApiUrl;
@@ -83,10 +87,13 @@ const customFetch = async (input: RequestInfo | URL, init?: RequestInit) => {
     ...init?.headers,
     "Cache-Control": "no-cache, no-store, must-revalidate",
     Pragma: "no-cache",
-    // 🎯 Direct Service Bindings require explicit header flags to bypass CMS KV cache!
     "X-Bypass-Cache": "true",
   };
 
+  if (frontendApiSecret) {
+    reqHeaders["Authorization"] = `Bearer ${frontendApiSecret}`;
+  }
+
   const fetchOpts: RequestInit = {
     ...init,
     headers: reqHeaders,
@@ -107,7 +114,9 @@ const treeId = getTreeId();
 const rawSlug = Array.isArray(slug) ? slug.join("/") : slugStr;
 const pathParts = rawSlug.split("/").filter(part => part.trim() !== "");
 const requestedSlug = pathParts.join("/");
-const targetSlug = requestedSlug || homeSlug;
+
+// 🎯 ONLY FIX NEEDED HERE: Pass '/' if empty so home route resolves, otherwise requestedSlug
+const targetSlug = requestedSlug || "/";
 
 let pageData: NodeResponse | null = null;
 let navTree: TreeNode[] = [];
@@ -129,7 +138,7 @@ try {
   ]);
 
   navTree = treeResult || [];
-  pageData = nodeResult;
+  pageData = nodeResult as NodeResponse | null;
 } catch (err) {
   console.error("❌ [SSR Error] Failed concurrent fetch execution:", err);
 }
@@ -141,12 +150,35 @@ if (!pageData || !pageData.node) {
 const node = pageData.node;
 const content = pageData.content || {};
 
+// 🎯 SMART EDGE CACHING LOGIC (API-Driven TTL)
+let cacheTtl = pageData?.meta?.cacheTtl;
+
+if (cacheTtl === undefined || cacheTtl === null) {
+  cacheTtl = 31536000; // Default: 1 Year (Forever)
+}
+
+cacheTtl = Math.max(60, cacheTtl);
+
+if (isTimeTraveling) {
+  Astro.response.headers.set(
+    "Cache-Control",
+    "no-cache, no-store, must-revalidate",
+  );
+} else {
+  Astro.response.headers.set(
+    "Cache-Control",
+    `public, max-age=0, s-maxage=${cacheTtl}, must-revalidate`,
+  );
+  Astro.response.headers.set("X-KV-Expiration", cacheTtl.toString());
+}
+
 const rootTreeSlug =
   navTree && navTree.length > 0
     ? navTree[0].slug || (navTree[0] as any).key
     : "";
 
 const isHomePage =
+  targetSlug === "/" ||
   targetSlug === homeSlug ||
   (rootTreeSlug && targetSlug === rootTreeSlug) ||
   node?.path === "/" ||
@@ -161,6 +193,44 @@ const hasSidebar = sidebarBlocks.length > 0;
 
 // Detect if this node is a standalone Page Skeleton
 const isSkeleton = node?.nodeType === "page-skeleton";
+
+const hotSwapScript = `
+  if (window !== window.top) {
+    window.addEventListener("message", async event => {
+      if (event.data && event.data.type === "kama-preview-update") {
+        try {
+          const currentScrollY = window.scrollY;
+          const res = await fetch(event.data.url);
+          const newHtml = await res.text();
+          const newDoc = new DOMParser().parseFromString(newHtml, "text/html");
+
+          newDoc.body
+            .querySelectorAll("script, style, link, meta, noscript")
+            .forEach(el => el.remove());
+
+          const preserveTags = ["SCRIPT", "STYLE", "LINK", "META", "NOSCRIPT"];
+
+          Array.from(document.body.children).forEach(child => {
+            if (!preserveTags.includes(child.tagName.toUpperCase())) {
+              child.remove();
+            }
+          });
+
+          const referenceNode = document.body.firstChild;
+          Array.from(newDoc.body.children).forEach(child => {
+            if (!preserveTags.includes(child.tagName.toUpperCase())) {
+              document.body.insertBefore(child.cloneNode(true), referenceNode);
+            }
+          });
+
+          window.scrollTo(0, currentScrollY);
+        } catch (err) {
+          console.error("[KAMA Preview] Failed to hot-swap HTML:", err);
+        }
+      }
+    });
+  }
+`;
 ---
 
 {
@@ -173,6 +243,8 @@ const isSkeleton = node?.nodeType === "page-skeleton";
       isHomePage={isHomePage}
     >
       <BlockRenderer blocks={mainBlocks} contentMap={content} region="main" />
+
+      {isPreview && <script is:inline set:html={hotSwapScript} />}
     </SkeletonLayout>
   ) : (
     <StandardLayout
@@ -232,6 +304,8 @@ const isSkeleton = node?.nodeType === "page-skeleton";
           </aside>
         )}
       </div>
+
+      {isPreview && <script is:inline set:html={hotSwapScript} />}
     </StandardLayout>
   )
 }

package/templates/astro-starter/src/pages/api/load-nodes.ts

@@ -0,0 +1,68 @@
+// src/pages/api/load-nodes.ts
+import type { APIRoute } from "astro";
+
+export const prerender = false; // Required to ensure this runs server-side on Cloudflare
+
+export const GET: APIRoute = async ({ request, locals }) => {
+    const url = new URL(request.url);
+    const searchParams = url.searchParams;
+
+    // 1. Get Environment Variables securely via middleware
+    const cfEnv = (locals as any).safeEnv || {};
+
+    const cmsWorker = cfEnv.CMS_WORKER;
+    const apiUrl = cfEnv.PUBLIC_API_URL || import.meta.env.PUBLIC_API_URL || "http://localhost:8787";
+    const secret = cfEnv.FRONTEND_API_SECRET || import.meta.env.FRONTEND_API_SECRET;
+
+    if (!secret) {
+        console.error("🚨 [Load Nodes Proxy] Critical Error: FRONTEND_API_SECRET is missing from the environment!");
+    }
+
+    // 2. Construct the actual backend URL
+    const cleanApiUrl = apiUrl.replace(/\/$/, "");
+    const backendUrl = `${cleanApiUrl}/api/v1/nodes?${searchParams.toString()}`;
+
+    try {
+        // 3. Prepare the secure headers
+        const reqHeaders: Record<string, string> = {
+            "Accept": "application/json",
+        };
+
+        if (secret) {
+            reqHeaders["Authorization"] = `Bearer ${secret}`;
+        }
+
+        const backendReq = new Request(backendUrl, {
+            method: "GET",
+            headers: reqHeaders
+        });
+
+        // 4. Fetch from the CMS securely (Bypass Cloudflare Access via Service Binding)
+        let response;
+        if (cmsWorker && typeof cmsWorker.fetch === "function") {
+            response = await cmsWorker.fetch(backendReq);
+        } else {
+            response = await fetch(backendReq);
+        }
+
+        if (!response.ok) {
+            console.error(`[Load Nodes Proxy] Backend rejected request with status: ${response.status}`);
+            return new Response(JSON.stringify({ error: "Failed to fetch nodes" }), { status: response.status });
+        }
+
+        const data = await response.json();
+
+        // 5. Return to the browser
+        return new Response(JSON.stringify(data), {
+            status: 200,
+            headers: {
+                "Content-Type": "application/json",
+                // 🎯 ARCHITECTURE FIX: Cache at the Cloudflare Edge for 60 seconds to eliminate redundant DB queries.
+                "Cache-Control": "public, max-age=0, s-maxage=60, stale-while-revalidate=120"
+            }
+        });
+    } catch (err) {
+        console.error("[Load Nodes Proxy] Failed to load nodes:", err);
+        return new Response(JSON.stringify({ error: "Internal Server Error" }), { status: 500 });
+    }
+};