akanjs 3.0.0-beta.23 → 3.0.0-beta.25

package/client/csrTypes.ts

@@ -103,6 +103,9 @@ export type LayoutErrorRender = (props: LayoutErrorProps) => PromiseOrObject<Rea
 export interface RouteRender {
   render: LayoutRender | PageRender;
   isAsync?: boolean;
+  /** CSR: a page's render reads the query; a layout's reads only the params of its own path (`paramNames`). */
+  kind?: "page" | "layout";
+  paramNames?: string[];
   Loading?: LayoutLoadingRender | PageLoadingRender;
   /** Loads the module and fills `Loading` without running `render`/`resolveHead` (the suffix compose path). */
   resolveLoading?: () => void | Promise<void>;
@@ -221,6 +224,7 @@ export interface Location {
   searchParams: { [key: string]: string | string[] };
   pathRoute: PathRoute;
   hash: string;
+  entryId?: string; 
 }
 export type CsrNavigationPhase = "idle" | "preparing" | "transitioning";
 export type CsrNavigationKind = "push" | "replace" | "back" | "popForward" | "popBack";
@@ -247,6 +251,7 @@ export interface History {
   idxMap: Map<string, number>;
   cachedLocationMap: Map<string, Location>;
   idx: number;
+  dormant?: Set<string>; 
 }
 
 export interface RouterProps {
@@ -256,14 +261,24 @@ export interface RouterProps {
   back: () => void | Promise<void>;
 }
 
+export type CsrPageType = "current" | "prev" | "pending" | "cached";
+export interface CsrStackEntry {
+  key: string; 
+  location: Location;
+  pageType: CsrPageType;
+  zIndex: number;
+}
+
 export interface RouteState {
   clientWidth: number;
   clientHeight: number;
   location: Location;
   prevLocation: Location | null;
   pendingLocation: Location | null;
+  stackEntries: CsrStackEntry[];
   navigationIntent: NavigationIntent | null;
   phase: CsrNavigationPhase;
+  isBackgrounded: boolean;
   history: RefObject<History>;
   topSafeAreaRef: RefObject<HTMLDivElement | null>;
   bottomSafeAreaRef: RefObject<HTMLDivElement | null>;
@@ -304,7 +319,8 @@ export const useCsr = () => {
 };
 
 export interface PathContextType {
-  pageType: "current" | "prev" | "cached" | "pending";
+  pageType: CsrPageType;
+  pageKey?: string;
   location: Location;
   prefix?: string;
   gestureEnabled: boolean;
@@ -317,6 +333,16 @@ export const usePathCtx = () => {
   return contextValues;
 };
 
+export type PageActivity = "current" | "prev" | "pending" | "hidden";
+export interface PageActivityState {
+  activity: PageActivity;
+  focused: boolean;
+}
+export const pageActivityContext = sharedContext<PageActivityState>("pageActivity", {
+  activity: "current",
+  focused: true,
+});
+
 export interface PathRoute {
   path: string;
   pathSegments: string[];

package/client/native.ts

@@ -35,6 +35,9 @@ export const isNativeApp = () => isNative && (platform === "ios" || platform ===
 
 export const nativePlatform = () => (isNativeApp() ? (platform as "ios" | "android") : null);
 
+export const desktopPlatform = () =>
+  isNative && (platform === "macos" || platform === "windows" || platform === "linux") ? platform : null;
+
 /** http(s) in the in-app browser, anything else (mailto:, tel:) in the app the system picks. */
 export const openExternalUrl = async (url: string) => {
   if (!isNativeApp()) {

package/client/route/RouteDefinition.ts

@@ -17,6 +17,8 @@ export type RouteArgsShape = Record<string, unknown>;
 export type RouteKind = "page" | "layout" | "rootLayout";
 /** Interned: a definition built inside the pages bundle must be recognised by a loader bundled apart from it. */
 export const routeDefinitionMarker = Symbol.for("akan.routeDefinition");
+/** Interned like the marker: the declared args ride on the module's render function, read by the CSR render cache. */
+export const routeArgsMarker = Symbol.for("akan.routeArgs");
 
 type HeadStage<Args> = Head | ((args: Args) => PromiseOrObject<Head | null | undefined>);
 
@@ -44,6 +46,11 @@ export abstract class RouteDefinition<
   #head?: HeadStage<never>;
   #loading?: (args: never) => PromiseOrObject<ReactNode>;
   #render?: (args: never) => PromiseOrObject<ReactNode>;
+  #renderRoute?: {
+    render: (args: never) => PromiseOrObject<ReactNode>;
+    argCount: number;
+    route: (props: RouteRenderProps) => Promise<ReactNode>;
+  };
 
   config(config: PageConfig) {
     this.#config = config;
@@ -122,7 +129,7 @@ export abstract class RouteDefinition<
     const head = this.#head;
     const loading = this.#loading;
     const module: PageModule & LayoutModule = {
-      default: (async (props: RouteRenderProps) => await render(this.#argsOf(props) as never)) as never,
+      default: this.#renderRouteOf(render) as never,
       ...(this.#config ? { pageConfig: this.#config } : {}),
       ...(head === undefined
         ? {}
@@ -143,6 +150,39 @@ export abstract class RouteDefinition<
     return module;
   }
 
+  #renderRouteOf(render: (args: never) => PromiseOrObject<ReactNode>) {
+    const kept = this.#renderRoute;
+    if (kept?.render === render && kept.argCount === this.args.length) return kept.route;
+    const route = async (props: RouteRenderProps) => await render(this.#argsOf(props) as never);
+    Object.defineProperty(route, routeArgsMarker, { value: this.args.map(({ kind, name }) => ({ kind, name })) });
+    this.#renderRoute = { render, argCount: this.args.length, route };
+    return route;
+  }
+
+  /**
+   * What a route's render output depends on: a chain's declared args plus `lang`. A legacy module declares nothing,
+   * so it depends on the params of its own path (`paramNames`, every param when unknown) and, for a page, every
+   * search value — a layout reads no query.
+   */
+  static renderArgsKey(
+    render: unknown,
+    props: { params: Record<string, string>; searchParams?: Record<string, string | string[]> },
+    { isPage, paramNames }: { isPage: boolean; paramNames?: string[] },
+  ): string {
+    const declared = (render as { [routeArgsMarker]?: Pick<RouteArgInfo, "kind" | "name">[] } | null)?.[
+      routeArgsMarker
+    ];
+    const searchParams = props.searchParams ?? {};
+    if (!declared) {
+      const params = paramNames ? paramNames.map((name) => props.params[name]) : props.params;
+      return JSON.stringify([params, isPage ? searchParams : null]);
+    }
+    return JSON.stringify([
+      props.params.lang,
+      ...declared.map(({ kind, name }) => (kind === "param" ? props.params[name] : searchParams[name])),
+    ]);
+  }
+
   #argsOf(props: RouteRenderProps): RouteBaseArgs & Args & Extra {
     const { lang = parseAkanI18nEnv().defaultLocale } = props.params;
     const resolved = this.resolveArgs({ params: props.params, searchParams: props.searchParams ?? {} });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-beta.23",
+  "version": "3.0.0-beta.25",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -200,6 +200,16 @@
       "types": "./types/server/logging/logTailClient.d.ts",
       "import": "./server/logging/logTailClient.ts",
       "default": "./server/logging/logTailClient.ts"
+    },
+    "./server/hmr/csrDevManifest": {
+      "types": "./types/server/hmr/csrDevManifest.d.ts",
+      "import": "./server/hmr/csrDevManifest.ts",
+      "default": "./server/hmr/csrDevManifest.ts"
+    },
+    "./server/hmr/runtimeMetadataFile": {
+      "types": "./types/server/hmr/runtimeMetadataFile.d.ts",
+      "import": "./server/hmr/runtimeMetadataFile.ts",
+      "default": "./server/hmr/runtimeMetadataFile.ts"
     }
   },
   "dependencies": {
@@ -224,13 +234,13 @@
     "ioredis": "^5.10.1",
     "postgres": "^3.4.9",
     "protobufjs": "^8.4.0",
-    "react": "19.2.7",
-    "react-dom": "19.2.7",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
     "react-icons": "^5.6.0",
-    "react-refresh": "^0.18.0",
-    "react-server-dom-webpack": "^19.2.7",
+    "react-refresh": "^0.19.0",
+    "react-server-dom-webpack": "^19.3.0",
     "react-spring": "^10.0.4",
-    "scheduler": "^0.27.0",
+    "scheduler": "^0.28.0",
     "tailwind-scrollbar": "^4.0.2",
     "typescript": "^6.0.3"
   },

package/server/SSR_MEMORY_DIAGNOSIS.md

@@ -130,8 +130,8 @@ that no GC reclaims, so the process only returns that memory by exiting. `AkanAp
 recycles it — gracefully, after its queues drain and once it has stayed quiet — past a ceiling:
 
 ```sh
-AKAN_BUILDER_MAX_RSS_MB=1200   # 0 leaves the builder unbounded; default is 1200 in dev
-AKAN_BUILDER_MAX_RSS=1200mb    # same ceiling with a unit suffix
+AKAN_BUILDER_MAX_RSS_MB=2048   # 0 leaves the builder unbounded; default is 2048 in dev
+AKAN_BUILDER_MAX_RSS=2gb       # same ceiling with a unit suffix
 ```
 
 Both resolve through `MemoryLimit.resolveMaxRssBytes`, so `AKAN_MEMORY_LIMIT` or a cgroup limit also

package/server/akanApp.ts

@@ -762,9 +762,7 @@ export class AkanApp {
       return await this.#proxyResponse(req, upstreamRes);
     } catch (error) {
       if (AkanApp.#isUpstreamOpenFailure(error)) {
-        this.logger.error(
-          `Child ${child.idx}/${child.role} upstream is unreachable (${socketPath}); restarting`,
-        );
+        this.logger.error(`Child ${child.idx}/${child.role} upstream is unreachable (${socketPath}); restarting`);
         this.#scheduleChildRestart(child, child.proc, "upstream-open-failed");
         return AkanApp.#unavailableResponse(req, "Federation child upstream is unreachable; restarting");
       }
@@ -1055,6 +1053,8 @@ export class AkanApp {
       case "invalidate":
       case "css-updated":
       case "pages-updated":
+      case "csr-updated":
+      case "ssr-updated":
       case "build-status":
         this.#fanoutToFederation(message);
         return;

package/server/akanServer.ts

@@ -380,7 +380,13 @@ export class AkanServer {
         registry: this.#di.registry,
         live: this.#di.live,
         hmrHub,
-        hmrState: webRouter ? { state: webRouter.renderState } : null,
+        hmrState: webRouter
+          ? {
+              state: webRouter.renderState,
+              refresh: () => webRouter.refreshHmrState(),
+              errors: () => webRouter.hmrBuildErrors(),
+            }
+          : null,
         logger: this.logger,
         onDrain: () => this.#binaryPubsub.flush(),
       }),

package/server/artifact/builderRpc.ts

@@ -8,9 +8,11 @@ import type {
   BuilderRes,
   BuildRouteClientResult,
   BuildRouteResultPayload,
+  CsrUpdatedPayload,
   CssPayload,
   DevBuildStatus,
   PagesBundlePayload,
+  SsrUpdatedPayload,
 } from "./ipcTypes";
 
 export interface BuilderRpcEventHandlers {
@@ -18,7 +20,9 @@ export interface BuilderRpcEventHandlers {
   onInvalidate?: (event: { kinds: ("code" | "css" | "config")[]; files: string[]; generation?: number }) => void;
   onCssUpdated?: (css: CssPayload) => void;
   /** A fresh `pages-*.js` bundle: re-import it in the running worker (`RscWorker.reload`) rather than respawning. */
-  onPagesUpdated?: (bundle: PagesBundlePayload) => void;
+  onPagesUpdated?: (bundle: PagesBundlePayload) => void | Promise<void>;
+  onCsrUpdated?: (update: CsrUpdatedPayload) => void;
+  onSsrUpdated?: (update: SsrUpdatedPayload) => void;
   onBuildStatus?: (status: DevBuildStatus) => void;
 }
 
@@ -57,7 +61,18 @@ export class BuilderRpc {
           handlers.onCssUpdated?.(ev.data);
           return;
         case "pages-updated":
-          handlers.onPagesUpdated?.(ev.data);
+          
+          void Promise.resolve(handlers.onPagesUpdated?.(ev.data)).catch((error: unknown) =>
+            this.#logger.error(
+              `[builder] pages-updated failed: ${error instanceof Error ? error.message : String(error)}`,
+            ),
+          );
+          return;
+        case "csr-updated":
+          handlers.onCsrUpdated?.(ev.data);
+          return;
+        case "ssr-updated":
+          handlers.onSsrUpdated?.(ev.data);
           return;
         case "build-status":
           handlers.onBuildStatus?.(ev.data);
@@ -85,6 +100,7 @@ export class BuilderRpc {
       discoveredEntries: payload.discoveredEntries,
       clientDeps: payload.clientDeps,
       clientDepsByEntry: payload.clientDepsByEntry,
+      ...(payload.seenGeneration !== undefined ? { seenGeneration: payload.seenGeneration } : {}),
     };
   }
 

package/server/artifact/ipcTypes.ts

@@ -9,6 +9,8 @@ export interface BuildRouteResultPayload {
   clientDepsByEntry?: Record<string, string[]>;
   routeId?: string;
   generation?: number;
+  /** The newest save batch whose files its client-entry discovery had taken in when it started. */
+  seenGeneration?: number;
 }
 
 /** Re-announces a recycled builder's artifact (not an edit); the host drops it when the hashed output did not move. */
@@ -42,7 +44,7 @@ export interface DevChangePlan {
   reasonByFile: Record<string, string[]>;
 }
 
-export type BuildPhase = "scan" | "barrel" | "csr" | "pages" | "css" | "route" | "backend";
+export type BuildPhase = "scan" | "barrel" | "csr" | "ssr" | "pages" | "css" | "route" | "backend";
 
 export interface DevBuildStatus {
   generation: number;
@@ -76,24 +78,67 @@ export type BuilderCsrRes =
 /** Drain and exit (the only way bundler memory returns to the OS); draining, not killing, keeps a rebuild whole. */
 export type BuilderControl = { type: "builder-shutdown"; reason: string };
 
+/** Epoch-ms marks a save picks up on its way to the page, so a slow update says which hop it waited in. */
+export interface HmrTrace {
+  eventAt?: number; 
+  flushAt?: number; 
+  batchAt?: number; 
+  spawnAt?: number; 
+  workerStartAt?: number; 
+  workerAt?: number; 
+  patchAt?: number; 
+  sentAt?: number; 
+  broadcastAt?: number; 
+}
+
 export interface PagesBundlePayload {
   bundlePath: string;
   buildId: number;
   generation?: number;
   changedFiles?: string[];
   reason?: BuilderStateReason;
+  trace?: HmrTrace;
+  /** False when no changed file is one the server renders (a `"use client"` edit that kept its export names). */
+  serverTouched?: boolean;
 }
 
 /** `Bun.build` keeps native arenas `Bun.gc(true)` never frees (macOS returns none when idle): hence recycling. */
 export interface BuilderMetrics {
   /** A peak sampled when the queues drain; stale within seconds on Linux, so the host re-reads RSS from the OS. */
   rssBytes: number;
-  /** The builder's newest generation; 0 until it has processed a watch batch since spawning. */
+  /** The builder's newest generation; a replacement builder continues from the last one its host saw. */
   generation: number;
   /** Work items completed since this builder spawned, so a host can require real work before recycling. */
   workCount: number;
 }
 
+export interface CsrUpdatedPayload {
+  generation: number;
+  mode: "registry" | "artifact";
+  reload: boolean;
+  reason?: string;
+  patchUrl?: string;
+  changedIds?: string[];
+  trace?: HmrTrace;
+}
+
+/** A new generation of the SSR dev registry, where SSR pages load their client code from: a patch, or a reload. */
+export interface SsrUpdatedPayload {
+  generation: number;
+  reload: boolean;
+  reason?: string;
+  patchUrl?: string;
+  changedIds?: string[];
+  trace?: HmrTrace;
+  /** The save also changed what the server renders: the tabs get this patch with that batch's RSC refresh. */
+  hold?: boolean;
+  /** The watch batch this patch came from, which the `pages-updated` releasing it names as its generation. */
+  batchGeneration?: number;
+  epoch?: number;
+  /** The registry's first build: no tab holds a module of it, so there is nothing to send them. */
+  first?: boolean;
+}
+
 export type BuilderEvent =
   
   | { type: "builder-ready"; buildId?: string }
@@ -107,8 +152,12 @@ export type BuilderEvent =
     }
   | { type: "css-updated"; data: CssPayload }
   | { type: "pages-updated"; data: PagesBundlePayload }
+  | { type: "csr-updated"; data: CsrUpdatedPayload }
+  | { type: "ssr-updated"; data: SsrUpdatedPayload }
   | { type: "build-status"; data: DevBuildStatus }
-  | { type: "builder-metrics"; data: BuilderMetrics };
+  | { type: "builder-metrics"; data: BuilderMetrics }
+  /** The boot builds settled (the SSR registry's, and CSR's when the env arms it): their workers are a boot's peak. */
+  | { type: "boot-armed" };
 
 export type BuilderMessage = BuilderReq | BuilderRes | BuilderCsrReq | BuilderCsrRes | BuilderControl | BuilderEvent;
 
@@ -128,4 +177,6 @@ export interface BuildRouteClientResult {
   discoveredEntries?: string[];
   clientDeps: string[];
   clientDepsByEntry?: Record<string, string[]>;
+  /** The newest save batch whose files its client-entry discovery had taken in when it started. */
+  seenGeneration?: number;
 }

package/server/artifact/routeClientCache.ts

@@ -30,9 +30,24 @@ type PendingBuild = { generation: number; promise: Promise<BuildRouteClientResul
 export interface InvalidateClientEntriesOptions {
   routePredicate: (routeId: string) => boolean;
   staleEntries: Iterable<string>;
+  /** The saved files behind it: a build still running that bundled one of them is built again. */
+  files?: Iterable<string>;
+  /** The save batch behind it: a route build whose discovery had taken that batch in is neither dropped nor rebuilt. */
+  batch?: number;
+}
+interface Invalidation {
+  /** The generation it moved the cache to: only a build started before it is checked against it. */
+  generation: number;
+  cleared: boolean;
+  routePredicate: (routeId: string) => boolean;
+  /** Its stale entries and saved files, normalized. */
+  touched: Set<string>;
+  batch?: number;
 }
 
 export class RouteClientCache {
+  static readonly #minEnsureAttempts = 3;
+  static readonly #ensureBudgetMs = 15_000;
   readonly #logger = new Logger("RouteClientCache");
   readonly #built = new Map<string, BuildRouteClientResult>();
   readonly #building = new Map<string, PendingBuild>();
@@ -40,6 +55,7 @@ export class RouteClientCache {
   readonly #buildRoute: RouteBuildFn;
   readonly #onMerge?: OnMergeFn;
   #revision = 0;
+  #invalidations: Invalidation[] = [];
 
   constructor({ buildRoute, onMerge }: RouteClientCacheOptions) {
     this.#buildRoute = buildRoute;
@@ -76,21 +92,33 @@ export class RouteClientCache {
   }
 
   async ensure(routeId: string, seeds: string[]): Promise<MergedManifest> {
-    if (this.#built.has(routeId)) return this.merged;
-    const existing = this.#building.get(routeId);
-    if (existing && existing.generation === this.merged.generation) {
-      await existing.promise;
-      return this.merged;
-    }
-    const generation = this.merged.generation;
-    const promise = this.#runBuild(routeId, seeds, generation);
-    this.#building.set(routeId, { generation, promise });
-    try {
-      await promise;
-    } finally {
-      const current = this.#building.get(routeId);
-      if (current?.promise === promise) this.#building.delete(routeId);
+    const started = Date.now();
+    const deadline = started + RouteClientCache.#ensureBudgetMs;
+    const within = (attempt: number) => attempt < RouteClientCache.#minEnsureAttempts || Date.now() < deadline;
+    let attempt = 0;
+    for (; within(attempt) && !this.#built.has(routeId); attempt += 1) {
+      const existing = this.#building.get(routeId);
+      if (existing) {
+        
+        if (existing.generation === this.merged.generation) await existing.promise;
+        else await existing.promise.catch(() => undefined);
+        continue;
+      }
+      const generation = this.merged.generation;
+      const promise = this.#runBuild(routeId, seeds, generation);
+      this.#building.set(routeId, { generation, promise });
+      try {
+        await promise;
+      } finally {
+        const current = this.#building.get(routeId);
+        if (current?.promise === promise) this.#building.delete(routeId);
+        this.#prune();
+      }
     }
+    if (attempt > 1)
+      this.#logger.verbose(
+        `[route-cache] ensure routeId=${routeId} took ${attempt} attempts in ${Date.now() - started}ms${this.#built.has(routeId) ? "" : "; rendering without it"}`,
+      );
     return this.merged;
   }
 
@@ -113,7 +141,7 @@ export class RouteClientCache {
     const knownEntries = new Set(this.merged.knownEntries);
     this.#logger.verbose(`[route-cache] build start routeId=${routeId} generation=${generation} seeds=${seeds.length}`);
     const delta = await this.#buildRoute(routeId, { seeds, knownEntries, generation });
-    if (this.merged.generation !== generation) {
+    if (this.merged.generation !== generation && this.#overtaken(routeId, generation, delta)) {
       this.#logger.verbose(
         `[route-cache] stale build ignored routeId=${routeId} generation=${generation} current=${this.merged.generation}`,
       );
@@ -142,39 +170,106 @@ export class RouteClientCache {
     return dropped;
   }
 
-  invalidate(predicate: (routeId: string) => boolean): string[] {
-    const dropped = this.#dropBuilt(predicate);
-    if (dropped.length > 0) {
-      this.#rebuildKnownEntriesPreservingManifest(this.merged.generation + 1);
-      this.#building.clear();
-      this.#logger.verbose(`[route-cache] invalidated ${dropped.length} routes: ${dropped.join(", ")}`);
-    }
+  invalidate(
+    predicate: (routeId: string) => boolean,
+    { files = [], batch }: { files?: Iterable<string>; batch?: number } = {},
+  ): string[] {
+    const spared = this.#sparedBy(batch);
+    const routePredicate = (routeId: string) => predicate(routeId) && !spared.has(routeId);
+    const dropped = this.#dropBuilt(routePredicate);
+    const touched = RouteClientCache.#normalizeAll(files);
+    if (dropped.length === 0 && !this.#mayOvertake(routePredicate, touched)) return dropped;
+    this.#rebuildKnownEntriesPreservingManifest(this.merged.generation + 1);
+    this.#record({ routePredicate, touched, batch });
+    this.#logger.verbose(`[route-cache] invalidated ${dropped.length} routes: ${dropped.join(", ")}`);
     return dropped;
   }
 
-  invalidateClientEntries({ routePredicate, staleEntries }: InvalidateClientEntriesOptions): string[] {
-    const normalizedStaleEntries = new Set([...staleEntries].map((entry) => RouteClientCache.#normalizePath(entry)));
-    const dropped = this.#dropBuilt(routePredicate);
-    if (dropped.length === 0 && normalizedStaleEntries.size === 0) return dropped;
+  invalidateClientEntries({
+    routePredicate,
+    staleEntries,
+    files = [],
+    batch,
+  }: InvalidateClientEntriesOptions): string[] {
+    const spared = this.#sparedBy(batch);
+    
+    const fresh = [...spared.values()].flatMap((delta) => [...RouteClientCache.#reachedOf(delta)]);
+    const normalizedStaleEntries = new Set(
+      [...RouteClientCache.#normalizeAll(staleEntries)].filter(
+        (entry) => !fresh.some((file) => file === entry || file.endsWith(`/${entry}`)),
+      ),
+    );
+    const touched = new Set([...normalizedStaleEntries, ...RouteClientCache.#normalizeAll(files)]);
+    const predicate = (routeId: string) => routePredicate(routeId) && !spared.has(routeId);
+    const dropped = this.#dropBuilt(predicate);
+    if (dropped.length === 0 && normalizedStaleEntries.size === 0 && !this.#mayOvertake(predicate, touched))
+      return dropped;
 
     this.#rebuildKnownEntriesPreservingManifest(this.merged.generation + 1, normalizedStaleEntries);
-    this.#building.clear();
+    this.#record({ routePredicate: predicate, touched, batch });
     this.#logger.verbose(
-      `[route-cache] client invalidated routes=${dropped.join(",") || "(none)"} entries=${normalizedStaleEntries.size}`,
+      `[route-cache] client invalidated routes=${dropped.join(",") || "(none)"} entries=${normalizedStaleEntries.size}${spared.size > 0 ? ` kept=${[...spared.keys()].join(",")}` : ""}`,
     );
     return dropped;
   }
 
+  #sparedBy(batch: number | undefined): Map<string, BuildRouteClientResult> {
+    if (batch === undefined) return new Map();
+    return new Map([...this.#built].filter(([, delta]) => (delta.seenGeneration ?? -1) >= batch));
+  }
+
+  static #reachedOf(delta: BuildRouteClientResult): Set<string> {
+    return RouteClientCache.#normalizeAll([
+      ...(delta.discoveredEntries ?? []),
+      ...delta.newEntries,
+      ...delta.clientDeps,
+      ...Object.values(delta.clientDepsByEntry ?? {}).flat(),
+    ]);
+  }
+
   clear(): string[] {
     const dropped = this.#dropBuilt(() => true);
     const nextGeneration = this.merged.generation + 1;
     this.merged = this.#getEmptyMerged(nextGeneration);
     this.#revision += 1;
-    this.#building.clear();
+    this.#record({ cleared: true, routePredicate: () => true, touched: new Set() });
     this.#logger.verbose(`[route-cache] cleared generation=${nextGeneration} dropped=${dropped.length}`);
     return dropped;
   }
 
+  #mayOvertake(predicate: (routeId: string) => boolean, touched: Set<string>): boolean {
+    return this.#building.size > 0 && (touched.size > 0 || [...this.#building.keys()].some(predicate));
+  }
+
+  #record({
+    cleared = false,
+    routePredicate,
+    touched,
+    batch,
+  }: Omit<Invalidation, "generation" | "cleared"> & { cleared?: boolean }) {
+    this.#invalidations.push({ generation: this.merged.generation, cleared, routePredicate, touched, batch });
+    this.#prune();
+  }
+
+  #prune(): void {
+    let oldest = Number.POSITIVE_INFINITY;
+    for (const pending of this.#building.values()) oldest = Math.min(oldest, pending.generation);
+    this.#invalidations = this.#invalidations.filter((invalidation) => invalidation.generation > oldest);
+  }
+
+  #overtaken(routeId: string, since: number, delta: BuildRouteClientResult): boolean {
+    const reached = RouteClientCache.#reachedOf(delta);
+    return this.#invalidations.some(
+      (invalidation) =>
+        invalidation.generation > since &&
+        !(invalidation.batch !== undefined && (delta.seenGeneration ?? -1) >= invalidation.batch) &&
+        (invalidation.cleared ||
+          invalidation.routePredicate(routeId) ||
+          (!delta.discoveredEntries && invalidation.touched.size > 0) ||
+          [...invalidation.touched].some((file) => reached.has(file))),
+    );
+  }
+
   #rebuildKnownEntriesPreservingManifest(generation: number, staleEntries: Set<string> = new Set()): void {
     const staleUrls = new Set<string>();
     for (const [key, row] of Object.entries(this.merged.clientManifest)) {
@@ -210,6 +305,10 @@ export class RouteClientCache {
     return filePath.split("\\").join("/");
   }
 
+  static #normalizeAll(filePaths: Iterable<string>): Set<string> {
+    return new Set([...filePaths].map((filePath) => RouteClientCache.#normalizePath(filePath)));
+  }
+
   static #manifestKeyMatchesEntries(key: string, entries: Set<string>): boolean {
     if (entries.size === 0) return false;
     const hashIdx = key.lastIndexOf("#");