@brightsideoy/kama 0.1.0-alpha.99 → 1.0.0-alpha.10

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

@@ -0,0 +1,318 @@
+---
+// src/pages/[...slug].astro
+
+import StandardLayout from "../layouts/StandardLayout.astro";
+import SkeletonLayout from "../layouts/SkeletonLayout.astro";
+import BlockRenderer from "../components/blocks/BlockRenderer.astro";
+import Breadcrumb from "../components/global/Breadcrumb.astro";
+import { getNodeByPath, getChannelId, getTree, getTreeId } from "../lib/cms";
+import type { NodeResponse, TreeNode } from "../lib/cms";
+
+export const prerender = false;
+
+const { slug } = Astro.params;
+
+// Extract Preview & Revision parameters from the URL
+const searchParams = Astro.url.searchParams;
+const isPreview = searchParams.get("preview") === "true";
+const revisionId = searchParams.get("revisionId");
+
+// Smart Edge Caching Logic
+const isTimeTraveling = isPreview || !!revisionId;
+
+// 🎯 Allow Cloudflare Edge to revalidate with Worker KV middleware
+Astro.response.headers.set(
+  "Cache-Control",
+  "public, no-cache, must-revalidate",
+);
+
+// 1. STATIC ASSET CHECK
+const staticExts = [
+  ".ico",
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".svg",
+  ".txt",
+  ".xml",
+  ".webmanifest",
+];
+const slugStr = String(slug || "");
+const isStaticAsset =
+  !slugStr.includes("/") &&
+  staticExts.some(ext => slugStr.toLowerCase().endsWith(ext));
+
+if (isStaticAsset) {
+  return new Response(null, { status: 404 });
+}
+
+// 2. ENV & WORKER RESOLUTION (Safe Dual-Environment)
+const safeEnv = (Astro.locals as any).safeEnv || {};
+const cmsWorker = safeEnv.CMS_WORKER;
+
+// Extract environment configuration & fallback slug
+const envHomeSlug = import.meta.env.PUBLIC_HOME_SLUG;
+const workerHomeSlug = safeEnv.PUBLIC_HOME_SLUG;
+const homeSlug = String(envHomeSlug || workerHomeSlug || "index").trim();
+
+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
+const frontendApiSecret =
+  import.meta.env.FRONTEND_API_SECRET || safeEnv.FRONTEND_API_SECRET;
+
+const cleanApiUrl = baseApiUrl.endsWith("/")
+  ? baseApiUrl.slice(0, -1)
+  : baseApiUrl;
+
+const customFetch = async (input: RequestInfo | URL, init?: RequestInit) => {
+  let urlStr = input instanceof URL ? input.toString() : String(input);
+  if (urlStr.startsWith("/")) urlStr = `${cleanApiUrl}${urlStr}`;
+
+  const urlObj = new URL(urlStr);
+
+  if (isTimeTraveling) {
+    if (revisionId) urlObj.searchParams.set("revisionId", revisionId);
+    if (isPreview) urlObj.searchParams.set("preview", "true");
+    urlObj.searchParams.set("_t", Date.now().toString());
+  } else {
+    urlObj.searchParams.set("_cb", Date.now().toString());
+  }
+
+  urlStr = urlObj.toString();
+
+  const reqHeaders: Record<string, string> = {
+    ...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}`;
+  }
+
+  const fetchOpts: RequestInit = {
+    ...init,
+    headers: reqHeaders,
+  };
+
+  const req = new Request(urlStr, fetchOpts);
+
+  if (cmsWorker && typeof cmsWorker.fetch === "function") {
+    return cmsWorker.fetch(req);
+  }
+  return fetch(req);
+};
+
+const channelId = getChannelId();
+const treeId = getTreeId();
+
+// 3. PATH & CONCURRENT FETCH RESOLUTION
+const rawSlug = Array.isArray(slug) ? slug.join("/") : slugStr;
+const pathParts = rawSlug.split("/").filter(part => part.trim() !== "");
+const requestedSlug = pathParts.join("/");
+const targetSlug = requestedSlug || homeSlug;
+
+let pageData: NodeResponse | null = null;
+let navTree: TreeNode[] = [];
+
+// 🎯 Fetch Tree and Node in PARALLEL using the cache-busting customFetch
+try {
+  const [treeResult, nodeResult] = await Promise.all([
+    getTree(treeId, channelId, customFetch).catch(err => {
+      console.error(`❌ [SSR Error] Failed to fetch tree "${treeId}":`, err);
+      return [];
+    }),
+    getNodeByPath(targetSlug, channelId, isPreview, customFetch).catch(err => {
+      console.error(
+        `❌ [SSR Error] Failed to fetch page data for path "${targetSlug}":`,
+        err,
+      );
+      return null;
+    }),
+  ]);
+
+  navTree = treeResult || [];
+  pageData = nodeResult as NodeResponse | null;
+} catch (err) {
+  console.error("❌ [SSR Error] Failed concurrent fetch execution:", err);
+}
+
+if (!pageData || !pageData.node) {
+  return new Response("Page Not Found", { status: 404 });
+}
+
+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) {
+  Astro.response.headers.set(
+    "Cache-Control",
+    "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());
+}
+
+const rootTreeSlug =
+  navTree && navTree.length > 0
+    ? navTree[0].slug || (navTree[0] as any).key
+    : "";
+
+const isHomePage =
+  targetSlug === homeSlug ||
+  (rootTreeSlug && targetSlug === rootTreeSlug) ||
+  node?.path === "/" ||
+  pathParts.length === 0;
+
+const normalizedSlug = isHomePage ? "" : targetSlug;
+
+const headerBlocks = content?.header || [];
+const mainBlocks = content?.content || [];
+const sidebarBlocks = content?.sidebar || [];
+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);
+        }
+      }
+    });
+  }
+`;
+---
+
+{
+  isSkeleton ? (
+    <SkeletonLayout
+      node={node}
+      content={content}
+      language={pageData?.language}
+      normalizedSlug={normalizedSlug}
+      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
+      node={node}
+      content={content}
+      language={pageData?.language}
+      normalizedSlug={normalizedSlug}
+      isHomePage={isHomePage}
+      hasSidebar={hasSidebar}
+      headerBlocks={headerBlocks}
+      tree={navTree}
+    >
+      {headerBlocks.length > 0 && (
+        <section class="region-header">
+          <BlockRenderer
+            blocks={headerBlocks}
+            contentMap={content}
+            region="header"
+          />
+        </section>
+      )}
+
+      {!isHomePage && (
+        <div class="breadcrumb-wrapper">
+          <Breadcrumb title={node?.title || "Page"} slug={normalizedSlug} />
+        </div>
+      )}
+
+      <div class:list={["content-layout", { "has-sidebar": hasSidebar }]}>
+        <div class="main-column">
+          {mainBlocks.length > 0 ? (
+            <section class="region-main">
+              <BlockRenderer
+                blocks={mainBlocks}
+                contentMap={content}
+                region="main"
+              />
+            </section>
+          ) : (
+            <div class="empty-content">
+              <p data-cms-field="summary">
+                {node?.summary || "No content available for this page."}
+              </p>
+            </div>
+          )}
+        </div>
+
+        {hasSidebar && (
+          <aside class="sidebar-column">
+            <section class="region-sidebar">
+              <BlockRenderer
+                blocks={sidebarBlocks}
+                contentMap={content}
+                region="sidebar"
+              />
+            </section>
+          </aside>
+        )}
+      </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

@@ -0,0 +1,40 @@
+// src/pages/api/load-nodes.ts
+import type { APIRoute } from "astro";
+
+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;
+
+    // 2. Construct the actual backend URL
+    const backendUrl = `${apiUrl.replace(/\/$/, "")}/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}` } : {})
+            }
+        });
+
+        if (!response.ok) {
+            return new Response(JSON.stringify({ error: "Failed to fetch nodes" }), { status: response.status });
+        }
+
+        const data = await response.json();
+
+        // 4. Return to the browser
+        return new Response(JSON.stringify(data), {
+            status: 200,
+            headers: { "Content-Type": "application/json" }
+        });
+    } catch (err) {
+        console.error("[Astro Proxy] Failed to load nodes:", err);
+        return new Response(JSON.stringify({ error: "Internal Server Error" }), { status: 500 });
+    }
+};

package/templates/astro-starter/src/pages/llms-full.txt.ts

@@ -0,0 +1,171 @@
+// src/pages/llms-full.txt.ts
+import type { APIRoute } from "astro";
+import { getTree, getTreeId, getChannelId, getNodeByPath } from "../lib/cms";
+import { renderTiptapNode } from "../utils/tiptap";
+
+export const prerender = false;
+
+export const GET: APIRoute = async (context) => {
+    // 1. Setup Worker Fetch Binding
+    const locals = (context.locals as any) || {};
+    const cfEnv = locals.cfContext?.env || {};
+    const cmsWorker = cfEnv.CMS_WORKER;
+
+    const envApiUrl = import.meta.env.PUBLIC_API_URL;
+    const workerApiUrl = cfEnv.PUBLIC_API_URL || (typeof process !== "undefined" ? process.env?.PUBLIC_API_URL : undefined);
+    const baseApiUrl = String(envApiUrl || workerApiUrl || "http://localhost:8787").replace(/\/$/, "");
+
+    const customFetch = async (input: RequestInfo | URL, init?: RequestInit) => {
+        let urlStr = input instanceof URL ? input.toString() : String(input);
+        if (urlStr.startsWith("/")) urlStr = `${baseApiUrl}${urlStr}`;
+
+        const req = new Request(urlStr, init);
+        if (cmsWorker && typeof cmsWorker.fetch === "function") {
+            return cmsWorker.fetch(req);
+        }
+        return fetch(req);
+    };
+
+    const channelId = getChannelId() || import.meta.env.PUBLIC_CHANNEL_ID || "main-channel";
+    const treeId = getTreeId() || import.meta.env.PUBLIC_TREE_ID || "main-tree";
+
+    // 🎯 Extract configurable fallback home slug
+    const envHomeSlug = import.meta.env.PUBLIC_HOME_SLUG;
+    const workerHomeSlug = cfEnv.PUBLIC_HOME_SLUG || (typeof process !== "undefined" ? process.env?.PUBLIC_HOME_SLUG : undefined);
+    const homeSlug = String(envHomeSlug || workerHomeSlug || "home").trim();
+
+    const rawOrigin = import.meta.env.PUBLIC_SITE_URL || context.url.origin;
+    const siteOrigin = String(rawOrigin).replace(/\/$/, "");
+    const brandName = import.meta.env.PUBLIC_SITE_NAME || "KAMA Starter";
+
+    try {
+        // 2. Fetch Navigation Tree first to determine root nodes
+        const rawNavTree = await getTree(treeId, channelId, customFetch).catch(() => []);
+        const navTree = Array.isArray(rawNavTree)
+            ? rawNavTree
+            : (rawNavTree?.tree || rawNavTree?.items || rawNavTree?.data || []);
+
+        // Determine home page slug (first root node in tree, or fallback home slug)
+        const rootTreeSlug = navTree.length > 0 ? (navTree[0].slug || navTree[0].key || "") : "";
+        const resolvedHomeSlug = rootTreeSlug || homeSlug;
+
+        // Fetch Home Node (for global context)
+        const homeData = await getNodeByPath(resolvedHomeSlug, channelId, false, customFetch).catch(() => null);
+
+        const siteSummary = homeData?.node?.abstract || homeData?.node?.summary || "Full Application Documentation Corpus";
+
+        // 3. Header section matching llmstxt.org spec
+        let fullText = `# ${brandName} - Full Corpus\n\n`;
+        fullText += `> ${siteSummary}\n\n`;
+        fullText += `This file contains the complete unabridged text content for all pages across the application.\n\n`;
+
+        // Helper to extract text from block data (handles TipTap AST & raw strings)
+        const parseBlockText = (blockData: any): string => {
+            if (!blockData) return "";
+            let rawText = "";
+
+            if (typeof blockData === "string") {
+                rawText = blockData;
+            } else if (blockData.type === "doc") {
+                rawText = renderTiptapNode(blockData);
+            } else if (blockData.body) {
+                rawText = parseBlockText(blockData.body);
+            } else if (blockData.text) {
+                rawText = parseBlockText(blockData.text);
+            }
+
+            // Convert basic HTML block tags to plain text linebreaks
+            return rawText
+                .replace(/<h[1-6][^>]*>(.*?)<\/h[1-6]>/gi, "## $1\n")
+                .replace(/<p[^>]*>(.*?)<\/p>/gi, "$1\n")
+                .replace(/<br\s*\/?>/gi, "\n")
+                .replace(/<[^>]+>/g, ""); // Strip any remaining tags
+        };
+
+        // Recursive walker to fetch each page's full content
+        const processNodes = async (nodes: any[], depth = 1) => {
+            let sectionContent = "";
+
+            for (const item of nodes) {
+                const nodeData = item.node || item;
+                if (!nodeData || nodeData.isHidden) continue;
+
+                const itemSlug = nodeData.slug || nodeData.path || "";
+                const isRootItem = itemSlug === resolvedHomeSlug || itemSlug === "" || itemSlug === "/";
+                const itemUrl = isRootItem ? siteOrigin : `${siteOrigin}/${itemSlug.replace(/^\//, "")}`;
+                const itemTitle = nodeData.title || nodeData.label || "Untitled Page";
+
+                const fetchSlug = isRootItem ? resolvedHomeSlug : itemSlug.replace(/^\//, "");
+
+                // Fetch node's block contents
+                const pageData = await getNodeByPath(
+                    fetchSlug,
+                    channelId,
+                    false,
+                    customFetch
+                ).catch(() => null);
+
+                // Add Document Title Header
+                sectionContent += `\n---\n\n`;
+                sectionContent += `# ${itemTitle}\n`;
+                sectionContent += `**URL:** ${itemUrl}\n`;
+                if (nodeData.abstract || nodeData.summary) {
+                    sectionContent += `**Abstract:** ${nodeData.abstract || nodeData.summary}\n`;
+                }
+                sectionContent += `\n`;
+
+                // Render all blocks on the node
+                const regions = pageData?.content || {};
+                let blockCount = 0;
+
+                Object.entries(regions).forEach(([regionName, blocks]) => {
+                    if (!Array.isArray(blocks)) return;
+
+                    blocks.forEach((block: any) => {
+                        const data = block.data || {};
+                        const renderedText = parseBlockText(data);
+
+                        if (renderedText && renderedText.trim()) {
+                            sectionContent += `${renderedText.trim()}\n\n`;
+                            blockCount++;
+                        }
+                    });
+                });
+
+                if (blockCount === 0) {
+                    sectionContent += `*(No text content available for this node)*\n\n`;
+                }
+
+                // Recursively process child pages
+                if (Array.isArray(item.children) && item.children.length > 0) {
+                    sectionContent += await processNodes(item.children, depth + 1);
+                }
+            }
+
+            return sectionContent;
+        };
+
+        if (navTree.length > 0) {
+            fullText += await processNodes(navTree);
+        } else {
+            fullText += `\n---\n\n# Home\n**URL:** ${siteOrigin}\n\nNo additional pages found in navigation tree.\n`;
+        }
+
+        fullText += `\n---\n*Generated dynamically by Kama Engine.*`;
+
+        return new Response(fullText, {
+            status: 200,
+            headers: {
+                "Content-Type": "text/plain; charset=utf-8",
+                "Cache-Control": "public, max-age=3600, s-maxage=86400"
+            },
+        });
+
+    } catch (error) {
+        console.error("[llms-full.txt Generator Error]:", error);
+        return new Response("# Error\nCould not generate full AI context corpus.", {
+            status: 500,
+            headers: { "Content-Type": "text/plain; charset=utf-8" }
+        });
+    }
+};

package/templates/astro-starter/src/pages/llms.txt.ts

@@ -0,0 +1,113 @@
+// src/pages/llms.txt.ts
+import type { APIRoute } from "astro";
+import { getTree, getTreeId, getChannelId, getNodeByPath } from "../lib/cms";
+
+// Ensure this route is dynamically rendered (SSR)
+export const prerender = false;
+
+export const GET: APIRoute = async (context) => {
+    // 1. Setup Cloudflare Worker Fetch Binding safely
+    const locals = (context.locals as any) || {};
+    const cfEnv = locals.cfContext?.env || {};
+    const cmsWorker = cfEnv.CMS_WORKER;
+
+    const envApiUrl = import.meta.env.PUBLIC_API_URL;
+    const workerApiUrl = cfEnv.PUBLIC_API_URL || (typeof process !== "undefined" ? process.env?.PUBLIC_API_URL : undefined);
+    const baseApiUrl = String(envApiUrl || workerApiUrl || "http://localhost:8787").replace(/\/$/, "");
+
+    const customFetch = async (input: RequestInfo | URL, init?: RequestInit) => {
+        let urlStr = input instanceof URL ? input.toString() : String(input);
+        if (urlStr.startsWith("/")) urlStr = `${baseApiUrl}${urlStr}`;
+
+        const req = new Request(urlStr, init);
+        if (cmsWorker && typeof cmsWorker.fetch === "function") {
+            return cmsWorker.fetch(req);
+        }
+        return fetch(req);
+    };
+
+    // 2. Load keys from environment or fallback defaults
+    const channelId = getChannelId() || import.meta.env.PUBLIC_CHANNEL_ID || "main-channel";
+    const treeId = getTreeId() || import.meta.env.PUBLIC_TREE_ID || "main-tree";
+
+    // 🎯 Extract configurable fallback home slug
+    const envHomeSlug = import.meta.env.PUBLIC_HOME_SLUG;
+    const workerHomeSlug = cfEnv.PUBLIC_HOME_SLUG || (typeof process !== "undefined" ? process.env?.PUBLIC_HOME_SLUG : undefined);
+    const homeSlug = String(envHomeSlug || workerHomeSlug || "home").trim();
+
+    const rawOrigin = import.meta.env.PUBLIC_SITE_URL || context.url.origin;
+    const siteOrigin = String(rawOrigin).replace(/\/$/, "");
+    const brandName = import.meta.env.PUBLIC_SITE_NAME || "KAMA Starter";
+
+    try {
+        // 3. Parallel fetch for Navigation Tree first to resolve root node slug
+        const rawNavTree = await getTree(treeId, channelId, customFetch).catch(() => []);
+        const navTree = Array.isArray(rawNavTree)
+            ? rawNavTree
+            : (rawNavTree?.tree || rawNavTree?.items || rawNavTree?.data || []);
+
+        const rootTreeSlug = navTree.length > 0 ? (navTree[0].slug || navTree[0].key || "") : "";
+        const resolvedHomeSlug = rootTreeSlug || homeSlug;
+
+        // Fetch Home Node summary
+        const homeData = await getNodeByPath(resolvedHomeSlug, channelId, false, customFetch).catch(() => null);
+
+        const siteSummary = homeData?.node?.abstract || homeData?.node?.summary || "Global Content Delivery at the Edge";
+
+        // 4. Build standard-compliant llms.txt Markdown
+        let markdown = `# ${brandName}\n\n`;
+        markdown += `> ${siteSummary}\n\n`;
+        markdown += `This file serves as a structured directory for AI agents and language models.\n\n`;
+        markdown += `## Site Directory\n\n`;
+
+        // Recursive tree flattener with link annotations
+        const buildList = (nodes: any[], depth = 0) => {
+            let list = "";
+            const indent = "  ".repeat(depth);
+
+            for (const item of nodes) {
+                const nodeData = item.node || item;
+                if (!nodeData || nodeData.isHidden) continue;
+
+                const itemSlug = nodeData.slug || nodeData.path || "";
+                const isRootItem = itemSlug === resolvedHomeSlug || itemSlug === "" || itemSlug === "/";
+                const itemUrl = isRootItem ? siteOrigin : `${siteOrigin}/${itemSlug.replace(/^\//, "")}`;
+
+                const itemTitle = nodeData.title || nodeData.label || nodeData.menuTitle || "Untitled";
+                const abstract = nodeData.abstract || nodeData.summary || nodeData.description;
+                const annotation = abstract ? `: ${abstract.trim()}` : "";
+
+                list += `${indent}- [${itemTitle}](${itemUrl})${annotation}\n`;
+
+                if (Array.isArray(item.children) && item.children.length > 0) {
+                    list += buildList(item.children, depth + 1);
+                }
+            }
+            return list;
+        };
+
+        if (navTree.length > 0) {
+            markdown += buildList(navTree);
+        } else {
+            const homeTitle = homeData?.node?.title || brandName;
+            markdown += `- [${homeTitle}](${siteOrigin}): Main landing page.\n`;
+        }
+
+        markdown += `\n---\n*Generated dynamically by Kama Engine.*`;
+
+        return new Response(markdown, {
+            status: 200,
+            headers: {
+                "Content-Type": "text/plain; charset=utf-8",
+                "Cache-Control": "public, max-age=3600, s-maxage=86400"
+            },
+        });
+
+    } catch (error) {
+        console.error("[llms.txt Generator Error]:", error);
+        return new Response("# Error\nCould not generate AI directory.", {
+            status: 500,
+            headers: { "Content-Type": "text/plain; charset=utf-8" }
+        });
+    }
+};

package/templates/astro-starter/src/pages/media/[...path].ts

@@ -0,0 +1,14 @@
+// src/pages/media/[...path].ts
+import type { APIRoute } from "astro";
+import { handleMediaProxy } from "../../lib/media/media-proxy";
+
+export const prerender = false;
+
+export const GET: APIRoute = async (context) => {
+    try {
+        return await handleMediaProxy(context);
+    } catch (error: any) {
+        console.error("❌ [Media Proxy Error]:", error?.message || error);
+        return new Response("Media Proxy Failed", { status: 500 });
+    }
+};