alabjs 0.1.0 → 0.2.0

package/src/server/app.ts

@@ -1,7 +1,7 @@
 import { createApp as createH3App, createRouter, defineEventHandler, getQuery, readBody } from "h3";
 import { createServer } from "node:http";
 import { resolve, dirname, join, extname } from "node:path";
-import { existsSync, createReadStream, statSync } from "node:fs";
+import { existsSync, createReadStream, statSync, readFileSync } from "node:fs";
 import { toNodeListener } from "h3";
 import type { RouteManifest } from "../router/manifest.js";
 import { renderToResponse } from "../ssr/render.js";
@@ -12,6 +12,8 @@ import type { MiddlewareModule } from "./middleware.js";
 import { runMiddleware } from "./middleware.js";
 import type { PageMetadata } from "../types/index.js";
 import { checkRevalidateAuth, applyRevalidate } from "./revalidate.js";
+import { applyCdnHeaders, type CdnCache } from "./cdn.js";
+import { getPPRShell, injectBuildIdIntoPPRShell, PPR_CACHE_SUBDIR } from "../ssr/ppr.js";
 
 /**
  * Find layout file paths (relative to cwd root) for a given route.file, ordered outermost→innermost.
@@ -75,6 +77,17 @@ export function createApp(manifest: RouteManifest, distDir: string): AlabApp {
   const router = createRouter();
   const publicDir = resolve(distDir, "../../public");
 
+  // Load the build ID written by `alab build` for skew protection.
+  // If the file is absent (first-run / non-standard setup) skew detection
+  // is silently disabled — existing behaviour is unchanged.
+  let buildId: string | undefined;
+  try {
+    buildId = readFileSync(resolve(distDir, "BUILD_ID"), "utf8").trim() || undefined;
+  } catch { /* no BUILD_ID file — skew protection disabled */ }
+
+  // Absolute path to the PPR shell cache directory.
+  const pprCacheDir = resolve(distDir, "../../", PPR_CACHE_SUBDIR);
+
   // ─── Global middleware ───────────────────────────────────────────────────────
   app.use(
     defineEventHandler((event) => {
@@ -319,12 +332,14 @@ export function createApp(manifest: RouteManifest, distDir: string): AlabApp {
       defineEventHandler(async (event) => {
         const res = event.node.res;
 
-        // HTML pages must not be cached by intermediaries — they contain
-        // user-specific CSRF tokens and may reflect auth state.
-        res.setHeader("cache-control", "no-store");
-
-        // Set CSRF cookie so the client can send it on mutations.
-        const csrfToken = setCsrfCookie(event);
+        // Skew protection: tell the client which build this server is running.
+        if (buildId) {
+          res.setHeader("x-alab-build-id", buildId);
+          const clientBuildId = event.node.req.headers["x-alab-build-id"];
+          if (clientBuildId && clientBuildId !== buildId) {
+            res.setHeader("x-alab-revalidate", "1");
+          }
+        }
 
         const rawParams = (event.context.params ?? {}) as Record<string, string>;
         const params = rawParams;
@@ -342,6 +357,8 @@ export function createApp(manifest: RouteManifest, distDir: string): AlabApp {
           metadata?: PageMetadata;
           generateMetadata?: (params: Record<string, string>) => PageMetadata | Promise<PageMetadata>;
           ssr?: boolean;
+          cdnCache?: CdnCache;
+          ppr?: boolean;
         };
 
         const Page = mod.default;
@@ -351,6 +368,31 @@ export function createApp(manifest: RouteManifest, distDir: string): AlabApp {
           return;
         }
 
+        // ── PPR: serve pre-rendered static shell ──────────────────────────────
+        // Pages with `export const ppr = true` get a static HTML shell built
+        // at `alab build` time. Serve it instantly with a long CDN TTL so the
+        // static portion is edge-cached. Dynamic sections (`<Dynamic>`) render
+        // their fallback in the shell and are filled in client-side via React
+        // hydration, or server-side via Suspense streaming on direct hits.
+        if (mod.ppr === true) {
+          let shell = getPPRShell(route.path, pprCacheDir);
+          if (shell !== null) {
+            // Inject the per-build skew-protection tag into the pre-rendered HTML.
+            if (buildId) shell = injectBuildIdIntoPPRShell(shell, buildId);
+
+            res.statusCode = 200;
+            res.setHeader("content-type", "text/html; charset=utf-8");
+            // Long CDN TTL: static shell doesn't change until the next build.
+            res.setHeader("cache-control", "public, s-maxage=3600, stale-while-revalidate=86400");
+            res.setHeader("x-alab-ppr", "shell");
+            if (buildId) res.setHeader("x-alab-build-id", buildId);
+            res.end(shell);
+            return;
+          }
+          // Shell not found — fall through to normal SSR and warn once.
+          console.warn(`[alabjs] ppr: no pre-rendered shell for ${route.path} — run \`alab build\` to generate it. Falling back to SSR.`);
+        }
+
         // Support both static metadata and dynamic generateMetadata (production fix)
         const metadata: PageMetadata =
           typeof mod.generateMetadata === "function"
@@ -369,8 +411,20 @@ export function createApp(manifest: RouteManifest, distDir: string): AlabApp {
         const layoutsJson = JSON.stringify(layoutRelPaths);
         const loadingFile = findProdLoadingFile(route.file, distDir) ?? undefined;
 
-        // Inject CSRF token into the HTML head so client JS can read it.
-        const headExtra = `<meta name="csrf-token" content="${csrfToken.replace(/"/g, "&quot;")}" />`;
+        // ── Cache-control + CSRF ──────────────────────────────────────────────
+        // Pages that export `cdnCache` are public, edge-cacheable pages.
+        // They get CDN headers instead of `no-store`, and CSRF tokens are
+        // omitted — a shared cache would deliver the same token to every
+        // visitor, defeating CSRF protection.
+        let headExtra = "";
+        if (mod.cdnCache) {
+          applyCdnHeaders(res, mod.cdnCache);
+        } else {
+          // Private page: must not be cached by intermediaries.
+          res.setHeader("cache-control", "no-store");
+          const csrfToken = setCsrfCookie(event);
+          headExtra = `<meta name="csrf-token" content="${csrfToken.replace(/"/g, "&quot;")}" />`;
+        }
 
         try {
           renderToResponse(res, {
@@ -384,6 +438,7 @@ export function createApp(manifest: RouteManifest, distDir: string): AlabApp {
             loadingFile,
             ssr: ssrEnabled,
             headExtra,
+            ...(buildId ? { buildId } : {}),
           });
         } catch (err) {
           // ── error.tsx fallback ────────────────────────────────────────────

package/src/server/cdn.ts

@@ -0,0 +1,187 @@
+/**
+ * CDN cache header utilities for Alab.
+ *
+ * Pages that export `const cdnCache: CdnCache = { ... }` are opt-in public,
+ * edge-cached pages. Alab sets response headers so any CDN or shared proxy
+ * (Cloudflare, Fastly, Varnish, Nginx, AWS CloudFront) can cache them without
+ * Vercel.
+ *
+ * ## Configuration
+ *
+ * Set `ALAB_CDN` in your environment to enable vendor-specific headers:
+ *
+ *   | Value        | Extra headers set                               |
+ *   |--------------|-------------------------------------------------|
+ *   | `cloudflare` | `CDN-Cache-Control`, `Cache-Tag`                |
+ *   | `fastly`     | `Surrogate-Control`, `Surrogate-Key`            |
+ *   | (unset)      | Universal `Cache-Control: public, s-maxage=N` only |
+ *
+ * ## Tag-based purge credentials
+ *
+ *   - Cloudflare: `CF_ZONE_ID` + `CF_API_TOKEN`
+ *   - Fastly:     `FASTLY_SERVICE_ID` + `FASTLY_API_KEY`
+ *
+ * ## Important
+ *
+ * CDN-cached pages are **public pages** — they must not contain user-specific
+ * state. Alab automatically skips CSRF token injection for pages that export
+ * `cdnCache` because a shared cache would hand the same token to every visitor,
+ * which defeats CSRF protection.
+ */
+
+import type { ServerResponse } from "node:http";
+
+// ─── Public type ──────────────────────────────────────────────────────────────
+
+export interface CdnCache {
+  /** Seconds the CDN / shared proxy may cache this response. */
+  maxAge: number;
+  /**
+   * Seconds the CDN may continue serving a stale response while it
+   * revalidates the entry in the background (stale-while-revalidate).
+   * Defaults to `maxAge` when omitted.
+   */
+  swr?: number;
+  /**
+   * Cache tags for targeted invalidation via `POST /_alabjs/revalidate`.
+   *
+   * - Cloudflare: emitted as `Cache-Tag: tag1,tag2`
+   * - Fastly / Varnish: emitted as `Surrogate-Key: tag1 tag2`
+   *
+   * @example
+   * export const cdnCache: CdnCache = {
+   *   maxAge: 60,
+   *   tags: ["posts", "post:42"],
+   * };
+   */
+  tags?: readonly string[];
+}
+
+// ─── Internal ─────────────────────────────────────────────────────────────────
+
+type CdnProvider = "cloudflare" | "fastly" | "none";
+
+function detectProvider(): CdnProvider {
+  switch (process.env["ALAB_CDN"]?.toLowerCase()) {
+    case "cloudflare": return "cloudflare";
+    case "fastly":     return "fastly";
+    default:           return "none";
+  }
+}
+
+// ─── Header helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Set CDN-appropriate response headers for a page that opts in to edge caching
+ * via `export const cdnCache = { ... }`.
+ *
+ * Always emits the universal `Cache-Control: public, s-maxage=N,
+ * stale-while-revalidate=M` header. Vendor-specific headers are added when
+ * `ALAB_CDN` is set.
+ */
+export function applyCdnHeaders(res: ServerResponse, cdnCache: CdnCache): void {
+  const { maxAge, swr = maxAge, tags = [] } = cdnCache;
+
+  // Universal — honoured by every shared proxy, CDN, and browser.
+  res.setHeader(
+    "cache-control",
+    `public, s-maxage=${maxAge}, stale-while-revalidate=${swr}`,
+  );
+
+  const provider = detectProvider();
+
+  if (provider === "cloudflare") {
+    // Cloudflare reads CDN-Cache-Control with higher priority than Cache-Control,
+    // allowing different TTLs at the edge vs. the browser.
+    res.setHeader("cdn-cache-control", `max-age=${maxAge}`);
+    if (tags.length > 0) {
+      // Cache-Tag enables Cloudflare tag-based purge via their API.
+      res.setHeader("cache-tag", [...tags].join(","));
+    }
+  } else if (provider === "fastly") {
+    // Surrogate-Control is stripped by Fastly before forwarding to the browser,
+    // so it can hold a much larger TTL than Cache-Control safely.
+    res.setHeader("surrogate-control", `max-age=${maxAge}`);
+    if (tags.length > 0) {
+      // Surrogate-Key is Fastly's mechanism for instant surrogate-key purge.
+      res.setHeader("surrogate-key", [...tags].join(" "));
+    }
+  }
+}
+
+// ─── CDN purge ────────────────────────────────────────────────────────────────
+
+/**
+ * Purge CDN cache entries by tag.
+ *
+ * Called from `/_alabjs/revalidate` **after** the in-process cache has been
+ * cleared. Silently no-ops when `ALAB_CDN` is not configured or the required
+ * credentials are absent — the TTL will expire the CDN entry naturally.
+ */
+export async function purgeCdnByTags(tags: readonly string[]): Promise<void> {
+  if (tags.length === 0) return;
+
+  switch (detectProvider()) {
+    case "cloudflare": await purgeCloudflare(tags); break;
+    case "fastly":     await purgeFastly(tags);     break;
+    // "none": no CDN purge needed — in-process cache already cleared.
+  }
+}
+
+async function purgeCloudflare(tags: readonly string[]): Promise<void> {
+  const zoneId   = process.env["CF_ZONE_ID"];
+  const apiToken = process.env["CF_API_TOKEN"];
+
+  if (!zoneId || !apiToken) {
+    console.warn(
+      "[alabjs] CDN purge: ALAB_CDN=cloudflare but CF_ZONE_ID or CF_API_TOKEN is not set — skipping.",
+    );
+    return;
+  }
+
+  const res = await fetch(
+    `https://api.cloudflare.com/client/v4/zones/${zoneId}/purge_cache`,
+    {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${apiToken}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ tags: [...tags] }),
+    },
+  );
+
+  if (!res.ok) {
+    console.error(`[alabjs] Cloudflare cache purge failed (${res.status}): ${await res.text()}`);
+  }
+}
+
+async function purgeFastly(tags: readonly string[]): Promise<void> {
+  const serviceId = process.env["FASTLY_SERVICE_ID"];
+  const apiKey    = process.env["FASTLY_API_KEY"];
+
+  if (!serviceId || !apiKey) {
+    console.warn(
+      "[alabjs] CDN purge: ALAB_CDN=fastly but FASTLY_SERVICE_ID or FASTLY_API_KEY is not set — skipping.",
+    );
+    return;
+  }
+
+  // Fastly instant purge by surrogate key (POST /service/{id}/purge with
+  // Surrogate-Key header containing space-separated tags).
+  const res = await fetch(
+    `https://api.fastly.com/service/${serviceId}/purge`,
+    {
+      method: "POST",
+      headers: {
+        "fastly-key":    apiKey,
+        "surrogate-key": [...tags].join(" "),
+        accept:          "application/json",
+      },
+    },
+  );
+
+  if (!res.ok) {
+    console.error(`[alabjs] Fastly cache purge failed (${res.status}): ${await res.text()}`);
+  }
+}

package/src/server/revalidate.ts

@@ -25,6 +25,7 @@
  */
 
 import { revalidatePath, revalidatePathPrefix, revalidateTag } from "./cache.js";
+import { purgeCdnByTags } from "./cdn.js";
 
 export interface RevalidateBody {
   /** Purge a single cached page path. */
@@ -64,7 +65,12 @@ export function applyRevalidate(
 
   if (path) revalidatePath(path);
   if (prefix) revalidatePathPrefix(prefix);
-  if (tags?.length) revalidateTag({ tags });
+  if (tags?.length) {
+    revalidateTag({ tags });
+    // Fire-and-forget: CDN purge is best-effort. In-process cache is already
+    // cleared above, so a CDN miss will just hit the origin and re-warm the edge.
+    void purgeCdnByTags(tags);
+  }
 
   return {
     revalidated: true,

package/src/ssr/html.ts

@@ -18,6 +18,13 @@ export interface HtmlShellOptions {
   headExtra?: string | undefined;
   /** Nonce for CSP inline scripts (optional). */
   nonce?: string | undefined;
+  /**
+   * Build ID for skew protection.
+   * Injected as `<meta name="alabjs-build-id">` so the client SPA router can
+   * detect a deployment change mid-session and trigger a hard reload instead
+   * of swapping components in-place with mismatched JS chunks.
+   */
+  buildId?: string | undefined;
 }
 
 /** Build the opening HTML fragment — everything up to and including `<div id="alabjs-root">`. */
@@ -31,6 +38,7 @@ export function htmlShellBefore(opts: HtmlShellOptions): string {
     layoutsJson,
     loadingFile,
     headExtra = "",
+    buildId,
   } = opts;
 
   const titleTag = metadata.title
@@ -76,6 +84,7 @@ export function htmlShellBefore(opts: HtmlShellOptions): string {
     <meta name="alabjs-search-params" content="${escAttr(searchParamsJson)}" />
     ${layoutsJson ? `<meta name="alabjs-layouts" content="${escAttr(layoutsJson)}" />` : ""}
     ${loadingFile ? `<meta name="alabjs-loading" content="${escAttr(loadingFile)}" />` : ""}
+    ${buildId ? `<meta name="alabjs-build-id" content="${escAttr(buildId)}" />` : ""}
     <link rel="stylesheet" href="/app/globals.css" />
     ${headExtra}
   </head>

package/src/ssr/ppr.ts

@@ -0,0 +1,167 @@
+/**
+ * Alab PPR — build-time static shell pre-renderer and runtime shell reader.
+ *
+ * ## Build-time
+ * `preRenderPPRShell()` renders a page with `PPRShellProvider` so that every
+ * `<Dynamic>` emits a `data-ppr-hole` placeholder instead of its children.
+ * The resulting HTML is saved to `.alabjs/ppr-cache/<slug>.html`.
+ *
+ * ## Runtime
+ * `getPPRShell()` reads the pre-rendered HTML for a given route path, or
+ * returns `null` if the file doesn't exist (triggers SSR fallback).
+ */
+
+import { createElement, Suspense, type ComponentType } from "react";
+import { renderToPipeableStream } from "react-dom/server";
+import { Writable } from "node:stream";
+import { writeFileSync, mkdirSync, existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { PPRShellProvider } from "../components/Dynamic.js";
+import { htmlShellBefore, htmlShellAfter } from "./html.js";
+import type { HtmlShellOptions } from "./html.js";
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+/** Relative path (from cwd) where pre-rendered shells are written. */
+export const PPR_CACHE_SUBDIR = ".alabjs/ppr-cache";
+
+// ─── Filename helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Convert a route path to a safe filesystem filename (no leading slash, no
+ * dynamic segment brackets, slashes replaced with `__`).
+ *
+ * @example
+ * routeToFilename("/")                  → "index"
+ * routeToFilename("/posts")             → "posts"
+ * routeToFilename("/posts/[id]")        → "posts___id_"
+ * routeToFilename("/a/[b]/c/[d]")       → "a___b___c___d_"
+ */
+export function routeToFilename(routePath: string): string {
+  const slug = routePath
+    .replace(/^\//, "")                   // strip leading /
+    .replace(/\[([^\]]+)\]/g, "__$1_")    // [param] → __param_
+    .replace(/\//g, "__");                // / → __
+  return (slug || "index") + ".html";
+}
+
+// ─── Build-time ───────────────────────────────────────────────────────────────
+
+export interface PPRPreRenderOptions {
+  /** Default component to render (page default export). */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  Page: ComponentType<any>;
+  /** Layout components, outermost → innermost. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  layouts: ComponentType<any>[];
+  /** Options forwarded to `htmlShellBefore` (minus `headExtra`). */
+  shellOpts: Omit<HtmlShellOptions, "headExtra">;
+  /** Absolute path to the PPR cache directory. */
+  pprCacheDir: string;
+  /** Alab route path, e.g. `"/posts/[id]"`. */
+  routePath: string;
+}
+
+/**
+ * Pre-render the static HTML shell for a PPR page and persist it to disk.
+ *
+ * The render uses `PPRShellProvider` so every `<Dynamic>` in the tree emits
+ * a `data-ppr-hole` placeholder — children (per-request logic) are omitted.
+ *
+ * Called from `alab build` after the Vite bundle step completes.
+ */
+export async function preRenderPPRShell({
+  Page,
+  layouts,
+  shellOpts,
+  pprCacheDir,
+  routePath,
+}: PPRPreRenderOptions): Promise<void> {
+  // Build the element tree: layouts wrapping Page, all inside PPRShellProvider.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let pageEl: any = createElement(Page, { params: {}, searchParams: {} });
+  // Suspense wrapper guards against any accidental top-level suspension.
+  pageEl = createElement(Suspense, { fallback: null }, pageEl);
+  for (let i = layouts.length - 1; i >= 0; i--) {
+    const Layout = layouts[i];
+    if (Layout) pageEl = createElement(Layout, {}, pageEl);
+  }
+  // PPRShellProvider switches Dynamic into placeholder mode.
+  // Pass children via props to satisfy strict TS prop checking.
+  const tree = createElement(PPRShellProvider, { children: pageEl });
+
+  // Wait for the full render (allReady) — we need a complete snapshot, not a
+  // partially streamed response, because the file is served as-is from disk.
+  const reactHtml = await new Promise<string>((resolve, reject) => {
+    let result = "";
+    const sink = new Writable({
+      write(chunk: Buffer, _enc, cb) { result += chunk.toString(); cb(); },
+      final(cb) { resolve(result); cb(); },
+    });
+    const { pipe } = renderToPipeableStream(tree, {
+      onAllReady() { pipe(sink); },
+      onError(err)  { reject(err instanceof Error ? err : new Error(String(err))); },
+    });
+  });
+
+  const before = htmlShellBefore({ ...shellOpts, headExtra: "" });
+  const after  = htmlShellAfter({});
+  const fullHtml = `${before}${reactHtml}${after}`;
+
+  mkdirSync(pprCacheDir, { recursive: true });
+  writeFileSync(join(pprCacheDir, routeToFilename(routePath)), fullHtml, "utf8");
+}
+
+// ─── Runtime ──────────────────────────────────────────────────────────────────
+
+/**
+ * Return the pre-rendered static HTML shell for `routePath`, or `null` if the
+ * cache file doesn't exist.
+ *
+ * Callers should fall back to normal SSR when `null` is returned.
+ */
+export function getPPRShell(routePath: string, pprCacheDir: string): string | null {
+  const filePath = join(pprCacheDir, routeToFilename(routePath));
+  try {
+    return existsSync(filePath) ? readFileSync(filePath, "utf8") : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Inject a `<meta name="alabjs-build-id">` tag into a pre-rendered PPR shell.
+ *
+ * The shell is pre-built and therefore doesn't include the per-build ID. We
+ * splice it in at serve time so skew protection still works for PPR pages.
+ */
+export function injectBuildIdIntoPPRShell(html: string, buildId: string): string {
+  const tag = `<meta name="alabjs-build-id" content="${buildId.replace(/"/g, "&quot;")}" />`;
+  // Insert after <head> if present; otherwise prepend to <html>.
+  const headClose = html.indexOf("</head>");
+  if (headClose !== -1) {
+    return html.slice(0, headClose) + `  ${tag}\n` + html.slice(headClose);
+  }
+  return tag + html;
+}
+
+// ─── Layout discovery (prod) ──────────────────────────────────────────────────
+
+/**
+ * Find layout file paths for a given page route file, ordered
+ * outermost → innermost. Mirrors the logic in `app.ts` but scoped to the
+ * build-time dist directory.
+ */
+export function findBuildLayoutFiles(routeFile: string, distDir: string): string[] {
+  const pageDir = dirname(routeFile);
+  const parts = pageDir.split("/");
+  const layouts: string[] = [];
+  for (let i = 1; i <= parts.length; i++) {
+    const dir = parts.slice(0, i).join("/");
+    const candidate = `${dir}/layout.tsx`;
+    if (existsSync(join(distDir, "server", candidate))) {
+      layouts.push(candidate);
+    }
+  }
+  return layouts;
+}

package/src/ssr/render.ts

@@ -29,6 +29,8 @@ export interface RenderOptions {
   headExtra?: string;
   /** CSP nonce (optional). */
   nonce?: string;
+  /** Build ID for skew protection (see html.ts). */
+  buildId?: string;
 }
 
 /**
@@ -50,6 +52,7 @@ export function renderToResponse(res: ServerResponse, opts: RenderOptions): void
     ssr,
     headExtra,
     nonce,
+    buildId,
   } = opts;
 
   const shellOpts: HtmlShellOptions = {
@@ -62,6 +65,7 @@ export function renderToResponse(res: ServerResponse, opts: RenderOptions): void
     ssr,
     headExtra,
     nonce,
+    buildId,
   };
 
   const before = htmlShellBefore(shellOpts);

package/src/types/index.ts

@@ -145,3 +145,26 @@ export type GenerateMetadata<Path extends string = string> = (props: {
   readonly params: RouteParams<Path>;
   readonly searchParams: Readonly<Record<string, string | readonly string[]>>;
 }) => Promise<PageMetadata> | PageMetadata;
+
+// ─── CDN cache ─────────────────────────────────────────────────────────────────
+
+/**
+ * Export `cdnCache` from a page to let any CDN or shared proxy cache it at
+ * the edge — no Vercel required.
+ *
+ * @example
+ * // app/posts/[id]/page.tsx
+ * import type { CdnCache } from "alabjs";
+ *
+ * export const cdnCache: CdnCache = {
+ *   maxAge: 60,          // CDN keeps the page for 60 s
+ *   swr: 30,             // serve stale for 30 s while revalidating
+ *   tags: ["posts", "post:42"],  // invalidate via /_alabjs/revalidate
+ * };
+ *
+ * @remarks
+ * CDN-cached pages are **public pages** — Alab skips CSRF token injection for
+ * them because a shared cache would hand the same token to every visitor.
+ * Do not use `cdnCache` on pages that contain user-specific state.
+ */
+export type { CdnCache } from "../server/cdn.js";