akanjs 2.2.11 → 2.2.12

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # akanjs
 
+## 2.2.12
+
+### Patch Changes
+
+- 666e46c: Improve SSR hydration payload handling, redirect status propagation, and restore dev HMR incremental refresh behavior.
+- 666e46c: Align RSC not-found responses with HTTP 404 semantics and add request-scoped policy tracking for future cache decisions.
+
 ## 2.2.11
 
 ### Patch Changes

package/client/cookie.ts

@@ -1,7 +1,7 @@
 import { getEnv } from "akanjs/base";
 import { decodeJwtPayload, Logger } from "akanjs/common";
 import type { Account } from "akanjs/fetch";
-import { requestStorage } from "akanjs/fetch";
+import { cookies as serverCookies, headers as serverHeaders } from "akanjs/fetch";
 import { loadCapacitorCore } from "./capacitor";
 import { storage } from "./storage";
 import { fetch } from "./useClient";
@@ -30,11 +30,7 @@ function parseCookieHeader(cookieHeader: string): Map<string, { name: string; va
 }
 
 export const cookies = (): Map<string, { name: string; value: string }> => {
-  if (getEnv().side === "server") {
-    const req = requestStorage?.getStore();
-    if (!req) return new Map();
-    return parseCookieHeader(req.headers.get("cookie") ?? "");
-  }
+  if (getEnv().side === "server") return serverCookies();
   return parseCookieHeader(document.cookie);
 };
 
@@ -75,13 +71,7 @@ export const removeCookie = (key: string, options: { path: string } = { path: "/
 };
 export const headers = (): Map<string, string> => {
   if (getEnv().side !== "server") return new Map();
-  const req = requestStorage?.getStore();
-  if (!req) return new Map();
-  const map = new Map<string, string>();
-  req.headers.forEach((value, key) => {
-    map.set(key, value);
-  });
-  return map;
+  return serverHeaders();
 };
 
 export const getHeader = (key: string): string | undefined => {

package/client/router.ts

@@ -35,12 +35,18 @@ interface CSRClientRouterOption extends RouterOptions {
   router: RouterInstance;
 }
 export type RedirectMethod = "replace" | "push";
+export type RedirectStatus = 303 | 307 | 308;
+export interface RedirectOptions {
+  method?: RedirectMethod;
+  status?: RedirectStatus;
+}
 
 export class AkanRedirectError extends Error {
   readonly digest = "AKAN_REDIRECT";
   constructor(
     readonly location: string,
     readonly method: RedirectMethod = "replace",
+    readonly status: RedirectStatus = 307,
   ) {
     super(`Redirect to ${location}`);
     this.name = "AkanRedirectError";
@@ -246,7 +252,9 @@ class Router {
     this.#instance.refresh();
     return undefined as never;
   }
-  redirect(href: string): never {
+  redirect(href: string, options: RedirectOptions = {}): never {
+    const method = options.method ?? "replace";
+    const status = options.status ?? 307;
     if (getEnv().side === "server") {
       const { getRequest, headers: requestHeaders } = getServerRequestContext();
       const h = requestHeaders();
@@ -257,9 +265,9 @@ class Router {
       const basePath = getServerBasePath(reqPathname, lang, h.get("x-base-path") ?? undefined, this.#prefix);
       const { pathname, href: fullHref } = getPathInfo(href, lang, shouldExposeBasePath() ? basePath : "");
       Logger.log(`redirect to:${pathname}`);
-      throw new AkanRedirectError(fullHref, "replace");
+      throw new AkanRedirectError(fullHref, method, status);
     } else {
-      this.#instance.replace(href);
+      this.#instance[method](href);
     }
     return undefined as never;
   }

package/fetch/requestStorage.ts

@@ -1,15 +1,35 @@
-export interface RequestStorage {
-  run<T>(store: Request, callback: () => T): T;
-  getStore(): Request | undefined;
+export type AkanTheme = "css" | "system" | (string & {});
+
+export interface AkanRequestPolicy {
+  routeId?: string;
+  rscCache?: "public" | false;
+  rscCacheTtl?: number;
+  cacheable?: boolean;
+  revalidate?: number | false;
+  tags: Set<string>;
 }
 
-export type AkanTheme = "css" | "system" | (string & {});
+export interface AkanDynamicUsage {
+  headers: boolean;
+  cookies: boolean;
+}
+
+export interface AkanRequestStore {
+  request: Request;
+  theme?: AkanTheme;
+  queryCache: Map<string, Promise<unknown>>;
+  policy: AkanRequestPolicy;
+  dynamicUsage: AkanDynamicUsage;
+}
+
+export interface RequestStorage {
+  run<T>(store: Request | AkanRequestStore, callback: () => T): T;
+  getStore(): AkanRequestStore | undefined;
+}
 
 declare global {
   var __AKAN_REQUEST_STORAGE__: RequestStorage | undefined;
-  var __AKAN_REQUEST_THEME__: WeakMap<Request, AkanTheme> | undefined;
-  var __AKAN_REQUEST_QUERY_CACHE__: WeakMap<Request, Map<string, Promise<unknown>>> | undefined;
-  var __AKAN_REQUEST_FALLBACK_STACK__: Request[] | undefined;
+  var __AKAN_REQUEST_FALLBACK_STACK__: AkanRequestStore[] | undefined;
 }
 
 let _requestStorage: RequestStorage | null = null;
@@ -17,74 +37,120 @@ if (typeof window === "undefined") {
   try {
 
     const { AsyncLocalStorage } = require("node:async_hooks") as typeof import("node:async_hooks");
-    globalThis.__AKAN_REQUEST_STORAGE__ ??= new AsyncLocalStorage() as RequestStorage;
+    const als = new AsyncLocalStorage<AkanRequestStore>();
+    globalThis.__AKAN_REQUEST_STORAGE__ ??= {
+      run<T>(store: Request | AkanRequestStore, callback: () => T): T {
+        return als.run(normalizeRequestStore(store), callback);
+      },
+      getStore(): AkanRequestStore | undefined {
+        return als.getStore();
+      },
+    };
     _requestStorage = globalThis.__AKAN_REQUEST_STORAGE__;
   } catch {}
 }
 
 export const requestStorage: RequestStorage | null = _requestStorage;
 
-function requestThemeMap(): WeakMap<Request, AkanTheme> {
-  globalThis.__AKAN_REQUEST_THEME__ ??= new WeakMap<Request, AkanTheme>();
-  return globalThis.__AKAN_REQUEST_THEME__;
+function createRequestPolicy(): AkanRequestPolicy {
+  return { tags: new Set() };
+}
+
+export function createRequestStore(
+  request: Request,
+  policy: Partial<Omit<AkanRequestPolicy, "tags">> = {},
+): AkanRequestStore {
+  return {
+    request,
+    queryCache: new Map(),
+    policy: { ...createRequestPolicy(), ...policy },
+    dynamicUsage: { headers: false, cookies: false },
+  };
+}
+
+function isRequestStore(store: Request | AkanRequestStore | undefined): store is AkanRequestStore {
+  return Boolean(store && typeof store === "object" && "request" in store && store.request instanceof Request);
+}
+
+function normalizeRequestStore(store: Request | AkanRequestStore): AkanRequestStore {
+  return isRequestStore(store) ? store : createRequestStore(store);
 }
 
-function requestQueryCacheMap(): WeakMap<Request, Map<string, Promise<unknown>>> {
-  globalThis.__AKAN_REQUEST_QUERY_CACHE__ ??= new WeakMap<Request, Map<string, Promise<unknown>>>();
-  return globalThis.__AKAN_REQUEST_QUERY_CACHE__;
+function getActiveRequestStore(): AkanRequestStore | undefined {
+  const store = requestStorage?.getStore() as Request | AkanRequestStore | undefined;
+  if (store) return isRequestStore(store) ? store : createRequestStore(store);
+  return globalThis.__AKAN_REQUEST_FALLBACK_STACK__?.at(-1);
 }
 
 /** Stores theme preference on the active request when server rendering. */
 export function setRequestTheme(theme: AkanTheme | undefined): void {
-  const req = getRequest();
-  if (!req || theme === undefined) return;
-  requestThemeMap().set(req, theme);
+  const store = getRequestStore();
+  if (!store || theme === undefined) return;
+  store.theme = theme;
 }
 
 export function getRequestTheme(): AkanTheme | undefined {
-  const req = getRequest();
-  if (!req) return undefined;
-  return requestThemeMap().get(req);
+  return getRequestStore()?.theme;
 }
 
 export function pushRequestFallback(req: Request): () => void {
   globalThis.__AKAN_REQUEST_FALLBACK_STACK__ ??= [];
   const stack = globalThis.__AKAN_REQUEST_FALLBACK_STACK__;
-  stack.push(req);
+  const store = createRequestStore(req);
+  stack.push(store);
   return () => {
-    const index = stack.lastIndexOf(req);
+    const index = stack.lastIndexOf(store);
     if (index >= 0) stack.splice(index, 1);
   };
 }
 
+/** Returns the active server request store from AsyncLocalStorage or the fallback stack. */
+export function getRequestStore(): AkanRequestStore | undefined {
+  return getActiveRequestStore();
+}
+
 /** Returns the active server request from AsyncLocalStorage or the fallback stack. */
 export function getRequest(): Request | undefined {
-  return requestStorage?.getStore() ?? globalThis.__AKAN_REQUEST_FALLBACK_STACK__?.at(-1);
+  return getRequestStore()?.request;
+}
+
+export function getRequestPolicy(): AkanRequestPolicy | undefined {
+  return getRequestStore()?.policy;
+}
+
+export function updateRequestPolicy(
+  patch: Partial<Omit<AkanRequestPolicy, "tags">> & { tags?: Iterable<string> },
+): AkanRequestPolicy | undefined {
+  const policy = getRequestPolicy();
+  if (!policy) return undefined;
+  const { tags, ...rest } = patch;
+  Object.assign(policy, rest);
+  if (tags) for (const tag of tags) policy.tags.add(tag);
+  return policy;
+}
+
+export function getRequestDynamicUsage(): AkanDynamicUsage | undefined {
+  return getRequestStore()?.dynamicUsage;
 }
 
 /** Deduplicates a promise-producing query within the active request. */
 export function memoizeRequestQuery<T>(key: string, factory: () => Promise<T>): Promise<T> {
-  const req = getRequest();
-  if (!req) return factory();
-  const cacheMap = requestQueryCacheMap();
-  let cache = cacheMap.get(req);
-  if (!cache) {
-    cache = new Map<string, Promise<unknown>>();
-    cacheMap.set(req, cache);
-  }
-  const existing = cache.get(key);
+  const store = getRequestStore();
+  if (!store) return factory();
+  const existing = store.queryCache.get(key);
   if (existing) return existing as Promise<T>;
   const promise = factory();
-  cache.set(key, promise);
+  store.queryCache.set(key, promise);
   return promise;
 }
 
 /** Returns current request headers as a Map, or an empty Map outside a request. */
 export function headers(): Map<string, string> {
-  const req = getRequest();
+  const store = getRequestStore();
   const map = new Map<string, string>();
-  if (!req) return map;
-  req.headers.forEach((value, key) => {
+  if (!store) return map;
+  store.dynamicUsage.headers = true;
+  store.request.headers.forEach((value, key) => {
     map.set(key, value);
   });
   return map;
@@ -121,7 +187,8 @@ export function parseCookieHeader(cookieHeader: string): Map<string, CookieEntry
 
 /** Returns parsed cookies from the current request, or an empty Map outside a request. */
 export function cookies(): Map<string, CookieEntry> {
-  const req = getRequest();
-  if (!req) return new Map();
-  return parseCookieHeader(req.headers.get("cookie") ?? "");
+  const store = getRequestStore();
+  if (!store) return new Map();
+  store.dynamicUsage.cookies = true;
+  return parseCookieHeader(store.request.headers.get("cookie") ?? "");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.2.11",
+  "version": "2.2.12",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/hmr/clientScript.ts

@@ -45,11 +45,11 @@ export const HMR_CLIENT_SCRIPT = `(function(){
         return;
       }
       if (msg.type === "rsc-refresh") {
-        reloadForHmr(msg);
+        refreshRsc(msg);
         return;
       }
       if (msg.type === "client-refresh") {
-        reloadForHmr(msg);
+        refreshClient(msg);
         return;
       }
       if (msg.type === "css-update") {
@@ -73,12 +73,6 @@ export const HMR_CLIENT_SCRIPT = `(function(){
     setTimeout(connect, delay);
   }
 
-  function reloadForHmr(msg){
-    try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}
-    if (msg && msg.buildId != null) lastBuildId = msg.buildId;
-    location.reload();
-  }
-
   function ensureOverlay(){
     if (overlayEl && overlayLabelEl) return overlayEl;
     if (!overlayStyleEl) {

package/server/rscClient.tsx

@@ -1,11 +1,14 @@
 import { createElement, type ReactNode, startTransition, use, useLayoutEffect, useState } from "react";
 import { hydrateRoot } from "react-dom/client";
 import { createFromReadableStream } from "react-server-dom-webpack/client.browser";
+import { isRscPayloadResponse } from "./rscHttp";
+
+type InlineRscChunk = [1, string] | [3, string];
 
 declare global {
-  var __RSC_CHUNKS__: string[] | undefined;
+  var __RSC_CHUNKS__: InlineRscChunk[] | undefined;
   var __RSC_CLOSED__: boolean | undefined;
-  var __RSC_PUSH__: ((b64: string) => void) | undefined;
+  var __RSC_PUSH__: ((type: InlineRscChunk[0], data: string) => void) | undefined;
   var __RSC_CLOSE__: (() => void) | undefined;
   var __AKAN_RSC_NAVIGATE__:
     | ((href: string, options?: { replace?: boolean; scrollToTop?: boolean }) => Promise<void>)
@@ -21,15 +24,20 @@ function decodeBase64(b64: string): Uint8Array {
   return bytes;
 }
 
+function decodeInlineRscChunk([type, data]: InlineRscChunk): Uint8Array {
+  if (type === 1) return new TextEncoder().encode(data);
+  return decodeBase64(data);
+}
+
 type RscThenable = Promise<ReactNode>;
-type RscFetchResult = { type: "rsc"; thenable: RscThenable } | { type: "redirected" };
+type RscFetchResult = { type: "rsc"; thenable: RscThenable } | { type: "redirected"; status?: number };
 const MAX_RSC_CACHE_ENTRIES = 32;
 
 function createInitialRscStream(): ReadableStream<Uint8Array> {
   return new ReadableStream<Uint8Array>({
     start(controller) {
       const queued = globalThis.__RSC_CHUNKS__ ?? [];
-      for (const b64 of queued) controller.enqueue(decodeBase64(b64));
+      for (const chunk of queued) controller.enqueue(decodeInlineRscChunk(chunk));
       globalThis.__RSC_CHUNKS__ = [];
 
       if (globalThis.__RSC_CLOSED__) {
@@ -37,7 +45,7 @@ function createInitialRscStream(): ReadableStream<Uint8Array> {
         return;
       }
 
-      globalThis.__RSC_PUSH__ = (b64: string) => controller.enqueue(decodeBase64(b64));
+      globalThis.__RSC_PUSH__ = (type, data) => controller.enqueue(decodeInlineRscChunk([type, data]));
       globalThis.__RSC_CLOSE__ = () => controller.close();
     },
   });
@@ -63,10 +71,12 @@ async function fetchRsc(href: string, options: { buildId?: number } = {}): Promi
   const redirect = res.headers.get("X-Akan-Redirect");
   if (redirect) {
     const method = res.headers.get("X-Akan-Redirect-Method");
+    const statusHeader = res.headers.get("X-Akan-Redirect-Status");
+    const status = statusHeader ? Number(statusHeader) : undefined;
     await globalThis.__AKAN_RSC_NAVIGATE__?.(redirect, { replace: method !== "push", scrollToTop: true });
-    return { type: "redirected" };
+    return { type: "redirected", status };
   }
-  if (!res.ok || !res.body) throw new Error(`[rscClient] RSC fetch failed ${res.status} ${res.statusText}`);
+  if (!isRscPayloadResponse(res)) throw new Error(`[rscClient] RSC fetch failed ${res.status} ${res.statusText}`);
 
   const buffer = await res.arrayBuffer();
   const completeStream = new ReadableStream<Uint8Array>({

package/server/rscHttp.ts

@@ -0,0 +1,7 @@
+export const RSC_CONTENT_TYPE = "text/x-component; charset=utf-8";
+
+export function isRscPayloadResponse(res: Response): boolean {
+  if (!res.body) return false;
+  if (res.ok) return true;
+  return res.status === 404 && (res.headers.get("Content-Type") ?? "").toLowerCase().startsWith("text/x-component");
+}

package/server/rscWorker.tsx

@@ -1,6 +1,12 @@
-import type { AkanNotFoundError, AkanRedirectError, LayoutFallbackRoute, PathRoute } from "akanjs/client";
+import type {
+  AkanNotFoundError,
+  AkanRedirectError,
+  LayoutFallbackRoute,
+  PathRoute,
+  RedirectStatus,
+} from "akanjs/client";
 import { type AkanI18nConfig, DEFAULT_AKAN_I18N, getBasePathFromPathname, Logger } from "akanjs/common";
-import { cookies, getRequest, getRequestTheme, requestStorage } from "akanjs/fetch";
+import { cookies, getRequest, getRequestTheme, requestStorage, updateRequestPolicy } from "akanjs/fetch";
 import type { ReactNode } from "react";
 import { renderToReadableStream } from "react-server-dom-webpack/server.node";
 import type { ClientManifest } from "./artifact";
@@ -40,7 +46,7 @@ interface UpdateCssAssetsMsg {
 }
 type InMsg = InitMsg | RenderMsg | ReloadMsg | UpdateCssAssetsMsg;
 type RenderControl =
-  | { type: "redirect"; location: string; method: "replace" | "push" }
+  | { type: "redirect"; location: string; method: "replace" | "push"; status: RedirectStatus }
   | { type: "not-found" }
   | { type: "error"; error: unknown };
 
@@ -82,7 +88,9 @@ export function isAkanRedirectError(error: unknown): error is AkanRedirectError
     "digest" in error &&
     (error as { digest?: unknown }).digest === "AKAN_REDIRECT" &&
     "location" in error &&
-    typeof (error as { location?: unknown }).location === "string"
+    typeof (error as { location?: unknown }).location === "string" &&
+    "status" in error &&
+    typeof (error as { status?: unknown }).status === "number"
   );
 }
 
@@ -272,6 +280,7 @@ class RscRenderer {
         const match = RouteTreeBuilder.match(urlObj.pathname, this.#pathRoutes);
         activeRoute.match = match;
         const routeId = match?.pathRoute.path ?? "__not_found__";
+        updateRequestPolicy({ routeId });
         this.#stats.lastRenderRouteId = routeId;
         this.#stats.lastRenderKind = match ? "route" : "not-found";
         if (match)
@@ -365,7 +374,13 @@ class RscRenderer {
       if (isAkanRedirectError(error)) {
         this.#stats.lastRenderKind = "redirect";
         this.#logger.verbose(`render[${requestId}] redirect ${error.location}`);
-        this.#send({ type: "redirect", requestId, location: error.location, method: error.method });
+        this.#send({
+          type: "redirect",
+          requestId,
+          location: error.location,
+          method: error.method,
+          status: error.status,
+        });
         return;
       }
       if (isAkanNotFoundError(error)) {
@@ -474,7 +489,12 @@ class RscRenderer {
     const stream = await renderToReadableStream(element, clientManifest, {
       onError: (error) => {
         if (isAkanRedirectError(error)) {
-          controlRef.current = { type: "redirect", location: error.location, method: error.method };
+          controlRef.current = {
+            type: "redirect",
+            location: error.location,
+            method: error.method,
+            status: error.status,
+          };
           return error.digest;
         }
         if (isAkanNotFoundError(error)) {
@@ -558,7 +578,13 @@ class RscRenderer {
   #sendRenderControl(requestId: string, control: RenderControl): void {
     if (control.type === "redirect") {
       this.#logger.verbose(`render[${requestId}] redirect ${control.location}`);
-      this.#send({ type: "redirect", requestId, location: control.location, method: control.method });
+      this.#send({
+        type: "redirect",
+        requestId,
+        location: control.location,
+        method: control.method,
+        status: control.status,
+      });
       return;
     }
     if (control.type === "error") {
@@ -594,6 +620,11 @@ class RscRenderer {
   async #getResultCacheKey(request: Request, url: URL, pathRoute: PathRoute): Promise<string | null> {
     const config = await pathRoute.renderPage.getPageConfig?.();
     const ttl = RscRenderer.#normalizeCacheTtl(config?.rscCacheTtl);
+    updateRequestPolicy({
+      rscCache: config?.rscCache,
+      rscCacheTtl: config?.rscCacheTtl,
+      cacheable: config?.rscCache === "public" || ttl !== null,
+    });
     if (config?.rscCache !== "public" && ttl === null) {
       this.#resultCacheBypass += 1;
       return null;

package/server/rscWorkerHost.ts

@@ -12,15 +12,16 @@ interface RscPending {
   onEnd: () => void;
   onError: (message: string) => void;
   onMeta?: (meta: { theme?: AkanTheme; status?: number }) => void;
-  onRedirect?: (location: string, method: RscRedirectMethod) => void;
+  onRedirect?: (location: string, method: RscRedirectMethod, status: RscRedirectStatus) => void;
   onNotFound?: () => void;
 }
 
 export type RscRedirectMethod = "replace" | "push";
+export type RscRedirectStatus = 303 | 307 | 308;
 
 export type RscRenderResult =
   | { type: "stream"; stream: ReadableStream<Uint8Array>; theme?: AkanTheme; status?: number }
-  | { type: "redirect"; location: string; method: RscRedirectMethod }
+  | { type: "redirect"; location: string; method: RscRedirectMethod; status: RscRedirectStatus }
   | { type: "not-found" };
 
 type RscInMsg =
@@ -30,7 +31,7 @@ type RscInMsg =
   | { type: "meta"; requestId: string; theme?: AkanTheme; status?: number }
   | { type: "chunk"; requestId: string; data: Uint8Array }
   | { type: "end"; requestId: string }
-  | { type: "redirect"; requestId: string; location: string; method?: RscRedirectMethod }
+  | { type: "redirect"; requestId: string; location: string; method?: RscRedirectMethod; status?: RscRedirectStatus }
   | { type: "not-found"; requestId: string }
   | { type: "metrics"; metrics: AkanMetricsReport }
   | { type: "error"; requestId: string; message: string; buildId?: number };
@@ -211,10 +212,10 @@ export class RscWorker {
               }
               controller.error(new Error(msg));
             },
-            onRedirect: (location, method) => {
+            onRedirect: (location, method, status) => {
               if (!settled) {
                 settled = true;
-                resolve({ type: "redirect", location, method });
+                resolve({ type: "redirect", location, method, status });
                 controller.close();
                 return;
               }
@@ -406,7 +407,9 @@ export class RscWorker {
         this.#resolvePending(message.requestId, (p) => p.onEnd());
         return;
       case "redirect":
-        this.#resolvePending(message.requestId, (p) => p.onRedirect?.(message.location, message.method ?? "replace"));
+        this.#resolvePending(message.requestId, (p) =>
+          p.onRedirect?.(message.location, message.method ?? "replace", message.status ?? 307),
+        );
         return;
       case "not-found":
         this.#resolvePending(message.requestId, (p) => p.onNotFound?.());

package/server/ssrFromRscRenderer.tsx

@@ -5,11 +5,115 @@ import { renderToReadableStream } from "react-dom/server.browser";
 import { createFromNodeStream } from "react-server-dom-webpack/client.node";
 import type { SsrChunkRegistryStats, SsrFromRscInput } from "./ssrTypes";
 
+const DEFAULT_SSR_CHUNK_REGISTRY_MAX_ENTRIES = 1024;
+
+interface SsrChunkRegistryEntry<T> {
+  keys: Set<string>;
+  lruKey: string;
+  value: T;
+}
+
+export class SsrChunkRegistry<T> {
+  readonly #entriesByKey = new Map<string, SsrChunkRegistryEntry<T>>();
+  readonly #lru = new Map<string, SsrChunkRegistryEntry<T>>();
+  #evictionCount = 0;
+
+  constructor(readonly maxEntries = DEFAULT_SSR_CHUNK_REGISTRY_MAX_ENTRIES) {}
+
+  get size(): number {
+    return this.#entriesByKey.size;
+  }
+
+  get evictionCount(): number {
+    return this.#evictionCount;
+  }
+
+  get(key: string): T | undefined {
+    const entry = this.#entriesByKey.get(key);
+    if (!entry) return undefined;
+    this.#touch(entry);
+    return entry.value;
+  }
+
+  set(keys: string[], value: T): void {
+    const uniqueKeys = [...new Set(keys)].filter(Boolean);
+    if (uniqueKeys.length === 0) return;
+
+    let entry = uniqueKeys
+      .map((key) => this.#entriesByKey.get(key))
+      .find((item): item is SsrChunkRegistryEntry<T> => Boolean(item));
+    if (!entry) {
+      entry = { keys: new Set(), lruKey: uniqueKeys[0] as string, value };
+    }
+    entry.value = value;
+
+    for (const key of uniqueKeys) {
+      const existing = this.#entriesByKey.get(key);
+      if (existing && existing !== entry) {
+        existing.keys.delete(key);
+        if (existing.keys.size === 0) this.#lru.delete(existing.lruKey);
+      }
+      entry.keys.add(key);
+      this.#entriesByKey.set(key, entry);
+    }
+
+    this.#touch(entry);
+    this.#evict(entry);
+  }
+
+  #touch(entry: SsrChunkRegistryEntry<T>): void {
+    this.#lru.delete(entry.lruKey);
+    this.#lru.set(entry.lruKey, entry);
+  }
+
+  #evict(protectedEntry: SsrChunkRegistryEntry<T>): void {
+    const maxEntries = this.maxEntries > 0 ? this.maxEntries : DEFAULT_SSR_CHUNK_REGISTRY_MAX_ENTRIES;
+    while (this.#entriesByKey.size > maxEntries) {
+      const oldest = this.#lru.entries().next().value as [string, SsrChunkRegistryEntry<T>] | undefined;
+      if (!oldest) return;
+      const [lruKey, entry] = oldest;
+      if (entry === protectedEntry && this.#lru.size === 1) return;
+      if (entry === protectedEntry) {
+        this.#touch(entry);
+        continue;
+      }
+      this.#lru.delete(lruKey);
+      for (const key of entry.keys) this.#entriesByKey.delete(key);
+      this.#evictionCount += 1;
+    }
+  }
+}
+
+export type InlineRscChunk = readonly [1, string] | readonly [3, string];
+
+export function encodeInlineRscChunk(chunk: Uint8Array): InlineRscChunk {
+  try {
+    return [1, new TextDecoder("utf-8", { fatal: true }).decode(chunk)];
+  } catch {
+    return [3, Buffer.from(chunk).toString("base64")];
+  }
+}
+
+export function htmlEscapeJsonString(value: string): string {
+  return JSON.stringify(value)
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+
+export function createInlineRscScript(chunk: Uint8Array): string {
+  const [type, data] = encodeInlineRscChunk(chunk);
+  return `<script>self.__RSC_PUSH__(${type},${htmlEscapeJsonString(data)})</script>`;
+}
+
 export class SsrFromRscRenderer {
   static readonly #chunkRegistryStats: SsrChunkRegistryStats = {
     ssrChunkRegistrySize: 0,
     ssrChunkLoadCount: 0,
     ssrChunkCacheHitCount: 0,
+    ssrChunkEvictionCount: 0,
   };
 
   static readonly #clientBootstrap = `(function(){
@@ -31,7 +135,7 @@ export class SsrFromRscRenderer {
   self.__webpack_get_script_filename__ = function(chunkId) { return chunkId; };
   self.__RSC_CHUNKS__ = [];
   self.__RSC_CLOSED__ = false;
-  self.__RSC_PUSH__ = function(b64){ self.__RSC_CHUNKS__.push(b64); };
+  self.__RSC_PUSH__ = function(type,data){ self.__RSC_CHUNKS__.push([type,data]); };
   self.__RSC_CLOSE__ = function(){ self.__RSC_CLOSED__ = true; };
 })();`;
 
@@ -98,18 +202,18 @@ export class SsrFromRscRenderer {
     if (g.__rsc_ssr_shims_installed__) return;
     g.__rsc_ssr_shims_installed__ = true;
 
-    const registry = new Map<string, Record<string, unknown>>();
+    const registry = new SsrChunkRegistry<Record<string, unknown>>(SsrFromRscRenderer.#getSsrChunkRegistryMaxEntries());
     g.__webpack_chunk_load__ = async (chunkId: string) => {
-      if (registry.has(chunkId)) {
+      if (registry.get(chunkId)) {
         SsrFromRscRenderer.#chunkRegistryStats.ssrChunkCacheHitCount += 1;
         return;
       }
       const mod = (await import(chunkId)) as Record<string, unknown>;
-      registry.set(chunkId, mod);
       const canonical = chunkId.replace(/\?v=\d+$/, "");
-      registry.set(canonical, mod);
+      registry.set([chunkId, canonical], mod);
       SsrFromRscRenderer.#chunkRegistryStats.ssrChunkLoadCount += 1;
       SsrFromRscRenderer.#chunkRegistryStats.ssrChunkRegistrySize = registry.size;
+      SsrFromRscRenderer.#chunkRegistryStats.ssrChunkEvictionCount = registry.evictionCount;
     };
     g.__webpack_require__ = (id: string) => {
       const mod = registry.get(id);
@@ -120,6 +224,11 @@ export class SsrFromRscRenderer {
     };
   }
 
+  static #getSsrChunkRegistryMaxEntries(): number {
+    const parsed = Number.parseInt(process.env.AKAN_SSR_CHUNK_REGISTRY_MAX_ENTRIES ?? "", 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_SSR_CHUNK_REGISTRY_MAX_ENTRIES;
+  }
+
   /**
    * Splice bootstrap-only head scripts immediately after the `<head>` opening
    * tag in the outgoing HTML stream.
@@ -281,8 +390,7 @@ export class SsrFromRscRenderer {
               const { value, done } = await rscReader.read();
               if (done) break;
               if (errored) return;
-              const b64 = Buffer.from(value).toString("base64");
-              controller.enqueue(encoder.encode(`<script>self.__RSC_PUSH__(${JSON.stringify(b64)})</script>`));
+              controller.enqueue(encoder.encode(createInlineRscScript(value)));
             }
           } finally {
             rscReader.releaseLock();

package/server/ssrTypes.ts

@@ -16,6 +16,7 @@ export interface SsrChunkRegistryStats {
   ssrChunkRegistrySize: number;
   ssrChunkLoadCount: number;
   ssrChunkCacheHitCount: number;
+  ssrChunkEvictionCount: number;
 }
 
 export interface SsrFromRscInput {

package/server/webRouter.ts

@@ -22,7 +22,7 @@ import { HMR_CLIENT_SCRIPT } from "./hmr/clientScript";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub";
 import { ImageOptimizer } from "./imageOptimizer";
 import { createDefaultRobotsTxt } from "./robots";
-import { RscWorker } from "./rscWorkerHost";
+import { type RscRedirectMethod, type RscRedirectStatus, RscWorker } from "./rscWorkerHost";
 import { createDefaultSitemapXml, getSitemapBasePath } from "./sitemap";
 import { SsrFromRscRenderer } from "./ssrFromRscRenderer";
 import { createSystemPageResponse, getSystemPageHomeHref } from "./systemPages";
@@ -30,6 +30,33 @@ import type { BaseBuildArtifact, HttpRoutes, RenderState } from "./types";
 
 const RESERVED_BASE_PATHS = new Set(["admin"]);
 
+export function createRscRedirectResponse(
+  location: string,
+  method: RscRedirectMethod,
+  status: RscRedirectStatus = 307,
+): Response {
+  return new Response(JSON.stringify({ type: "redirect", location, method, status }), {
+    status: 200,
+    headers: {
+      "Content-Type": "application/json; charset=utf-8",
+      "Cache-Control": "no-store",
+      "X-Akan-Redirect": location,
+      "X-Akan-Redirect-Method": method,
+      "X-Akan-Redirect-Status": String(status),
+    },
+  });
+}
+
+export function createRscStreamResponse(stream: BodyInit, status = 200): Response {
+  return new Response(stream, {
+    status,
+    headers: {
+      "Content-Type": "text/x-component; charset=utf-8",
+      "Cache-Control": "no-store",
+    },
+  });
+}
+
 export function normalizeRscTargetUrlForHostBasePath(
   targetUrl: URL,
   options: {
@@ -262,17 +289,12 @@ export class WebRouter {
           const result = await this.#rsc.renderWithMeta(rscReq, {
             clientManifest: manifest.clientManifest,
           });
-          if (result.type === "redirect") return WebRouter.#rscRedirectResponse(result.location, result.method);
-          if (result.type === "not-found") return WebRouter.#rscRedirectResponse("/404", "replace");
-          if (result.status === 404) return WebRouter.#rscRedirectResponse("/404", "replace");
+          if (result.type === "redirect")
+            return createRscRedirectResponse(result.location, result.method, result.status);
+          if (result.type === "not-found") return WebRouter.#rscNotFoundResponse();
           if (result.status && result.status >= 500)
             return this.#renderRscErrorResponse("__rsc", "Internal Server Error");
-          return new Response(result.stream, {
-            headers: {
-              "Content-Type": "text/x-component; charset=utf-8",
-              "Cache-Control": "no-store",
-            },
-          });
+          return createRscStreamResponse(result.stream, result.status ?? 200);
         } catch (err) {
           return this.#renderRscErrorResponse("__rsc", err);
         }
@@ -368,7 +390,8 @@ export class WebRouter {
           const rscResult = await this.#rsc.renderWithMeta(req, {
             clientManifest: manifest.clientManifest,
           });
-          if (rscResult.type === "redirect") return Response.redirect(new URL(rscResult.location, url.origin), 307);
+          if (rscResult.type === "redirect")
+            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 htmlStream = await new SsrFromRscRenderer().render({
@@ -417,6 +440,7 @@ export class WebRouter {
       ssrChunkRegistrySize: ssrStats.ssrChunkRegistrySize,
       ssrChunkLoadCount: ssrStats.ssrChunkLoadCount,
       ssrChunkCacheHitCount: ssrStats.ssrChunkCacheHitCount,
+      ssrChunkEvictionCount: ssrStats.ssrChunkEvictionCount,
       httpFullSsrCount: this.#requestStats.fullSsr,
       httpRscNavigationCount: this.#requestStats.rscNavigation,
       httpStaticAssetCount: this.#requestStats.staticAsset,
@@ -650,15 +674,10 @@ export class WebRouter {
     if (!last || last.index === undefined) return `${html}\n${snippet}`;
     return `${html.slice(0, last.index)}${snippet}\n${html.slice(last.index)}`;
   }
-  static #rscRedirectResponse(location: string, method: "replace" | "push") {
-    return new Response(JSON.stringify({ type: "redirect", location, method }), {
-      status: 200,
-      headers: {
-        "Content-Type": "application/json; charset=utf-8",
-        "Cache-Control": "no-store",
-        "X-Akan-Redirect": location,
-        "X-Akan-Redirect-Method": method,
-      },
+  static #rscNotFoundResponse(): Response {
+    return new Response("Not Found", {
+      status: 404,
+      headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" },
     });
   }
   #getProductionRouteCache() {

package/service/ipcTypes.ts

@@ -85,6 +85,7 @@ export interface AkanMetricsReport {
   ssrChunkRegistrySize?: number;
   ssrChunkLoadCount?: number;
   ssrChunkCacheHitCount?: number;
+  ssrChunkEvictionCount?: number;
   httpFullSsrCount?: number;
   httpRscNavigationCount?: number;
   httpStaticAssetCount?: number;

package/types/client/router.d.ts

@@ -25,11 +25,17 @@ interface CSRClientRouterOption extends RouterOptions {
     router: RouterInstance;
 }
 export type RedirectMethod = "replace" | "push";
+export type RedirectStatus = 303 | 307 | 308;
+export interface RedirectOptions {
+    method?: RedirectMethod;
+    status?: RedirectStatus;
+}
 export declare class AkanRedirectError extends Error {
     readonly location: string;
     readonly method: RedirectMethod;
+    readonly status: RedirectStatus;
     readonly digest = "AKAN_REDIRECT";
-    constructor(location: string, method?: RedirectMethod);
+    constructor(location: string, method?: RedirectMethod, status?: RedirectStatus);
 }
 export declare class AkanNotFoundError extends Error {
     readonly digest = "AKAN_NOT_FOUND";
@@ -53,7 +59,7 @@ declare class Router {
     replace(href: string, routeOptions?: RouteOptions): never;
     back(routeOptions?: RouteOptions): never;
     refresh(): never;
-    redirect(href: string): never;
+    redirect(href: string, options?: RedirectOptions): never;
     notFound(): never;
     setLang(lang: string): never;
     getPath(pathname?: string): string;

package/types/fetch/requestStorage.d.ts

@@ -1,21 +1,46 @@
+export type AkanTheme = "css" | "system" | (string & {});
+export interface AkanRequestPolicy {
+    routeId?: string;
+    rscCache?: "public" | false;
+    rscCacheTtl?: number;
+    cacheable?: boolean;
+    revalidate?: number | false;
+    tags: Set<string>;
+}
+export interface AkanDynamicUsage {
+    headers: boolean;
+    cookies: boolean;
+}
+export interface AkanRequestStore {
+    request: Request;
+    theme?: AkanTheme;
+    queryCache: Map<string, Promise<unknown>>;
+    policy: AkanRequestPolicy;
+    dynamicUsage: AkanDynamicUsage;
+}
 export interface RequestStorage {
-    run<T>(store: Request, callback: () => T): T;
-    getStore(): Request | undefined;
+    run<T>(store: Request | AkanRequestStore, callback: () => T): T;
+    getStore(): AkanRequestStore | undefined;
 }
-export type AkanTheme = "css" | "system" | (string & {});
 declare global {
     var __AKAN_REQUEST_STORAGE__: RequestStorage | undefined;
-    var __AKAN_REQUEST_THEME__: WeakMap<Request, AkanTheme> | undefined;
-    var __AKAN_REQUEST_QUERY_CACHE__: WeakMap<Request, Map<string, Promise<unknown>>> | undefined;
-    var __AKAN_REQUEST_FALLBACK_STACK__: Request[] | undefined;
+    var __AKAN_REQUEST_FALLBACK_STACK__: AkanRequestStore[] | undefined;
 }
 export declare const requestStorage: RequestStorage | null;
+export declare function createRequestStore(request: Request, policy?: Partial<Omit<AkanRequestPolicy, "tags">>): AkanRequestStore;
 /** 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;
+/** 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 getRequestPolicy(): AkanRequestPolicy | undefined;
+export declare function updateRequestPolicy(patch: Partial<Omit<AkanRequestPolicy, "tags">> & {
+    tags?: Iterable<string>;
+}): AkanRequestPolicy | undefined;
+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. */

package/types/server/hmr/clientScript.d.ts

@@ -1 +1 @@
-export declare const HMR_CLIENT_SCRIPT = "(function(){\n  if (self.__AKAN_HMR_INSTALLED__) return;\n  self.__AKAN_HMR_INSTALLED__ = true;\n  var proto = location.protocol === \"https:\" ? \"wss:\" : \"ws:\";\n  var url = proto + \"//\" + location.host + \"/_akan/hmr\";\n  var attempts = 0;\n  var socket = null;\n  var lastBuildId = null;\n  var refreshRuntimePromise = null;\n  var refreshQueue = Promise.resolve();\n  var overlayEl = null;\n  var overlayLabelEl = null;\n  var overlayStyleEl = null;\n  var overlayTimer = null;\n  var overlayHideTimer = null;\n  var overlayNextToken = 1;\n  var overlayJobs = {};\n  self.__AKAN_HMR_PHASE__ = null;\n\n  // Bun's React Fast Refresh transform can emit top-level calls to these globals\n  // even when we fall back to full reload instead of applying React Refresh.\n  self.$RefreshReg$ = self.$RefreshReg$ || function(){};\n  self.$RefreshSig$ = self.$RefreshSig$ || function(){ return function(type){ return type; }; };\n\n  function connect(){\n    try { socket = new WebSocket(url); }\n    catch(e){ console.error(\"[akan-hmr] ws init failed\", e); schedule(); return; }\n    socket.addEventListener(\"open\", function(){ attempts = 0; });\n    socket.addEventListener(\"message\", function(ev){\n      var msg;\n      try { msg = JSON.parse(ev.data); } catch (e){ return; }\n      if (!msg || typeof msg.type !== \"string\") return;\n      if (msg.type === \"hello\") {\n        if (lastBuildId !== null && msg.buildId !== lastBuildId) {\n          location.reload();\n          return;\n        }\n        lastBuildId = msg.buildId;\n        return;\n      }\n      if (msg.type === \"reload\") {\n        beginHmrOverlay(\"Reloading...\", true);\n        try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}\n        setTimeout(function(){ location.reload(); }, 30);\n        return;\n      }\n      if (msg.type === \"rsc-refresh\") {\n        reloadForHmr(msg);\n        return;\n      }\n      if (msg.type === \"client-refresh\") {\n        reloadForHmr(msg);\n        return;\n      }\n      if (msg.type === \"css-update\") {\n        var cssUrl = selectCssUrl(msg.cssAssets);\n        if (cssUrl) swapCss(cssUrl);\n        else {\n          beginHmrOverlay(\"Reloading...\", true);\n          location.reload();\n        }\n        return;\n      }\n      if (msg.type === \"error\") { console.error(\"[akan-hmr]\", msg.message); return; }\n    });\n    socket.addEventListener(\"close\", function(){ socket = null; schedule(); });\n    socket.addEventListener(\"error\", function(){ try { socket && socket.close(); } catch(e){} });\n  }\n\n  function schedule(){\n    attempts = Math.min(attempts + 1, 6);\n    var delay = Math.min(30000, 250 * Math.pow(2, attempts - 1));\n    setTimeout(connect, delay);\n  }\n\n  // goseoghyeon: CSR route registry keeps stale module refs, so JS/RSC HMR uses full reload for now.\n  function reloadForHmr(msg){\n    try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}\n    if (msg && msg.buildId != null) lastBuildId = msg.buildId;\n    location.reload();\n  }\n\n  function ensureOverlay(){\n    if (overlayEl && overlayLabelEl) return overlayEl;\n    if (!overlayStyleEl) {\n      overlayStyleEl = document.createElement(\"style\");\n      overlayStyleEl.textContent =\n        \"@keyframes akan-hmr-spin{to{transform:rotate(360deg)}}\" +\n        \".__akan_hmr_overlay{position:fixed;left:16px;bottom:16px;z-index:2147483647;display:flex;align-items:center;gap:9px;padding:10px 12px;border-radius:999px;background:rgba(17,24,39,.94);color:#fff;font:500 13px/1.2 ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif;box-shadow:0 10px 28px rgba(0,0,0,.28);pointer-events:none;opacity:0;transform:translateY(6px);transition:opacity .15s ease,transform .15s ease;backdrop-filter:blur(8px)}\" +\n        \".__akan_hmr_overlay[data-show=true]{opacity:1;transform:translateY(0)}\" +\n        \".__akan_hmr_spinner{width:14px;height:14px;border:2px solid rgba(255,255,255,.32);border-top-color:#fff;border-radius:999px;animation:akan-hmr-spin .75s linear infinite;flex:none}\" +\n        \"@media (prefers-reduced-motion:reduce){.__akan_hmr_overlay{transition:none}.__akan_hmr_spinner{animation:none}}\";\n      document.head.appendChild(overlayStyleEl);\n    }\n    overlayEl = document.createElement(\"div\");\n    overlayEl.className = \"__akan_hmr_overlay\";\n    overlayEl.setAttribute(\"role\", \"status\");\n    overlayEl.setAttribute(\"aria-live\", \"polite\");\n    overlayEl.innerHTML = '<span class=\"__akan_hmr_spinner\" aria-hidden=\"true\"></span><span data-akan-hmr-label>Updating...</span>';\n    overlayLabelEl = overlayEl.querySelector(\"[data-akan-hmr-label]\");\n    (document.body || document.documentElement).appendChild(overlayEl);\n    return overlayEl;\n  }\n\n  function activeOverlayTokens(){\n    return Object.keys(overlayJobs);\n  }\n\n  function latestOverlayLabel(){\n    var keys = activeOverlayTokens();\n    if (keys.length === 0) return \"Updating...\";\n    return overlayJobs[keys[keys.length - 1]] || \"Updating...\";\n  }\n\n  function showOverlayNow(){\n    overlayTimer = null;\n    if (activeOverlayTokens().length === 0) return;\n    var el = ensureOverlay();\n    if (overlayHideTimer) {\n      clearTimeout(overlayHideTimer);\n      overlayHideTimer = null;\n    }\n    if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n    requestAnimationFrame(function(){ el.setAttribute(\"data-show\", \"true\"); });\n  }\n\n  function beginHmrOverlay(label, immediate){\n    var token = overlayNextToken++;\n    overlayJobs[token] = label || \"Updating...\";\n    if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n    if (overlayHideTimer) {\n      clearTimeout(overlayHideTimer);\n      overlayHideTimer = null;\n    }\n    if (immediate) {\n      if (overlayTimer) clearTimeout(overlayTimer);\n      showOverlayNow();\n    } else if (!overlayTimer && (!overlayEl || overlayEl.getAttribute(\"data-show\") !== \"true\")) {\n      overlayTimer = setTimeout(showOverlayNow, 120);\n    }\n    return token;\n  }\n\n  function setHmrOverlayLabel(token, label){\n    if (!overlayJobs[token]) return;\n    overlayJobs[token] = label || \"Updating...\";\n    if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n  }\n\n  function endHmrOverlay(token){\n    delete overlayJobs[token];\n    if (activeOverlayTokens().length > 0) {\n      if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n      return;\n    }\n    if (overlayTimer) {\n      clearTimeout(overlayTimer);\n      overlayTimer = null;\n    }\n    if (!overlayEl) return;\n    overlayEl.setAttribute(\"data-show\", \"false\");\n    if (overlayHideTimer) clearTimeout(overlayHideTimer);\n    overlayHideTimer = setTimeout(function(){\n      if (overlayEl && activeOverlayTokens().length === 0 && overlayEl.parentNode) {\n        overlayEl.parentNode.removeChild(overlayEl);\n        overlayEl = null;\n        overlayLabelEl = null;\n      }\n    }, 180);\n  }\n\n  function refreshRsc(msg){\n    var started = performance.now();\n    var overlayToken = beginHmrOverlay(\"Refreshing page...\");\n    try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}\n    if (!self.__AKAN_RSC_REFRESH__) {\n      console.warn(\"[akan-hmr] RSC refresh API unavailable, falling back to full reload\");\n      setHmrOverlayLabel(overlayToken, \"Reloading...\");\n      setTimeout(function(){ location.reload(); }, 30);\n      return;\n    }\n    Promise.resolve(self.__AKAN_RSC_REFRESH__({ buildId: msg.buildId })).then(function(){\n      lastBuildId = msg.buildId;\n      endHmrOverlay(overlayToken);\n      console.debug && console.debug(\"[akan-hmr] RSC refreshed\", {\n        buildId: msg.buildId,\n        generation: msg.generation,\n        routeIds: msg.routeIds,\n        changedFiles: msg.changedFiles && msg.changedFiles.length,\n        durationMs: Math.round(performance.now() - started)\n      });\n    }, function(err){\n      console.error(\"[akan-hmr] RSC refresh failed, falling back to full reload\", err);\n      setHmrOverlayLabel(overlayToken, \"Update failed, reloading...\");\n      setTimeout(function(){ location.reload(); }, 250);\n    });\n  }\n\n  function ensureRefreshRuntime(){\n    if (refreshRuntimePromise) return refreshRuntimePromise;\n    refreshRuntimePromise = import(\"react-refresh/runtime\").then(function(mod){\n      var runtime = mod.default || mod;\n      if (!self.__AKAN_REACT_REFRESH_READY__) {\n        runtime.injectIntoGlobalHook(self);\n        self.$RefreshReg$ = function(type, id){ runtime.register(type, id); };\n        self.$RefreshSig$ = runtime.createSignatureFunctionForTransform;\n        self.__AKAN_REACT_REFRESH_READY__ = true;\n        self.__AKAN_REACT_REFRESH_RUNTIME__ = runtime;\n      }\n      return runtime;\n    });\n    return refreshRuntimePromise;\n  }\n\n  function refreshClient(msg){\n    refreshQueue = refreshQueue.then(function(){ return doRefreshClient(msg); }, function(){ return doRefreshClient(msg); });\n  }\n\n  function setHmrPhase(phase){\n    self.__AKAN_HMR_PHASE__ = phase;\n  }\n\n  function doRefreshClient(msg){\n    var started = performance.now();\n    var metadataAt = started;\n    var importAt = started;\n    var refreshAt = started;\n    var overlayToken = beginHmrOverlay(\"Updating...\");\n    var fallbackToRsc = false;\n    return ensureRefreshRuntime().then(function(runtime){\n      setHmrOverlayLabel(overlayToken, \"Fetching update...\");\n      var endpoint = new URL(\"/_akan/hmr/client-refresh\", location.origin);\n      endpoint.searchParams.set(\"url\", location.href);\n      if (msg.buildId != null) endpoint.searchParams.set(\"buildId\", String(msg.buildId));\n      return fetch(endpoint, { credentials: \"same-origin\", cache: \"no-store\" })\n        .then(function(res){\n          if (!res.ok) throw new Error(\"client-refresh metadata failed \" + res.status + \" \" + res.statusText);\n          return res.json();\n        })\n        .then(function(info){\n          metadataAt = performance.now();\n          var chunks = Array.isArray(info.chunks) ? info.chunks : [];\n          if (chunks.length === 0) throw new Error(\"no client chunks returned\");\n          setHmrPhase(\"refresh-import\");\n          setHmrOverlayLabel(overlayToken, \"Importing update...\");\n          return Promise.all(chunks.map(function(chunk){ return import(chunk); })).then(function(){\n            importAt = performance.now();\n            setHmrPhase(\"react-refresh\");\n            setHmrOverlayLabel(overlayToken, \"Applying update...\");\n            try {\n              runtime.performReactRefresh();\n            } finally {\n              setHmrPhase(null);\n            }\n            refreshAt = performance.now();\n            lastBuildId = msg.buildId;\n            console.debug && console.debug(\"[akan-hmr] React Fast Refresh applied\", {\n              buildId: msg.buildId,\n              generation: msg.generation,\n              chunks: chunks.length,\n              routeIds: info.routeIds || msg.routeIds,\n              changedFiles: msg.changedFiles && msg.changedFiles.length,\n              metadataMs: Math.round(metadataAt - started),\n              importMs: Math.round(importAt - metadataAt),\n              refreshMs: Math.round(refreshAt - importAt),\n              durationMs: Math.round(refreshAt - started)\n            });\n            endHmrOverlay(overlayToken);\n          }, function(err){\n            setHmrPhase(null);\n            throw err;\n          });\n        });\n    }).catch(function(err){\n      console.warn(\"[akan-hmr] React Fast Refresh failed, falling back to RSC refresh\", err);\n      fallbackToRsc = true;\n      endHmrOverlay(overlayToken);\n      refreshRsc(msg);\n    }).finally(function(){\n      if (!fallbackToRsc) endHmrOverlay(overlayToken);\n    });\n  }\n\n  function swapCss(href){\n    var overlayToken = beginHmrOverlay(\"Updating styles...\");\n    var link = document.createElement(\"link\");\n    link.rel = \"stylesheet\";\n    link.href = href;\n    link.setAttribute(\"data-akan-css\", \"pending\");\n    link.addEventListener(\"load\", function(){\n      var prev = document.querySelectorAll(\"link[data-akan-css=active]\");\n      for (var i = 0; i < prev.length; i++) prev[i].parentNode && prev[i].parentNode.removeChild(prev[i]);\n      link.setAttribute(\"data-akan-css\", \"active\");\n      endHmrOverlay(overlayToken);\n    });\n    link.addEventListener(\"error\", function(){\n      if (link.parentNode) link.parentNode.removeChild(link);\n      endHmrOverlay(overlayToken);\n    });\n    document.head.appendChild(link);\n  }\n\n  function selectCssUrl(cssAssets){\n    if (!cssAssets || typeof cssAssets !== \"object\") return null;\n    var parts = location.pathname.split(\"/\").filter(Boolean);\n    for (var i = 0; i < parts.length; i++) {\n      var asset = cssAssets[parts[i]];\n      if (asset && asset.cssUrl) return asset.cssUrl;\n    }\n    return cssAssets[\"\"] && cssAssets[\"\"].cssUrl ? cssAssets[\"\"].cssUrl : null;\n  }\n\n  connect();\n})();";
+export declare const HMR_CLIENT_SCRIPT = "(function(){\n  if (self.__AKAN_HMR_INSTALLED__) return;\n  self.__AKAN_HMR_INSTALLED__ = true;\n  var proto = location.protocol === \"https:\" ? \"wss:\" : \"ws:\";\n  var url = proto + \"//\" + location.host + \"/_akan/hmr\";\n  var attempts = 0;\n  var socket = null;\n  var lastBuildId = null;\n  var refreshRuntimePromise = null;\n  var refreshQueue = Promise.resolve();\n  var overlayEl = null;\n  var overlayLabelEl = null;\n  var overlayStyleEl = null;\n  var overlayTimer = null;\n  var overlayHideTimer = null;\n  var overlayNextToken = 1;\n  var overlayJobs = {};\n  self.__AKAN_HMR_PHASE__ = null;\n\n  // Bun's React Fast Refresh transform can emit top-level calls to these globals\n  // even when we fall back to full reload instead of applying React Refresh.\n  self.$RefreshReg$ = self.$RefreshReg$ || function(){};\n  self.$RefreshSig$ = self.$RefreshSig$ || function(){ return function(type){ return type; }; };\n\n  function connect(){\n    try { socket = new WebSocket(url); }\n    catch(e){ console.error(\"[akan-hmr] ws init failed\", e); schedule(); return; }\n    socket.addEventListener(\"open\", function(){ attempts = 0; });\n    socket.addEventListener(\"message\", function(ev){\n      var msg;\n      try { msg = JSON.parse(ev.data); } catch (e){ return; }\n      if (!msg || typeof msg.type !== \"string\") return;\n      if (msg.type === \"hello\") {\n        if (lastBuildId !== null && msg.buildId !== lastBuildId) {\n          location.reload();\n          return;\n        }\n        lastBuildId = msg.buildId;\n        return;\n      }\n      if (msg.type === \"reload\") {\n        beginHmrOverlay(\"Reloading...\", true);\n        try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}\n        setTimeout(function(){ location.reload(); }, 30);\n        return;\n      }\n      if (msg.type === \"rsc-refresh\") {\n        refreshRsc(msg);\n        return;\n      }\n      if (msg.type === \"client-refresh\") {\n        refreshClient(msg);\n        return;\n      }\n      if (msg.type === \"css-update\") {\n        var cssUrl = selectCssUrl(msg.cssAssets);\n        if (cssUrl) swapCss(cssUrl);\n        else {\n          beginHmrOverlay(\"Reloading...\", true);\n          location.reload();\n        }\n        return;\n      }\n      if (msg.type === \"error\") { console.error(\"[akan-hmr]\", msg.message); return; }\n    });\n    socket.addEventListener(\"close\", function(){ socket = null; schedule(); });\n    socket.addEventListener(\"error\", function(){ try { socket && socket.close(); } catch(e){} });\n  }\n\n  function schedule(){\n    attempts = Math.min(attempts + 1, 6);\n    var delay = Math.min(30000, 250 * Math.pow(2, attempts - 1));\n    setTimeout(connect, delay);\n  }\n\n  function ensureOverlay(){\n    if (overlayEl && overlayLabelEl) return overlayEl;\n    if (!overlayStyleEl) {\n      overlayStyleEl = document.createElement(\"style\");\n      overlayStyleEl.textContent =\n        \"@keyframes akan-hmr-spin{to{transform:rotate(360deg)}}\" +\n        \".__akan_hmr_overlay{position:fixed;left:16px;bottom:16px;z-index:2147483647;display:flex;align-items:center;gap:9px;padding:10px 12px;border-radius:999px;background:rgba(17,24,39,.94);color:#fff;font:500 13px/1.2 ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif;box-shadow:0 10px 28px rgba(0,0,0,.28);pointer-events:none;opacity:0;transform:translateY(6px);transition:opacity .15s ease,transform .15s ease;backdrop-filter:blur(8px)}\" +\n        \".__akan_hmr_overlay[data-show=true]{opacity:1;transform:translateY(0)}\" +\n        \".__akan_hmr_spinner{width:14px;height:14px;border:2px solid rgba(255,255,255,.32);border-top-color:#fff;border-radius:999px;animation:akan-hmr-spin .75s linear infinite;flex:none}\" +\n        \"@media (prefers-reduced-motion:reduce){.__akan_hmr_overlay{transition:none}.__akan_hmr_spinner{animation:none}}\";\n      document.head.appendChild(overlayStyleEl);\n    }\n    overlayEl = document.createElement(\"div\");\n    overlayEl.className = \"__akan_hmr_overlay\";\n    overlayEl.setAttribute(\"role\", \"status\");\n    overlayEl.setAttribute(\"aria-live\", \"polite\");\n    overlayEl.innerHTML = '<span class=\"__akan_hmr_spinner\" aria-hidden=\"true\"></span><span data-akan-hmr-label>Updating...</span>';\n    overlayLabelEl = overlayEl.querySelector(\"[data-akan-hmr-label]\");\n    (document.body || document.documentElement).appendChild(overlayEl);\n    return overlayEl;\n  }\n\n  function activeOverlayTokens(){\n    return Object.keys(overlayJobs);\n  }\n\n  function latestOverlayLabel(){\n    var keys = activeOverlayTokens();\n    if (keys.length === 0) return \"Updating...\";\n    return overlayJobs[keys[keys.length - 1]] || \"Updating...\";\n  }\n\n  function showOverlayNow(){\n    overlayTimer = null;\n    if (activeOverlayTokens().length === 0) return;\n    var el = ensureOverlay();\n    if (overlayHideTimer) {\n      clearTimeout(overlayHideTimer);\n      overlayHideTimer = null;\n    }\n    if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n    requestAnimationFrame(function(){ el.setAttribute(\"data-show\", \"true\"); });\n  }\n\n  function beginHmrOverlay(label, immediate){\n    var token = overlayNextToken++;\n    overlayJobs[token] = label || \"Updating...\";\n    if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n    if (overlayHideTimer) {\n      clearTimeout(overlayHideTimer);\n      overlayHideTimer = null;\n    }\n    if (immediate) {\n      if (overlayTimer) clearTimeout(overlayTimer);\n      showOverlayNow();\n    } else if (!overlayTimer && (!overlayEl || overlayEl.getAttribute(\"data-show\") !== \"true\")) {\n      overlayTimer = setTimeout(showOverlayNow, 120);\n    }\n    return token;\n  }\n\n  function setHmrOverlayLabel(token, label){\n    if (!overlayJobs[token]) return;\n    overlayJobs[token] = label || \"Updating...\";\n    if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n  }\n\n  function endHmrOverlay(token){\n    delete overlayJobs[token];\n    if (activeOverlayTokens().length > 0) {\n      if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n      return;\n    }\n    if (overlayTimer) {\n      clearTimeout(overlayTimer);\n      overlayTimer = null;\n    }\n    if (!overlayEl) return;\n    overlayEl.setAttribute(\"data-show\", \"false\");\n    if (overlayHideTimer) clearTimeout(overlayHideTimer);\n    overlayHideTimer = setTimeout(function(){\n      if (overlayEl && activeOverlayTokens().length === 0 && overlayEl.parentNode) {\n        overlayEl.parentNode.removeChild(overlayEl);\n        overlayEl = null;\n        overlayLabelEl = null;\n      }\n    }, 180);\n  }\n\n  function refreshRsc(msg){\n    var started = performance.now();\n    var overlayToken = beginHmrOverlay(\"Refreshing page...\");\n    try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}\n    if (!self.__AKAN_RSC_REFRESH__) {\n      console.warn(\"[akan-hmr] RSC refresh API unavailable, falling back to full reload\");\n      setHmrOverlayLabel(overlayToken, \"Reloading...\");\n      setTimeout(function(){ location.reload(); }, 30);\n      return;\n    }\n    Promise.resolve(self.__AKAN_RSC_REFRESH__({ buildId: msg.buildId })).then(function(){\n      lastBuildId = msg.buildId;\n      endHmrOverlay(overlayToken);\n      console.debug && console.debug(\"[akan-hmr] RSC refreshed\", {\n        buildId: msg.buildId,\n        generation: msg.generation,\n        routeIds: msg.routeIds,\n        changedFiles: msg.changedFiles && msg.changedFiles.length,\n        durationMs: Math.round(performance.now() - started)\n      });\n    }, function(err){\n      console.error(\"[akan-hmr] RSC refresh failed, falling back to full reload\", err);\n      setHmrOverlayLabel(overlayToken, \"Update failed, reloading...\");\n      setTimeout(function(){ location.reload(); }, 250);\n    });\n  }\n\n  function ensureRefreshRuntime(){\n    if (refreshRuntimePromise) return refreshRuntimePromise;\n    refreshRuntimePromise = import(\"react-refresh/runtime\").then(function(mod){\n      var runtime = mod.default || mod;\n      if (!self.__AKAN_REACT_REFRESH_READY__) {\n        runtime.injectIntoGlobalHook(self);\n        self.$RefreshReg$ = function(type, id){ runtime.register(type, id); };\n        self.$RefreshSig$ = runtime.createSignatureFunctionForTransform;\n        self.__AKAN_REACT_REFRESH_READY__ = true;\n        self.__AKAN_REACT_REFRESH_RUNTIME__ = runtime;\n      }\n      return runtime;\n    });\n    return refreshRuntimePromise;\n  }\n\n  function refreshClient(msg){\n    refreshQueue = refreshQueue.then(function(){ return doRefreshClient(msg); }, function(){ return doRefreshClient(msg); });\n  }\n\n  function setHmrPhase(phase){\n    self.__AKAN_HMR_PHASE__ = phase;\n  }\n\n  function doRefreshClient(msg){\n    var started = performance.now();\n    var metadataAt = started;\n    var importAt = started;\n    var refreshAt = started;\n    var overlayToken = beginHmrOverlay(\"Updating...\");\n    var fallbackToRsc = false;\n    return ensureRefreshRuntime().then(function(runtime){\n      setHmrOverlayLabel(overlayToken, \"Fetching update...\");\n      var endpoint = new URL(\"/_akan/hmr/client-refresh\", location.origin);\n      endpoint.searchParams.set(\"url\", location.href);\n      if (msg.buildId != null) endpoint.searchParams.set(\"buildId\", String(msg.buildId));\n      return fetch(endpoint, { credentials: \"same-origin\", cache: \"no-store\" })\n        .then(function(res){\n          if (!res.ok) throw new Error(\"client-refresh metadata failed \" + res.status + \" \" + res.statusText);\n          return res.json();\n        })\n        .then(function(info){\n          metadataAt = performance.now();\n          var chunks = Array.isArray(info.chunks) ? info.chunks : [];\n          if (chunks.length === 0) throw new Error(\"no client chunks returned\");\n          setHmrPhase(\"refresh-import\");\n          setHmrOverlayLabel(overlayToken, \"Importing update...\");\n          return Promise.all(chunks.map(function(chunk){ return import(chunk); })).then(function(){\n            importAt = performance.now();\n            setHmrPhase(\"react-refresh\");\n            setHmrOverlayLabel(overlayToken, \"Applying update...\");\n            try {\n              runtime.performReactRefresh();\n            } finally {\n              setHmrPhase(null);\n            }\n            refreshAt = performance.now();\n            lastBuildId = msg.buildId;\n            console.debug && console.debug(\"[akan-hmr] React Fast Refresh applied\", {\n              buildId: msg.buildId,\n              generation: msg.generation,\n              chunks: chunks.length,\n              routeIds: info.routeIds || msg.routeIds,\n              changedFiles: msg.changedFiles && msg.changedFiles.length,\n              metadataMs: Math.round(metadataAt - started),\n              importMs: Math.round(importAt - metadataAt),\n              refreshMs: Math.round(refreshAt - importAt),\n              durationMs: Math.round(refreshAt - started)\n            });\n            endHmrOverlay(overlayToken);\n          }, function(err){\n            setHmrPhase(null);\n            throw err;\n          });\n        });\n    }).catch(function(err){\n      console.warn(\"[akan-hmr] React Fast Refresh failed, falling back to RSC refresh\", err);\n      fallbackToRsc = true;\n      endHmrOverlay(overlayToken);\n      refreshRsc(msg);\n    }).finally(function(){\n      if (!fallbackToRsc) endHmrOverlay(overlayToken);\n    });\n  }\n\n  function swapCss(href){\n    var overlayToken = beginHmrOverlay(\"Updating styles...\");\n    var link = document.createElement(\"link\");\n    link.rel = \"stylesheet\";\n    link.href = href;\n    link.setAttribute(\"data-akan-css\", \"pending\");\n    link.addEventListener(\"load\", function(){\n      var prev = document.querySelectorAll(\"link[data-akan-css=active]\");\n      for (var i = 0; i < prev.length; i++) prev[i].parentNode && prev[i].parentNode.removeChild(prev[i]);\n      link.setAttribute(\"data-akan-css\", \"active\");\n      endHmrOverlay(overlayToken);\n    });\n    link.addEventListener(\"error\", function(){\n      if (link.parentNode) link.parentNode.removeChild(link);\n      endHmrOverlay(overlayToken);\n    });\n    document.head.appendChild(link);\n  }\n\n  function selectCssUrl(cssAssets){\n    if (!cssAssets || typeof cssAssets !== \"object\") return null;\n    var parts = location.pathname.split(\"/\").filter(Boolean);\n    for (var i = 0; i < parts.length; i++) {\n      var asset = cssAssets[parts[i]];\n      if (asset && asset.cssUrl) return asset.cssUrl;\n    }\n    return cssAssets[\"\"] && cssAssets[\"\"].cssUrl ? cssAssets[\"\"].cssUrl : null;\n  }\n\n  connect();\n})();";

package/types/server/rscClient.d.ts

@@ -1,7 +1,8 @@
+type InlineRscChunk = [1, string] | [3, string];
 declare global {
-    var __RSC_CHUNKS__: string[] | undefined;
+    var __RSC_CHUNKS__: InlineRscChunk[] | undefined;
     var __RSC_CLOSED__: boolean | undefined;
-    var __RSC_PUSH__: ((b64: string) => void) | undefined;
+    var __RSC_PUSH__: ((type: InlineRscChunk[0], data: string) => void) | undefined;
     var __RSC_CLOSE__: (() => void) | undefined;
     var __AKAN_RSC_NAVIGATE__: ((href: string, options?: {
         replace?: boolean;

package/types/server/rscHttp.d.ts

@@ -0,0 +1,2 @@
+export declare const RSC_CONTENT_TYPE = "text/x-component; charset=utf-8";
+export declare function isRscPayloadResponse(res: Response): boolean;

package/types/server/rscWorkerHost.d.ts

@@ -4,6 +4,7 @@ import type { AkanMetricsReport } from "akanjs/service";
 import type { ClientManifest } from "./artifact.d.ts";
 import type { BaseBuildArtifact, CssAsset } from "./types.d.ts";
 export type RscRedirectMethod = "replace" | "push";
+export type RscRedirectStatus = 303 | 307 | 308;
 export type RscRenderResult = {
     type: "stream";
     stream: ReadableStream<Uint8Array>;
@@ -13,6 +14,7 @@ export type RscRenderResult = {
     type: "redirect";
     location: string;
     method: RscRedirectMethod;
+    status: RscRedirectStatus;
 } | {
     type: "not-found";
 };

package/types/server/ssrFromRscRenderer.d.ts

@@ -1,4 +1,17 @@
 import type { SsrChunkRegistryStats, SsrFromRscInput } from "./ssrTypes.d.ts";
+export declare class SsrChunkRegistry<T> {
+    #private;
+    readonly maxEntries: number;
+    constructor(maxEntries?: number);
+    get size(): number;
+    get evictionCount(): number;
+    get(key: string): T | undefined;
+    set(keys: string[], value: T): void;
+}
+export type InlineRscChunk = readonly [1, string] | readonly [3, string];
+export declare function encodeInlineRscChunk(chunk: Uint8Array): InlineRscChunk;
+export declare function htmlEscapeJsonString(value: string): string;
+export declare function createInlineRscScript(chunk: Uint8Array): string;
 export declare class SsrFromRscRenderer {
     #private;
     static getChunkRegistryStats(): SsrChunkRegistryStats;

package/types/server/ssrTypes.d.ts

@@ -16,6 +16,7 @@ export interface SsrChunkRegistryStats {
     ssrChunkRegistrySize: number;
     ssrChunkLoadCount: number;
     ssrChunkCacheHitCount: number;
+    ssrChunkEvictionCount: number;
 }
 export interface SsrFromRscInput {
     request?: Request;

package/types/server/webRouter.d.ts

@@ -2,8 +2,10 @@ import { type AkanI18nConfig } from "akanjs/common";
 import type { AkanMetricsReport } from "akanjs/service";
 import { type BuilderRpc, type RouteSeedIndex } from "./artifact.d.ts";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub.d.ts";
-import { RscWorker } from "./rscWorkerHost.d.ts";
+import { type RscRedirectMethod, type RscRedirectStatus, RscWorker } from "./rscWorkerHost.d.ts";
 import type { BaseBuildArtifact, HttpRoutes, RenderState } from "./types.d.ts";
+export declare function createRscRedirectResponse(location: string, method: RscRedirectMethod, status?: RscRedirectStatus): Response;
+export declare function createRscStreamResponse(stream: BodyInit, status?: number): Response;
 export declare function normalizeRscTargetUrlForHostBasePath(targetUrl: URL, options: {
     basePath: string | null;
     basePaths?: readonly string[];

package/types/service/ipcTypes.d.ts

@@ -99,6 +99,7 @@ export interface AkanMetricsReport {
     ssrChunkRegistrySize?: number;
     ssrChunkLoadCount?: number;
     ssrChunkCacheHitCount?: number;
+    ssrChunkEvictionCount?: number;
     httpFullSsrCount?: number;
     httpRscNavigationCount?: number;
     httpStaticAssetCount?: number;