@brightsideoy/kama 1.0.0-alpha.13 → 1.0.0-alpha.17

package/dist/schema-compiler.js

@@ -30,7 +30,7 @@ async function f() {
 	if (n(f)) l = (await import(t(f).href)).compileDefinitions;
 	else if (n(p)) l = (await import(t(p).href)).compileDefinitions;
 	else try {
-		l = (await import("./dist-kIJlDMvm.js")).compileDefinitions;
+		l = (await import("./dist-BGv2bzzF.js")).compileDefinitions;
 	} catch (e) {
 		console.error("\x1B[31m  ✖\x1B[0m \x1B[31mCould not resolve Kama Schema Engine:\x1B[0m", e), process.exit(1);
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brightsideoy/kama",
-  "version": "1.0.0-alpha.13",
+  "version": "1.0.0-alpha.17",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/schema.sql

@@ -92,6 +92,8 @@ CREATE TABLE IF NOT EXISTS "content_nodes" (
     language TEXT,
     isHidden INTEGER NOT NULL DEFAULT 0,
     status TEXT DEFAULT 'draft',
+    startShowingAt TEXT,
+    stopShowingAt TEXT,
     hasUnpublishedChanges INTEGER DEFAULT 0,
     disabledRegionsJson TEXT DEFAULT '{}',
     dataJson TEXT,
@@ -263,3 +265,4 @@ CREATE INDEX IF NOT EXISTS idx_node_relations_source ON node_relations(sourceNod
 CREATE INDEX IF NOT EXISTS idx_node_relations_target ON node_relations(targetNodeId);
 CREATE INDEX IF NOT EXISTS idx_node_routes_lookup ON node_routes(path, channelId);
 CREATE INDEX IF NOT EXISTS idx_node_routes_node ON node_routes(nodeId);
+CREATE INDEX IF NOT EXISTS idx_content_nodes_public_feed ON content_nodes(contentType, isHidden, status, startShowingAt, stopShowingAt, updatedAt DESC);

package/templates/astro-starter/src/components/blocks/NodeList.astro

@@ -1,5 +1,6 @@
 ---
 // src/components/blocks/NodeList.astro
+import KamaImage from "@/components/ui/KamaImage.astro";
 
 interface Props {
   data: Record<string, any>;
@@ -21,10 +22,13 @@ const listTitle = data.listTitle || "";
         {items.map((item: any) => (
           <article class="node-card">
             <a href={`/${item.slug}`} class="node-card-link">
+              {/* 🎯 ARCHITECTURAL FIX: Use KamaImage for initial load optimization */}
               {item.image ? (
-                <img
-                  src={item.image.url}
-                  alt={item.image.alt || item.title}
+                <KamaImage
+                  image={item.image}
+                  sizes="(max-width: 639px) 100vw, (max-width: 1023px) 50vw, 33vw"
+                  desktopWidths={[320, 640, 768, 1024]}
+                  idealWidth={429}
                   loading="lazy"
                 />
               ) : (
@@ -66,6 +70,7 @@ const listTitle = data.listTitle || "";
     )
   }
 </div>
+
 <style is:global>
   .node-list-wrapper {
     margin: 2rem 0;
@@ -124,14 +129,18 @@ const listTitle = data.listTitle || "";
     height: 100%;
   }
 
+  /* 🎯 Because of is:global, this styling will automatically apply to <KamaImage> outputs! */
   .node-card img,
   .node-card .image-placeholder {
     width: 100%;
-    aspect-ratio: 16 / 9;
+    height: auto; /* 🎯 FIX: Allows tall images to display their natural height */
     object-fit: cover;
     background: #f1f5f9;
   }
 
+  .node-card .image-placeholder {
+    aspect-ratio: 16 / 9; /* Keep the placeholder a rectangle if there is no image at all */
+  }
   .node-card-content {
     padding: 1.25rem;
     display: flex;
@@ -186,10 +195,12 @@ const listTitle = data.listTitle || "";
 </style>
 
 <script>
-  document.addEventListener("DOMContentLoaded", () => {
-    const buttons = document.querySelectorAll(".load-more-btn");
+  function initLoadMoreButtons() {
+    const buttons = document.querySelectorAll(".load-more-btn:not(.is-bound)");
 
     buttons.forEach(btn => {
+      btn.classList.add("is-bound");
+
       btn.addEventListener("click", async e => {
         const targetBtn = e.currentTarget as HTMLButtonElement;
         const urlString = targetBtn.getAttribute("data-url");
@@ -200,69 +211,47 @@ const listTitle = data.listTitle || "";
         const grid = document.getElementById(targetId);
         if (!grid) return;
 
-        // Change the original backend URL path to our local Astro proxy path
         const urlObj = new URL(urlString, window.location.origin);
-        const proxyUrl = `/api/load-nodes${urlObj.search}`;
+        // 🎯 ARCHITECTURAL FIX: Route to the new HTML Partial Endpoint
+        const proxyUrl = `/api/partials/node-cards${urlObj.search}`;
 
-        const originalText = targetBtn.textContent;
         targetBtn.textContent = "Loading...";
         targetBtn.disabled = true;
 
         try {
           const res = await fetch(proxyUrl);
-          const data = await res.json();
-
-          if (data.items && data.items.length > 0) {
-            // Append each new item to the grid
-            data.items.forEach((item: any) => {
-              const dateStr = item.createdAt
-                ? new Date(item.createdAt).toLocaleDateString("en-GB", {
-                    day: "numeric",
-                    month: "short",
-                    year: "numeric",
-                  })
-                : "";
-
-              const imgHtml = item.image
-                ? `<img src="${item.image.url}" alt="${item.image.alt || item.title}" loading="lazy" />`
-                : `<div class="image-placeholder"></div>`;
-
-              const articleHtml = `
-                <article class="node-card">
-                  <a href="/${item.slug}" class="node-card-link">
-                    ${imgHtml}
-                    <div class="node-card-content">
-                      <h3 class="node-card-title">${item.title}</h3>
-                      ${dateStr ? `<time datetime="${item.createdAt}" class="node-card-date">${dateStr}</time>` : ""}
-                      ${item.excerpt ? `<p class="node-card-excerpt">${item.excerpt}</p>` : ""}
-                    </div>
-                  </a>
-                </article>
-              `;
-              grid.insertAdjacentHTML("beforeend", articleHtml);
-            });
-
-            // If we received a full batch, there might be more. Update the offset.
-            if (data.items.length === data.limit) {
-              const currentOffset = parseInt(
-                urlObj.searchParams.get("offset") || "0",
-                10,
-              );
-              urlObj.searchParams.set(
-                "offset",
-                (currentOffset + data.limit).toString(),
-              );
-              targetBtn.setAttribute(
-                "data-url",
-                urlObj.pathname + urlObj.search,
-              );
-              targetBtn.textContent = "Load More";
-              targetBtn.disabled = false;
-            } else {
-              // Hide the button container if we've reached the end
-              if (targetBtn.parentElement)
-                targetBtn.parentElement.style.display = "none";
-            }
+
+          if (!res.ok) {
+            throw new Error(`HTTP error! status: ${res.status}`);
+          }
+
+          // 1. Read metadata from headers sent by our partial endpoint
+          const rawCountStr = res.headers.get("X-Consumed-Rows");
+          const limitStr = res.headers.get("X-Limit");
+          const consumedRows = parseInt(rawCountStr || "0", 10);
+          const limit = parseInt(limitStr || "12", 10);
+
+          // 2. Extract and render the raw HTML
+          const htmlSnippet = await res.text();
+
+          if (htmlSnippet.trim().length > 0) {
+            grid.insertAdjacentHTML("beforeend", htmlSnippet);
+          }
+
+          // 3. Handle Pagination
+          if (consumedRows >= limit && limit > 0) {
+            const currentOffset = parseInt(
+              urlObj.searchParams.get("offset") || "0",
+              10,
+            );
+            urlObj.searchParams.set(
+              "offset",
+              (currentOffset + limit).toString(),
+            );
+
+            targetBtn.setAttribute("data-url", urlObj.pathname + urlObj.search);
+            targetBtn.textContent = "Load More";
+            targetBtn.disabled = false;
           } else {
             if (targetBtn.parentElement)
               targetBtn.parentElement.style.display = "none";
@@ -274,5 +263,12 @@ const listTitle = data.listTitle || "";
         }
       });
     });
-  });
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initLoadMoreButtons);
+  } else {
+    initLoadMoreButtons();
+  }
+  document.addEventListener("astro:page-load", initLoadMoreButtons);
 </script>

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

@@ -84,7 +84,6 @@ 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;
@@ -155,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" }), {
@@ -169,6 +168,13 @@ 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 {
@@ -194,9 +200,16 @@ export const onRequest = defineMiddleware(async (context, next) => {
                             await HTML_CACHE.put("v:/", now);
                             console.log(`✅ [Version Tagging] Global site_version updated to ${now}`);
                         } catch (kvLimitErr: any) {
-                            console.warn(`[KV Warning] Skipped global version bump: ${kvLimitErr.message}`);
+                            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);
+
                         // 🎯 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;
@@ -339,50 +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/');
-    // 🎯 The ONLY way we refer to the homepage in KV is "/"
+
+    // 🎯 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.replace(/\/$/, "") || "/") + (pathname.startsWith('/api/partials/') ? context.url.search : "");
 
     let activeCacheKey = cleanLookupPath;
 
-    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 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;
+            // 🎯 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
                     }
-                } 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,
-                        // 🎯 ARCHITECTURE FIX: 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"
-                    }
-                });
+                    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);
@@ -410,18 +433,23 @@ export const onRequest = defineMiddleware(async (context, next) => {
         response.headers.delete("X-KV-Expiration");
 
         const writeTask = (async () => {
-            if (activeCacheKey === cleanLookupPath || isWarmer) {
+            // 🎯 FIX: Removed `|| isWarmer` here so warmer requests safely write to the existing activeCacheKey
+            if (activeCacheKey === cleanLookupPath) {
                 const forcedVersion = Date.now().toString();
                 try {
-                    await HTML_CACHE.put(`v:${cleanLookupPath}`, forcedVersion);
+                    // 🎯 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";
-                    activeCacheKey = `${cleanLookupPath}:v:${siteVer}:${forcedVersion}`;
+                    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}`);
                 }
             }
 
-            // 🎯 Architecture Fix: Save TTL alongside HTML so CDN can properly cache reads
+            // 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 });
 

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

@@ -59,7 +59,7 @@ const envApiUrl = import.meta.env.PUBLIC_API_URL;
 const workerApiUrl = safeEnv.PUBLIC_API_URL;
 const baseApiUrl = String(envApiUrl || workerApiUrl || "http://localhost:8787");
 
-// 🎯 NEW: Safely extract the secret across both environments
+// 🎯 Safely extract the secret across both environments
 const frontendApiSecret =
   import.meta.env.FRONTEND_API_SECRET || safeEnv.FRONTEND_API_SECRET;
 
@@ -87,11 +87,9 @@ 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",
   };
 
-  // 🎯 NEW: Inject the secret securely into every outgoing server request
   if (frontendApiSecret) {
     reqHeaders["Authorization"] = `Bearer ${frontendApiSecret}`;
   }
@@ -116,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[] = [];
@@ -151,14 +151,12 @@ const node = pageData.node;
 const content = pageData.content || {};
 
 // 🎯 SMART EDGE CACHING LOGIC (API-Driven TTL)
-// Rely on the backend API's meta.cacheTtl which calculates the closest publishing event for the node AND its blocks.
 let cacheTtl = pageData?.meta?.cacheTtl;
 
 if (cacheTtl === undefined || cacheTtl === null) {
   cacheTtl = 31536000; // Default: 1 Year (Forever)
 }
 
-// Clamp to Cloudflare's 60-second minimum for KV expirations
 cacheTtl = Math.max(60, cacheTtl);
 
 if (isTimeTraveling) {
@@ -167,12 +165,10 @@ if (isTimeTraveling) {
     "no-cache, no-store, must-revalidate",
   );
 } else {
-  // 🎯 FIX: max-age=0 prevents local browser caching. s-maxage handles Cloudflare CDN!
   Astro.response.headers.set(
     "Cache-Control",
     `public, max-age=0, s-maxage=${cacheTtl}, must-revalidate`,
   );
-  // Tell middleware how long to store in KV
   Astro.response.headers.set("X-KV-Expiration", cacheTtl.toString());
 }
 
@@ -182,6 +178,7 @@ const rootTreeSlug =
     : "";
 
 const isHomePage =
+  targetSlug === "/" ||
   targetSlug === homeSlug ||
   (rootTreeSlug && targetSlug === rootTreeSlug) ||
   node?.path === "/" ||
@@ -197,8 +194,6 @@ const hasSidebar = sidebarBlocks.length > 0;
 // Detect if this node is a standalone Page Skeleton
 const isSkeleton = node?.nodeType === "page-skeleton";
 
-// 🎯 HTML-OVER-THE-WIRE HOT SWAP LOGIC
-// Isolated as a string so we don't violate DRY when injecting into multiple layouts
 const hotSwapScript = `
   if (window !== window.top) {
     window.addEventListener("message", async event => {
@@ -249,7 +244,6 @@ const hotSwapScript = `
     >
       <BlockRenderer blocks={mainBlocks} contentMap={content} region="main" />
 
-      {/* 🎯 FIX: Script injected securely inside the layout ONLY during preview mode */}
       {isPreview && <script is:inline set:html={hotSwapScript} />}
     </SkeletonLayout>
   ) : (
@@ -311,7 +305,6 @@ const hotSwapScript = `
         )}
       </div>
 
-      {/* 🎯 FIX: Script injected securely inside the layout ONLY during preview mode */}
       {isPreview && <script is:inline set:html={hotSwapScript} />}
     </StandardLayout>
   )

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

@@ -1,40 +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
-    const safeEnv = (locals as any).safeEnv || {};
-    const apiUrl = import.meta.env.PUBLIC_API_URL || safeEnv.PUBLIC_API_URL || "http://localhost:8787";
-    const secret = import.meta.env.FRONTEND_API_SECRET || safeEnv.FRONTEND_API_SECRET;
+    // 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 backendUrl = `${apiUrl.replace(/\/$/, "")}/api/v1/nodes?${searchParams.toString()}`;
+    const cleanApiUrl = apiUrl.replace(/\/$/, "");
+    const backendUrl = `${cleanApiUrl}/api/v1/nodes?${searchParams.toString()}`;
 
     try {
-        // 3. Fetch from the CMS securely
-        const response = await fetch(backendUrl, {
-            headers: {
-                "Accept": "application/json",
-                ...(secret ? { "Authorization": `Bearer ${secret}` } : {})
-            }
+        // 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();
 
-        // 4. Return to the browser
+        // 5. Return to the browser
         return new Response(JSON.stringify(data), {
             status: 200,
-            headers: { "Content-Type": "application/json" }
+            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("[Astro Proxy] Failed to load nodes:", err);
+        console.error("[Load Nodes Proxy] Failed to load nodes:", err);
         return new Response(JSON.stringify({ error: "Internal Server Error" }), { status: 500 });
     }
 };

package/templates/astro-starter/src/pages/api/partials/node-cards.astro

@@ -0,0 +1,101 @@
+---
+// src/pages/api/partials/node-cards.astro
+export const partial = true; // Tells Astro not to inject DOCTYPE or <head> tags
+
+import KamaImage from "@/components/ui/KamaImage.astro";
+
+const { request, locals } = Astro;
+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;
+
+// 2. Construct the actual backend URL
+const cleanApiUrl = apiUrl.replace(/\/$/, "");
+const backendUrl = `${cleanApiUrl}/api/v1/nodes?${searchParams.toString()}`;
+
+// 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 securely using Service Binding
+let response;
+if (cmsWorker && typeof cmsWorker.fetch === "function") {
+  response = await cmsWorker.fetch(backendReq);
+} else {
+  response = await fetch(backendReq);
+}
+
+let itemsArray: any[] = [];
+let limit = 12;
+let consumedRows = 0;
+
+if (response.ok) {
+  const data = await response.json();
+  itemsArray = Array.isArray(data)
+    ? data
+    : data.items || data.nodes || data.data || [];
+  limit = data.limit || 12;
+  consumedRows =
+    data.rawCount !== undefined ? data.rawCount : itemsArray.length;
+}
+
+// 5. Send pagination data back to the frontend script via custom HTTP Headers
+Astro.response.headers.set("X-Consumed-Rows", consumedRows.toString());
+Astro.response.headers.set("X-Limit", limit.toString());
+Astro.response.headers.set(
+  "Cache-Control",
+  "public, max-age=0, s-maxage=60, stale-while-revalidate=120",
+);
+---
+
+{
+  itemsArray.map((item: any) => {
+    const dateStr = item.createdAt
+      ? new Date(item.createdAt).toLocaleDateString("en-GB", {
+          day: "numeric",
+          month: "short",
+          year: "numeric",
+        })
+      : "";
+
+    return (
+      <article class="node-card">
+        <a href={`/${item.slug}`} class="node-card-link">
+          {item.image ? (
+            <KamaImage
+              image={item.image}
+              sizes="(max-width: 639px) 100vw, (max-width: 1023px) 50vw, 33vw"
+              desktopWidths={[320, 640, 768, 1024]}
+              idealWidth={429}
+              loading="lazy"
+            />
+          ) : (
+            <div class="image-placeholder" />
+          )}
+          <div class="node-card-content">
+            <h3 class="node-card-title">{item.title}</h3>
+            {dateStr && (
+              <time datetime={item.createdAt} class="node-card-date">
+                {dateStr}
+              </time>
+            )}
+            {item.excerpt && <p class="node-card-excerpt">{item.excerpt}</p>}
+          </div>
+        </a>
+      </article>
+    );
+  })
+}