@brightsideoy/kama 1.0.0-alpha.7 → 1.0.0-alpha.9

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

@@ -45,13 +45,13 @@ if (region.includes("_")) {
 }
 
 /**
- * Default single-column layout.
+ * Default single-column layout (aligned to backend CDN buckets).
  */
 let maxWidth = "1352";
 let targetColumnWidth = 1352;
 
-// 1-col: Base mobile (~400), 2x mobile/tablet (~800), 1x desktop (1352), 2x desktop (2704)
-let optimizedWidths = [400, 800, 1352, 2048, 2704];
+// 1-col: 1x/2x desktop and retina buckets
+let optimizedWidths = [768, 1352, 1920, 2560];
 let sizes = "(max-width: 1399px) calc(100vw - 48px), 1352px";
 
 /**
@@ -61,8 +61,7 @@ if (columnCount === 2) {
   maxWidth = "660";
   targetColumnWidth = 660;
 
-  // 2-col: 1x desktop (660), 2x mobile stacked (~800), 2x desktop (1320)
-  optimizedWidths = [400, 660, 800, 1320];
+  optimizedWidths = [640, 768, 1024, 1352];
   sizes =
     "(max-width: 767px) calc(100vw - 48px), " +
     "(max-width: 1399px) calc((100vw - 80px) / 2), " +
@@ -76,8 +75,7 @@ else if (columnCount === 3) {
   maxWidth = "429";
   targetColumnWidth = 429;
 
-  // 3-col: 1x desktop (429), 2x desktop/tablet (~858), 2x/3x mobile stacked (~1000)
-  optimizedWidths = [300, 429, 858, 1024];
+  optimizedWidths = [320, 640, 768, 1024];
   sizes =
     "(max-width: 767px) calc(100vw - 48px), " +
     "(max-width: 1399px) calc((100vw - 112px) / 3), " +
@@ -91,8 +89,7 @@ else if (columnCount === 4) {
   maxWidth = "314";
   targetColumnWidth = 314;
 
-  // 4-col: 1x desktop (314), 2x desktop (628), 2x/3x mobile stacked (~1000)
-  optimizedWidths = [264, 314, 628, 1024];
+  optimizedWidths = [320, 640, 768];
   sizes =
     "(max-width: 767px) calc(100vw - 48px), " +
     "(max-width: 1399px) calc((100vw - 144px) / 4), " +
@@ -106,12 +103,9 @@ else if (columnCount === 4) {
     sizes={sizes}
     desktopWidths={optimizedWidths}
     idealWidth={targetColumnWidth}
-    width={data.width || data.image_meta?.width}
-    height={data.height || data.image_meta?.height}
     class="responsive-header-image"
     loading={isLcp ? "eager" : "lazy"}
     fetchpriority={isLcp ? "high" : "auto"}
-    decoding={isLcp ? "sync" : "async"}
   />
 </div>
 

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

@@ -26,31 +26,31 @@ if (region.includes("_")) {
   if (region.includes("_col4")) columnCount = 4;
 }
 
-// 🎯 Column Config Lookup (Max width, breakpoint widths, sizes)
+// 🎯 Column Config Lookup (Target width, aligned CDN breakpoint widths, sizes)
 const COLUMN_CONFIGS: Record<
   number,
   { targetWidth: number; widths: number[]; sizes: string }
 > = {
   1: {
     targetWidth: 1352,
-    widths: [768, 1352],
+    widths: [768, 1352, 1920, 2560],
     sizes: "(max-width: 1399px) calc(100vw - 48px), 1352px",
   },
   2: {
     targetWidth: 660,
-    widths: [400, 660],
+    widths: [640, 768, 1024, 1352],
     sizes:
       "(max-width: 767px) calc(100vw - 48px), (max-width: 1399px) calc((100vw - 80px) / 2), 660px",
   },
   3: {
     targetWidth: 429,
-    widths: [300, 429],
+    widths: [320, 640, 768, 1024],
     sizes:
       "(max-width: 767px) calc(100vw - 48px), (max-width: 1399px) calc((100vw - 112px) / 3), 429px",
   },
   4: {
     targetWidth: 314,
-    widths: [264, 314],
+    widths: [320, 640, 768],
     sizes:
       "(max-width: 767px) calc(100vw - 48px), (max-width: 1399px) calc((100vw - 144px) / 4), 314px",
   },
@@ -67,7 +67,6 @@ const layout = COLUMN_CONFIGS[columnCount] || COLUMN_CONFIGS[1];
         sizes={layout.sizes}
         desktopWidths={layout.widths}
         idealWidth={layout.targetWidth}
-        maxWidth={layout.targetWidth}
         class="free-crop-image"
         loading={isLcp ? "eager" : "lazy"}
         fetchpriority={isLcp ? "high" : "auto"}

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/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,

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

@@ -187,6 +187,46 @@ 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 => {
+      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);
+        }
+      }
+    });
+  }
+`;
 ---
 
 {
@@ -199,6 +239,9 @@ const isSkeleton = node?.nodeType === "page-skeleton";
       isHomePage={isHomePage}
     >
       <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>
   ) : (
     <StandardLayout
@@ -258,6 +301,9 @@ const isSkeleton = node?.nodeType === "page-skeleton";
           </aside>
         )}
       </div>
+
+      {/* 🎯 FIX: Script injected securely inside the layout ONLY during preview mode */}
+      {isPreview && <script is:inline set:html={hotSwapScript} />}
     </StandardLayout>
   )
 }