akanjs 3.0.0-beta.24 → 3.0.0-beta.26

package/server/webRouter.ts

@@ -19,6 +19,7 @@ import {
   RouteClientCache,
   type RouteSeedIndex,
   RouteSeedIndexStore,
+  type RoutesManifest,
   RoutesManifestStore,
 } from "./artifact";
 import {
@@ -36,9 +37,10 @@ import {
 } from "./cachePolicy";
 import { encodedFileResponse } from "./contentEncoding";
 import { HMR_CLIENT_SCRIPT } from "./hmr/clientScript";
-import { CSR_DEV_ROUTE_PREFIX, resolveDevCsrMode } from "./hmr/csrDevManifest";
+import { CSR_DEV_ROUTE_PREFIX, resolveDevCsrMode, SSR_DEV_DIRNAME, SSR_DEV_ROUTE_PREFIX } from "./hmr/csrDevManifest";
 import { CsrDevShell } from "./hmr/csrDevShell";
 import { DevHmrController } from "./hmr/devHmrController";
+import { SsrDevShim } from "./hmr/ssrDevShim";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub";
 import { ImageOptimizer } from "./imageOptimizer";
 import { normalizeHost, resolveArtifactDir, warnIgnoredSubRouteBasePaths } from "./proxy/hostBasePathWebProxy";
@@ -250,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 {
@@ -272,6 +276,8 @@ export class WebRouter {
   #routeCache: RouteClientCache;
   #devHmr: DevHmrController | null = null;
   #csrDevShell: CsrDevShell | null = null;
+  /** Dev only: SSR pages load their client code from the dev module registry it serves. */
+  #ssrDevShell: CsrDevShell | null = null;
   #csrArmed = false;
   #csrOnDemandBuild: Promise<unknown> | null = null;
   readonly #requestStats = {
@@ -297,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)
@@ -317,6 +324,7 @@ export class WebRouter {
       cssBytesByUrl,
     };
     this.#seedIndex = seedIndex;
+    this.#prebuilt = prebuilt;
     if (this.#prodMode) {
       this.#builderRpc = null;
       this.#routeCache = new RouteClientCache({
@@ -333,25 +341,21 @@ export class WebRouter {
         rsc: this.#rsc,
         seedIndex: this.#seedIndex,
         upgradeHmrWs,
+        pagesBundlePath: this.#artifact.pagesBundlePath,
       });
       this.#builderRpc = this.#devHmr.builderRpc;
       this.#routeCache = this.#devHmr.routeCache;
       this.#hub = this.#devHmr.hub;
       if (resolveDevCsrMode() === "registry") this.#csrDevShell = new CsrDevShell(this.#artifactDir);
+      this.#ssrDevShell = new CsrDevShell(this.#artifactDir, {
+        dirName: SSR_DEV_DIRNAME,
+        routePrefix: SSR_DEV_ROUTE_PREFIX,
+      });
     }
   }
 
   async initializeRoute() {
-    const prebuilt = this.#prodMode ? await RoutesManifestStore.read(this.#artifactDir) : null;
-    if (prebuilt) {
-      this.#routeCache.seed(prebuilt);
-      await this.#rsc.reload({
-        clientManifest: this.#mergeRuntimeManifest().clientManifest,
-        cssAssets: this.renderState.cssAssets,
-        
-        buildId: this.#artifact.pagesBundleBuildId,
-      });
-    }
+    if (this.#prebuilt) this.#routeCache.seed(this.#prebuilt);
 
     const clientServePrefix = `/_akan/client`;
     const clientOutputDir = `${this.#artifactDir}/client`;
@@ -390,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
               ? {
@@ -402,6 +406,14 @@ export class WebRouter {
               : {}),
           }
         : {}),
+      ...(this.#ssrDevShell
+        ? {
+            [`${SSR_DEV_ROUTE_PREFIX}*`]: async (req: Request) => {
+              this.#requestStats.staticAsset += 1;
+              return (await this.#ssrDevShell?.serve(req)) ?? new Response("Not Found", { status: 404 });
+            },
+          }
+        : {}),
       [`${clientServePrefix}/*`]: async (req) => {
         this.#requestStats.staticAsset += 1;
         const url = new URL(req.url);
@@ -453,8 +465,6 @@ export class WebRouter {
         ? {
             "/_akan/hmr": (req: Request) =>
               this.#devHmr?.handleWs(req) ?? new Response("HMR unavailable", { status: 404 }),
-            "/_akan/hmr/client-refresh": (req: Request) =>
-              this.#devHmr?.handleClientRefresh(req) ?? new Response("HMR unavailable", { status: 404 }),
           }
         : {}),
       "/__rsc": async (req) => {
@@ -535,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;
@@ -594,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 });
           }
@@ -612,6 +622,9 @@ export class WebRouter {
             rscResult.trace?.routeState
               ? `self.__AKAN_RSC_INITIAL_STATE__=${JSON.stringify(rscResult.trace.routeState)};`
               : "",
+            this.#ssrDevShell
+              ? SsrDevShim.script(await this.#ssrDevShell.readManifest(), Object.keys(this.#artifact.vendorMap))
+              : "",
             !this.#prodMode ? HMR_CLIENT_SCRIPT : "",
           ]
             .filter(Boolean)
@@ -632,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");
@@ -704,6 +717,12 @@ export class WebRouter {
     };
     return { renderEnvRoutes, hmrHub: this.#hub, builderRpc: this.#builderRpc };
   }
+  refreshHmrState(): void {
+    this.#devHmr?.refreshRegistryState();
+  }
+  hmrBuildErrors(): { phase: string }[] {
+    return this.#devHmr?.buildErrorMessages() ?? [];
+  }
   dispose() {
     this.#devHmr?.dispose();
     this.#devHmr = null;
@@ -793,6 +812,11 @@ export class WebRouter {
   }
 
   #getHtmlCacheEntry(req: Request, url: URL): { entry: RouteCacheEntry | null; reason?: string } {
+
+    if (this.#ssrDevShell) {
+      this.#htmlCacheBypass += 1;
+      return { entry: null, reason: "dev-registry" };
+    }
     const decision = resolvePublicRouteCacheEntryDecision({
       request: req,
       url,
@@ -893,6 +917,7 @@ export class WebRouter {
       stylesheetHref: this.#getStylesheetHref(req, new URL(req.url).pathname),
       showDetails: !this.#prodMode,
       error: err,
+      ...(this.#prodMode ? {} : { script: `self.__AKAN_HMR_SYSTEM_PAGE__=true;${HMR_CLIENT_SCRIPT}` }),
     });
   }
 
@@ -942,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 {
@@ -965,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);
@@ -1015,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)}`);
@@ -1030,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/builderRpc.d.ts

@@ -1,4 +1,4 @@
-import type { BuildRouteClientResult, CsrUpdatedPayload, CssPayload, DevBuildStatus, PagesBundlePayload } from "./ipcTypes.d.ts";
+import type { BuildRouteClientResult, CsrUpdatedPayload, CssPayload, DevBuildStatus, PagesBundlePayload, SsrUpdatedPayload } from "./ipcTypes.d.ts";
 export interface BuilderRpcEventHandlers {
     /** A watcher batch changed files: clear the route cache and broadcast a dev reload. */
     onInvalidate?: (event: {
@@ -8,8 +8,9 @@ export interface BuilderRpcEventHandlers {
     }) => 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;
 }
 /** One per backend process: subscribes to the IPC channel on construction and unsubscribes on `dispose()`. */

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

@@ -18,6 +18,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. */
 export type BuilderStateReason = "builder-recycle";
@@ -41,13 +43,15 @@ export interface DevChangePlan {
     actions: DevChangeAction[];
     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;
     phase: BuildPhase;
     ok: boolean;
     files: string[];
     message?: string;
+    /** The route a route build's status speaks for. */
+    scope?: string;
 }
 export type BuilderReq = {
     type: "build-route";
@@ -90,18 +94,33 @@ 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;
@@ -113,6 +132,23 @@ 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 = {
     type: "builder-ready";
@@ -135,12 +171,19 @@ export type BuilderEvent = {
 } | {
     type: "csr-updated";
     data: CsrUpdatedPayload;
+} | {
+    type: "ssr-updated";
+    data: SsrUpdatedPayload;
 } | {
     type: "build-status";
     data: DevBuildStatus;
 } | {
     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;
 export interface ClientManifestEntry {
@@ -157,4 +200,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/types/server/artifact/routeClientCache.d.ts

@@ -26,6 +26,10 @@ interface RouteClientCacheOptions {
 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;
 }
 export declare class RouteClientCache {
     #private;
@@ -36,8 +40,11 @@ export declare class RouteClientCache {
     seed(manifest: RoutesManifest): void;
     ensure(routeId: string, seeds: string[]): Promise<MergedManifest>;
     snapshot(): MergedManifest;
-    invalidate(predicate: (routeId: string) => boolean): string[];
-    invalidateClientEntries({ routePredicate, staleEntries }: InvalidateClientEntriesOptions): string[];
+    invalidate(predicate: (routeId: string) => boolean, { files, batch }?: {
+        files?: Iterable<string>;
+        batch?: number;
+    }): string[];
+    invalidateClientEntries({ routePredicate, staleEntries, files, batch, }: InvalidateClientEntriesOptions): string[];
     clear(): string[];
 }
 export {};

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

@@ -2,13 +2,28 @@ export declare const CSR_DEV_DIRNAME = "csr-dev";
 export declare const CSR_DEV_ROUTE_PREFIX = "/_akan/csr-dev/";
 export declare const CSR_DEV_APP_FILE = "app.js";
 export declare 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 declare 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 declare const CSR_DEV_KEPT_PATCHES = 40;
+export declare const SSR_DEV_DIRNAME = "ssr-dev";
+export declare 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 declare 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 declare 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 declare const appGenerationOf: (manifest: CsrDevManifest) => number;
 /** Where each module's generated code starts in a combined file (`app.js`, a patch), for its source map. */
 export interface CsrDevLayout {
     lineCount: number;

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

@@ -26,17 +26,43 @@ export interface CsrDevRuntimeApi {
         generation: number;
         refresh: string;
     }): void;
+    /** No entry to run: an SSR page requires the modules its RSC payload names, after the bootstrap has run. */
+    startLibrary(options: LibraryStart): void;
+    /** Registers a module the page already loaded outside the registry (an import map vendor). */
+    provide(id: string, namespace: unknown): void;
+    require(id: string): unknown;
+    has(id: string): boolean;
+    /** Settles once a patch defines `id`: the RSC payload can name a module whose patch is still on its way. */
+    whenDefined(id: string): Promise<void>;
+    /** Settles once every update handed to `hot` so far is applied, its accept callbacks included. */
+    whenSettled(): Promise<void>;
     update(generation: number, factories: Record<string, CsrModuleFactory>): void;
     accept(ownerId: string, deps: string[], callback: CsrAcceptCallback): void;
     hot(message: CsrUpdateMessage): void;
+    /** Loads every patch after the newest generation handed to `hot` up to `generation`, from `<prefix>patch-<n>.js`. */
+    catchUp(generation: number, prefix: string): void;
     toESM(mod: unknown, isNodeMode?: number): unknown;
     reExport(target: object, mod: unknown, secondTarget?: object): object | undefined;
+    /** `target` is the newest generation handed to `hot`, applied or still loading. */
     inspect(): {
         generation: number;
+        target: number;
+        started: boolean;
+        failed: boolean;
         executed: string[];
         modules: number;
+        /** What the library app.js was built with; undefined for a CSR page. */
+        vendorFile?: string;
+        epoch?: number;
     };
 }
+export interface LibraryStart {
+    generation: number;
+    refresh: string;
+    bootstrap: string;
+    vendorFile?: string;
+    epoch?: number;
+}
 interface CsrScriptElement {
     src: string;
     dataset: Record<string, string | undefined>;
@@ -49,6 +75,8 @@ export interface CsrDevRuntimeHost {
     __AKAN_CSR_LAST_UPDATE__?: {
         generation: number;
         executed: string[];
+        appliedAt?: number;
+        refreshedAt?: number;
     };
     document: {
         currentScript: unknown;
@@ -63,6 +91,12 @@ export interface CsrDevRuntimeHost {
     console: {
         warn(...args: unknown[]): void;
     };
+    fetch?(url: string, init: {
+        method: string;
+        cache: "no-store";
+    }): Promise<{
+        ok: boolean;
+    }>;
     setTimeout(callback: () => void, ms: number): unknown;
     clearTimeout(handle: unknown): void;
 }

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

@@ -5,9 +5,17 @@ export interface CsrDevShellRenderOptions {
     title: string;
     cssHref: string | null;
 }
+export interface CsrDevShellOptions {
+    /** The registry this serves: the CSR one by default, `ssr-dev` for the client code of SSR pages. */
+    dirName?: string;
+    routePrefix?: string;
+    appWaitMs?: number;
+    appPollMs?: number;
+    bootWaitMs?: number;
+}
 export declare class CsrDevShell {
     #private;
-    constructor(artifactDir: string);
+    constructor(artifactDir: string, { dirName, routePrefix, appWaitMs, appPollMs, bootWaitMs, }?: CsrDevShellOptions);
     readManifest(): Promise<CsrDevManifest | null>;
     render({ basePath, lang, title, cssHref }: CsrDevShellRenderOptions): Promise<string | null>;
     serve(req: Request): Promise<Response>;

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

@@ -14,17 +14,20 @@ export interface DevHmrControllerOptions {
     rsc: RscWorker;
     seedIndex: RouteSeedIndex;
     upgradeHmrWs: (req: Request, data: HmrWsData) => boolean;
+    /** The pages bundle the RSC worker booted with: the base build's, however many pages builds came after it. */
+    pagesBundlePath?: string;
 }
 export declare class DevHmrController {
     #private;
     readonly routeCache: RouteClientCache;
-    constructor({ artifactDir, renderState, rsc, seedIndex, upgradeHmrWs }: DevHmrControllerOptions);
+    constructor({ artifactDir, renderState, rsc, seedIndex, upgradeHmrWs, pagesBundlePath }: DevHmrControllerOptions);
+    refreshRegistryState(): void;
+    /** The phases failing now, for a socket that connects after their status went out (a page opened after a failed boot). */
+    buildErrorMessages(): Extract<HmrMessage, {
+        type: "build-status";
+    }>[];
     get hub(): HmrWsHub;
     get builderRpc(): BuilderRpc;
     dispose(): void;
     handleWs(req: Request): Response | undefined;
-    handleClientRefresh(req: Request): Promise<Response>;
-    ensureRoute(url: URL): Promise<import("..").MergedManifest>;
-    routeIdsForPath(pathname: string): string[] | undefined;
-    static clientChunkUrls(clientManifest: ClientManifest): string[];
 }

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

@@ -0,0 +1,7 @@
+import { type CsrDevManifest } from "./csrDevManifest.d.ts";
+export declare class SsrDevShim {
+    #private;
+    static readonly runtimeUrl: string;
+    /** `vendors` are the import map's specifiers: the registry requires them as `vendor:<specifier>`, never compiles them. */
+    static script(manifest: CsrDevManifest | null, vendors: string[]): string;
+}

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

@@ -0,0 +1,23 @@
+import type { SsrUpdatedPayload } from "../artifact.d.ts";
+import type { HmrMessage } from "./wsHub.d.ts";
+export type SsrUpdateMessage = Extract<HmrMessage, {
+    type: "ssr-update";
+}>;
+export declare class SsrUpdateQueue {
+    #private;
+    constructor(send: (message: SsrUpdateMessage) => void, { maxHoldMs }?: {
+        maxHoldMs?: number;
+    });
+    get size(): number;
+    push(update: SsrUpdatedPayload): void;
+    /**
+     * The pages batch of `generation` finished or failed: sends what it covers and everything queued behind that, and
+     * says whether a reload went out (the tabs then need no RSC refresh).
+     */
+    release(generation: number | undefined): {
+        released: number;
+        reload: boolean;
+    };
+    /** Drops what the pages batch of `generation` covers, or everything without one: the tabs are about to reload. */
+    clear(generation?: number): void;
+}

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

@@ -1,8 +1,9 @@
-import type { BuildPhase } from "../artifact.d.ts";
+import type { BuildPhase, HmrTrace } from "../artifact.d.ts";
 export type ChangeKind = "code" | "css" | "config" | "ignore";
 export interface ChangeBatch {
     files: string[];
     kinds: Set<Exclude<ChangeKind, "ignore">>;
+    trace?: HmrTrace;
 }
 export type HmrClientKind = "ssr" | "csr";
 export interface HmrWsData {
@@ -18,6 +19,10 @@ export type HmrMessage = {
         cssRelPath: string;
     }>;
     csrGeneration?: number;
+    ssrGeneration?: number;
+    ssrEpoch?: number;
+    /** The phases failing now, each sent right after: a tab drops an error it holds for any other. */
+    failingPhases?: string[];
 } | {
     type: "reload";
     buildId: number;
@@ -28,18 +33,22 @@ export type HmrMessage = {
     changedIds?: string[];
     reload?: boolean;
     reason?: string;
+    trace?: HmrTrace;
 } | {
-    type: "rsc-refresh";
-    buildId: number;
-    generation?: number;
-    changedFiles?: string[];
-    routeIds?: string[];
+    type: "ssr-update";
+    generation: number;
+    url?: string;
+    changedIds?: string[];
+    reload?: boolean;
+    reason?: string;
+    trace?: HmrTrace;
 } | {
-    type: "client-refresh";
+    type: "rsc-refresh";
     buildId: number;
     generation?: number;
     changedFiles?: string[];
     routeIds?: string[];
+    trace?: HmrTrace;
 } | {
     type: "css-update";
     cssAssets?: Record<string, {

package/types/server/routing/apiRouter.d.ts

@@ -12,7 +12,15 @@ export interface HmrStateSource {
             cssRelPath: string;
         }>;
         csrGeneration?: number;
+        ssrGeneration?: number;
+        ssrEpoch?: number;
     };
+    /** Called before each hello: brings what the state says about the dev registries up to what is on disk. */
+    refresh?: () => void;
+    /** Sent right after hello: the build statuses failing now, which the socket connected too late to hear. */
+    errors?: () => {
+        phase: string;
+    }[];
 }
 export type NonNullHttpRoutes = NonNullable<HttpRoutes>;
 export interface ApiRouteInputs {