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

package/templates/astro-starter/src/components/global/Header.astro

@@ -15,7 +15,6 @@ const props = Astro.props as Props;
 const currentPropsNode = props.node || {};
 let rawTree: TreeNode[] = props.tree || [];
 
-// 🎯 Read the safely extracted environment from middleware (Fixes Astro 7 crash)
 const safeEnv = (Astro.locals as any).safeEnv || {};
 const cmsWorker = safeEnv.CMS_WORKER;
 
@@ -41,29 +40,27 @@ const customFetch = (input: RequestInfo | URL, init?: RequestInit) => {
   return fetch(req);
 };
 
-// 🎯 Fetch Global Channel Metadata and Nav Tree in Parallel
-const channelId = getChannelId() || "website";
-const treeId = getTreeId() || "main-nav";
+// 🎯 Resolve Channel ID dynamically from env/lib without hardcoding "website"
+const channelId = getChannelId();
+const treeId = getTreeId();
 
 let channelData: Record<string, any> | null = null;
 
 try {
-  const [fetchedChannel, fetchedTree] = await Promise.all([
-    getChannel(channelId, customFetch),
-    !rawTree || rawTree.length === 0
-      ? getTree(treeId, channelId, customFetch)
-      : Promise.resolve(rawTree),
-  ]);
-
-  channelData = fetchedChannel;
   if (!rawTree || rawTree.length === 0) {
+    const [fetchedChannel, fetchedTree] = await Promise.all([
+      getChannel(channelId, customFetch),
+      getTree(treeId, channelId, customFetch),
+    ]);
+    channelData = fetchedChannel;
     rawTree = fetchedTree || [];
+  } else {
+    channelData = await getChannel(channelId, customFetch);
   }
 } catch (e) {
   console.error("[Header] Failed to load layout data:", e);
 }
 
-// 🎯 1. Resolve Logo Text (Strict waterfall prioritizing explicit strings)
 const rawLogoText = channelData?.logoText;
 const rawSiteTitle = channelData?.siteTitle;
 const rawLabel = channelData?.label;
@@ -82,11 +79,9 @@ if (typeof rawLogoText === "string" && rawLogoText.trim() !== "") {
   logoText = import.meta.env.PUBLIC_SITE_NAME || "KAMA";
 }
 
-// 🎯 2. Extract Raw Logo Asset (Unwraps array wrappers if present)
 const rawLogoAsset = channelData?.logoImage || channelData?.logo;
 const targetLogo = Array.isArray(rawLogoAsset) ? rawLogoAsset[0] : rawLogoAsset;
 
-// 🎯 3. Strict Image Validation Guard (Guarantees non-empty string or populated object)
 const hasValidLogoImage = Boolean(
   targetLogo &&
   ((typeof targetLogo === "string" && targetLogo.trim() !== "") ||
@@ -152,7 +147,6 @@ const hasValidLogoImage = Boolean(
     z-index: 1001;
   }
 
-  /* 🎯 Strict 16px Height Constraint for KamaImage output */
   :global(.logo-image) {
     height: 16px !important;
     max-height: 16px !important;

package/templates/astro-starter/src/components/global/NavigationMenu.astro

@@ -8,25 +8,28 @@ export interface Props {
 
 const { tree = [] } = Astro.props;
 
-// 🎯 Grab the current path directly from Astro's server request
 const currentPath = Astro.url.pathname.replace(/\/$/, "") || "/";
-const homeSlug = String(import.meta.env.PUBLIC_HOME_SLUG || "index").trim();
 
-const homeNode = tree.find(
-  item =>
-    item.slug === homeSlug ||
-    item.slug === "" ||
-    item.path === "/" ||
-    item.path === "",
-);
+// 🎯 FIX: Identify the root node in the tree structure
+const rootNode =
+  tree.find(
+    item =>
+      item.path === "/" ||
+      item.path === "" ||
+      item.slug === "index" ||
+      (item as any).isRoot === true ||
+      (item as any).isRootNode === 1,
+  ) || tree[0];
 
+// 🎯 FIX: If rootNode has children, display those children as top-level menu items.
+// If not, filter out the root node by ID AND path.
 const topLevelNavItems =
-  homeNode?.children && homeNode.children.length > 0
-    ? homeNode.children
+  rootNode?.children && rootNode.children.length > 0
+    ? rootNode.children
     : tree.filter(
         item =>
-          item.slug !== homeSlug &&
-          item.slug !== "" &&
+          item.id !== rootNode?.id &&
+          item.slug !== rootNode?.slug &&
           item.path !== "/" &&
           item.path !== "",
       );
@@ -125,58 +128,66 @@ const isExactActive = (itemPath?: string) => {
   </ul>
 </nav>
 
-<script>
-  // 🎯 Clean, standard event listeners that run when the HTML is parsed
-  document.addEventListener("DOMContentLoaded", () => {
+<script is:inline>
+  const initMobileMenu = () => {
     const toggleBtn = document.getElementById("menu-toggle");
     const navOverlay = document.getElementById("nav-overlay");
 
+    if (!toggleBtn || !navOverlay) return;
+
+    // Remove old listeners by replacing the nodes (prevents duplicate bindings)
+    const newToggleBtn = toggleBtn.cloneNode(true);
+    toggleBtn.parentNode.replaceChild(newToggleBtn, toggleBtn);
+
     const closeMenu = () => {
-      if (toggleBtn && navOverlay) {
-        toggleBtn.setAttribute("aria-expanded", "false");
-        toggleBtn.classList.remove("is-open");
-        navOverlay.classList.remove("is-open");
-        document.body.classList.remove("menu-lock-scroll");
-      }
+      newToggleBtn.setAttribute("aria-expanded", "false");
+      newToggleBtn.classList.remove("is-open");
+      navOverlay.classList.remove("is-open");
+      document.body.classList.remove("menu-lock-scroll");
     };
 
-    if (toggleBtn && navOverlay) {
-      toggleBtn.addEventListener("click", () => {
-        const isOpen = toggleBtn.getAttribute("aria-expanded") === "true";
-        toggleBtn.setAttribute("aria-expanded", (!isOpen).toString());
-        toggleBtn.classList.toggle("is-open");
-        navOverlay.classList.toggle("is-open");
-        document.body.classList.toggle("menu-lock-scroll");
-      });
+    newToggleBtn.addEventListener("click", e => {
+      e.stopPropagation();
+      const isOpen = newToggleBtn.getAttribute("aria-expanded") === "true";
+      newToggleBtn.setAttribute("aria-expanded", (!isOpen).toString());
+      newToggleBtn.classList.toggle("is-open");
+      navOverlay.classList.toggle("is-open");
+      document.body.classList.toggle("menu-lock-scroll");
+    });
 
-      const navLinks = navOverlay.querySelectorAll("a");
-      navLinks.forEach(link => {
-        link.addEventListener("click", () => {
-          const targetUrl = new URL(link.href);
-          const currentUrl = new window.URL(window.location.href);
-          if (targetUrl.pathname === currentUrl.pathname) closeMenu();
-        });
+    // Close menu when clicking nav links
+    const navLinks = navOverlay.querySelectorAll("a");
+    navLinks.forEach(link => {
+      link.addEventListener("click", () => {
+        closeMenu();
       });
-    }
-
-    window.addEventListener("pageshow", closeMenu);
+    });
 
+    // Close details dropdowns when clicking outside
     document.addEventListener("click", event => {
       const allDetails = document.querySelectorAll("details.nav-details");
       allDetails.forEach(details => {
-        if (
-          details.hasAttribute("open") &&
-          !details.contains(event.target as Node)
-        ) {
+        if (details.hasAttribute("open") && !details.contains(event.target)) {
           details.removeAttribute("open");
         }
       });
     });
-  });
+
+    window.addEventListener("pageshow", closeMenu);
+  };
+
+  // Run on first load
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initMobileMenu);
+  } else {
+    initMobileMenu();
+  }
+
+  // Run on every Astro View Transition page navigation
+  document.addEventListener("astro:page-load", initMobileMenu);
 </script>
 
 <style>
-  /* Keeps all of your exact original CSS styles intact! */
   .mobile-toggle {
     display: flex;
     flex-direction: column;

package/templates/astro-starter/src/components/ui/KamaImage.astro

@@ -20,7 +20,7 @@ interface Props {
 const {
   image = {},
   sizes = "100vw",
-  desktopWidths = [768, 1352],
+  desktopWidths = [768, 1352, 1920, 2560],
   idealWidth = 1352,
   class: className = "",
   loading = "lazy",
@@ -90,18 +90,26 @@ function buildAgnosticSrcset(
     .join(", ");
 }
 
-// Generate srcsets only for raster images
+// 🎯 High-DPI / Retina Optimization:
+// - Mobile: Includes 320, 640, 768 (covers 2x and 3x Retina mobile displays)
+// - Tablet: Includes 768, 1024, 1352 (covers iPad Pro Retina density)
+// - Desktop: Uses desktopWidths (defaults to 768, 1352, 1920, 2560 for 1440p and 4K)
 const mobileSrcset =
-  !isSvg && rawMobileUrl ? buildAgnosticSrcset(rawMobileUrl, [400, 768]) : null;
+  !isSvg && rawMobileUrl
+    ? buildAgnosticSrcset(rawMobileUrl, [320, 640, 768])
+    : null;
 
 const tabletSrcset =
   !isSvg && rawTabletUrl
-    ? buildAgnosticSrcset(rawTabletUrl, [768, 1024])
+    ? buildAgnosticSrcset(rawTabletUrl, [768, 1024, 1352])
     : null;
 
 const desktopSrcset =
   !isSvg && rawDesktopUrl
-    ? buildAgnosticSrcset(rawDesktopUrl, desktopWidths)
+    ? buildAgnosticSrcset(
+        rawDesktopUrl,
+        desktopWidths.length ? desktopWidths : [768, 1352, 1920, 2560],
+      )
     : null;
 
 const fallbackUrl =

package/templates/astro-starter/src/layouts/StandardLayout.astro

@@ -32,8 +32,8 @@ const {
 // (MetaHead will resolve channel.defaultLanguage if this remains undefined)
 const pageLang = language || node?.language || undefined;
 
-// ❌ Removed: const footerBlocks = content?.footer || [];
-// (The new Footer component handles its own data now!)
+// 🎯 FIX: Extract the footer blocks from the payload again
+const footerBlocks = content?.footer || [];
 ---
 
 <!doctype html>
@@ -57,6 +57,7 @@ const pageLang = language || node?.language || undefined;
       </div>
     </main>
 
-    <Footer />
+    {/* 🎯 FIX: Pass the blocks and contentMap into the Footer */}
+    <Footer blocks={footerBlocks} contentMap={content} />
   </body>
 </html>

package/templates/astro-starter/src/lib/cms.ts

@@ -93,6 +93,14 @@ export function getTreeId(): string {
     return import.meta.env.PUBLIC_TREE_ID || 'navigation';
 }
 
+// 🎯 Safely resolve global authorization header for default CMS fetches
+function getAuthHeaders(): Record<string, string> {
+    const secret = import.meta.env.FRONTEND_API_SECRET;
+    const headers: Record<string, string> = { Accept: 'application/json' };
+    if (secret) headers['Authorization'] = `Bearer ${secret}`;
+    return headers;
+}
+
 /**
  * Fetch channel metadata by key/ID.
  * Serves global site branding, logos, favicons, and schema-defined public fields.
@@ -106,13 +114,17 @@ export async function getChannel(
 
     try {
         const res = await customFetch(requestUrl, {
-            headers: {
-                Accept: 'application/json',
-            },
+            headers: getAuthHeaders(),
         });
 
         if (!res.ok) return null;
 
+        // 🎯 Defensive HTML check
+        if (res.headers.get("content-type")?.includes("text/html")) {
+            console.error(`❌ [CMS Client] API returned HTML instead of JSON for Channel: ${requestUrl}`);
+            return null;
+        }
+
         return (await res.json()) as ChannelResponse;
     } catch (err) {
         console.error('[CMS Client] Failed to fetch public channel:', err);
@@ -134,13 +146,17 @@ export async function getTree(
 
     try {
         const res = await customFetch(requestUrl, {
-            headers: {
-                Accept: 'application/json',
-            },
+            headers: getAuthHeaders(),
         });
 
         if (!res.ok) return [];
 
+        // 🎯 Defensive HTML check
+        if (res.headers.get("content-type")?.includes("text/html")) {
+            console.error(`❌ [CMS Client] API returned HTML instead of JSON for Tree: ${requestUrl}`);
+            return [];
+        }
+
         const data = await res.json();
         return data.items || [];
     } catch (err) {
@@ -159,22 +175,28 @@ export async function getNodeByPath(
     preview = false,
     customFetch: typeof fetch = fetch
 ): Promise<NodeResponse | null> {
-    const cleanPath = path.replace(/^\/+|\/+$/g, '') || 'home';
+    // 🎯 We keep 'index' as the fallback string for Hono routing compatibility,
+    // because the backend dynamically intercepts 'index' and returns the channelRoot!
+    const cleanPath = path.replace(/^\/+|\/+$/g, '') || 'index';
     const baseUrl = getCmsUrl();
     const requestUrl = `${baseUrl}/api/v1/node/${cleanPath}?channelId=${channel}&preview=${preview}`;
 
     try {
         const res = await customFetch(requestUrl, {
-            headers: {
-                Accept: 'application/json',
-            },
+            headers: getAuthHeaders(),
         });
 
         if (!res.ok) return null;
 
+        // 🎯 Defensive HTML check (Prevents the dreaded "<!DOCTYPE html" JSON parse crash)
+        if (res.headers.get("content-type")?.includes("text/html")) {
+            console.error(`❌ [CMS Client] API returned HTML instead of JSON for Node: ${requestUrl}`);
+            return null;
+        }
+
         return (await res.json()) as NodeResponse;
     } catch (err) {
-        console.error('[CMS Client] Failed to fetch node by path:', err);
+        console.error(`[CMS Client] Failed to fetch node by path (${cleanPath}):`, err);
         return null;
     }
 }

package/templates/astro-starter/src/lib/media/kama-image-service.ts

@@ -28,10 +28,21 @@ const kamaImageService: LocalImageService = {
 
                 const url = new URL(src, 'http://localhost');
 
-                if (options.width) url.searchParams.set('w', Math.round(options.width).toString());
-                if (options.height) url.searchParams.set('h', Math.round(options.height).toString());
-                if (options.quality) url.searchParams.set('q', options.quality.toString());
-                if (options.format) url.searchParams.set('f', options.format.toString());
+                // 🎯 Pass width if defined (snapped on backend by assets.ts)
+                if (options.width && !isNaN(options.width)) {
+                    url.searchParams.set('w', Math.round(options.width).toString());
+                }
+
+                // 🎯 Pass height only if explicitly provided to maintain intrinsic aspect ratios
+                if (options.height && !isNaN(options.height)) {
+                    url.searchParams.set('h', Math.round(options.height).toString());
+                }
+
+                // 🎯 Default quality to 75 if unsupplied
+                url.searchParams.set('q', (options.quality || 75).toString());
+
+                // 🎯 Default format to 'auto' for backend WebP/AVIF negotiation
+                url.searchParams.set('f', options.format ? options.format.toString() : 'auto');
 
                 return src.startsWith('http') ? url.toString() : (url.pathname + url.search);
             } catch (e) {

package/templates/astro-starter/src/lib/media/media-proxy.ts

@@ -28,12 +28,31 @@ export async function handleMediaProxy({ request, params, url, locals }: APICont
     // 🎯 Detect if Astro is requesting a resized variant
     const hasResizeParams = url.searchParams.has('w') || url.searchParams.has('h') || url.searchParams.has('q') || url.searchParams.has('f');
 
+    // 🎯 Resolve Negotiated Format for Edge Cache Key
+    const acceptHeader = request.headers.get('Accept') || '';
+    const fParam = url.searchParams.get('f');
+    let resolvedFormat = fParam && fParam !== 'auto' ? fParam : '';
+
+    if (!resolvedFormat && hasResizeParams) {
+        if (acceptHeader.includes('image/avif')) resolvedFormat = 'avif';
+        else if (acceptHeader.includes('image/webp')) resolvedFormat = 'webp';
+    }
+
+    // 🎯 Construct a safe Cache Key that accounts for format negotiation
+    let cacheKeyUrl = request.url;
+    if (hasResizeParams && resolvedFormat && !fParam) {
+        const cacheUrlObj = new URL(cacheKeyUrl);
+        cacheUrlObj.searchParams.set('_resolvedFormat', resolvedFormat);
+        cacheKeyUrl = cacheUrlObj.toString();
+    }
+    const cacheKey = new Request(cacheKeyUrl, request);
+
     // 1. Cloudflare Edge Cache API
     let edgeCache: Cache | null = null;
     try {
         if (typeof caches !== "undefined" && caches.default) {
             edgeCache = caches.default;
-            const cachedResponse = await edgeCache.match(request);
+            const cachedResponse = await edgeCache.match(cacheKey);
             if (cachedResponse) return cachedResponse;
         }
     } catch (err) {
@@ -67,7 +86,7 @@ export async function handleMediaProxy({ request, params, url, locals }: APICont
                 const r2Response = new Response(r2Object.body, { status: 200, headers });
 
                 if (edgeCache) {
-                    const cachePromise = edgeCache.put(request, r2Response.clone());
+                    const cachePromise = edgeCache.put(cacheKey, r2Response.clone());
                     if (cfContext?.waitUntil) cfContext.waitUntil(cachePromise);
                     else cachePromise.catch(e => console.warn(e));
                 }
@@ -112,7 +131,7 @@ export async function handleMediaProxy({ request, params, url, locals }: APICont
             });
 
             if (edgeCache) {
-                const cachePromise = edgeCache.put(request, proxyResponse.clone());
+                const cachePromise = edgeCache.put(cacheKey, proxyResponse.clone());
                 if (cfContext?.waitUntil) cfContext.waitUntil(cachePromise);
                 else cachePromise.catch(e => console.warn(e));
             }

package/templates/astro-starter/src/lib/media/media-url.ts

@@ -1,11 +1,22 @@
 // src/lib/media/media-url.ts
 
+/**
+ * Normalizes absolute CMS URLs into clean relative /media/... paths.
+ * Ensures CSP compliance by routing requests through the Astro frontend proxy.
+ */
 export function toRelativeMediaPath(rawUrl: string): string {
     if (!rawUrl) return "";
 
-    let clean = String(rawUrl);
-    clean = clean.replace(/^https?:\/\/[^/]+/, "");
-    clean = clean.split("?")[0].split("#")[0];
+    let clean = String(rawUrl).trim();
+
+    try {
+        // Parse absolute or relative URLs safely using a dummy origin fallback
+        const urlObj = new URL(clean, "http://localhost");
+        clean = urlObj.pathname;
+    } catch {
+        // Fallback cleanup for malformed strings
+        clean = clean.replace(/^https?:\/\/[^/]+/, "").split("?")[0].split("#")[0];
+    }
 
     const mediaIndex = clean.indexOf("/media/");
     if (mediaIndex !== -1) {
@@ -26,6 +37,9 @@ export function isSvgImage(urlOrMime: string): boolean {
     return lower.endsWith('.svg') || lower.includes('image/svg+xml') || lower.includes('.svg?');
 }
 
+/**
+ * Constructs an agnostic /media/... URL with standard optimization query parameters.
+ */
 export function buildAgnosticImageUrl(
     url: string,
     width: number,