@akanjs/devkit 2.4.1-rc.2 → 2.4.1-rc.4

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -7,14 +7,10 @@ import {
   AutoImportSync,
   type ChangeBatch,
   type ClientEntryDiscovery,
-  CsrArtifactBuilder,
-  type CssCompiler,
   DevChangePlanner,
   DevGeneratedIndexSync,
-  FontOptimizer,
   GraphClientEntryDiscovery,
   HmrWatcher,
-  PagesBundleBuilder,
   RouteClientBuilder,
   SsrBaseArtifactBuilder,
   WatchRootResolver,
@@ -23,56 +19,61 @@ import { Logger } from "akanjs/common";
 import type {
   BaseBuildArtifact,
   BuilderCsrReq,
-  BuilderCsrRes,
   BuilderMessage,
   BuilderReq,
   BuilderRes,
   BuildPhase,
   BuildRouteResultPayload,
 } from "akanjs/server";
+import type { BuildBatchNeed, BuildBatchRequest, BuildBatchResult, OptimizedFonts } from "./buildBatchProtocol";
+import { BuildBatchRunner } from "./buildBatchRunner";
+import { BuilderReply } from "./builderReply";
 import { prepareDevWatchBatch } from "./devWatchBatch";
 
 interface IncrementalBuilderOptions {
   app: App;
   artifact: BaseBuildArtifact;
   watch: boolean;
-  cssCompiler: CssCompiler;
-  optimizedFonts: Awaited<ReturnType<FontOptimizer["optimize"]>>;
+  optimizedFonts: OptimizedFonts;
   discovery: ClientEntryDiscovery;
   initialGeneration?: number;
 }
 
-type IncrementalBuilderBootDeps = Pick<
-  IncrementalBuilderOptions,
-  "artifact" | "cssCompiler" | "optimizedFonts" | "discovery"
->;
+type IncrementalBuilderBootDeps = Pick<IncrementalBuilderOptions, "artifact" | "optimizedFonts" | "discovery">;
 
 class IncrementalBuilder {
   #logger = new Logger("IncrementalBuilder");
   #app: App;
   #artifact: BaseBuildArtifact;
   #watch: boolean;
-  #cssCompiler: CssCompiler;
-  #optimizedFonts: Awaited<ReturnType<FontOptimizer["optimize"]>>;
+  /** Kept by value, not as a live `FontOptimizer`: it has to travel to each disposable build worker. */
+  #optimizedFonts: OptimizedFonts;
   #discovery: ClientEntryDiscovery;
+  #batchRunner: BuildBatchRunner;
   #changePlanner: DevChangePlanner;
   #generatedIndexSync: DevGeneratedIndexSync;
   #autoImportSync: AutoImportSync;
+  #watcher: HmrWatcher | null = null;
   #generation = 0;
   #csrActive = IncrementalBuilder.#csrArmedByEnv();
   #workQueue: Promise<void> = Promise.resolve();
+  #inFlight = 0;
+  #workCount = 0;
+  #shuttingDown = false;
   #cssRebuildQueue: Promise<void> = Promise.resolve();
   #cssRebuildTimer: ReturnType<typeof setTimeout> | null = null;
-  #pendingCssRebuild: { artifactDir: string; refresh: boolean; generation?: number; changedFiles?: string[] } | null =
-    null;
+  #pendingCssRebuild: { generation?: number; changedFiles?: string[] } | null = null;
   constructor(options: IncrementalBuilderOptions) {
     this.#app = options.app;
     this.#artifact = options.artifact;
     this.#watch = options.watch;
-    this.#cssCompiler = options.cssCompiler;
     this.#optimizedFonts = options.optimizedFonts;
     this.#discovery = options.discovery;
     this.#generation = options.initialGeneration ?? 0;
+    this.#batchRunner = new BuildBatchRunner({
+      workspaceRoot: options.app.workspace.workspaceRoot,
+      cwd: options.app.cwdPath,
+    });
     this.#changePlanner = new DevChangePlanner({ workspaceRoot: options.app.workspace.workspaceRoot });
     this.#generatedIndexSync = new DevGeneratedIndexSync({ workspaceRoot: options.app.workspace.workspaceRoot });
     this.#autoImportSync = new AutoImportSync({ workspaceRoot: options.app.workspace.workspaceRoot });
@@ -82,8 +83,14 @@ class IncrementalBuilder {
     return `${this.#app.cwdPath}/.akan/artifact`;
   }
 
-  async handleBuildRoute(msg: BuilderReq): Promise<BuilderRes> {
-    return this.#enqueueWork(`build-route:${msg.routeId}`, async () => this.#handleBuildRoute(msg));
+  /**
+   * Build a route and answer it. The reply is part of the work item on purpose: `shutdown` drains the
+   * work queue before exiting, so folding the flush in here is what makes "drained" mean "answered".
+   */
+  async handleBuildRoute(msg: BuilderReq): Promise<void> {
+    await this.#enqueueWork(`build-route:${msg.routeId}`, async () =>
+      BuilderReply.send(await this.#handleBuildRoute(msg)),
+    );
   }
 
   async #handleBuildRoute(msg: BuilderReq): Promise<BuilderRes> {
@@ -138,14 +145,63 @@ class IncrementalBuilder {
   }
   async #enqueueWork<T>(label: string, fn: () => Promise<T>): Promise<T> {
     const started = Date.now();
+    this.#inFlight += 1;
     const run = this.#workQueue.then(fn, fn);
     this.#workQueue = run.then(() => undefined).catch(() => undefined);
     try {
       return await run;
     } finally {
+      this.#inFlight -= 1;
+      this.#workCount += 1;
       this.#logger.verbose(`[work-queue] ${label} finished in ${Date.now() - started}ms`);
+      this.#reportMetrics();
     }
   }
+
+  /** No queued work and no debounced css rebuild, so nothing is lost if the process exits now. */
+  get #idle(): boolean {
+    return this.#inFlight === 0 && this.#cssRebuildTimer === null;
+  }
+
+  /**
+   * Reported only when the builder is idle. The host's only lever against the bundler arenas
+   * `Bun.build` retains is to recycle this process, and a recycle decided while work is queued would
+   * either truncate that work or race the shutdown drain — so a busy builder simply says nothing.
+   */
+  #reportMetrics(): void {
+    if (!this.#idle || this.#shuttingDown) return;
+    process.send?.({
+      type: "builder-metrics",
+      data: { rssBytes: process.memoryUsage.rss(), generation: this.#generation, workCount: this.#workCount },
+    });
+  }
+
+  /**
+   * Finish queued work, then exit so the OS reclaims the bundler arenas. The host restarts a
+   * replacement; build requests that arrive during the drain are refused with the same retry error
+   * the backend already handles for any other builder restart.
+   */
+  async shutdown(reason: string): Promise<void> {
+    if (this.#shuttingDown) return;
+    this.#shuttingDown = true;
+    const started = Date.now();
+    this.#logger.info(`shutdown requested (${reason}); draining ${this.#inFlight} work item(s)`);
+    if (this.#cssRebuildTimer) {
+      // Only reachable if a css batch landed between the idle report and this request: the fresh
+      // boot build recompiles css from scratch anyway, so dropping the debounce loses nothing.
+      clearTimeout(this.#cssRebuildTimer);
+      this.#cssRebuildTimer = null;
+      this.#pendingCssRebuild = null;
+    }
+    await this.#workQueue.catch(() => undefined);
+    await this.#cssRebuildQueue.catch(() => undefined);
+    this.#logger.info(`drained in ${Date.now() - started}ms; exiting for recycle`);
+    process.exit(0);
+  }
+
+  get shuttingDown(): boolean {
+    return this.#shuttingDown;
+  }
   batchTouchesPagesTree(appDir: string, batch: ChangeBatch): boolean {
     const absAppDir = path.resolve(appDir);
     for (const f of batch.files) {
@@ -167,75 +223,23 @@ class IncrementalBuilder {
     }
     return false;
   }
-  async rebuildCssArtifact(
-    artifactDir: string,
-    { refresh, generation, changedFiles }: { refresh: boolean; generation?: number; changedFiles?: string[] },
-  ) {
-    const cssStarted = Date.now();
-    const cssByBasePathStarted = Date.now();
-    const cssByBasePath = await this.#cssCompiler.getCssByBasePath({ refresh });
-    this.#logger.verbose(`css-get-by-base-path ok (${Date.now() - cssByBasePathStarted}ms)`);
-    const fontStarted = Date.now();
-    const optimizedFonts = await this.#getOptimizedFonts(changedFiles ?? []);
-    this.#logger.verbose(`font-assets ready (${Date.now() - fontStarted}ms)`);
-    const cssAssetEntries: Array<[string, { cssUrl: string; cssRelPath: string }]> = [];
-    const cssBase64ByUrl: Record<string, string> = {};
-    await Promise.all(
-      Object.entries(cssByBasePath).flatMap(([basePath, baseCssText]) => {
-        const cssText = [baseCssText, optimizedFonts.css].filter(Boolean).join("\n");
-        if (!cssText) return [];
-        return [
-          (async () => {
-            const cssAssetName = basePath || "root";
-            const cssHash = Bun.hash(`${basePath}\n${cssText}`).toString(36);
-            const cssRelPath = `styles/${cssAssetName}-${cssHash}.css`;
-            const cssUrl = `/_akan/styles/${cssAssetName}-${cssHash}.css`;
-            await Bun.write(path.join(artifactDir, cssRelPath), cssText);
-            cssAssetEntries.push([basePath, { cssUrl, cssRelPath }]);
-            cssBase64ByUrl[cssUrl] = Buffer.from(new TextEncoder().encode(cssText)).toString("base64");
-          })(),
-        ];
-      }),
-    );
-    const cssAssets = Object.fromEntries(cssAssetEntries);
-    if (JSON.stringify(this.#artifact.cssAssets ?? {}) === JSON.stringify(cssAssets)) {
-      this.#logger.verbose("css-rebuild unchanged assets; broadcast skipped");
-      return;
-    }
-    this.#artifact = { ...this.#artifact, cssAssets };
-    this.#logger.verbose(`css-compile ok assets=${Object.keys(cssAssets).length} (${Date.now() - cssStarted}ms)`);
-    process.send?.({
-      type: "css-updated",
-      data: {
-        cssAssets,
-        cssBase64ByUrl,
-        generation,
-        changedFiles,
-      },
-    });
-  }
-
-  scheduleCssRebuild(
-    artifactDir: string,
-    { refresh, generation, changedFiles }: { refresh: boolean; generation?: number; changedFiles?: string[] },
-  ) {
-    this.#pendingCssRebuild = { artifactDir, refresh, generation, changedFiles };
+  /** Debounced css-only rebuild; the compile itself runs in a disposable worker like every other build. */
+  scheduleCssRebuild({ generation, changedFiles }: { generation?: number; changedFiles?: string[] }) {
+    this.#pendingCssRebuild = { generation, changedFiles };
     if (this.#cssRebuildTimer) clearTimeout(this.#cssRebuildTimer);
     this.#cssRebuildTimer = setTimeout(() => {
       this.#cssRebuildTimer = null;
       const next = this.#pendingCssRebuild;
       this.#pendingCssRebuild = null;
       if (!next) return;
+      this.#inFlight += 1;
       this.#cssRebuildQueue = this.#cssRebuildQueue
         .then(async () => {
-          const started = Date.now();
-          await this.rebuildCssArtifact(next.artifactDir, {
-            refresh: next.refresh,
-            generation: next.generation,
-            changedFiles: next.changedFiles,
+          await this.#runBatch({
+            generation: next.generation ?? this.#generation,
+            needs: ["css"],
+            changedFiles: next.changedFiles ?? [],
           });
-          this.#sendBuildStatus("css", { generation: next.generation, ok: true, files: next.changedFiles });
-          this.#logger.verbose(`css-rebuild checked (${Date.now() - started}ms)`);
         })
         .catch((err) => {
           const message = err instanceof Error ? err.message : String(err);
@@ -246,29 +250,13 @@ class IncrementalBuilder {
             files: next.changedFiles,
             message,
           });
+        })
+        .finally(() => {
+          this.#inFlight -= 1;
+          this.#reportMetrics();
         });
     }, 150);
   }
-
-  async #getOptimizedFonts(changedFiles: string[]) {
-    if (!this.#shouldReoptimizeFonts(changedFiles)) {
-      this.#logger.verbose(`font-optimize cached files=${this.#optimizedFonts.files.length}`);
-      return this.#optimizedFonts;
-    }
-    const started = Date.now();
-    this.#optimizedFonts = await new FontOptimizer(this.#app, "start").optimize();
-    this.#logger.verbose(`font-optimize ok files=${this.#optimizedFonts.files.length} (${Date.now() - started}ms)`);
-    return this.#optimizedFonts;
-  }
-
-  #shouldReoptimizeFonts(changedFiles: string[]) {
-    if (changedFiles.length === 0) return false;
-    return changedFiles.some((file) => {
-      const normalized = path.resolve(file);
-      if (/\.(woff2?|ttf|otf)$/i.test(normalized)) return true;
-      return this.#optimizedFonts.files.some((fontFile) => path.resolve(fontFile) === normalized);
-    });
-  }
   async installWatcher() {
     const [appDir, artifactDir] = [`${this.#app.cwdPath}/page`, this.#artifactDir];
     const roots = await new WatchRootResolver(this.#app).resolve();
@@ -279,7 +267,8 @@ class IncrementalBuilder {
         await this.#enqueueWork("hmr-batch", async () => this.#handleWatchBatch(appDir, artifactDir, batch));
       },
     });
-    watcher.start();
+    await watcher.start();
+    this.#watcher = watcher;
     this.#logger.verbose(`watching ${roots.length} roots`);
   }
 
@@ -295,6 +284,10 @@ class IncrementalBuilder {
     if (autoImport.changedFiles.length > 0)
       this.#logger.verbose(`[auto-import] inserted imports into ${autoImport.changedFiles.length} file(s)`);
     const indexSync = await this.#generatedIndexSync.syncForBatch(batch.files);
+    //* Both passes above write source files, and this generation's build consumes what they wrote. Hand
+    //* them to the watcher so its verification scan does not read them back as a user edit and spend a
+    //* second generation rebuilding identical content.
+    await this.#watcher?.absorb([...autoImport.changedFiles, ...indexSync.changedFiles]);
     const { files, kinds, expandedBatch, event, hasSyncErrors } = prepareDevWatchBatch({
       generation,
       batch,
@@ -338,49 +331,86 @@ class IncrementalBuilder {
       this.#logger.verbose("pageKeys refresh skipped; changed page source cannot add/remove a route key");
     }
 
-    if (kinds.includes("code") && rebuildClient && this.#shouldRebuildCsr()) {
-      try {
-        const started = Date.now();
-        await new CsrArtifactBuilder(this.#app).build();
-        this.#sendBuildStatus("csr", { generation, ok: true, files });
-        this.#logger.verbose(`csr-rebundle ok (${Date.now() - started}ms)`);
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        this.#logger.error(`csr-rebundle failed: ${message}`);
-        this.#sendBuildStatus("csr", { generation, ok: false, files, message });
-      }
-    } else if (kinds.includes("code") && rebuildClient) {
-      this.#logger.verbose(
-        `csr-rebundle skipped; request /__csr or ?csr=true (or set AKAN_DEV_CSR_REBUILD=1) to enable per-save CSR rebuilds`,
-      );
+    const needs: BuildBatchNeed[] = [];
+    if (kinds.includes("code") && rebuildClient) {
+      if (this.#shouldRebuildCsr()) needs.push("csr");
+      else
+        this.#logger.verbose(
+          `csr-rebundle skipped; request /__csr or ?csr=true (or set AKAN_DEV_CSR_REBUILD=1) to enable per-save CSR rebuilds`,
+        );
+      needs.push("pages");
+      // Server-only code edits cannot introduce class names the CSS scanner would pick up; only a
+      // client rebuild or a direct stylesheet edit can change the compiled CSS. Folded into this
+      // generation's batch rather than debounced separately: the work queue already serializes
+      // generations, so by the time a second batch runs the 150ms debounce would have fired anyway,
+      // and a second worker spawn per save costs more than the coalescing ever saved.
+      needs.push("css");
     }
 
     process.send?.(event);
 
-    if (kinds.includes("code") && rebuildClient) {
-      try {
-        const started = Date.now();
-        const next = await new PagesBundleBuilder(this.#app).build();
-        process.send?.({
-          type: "pages-updated",
-          data: { bundlePath: next.bundlePath, buildId: next.buildId, generation, changedFiles: files },
-        });
-        this.#sendBuildStatus("pages", { generation, ok: true, files });
-        this.#logger.verbose(`pages-rebundle ok buildId=${next.buildId} (${Date.now() - started}ms)`);
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        this.#logger.error(`pages-rebundle failed: ${message}`);
-        this.#sendBuildStatus("pages", { generation, ok: false, files, message });
-      }
-    }
-    // Server-only code edits cannot introduce class names the CSS scanner would pick up; only a
-    // client rebuild or a direct stylesheet edit can change the compiled CSS.
-    if (kinds.includes("css") || (kinds.includes("code") && rebuildClient)) {
-      this.scheduleCssRebuild(artifactDir, { refresh: true, generation, changedFiles: files });
+    if (needs.length > 0) await this.#runBatch({ generation, needs, changedFiles: files });
+    // A css-only batch keeps its debounce: those arrive in bursts while a stylesheet is edited, and
+    // without a pages build in front of them there is nothing else to space them out.
+    else if (kinds.includes("css")) {
+      this.scheduleCssRebuild({ generation, changedFiles: files });
       this.#logger.verbose(`css-rebuild scheduled generation=${generation}`);
     }
   }
 
+  /**
+   * Run one generation of build work in a process that exits afterwards. The worker streams the
+   * messages the backend and the HMR overlay consume, which this relays untouched, so the sequence a
+   * browser observes is the same one the in-process build produced.
+   */
+  async #runBatch({
+    generation,
+    needs,
+    changedFiles,
+  }: {
+    generation: number;
+    needs: BuildBatchNeed[];
+    changedFiles: string[];
+  }): Promise<BuildBatchResult> {
+    const started = Date.now();
+    const result = await this.#batchRunner.run(await this.#batchRequest({ generation, needs, changedFiles }), (msg) =>
+      process.send?.(msg),
+    );
+    if (result.optimizedFonts) this.#optimizedFonts = result.optimizedFonts;
+    if (result.cssAssets) this.#artifact = { ...this.#artifact, cssAssets: result.cssAssets };
+    // A worker that died before reporting streamed no build-status of its own, so report one per need
+    // it was given: the generation must go red rather than look like it silently succeeded.
+    if (result.crashed) {
+      for (const need of needs)
+        this.#sendBuildStatus(need, { generation, ok: false, files: changedFiles, message: result.errors[need] });
+    }
+    if (needs.includes("css")) this.#logger.verbose(`css-rebuild checked (${Date.now() - started}ms)`);
+    return result;
+  }
+
+  async #batchRequest({
+    generation,
+    needs,
+    changedFiles,
+  }: {
+    generation: number;
+    needs: BuildBatchNeed[];
+    changedFiles: string[];
+  }): Promise<BuildBatchRequest> {
+    return {
+      appName: this.#app.name,
+      workspaceRoot: this.#app.workspace.workspaceRoot,
+      repoName: this.#app.workspace.repoName,
+      generation,
+      needs,
+      changedFiles,
+      pageKeys: await this.#app.getPageKeys(),
+      optimizedFonts: this.#optimizedFonts,
+      cssAssets: this.#artifact.cssAssets ?? null,
+      artifactDir: path.resolve(this.#artifactDir),
+    };
+  }
+
   async boot(): Promise<void> {
     if (this.#watch) await this.installWatcher();
     process.send?.({ type: "builder-ready" });
@@ -394,20 +424,47 @@ class IncrementalBuilder {
   async announceRecoveredState(changedFiles: string[]): Promise<void> {
     const generation = ++this.#generation;
     await this.#enqueueWork("boot-recovered", async () => {
-      try {
-        const next = await new PagesBundleBuilder(this.#app).build();
-        process.send?.({
-          type: "pages-updated",
-          data: { bundlePath: next.bundlePath, buildId: next.buildId, generation, changedFiles },
-        });
-        this.#sendBuildStatus("pages", { generation, ok: true, files: changedFiles, message: "Boot build recovered" });
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        this.#logger.error(`recovered pages rebundle failed: ${message}`);
-        this.#sendBuildStatus("pages", { generation, ok: false, files: changedFiles, message });
-      }
-      this.scheduleCssRebuild(this.#artifactDir, { refresh: true, generation, changedFiles });
+      await this.#runBatch({ generation, needs: ["pages", "css"], changedFiles });
+    });
+  }
+
+  /**
+   * Re-announce the state this builder just booted with, after the host recycled the previous one.
+   *
+   * The backend reads `base-artifact.json` once at boot and never re-reads it, so a pages or css hash
+   * that moved while the builder was being replaced would otherwise leave it pointing at the previous
+   * artifact until the next save. Announced from the boot artifact rather than by rebuilding: the
+   * bundles are already on disk, and spending another ~200MB of bundler arena in a process that was
+   * just recycled to reclaim memory would defeat the purpose. The host suppresses the announcement
+   * when the hashes match, which is the common case, so a clean recycle never reloads a browser.
+   */
+  async announceBootState(): Promise<void> {
+    const generation = ++this.#generation;
+    const reason = "builder-recycle" as const;
+    process.send?.({
+      type: "pages-updated",
+      data: {
+        bundlePath: this.#artifact.pagesBundlePath,
+        buildId: this.#artifact.pagesBundleBuildId,
+        generation,
+        changedFiles: [],
+        reason,
+      },
+    });
+    const cssAssets = this.#artifact.cssAssets ?? {};
+    const cssBase64ByUrl = Object.fromEntries(
+      await Promise.all(
+        Object.values(cssAssets).map(async ({ cssUrl, cssRelPath }) => [
+          cssUrl,
+          Buffer.from(await Bun.file(path.join(this.#artifactDir, cssRelPath)).arrayBuffer()).toString("base64"),
+        ]),
+      ),
+    );
+    process.send?.({
+      type: "css-updated",
+      data: { cssAssets, cssBase64ByUrl, generation, changedFiles: [], reason },
     });
+    this.#logger.verbose(`announced boot state after recycle generation=${generation}`);
   }
 
   /**
@@ -415,19 +472,23 @@ class IncrementalBuilder {
    * dev server only serves CSR through the opt-in `/__csr` and `?csr=true` routes — mobile local dev
    * points a device WebView at the latter — so nothing needs the artifact until one of them is hit.
    */
-  async handleBuildCsr(msg: BuilderCsrReq): Promise<BuilderCsrRes> {
-    return this.#enqueueWork("build-csr", async (): Promise<BuilderCsrRes> => {
+  async handleBuildCsr(msg: BuilderCsrReq): Promise<void> {
+    await this.#enqueueWork("build-csr", async (): Promise<void> => {
       const started = Date.now();
-      try {
-        await new CsrArtifactBuilder(this.#app).build();
-        this.#csrActive = true;
-        this.#logger.info(`csr-build ok on demand (${Date.now() - started}ms); rebuilding CSR on every save now`);
-        return { type: "build-csr-res", id: msg.id, ok: true };
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        this.#logger.error(`csr-build failed: ${message}`);
-        return { type: "build-csr-res", id: msg.id, ok: false, error: message };
+      // Messages are not relayed: an on-demand CSR build is a request/response, and the phase board
+      // never carried a csr status for it before. The error travels in the response below.
+      const result = await this.#batchRunner.run(
+        await this.#batchRequest({ generation: this.#generation, needs: ["csr"], changedFiles: [] }),
+      );
+      const error = result.errors.csr;
+      if (error) {
+        this.#logger.error(`csr-build failed: ${error}`);
+        await BuilderReply.send({ type: "build-csr-res", id: msg.id, ok: false, error });
+        return;
       }
+      this.#csrActive = true;
+      this.#logger.info(`csr-build ok on demand (${Date.now() - started}ms); rebuilding CSR on every save now`);
+      await BuilderReply.send({ type: "build-csr-res", id: msg.id, ok: true });
     });
   }
 
@@ -440,12 +501,28 @@ class IncrementalBuilder {
   }
 
   static async #buildBootDeps(app: App): Promise<IncrementalBuilderBootDeps> {
-    const { artifact, cssCompiler, optimizedFonts } = await new SsrBaseArtifactBuilder(app).build();
-    //* A full minified browser-target build of every page costs ~350MB of bundler arena the process
-    //* never returns, so skip it until a `/__csr` or `?csr=true` request arms it via `build-csr`.
-    if (IncrementalBuilder.#csrArmedByEnv()) await new CsrArtifactBuilder(app).build();
+    const { artifact, optimizedFonts } = await new SsrBaseArtifactBuilder(app).build();
     const discovery = await GraphClientEntryDiscovery.create(app);
-    return { artifact, cssCompiler, optimizedFonts, discovery };
+    return { artifact, optimizedFonts, discovery };
+  }
+
+  /**
+   * A session that already armed dev CSR keeps it armed across builder restarts through the env flag,
+   * so the artifact has to be rebuilt for the replacement. Queued after `builder-ready` and run in a
+   * disposable worker rather than inline: a full minified browser-target build of every page costs
+   * ~350MB of bundler arena that an inline build would never give back, and nothing serves CSR until a
+   * `/__csr` or `?csr=true` request arrives anyway.
+   */
+  async rearmCsrFromEnv(): Promise<void> {
+    if (!IncrementalBuilder.#csrArmedByEnv()) return;
+    this.#csrActive = true;
+    await this.#enqueueWork("build-csr-rearm", async () => {
+      const result = await this.#batchRunner.run(
+        await this.#batchRequest({ generation: this.#generation, needs: ["csr"], changedFiles: [] }),
+      );
+      if (result.errors.csr) this.#logger.error(`csr-rearm failed: ${result.errors.csr}`);
+      else this.#logger.verbose("csr-rearm ok; this session had CSR armed before the builder restarted");
+    });
   }
 
   /**
@@ -494,7 +571,7 @@ class IncrementalBuilder {
             }
           },
         });
-        watcher.start();
+        await watcher.start();
         logger.warn(`[degraded] watching ${roots.length} roots for a fix`);
       })().catch(reject);
     });
@@ -511,22 +588,33 @@ class IncrementalBuilder {
     // Registered before the boot build so backend requests get an error response (instead of hanging
     // the backend) while the builder is still booting or recovering from a failed build.
     const bootingError = "builder is recovering from a failed boot build; retry after the build error is fixed";
+    const recyclingError = "builder is recycling to release bundler memory; retry after it restarts";
     process.on("message", (msg: BuilderMessage) => {
       if (!msg || typeof msg !== "object") return;
-      if (msg.type === "build-route") {
+      if (msg.type === "builder-shutdown") {
         if (!builder) {
-          process.send?.({ type: "build-route-res", id: msg.id, ok: false, error: bootingError });
+          logger.warn(`ignoring shutdown request (${msg.reason}); builder is still recovering from a failed boot`);
           return;
         }
-        void builder.handleBuildRoute(msg).then((res) => process.send?.(res));
+        void builder.shutdown(msg.reason);
+        return;
+      }
+      if (msg.type === "build-route") {
+        const error = builder?.shuttingDown ? recyclingError : bootingError;
+        if (!builder || builder.shuttingDown) {
+          process.send?.({ type: "build-route-res", id: msg.id, ok: false, error });
+          return;
+        }
+        void builder.handleBuildRoute(msg);
         return;
       }
       if (msg.type === "build-csr") {
-        if (!builder) {
-          process.send?.({ type: "build-csr-res", id: msg.id, ok: false, error: bootingError });
+        const error = builder?.shuttingDown ? recyclingError : bootingError;
+        if (!builder || builder.shuttingDown) {
+          process.send?.({ type: "build-csr-res", id: msg.id, ok: false, error });
           return;
         }
-        void builder.handleBuildCsr(msg).then((res) => process.send?.(res));
+        void builder.handleBuildCsr(msg);
       }
     });
     // The IPC channel closes when the dev host dies (including SIGKILL); exit instead of running
@@ -546,6 +634,8 @@ class IncrementalBuilder {
     }
     await builder.boot();
     if (recoveredFiles) await builder.announceRecoveredState(recoveredFiles);
+    else if (process.env.AKAN_BUILDER_ANNOUNCE_BOOT === "1") await builder.announceBootState();
+    await builder.rearmCsrFromEnv();
   }
 }