akanjs 3.0.0-beta.9 → 3.0.1

package/server/webRouter.ts

@@ -1,8 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
 import type { AkanWebConfig } from "akanjs";
-import { getEnv } from "akanjs/base";
 import {
   type AkanI18nConfig,
   DEFAULT_AKAN_I18N,
@@ -17,18 +15,16 @@ import type { AkanMetricsReport } from "akanjs/service";
 import type { PagePromptSource } from "../signal/mcp/pagePrompt";
 import {
   type BuilderRpc,
-  type ClientManifest,
   type MergedManifest,
   RouteClientCache,
   type RouteSeedIndex,
   RouteSeedIndexStore,
+  type RoutesManifest,
   RoutesManifestStore,
 } from "./artifact";
-import { resolveEncodedSidecar } from "./assetEncoding";
 import {
   getClientFacingOrigin,
   hasRouteCacheInvalidationScope,
-  isRouteCachePathAllowed,
   LruTtlCache,
   parsePositiveInt,
   type RouteCacheEntry,
@@ -39,10 +35,16 @@ import {
   shouldInvalidateRouteCacheEntry,
   shouldStoreRouteCache,
 } from "./cachePolicy";
-import { DevHmrController } from "./hmr";
+import { encodedFileResponse } from "./contentEncoding";
+import { isCrawlerUserAgent } from "./crawler";
 import { HMR_CLIENT_SCRIPT } from "./hmr/clientScript";
+import { CSR_DEV_ROUTE_PREFIX, resolveDevCsrMode, SSR_DEV_DIRNAME, SSR_DEV_ROUTE_PREFIX } from "./hmr/csrDevManifest";
+import { CsrDevShell } from "./hmr/csrDevShell";
+import { DevHmrController } from "./hmr/devHmrController";
+import { SsrDevShim } from "./hmr/ssrDevShim";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub";
 import { ImageOptimizer } from "./imageOptimizer";
+import { normalizeHost, resolveArtifactDir, warnIgnoredSubRouteBasePaths } from "./proxy/hostBasePathWebProxy";
 import { createDefaultRobotsTxt } from "./robots";
 import {
   AKAN_RSC_PATCH_HEAD_SAFE_HEADER,
@@ -57,6 +59,7 @@ import { createDefaultSitemapXml, getSitemapBasePath } from "./sitemap";
 import { SsrFromRscRenderer } from "./ssrFromRscRenderer";
 import type { RscTraceMetadata, SsrManifest } from "./ssrTypes";
 import { resolveStaticPath } from "./staticPath";
+import { getPathnameLocale } from "./systemPageDocument";
 import { createSubRouteIndexResponse, createSystemPageResponse, getSystemPageHomeHref } from "./systemPages";
 import { type BaseBuildArtifact, type HttpRoutes, type RenderState, resolveWebConfig } from "./types";
 
@@ -66,18 +69,6 @@ export const DEFAULT_HTML_RESULT_CACHE_MAX_BODY_BYTES = 2 * 1024 * 1024;
 const ROUTE_CACHE_SWEEP_INTERVAL_MS = 60_000;
 const APPLE_APP_SITE_ASSOCIATION_PATH = "/.well-known/apple-app-site-association";
 const ANDROID_ASSET_LINKS_PATH = "/.well-known/assetlinks.json";
-const FIREBASE_MESSAGING_SW_PATH = "/firebase-messaging-sw.js";
-const FIREBASE_WEB_SDK_VERSION = "12.13.0";
-
-interface FirebaseClientEnvConfig {
-  apiKey: string;
-  authDomain?: string;
-  projectId: string;
-  storageBucket?: string;
-  messagingSenderId: string;
-  appId: string;
-  vapidKey?: string;
-}
 
 export function createRscRedirectResponse(
   location: string,
@@ -205,26 +196,10 @@ export function resolveHtmlRouteCacheStoreTtl(input: {
   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>,
-  options: { defaultAllow?: boolean } = {},
-): boolean {
-  return isRouteCachePathAllowed(pathname, {
-    allow: env.AKAN_HTML_RESULT_CACHE_PATHS,
-    deny: env.AKAN_HTML_RESULT_CACHE_EXCLUDE_PATHS,
-    defaultAllow: options.defaultAllow,
-  });
-}
-
 export async function createRscNavigationStreamResponse(
   result: Extract<RscRenderResult, { type: "stream" }>,
 ): Promise<Response> {
-
+  
   const response = createRscStreamResponse(result.stream, result.status ?? 200);
   appendRscTraceHeaders(response.headers, result.trace);
   return response;
@@ -245,6 +220,13 @@ export function normalizeRscTargetUrlForHostBasePath(
   const segments = targetUrl.pathname.split("/").filter(Boolean);
   const [locale, firstPath] = segments;
   if (!locale || !i18n.locales.includes(locale)) return { url: targetUrl, basePath: null };
+  
+  if (basePath) {
+    if (firstPath === basePath) return { url: targetUrl, basePath };
+    const normalized = new URL(targetUrl);
+    normalized.pathname = `/${[locale, basePath, ...segments.slice(1)].join("/")}`;
+    return { url: normalized, basePath };
+  }
 
   const targetBasePath = firstPath && basePaths.includes(firstPath) ? firstPath : null;
   if (seedEntries && routeMatches(targetUrl)) return { url: targetUrl, basePath: targetBasePath ?? basePath };
@@ -259,12 +241,6 @@ export function normalizeRscTargetUrlForHostBasePath(
   return { url: targetUrl, basePath: basePath ?? targetBasePath };
 }
 
-export interface SsrRoutesResult {
-  renderEnvRoutes: HttpRoutes;
-  hmrHub: HmrWsHub | null;
-  builderRpc: BuilderRpc | null;
-}
-
 export interface SsrRoutesInputs {
   web: AkanWebConfig;
   upgradeHmrWs: (req: Request, data: HmrWsData) => boolean;
@@ -277,6 +253,8 @@ interface WebRouterOptions {
   rsc: RscWorker;
   seedIndex: RouteSeedIndex;
   upgradeHmrWs: (req: Request, data: HmrWsData) => boolean;
+  /** The production build's route manifest, which the worker was already handed at boot. */
+  prebuilt?: RoutesManifest | null;
 }
 
 interface CachedHtmlResult {
@@ -288,21 +266,19 @@ interface CachedHtmlResult {
 
 export class WebRouter {
   #logger = new Logger("WebRouter");
-  #artifactDir = WebRouter.#resolveArtifactDir();
+  #artifactDir = resolveArtifactDir();
   #artifact: BaseBuildArtifact;
   #subRoutes: Record<string, string[]>;
   #rsc: RscWorker;
   #hub: HmrWsHub | null = null;
-  /**
-   * `akan start` is the dev server whatever the environment claims. Its artifact directory carries no routes
-   * manifest — only `akan build` writes one — so the production branch cannot build a route on demand and
-   * throws on every request instead. `NODE_ENV` arrives by accident often enough (a workspace `.env` Bun loads
-   * on its own, a CI image default) that the command which started this process has to outrank it.
-   */
+
   #prodMode = process.env.NODE_ENV === "production" && process.env.AKAN_COMMAND_TYPE !== "start";
   #builderRpc: BuilderRpc | null;
   #routeCache: RouteClientCache;
   #devHmr: DevHmrController | null = null;
+  #csrDevShell: CsrDevShell | null = null;
+  /** Dev only: SSR pages load their client code from the dev module registry it serves. */
+  #ssrDevShell: CsrDevShell | null = null;
   #csrArmed = false;
   #csrOnDemandBuild: Promise<unknown> | null = null;
   readonly #requestStats = {
@@ -328,7 +304,8 @@ export class WebRouter {
   /** What this router actually mounts, already intersected with what the artifact carries. */
   readonly web: AkanWebConfig;
   #seedIndex: RouteSeedIndex;
-  constructor({ artifact, web, cssBytesByUrl, rsc, seedIndex, upgradeHmrWs }: WebRouterOptions) {
+  readonly #prebuilt: RoutesManifest | null;
+  constructor({ artifact, web, cssBytesByUrl, rsc, seedIndex, upgradeHmrWs, prebuilt = null }: WebRouterOptions) {
     this.#logger.verbose(`[SSR] loaded ${Object.keys(cssBytesByUrl).length} CSS assets`);
     this.web = web;
     if (process.env.NODE_ENV === "production" && !this.#prodMode)
@@ -340,10 +317,7 @@ export class WebRouter {
       env: process.env.AKAN_SUB_ROUTE_HOSTS,
     });
     this.#subRoutes = subRoutes;
-    if (ignoredBasePaths.length)
-      this.#logger.warn(
-        `AKAN_SUB_ROUTE_HOSTS names basePaths this build does not serve, ignoring: ${ignoredBasePaths.join(", ")}`,
-      );
+    warnIgnoredSubRouteBasePaths(this.#logger, ignoredBasePaths);
     this.#rsc = rsc;
     this.renderState = {
       buildId: 0,
@@ -351,37 +325,44 @@ export class WebRouter {
       cssBytesByUrl,
     };
     this.#seedIndex = seedIndex;
+    this.#prebuilt = prebuilt;
     if (this.#prodMode) {
       this.#builderRpc = null;
-      this.#routeCache = this.#getProductionRouteCache();
+      this.#routeCache = new RouteClientCache({
+        buildRoute: async (routeId) => {
+          throw new Error(
+            `[SSR] route ${routeId} missing from production artifact — rebuild with \`akan build\` to include it`,
+          );
+        },
+      });
     } else {
       this.#devHmr = new DevHmrController({
+        artifactDir: this.#artifactDir,
         renderState: this.renderState,
         rsc: this.#rsc,
         seedIndex: this.#seedIndex,
         upgradeHmrWs,
+        pagesBundlePath: this.#artifact.pagesBundlePath,
       });
       this.#builderRpc = this.#devHmr.builderRpc;
       this.#routeCache = this.#devHmr.routeCache;
       this.#hub = this.#devHmr.hub;
+      if (resolveDevCsrMode() === "registry") this.#csrDevShell = new CsrDevShell(this.#artifactDir);
+      this.#ssrDevShell = new CsrDevShell(this.#artifactDir, {
+        dirName: SSR_DEV_DIRNAME,
+        routePrefix: SSR_DEV_ROUTE_PREFIX,
+      });
     }
   }
 
   async initializeRoute() {
-    const prebuilt = this.#prodMode ? await RoutesManifestStore.read(this.#artifactDir) : null;
-    if (prebuilt) {
-      this.#routeCache.seed(prebuilt);
-      await this.#rsc.reload({
-        clientManifest: this.#mergeRuntimeManifest().clientManifest,
-        cssAssets: this.renderState.cssAssets,
-        buildId: this.renderState.buildId,
-      });
-    }
+    if (this.#prebuilt) this.#routeCache.seed(this.#prebuilt);
 
     const clientServePrefix = `/_akan/client`;
     const clientOutputDir = `${this.#artifactDir}/client`;
-    const csrOutputDir = WebRouter.#resolveCsrDir(this.#artifactDir);
-    const publicDir = path.join(WebRouter.#resolveAppDir(), "public");
+    const localCsrDir = path.join(process.cwd(), "csr");
+    const csrOutputDir = fs.existsSync(localCsrDir) ? localCsrDir : path.join(this.#artifactDir, "csr");
+    const publicDir = path.join(process.env.AKAN_APP_DIR ?? path.dirname(Bun.main), "public");
     const imageCacheDir = path.join(this.#artifactDir, "image-cache");
     const imageOptimizer = new ImageOptimizer({
       publicDir,
@@ -393,8 +374,9 @@ export class WebRouter {
     const renderEnvRoutes: HttpRoutes = {
       ...(this.web.csr
         ? {
-            "/__csr": async () => {
+            "/__csr": async (req) => {
               this.#requestStats.csr += 1;
+              if (this.#csrDevShell) return await this.#serveCsrDevShell(req, "/", this.#csrDevShell);
               const csrHtml = await this.#resolveCsrHtml(csrOutputDir, "/");
               const csrFile = csrHtml ? Bun.file(csrHtml) : null;
               const htmlText =
@@ -413,7 +395,23 @@ export class WebRouter {
     <script type="module" src="/csr.js"></script>
   </body>
 </html>`;
-              return new Response(this.#withCsrHmr(htmlText), { headers: WebRouter.#htmlResponseHeaders(200) });
+              return new Response(this.#withCsrHmr(htmlText), { headers: this.#htmlResponseHeaders(200) });
+            },
+            ...(this.#csrDevShell
+              ? {
+                  [`${CSR_DEV_ROUTE_PREFIX}*`]: async (req: Request) => {
+                    this.#requestStats.staticAsset += 1;
+                    return (await this.#csrDevShell?.serve(req)) ?? new Response("Not Found", { status: 404 });
+                  },
+                }
+              : {}),
+          }
+        : {}),
+      ...(this.#ssrDevShell
+        ? {
+            [`${SSR_DEV_ROUTE_PREFIX}*`]: async (req: Request) => {
+              this.#requestStats.staticAsset += 1;
+              return (await this.#ssrDevShell?.serve(req)) ?? new Response("Not Found", { status: 404 });
             },
           }
         : {}),
@@ -441,10 +439,14 @@ export class WebRouter {
         }
         const cssBytes = this.renderState.cssBytesByUrl[url.pathname];
         if (!cssBytes) return new Response("Not Found", { status: 404 });
-        return WebRouter.#bytesResponse(req, cssBytes, {
+        const headers = WebRouter.#baseAssetHeaders({
           contentType: "text/css; charset=utf-8",
           cacheControl: "no-store",
         });
+        return new Response(
+          cssBytes.buffer.slice(cssBytes.byteOffset, cssBytes.byteOffset + cssBytes.byteLength) as ArrayBuffer,
+          { headers },
+        );
       },
       "/_akan/fonts/*": (req) => {
         this.#requestStats.staticAsset += 1;
@@ -462,19 +464,16 @@ export class WebRouter {
       },
       ...(!this.#prodMode
         ? {
-            "/_akan/hmr": (req: Request) => {
-              return this.#devHmr?.handleWs(req) ?? new Response("HMR unavailable", { status: 404 });
-            },
-            "/_akan/hmr/client-refresh": (req: Request) =>
-              this.#devHmr?.handleClientRefresh(req) ?? new Response("HMR unavailable", { status: 404 }),
+            "/_akan/hmr": (req: Request) =>
+              this.#devHmr?.handleWs(req) ?? new Response("HMR unavailable", { status: 404 }),
           }
         : {}),
       "/__rsc": async (req) => {
         this.#requestStats.rscNavigation += 1;
         try {
           const reqUrl = new URL(req.url);
-          /** After TLS/pass-through proxies Bun often sees internal http origins; forwarded headers preserve the browser origin for same-origin checks. */
-          const clientOrigin = WebRouter.#clientFacingOrigin(req);
+          
+          const clientOrigin = getClientFacingOrigin(req);
           const target = reqUrl.searchParams.get("url");
           const rawTargetUrl = target ? new URL(target, clientOrigin) : reqUrl;
           const requestBasePath = this.#requestBasePath(req);
@@ -490,6 +489,12 @@ export class WebRouter {
           const manifest = await this.#ensureRoute(targetUrl);
           const rscHeaders = new Headers(req.headers);
           if (normalizedTarget.basePath) rscHeaders.set("x-base-path", normalizedTarget.basePath);
+          
+          const [, targetLocale = "", ...targetPath] = rawTargetUrl.pathname.split("/");
+          if (this.#artifact.i18n.locales.includes(targetLocale)) {
+            rscHeaders.set("x-locale", targetLocale);
+            rscHeaders.set("x-path", `/${targetPath.join("/")}`);
+          }
           const rscReq = new Request(targetUrl, {
             method: "GET",
             headers: rscHeaders,
@@ -500,7 +505,7 @@ export class WebRouter {
           });
           if (result.type === "redirect")
             return createRscRedirectResponse(result.location, result.method, result.status);
-          if (result.type === "not-found") return WebRouter.#rscNotFoundResponse();
+          if (result.type === "not-found") return createRscNotFoundFallbackResponse();
           if (result.status && result.status >= 500)
             return this.#renderRscErrorResponse("__rsc", "Internal Server Error");
           return createRscNavigationStreamResponse(result);
@@ -526,19 +531,9 @@ export class WebRouter {
           status: 404,
           headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" },
         }),
-      [FIREBASE_MESSAGING_SW_PATH]: async () => {
-        this.#requestStats.staticAsset += 1;
-        const firebaseConfig = await WebRouter.#resolveFirebaseClientConfig();
-        return new Response(WebRouter.#createFirebaseMessagingServiceWorker(firebaseConfig), {
-          headers: WebRouter.#baseAssetHeaders({
-            contentType: "application/javascript; charset=utf-8",
-            cacheControl: "no-store",
-          }),
-        });
-      },
       "/*": async (req) => {
         const url = new URL(req.url);
-        if (WebRouter.#isImageOptimizerPath(url.pathname)) {
+        if (url.pathname.endsWith("/_akan/image")) {
           this.#requestStats.image += 1;
           return imageOptimizer.handle(req);
         }
@@ -547,10 +542,11 @@ export class WebRouter {
           const isCsr = url.searchParams.get("csr") === "true";
           if (isCsr) {
             this.#requestStats.csr += 1;
+            if (this.#csrDevShell) return await this.#serveCsrDevShell(req, url.pathname, this.#csrDevShell);
             const csrHtml = await this.#resolveCsrHtml(csrOutputDir, url.pathname);
             if (!csrHtml) return this.#csrUnavailableResponse(url.pathname);
             const html = await Bun.file(csrHtml).text();
-            return new Response(this.#withCsrHmr(html), { headers: WebRouter.#htmlResponseHeaders(200) });
+            return new Response(this.#withCsrHmr(html), { headers: this.#htmlResponseHeaders(200) });
           }
 
           const csrAssetPath = path.extname(url.pathname) ? resolveStaticPath(csrOutputDir, url.pathname) : null;
@@ -564,14 +560,12 @@ export class WebRouter {
         }
 
         const filePath = resolveStaticPath(publicDir, url.pathname);
-        if (filePath) {
-          if (await Bun.file(filePath).exists()) {
-            this.#requestStats.staticAsset += 1;
-            return WebRouter.#fileResponse(req, filePath, {
-              contentType: Bun.file(filePath).type || "application/octet-stream",
-              cacheControl: this.#prodMode ? "public, max-age=300" : "no-store",
-            });
-          }
+        if (filePath && (await Bun.file(filePath).exists())) {
+          this.#requestStats.staticAsset += 1;
+          return WebRouter.#fileResponse(req, filePath, {
+            contentType: Bun.file(filePath).type || "application/octet-stream",
+            cacheControl: this.#prodMode ? "public, max-age=300" : "no-store",
+          });
         }
 
         if (url.pathname === "/robots.txt") {
@@ -587,7 +581,7 @@ export class WebRouter {
         if (sitemapBasePath !== undefined) {
           return new Response(
             createDefaultSitemapXml({
-              origin: WebRouter.#clientFacingOrigin(req),
+              origin: getClientFacingOrigin(req),
               basePath: sitemapBasePath,
               entries: this.#seedIndex.entries,
               i18n: parseAkanI18nEnv(),
@@ -607,11 +601,12 @@ export class WebRouter {
         try {
           this.#requestStats.fullSsr += 1;
           const manifest = await this.#ensureRoute(url);
-          const htmlCacheDecision = this.#getHtmlCacheEntry(req, url);
+          const isCrawler = isCrawlerUserAgent(req.headers.get("user-agent"));
+          const htmlCacheDecision = this.#getHtmlCacheEntry(req, url, isCrawler);
           const htmlCacheEntry = htmlCacheDecision.entry;
           const cachedHtml = htmlCacheEntry ? this.#getCachedHtml(htmlCacheEntry.key) : null;
           if (cachedHtml) {
-            const cachedHeaders = WebRouter.#htmlResponseHeaders(200);
+            const cachedHeaders = this.#htmlResponseHeaders(200);
             cachedHeaders.set("X-Akan-Cache", "HIT");
             return new Response(cachedHtml, { headers: cachedHeaders });
           }
@@ -629,6 +624,9 @@ export class WebRouter {
             rscResult.trace?.routeState
               ? `self.__AKAN_RSC_INITIAL_STATE__=${JSON.stringify(rscResult.trace.routeState)};`
               : "",
+            this.#ssrDevShell
+              ? SsrDevShim.script(await this.#ssrDevShell.readManifest(), Object.keys(this.#artifact.vendorMap))
+              : "",
             !this.#prodMode ? HMR_CLIENT_SCRIPT : "",
           ]
             .filter(Boolean)
@@ -641,15 +639,19 @@ export class WebRouter {
             bootstrapModules: [this.#artifact.rscClientUrl],
             extraBootstrapInline: extraBootstrapInline || undefined,
             importmap: this.#artifact.vendorMap,
-            theme: cookieTheme ?? rscResult.theme ?? "system",
+            
+            get theme() {
+              return cookieTheme ?? rscResult.theme ?? "system";
+            },
             lateControl: rscResult.lateControl,
             waitForAllReady: rscResult.trace?.ssrBlocking ?? false,
+            inlineBoundaries: isCrawler,
             onCancel: (reason: unknown) => {
               rscResult.cancel(reason);
             },
           });
           const responseStatus = rscResult.status ?? 200;
-          const responseHeaders = WebRouter.#htmlResponseHeaders(responseStatus);
+          const responseHeaders = this.#htmlResponseHeaders(responseStatus);
           if (req.method === "HEAD") {
             const headers = new Headers(responseHeaders);
             if (htmlCacheEntry && responseStatus === 200) headers.set("X-Akan-Cache", "MISS");
@@ -687,7 +689,7 @@ export class WebRouter {
               cacheHtmlWhileStreaming(
                 htmlStream,
                 (html) => {
-                  this.#setCachedHtml(htmlCacheEntry.key, html, htmlStoreTtl, htmlCacheMetadata);
+                  this.#htmlCache.set(htmlCacheEntry.key, { html, ...htmlCacheMetadata }, htmlStoreTtl);
                 },
                 {
                   shouldCache: () => shouldCacheHtml,
@@ -721,6 +723,12 @@ export class WebRouter {
     };
     return { renderEnvRoutes, hmrHub: this.#hub, builderRpc: this.#builderRpc };
   }
+  refreshHmrState(): void {
+    this.#devHmr?.refreshRegistryState();
+  }
+  hmrBuildErrors(): { phase: string }[] {
+    return this.#devHmr?.buildErrorMessages() ?? [];
+  }
   dispose() {
     this.#devHmr?.dispose();
     this.#devHmr = null;
@@ -733,7 +741,6 @@ export class WebRouter {
     this.#rsc.setLogLevel(minSev);
   }
 
-  /** Page prompts live with the pages, in the RSC worker; the MCP router reaches them through this. */
   pagePrompts(): PagePromptSource {
     return {
       list: () => this.#rsc.listPagePrompts(),
@@ -766,7 +773,6 @@ export class WebRouter {
     };
   }
 
-  /** @internal Clears or scopes invalidation for local route result caches owned by the host and RSC worker. */
   invalidateRouteCaches(invalidation?: string | RouteCacheInvalidation): void {
     const payload = typeof invalidation === "string" ? { reason: invalidation } : invalidation;
     if (!hasRouteCacheInvalidationScope(payload)) {
@@ -786,19 +792,6 @@ export class WebRouter {
     this.#rsc.invalidateRouteResultCache(invalidation);
   }
 
-  /**
-   * 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 {
-    return getClientFacingOrigin(req);
-  }
-
-  /**
-   * `x-base-path` is set by `HostBasePathWebProxy`, but it reaches here from the wire too, so it is checked against
-   * the basePaths this build serves — the same check `getBasePathFromPathname` already applies to it. An unknown
-   * value falls through to host matching instead of routing the request into a basePath that resolves to nothing.
-   */
   #requestBasePath(req: Request): string | null {
     const headerBasePath = req.headers.get("x-base-path");
     if (headerBasePath && this.#artifact.basePaths.includes(headerBasePath)) return headerBasePath;
@@ -806,12 +799,10 @@ export class WebRouter {
   }
 
   static #basePathForRequestHost(req: Request, subRoutes: Record<string, string[]>): string | null {
-    const host = (req.headers.get("x-forwarded-host") ?? req.headers.get("host") ?? "")
-      .toLowerCase()
-      .replace(/:\d+$/, "");
+    const host = normalizeHost(req.headers.get("x-forwarded-host")?.split(",")[0]?.trim() ?? req.headers.get("host"));
     if (!host) return null;
     for (const [basePath, domains] of Object.entries(subRoutes)) {
-      if (domains.some((domain) => domain.toLowerCase().replace(/:\d+$/, "") === host)) return basePath;
+      if (domains.some((domain) => normalizeHost(domain) === host)) return basePath;
     }
     return null;
   }
@@ -826,11 +817,17 @@ export class WebRouter {
     }
   }
 
-  #getHtmlCacheEntry(req: Request, url: URL): { entry: RouteCacheEntry | null; reason?: string } {
+  #getHtmlCacheEntry(req: Request, url: URL, isCrawler: boolean): { entry: RouteCacheEntry | null; reason?: string } {
+
+    if (this.#ssrDevShell) {
+      this.#htmlCacheBypass += 1;
+      return { entry: null, reason: "dev-registry" };
+    }
     const decision = resolvePublicRouteCacheEntryDecision({
       request: req,
       url,
       theme: WebRouter.#cookieValue(req, "theme"),
+      variant: isCrawler ? "crawler" : undefined,
       defaultEnabled: this.#prodMode,
       defaultAllow: this.#prodMode,
       env: {
@@ -854,18 +851,10 @@ export class WebRouter {
     return cached.html;
   }
 
-  #setCachedHtml(cacheKey: string, html: string, ttl: number, metadata: Omit<CachedHtmlResult, "html">): void {
-    this.#htmlCache.set(cacheKey, { html, ...metadata }, ttl);
-  }
-
   static #cookieValue(req: Request, name: string): string | undefined {
     return parseCookieHeader(req.headers.get("cookie") ?? "").get(name)?.value;
   }
 
-  static #isImageOptimizerPath(pathname: string): boolean {
-    return pathname === "/_akan/image" || pathname.endsWith("/_akan/image");
-  }
-
   async #ensureRoute(url: URL) {
     const started = Date.now();
     const matched =
@@ -878,21 +867,17 @@ export class WebRouter {
     return this.#mergeRuntimeManifest();
   }
 
-  /**
-   * Memoized on the route cache's revision. Both the snapshot and the runtime merge copy the whole client manifest
-   * and SSR module map, which is a few hundred KB of structure for a small app — and this ran on every request. In
-   * production the revision never moves after `seed`, so the manifest is built once; in dev a rebuild bumps it and
-   * the next request pays for one fresh copy. The cached object is still a copy, so an in-flight request keeps
-   * consuming a stable manifest across an invalidate exactly as the per-request snapshot made it.
-   */
   #mergeRuntimeManifest(): MergedManifest {
     const revision = this.#routeCache.revision;
     if (this.#runtimeManifest?.revision === revision) return this.#runtimeManifest.manifest;
     const snapshot = this.#routeCache.snapshot();
     const manifest: MergedManifest = {
       ...snapshot,
-      clientManifest: WebRouter.#mergeClientManifest(this.#artifact.rscRuntimeClientManifest, snapshot.clientManifest),
-      ssrManifest: WebRouter.#mergeSsrManifest(this.#artifact.rscRuntimeSsrManifest, snapshot.ssrManifest),
+      clientManifest: Object.assign({}, this.#artifact.rscRuntimeClientManifest, snapshot.clientManifest),
+      ssrManifest: {
+        moduleLoading: null,
+        moduleMap: Object.assign({}, this.#artifact.rscRuntimeSsrManifest?.moduleMap, snapshot.ssrManifest.moduleMap),
+      },
     };
     this.#runtimeManifest = { revision, manifest };
     return manifest;
@@ -902,24 +887,18 @@ export class WebRouter {
       kind: "not-found",
       method: req.method,
       pathname: url.pathname,
-      lang: WebRouter.#getLocale(url.pathname, this.#artifact.i18n),
+      lang: getPathnameLocale(url.pathname, this.#artifact.i18n),
       homeHref: this.#getSystemPageHomeHref(req, url.pathname),
       stylesheetHref: this.#getStylesheetHref(req, url.pathname),
     });
   }
 
-  /**
-   * A build with subRoutes must keep every route file under `page/<basePath>`, so the site root owns no page and
-   * answers 404 — including the URL `akan start` opens a browser on. Locally that reads as a broken app, so serve a
-   * picker of the basePaths this build carries instead. Deployed hosts never reach it: `HostBasePathWebProxy`
-   * rewrites the root onto the basePath its host maps to before the router sees it.
-   */
   #localSubRouteIndexResponse(req: Request, url: URL): Promise<Response> | null {
     if (process.env.AKAN_PUBLIC_ENV !== "local" || !this.#artifact.basePaths.length) return null;
     if (!WebRouter.#isSiteRootPathname(url.pathname, this.#artifact.i18n)) return null;
     return createSubRouteIndexResponse({
       method: req.method,
-      locale: WebRouter.#getLocale(url.pathname, this.#artifact.i18n),
+      locale: getPathnameLocale(url.pathname, this.#artifact.i18n),
       basePaths: this.#artifact.basePaths,
       subRoutes: this.#subRoutes,
     });
@@ -940,11 +919,12 @@ export class WebRouter {
       kind: "error",
       method: req.method,
       pathname: scope,
-      lang: WebRouter.#getLocale(new URL(req.url).pathname, this.#artifact.i18n),
+      lang: getPathnameLocale(new URL(req.url).pathname, this.#artifact.i18n),
       homeHref: this.#getSystemPageHomeHref(req, new URL(req.url).pathname),
       stylesheetHref: this.#getStylesheetHref(req, new URL(req.url).pathname),
       showDetails: !this.#prodMode,
       error: err,
+      ...(this.#prodMode ? {} : { script: `self.__AKAN_HMR_SYSTEM_PAGE__=true;${HMR_CLIENT_SCRIPT}` }),
     });
   }
 
@@ -994,25 +974,31 @@ export class WebRouter {
     return this.renderState.cssAssets[basePath ?? ""]?.cssUrl ?? null;
   }
 
-  static #getLocale(pathname: string, i18n: AkanI18nConfig): string {
-    const [segment] = pathname.split("/").filter(Boolean);
-    return segment && i18n.locales.includes(segment) ? segment : i18n.defaultLocale;
-  }
-
-  static #htmlResponseHeaders(status: number): Headers {
+  #htmlResponseHeaders(status: number): Headers {
     const headers = new Headers({ "Content-Type": "text/html; charset=utf-8" });
-    if (status >= 400) headers.set("Cache-Control", "no-store");
+    if (status >= 400 || !this.#prodMode) headers.set("Cache-Control", "no-store");
     return WebRouter.#applySecurityHeaders(headers, { html: true });
   }
   #withCsrHmr(html: string): string {
     if (this.#prodMode) return html;
-    return WebRouter.#injectBeforeBodyEnd(html, `<script>${HMR_CLIENT_SCRIPT}</script>`);
+    const csrGeneration = this.renderState.csrGeneration ?? null;
+    const flags = `self.__AKAN_HMR_CLIENT__="csr";self.__AKAN_CSR_GENERATION__=${csrGeneration};`;
+    return WebRouter.#injectBeforeBodyEnd(html, `<script>${flags}${HMR_CLIENT_SCRIPT}</script>`);
+  }
+  
+  async #serveCsrDevShell(req: Request, pathname: string, shell: CsrDevShell): Promise<Response> {
+    await this.#armCsrArtifact(pathname);
+    const basePath =
+      getBasePathFromPathname(pathname, { basePaths: this.#artifact.basePaths, i18n: this.#artifact.i18n }) ?? "";
+    const html = await shell.render({
+      basePath,
+      lang: "en",
+      title: process.env.AKAN_PUBLIC_APP_NAME ?? "akan",
+      cssHref: this.#getStylesheetHref(req, pathname),
+    });
+    if (!html) return this.#csrUnavailableResponse(pathname);
+    return new Response(this.#withCsrHmr(html), { headers: this.#htmlResponseHeaders(200) });
   }
-  /**
-   * Resolve a CSR html file, asking the builder to build the artifact first if it is not there yet.
-   * Dev CSR is only reachable through `/__csr` and `?csr=true`, so the builder skips it until one of
-   * them is requested; the first request pays for the build and every save keeps it in sync after.
-   */
   async #resolveCsrHtml(csrOutputDir: string, pathname: string): Promise<string | null> {
     const resolved = WebRouter.#resolveCsrHtmlPath(csrOutputDir, pathname, this.#artifact);
     if (resolved) return resolved;
@@ -1021,7 +1007,7 @@ export class WebRouter {
   }
   #armCsrArtifact(reason: string): Promise<unknown> {
     const rpc = this.#builderRpc;
-
+    
     if (this.#csrArmed || !rpc) return Promise.resolve();
     this.#csrOnDemandBuild ??= rpc
       .buildCsr(reason)
@@ -1049,33 +1035,34 @@ 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 #rscNotFoundResponse(): Response {
-    return createRscNotFoundFallbackResponse();
-  }
-  #getProductionRouteCache() {
-    return new RouteClientCache({
-      buildRoute: async (routeId) => {
-        throw new Error(
-          `[SSR] route ${routeId} missing from production artifact — rebuild with \`akan build\` to include it`,
-        );
-      },
-    });
-  }
 
-  /**
-   * `null` when the build produced no web artifact — an api-only build, or a workspace with no `page/` at all.
-   * The caller boots without a web surface instead of failing on the missing file.
-   */
+  /** `null` when the build has no web artifact (an api-only build, or no `page/`): boot without a web surface. */
   static async create({ web, upgradeHmrWs }: SsrRoutesInputs): Promise<WebRouter | null> {
-    const artifactDir = WebRouter.#resolveArtifactDir();
+    const artifactDir = resolveArtifactDir();
     const artifactFile = Bun.file(path.join(artifactDir, "base-artifact.json"));
     if (!(await artifactFile.exists())) return null;
     const artifact = WebRouter.#normalizeArtifact((await artifactFile.json()) as BaseBuildArtifact, artifactDir);
     const builtWeb = resolveWebConfig(artifact.web);
     if (!builtWeb.ssr) return null;
     const cssBytesByUrl = await WebRouter.#loadCssBytesByUrl(artifact, artifactDir);
-    const rsc = new RscWorker(artifact);
-    await rsc.ready;
+    const prodMode = process.env.NODE_ENV === "production" && process.env.AKAN_COMMAND_TYPE !== "start";
+
+    const prebuilt = prodMode ? await RoutesManifestStore.read(artifactDir) : null;
+    const rsc = new RscWorker(
+      prebuilt
+        ? {
+            ...artifact,
+            rscRuntimeClientManifest: { ...artifact.rscRuntimeClientManifest, ...prebuilt.clientManifest },
+          }
+        : artifact,
+      { failBeforeReady: prodMode },
+    );
+    if (prodMode)
+      void rsc.ready.catch((error: unknown) => {
+        new Logger("WebRouter").error(`RSC worker failed to load the pages bundle: ${String(error)}`);
+        process.exit(1);
+      });
+    else await rsc.ready;
     const seedIndex = await RouteSeedIndexStore.load(artifactDir);
     return new WebRouter({
       artifact,
@@ -1084,92 +1071,10 @@ export class WebRouter {
       rsc,
       seedIndex,
       upgradeHmrWs,
+      prebuilt,
     });
   }
 
-  static #resolveArtifactDir() {
-    const localArtifactDir = path.join(process.cwd(), ".akan", "artifact");
-    if (fs.existsSync(path.join(localArtifactDir, "base-artifact.json"))) return localArtifactDir;
-    return path.join(process.cwd(), "apps", getEnv().appName, ".akan", "artifact");
-  }
-
-  static #resolveAppDir() {
-    return process.env.AKAN_APP_DIR ?? path.dirname(Bun.main);
-  }
-
-  static async #resolveFirebaseClientConfig(): Promise<FirebaseClientEnvConfig | null> {
-    const envPath = path.join(WebRouter.#resolveAppDir(), "env", "env.client.ts");
-    if (!fs.existsSync(envPath)) return null;
-    try {
-      const envUrl = pathToFileURL(envPath);
-      envUrl.searchParams.set("t", String(Date.now()));
-      const envModule = (await import(envUrl.href)) as { env?: { firebase?: unknown } };
-      return WebRouter.#normalizeFirebaseClientConfig(envModule.env?.firebase);
-    } catch {
-      return null;
-    }
-  }
-
-  static #normalizeFirebaseClientConfig(config: unknown): FirebaseClientEnvConfig | null {
-    if (!config || typeof config !== "object") return null;
-    const value = config as Partial<Record<keyof FirebaseClientEnvConfig, unknown>>;
-    if (
-      typeof value.apiKey !== "string" ||
-      typeof value.projectId !== "string" ||
-      typeof value.messagingSenderId !== "string" ||
-      typeof value.appId !== "string"
-    ) {
-      return null;
-    }
-    return {
-      apiKey: value.apiKey,
-      ...(typeof value.authDomain === "string" ? { authDomain: value.authDomain } : {}),
-      projectId: value.projectId,
-      ...(typeof value.storageBucket === "string" ? { storageBucket: value.storageBucket } : {}),
-      messagingSenderId: value.messagingSenderId,
-      appId: value.appId,
-    };
-  }
-
-  static #createFirebaseMessagingServiceWorker(config: FirebaseClientEnvConfig | null): string {
-    const configJson = JSON.stringify(config);
-    return `/* Generated by Akan.js. Do not edit. */
-const firebaseConfig = ${configJson};
-
-if (firebaseConfig) {
-  importScripts("https://www.gstatic.com/firebasejs/${FIREBASE_WEB_SDK_VERSION}/firebase-app-compat.js");
-  importScripts("https://www.gstatic.com/firebasejs/${FIREBASE_WEB_SDK_VERSION}/firebase-messaging-compat.js");
-
-  firebase.initializeApp(firebaseConfig);
-  const messaging = firebase.messaging();
-
-  const notificationUrl = (payload) =>
-    payload?.data?.url || payload?.fcmOptions?.link || payload?.notification?.click_action;
-
-  messaging.onBackgroundMessage((payload) => {
-    const title = payload?.notification?.title || "";
-    const options = {
-      body: payload?.notification?.body,
-      icon: payload?.notification?.icon,
-      image: payload?.notification?.image,
-      data: {
-        url: notificationUrl(payload),
-        FCM_MSG: payload,
-      },
-    };
-    self.registration.showNotification(title, options);
-  });
-}
-
-self.addEventListener("notificationclick", (event) => {
-  const url = event.notification?.data?.url || event.notification?.data?.FCM_MSG?.data?.url;
-  event.notification?.close();
-  if (!url) return;
-  event.waitUntil(clients.openWindow(url));
-});
-`;
-  }
-
   static #normalizeArtifact(artifact: BaseBuildArtifact, artifactDir: string): BaseBuildArtifact {
     const normalizedArtifactDir = path.resolve(artifactDir);
     const pagesBundlePath = WebRouter.#resolveArtifactPath(artifact.pagesBundlePath, normalizedArtifactDir);
@@ -1184,18 +1089,6 @@ self.addEventListener("notificationclick", (event) => {
     };
   }
 
-  static #mergeClientManifest(...manifests: Array<ClientManifest | undefined>): ClientManifest {
-    return Object.assign({}, ...manifests.filter(Boolean));
-  }
-
-  static #mergeSsrManifest(...manifests: Array<SsrManifest | undefined>): SsrManifest {
-    const definedManifests = manifests.filter((manifest): manifest is SsrManifest => Boolean(manifest));
-    return {
-      moduleLoading: null,
-      moduleMap: Object.assign({}, ...definedManifests.map((manifest) => manifest.moduleMap)),
-    };
-  }
-
   static #normalizeSsrManifest(ssrManifest: SsrManifest, artifactDir: string): SsrManifest {
     return {
       ...ssrManifest,
@@ -1246,12 +1139,6 @@ self.addEventListener("notificationclick", (event) => {
     return path.resolve(artifactDir, "server", path.basename(artifactPath));
   }
 
-  static #resolveCsrDir(artifactDir: string) {
-    const localCsrDir = path.join(process.cwd(), "csr");
-    if (fs.existsSync(localCsrDir)) return localCsrDir;
-    return path.join(artifactDir, "csr");
-  }
-
   static #resolveCsrHtmlPath(csrOutputDir: string, pathname: string, artifact: BaseBuildArtifact): string | null {
     const basePath = getBasePathFromPathname(pathname, {
       basePaths: artifact.basePaths,
@@ -1272,20 +1159,12 @@ self.addEventListener("notificationclick", (event) => {
     if (!(await file.exists())) return new Response("Not Found", { status: 404 });
     const stat = fs.statSync(filePath);
     const lastModifiedMs = Math.floor(stat.mtimeMs / 1000) * 1000;
-    const etag = WebRouter.#weakEtag(stat.size, lastModifiedMs);
+    const etag = `W/"${stat.size.toString(16)}-${lastModifiedMs.toString(16)}"`;
     headers.set("ETag", etag);
     headers.set("Last-Modified", new Date(lastModifiedMs).toUTCString());
     if (WebRouter.#isNotModified(req, etag, lastModifiedMs)) return new Response(null, { status: 304, headers });
 
-    const sidecar = await resolveEncodedSidecar(req, filePath, options.contentType);
-    if (sidecar) {
-      headers.set("Content-Encoding", sidecar.encoding);
-      headers.set("Content-Length", String(sidecar.bytes.byteLength));
-      headers.set("Vary", "Accept-Encoding");
-      return new Response(sidecar.bytes, { headers });
-    }
-
-    return new Response(file.stream(), { headers });
+    return await encodedFileResponse(req, filePath, options.contentType, headers);
   }
 
   static #deepLinkAssociationResponse(
@@ -1293,30 +1172,36 @@ self.addEventListener("notificationclick", (event) => {
     artifact: BaseBuildArtifact,
     { cacheControl }: { cacheControl: string },
   ) {
-    if (pathname !== APPLE_APP_SITE_ASSOCIATION_PATH && pathname !== ANDROID_ASSET_LINKS_PATH) return null;
     const associations = artifact.deepLinkAssociations ?? [];
     if (pathname === APPLE_APP_SITE_ASSOCIATION_PATH) {
       const details = associations
-        .filter((association) => association.domains.length > 0 && association.iosTeamId)
+        .filter((association) => association.domains.length > 0 && association.iosTeamId && association.iosAppId)
         .map((association) => ({
-          appIDs: [`${association.iosTeamId}.${association.appId}`],
+          appIDs: [`${association.iosTeamId}.${association.iosAppId}`],
           components: [{ "/": "/*" }],
         }));
       if (details.length === 0) return null;
       return WebRouter.#jsonResponse({ applinks: { apps: [], details } }, cacheControl);
     }
+    
+    const packageSuffixes = process.env.AKAN_PUBLIC_ENV === "main" ? [""] : ["", ".debug"];
     const assetLinks = associations
       .filter(
-        (association) => association.domains.length > 0 && (association.androidSha256CertFingerprints?.length ?? 0) > 0,
+        (association) =>
+          association.domains.length > 0 &&
+          !!association.androidAppId &&
+          (association.androidSha256CertFingerprints?.length ?? 0) > 0,
       )
-      .map((association) => ({
-        relation: ["delegate_permission/common.handle_all_urls"],
-        target: {
-          namespace: "android_app",
-          package_name: association.appId,
-          sha256_cert_fingerprints: association.androidSha256CertFingerprints,
-        },
-      }));
+      .flatMap((association) =>
+        packageSuffixes.map((suffix) => ({
+          relation: ["delegate_permission/common.handle_all_urls"],
+          target: {
+            namespace: "android_app",
+            package_name: `${association.androidAppId}${suffix}`,
+            sha256_cert_fingerprints: association.androidSha256CertFingerprints,
+          },
+        })),
+      );
     if (assetLinks.length === 0) return null;
     return WebRouter.#jsonResponse(assetLinks, cacheControl);
   }
@@ -1330,29 +1215,6 @@ self.addEventListener("notificationclick", (event) => {
     });
   }
 
-  static #bytesResponse(
-    _req: Request,
-    bytes: Uint8Array,
-    options: { contentType: string; cacheControl?: string },
-  ): Response {
-    const headers = WebRouter.#baseAssetHeaders(options);
-    return new Response(WebRouter.#toArrayBuffer(bytes), { headers });
-  }
-
-  static #toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
-    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
-  }
-
-  /**
-   * Headers every response carries, whatever it is.
-   *
-   * `nosniff` because `Bun.file().type` falls back to `application/octet-stream` for an extension it does not
-   * know, and a sniffing browser then guesses again — on a `public/` tree the app serves from its own origin,
-   * that guess is script execution. `Referrer-Policy` because route paths carry ids.
-   *
-   * `X-Frame-Options` is on the HTML only: framing an image or a stylesheet means nothing, and the header is
-   * what stops a page authenticated by a `SameSite=None` cookie from being clickjacked inside somebody else's.
-   */
   static #applySecurityHeaders(headers: Headers, { html = false } = {}): Headers {
     headers.set("X-Content-Type-Options", "nosniff");
     headers.set("Referrer-Policy", "strict-origin-when-cross-origin");
@@ -1366,10 +1228,6 @@ self.addEventListener("notificationclick", (event) => {
     return WebRouter.#applySecurityHeaders(headers);
   }
 
-  static #weakEtag(size: number, mtimeMs: number): string {
-    return `W/"${size.toString(16)}-${mtimeMs.toString(16)}"`;
-  }
-
   static #isNotModified(req: Request, etag: string, lastModifiedMs: number): boolean {
     if (req.method !== "GET" && req.method !== "HEAD") return false;
     const ifNoneMatch = req.headers.get("if-none-match");