akanjs 2.2.13-rc.0 → 2.3.0

package/server/ssrFromRscRenderer.tsx

@@ -1,5 +1,5 @@
 import { Readable } from "node:stream";
-import { type AkanTheme, pushRequestFallback, requestStorage } from "akanjs/fetch";
+import { type AkanRequestStore, type AkanTheme, pushRequestFallback, requestStorage } from "akanjs/fetch";
 import { type ReactNode, use } from "react";
 import { renderToReadableStream } from "react-dom/server.browser";
 import { createFromNodeStream } from "react-server-dom-webpack/client.node";
@@ -109,9 +109,14 @@ export function createInlineRscScript(chunk: Uint8Array): string {
   return `<script>self.__RSC_PUSH__(${type},${htmlEscapeJsonString(data)})</script>`;
 }
 
+function escapeHtmlAttr(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
 export function createSoftRedirectScript(redirect: SsrLateRedirect): string {
   const method = redirect.method === "push" ? "assign" : "replace";
-  return `<script>window.location.${method}(${htmlEscapeJsonString(redirect.location)})</script>`;
+  const fallback = `<noscript><meta http-equiv="refresh" content="0;url=${escapeHtmlAttr(redirect.location)}"></noscript>`;
+  return `${fallback}<script>window.location.${method}(${htmlEscapeJsonString(redirect.location)})</script>`;
 }
 
 function sanitizeFlightRows(
@@ -121,7 +126,7 @@ function sanitizeFlightRows(
   const decoder = new TextDecoder("utf-8", { fatal: true });
   const encoder = new TextEncoder();
   const hlStylesheetRe = /(:HL\["[^"\\]*(?:\\.[^"\\]*)*",)"stylesheet"(\])/g;
-  const redirectErrorRowRe = /^([0-9a-z]+):E(\{[^\n]*"digest":"AKAN_REDIRECT"[^\n]*\})(\n?)$/;
+  const redirectErrorRowRe = /^([0-9a-z]+):E(\{[^\n]*"digest":"AKAN_REDIRECT(?:;[^"]*)?"[^\n]*\})(\n?)$/;
   let buffered: Uint8Array<ArrayBuffer> = new Uint8Array(0);
 
   const concatBytes = (left: Uint8Array, right: Uint8Array): Uint8Array<ArrayBuffer> => {
@@ -335,6 +340,7 @@ export function interleaveRscScriptsWithHtml(
     onComplete?: () => void;
     onCancel?: (reason?: unknown) => void;
     request?: Request;
+    requestStore?: AkanRequestStore;
   } = {},
 ): ReadableStream<Uint8Array> {
   const encoder = new TextEncoder();
@@ -464,7 +470,8 @@ export function interleaveRscScriptsWithHtml(
       };
 
       const runPump = () => {
-        const cleanup = options.request ? pushRequestFallback(options.request) : undefined;
+        const requestContext = options.requestStore ?? options.request;
+        const cleanup = requestContext ? pushRequestFallback(requestContext) : undefined;
         return pump()
           .catch(fail)
           .finally(() => {
@@ -472,7 +479,8 @@ export function interleaveRscScriptsWithHtml(
             options.onComplete?.();
           });
       };
-      if (options.request && requestStorage) void requestStorage.run(options.request, runPump);
+      const requestContext = options.requestStore ?? options.request;
+      if (requestContext && requestStorage) void requestStorage.run(requestContext, runPump);
       else void runPump();
     },
     cancel(reason) {
@@ -589,8 +597,9 @@ export class SsrFromRscRenderer {
       renderToReadableStream(<Root />, {
         bootstrapScriptContent: bootstrap,
       });
+    const requestContext = input.requestStore ?? input.request;
     const htmlStream =
-      input.request && requestStorage ? await requestStorage.run(input.request, renderHtml) : await renderHtml();
+      requestContext && requestStorage ? await requestStorage.run(requestContext, renderHtml) : await renderHtml();
 
     const withHeadScripts = SsrFromRscRenderer.#injectHeadScriptsIntoHead(htmlStream, {
       importmap: input.importmap,
@@ -604,6 +613,7 @@ export class SsrFromRscRenderer {
       SsrFromRscRenderer.#sanitizeFlightForClient(rscForClient),
       input.bootstrapModules,
       input.request,
+      input.requestStore,
       input.lateControl,
       () => stderrSuppressor?.stop(),
       input.onCancel,
@@ -771,6 +781,7 @@ export class SsrFromRscRenderer {
     rscClientStream: ReadableStream<Uint8Array>,
     bootstrapModules?: string[],
     request?: Request,
+    requestStore?: AkanRequestStore,
     lateControl?: Promise<SsrLateRedirect | null>,
     onComplete?: () => void,
     onCancel?: (reason?: unknown) => void,
@@ -783,6 +794,7 @@ export class SsrFromRscRenderer {
       onComplete,
       onCancel,
       request,
+      requestStore,
     });
   }
 }

package/server/ssrTypes.ts

@@ -1,4 +1,4 @@
-import type { AkanTheme } from "akanjs/fetch";
+import type { AkanRequestStore, AkanTheme } from "akanjs/fetch";
 
 export interface SsrManifestEntry {
   id: string;
@@ -28,6 +28,7 @@ export interface SsrLateRedirect {
 
 export interface SsrFromRscInput {
   request?: Request;
+  requestStore?: AkanRequestStore;
   rscStream: ReadableStream<Uint8Array>;
   ssrManifest: SsrManifest;
   bootstrapModules?: string[];

package/server/webRouter.ts

@@ -8,7 +8,7 @@ import {
   Logger,
   parseAkanI18nEnv,
 } from "akanjs/common";
-import { parseCookieHeader } from "akanjs/fetch";
+import { type AkanRequestStore, createRequestStore, parseCookieHeader } from "akanjs/fetch";
 import type { AkanMetricsReport } from "akanjs/service";
 import {
   type BuilderRpc,
@@ -17,6 +17,19 @@ import {
   RouteSeedIndexStore,
   RoutesManifestStore,
 } from "./artifact";
+import {
+  createRouteCacheEntry,
+  getClientFacingOrigin,
+  isPublicRouteCacheableRequest,
+  isRouteCachePathAllowed,
+  LruTtlCache,
+  normalizeRouteCacheTtl,
+  parsePositiveInt,
+  type RouteCacheEntry,
+  type RouteCacheRenderState,
+  resolveRouteCacheStoreTtl,
+  shouldStoreRouteCache,
+} from "./cachePolicy";
 import { DevHmrController } from "./hmr";
 import { HMR_CLIENT_SCRIPT } from "./hmr/clientScript";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub";
@@ -57,22 +70,36 @@ export function createRscStreamResponse(stream: BodyInit, status = 200): Respons
   });
 }
 
+export function createRscNotFoundFallbackResponse(): Response {
+  return createRscStreamResponse("0:null\n", 404);
+}
+
 export function cacheHtmlWhileStreaming(
   stream: ReadableStream<Uint8Array>,
   onComplete: (html: string) => void,
+  options: { shouldCache?: () => boolean | Promise<boolean>; maxBodyBytes?: number | null } = {},
 ): ReadableStream<Uint8Array> {
   const chunks: Uint8Array[] = [];
   let byteLength = 0;
+  let exceededMaxBodyBytes = false;
   const decoder = new TextDecoder();
 
   return stream.pipeThrough(
     new TransformStream<Uint8Array, Uint8Array>({
       transform(chunk, controller) {
-        chunks.push(chunk.slice());
-        byteLength += chunk.byteLength;
+        if (!exceededMaxBodyBytes) {
+          byteLength += chunk.byteLength;
+          if (options.maxBodyBytes && byteLength > options.maxBodyBytes) {
+            exceededMaxBodyBytes = true;
+            chunks.length = 0;
+          } else {
+            chunks.push(chunk.slice());
+          }
+        }
         controller.enqueue(chunk);
       },
-      flush() {
+      async flush() {
+        if (exceededMaxBodyBytes) return;
         const body = new Uint8Array(byteLength);
         let offset = 0;
         for (const chunk of chunks) {
@@ -80,6 +107,7 @@ export function cacheHtmlWhileStreaming(
           offset += chunk.byteLength;
         }
         try {
+          if (options.shouldCache && !(await options.shouldCache())) return;
           onComplete(decoder.decode(body));
         } catch {
         }
@@ -93,34 +121,41 @@ export function cancelStreamForHeadResponse(stream: ReadableStream<Uint8Array>,
   });
 }
 
+export function resolveHtmlRouteCacheStoreTtl(input: {
+  baseTtl: number;
+  workerCacheState: RouteCacheRenderState;
+  hostRequestStore: AkanRequestStore;
+  lateControl?: { type: "redirect" } | null;
+}): number | null {
+  if (input.lateControl?.type === "redirect") return null;
+  const workerTtl = resolveRouteCacheStoreTtl(input.baseTtl, input.workerCacheState);
+  if (workerTtl === null) return null;
+  const hostCacheState = shouldStoreRouteCache({
+    policy: input.hostRequestStore.policy,
+    dynamicUsage: input.hostRequestStore.dynamicUsage,
+  });
+  return resolveRouteCacheStoreTtl(workerTtl, hostCacheState);
+}
+
+export function isHtmlRouteCachePathAllowed(
+  pathname: string,
+  env: {
+    [key: string]: string | undefined;
+    AKAN_HTML_RESULT_CACHE_PATHS?: string;
+    AKAN_HTML_RESULT_CACHE_EXCLUDE_PATHS?: string;
+  } = process.env as Record<string, string | undefined>,
+): boolean {
+  return isRouteCachePathAllowed(pathname, {
+    allow: env.AKAN_HTML_RESULT_CACHE_PATHS,
+    deny: env.AKAN_HTML_RESULT_CACHE_EXCLUDE_PATHS,
+  });
+}
+
 export async function createRscNavigationStreamResponse(
   result: Extract<RscRenderResult, { type: "stream" }>,
 ): Promise<Response> {
 
-  const chunks: Uint8Array[] = [];
-  let byteLength = 0;
-  const reader = result.stream.getReader();
-  try {
-    while (true) {
-      const { value, done } = await reader.read();
-      if (done) break;
-      chunks.push(value);
-      byteLength += value.byteLength;
-    }
-  } finally {
-    reader.releaseLock();
-  }
-
-  const lateControl = await result.lateControl;
-  if (lateControl?.type === "redirect")
-    return createRscRedirectResponse(lateControl.location, lateControl.method, lateControl.status);
-  const body = new Uint8Array(byteLength);
-  let offset = 0;
-  for (const chunk of chunks) {
-    body.set(chunk, offset);
-    offset += chunk.byteLength;
-  }
-  return createRscStreamResponse(body, result.status ?? 200);
+  return createRscStreamResponse(result.stream, result.status ?? 200);
 }
 
 export function normalizeRscTargetUrlForHostBasePath(
@@ -173,7 +208,6 @@ interface WebRouterOptions {
 }
 
 interface CachedHtmlResult {
-  expiresAt: number;
   html: string;
 }
 
@@ -194,7 +228,9 @@ export class WebRouter {
     csr: 0,
     image: 0,
   };
-  readonly #htmlCache = new Map<string, CachedHtmlResult>();
+  readonly #htmlCache = new LruTtlCache<CachedHtmlResult>(
+    parsePositiveInt(process.env.AKAN_HTML_RESULT_CACHE_MAX_ENTRIES) ?? 100,
+  );
   #htmlCacheHits = 0;
   #htmlCacheMisses = 0;
   #htmlCacheBypass = 0;
@@ -444,8 +480,8 @@ export class WebRouter {
         try {
           this.#requestStats.fullSsr += 1;
           const manifest = await this.#ensureRoute(url);
-          const htmlCacheKey = this.#getHtmlCacheKey(req, url);
-          const cachedHtml = htmlCacheKey ? this.#getCachedHtml(htmlCacheKey) : null;
+          const htmlCacheEntry = this.#getHtmlCacheEntry(req, url);
+          const cachedHtml = htmlCacheEntry ? this.#getCachedHtml(htmlCacheEntry.key) : null;
           if (cachedHtml) {
             return new Response(cachedHtml, {
               headers: {
@@ -462,8 +498,10 @@ export class WebRouter {
             return Response.redirect(new URL(rscResult.location, url.origin), rscResult.status);
           if (rscResult.type === "not-found") return this.#renderNotFoundResponse(req, url);
           const themeCookieExists = WebRouter.#hasCookie(req, "theme");
+          const hostRequestStore = createRequestStore(req);
           const htmlStream = await new SsrFromRscRenderer().render({
             request: req,
+            requestStore: hostRequestStore,
             rscStream: rscResult.stream,
             ssrManifest: manifest.ssrManifest,
             bootstrapModules: [this.#artifact.rscClientUrl],
@@ -471,7 +509,7 @@ export class WebRouter {
             importmap: this.#artifact.vendorMap,
             theme: themeCookieExists ? undefined : (rscResult.theme ?? "system"),
             lateControl: rscResult.lateControl,
-            onCancel: (reason) => {
+            onCancel: (reason: unknown) => {
               rscResult.cancel(reason);
             },
           });
@@ -479,17 +517,38 @@ export class WebRouter {
           const responseHeaders = WebRouter.#htmlResponseHeaders(responseStatus);
           if (req.method === "HEAD") {
             const headers = new Headers(responseHeaders);
-            if (htmlCacheKey && responseStatus === 200) headers.set("X-Akan-Cache", "MISS");
+            if (htmlCacheEntry && responseStatus === 200) headers.set("X-Akan-Cache", "MISS");
             cancelStreamForHeadResponse(htmlStream, new Error("HEAD response does not consume body"));
             return new Response(null, { status: responseStatus, headers });
           }
-          if (htmlCacheKey && responseStatus === 200) {
+          if (htmlCacheEntry && responseStatus === 200) {
             const headers = new Headers(responseHeaders);
             headers.set("X-Akan-Cache", "MISS");
+            let htmlStoreTtl = htmlCacheEntry.ttl;
+            const shouldCacheHtml = Promise.all([rscResult.lateControl, rscResult.cacheState]).then(
+              ([control, cacheState]) => {
+                const storeTtl = resolveHtmlRouteCacheStoreTtl({
+                  baseTtl: htmlCacheEntry.ttl,
+                  workerCacheState: cacheState,
+                  hostRequestStore,
+                  lateControl: control,
+                });
+                if (storeTtl === null) return false;
+                htmlStoreTtl = storeTtl;
+                return true;
+              },
+            );
             return new Response(
-              cacheHtmlWhileStreaming(htmlStream, (html) => {
-                this.#setCachedHtml(htmlCacheKey, html);
-              }),
+              cacheHtmlWhileStreaming(
+                htmlStream,
+                (html) => {
+                  this.#setCachedHtml(htmlCacheEntry.key, html, htmlStoreTtl);
+                },
+                {
+                  shouldCache: () => shouldCacheHtml,
+                  maxBodyBytes: parsePositiveInt(process.env.AKAN_HTML_RESULT_CACHE_MAX_BODY_BYTES),
+                },
+              ),
               {
                 status: responseStatus,
                 headers,
@@ -533,23 +592,19 @@ export class WebRouter {
       httpHtmlCacheBypass: this.#htmlCacheBypass,
     };
   }
+
+  /** @internal Clears local route result caches owned by the host and RSC worker. */
+  invalidateRouteCaches(reason?: string): void {
+    this.#htmlCache.clear();
+    this.#rsc.invalidateRouteResultCache(reason);
+  }
+
   /**
    * Reconstruct origin as the browser saw it when behind Ingress / reverse proxies
    * (prevents `/__rsc` same-origin rejecting because `req.url` is internal).
    */
   static #clientFacingOrigin(req: Request): string {
-    const parsed = new URL(req.url);
-    const fwdProto = req.headers.get("x-forwarded-proto")?.split(",")[0]?.trim();
-    const fwdHost = req.headers.get("x-forwarded-host")?.split(",")[0]?.trim();
-    const hostFallback = fwdHost ?? req.headers.get("host");
-    const protoFallback = fwdProto ?? parsed.protocol.slice(0, -1); 
-    if (hostFallback && protoFallback) {
-      try {
-        return new URL(`${protoFallback}://${hostFallback}`).origin;
-      } catch {
-      }
-    }
-    return parsed.origin;
+    return getClientFacingOrigin(req);
   }
 
   static #basePathForRequestHost(req: Request, subRoutes: Record<string, string[]>): string | null {
@@ -576,33 +631,25 @@ export class WebRouter {
   static #hasCookie(req: Request, name: string): boolean {
     return parseCookieHeader(req.headers.get("cookie") ?? "").has(name);
   }
-  #getHtmlCacheKey(req: Request, url: URL): string | null {
+  #getHtmlCacheEntry(req: Request, url: URL): RouteCacheEntry | null {
     if (!this.#prodMode || process.env.AKAN_HTML_RESULT_CACHE !== "1") {
       this.#htmlCacheBypass += 1;
       return null;
     }
-    if (!WebRouter.#isPublicCacheableRequest(req)) {
+    if (!isPublicRouteCacheableRequest(req)) {
       this.#htmlCacheBypass += 1;
       return null;
     }
-    if (!WebRouter.#isHtmlCachePathAllowed(url.pathname)) {
+    if (!isHtmlRouteCachePathAllowed(url.pathname)) {
       this.#htmlCacheBypass += 1;
       return null;
     }
-    const ttl = WebRouter.#htmlCacheTtlSeconds();
-    if (ttl <= 0) {
+    const ttl = normalizeRouteCacheTtl(process.env.AKAN_HTML_RESULT_CACHE_TTL);
+    if (ttl === null) {
       this.#htmlCacheBypass += 1;
       return null;
     }
-    return [
-      WebRouter.#clientFacingOrigin(req),
-      req.headers.get("x-base-path") ?? "",
-      url.pathname,
-      url.search,
-      req.headers.get("accept-language") ?? "",
-      WebRouter.#cookieValue(req, "theme") ?? "",
-      ttl,
-    ].join("\n");
+    return createRouteCacheEntry({ request: req, url, theme: WebRouter.#cookieValue(req, "theme"), ttl });
   }
 
   #getCachedHtml(cacheKey: string): string | null {
@@ -611,58 +658,18 @@ export class WebRouter {
       this.#htmlCacheMisses += 1;
       return null;
     }
-    if (cached.expiresAt <= Date.now()) {
-      this.#htmlCache.delete(cacheKey);
-      this.#htmlCacheMisses += 1;
-      return null;
-    }
     this.#htmlCacheHits += 1;
     return cached.html;
   }
 
-  #setCachedHtml(cacheKey: string, html: string): void {
-    const ttl = Number.parseInt(cacheKey.split("\n").at(-1) ?? "30", 10);
-    const maxEntries = WebRouter.#positiveIntEnv("AKAN_HTML_RESULT_CACHE_MAX_ENTRIES") ?? 100;
-    while (this.#htmlCache.size >= maxEntries) {
-      const firstKey = this.#htmlCache.keys().next().value;
-      if (!firstKey) break;
-      this.#htmlCache.delete(firstKey);
-    }
-    this.#htmlCache.set(cacheKey, { html, expiresAt: Date.now() + ttl * 1000 });
+  #setCachedHtml(cacheKey: string, html: string, ttl: number): void {
+    this.#htmlCache.set(cacheKey, { html }, ttl);
   }
 
   static #cookieValue(req: Request, name: string): string | undefined {
     return parseCookieHeader(req.headers.get("cookie") ?? "").get(name)?.value;
   }
 
-  static #isPublicCacheableRequest(req: Request): boolean {
-    if (req.method !== "GET") return false;
-    if (req.headers.has("authorization")) return false;
-    const cookie = req.headers.get("cookie");
-    if (!cookie) return true;
-    return [...parseCookieHeader(cookie).keys()].every((name) => name === "theme" || name.startsWith("akan_public_"));
-  }
-
-  static #htmlCacheTtlSeconds(): number {
-    return WebRouter.#positiveIntEnv("AKAN_HTML_RESULT_CACHE_TTL") ?? 30;
-  }
-
-  static #isHtmlCachePathAllowed(pathname: string): boolean {
-    const prefixes = (process.env.AKAN_HTML_RESULT_CACHE_PATHS ?? "")
-      .split(",")
-      .map((prefix) => prefix.trim())
-      .filter(Boolean);
-    if (prefixes.length === 0) return false;
-    return prefixes.some(
-      (prefix) => pathname === prefix || pathname.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`),
-    );
-  }
-
-  static #positiveIntEnv(name: string): number | null {
-    const parsed = Number.parseInt(process.env[name] ?? "", 10);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
-  }
-
   static #isImageOptimizerPath(pathname: string): boolean {
     return pathname === "/_akan/image" || pathname.endsWith("/_akan/image");
   }
@@ -756,10 +763,7 @@ export class WebRouter {
     return `${html.slice(0, last.index)}${snippet}\n${html.slice(last.index)}`;
   }
   static #rscNotFoundResponse(): Response {
-    return new Response("Not Found", {
-      status: 404,
-      headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" },
-    });
+    return createRscNotFoundFallbackResponse();
   }
   #getProductionRouteCache() {
     return new RouteClientCache({

package/types/client/csrTypes.d.ts

@@ -5,7 +5,7 @@ import type { AnimatedComponent, AnimatedProps, Interpolation, SpringValue } fro
 import type { RouterInstance } from "./router.d.ts";
 import type { ReactFont } from "./types.d.ts";
 export type TransitionType = "none" | "fade" | "bottomUp" | "stack" | "scaleOut";
-/** Per-page CSR configuration for transition, safe-area, gesture, and cache behavior. */
+/** Per-page CSR configuration for transition, safe-area, and gesture behavior. */
 export interface PageConfig {
     transition?: TransitionType;
     safeArea?: boolean | "top" | "bottom";
@@ -16,8 +16,6 @@ export interface PageConfig {
     bottomInset?: boolean | number;
     gesture?: boolean;
     cache?: boolean;
-    rscCache?: "public" | false;
-    rscCacheTtl?: number;
     topSafeAreaColor?: string;
     bottomSafeAreaColor?: string;
 }
@@ -63,7 +61,12 @@ export interface LayoutErrorProps extends LayoutNotFoundProps {
 }
 export type Head = ReactNode;
 export type GenerateHead = (props: PageProps) => PromiseOrObject<Head | null | undefined>;
-export type ResolveHead = (props: PageProps) => PromiseOrObject<Head | null | undefined>;
+export interface ResolvedHead {
+    node: Head | null | undefined;
+    hasExplicitLanguageAlternates: boolean;
+}
+export type ResolveHeadResult = Head | ResolvedHead | null | undefined;
+export type ResolveHead = (props: PageProps) => PromiseOrObject<ResolveHeadResult>;
 export type HeadProps = PageProps;
 export type PageRender = (props: PageProps) => PromiseOrObject<ReactNode>;
 export type LayoutRender = (props: LayoutProps) => PromiseOrObject<ReactNode>;
@@ -107,17 +110,45 @@ export interface WebAppManifest {
     screenshots?: WebAppManifestIcon[];
     [key: string]: unknown;
 }
+export interface AkanMetadata {
+    title?: string;
+    description?: string;
+    robots?: string;
+    openGraph?: {
+        title?: string;
+        description?: string;
+        type?: string;
+        url?: string;
+        siteName?: string;
+        images?: string | string[];
+    };
+    twitter?: {
+        card?: "summary" | "summary_large_image" | "app" | "player" | (string & {});
+        title?: string;
+        description?: string;
+        images?: string | string[];
+    };
+    alternates?: {
+        canonical?: string;
+        languages?: Record<string, string>;
+    };
+}
+export type GenerateMetadata = (props: PageProps) => PromiseOrObject<AkanMetadata | null | undefined>;
 export interface PageModule {
     default?: PageRender;
     pageConfig?: PageConfig;
     head?: Head;
+    metadata?: AkanMetadata;
     generateHead?: GenerateHead;
+    generateMetadata?: GenerateMetadata;
     Loading?: PageLoadingRender;
 }
 export interface LayoutModule {
     default?: LayoutRender;
     head?: Head;
+    metadata?: AkanMetadata;
     generateHead?: GenerateHead;
+    generateMetadata?: GenerateMetadata;
     fonts?: ReactFont[];
     manifest?: WebAppManifest;
     theme?: string;
@@ -137,7 +168,7 @@ export interface Route {
     renderLayout?: RouteRender;
     pageIncludesOwnLayout?: boolean;
     isSpecialRoute?: boolean;
-    loader?: () => any;
+    loader?: () => unknown;
     pageState?: PageState;
     children: Map<string, Route>;
 }
@@ -218,7 +249,7 @@ export interface RouteState {
     pathRoutes: PathRoute[];
 }
 export type UseCsrTransition = CsrTransitionStyles & {
-    pageBind: (...args: any[]) => ReactDOMAttributes;
+    pageBind: (...args: unknown[]) => ReactDOMAttributes;
     pageClassName: string;
     transDirection: "vertical" | "horizontal" | "none";
     transUnitRange: number[];

package/types/fetch/requestStorage.d.ts

@@ -1,8 +1,6 @@
 export type AkanTheme = "css" | "system" | (string & {});
 export interface AkanRequestPolicy {
     routeId?: string;
-    rscCache?: "public" | false;
-    rscCacheTtl?: number;
     cacheable?: boolean;
     revalidate?: number | false;
     tags: Set<string>;
@@ -31,11 +29,15 @@ export declare function createRequestStore(request: Request, policy?: Partial<Om
 /** Stores theme preference on the active request when server rendering. */
 export declare function setRequestTheme(theme: AkanTheme | undefined): void;
 export declare function getRequestTheme(): AkanTheme | undefined;
-export declare function pushRequestFallback(req: Request): () => void;
+export declare function pushRequestFallback(storeOrRequest: Request | AkanRequestStore): () => void;
 /** Returns the active server request store from AsyncLocalStorage or the fallback stack. */
 export declare function getRequestStore(): AkanRequestStore | undefined;
 /** Returns the active server request from AsyncLocalStorage or the fallback stack. */
-export declare function getRequest(): Request | undefined;
+export declare function getRequest(options?: {
+    trackDynamic?: boolean;
+}): Request | undefined;
+/** Reads the framework's active server request without marking the user route dynamic. */
+export declare function untrackedRequest(): Request | undefined;
 export declare function getRequestPolicy(): AkanRequestPolicy | undefined;
 export declare function updateRequestPolicy(patch: Partial<Omit<AkanRequestPolicy, "tags">> & {
     tags?: Iterable<string>;
@@ -44,11 +46,19 @@ export declare function getRequestDynamicUsage(): AkanDynamicUsage | undefined;
 /** Deduplicates a promise-producing query within the active request. */
 export declare function memoizeRequestQuery<T>(key: string, factory: () => Promise<T>): Promise<T>;
 /** Returns current request headers as a Map, or an empty Map outside a request. */
-export declare function headers(): Map<string, string>;
+export declare function headers(options?: {
+    trackDynamic?: boolean;
+}): Map<string, string>;
+/** Reads headers for framework internals without marking the user route dynamic. */
+export declare function untrackedHeaders(): Map<string, string>;
 export interface CookieEntry {
     name: string;
     value: string;
 }
 export declare function parseCookieHeader(cookieHeader: string): Map<string, CookieEntry>;
 /** Returns parsed cookies from the current request, or an empty Map outside a request. */
-export declare function cookies(): Map<string, CookieEntry>;
+export declare function cookies(options?: {
+    trackDynamic?: boolean;
+}): Map<string, CookieEntry>;
+/** Reads cookies for framework internals without marking the user route dynamic. */
+export declare function untrackedCookies(): Map<string, CookieEntry>;

package/types/server/cachePolicy.d.ts

@@ -0,0 +1,55 @@
+import { type AkanDynamicUsage, type AkanRequestPolicy } from "akanjs/fetch";
+export declare const DEFAULT_ROUTE_CACHE_TTL_SECONDS = 30;
+export interface RouteCacheKeyInput {
+    request: Request;
+    url: URL;
+    theme?: string;
+}
+export interface RouteCacheRenderState {
+    cacheable: boolean;
+    revalidate?: number | false;
+    tags?: string[];
+    dynamicUsage?: AkanDynamicUsage;
+    reason?: string;
+}
+export interface RouteCacheEntry {
+    key: string;
+    ttl: number;
+}
+export type RouteCacheRenderControlType = "redirect" | "not-found" | "error";
+export declare function parsePositiveInt(value: string | undefined | null): number | null;
+export declare function normalizeRouteCacheTtl(value: unknown, fallback?: number): number | null;
+export declare function resolveAutoRouteCacheTtl(input: {
+    enabled?: string | null;
+    ttl?: string | null;
+    defaultTtl?: number;
+}): number | null;
+export declare function combineMinRevalidate(...values: Array<number | false | null | undefined>): number | false | undefined;
+export declare function getClientFacingOrigin(request: Request, url?: URL): string;
+export declare function isPublicRouteCacheableRequest(request: Request): boolean;
+export declare function isRouteCachePathAllowed(pathname: string, options?: {
+    allow?: string | null;
+    deny?: string | null;
+}): boolean;
+export declare function createRouteCacheKey({ request, url, theme }: RouteCacheKeyInput): string;
+export declare function createRouteCacheEntry(input: RouteCacheKeyInput & {
+    ttl: number;
+}): RouteCacheEntry;
+export declare function resolveRouteCacheStoreTtl(baseTtl: number, state: RouteCacheRenderState): number | null;
+export declare function shouldStoreRouteCache(input: {
+    policy?: AkanRequestPolicy;
+    dynamicUsage?: AkanDynamicUsage;
+    renderControlType?: RouteCacheRenderControlType;
+    lateRedirect?: boolean;
+}): RouteCacheRenderState;
+export declare class LruTtlCache<T> {
+    #private;
+    readonly maxEntries: number;
+    constructor(maxEntries?: number);
+    get size(): number;
+    get(key: string): T | null;
+    set(key: string, value: T, ttlSeconds: number): void;
+    delete(key: string): boolean;
+    invalidate(predicate: (key: string, value: T) => boolean): number;
+    clear(): void;
+}