akanjs 3.0.0-beta.24 → 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.24",
+  "version": "3.0.0-beta.26",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

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

@@ -1054,6 +1054,7 @@ export class AkanApp {
       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

@@ -12,6 +12,7 @@ import type {
   CssPayload,
   DevBuildStatus,
   PagesBundlePayload,
+  SsrUpdatedPayload,
 } from "./ipcTypes";
 
 export interface BuilderRpcEventHandlers {
@@ -19,8 +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;
 }
 
@@ -59,11 +61,19 @@ 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);
           return;
@@ -90,6 +100,7 @@ export class BuilderRpc {
       discoveredEntries: payload.discoveredEntries,
       clientDeps: payload.clientDeps,
       clientDepsByEntry: payload.clientDepsByEntry,
+      ...(payload.seenGeneration !== undefined ? { seenGeneration: payload.seenGeneration } : {}),
     };
   }
 

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

@@ -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;
@@ -50,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 = {
@@ -76,19 +80,35 @@ 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;
@@ -101,6 +121,24 @@ export interface CsrUpdatedPayload {
   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 =
@@ -117,8 +155,11 @@ 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;
 
@@ -138,4 +179,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("#");

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;