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

package/server/hmr/clientScript.ts

@@ -1,3 +1,4 @@
+import { SSR_DEV_ROUTE_PREFIX } from "./csrDevManifest";
 import { isSyncNavigationEnabled } from "./wsHub";
 
 export const HMR_CLIENT_SCRIPT = `(function(){
@@ -5,15 +6,16 @@ export const HMR_CLIENT_SCRIPT = `(function(){
   self.__AKAN_HMR_INSTALLED__ = true;
   var syncNavigationEnabled = ${JSON.stringify(isSyncNavigationEnabled())};
   var syncNavigationClientId = Math.random().toString(36).slice(2) + Date.now().toString(36);
+  var clientKind = self.__AKAN_HMR_CLIENT__ === "csr" ? "csr" : "ssr";
+  var systemPage = !!self.__AKAN_HMR_SYSTEM_PAGE__;
   var proto = location.protocol === "https:" ? "wss:" : "ws:";
-  var url = proto + "//" + location.host + "/_akan/hmr";
+  var url = proto + "//" + location.host + "/_akan/hmr" + (clientKind === "csr" ? "?client=csr" : "");
   var attempts = 0;
   var socket = null;
   var lastBuildId = null;
   var refreshRuntimePromise = null;
   var refreshRuntime = null;
   var pendingRefreshRegistrations = [];
-  var refreshQueue = Promise.resolve();
   var overlayEl = null;
   var overlayLabelEl = null;
   var overlayDetailEl = null;
@@ -23,7 +25,7 @@ export const HMR_CLIENT_SCRIPT = `(function(){
   var overlayNextToken = 1;
   var overlayJobs = {};
   var buildErrorStates = {};
-  self.__AKAN_HMR_PHASE__ = null;
+  var traces = self.__AKAN_HMR_TRACES__ = self.__AKAN_HMR_TRACES__ || [];
   self.__AKAN_DEV_SYNC_NAVIGATION__ = function(href, kind){
     if (self.__AKAN_DEV_SYNC_NAVIGATION_APPLYING__ || !syncNavigationEnabled || !socket || socket.readyState !== WebSocket.OPEN) return;
     try {
@@ -43,7 +45,7 @@ export const HMR_CLIENT_SCRIPT = `(function(){
     else pendingRefreshRegistrations.push([type, id]);
   };
   self.$RefreshSig$ = self.$RefreshSig$ || function(){ return function(type){ return type; }; };
-  ensureRefreshRuntime().catch(function(err){
+  if (clientKind === "ssr" && !systemPage) ensureRefreshRuntime().catch(function(err){
     console.warn("[akan-hmr] React Refresh runtime preload failed", err);
   });
 
@@ -56,11 +58,41 @@ export const HMR_CLIENT_SCRIPT = `(function(){
       try { msg = JSON.parse(ev.data); } catch (e){ return; }
       if (!msg || typeof msg.type !== "string") return;
       if (msg.type === "hello") {
-        if (lastBuildId !== null && msg.buildId !== lastBuildId) {
-          location.reload();
+        var dropped = Array.isArray(msg.failingPhases) && dropBuildErrorsExcept(msg.failingPhases);
+        if (dropped && systemPage) {
+          reloadForUpdate("the build that failed to render this page recovered");
+          return;
+        }
+        if (clientKind === "csr") {
+          if (csrGenerationMoved(msg.csrGeneration)) reloadForUpdate("missed a CSR update while disconnected");
+          return;
+        }
+        if (systemPage) {
+          if (lastBuildId !== null && msg.buildId !== lastBuildId) location.reload();
+          lastBuildId = msg.buildId;
+          return;
+        }
+        if (ssrRegistryReplaced(msg.ssrEpoch)) {
+          reloadForUpdate("the dev server rebuilt the SSR registry while this tab held the previous one");
+          return;
+        }
+        if (ssrRegistryGone(msg.ssrEpoch)) {
+          reloadForUpdate("the dev server has no SSR registry yet: a new session or a config restart is building one");
           return;
         }
-        lastBuildId = msg.buildId;
+        if (ssrBootFailedBefore(msg.ssrGeneration, msg.ssrEpoch)) {
+          reloadForUpdate("the SSR registry this tab failed to load was rebuilt");
+          return;
+        }
+        if (typeof msg.ssrGeneration === "number") self.__AKAN_SSR_HELLO_GENERATION__ = msg.ssrGeneration;
+        var sameRegistry = holdsSsrRegistry(msg.ssrEpoch);
+        if (sameRegistry) catchUpSsrRegistry(msg.ssrGeneration);
+        if (lastBuildId === null || msg.buildId === lastBuildId) {
+          lastBuildId = msg.buildId;
+          return;
+        }
+        if (sameRegistry) refreshRsc({ buildId: msg.buildId });
+        else location.reload();
         return;
       }
       if (msg.type === "reload") {
@@ -73,8 +105,12 @@ export const HMR_CLIENT_SCRIPT = `(function(){
         refreshRsc(msg);
         return;
       }
-      if (msg.type === "client-refresh") {
-        refreshClient(msg);
+      if (msg.type === "csr-update") {
+        applyCsrUpdate(msg);
+        return;
+      }
+      if (msg.type === "ssr-update") {
+        applySsrUpdate(msg);
         return;
       }
       if (msg.type === "css-update") {
@@ -112,6 +148,81 @@ export const HMR_CLIENT_SCRIPT = `(function(){
     socket.addEventListener("error", function(){ try { socket && socket.close(); } catch(e){} });
   }
 
+  function csrGenerationMoved(generation){
+    if (typeof generation !== "number") return false;
+    var current = self.__akan ? self.__akan.generation : self.__AKAN_CSR_GENERATION__;
+    return typeof current === "number" && current !== generation;
+  }
+
+  function reloadForUpdate(reason){
+    console.warn("[akan-hmr] reloading the page: " + reason);
+    beginHmrOverlay("Reloading...", true);
+    setTimeout(function(){ location.reload(); }, 30);
+  }
+
+  function recordTrace(kind, msg, receivedAt, appliedAt){
+    traces.push({ kind: kind, generation: msg.generation, trace: msg.trace || null, receivedAt: receivedAt, appliedAt: appliedAt });
+    if (traces.length > 64) traces.shift();
+  }
+
+  function applyCsrUpdate(msg){
+    recordTrace("csr", msg, Date.now(), null);
+    if (msg.reload || !self.__akan || typeof self.__akan.hot !== "function") {
+      reloadForUpdate(msg.reason || "the CSR bundle was rebuilt");
+      return;
+    }
+    self.__akan.hot(msg);
+  }
+
+  function ssrRegistryReplaced(epoch){
+    var own = self.__AKAN_SSR_EPOCH__;
+    return typeof epoch === "number" && typeof own === "number" && own !== epoch;
+  }
+
+  function holdsSsrRegistry(epoch){
+    return typeof epoch === "number" && self.__AKAN_SSR_EPOCH__ === epoch;
+  }
+
+  function ssrRegistryGone(epoch){
+    return typeof self.__AKAN_SSR_EPOCH__ === "number" && typeof epoch !== "number";
+  }
+
+  function catchUpSsrRegistry(generation){
+    var registry = self.__akan;
+    if (typeof generation !== "number" || !registry || typeof registry.catchUp !== "function") return;
+    if (registry.inspect().target < generation) registry.catchUp(generation, ${JSON.stringify(SSR_DEV_ROUTE_PREFIX)});
+  }
+
+  function ssrBootFailedBefore(generation, epoch){
+    var failed = self.__AKAN_SSR_BOOT_FAILED__;
+    if (!failed || typeof generation !== "number") return false;
+    return generation > failed.generation || (typeof epoch === "number" && typeof failed.epoch === "number" && epoch !== failed.epoch);
+  }
+
+  function applySsrUpdate(msg){
+    recordTrace("ssr", msg, Date.now(), null);
+    if (systemPage) {
+      reloadForUpdate("a save changed the client code of the page that failed to render");
+      return;
+    }
+    if (ssrBootFailedBefore(msg.generation)) {
+      reloadForUpdate("the SSR registry this tab failed to load was updated");
+      return;
+    }
+    var startFailed = !!(self.__akan && typeof self.__akan.inspect === "function" && self.__akan.inspect().failed);
+    if (msg.reload && self.__akan && (!(msg.generation <= self.__akan.generation) || (startFailed && msg.generation >= self.__akan.generation))) {
+      reloadForUpdate(msg.reason || "the SSR registry was rebuilt");
+      return;
+    }
+    if (self.__akan && typeof self.__akan.hot === "function") {
+      self.__akan.hot(msg);
+      return;
+    }
+    var early = self.__AKAN_SSR_EARLY_UPDATES__ = self.__AKAN_SSR_EARLY_UPDATES__ || [];
+    early.push(msg);
+    if (early.length > 64) early.shift();
+  }
+
   function schedule(){
     attempts = Math.min(attempts + 1, 6);
     var delay = Math.min(30000, 250 * Math.pow(2, attempts - 1));
@@ -230,6 +341,10 @@ export const HMR_CLIENT_SCRIPT = `(function(){
       showBuildErrorOverlay(msg);
       return;
     }
+    if (msg.status === "ok" && systemPage) {
+      reloadForUpdate("the build that failed to render this page recovered");
+      return;
+    }
     if (msg.status === "ok") clearBuildErrorOverlay(msg);
   }
 
@@ -272,9 +387,25 @@ export const HMR_CLIENT_SCRIPT = `(function(){
     var current = buildErrorStates[phase];
     if (!current) return;
     var generation = typeof msg.generation === "number" ? msg.generation : 0;
-    var recovered = phase === "backend" ? generation >= current.generation : generation > current.generation;
+    var sameGeneration = phase === "backend" || phase === "scan" || phase === "route";
+    var recovered = sameGeneration ? generation >= current.generation : generation > current.generation;
     if (!recovered) return;
     delete buildErrorStates[phase];
+    showBuildRecovered(msg);
+  }
+
+  function dropBuildErrorsExcept(failing){
+    var dropped = false;
+    for (var phase in buildErrorStates) {
+      if (failing.indexOf(phase) >= 0) continue;
+      delete buildErrorStates[phase];
+      dropped = true;
+    }
+    if (dropped && !systemPage) showBuildRecovered({});
+    return dropped;
+  }
+
+  function showBuildRecovered(msg){
     if (hasBuildErrors()) {
       renderBuildErrorOverlay();
       return;
@@ -332,6 +463,21 @@ export const HMR_CLIENT_SCRIPT = `(function(){
   }
 
   function refreshRsc(msg){
+    var receivedAt = Date.now();
+    var refresh = function(){ doRefreshRsc(msg, receivedAt); };
+    var settle = function(){
+      return self.__akan && typeof self.__akan.whenSettled === "function" ? self.__akan.whenSettled() : null;
+    };
+    var booting = self.__AKAN_SSR_BOOT__;
+    var settled = booting ? Promise.resolve(booting).then(settle, function(){ return null; }) : settle();
+    if (!settled) {
+      refresh();
+      return;
+    }
+    settled.then(refresh, refresh);
+  }
+
+  function doRefreshRsc(msg, receivedAt){
     var started = performance.now();
     var overlayToken = beginHmrOverlay("Refreshing page...");
     try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}
@@ -343,6 +489,7 @@ export const HMR_CLIENT_SCRIPT = `(function(){
     }
     Promise.resolve(self.__AKAN_RSC_REFRESH__({ buildId: msg.buildId })).then(function(){
       lastBuildId = msg.buildId;
+      recordTrace("rsc-refresh", msg, receivedAt, Date.now());
       endHmrOverlay(overlayToken);
       console.debug && console.debug("[akan-hmr] RSC refreshed", {
         buildId: msg.buildId,
@@ -379,75 +526,6 @@ export const HMR_CLIENT_SCRIPT = `(function(){
     return refreshRuntimePromise;
   }
 
-  function refreshClient(msg){
-    refreshQueue = refreshQueue.then(function(){ return doRefreshClient(msg); }, function(){ return doRefreshClient(msg); });
-  }
-
-  function setHmrPhase(phase){
-    self.__AKAN_HMR_PHASE__ = phase;
-  }
-
-  function doRefreshClient(msg){
-    var started = performance.now();
-    var metadataAt = started;
-    var importAt = started;
-    var refreshAt = started;
-    var overlayToken = beginHmrOverlay("Updating...");
-    var fallbackToRsc = false;
-    return ensureRefreshRuntime().then(function(runtime){
-      setHmrOverlayLabel(overlayToken, "Fetching update...");
-      var endpoint = new URL("/_akan/hmr/client-refresh", location.origin);
-      endpoint.searchParams.set("url", location.href);
-      if (msg.buildId != null) endpoint.searchParams.set("buildId", String(msg.buildId));
-      return fetch(endpoint, { credentials: "same-origin", cache: "no-store" })
-        .then(function(res){
-          if (!res.ok) throw new Error("client-refresh metadata failed " + res.status + " " + res.statusText);
-          return res.json();
-        })
-        .then(function(info){
-          metadataAt = performance.now();
-          var chunks = Array.isArray(info.chunks) ? info.chunks : [];
-          if (chunks.length === 0) throw new Error("no client chunks returned");
-          setHmrPhase("refresh-import");
-          setHmrOverlayLabel(overlayToken, "Importing update...");
-          return Promise.all(chunks.map(function(chunk){ return import(chunk); })).then(function(){
-            importAt = performance.now();
-            setHmrPhase("react-refresh");
-            setHmrOverlayLabel(overlayToken, "Applying update...");
-            try {
-              runtime.performReactRefresh();
-            } finally {
-              setHmrPhase(null);
-            }
-            refreshAt = performance.now();
-            lastBuildId = msg.buildId;
-            console.debug && console.debug("[akan-hmr] React Fast Refresh applied", {
-              buildId: msg.buildId,
-              generation: msg.generation,
-              chunks: chunks.length,
-              routeIds: info.routeIds || msg.routeIds,
-              changedFiles: msg.changedFiles && msg.changedFiles.length,
-              metadataMs: Math.round(metadataAt - started),
-              importMs: Math.round(importAt - metadataAt),
-              refreshMs: Math.round(refreshAt - importAt),
-              durationMs: Math.round(refreshAt - started)
-            });
-            endHmrOverlay(overlayToken);
-          }, function(err){
-            setHmrPhase(null);
-            throw err;
-          });
-        });
-    }).catch(function(err){
-      console.warn("[akan-hmr] React Fast Refresh failed, falling back to RSC refresh", err);
-      fallbackToRsc = true;
-      endHmrOverlay(overlayToken);
-      refreshRsc(msg);
-    }).finally(function(){
-      if (!fallbackToRsc) endHmrOverlay(overlayToken);
-    });
-  }
-
   function swapCss(href){
     var overlayToken = beginHmrOverlay("Updating styles...");
     var link = document.createElement("link");

package/server/hmr/csrDevManifest.ts

@@ -0,0 +1,42 @@
+export const CSR_DEV_DIRNAME = "csr-dev";
+export const CSR_DEV_ROUTE_PREFIX = "/_akan/csr-dev/";
+export const CSR_DEV_APP_FILE = "app.js";
+export const CSR_DEV_MANIFEST_FILE = "manifest.json";
+/** Present only while the resident builder patches: a builder that dies holding it takes the patcher off. */
+export const CSR_DEV_PATCHING_MARKER = ".patching";
+/** Patches kept on disk behind the newest, and as many as a reconnecting tab catches up on before it reloads instead. */
+export const CSR_DEV_KEPT_PATCHES = 40;
+
+export const SSR_DEV_DIRNAME = "ssr-dev";
+export const SSR_DEV_ROUTE_PREFIX = "/_akan/ssr-dev/";
+/** The one chunk every SSR registry row names: loading it boots the registry in the tab. */
+export const SSR_DEV_CHUNK = "ssr-dev";
+/** Marks a row id as a registry module, so the dev shim tells it from the runtime rows that stay chunk URLs. */
+export const SSR_DEV_ID_PREFIX = "ssr-dev:";
+
+export type DevCsrMode = "registry" | "artifact";
+
+export interface CsrDevManifest {
+  version: 1;
+  generation: number;
+  /** The generation `app.js` holds; a patch is announced before `app.js` catches up, so it may trail `generation`. */
+  appGeneration?: number;
+  vendorFile: string;
+  entries: Record<string, string>;
+  /** When the registry was last built whole: a tab from an earlier registry must reload, whatever its generation. */
+  epoch?: number;
+}
+
+export const appGenerationOf = (manifest: CsrDevManifest): number => manifest.appGeneration ?? manifest.generation;
+
+/** Where each module's generated code starts in a combined file (`app.js`, a patch), for its source map. */
+export interface CsrDevLayout {
+  lineCount: number;
+  modules: [id: string, line: number][];
+}
+
+export const csrDevModuleFile = (id: string, extension: ".js" | ".js.map") =>
+  `modules/${Bun.hash(id).toString(36)}${extension}`;
+
+export const resolveDevCsrMode = (env: Record<string, string | undefined> = process.env): DevCsrMode =>
+  env.AKAN_DEV_CSR === "artifact" ? "artifact" : "registry";