@brightsideoy/kama 0.1.0-alpha.12 → 0.1.0-alpha.121

package/templates/astro-starter/middleware/kv-cache.ts

@@ -0,0 +1,76 @@
+import { defineMiddleware } from "astro:middleware";
+import { env } from "cloudflare:workers";
+
+export const kvCacheMiddleware = defineMiddleware(async (context, next) => {
+    const pathname = context.url.pathname;
+    const locals = context.locals as any;
+    const cfContext = locals.cfContext;
+    const workerEnv = (typeof env !== "undefined" ? env : (process?.env || {})) as any;
+    const HTML_CACHE = workerEnv?.HTML_CACHE;
+
+    const isWarmer = context.request.headers.get("X-Cache-Warmer") === "true";
+    const isHtmlPage = !pathname.includes('.') && !pathname.startsWith('/api/');
+    const cleanLookupPath = pathname.replace(/\/$/, "") || "/";
+
+    let activeCacheKey = cleanLookupPath;
+
+    // 🎯 1. READ PHASE
+    if (isHtmlPage && HTML_CACHE && !isWarmer) {
+        try {
+            const [siteVer, pageVer] = await Promise.all([
+                HTML_CACHE.get("site_version"),
+                HTML_CACHE.get(`v:${cleanLookupPath}`)
+            ]);
+
+            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"
+                    }
+                });
+            }
+        } catch (e) {
+            console.warn("[KV Cache] Lookup bypassed:", e);
+        }
+    }
+
+    // Process downstream SSR route
+    const response = await next();
+
+    // 🎯 2. WRITE PHASE
+    if (
+        isHtmlPage &&
+        HTML_CACHE &&
+        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();
+                await HTML_CACHE.put(`v:${cleanLookupPath}`, forcedVersion);
+                const siteVer = await HTML_CACHE.get("site_version") || "1";
+                activeCacheKey = `${cleanLookupPath}:v:${siteVer}:${forcedVersion}`;
+            }
+
+            await HTML_CACHE.put(activeCacheKey, htmlText);
+            console.log(`✅ [KV Cache] Saved HTML under key: ${activeCacheKey}`);
+        })();
+
+        if (cfContext && typeof cfContext.waitUntil === 'function') {
+            cfContext.waitUntil(writeTask);
+        } else {
+            writeTask.catch((e: any) => console.error("KV write error:", e));
+        }
+    }
+
+    return response;
+});

package/templates/astro-starter/middleware/response-headers.ts

@@ -0,0 +1,43 @@
+import { defineMiddleware } from "astro:middleware";
+
+export const responseHeadersMiddleware = defineMiddleware(async (context, next) => {
+    // Process downstream routes first so we have the response to modify
+    const response = await next();
+    const pathname = context.url.pathname;
+
+    // 1. LLMs & XML Configs
+    if (pathname === "/llms.txt" || pathname === "/llms-full.txt") {
+        response.headers.set("Content-Type", "text/plain; charset=utf-8");
+        response.headers.set("Cache-Control", "public, max-age=3600");
+        response.headers.set("Access-Control-Allow-Origin", "*");
+    }
+    else if (pathname === "/llxml.txt") {
+        response.headers.set("Content-Type", "application/xml; charset=utf-8");
+        response.headers.set("Cache-Control", "public, max-age=3600");
+        response.headers.set("Access-Control-Allow-Origin", "*");
+    }
+
+    // 2. Static Asset Caching
+    else if (
+        pathname.startsWith("/media/") ||
+        pathname.startsWith("/_image") ||
+        pathname.match(/\.(png|jpg|jpeg|webp|avif|svg|gif|ico|woff2?|css|js)$/i)
+    ) {
+        response.headers.set("Cache-Control", "public, max-age=31536000, s-maxage=31536000, immutable");
+        response.headers.set("Access-Control-Allow-Origin", "*");
+    }
+
+    // 3. Security Headers for HTML
+    if (response.headers.get("content-type")?.includes("text/html")) {
+        response.headers.set("Strict-Transport-Security", "max-age=31536000; includeSubDomains; preload");
+        response.headers.set("X-Frame-Options", "SAMEORIGIN");
+        response.headers.set("X-Content-Type-Options", "nosniff");
+        response.headers.set("Cross-Origin-Opener-Policy", "same-origin-allow-popups");
+        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';"
+        );
+    }
+
+    return response;
+});

package/templates/astro-starter/package.json.template

@@ -0,0 +1,20 @@
+{
+  "name": "{{SITE_NAME}}",
+  "type": "module",
+  "version": "0.0.1",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "deploy": "astro build && wrangler deploy"
+  },
+  "dependencies": {
+    "@astrojs/cloudflare": "^14.2.5",
+    "@brightsideoy/kama": "{{KAMA_VERSION}}",
+    "astro": "^7.2.0",
+    "wrangler": "^4.0.0"
+  }
+}

package/templates/astro-starter/public/css/standard-theme.css

@@ -0,0 +1,157 @@
+/* =======================================
+   1. GLOBAL RESETS & TYPOGRAPHY
+   ======================================= */
+*,
+*::before,
+*::after {
+    box-sizing: border-box;
+    border-radius: 0 !important;
+}
+
+html {
+    font-size: 16px;
+    -webkit-text-size-adjust: 100%;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    text-rendering: optimizeLegibility;
+}
+
+body {
+    margin: 0;
+    padding: 0;
+    font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    font-display: swap;
+    background-color: #ffffff;
+    color: #1e293b;
+    min-height: 100vh;
+    display: flex;
+    flex-direction: column;
+    line-height: 1.65;
+    letter-spacing: -0.011em;
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+    color: #0f172a;
+    font-weight: 700;
+    line-height: 1.25;
+    letter-spacing: -0.022em;
+    margin-top: 1.6em;
+    margin-bottom: 0.6em;
+}
+
+h1 {
+    font-size: 2.25rem;
+}
+
+h2 {
+    font-size: 1.65rem;
+}
+
+h3 {
+    font-size: 1.35rem;
+}
+
+p {
+    margin-top: 0;
+    margin-bottom: 1.25em;
+    color: #334155;
+    font-size: 1.03rem;
+}
+
+a {
+    color: #0284c7;
+    text-decoration-thickness: 1px;
+    text-underline-offset: 3px;
+    transition: color 0.15s ease;
+}
+
+a:hover {
+    color: #0369a1;
+}
+
+li>p:last-child {
+    margin-bottom: 0;
+}
+
+/* =======================================
+   2. MAIN LAYOUT SHELL
+   ======================================= */
+.content-block {
+    flex: 1;
+    padding: 40px 0 64px 0;
+}
+
+.content-container {
+    max-width: 1400px;
+    margin: 0 auto;
+    padding: 0 24px;
+    width: 100%;
+    box-sizing: border-box;
+}
+
+/* =======================================
+   3. ROUTER REGIONS (from slug.astro)
+   ======================================= */
+.region-header {
+    margin-bottom: 24px;
+}
+
+.breadcrumb-wrapper {
+    margin-bottom: 24px;
+}
+
+.content-layout {
+    width: 100%;
+    display: block;
+}
+
+.main-column {
+    width: 100%;
+    min-width: 0;
+}
+
+@media (min-width: 768px) {
+    .content-layout.has-sidebar {
+        display: grid !important;
+        grid-template-columns: calc(100% - 360px) 310px !important;
+        column-gap: 48px !important;
+        align-items: start !important;
+    }
+
+    .main-column {
+        grid-column: 1 / 2 !important;
+    }
+
+    .sidebar-column {
+        grid-column: 2 / 3 !important;
+        position: sticky;
+        top: 32px;
+    }
+}
+
+.sidebar-column {
+    background: #f8fafc;
+    border: 1px solid #e2e8f0;
+    padding: 28px;
+    box-sizing: border-box;
+}
+
+@media (max-width: 767px) {
+    .sidebar-column {
+        margin-top: 40px;
+    }
+}
+
+.empty-content {
+    padding: 32px;
+    border: 1px dashed #cbd5e1;
+    background: #f8fafc;
+    color: #64748b;
+    font-size: 0.95rem;
+    text-align: center;
+}

package/templates/astro-starter/public/robots.txt

@@ -0,0 +1,23 @@
+# Allow standard search engine crawlers
+User-agent: *
+Allow: /
+
+# Block sensitive or irrelevant paths
+Disallow: /api/
+Disallow: /*?*search=
+
+# Explicitly block AI scrapers / Training Bots (Optional)
+# User-agent: GPTBot
+# Disallow: /
+
+# User-agent: CCBot
+# Disallow: /
+
+# User-agent: Anthropic-ai
+# Disallow: /
+
+# User-agent: Google-Extended
+# Disallow: /
+
+# XML Sitemap location
+# Sitemap: https://yourdomain.com/sitemap-index.xml

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

@@ -0,0 +1,133 @@
+---
+// src/components/blocks/BlockRenderer.astro
+import ImageBlock from "@/components/blocks/ImageBlock.astro";
+import HeaderImage from "@/components/blocks/HeaderImage.astro";
+import ColumnLayout from "@/components/blocks/ColumnLayout.astro";
+import HtmlBlock from "@/components/blocks/HtmlBlock.astro";
+import { extractHtml } from "@/utils/tiptap";
+
+interface Block {
+  instanceId: number;
+  blockId?: string;
+  componentId: string;
+  data: Record<string, any>;
+}
+
+interface Props {
+  blocks?: Block[];
+  contentMap?: Record<string, any[]>;
+  region?: string;
+}
+
+const { blocks = [], contentMap = {}, region = "main" } = Astro.props;
+const safeBlocks = Array.isArray(blocks) ? blocks : [];
+
+const visibleBlocks = safeBlocks.filter(b => {
+  if (!b || (!b.data && !b.componentId?.includes("column"))) return false;
+
+  const blockData = b.data || {};
+  if (
+    blockData.hidden === true ||
+    blockData.hidden === 1 ||
+    String(blockData.hidden) === "true"
+  ) {
+    return false;
+  }
+
+  const now = new Date();
+  if (blockData.startShowingAt) {
+    const start = new Date(blockData.startShowingAt);
+    if (!isNaN(start.getTime()) && now < start) return false;
+  }
+  if (blockData.stopShowingAt) {
+    const stop = new Date(blockData.stopShowingAt);
+    if (!isNaN(stop.getTime()) && now > stop) return false;
+  }
+
+  return true;
+});
+---
+
+{
+  visibleBlocks.map((block, index) => {
+    const data = block.data || {};
+    const blockId = block.blockId || data.blockId || "";
+    const componentId = (block.componentId || "").toLowerCase();
+
+    // Check for any column layout ending in column or two-column
+    if (componentId.includes("column")) {
+      return <ColumnLayout blockId={blockId} contentMap={contentMap} />;
+    }
+
+    switch (componentId) {
+      case "header":
+      case "headline":
+      case "header-block":
+      case "header_block": {
+        const headline = extractHtml(data.headline || data.title);
+        const subhead = extractHtml(data.subhead || data.body);
+        return (
+          <header class="cms-block cms-block-header">
+            {headline && <Fragment set:html={headline} />}
+            {subhead && <Fragment set:html={subhead} />}
+          </header>
+        );
+      }
+
+      case "text":
+      case "text-block":
+      case "text_block": {
+        const bodyText = extractHtml(data.body || data.text || data.content);
+        return (
+          <div class="cms-block cms-block-text">
+            <Fragment set:html={bodyText} />
+          </div>
+        );
+      }
+
+      case "html":
+      case "html-block":
+      case "html_block":
+      case "raw-html": {
+        return <HtmlBlock data={data} />;
+      }
+
+      case "header-image":
+      case "header_image": {
+        return (
+          <HeaderImage data={data} region={region} isFirst={index === 0} />
+        );
+      }
+
+      case "image":
+      case "image-block":
+      case "image_block":
+      case "single_image":
+      case "single-image": {
+        return <ImageBlock data={data} region={region} isFirst={index === 0} />;
+      }
+
+      default:
+        return import.meta.env.DEV ? (
+          <div class="unhandled-block">
+            <p>Unhandled component: {block.componentId}</p>
+          </div>
+        ) : null;
+    }
+  })
+}
+
+<style>
+  .cms-block {
+    margin-bottom: 1.5rem;
+  }
+
+  .unhandled-block {
+    padding: 12px 16px;
+    border: 1px dashed #cbd5e1;
+    background: #f8fafc;
+    color: #64748b;
+    font-size: 13px;
+    margin-bottom: 1.5rem;
+  }
+</style>

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

@@ -0,0 +1,66 @@
+---
+// src/components/blocks/ColumnLayout.astro
+import BlockRenderer from "@/components/blocks/BlockRenderer.astro";
+
+interface Props {
+  blockId: string;
+  contentMap: Record<string, any[]>;
+}
+
+const { blockId, contentMap } = Astro.props;
+
+const order = ["left", "middle", "right", "col1", "col2", "col3", "col4"];
+
+// 1. Find all sub-regions belonging to this specific layout instance
+const regionKeys = Object.keys(contentMap).filter(
+  key => blockId && key.startsWith(`${blockId}_`),
+);
+
+// 2. Sort keys logically (left -> middle -> right or col1 -> col2 -> col3)
+const sortedKeys = regionKeys.sort((a, b) => {
+  const suffixA = a.replace(`${blockId}_`, "");
+  const suffixB = b.replace(`${blockId}_`, "");
+  const idxA = order.indexOf(suffixA);
+  const idxB = order.indexOf(suffixB);
+
+  if (idxA === -1 && idxB === -1) return a.localeCompare(b);
+  if (idxA === -1) return 1;
+  if (idxB === -1) return -1;
+  return idxA - idxB;
+});
+
+const columnCount = Math.max(sortedKeys.length, 1);
+---
+
+<div class="cms-column-layout" style={`--col-count: ${columnCount}`}>
+  {
+    sortedKeys.map(key => {
+      const columnBlocks = contentMap[key] || [];
+      return (
+        <div class="column">
+          <!-- 🎯 Passes region={key} down to BlockRenderer -->
+          <BlockRenderer 
+            blocks={columnBlocks} 
+            contentMap={contentMap} 
+            region={key} 
+          />
+        </div>
+      );
+    })
+  }
+</div>
+
+<style>
+  .cms-column-layout {
+    display: grid;
+    gap: 2rem;
+    margin-bottom: 1.5rem;
+    grid-template-columns: 1fr;
+  }
+
+  @media (min-width: 768px) {
+    .cms-column-layout {
+      grid-template-columns: repeat(var(--col-count, 1), 1fr);
+    }
+  }
+</style>

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

@@ -0,0 +1,131 @@
+---
+// src/components/blocks/HeaderImage.astro
+import KamaImage from "@/components/ui/KamaImage.astro";
+
+interface Props {
+  data: {
+    image?: any;
+    image_meta?: any;
+    width?: number | string;
+    height?: number | string;
+  };
+  region?: string;
+  isFirst?: boolean;
+}
+
+const { data, region = "main", isFirst = false } = Astro.props;
+
+const img = data?.image;
+
+if (!img) {
+  return null;
+}
+
+/**
+ * Determine if this image is likely to be the Largest Contentful Paint.
+ */
+const isLcp = region === "header" || (region === "main" && isFirst);
+
+/**
+ * Determine grid column count from the region name.
+ */
+let columnCount = 1;
+
+if (region.includes("_")) {
+  columnCount = 2;
+
+  if (region.includes("_middle") || region.includes("_col3")) {
+    columnCount = 3;
+  }
+
+  if (region.includes("_col4")) {
+    columnCount = 4;
+  }
+}
+
+/**
+ * Default single-column layout.
+ */
+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];
+let sizes = "(max-width: 1399px) calc(100vw - 48px), 1352px";
+
+/**
+ * Two-column layout.
+ */
+if (columnCount === 2) {
+  maxWidth = "660";
+  targetColumnWidth = 660;
+
+  // 2-col: 1x desktop (660), 2x mobile stacked (~800), 2x desktop (1320)
+  optimizedWidths = [400, 660, 800, 1320];
+  sizes =
+    "(max-width: 767px) calc(100vw - 48px), " +
+    "(max-width: 1399px) calc((100vw - 80px) / 2), " +
+    "660px";
+}
+
+/**
+ * Three-column layout.
+ */
+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];
+  sizes =
+    "(max-width: 767px) calc(100vw - 48px), " +
+    "(max-width: 1399px) calc((100vw - 112px) / 3), " +
+    "429px";
+}
+
+/**
+ * Four-column layout.
+ */
+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];
+  sizes =
+    "(max-width: 767px) calc(100vw - 48px), " +
+    "(max-width: 1399px) calc((100vw - 144px) / 4), " +
+    "314px";
+}
+---
+
+<div class="cms-block cms-block-header-image" style={`--max-w: ${maxWidth}px;`}>
+  <KamaImage
+    image={img}
+    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>
+
+<style>
+  .cms-block-header-image {
+    width: 100%;
+    max-width: var(--max-w, 1352px);
+    margin: 0 auto 1.5rem auto;
+  }
+
+  :global(.responsive-header-image) {
+    width: 100%;
+    height: auto;
+    display: block;
+    border-radius: var(--cms-radius-md, 0.5rem);
+    max-width: 100%;
+  }
+</style>