akanjs 3.0.0-beta.25 → 3.0.0-beta.26

package/common/hmrPhase.ts

@@ -5,6 +5,7 @@ declare global {
   var __AKAN_HMR_PHASE__: AkanHmrPhase | undefined;
 }
 
+/** @deprecated Always `null`: the dev client that set the phase applies modules through its registry now. */
 export function getAkanHmrPhase(): AkanHmrPhase {
   if (typeof globalThis === "undefined") return null;
   const phase = globalThis.__AKAN_HMR_PHASE__;
@@ -12,6 +13,7 @@ export function getAkanHmrPhase(): AkanHmrPhase {
   return null;
 }
 
+/** @deprecated Always `false`, for the reason `getAkanHmrPhase` is always `null`. */
 export function isAkanHmrApplying(): boolean {
   return getAkanHmrPhase() !== null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-beta.25",
+  "version": "3.0.0-beta.26",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/artifact/devBuildRecovery.ts

@@ -0,0 +1,12 @@
+import type { DevBuildStatus } from "./ipcTypes";
+
+export class DevBuildRecovery {
+
+  static recovers(previous: DevBuildStatus | undefined, status: DevBuildStatus): boolean {
+    if (!previous || previous.ok || !status.ok) return false;
+    if (status.phase === "route" && status.scope !== undefined && previous.scope !== undefined)
+      return status.scope === previous.scope && status.generation >= previous.generation;
+    if (status.generation !== previous.generation) return status.generation > previous.generation;
+    return status.phase === "backend";
+  }
+}

package/server/artifact/index.ts

@@ -1,4 +1,5 @@
 export * from "./builderRpc";
+export * from "./devBuildRecovery";
 export * from "./ipcTypes";
 export * from "./routeClientCache";
 export * from "./routeSeedIndexStore";

package/server/artifact/ipcTypes.ts

@@ -52,6 +52,8 @@ export interface DevBuildStatus {
   ok: boolean;
   files: string[];
   message?: string;
+  /** The route a route build's status speaks for. */
+  scope?: string;
 }
 
 export type BuilderReq = {

package/server/di/diLifecycle.ts

@@ -118,7 +118,7 @@ export class DiLifecycle {
   constructor({ env, modules = [], disableModules = [], disableLibs = [] }: DiLifecycleProps, ...libs: AkanLib[]) {
     this.#env = env;
     const databaseMode = DiLifecycle.#databaseMode();
-    this.logger.info(`Database mode: ${DatabaseModes.describe(databaseMode)}`);
+    this.logger.debug(`Database mode: ${DatabaseModes.describe(databaseMode)}`);
     
     this.#predefinedAdaptor = { ...getPredefinedAdaptor(databaseMode) };
     this.#libs = libs;

package/server/hmr/clientScript.ts

@@ -52,12 +52,12 @@ export const HMR_CLIENT_SCRIPT = `(function(){
   function connect(){
     try { socket = new WebSocket(url); }
     catch(e){ console.error("[akan-hmr] ws init failed", e); schedule(); return; }
-    socket.addEventListener("open", function(){ attempts = 0; });
     socket.addEventListener("message", function(ev){
       var msg;
       try { msg = JSON.parse(ev.data); } catch (e){ return; }
       if (!msg || typeof msg.type !== "string") return;
       if (msg.type === "hello") {
+        attempts = 0;
         var dropped = Array.isArray(msg.failingPhases) && dropBuildErrorsExcept(msg.failingPhases);
         if (dropped && systemPage) {
           reloadForUpdate("the build that failed to render this page recovered");
@@ -387,7 +387,7 @@ export const HMR_CLIENT_SCRIPT = `(function(){
     var current = buildErrorStates[phase];
     if (!current) return;
     var generation = typeof msg.generation === "number" ? msg.generation : 0;
-    var sameGeneration = phase === "backend" || phase === "scan" || phase === "route";
+    var sameGeneration = phase === "backend" || phase === "route";
     var recovered = sameGeneration ? generation >= current.generation : generation > current.generation;
     if (!recovered) return;
     delete buildErrorStates[phase];
@@ -405,6 +405,12 @@ export const HMR_CLIENT_SCRIPT = `(function(){
     return dropped;
   }
 
+  function clearRenderError(){
+    if (!buildErrorStates.build) return;
+    delete buildErrorStates.build;
+    showBuildRecovered({});
+  }
+
   function showBuildRecovered(msg){
     if (hasBuildErrors()) {
       renderBuildErrorOverlay();
@@ -462,9 +468,12 @@ export const HMR_CLIENT_SCRIPT = `(function(){
     return prefix ? prefix + "\\n" + msg.message : msg.message;
   }
 
+  var rscRefreshSeq = 0;
+  var rscRefreshedSeq = 0;
   function refreshRsc(msg){
     var receivedAt = Date.now();
-    var refresh = function(){ doRefreshRsc(msg, receivedAt); };
+    var seq = ++rscRefreshSeq;
+    var refresh = function(){ if (seq === rscRefreshSeq) doRefreshRsc(msg, receivedAt, seq); };
     var settle = function(){
       return self.__akan && typeof self.__akan.whenSettled === "function" ? self.__akan.whenSettled() : null;
     };
@@ -477,7 +486,7 @@ export const HMR_CLIENT_SCRIPT = `(function(){
     settled.then(refresh, refresh);
   }
 
-  function doRefreshRsc(msg, receivedAt){
+  function doRefreshRsc(msg, receivedAt, seq){
     var started = performance.now();
     var overlayToken = beginHmrOverlay("Refreshing page...");
     try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}
@@ -488,9 +497,13 @@ export const HMR_CLIENT_SCRIPT = `(function(){
       return;
     }
     Promise.resolve(self.__AKAN_RSC_REFRESH__({ buildId: msg.buildId })).then(function(){
-      lastBuildId = msg.buildId;
+      if (!(seq < rscRefreshedSeq)) {
+        rscRefreshedSeq = seq;
+        lastBuildId = msg.buildId;
+      }
       recordTrace("rsc-refresh", msg, receivedAt, Date.now());
       endHmrOverlay(overlayToken);
+      clearRenderError();
       console.debug && console.debug("[akan-hmr] RSC refreshed", {
         buildId: msg.buildId,
         generation: msg.generation,

package/server/hmr/csrDevRuntime.ts

@@ -207,21 +207,25 @@ export const installCsrDevRuntime = (host: CsrDevRuntimeHost): void => {
       const entry = script?.dataset.akanCsrEntry;
       if (!entry) throw new Error("[akan-csr] the app script carries no data-akan-csr-entry");
       this.#generation = generation;
-      this.#refresh = this.#load(refresh).exports as RefreshRuntime;
-      
-      this.#refresh.injectIntoGlobalHook(host);
-      this.#run(entry);
+      this.#run(entry, () => {
+        const runtime = this.#load(refresh).exports as RefreshRuntime;
+        
+        runtime.injectIntoGlobalHook(host);
+        this.#refresh = runtime;
+      });
     }
 
     startLibrary({ generation, refresh, bootstrap, vendorFile, epoch }: LibraryStart) {
       this.#library = { vendorFile, epoch };
       this.#generation = generation;
-      this.#refresh = this.#load(refresh).exports as RefreshRuntime;
-      this.#run(bootstrap);
+      this.#run(bootstrap, () => {
+        this.#refresh = this.#load(refresh).exports as RefreshRuntime;
+      });
     }
 
-    #run(entry: string) {
+    #run(entry: string, loadRefresh: () => void) {
       try {
+        loadRefresh();
         this.#load(entry);
       } catch (error) {
         this.#startFailed = true;

package/server/hmr/csrDevShell.ts

@@ -1,3 +1,4 @@
+import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveStaticPath } from "../staticPath";
 import {
@@ -38,6 +39,8 @@ export class CsrDevShell {
   readonly #appWaitMs: number;
   readonly #appPollMs: number;
   readonly #bootWaitMs: number;
+  
+  readonly #sourceMaps = new Map<string, { stamp: string; body: string }>();
 
   constructor(
     artifactDir: string,
@@ -109,7 +112,8 @@ ${stylesheet}  </head>
     const deadline = Date.now() + this.#appWaitMs;
     for (;;) {
       const manifest = await this.readManifest();
-      if (!manifest || appGenerationOf(manifest) >= generation || Date.now() >= deadline || signal?.aborted) return;
+      if (!manifest || manifest.generation < generation || appGenerationOf(manifest) >= generation) return;
+      if (Date.now() >= deadline || signal?.aborted) return;
       await Bun.sleep(this.#appPollMs);
     }
   }
@@ -135,9 +139,26 @@ ${stylesheet}  </head>
 
   async #serveSourceMap(name: string): Promise<Response> {
     const generatedFile = name.slice(0, -".map".length);
-    const layoutFile = Bun.file(path.join(this.#dir, `${generatedFile}.layout.json`));
-    if (!(await layoutFile.exists())) return new Response("Not Found", { status: 404 });
-    const layout = (await layoutFile.json()) as CsrDevLayout;
+    const layoutPath = path.join(this.#dir, `${generatedFile}.layout.json`);
+    const stat = await fs.stat(layoutPath).catch(() => null);
+    if (!stat) return new Response("Not Found", { status: 404 });
+    const stamp = `${stat.ino}:${stat.size}:${stat.mtimeMs}`;
+    const cached = this.#sourceMaps.get(generatedFile);
+    const body = cached?.stamp === stamp ? cached.body : await this.#mergeSourceMap(generatedFile, layoutPath);
+    if (!body) return new Response("Not Found", { status: 404 });
+    this.#sourceMaps.delete(generatedFile);
+    this.#sourceMaps.set(generatedFile, { stamp, body });
+    for (const oldest of this.#sourceMaps.keys()) {
+      if (this.#sourceMaps.size <= 4) break;
+      this.#sourceMaps.delete(oldest);
+    }
+    return new Response(body, { headers: CsrDevShell.#headers("application/json", "no-store") });
+  }
+
+  async #mergeSourceMap(generatedFile: string, layoutPath: string): Promise<string | null> {
+    const layoutText = await fs.readFile(layoutPath, "utf8").catch(() => null);
+    if (!layoutText) return null;
+    const layout = JSON.parse(layoutText) as CsrDevLayout;
     const sections = await Promise.all(
       layout.modules.map(async ([id, line]) => {
         const file = Bun.file(path.join(this.#dir, csrDevModuleFile(id, ".js.map")));
@@ -149,7 +170,7 @@ ${stylesheet}  </head>
       sections.filter((section) => section !== null),
       layout.lineCount,
     );
-    return new Response(JSON.stringify(map), { headers: CsrDevShell.#headers("application/json", "no-store") });
+    return JSON.stringify(map);
   }
 
   static #js(body: string | Blob, cacheControl: string): Response {

package/server/hmr/devArtifactPruner.ts

@@ -0,0 +1,77 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Logger } from "akanjs/common";
+import type { CssAsset } from "../types";
+
+export class DevArtifactPruner {
+  
+  static readonly #defaultGraceMs = 60_000;
+  static readonly #pagesFile = /^pages-[^/\\]+\.js$/;
+  readonly #logger = new Logger("DevArtifactPruner");
+  readonly #artifactDir: string;
+  readonly #graceMs: number;
+  #pruning: Promise<void> = Promise.resolve();
+
+  constructor(artifactDir: string, { graceMs = DevArtifactPruner.#defaultGraceMs }: { graceMs?: number } = {}) {
+    this.#artifactDir = path.resolve(artifactDir);
+    this.#graceMs = graceMs;
+  }
+
+  prunePages(runningPath: string): Promise<void> {
+    return this.#queue(async () => {
+      const running = await fs.stat(runningPath).catch(() => null);
+      if (!running) return;
+      const keep = new Set([path.resolve(runningPath), ...(await this.#baseArtifact()).pages]);
+      const serverDir = path.join(this.#artifactDir, "server");
+      const before = Math.min(running.mtimeMs, Date.now() - this.#graceMs);
+      await this.#removeOlder(serverDir, (name) => DevArtifactPruner.#pagesFile.test(name), keep, before);
+    });
+  }
+
+  pruneStyles(cssAssets: Record<string, CssAsset>): Promise<void> {
+    return this.#queue(async () => {
+      const current = Object.values(cssAssets).map((asset) => path.join(this.#artifactDir, asset.cssRelPath));
+      const keep = new Set([...current, ...(await this.#baseArtifact()).styles]);
+      const stylesDir = path.join(this.#artifactDir, "styles");
+      await this.#removeOlder(stylesDir, (name) => name.endsWith(".css"), keep, Date.now() - this.#graceMs);
+    });
+  }
+
+  #queue(prune: () => Promise<void>): Promise<void> {
+    this.#pruning = this.#pruning.then(prune).catch((error: unknown) => {
+      this.#logger.verbose(`[dev-artifact] prune skipped: ${String(error)}`);
+    });
+    return this.#pruning;
+  }
+
+  async #removeOlder(dir: string, matches: (name: string) => boolean, keep: Set<string>, before: number) {
+    const names = await fs.readdir(dir).catch(() => [] as string[]);
+    let removed = 0;
+    for (const name of names) {
+      const file = path.join(dir, name);
+      if (!matches(name) || keep.has(file)) continue;
+      const stat = await fs.stat(file).catch(() => null);
+      if (!stat || stat.mtimeMs >= before) continue;
+      
+      if (
+        await fs.rm(file, { force: true }).then(
+          () => true,
+          () => false,
+        )
+      )
+        removed += 1;
+    }
+    if (removed > 0) this.#logger.verbose(`[dev-artifact] removed ${removed} superseded file(s) from ${dir}`);
+  }
+
+  async #baseArtifact(): Promise<{ pages: string[]; styles: string[] }> {
+    const text = await fs.readFile(path.join(this.#artifactDir, "base-artifact.json"), "utf8").catch(() => null);
+    const artifact = text
+      ? (JSON.parse(text) as { pagesBundlePath?: string; cssAssets?: Record<string, CssAsset> })
+      : null;
+    return {
+      pages: artifact?.pagesBundlePath ? [path.resolve(this.#artifactDir, artifact.pagesBundlePath)] : [],
+      styles: Object.values(artifact?.cssAssets ?? {}).map((asset) => path.join(this.#artifactDir, asset.cssRelPath)),
+    };
+  }
+}

package/server/hmr/devHmrController.ts

@@ -1,9 +1,11 @@
 import fs from "node:fs";
 import path from "node:path";
 import { Logger } from "akanjs/common";
+import { CrossSiteGuard } from "../../signal/CrossSiteGuard";
 import {
   BuilderRpc,
   type ClientManifest,
+  DevBuildRecovery,
   type DevBuildStatus,
   type HmrTrace,
   RouteClientCache,
@@ -13,6 +15,7 @@ import {
 import type { RscReloadFailure, RscWorker } from "../rscWorkerHost";
 import type { RenderState } from "../types";
 import { CSR_DEV_DIRNAME, CSR_DEV_MANIFEST_FILE, type CsrDevManifest, SSR_DEV_DIRNAME } from "./csrDevManifest";
+import { DevArtifactPruner } from "./devArtifactPruner";
 import { isAkanRuntimeMetadataFile } from "./runtimeMetadataFile";
 import { type SsrUpdateMessage, SsrUpdateQueue } from "./ssrUpdateQueue";
 import { type ChangeKind, type HmrMessage, type HmrWsData, HmrWsHub } from "./wsHub";
@@ -49,11 +52,7 @@ export function devBuildStatusToHmrMessage(
       files: status.files.length,
     };
   }
-  if (!previous || previous.ok) return null;
-  
-  const sameGeneration = status.phase === "backend" || status.phase === "scan" || status.phase === "route";
-  const recovered = sameGeneration ? status.generation >= previous.generation : status.generation > previous.generation;
-  if (!recovered) return null;
+  if (!DevBuildRecovery.recovers(previous, status)) return null;
   return {
     type: "build-status",
     status: "ok",
@@ -85,6 +84,8 @@ export class DevHmrController {
   readonly #ssrUpdates = new SsrUpdateQueue((message) => this.#sendSsrUpdate(message));
   readonly #builderRpc: BuilderRpc;
   readonly routeCache: RouteClientCache;
+  #recheckingRoute = false;
+  #recheckAgain: DevBuildStatus | null = null;
   readonly #recentClientEntries = new Set<string>();
   /** File to the newest save that invalidated its routes already: that save's pages build must not drop them again. */
   readonly #earlyInvalidated = new Map<string, number>();
@@ -97,10 +98,12 @@ export class DevHmrController {
   readonly #buildStatusByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>();
   #graphSeeds: string[];
   #runningBundlePath: string | null;
+  readonly #pruner: DevArtifactPruner;
 
   constructor({ artifactDir, renderState, rsc, seedIndex, upgradeHmrWs, pagesBundlePath }: DevHmrControllerOptions) {
     this.#artifactDir = artifactDir;
     this.#runningBundlePath = pagesBundlePath ? path.resolve(pagesBundlePath) : null;
+    this.#pruner = new DevArtifactPruner(artifactDir);
     this.#renderState = renderState;
     this.#rsc = rsc;
     this.#seedIndex = seedIndex;
@@ -155,28 +158,17 @@ export class DevHmrController {
   }
 
   handleWs(req: Request): Response | undefined {
+
+    try {
+      CrossSiteGuard.assertOrigin(req, new URL(req.url), "hmr");
+    } catch {
+      return new Response("Forbidden", { status: 403 });
+    }
     const client = new URL(req.url).searchParams.get("client") === "csr" ? "csr" : "ssr";
     if (this.#upgradeHmrWs(req, { kind: "akan-hmr", openedAt: Date.now(), client })) return;
     return new Response("Failed to upgrade HMR WebSocket", { status: 500 });
   }
 
-  async ensureRoute(url: URL) {
-    const started = Date.now();
-    const matched =
-      RouteSeedIndexStore.match(url.pathname, this.#seedIndex.entries) ??
-      RouteSeedIndexStore.matchPrefix(url.pathname, this.#seedIndex.entries);
-    if (matched) await this.routeCache.ensure(matched.entry.routeId, matched.entry.seeds);
-    this.#logger.verbose(
-      `[route-cache] ensure pathname=${url.pathname} routeId=${matched?.entry.routeId ?? "(none)"} in ${Date.now() - started}ms`,
-    );
-    return this.routeCache.snapshot();
-  }
-
-  routeIdsForPath(pathname: string): string[] | undefined {
-    const matched = RouteSeedIndexStore.match(pathname, this.#seedIndex.entries);
-    return matched ? [matched.entry.routeId] : undefined;
-  }
-
   #sendSsrUpdate(message: SsrUpdateMessage): void {
     this.#renderState.ssrGeneration = message.generation;
     this.#hub.broadcast({ ...message, trace: DevHmrController.#broadcastTrace(message.trace) });
@@ -235,6 +227,7 @@ export class DevHmrController {
         this.#renderState.cssBytesByUrl = cssBytesByUrl;
         this.#rsc.updateCssAssets(this.#renderState.cssAssets);
         this.#hub.broadcast({ type: "css-update", cssAssets: this.#renderState.cssAssets });
+        void this.#pruner.pruneStyles(this.#renderState.cssAssets);
         this.#logger.verbose(
           `css-update assets=${Object.keys(this.#renderState.cssAssets).length} generation=${css.generation ?? "(unknown)"} files=${css.changedFiles?.length ?? 0} in ${Date.now() - started}ms (ipc)`,
         );
@@ -266,6 +259,7 @@ export class DevHmrController {
         const manifest = this.routeCache.snapshot();
 
         const running = bundlePath ? path.resolve(bundlePath) : null;
+        let tabBuildId = buildId;
         if (serverTouched === false && !clearAll && running === this.#runningBundlePath) {
           this.#logger.verbose(
             `[SSR] pages bundle unchanged for the server; buildId ${this.#renderState.buildId} kept`,
@@ -275,25 +269,29 @@ export class DevHmrController {
           this.#renderState.buildId = buildId;
           const reloadStarted = Date.now();
           try {
-            this.#runningBundlePath = path.resolve(
-              await this.#rsc.reload({
-                clientManifest: manifest.clientManifest,
-                cssAssets: this.#renderState.cssAssets,
-                buildId,
-                pagesBundlePath: bundlePath,
-              }),
-            );
+            const adopted = await this.#rsc.reload({
+              clientManifest: manifest.clientManifest,
+              cssAssets: this.#renderState.cssAssets,
+              buildId,
+              pagesBundlePath: bundlePath,
+            });
+            this.#adoptBundle(adopted.pagesBundlePath);
+            
+            tabBuildId = adopted.buildId;
           } catch (error) {
             const failure = DevHmrController.#reloadFailure(error);
             
             if (failure) {
               this.#renderState.buildId = failure.adopted.buildId;
-              this.#runningBundlePath = path.resolve(failure.adopted.pagesBundlePath);
+              this.#adoptBundle(failure.adopted.pagesBundlePath);
             } else if (this.#renderState.buildId === buildId) this.#renderState.buildId = previousBuildId;
             
-            if (failure?.superseded) this.#ssrUpdates.release(generation);
-            else this.#failPagesReload(generation, files, error);
-            return;
+            if (failure?.adopted.buildId !== buildId) {
+
+              if (failure && failure.failed.buildId !== buildId) this.#ssrUpdates.release(generation);
+              else this.#failPagesReload(generation, files, error);
+              return;
+            }
           }
           this.#logger.verbose(`[SSR] rsc reload buildId=${buildId} in ${Date.now() - reloadStarted}ms`);
         }
@@ -301,7 +299,7 @@ export class DevHmrController {
         const broadcastTrace = DevHmrController.#broadcastTrace(trace);
         if (shouldReload) this.#ssrUpdates.clear(generation);
         const released = shouldReload ? { released: 0, reload: false } : this.#ssrUpdates.release(generation);
-        if (shouldReload) this.#hub.broadcast({ type: "reload", buildId });
+        if (shouldReload) this.#hub.broadcast({ type: "reload", buildId: tabBuildId });
         else if (released.reload)
           this.#logger.verbose(`[hmr] generation=${generation} released a registry reload; no RSC refresh needed`);
         else if (serverTouched === false)
@@ -311,7 +309,7 @@ export class DevHmrController {
         else
           this.#hub.broadcast({
             type: "rsc-refresh",
-            buildId,
+            buildId: tabBuildId,
             generation,
             changedFiles,
             routeIds,
@@ -324,6 +322,13 @@ export class DevHmrController {
     });
   }
 
+  #adoptBundle(bundlePath: string): void {
+    const running = path.resolve(bundlePath);
+    if (running === this.#runningBundlePath) return;
+    this.#runningBundlePath = running;
+    void this.#pruner.prunePages(running);
+  }
+
   static #reloadFailure(error: unknown): RscReloadFailure | null {
     return error instanceof Error && "adopted" in error ? (error as RscReloadFailure) : null;
   }
@@ -351,6 +356,7 @@ export class DevHmrController {
   }
 
   #recordBuildStatus(status: DevBuildStatus): void {
+    this.#recheckFailedRoute(status);
     const previous = this.#buildStatusByPhase.get(status.phase);
     const message = devBuildStatusToHmrMessage(status, previous);
 
@@ -363,6 +369,26 @@ export class DevHmrController {
     );
   }
 
+  #recheckFailedRoute(status: DevBuildStatus, { again = false }: { again?: boolean } = {}): void {
+    if (!status.ok || (status.phase !== "pages" && status.phase !== "ssr")) return;
+    if (this.#recheckingRoute) {
+      this.#recheckAgain = status;
+      return;
+    }
+    const failed = this.#buildStatusByPhase.get("route");
+    if (!failed || failed.ok || !failed.scope || (!again && failed.generation >= status.generation)) return;
+    this.#recheckingRoute = true;
+    void this.routeCache
+      .ensure(failed.scope, failed.files)
+      .catch(() => undefined)
+      .finally(() => {
+        this.#recheckingRoute = false;
+        const next = this.#recheckAgain;
+        this.#recheckAgain = null;
+        if (next) this.#recheckFailedRoute(next, { again: true });
+      });
+  }
+
   #createRouteCache() {
     return new RouteClientCache({
       buildRoute: async (routeId, { seeds, knownEntries, generation }) => {
@@ -387,17 +413,16 @@ export class DevHmrController {
         if (delta.newEntries.length === 0 && removedEntries.size === 0) return;
         this.#rememberClientDeps(routeId, delta.clientDeps, delta.clientDepsByEntry);
         try {
-          this.#runningBundlePath = path.resolve(
-            await this.#rsc.reload({
-              clientManifest: nextMerged.clientManifest,
-              cssAssets: this.#renderState.cssAssets,
-              buildId: this.#renderState.buildId,
-            }),
-          );
+          const adopted = await this.#rsc.reload({
+            clientManifest: nextMerged.clientManifest,
+            cssAssets: this.#renderState.cssAssets,
+            buildId: this.#renderState.buildId,
+          });
+          this.#adoptBundle(adopted.pagesBundlePath);
         } catch (error) {
 
           const failure = DevHmrController.#reloadFailure(error);
-          if (failure) this.#runningBundlePath = path.resolve(failure.adopted.pagesBundlePath);
+          if (failure) this.#adoptBundle(failure.adopted.pagesBundlePath);
           this.#logger.warn(`[SSR] route ${routeId} merged, but the worker did not reload: ${String(error)}`);
         }
         this.#logger.verbose(

package/server/hmr/ssrDevShim.ts

@@ -52,9 +52,15 @@ export class SsrDevShim {
     var hello = self.__AKAN_SSR_HELLO_GENERATION__;
     if (typeof hello === "number") self.__akan.catchUp(hello, c.prefix);
   }
+  function runtime(attempt) {
+    return script(c.runtime).catch(function (error) {
+      if (attempt >= 3) throw error;
+      return wait(500).then(state).then(function () { return runtime(attempt + 1); });
+    });
+  }
   function boot() {
     if (!booting)
-      booting = self.__AKAN_SSR_BOOT__ = script(c.runtime).then(function () {
+      booting = self.__AKAN_SSR_BOOT__ = runtime(0).then(function () {
         var early = self.__AKAN_SSR_EARLY_UPDATES__ || [];
         self.__AKAN_SSR_EARLY_UPDATES__ = null;
         for (var i = 0; i < early.length; i++) self.__akan.hot(early[i]);

package/server/rscWorker.tsx

@@ -387,7 +387,12 @@ export class RscRenderer {
       this.#resultCache.clear();
       this.#patchResultCache.clear();
       this.#logger.verbose(`reload complete buildId=${msg.buildId} in ${Date.now() - startedAt}ms`);
-      this.#send({ type: "reloaded", buildId: msg.buildId, reloadId: msg.reloadId });
+      this.#send({
+        type: "reloaded",
+        buildId: msg.buildId,
+        reloadId: msg.reloadId,
+        pagesBundlePath: nextPagesBundlePath,
+      });
     } catch (error) {
       this.#logger.error(
         `reload failed buildId=${msg.buildId}: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`,
@@ -399,6 +404,7 @@ export class RscRenderer {
         requestId: "__reload__",
         buildId: msg.buildId,
         reloadId: msg.reloadId,
+        running: { pagesBundlePath: this.#pagesBundlePath, buildId: this.#pagesBundleBuildId },
         message: error instanceof Error ? error.message : String(error),
       });
     }

package/server/rscWorkerHost.ts

@@ -297,7 +297,7 @@ export function createRscHostRenderStream(input: {
 type RscInMsg =
   | { type: "hello" }
   | { type: "ready" }
-  | { type: "reloaded"; buildId: number; reloadId?: number }
+  | { type: "reloaded"; buildId: number; reloadId?: number; pagesBundlePath?: string }
   | { type: "meta"; requestId: string; theme?: AkanTheme; status?: number; trace?: RscTraceMetadata }
   | { type: "cache-state"; requestId: string; state: RouteCacheRenderState }
   | { type: "chunk"; requestId: string; data: Uint8Array }
@@ -315,7 +315,14 @@ type RscInMsg =
   | { type: "log.records"; records: LogRecord[]; dropped?: number }
   | { type: "page-prompts.result"; requestId: string; result: PagePromptEntry[] }
   | { type: "page-prompt.result"; requestId: string; result: PagePromptRun }
-  | { type: "error"; requestId: string; message: string; buildId?: number; reloadId?: number };
+  | {
+      type: "error";
+      requestId: string;
+      message: string;
+      buildId?: number;
+      reloadId?: number;
+      running?: RscAdoptedBundle;
+    };
 
 export interface RscWorkerReloadInput {
   clientManifest: ClientManifest;
@@ -325,20 +332,22 @@ export interface RscWorkerReloadInput {
   pagesBundlePath?: string;
 }
 
-interface RscAdoptedBundle {
+export interface RscAdoptedBundle {
   pagesBundlePath: string;
   buildId: number;
 }
 
 interface RscReloadWaiter {
-  resolve: (pagesBundlePath: string) => void;
+  resolve: (adopted: RscAdoptedBundle) => void;
   reject: (err: RscReloadFailure) => void;
 }
 
 /** A reload the worker did not take: what it runs instead, and whether a later reload failed in this one's place. */
 export interface RscReloadFailure extends Error {
+  /** What the worker runs now. */
   adopted: RscAdoptedBundle;
-  superseded: boolean;
+  /** The latest state it was asked to take, which a later reload may have moved past the caller's own. */
+  failed: RscAdoptedBundle;
 }
 
 type WorkerStatus = "starting" | "ready" | "restarting" | "stopped";
@@ -371,6 +380,9 @@ export class RscWorker {
     buildId: number;
   } | null = null;
   #nextReloadId = 1;
+  #answeredReloadId = 0;
+  
+  #droppedWhileBooting = false;
   #reloadState = 0;
   #init: RscAdoptedBundle & { reloadState: number } = { pagesBundlePath: "", buildId: 0, reloadState: 0 };
   /** What the worker runs: a respawn falls back to it when the bundle a reload named failed to import. */
@@ -378,7 +390,7 @@ export class RscWorker {
 
   #status: WorkerStatus = "starting";
   #killed = false;
-  #queuedSends: Array<() => void> = [];
+  #queuedSends: { requestId: string; send: () => void }[] = [];
   #restartAttempts = 0;
   #restartCount = 0;
   #recycleCount = 0;
@@ -391,9 +403,11 @@ export class RscWorker {
   #hostPendingChunkOverflowCount = 0;
   #restartTimer: ReturnType<typeof setTimeout> | null = null;
   #recycleTimer: ReturnType<typeof setTimeout> | null = null;
-  #rollingRecycle: { oldProc: RscProcess; reason: string } | null = null;
+  #rollingRecycle: { oldProc: RscProcess; reason: string; reloadsSinceSpawn: number } | null = null;
+  #booting: RscProcess | null = null;
 
   readonly #failBeforeReady: boolean;
+  static readonly #queuedRespawns = 2;
 
   constructor(artifact: BaseBuildArtifact, { failBeforeReady = false }: { failBeforeReady?: boolean } = {}) {
     this.#failBeforeReady = failBeforeReady;
@@ -462,7 +476,7 @@ export class RscWorker {
       if (this.#status === "ready") send();
       else if (this.#status === "stopped")
         this.#settleCall(requestId, (call) => call.reject(new Error("rsc worker is stopped")));
-      else this.#queuedSends.push(send);
+      else this.#queuedSends.push({ requestId, send });
     });
   }
 
@@ -475,7 +489,10 @@ export class RscWorker {
   }
 
   invalidateRouteResultCache(invalidation?: string | RouteCacheInvalidation): void {
-    if (this.#status !== "ready") return;
+    if (this.#status !== "ready") {
+      this.#droppedWhileBooting = true;
+      return;
+    }
     try {
       this.#proc.send(createRscWorkerInvalidateCacheMessage(invalidation));
     } catch (error) {
@@ -499,6 +516,7 @@ export class RscWorker {
 
   setLogLevel(minSev: number | null) {
     this.#logLevel = minSev;
+    if (this.#status !== "ready") this.#droppedWhileBooting = true;
     this.#sendLogLevel();
   }
 
@@ -527,7 +545,7 @@ export class RscWorker {
     if (this.#killed || this.#status === "stopped" || this.#status === "starting" || this.#status === "restarting") {
       return false;
     }
-    if (this.#pending.size > 0 || this.#queuedSends.length > 0) {
+    if (this.#pending.size > 0 || this.#calls.size > 0 || this.#queuedSends.length > 0) {
       if (!this.#recycleTimer) {
         const graceMs = MemoryLimit.parsePositiveIntEnv("AKAN_RSC_WORKER_RECYCLE_GRACE_MS") ?? 5_000;
         this.#recycleTimer = setTimeout(() => {
@@ -542,14 +560,17 @@ export class RscWorker {
     this.#lastRecycleAtMono = performance.now();
     this.#logger.info(`[rsc] rolling recycle worker reason=${reason} oldPid=${this.#proc.pid}`);
     this.#status = "restarting";
-    this.#rollingRecycle = { oldProc: this.#proc, reason };
+    this.#rollingRecycle = { oldProc: this.#proc, reason, reloadsSinceSpawn: this.#reloadsSinceSpawn };
     this.#proc = this.#spawn();
     return true;
   }
 
   updateCssAssets(cssAssets: Record<string, CssAsset>): void {
     this.#cssAssets = cssAssets;
-    if (this.#status !== "ready") return;
+    if (this.#status !== "ready") {
+      this.#droppedWhileBooting = true;
+      return;
+    }
     try {
       this.#proc.send({ type: "updateCssAssets", cssAssets });
     } catch {
@@ -557,13 +578,14 @@ export class RscWorker {
   }
 
   /** Resolves with the pages bundle the worker runs once it has taken this reload, or a later one. */
-  reload(input: RscWorkerReloadInput): Promise<string> {
+  reload(input: RscWorkerReloadInput): Promise<RscAdoptedBundle> {
+    if (this.#killed) return Promise.reject(new Error("rsc worker is stopped"));
     this.#reloadState += 1;
     this.#clientManifest = input.clientManifest;
     this.#cssAssets = input.cssAssets ?? this.#cssAssets;
     this.#pagesBundleBuildId = input.buildId;
     if (input.pagesBundlePath) this.#pagesBundlePath = input.pagesBundlePath;
-    return new Promise<string>((resolve, reject) => {
+    return new Promise<RscAdoptedBundle>((resolve, reject) => {
 
       this.#pendingReload = {
         waiters: [...(this.#pendingReload?.waiters ?? []), { resolve, reject }],
@@ -580,7 +602,9 @@ export class RscWorker {
     const pending = this.#pendingReload;
     if (!pending) return;
 
-    if (this.#shouldRecycleForReloadAccumulation() && this.restartWhenIdle("pages-reload-accumulation")) return;
+    const answering = this.#answeredReloadId < this.#nextReloadId - 1;
+    if (!answering && this.#shouldRecycleForReloadAccumulation() && this.restartWhenIdle("pages-reload-accumulation"))
+      return;
     this.#reloadsSinceSpawn += 1;
     pending.reloadId = this.#nextReloadId++;
     try {
@@ -604,7 +628,7 @@ export class RscWorker {
     const pending = this.#pendingReload;
     if (!pending) return;
     this.#pendingReload = null;
-    for (const waiter of pending.waiters) waiter.resolve(adopted.pagesBundlePath);
+    for (const waiter of pending.waiters) waiter.resolve(adopted);
   }
 
   #rejectReload(message: string): void {
@@ -613,10 +637,9 @@ export class RscWorker {
     const pending = this.#pendingReload;
     if (!pending) return;
     this.#pendingReload = null;
-    for (const [idx, waiter] of pending.waiters.entries())
-      waiter.reject(
-        Object.assign(new Error(message), { adopted: this.#adopted, superseded: idx < pending.waiters.length - 1 }),
-      );
+    const failed = { pagesBundlePath: pending.pagesBundlePath, buildId: pending.buildId };
+    for (const waiter of pending.waiters)
+      waiter.reject(Object.assign(new Error(message), { adopted: this.#adopted, failed }));
   }
 
   #spawn(): RscProcess {
@@ -695,6 +718,7 @@ export class RscWorker {
     switch (message.type) {
       case "hello":
         
+        this.#booting = proc;
         this.#init = {
           pagesBundlePath: this.#pagesBundlePath,
           buildId: this.#pagesBundleBuildId,
@@ -711,7 +735,10 @@ export class RscWorker {
         });
         return;
       case "ready":
+        this.#booting = null;
         this.#status = "ready";
+        this.#answeredReloadId = this.#nextReloadId - 1;
+        this.#droppedWhileBooting = false;
         this.#restartAttempts = 0;
         this.#resolveReady();
         this.#finishRollingRecycle();
@@ -725,6 +752,15 @@ export class RscWorker {
         return;
       case "reloaded": {
         const pending = this.#pendingReload;
+
+        if (proc === this.#proc && message.pagesBundlePath) {
+          this.#adopted = { pagesBundlePath: message.pagesBundlePath, buildId: message.buildId };
+          this.#answeredReloadId = Math.max(this.#answeredReloadId, message.reloadId ?? 0);
+          if (!pending) {
+            this.#pagesBundlePath = message.pagesBundlePath;
+            this.#pagesBundleBuildId = message.buildId;
+          }
+        }
         if (pending && pending.reloadId !== null && pending.reloadId === message.reloadId)
           this.#resolveReload({ pagesBundlePath: pending.pagesBundlePath, buildId: pending.buildId });
         return;
@@ -770,23 +806,14 @@ export class RscWorker {
             this.#rejectReload(String(message.message));
             this.#rejectReady(new Error(String(message.message)));
           } else {
-            this.#logger.error(`[rsc] worker init error on restart: ${message.message}`);
-            
-            const covered = !this.#pendingReload || this.#pendingReload.reloadState <= this.#init.reloadState;
-            if (covered) this.#rejectReload(String(message.message));
-            const rolling = this.#rollingRecycle;
-            if (covered && rolling && proc === this.#proc) {
-
-              this.#rollingRecycle = null;
-              this.#proc = rolling.oldProc;
-              this.#status = "ready";
-              this.#flushQueuedSends();
-            }
+            this.#bootFailed(proc, String(message.message));
             proc.kill();
           }
           return;
         }
         if (message.requestId === "__reload__") {
+          if (proc === this.#proc) this.#answeredReloadId = Math.max(this.#answeredReloadId, message.reloadId ?? 0);
+          if (proc === this.#proc && message.running) this.#adopted = message.running;
           const pending = this.#pendingReload;
           if (pending && pending.reloadId !== null && pending.reloadId === message.reloadId)
             this.#rejectReload(String(message.message));
@@ -824,7 +851,7 @@ export class RscWorker {
     else if (this.#status === "stopped") {
       this.#resolvePending(requestId, (p) => p.onError("rsc worker is stopped"));
     } else {
-      this.#queuedSends.push(send);
+      this.#queuedSends.push({ requestId, send });
     }
   }
 
@@ -839,7 +866,7 @@ export class RscWorker {
   #flushQueuedSends(): void {
     const queue = this.#queuedSends;
     this.#queuedSends = [];
-    for (const send of queue) {
+    for (const { send } of queue) {
       try {
         send();
       } catch (err) {
@@ -848,6 +875,46 @@ export class RscWorker {
     }
   }
 
+  #failRequests(err: Error, which: (requestId: string) => boolean = () => true): void {
+    for (const [requestId, pending] of this.#pending) {
+      if (!which(requestId)) continue;
+      this.#pending.delete(requestId);
+      pending.onError(err.message);
+    }
+    for (const [requestId, call] of this.#calls) {
+      if (!which(requestId)) continue;
+      this.#calls.delete(requestId);
+      call.reject(err);
+    }
+    this.#queuedSends = this.#queuedSends.filter((entry) => !which(entry.requestId));
+  }
+
+  #bootFailed(proc: RscProcess, message: string): boolean {
+    this.#booting = null;
+    this.#logger.error(`[rsc] worker init error on restart: ${message}`);
+    const covered = !this.#pendingReload || this.#pendingReload.reloadState <= this.#init.reloadState;
+    if (covered) this.#rejectReload(message);
+    const rolling = proc === this.#proc ? this.#rollingRecycle : null;
+    this.#rollingRecycle = null;
+    if (!rolling || !RscWorker.#isAlive(rolling.oldProc)) return false;
+    this.#proc = rolling.oldProc;
+    this.#status = "ready";
+    this.#reloadsSinceSpawn = rolling.reloadsSinceSpawn;
+    if (this.#droppedWhileBooting) {
+      this.#droppedWhileBooting = false;
+      this.updateCssAssets(this.#cssAssets);
+      this.#sendLogLevel();
+      this.invalidateRouteResultCache();
+    }
+    this.#flushQueuedSends();
+    if (!covered) this.#sendPendingReload();
+    return true;
+  }
+
+  static #isAlive(proc: RscProcess): boolean {
+    return proc.exitCode === null && proc.signalCode === null && !proc.killed;
+  }
+
   #finishRollingRecycle(): void {
     const recycle = this.#rollingRecycle;
     if (!recycle) return;
@@ -861,22 +928,41 @@ export class RscWorker {
 
   #handleExit(proc: RscProcess, code: number | null): void {
     
+    if (proc === this.#rollingRecycle?.oldProc) {
+      this.#rollingRecycle = null;
+      return;
+    }
+    
     if (proc !== this.#proc) return;
 
+    if (proc === this.#booting && !this.#killed && proc.signalCode === null) {
+      const message = `rsc worker exited with code ${code} while loading the pages bundle`;
+      if (this.#readyResolved && this.#bootFailed(proc, message)) return;
+      if (!this.#readyResolved) {
+        this.#booting = null;
+        this.#status = "stopped";
+        this.#failRequests(new Error(message));
+        this.#rejectReload(message);
+        this.#rejectReady(new Error(message));
+        return;
+      }
+    }
+
     const err = new Error(`rsc worker exited with code ${code}`);
-    for (const [, p] of this.#pending) p.onError(err.message);
-    this.#pending.clear();
-    for (const [, call] of this.#calls) call.reject(err);
-    this.#calls.clear();
-    this.#queuedSends = [];
+
+    const queued = new Set(this.#queuedSends.map((entry) => entry.requestId));
+    const keepsQueue = this.#restartAttempts < RscWorker.#queuedRespawns;
+    this.#failRequests(err, (requestId) => !keepsQueue || !queued.has(requestId));
 
     if (this.#killed) {
       this.#status = "stopped";
+      this.#failRequests(err);
       this.#rejectReload(err.message);
       return;
     }
     if (this.#failBeforeReady && !this.#readyResolved) {
       this.#status = "stopped";
+      this.#failRequests(err);
       this.#rejectReload(err.message);
       this.#rejectReady(err);
       return;
@@ -913,7 +999,7 @@ export class RscWorker {
   }
 
   #maybeRecycleFromMetrics(metrics: AkanMetricsReport): void {
-    if (this.#pending.size > 0) return;
+    if (this.#pending.size > 0 || this.#calls.size > 0) return;
     const maxRssBytes = RscWorker.#getRscMaxRssBytes();
     if (maxRssBytes && metrics.rssBytes && metrics.rssBytes >= maxRssBytes) {
       this.restartWhenIdle(`rss>${Math.round(maxRssBytes / 1024 / 1024)}MiB`);

package/server/webRouter.ts

@@ -19,6 +19,7 @@ import {
   RouteClientCache,
   type RouteSeedIndex,
   RouteSeedIndexStore,
+  type RoutesManifest,
   RoutesManifestStore,
 } from "./artifact";
 import {
@@ -251,6 +252,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 {
@@ -300,7 +303,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)
@@ -320,6 +324,7 @@ export class WebRouter {
       cssBytesByUrl,
     };
     this.#seedIndex = seedIndex;
+    this.#prebuilt = prebuilt;
     if (this.#prodMode) {
       this.#builderRpc = null;
       this.#routeCache = new RouteClientCache({
@@ -350,16 +355,7 @@ export class WebRouter {
   }
 
   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.#artifact.pagesBundleBuildId,
-      });
-    }
+    if (this.#prebuilt) this.#routeCache.seed(this.#prebuilt);
 
     const clientServePrefix = `/_akan/client`;
     const clientOutputDir = `${this.#artifactDir}/client`;
@@ -398,7 +394,7 @@ 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
               ? {
@@ -549,7 +545,7 @@ export class WebRouter {
             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;
@@ -608,7 +604,7 @@ export class WebRouter {
           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 });
           }
@@ -649,7 +645,7 @@ export class WebRouter {
             },
           });
           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");
@@ -971,9 +967,9 @@ export class WebRouter {
     return this.renderState.cssAssets[basePath ?? ""]?.cssUrl ?? null;
   }
 
-  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 {
@@ -994,7 +990,7 @@ export class WebRouter {
       cssHref: this.#getStylesheetHref(req, pathname),
     });
     if (!html) return this.#csrUnavailableResponse(pathname);
-    return new Response(this.#withCsrHmr(html), { headers: WebRouter.#htmlResponseHeaders(200) });
+    return new Response(this.#withCsrHmr(html), { headers: this.#htmlResponseHeaders(200) });
   }
   async #resolveCsrHtml(csrOutputDir: string, pathname: string): Promise<string | null> {
     const resolved = WebRouter.#resolveCsrHtmlPath(csrOutputDir, pathname, this.#artifact);
@@ -1044,7 +1040,16 @@ export class WebRouter {
     const cssBytesByUrl = await WebRouter.#loadCssBytesByUrl(artifact, artifactDir);
     const prodMode = process.env.NODE_ENV === "production" && process.env.AKAN_COMMAND_TYPE !== "start";
 
-    const rsc = new RscWorker(artifact, { failBeforeReady: prodMode });
+    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)}`);
@@ -1059,6 +1064,7 @@ export class WebRouter {
       rsc,
       seedIndex,
       upgradeHmrWs,
+      prebuilt,
     });
   }
 

package/types/common/hmrPhase.d.ts

@@ -2,5 +2,7 @@ export type AkanHmrPhase = "refresh-import" | "react-refresh" | null;
 declare global {
     var __AKAN_HMR_PHASE__: AkanHmrPhase | undefined;
 }
+/** @deprecated Always `null`: the dev client that set the phase applies modules through its registry now. */
 export declare function getAkanHmrPhase(): AkanHmrPhase;
+/** @deprecated Always `false`, for the reason `getAkanHmrPhase` is always `null`. */
 export declare function isAkanHmrApplying(): boolean;

package/types/server/artifact/devBuildRecovery.d.ts

@@ -0,0 +1,4 @@
+import type { DevBuildStatus } from "./ipcTypes.d.ts";
+export declare class DevBuildRecovery {
+    static recovers(previous: DevBuildStatus | undefined, status: DevBuildStatus): boolean;
+}

package/types/server/artifact/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./builderRpc.d.ts";
+export * from "./devBuildRecovery.d.ts";
 export * from "./ipcTypes.d.ts";
 export * from "./routeClientCache.d.ts";
 export * from "./routeSeedIndexStore.d.ts";

package/types/server/artifact/ipcTypes.d.ts

@@ -50,6 +50,8 @@ export interface DevBuildStatus {
     ok: boolean;
     files: string[];
     message?: string;
+    /** The route a route build's status speaks for. */
+    scope?: string;
 }
 export type BuilderReq = {
     type: "build-route";

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

@@ -0,0 +1,9 @@
+import type { CssAsset } from "../types.d.ts";
+export declare class DevArtifactPruner {
+    #private;
+    constructor(artifactDir: string, { graceMs }?: {
+        graceMs?: number;
+    });
+    prunePages(runningPath: string): Promise<void>;
+    pruneStyles(cssAssets: Record<string, CssAsset>): Promise<void>;
+}

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

@@ -30,6 +30,4 @@ export declare class DevHmrController {
     get builderRpc(): BuilderRpc;
     dispose(): void;
     handleWs(req: Request): Response | undefined;
-    ensureRoute(url: URL): Promise<import("..").MergedManifest>;
-    routeIdsForPath(pathname: string): string[] | undefined;
 }

package/types/server/rscWorkerHost.d.ts

@@ -67,14 +67,16 @@ export interface RscWorkerReloadInput {
     /** Undefined keeps the latest bundle a reload named (e.g. a client-manifest-only reload after a lazy route build). */
     pagesBundlePath?: string;
 }
-interface RscAdoptedBundle {
+export interface RscAdoptedBundle {
     pagesBundlePath: string;
     buildId: number;
 }
 /** A reload the worker did not take: what it runs instead, and whether a later reload failed in this one's place. */
 export interface RscReloadFailure extends Error {
+    /** What the worker runs now. */
     adopted: RscAdoptedBundle;
-    superseded: boolean;
+    /** The latest state it was asked to take, which a later reload may have moved past the caller's own. */
+    failed: RscAdoptedBundle;
 }
 export declare class RscWorker {
     #private;
@@ -96,6 +98,5 @@ export declare class RscWorker {
     restartWhenIdle(reason: string): boolean;
     updateCssAssets(cssAssets: Record<string, CssAsset>): void;
     /** Resolves with the pages bundle the worker runs once it has taken this reload, or a later one. */
-    reload(input: RscWorkerReloadInput): Promise<string>;
+    reload(input: RscWorkerReloadInput): Promise<RscAdoptedBundle>;
 }
-export {};

package/types/server/webRouter.d.ts

@@ -3,7 +3,7 @@ import { type AkanI18nConfig, type LogRecord } from "akanjs/common";
 import { type AkanRequestStore } from "akanjs/fetch";
 import type { AkanMetricsReport } from "akanjs/service";
 import type { PagePromptSource } from "../signal/mcp/pagePrompt.d.ts";
-import { type BuilderRpc, type RouteSeedIndex } from "./artifact.d.ts";
+import { type BuilderRpc, type RouteSeedIndex, type RoutesManifest } from "./artifact.d.ts";
 import { type RouteCacheInvalidation, type RouteCacheRenderState } from "./cachePolicy.d.ts";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub.d.ts";
 import { type RscRedirectMethod, type RscRedirectStatus, type RscRenderResult, RscWorker } from "./rscWorkerHost.d.ts";
@@ -49,13 +49,15 @@ 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;
 }
 export declare class WebRouter {
     #private;
     renderState: RenderState;
     /** What this router actually mounts, already intersected with what the artifact carries. */
     readonly web: AkanWebConfig;
-    constructor({ artifact, web, cssBytesByUrl, rsc, seedIndex, upgradeHmrWs }: WebRouterOptions);
+    constructor({ artifact, web, cssBytesByUrl, rsc, seedIndex, upgradeHmrWs, prebuilt }: WebRouterOptions);
     initializeRoute(): Promise<{
         renderEnvRoutes: Bun.Serve.Routes<unknown, string> | Bun.Serve.RoutesWithUpgrade<unknown, string>;
         hmrHub: HmrWsHub | null;