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

package/server/hmr/csrDevRuntime.ts

@@ -45,12 +45,43 @@ export interface CsrDevRuntimeApi {
   defineHelpers(hash: string, factory: () => Record<string, unknown>): void;
   helpers(hash: string): Record<string, unknown>;
   start(options: { 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;
-  inspect(): { generation: number; executed: string[]; modules: number };
+  /** `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 {
@@ -63,7 +94,7 @@ interface CsrScriptElement {
 
 export interface CsrDevRuntimeHost {
   __akan?: CsrDevRuntimeApi;
-  __AKAN_CSR_LAST_UPDATE__?: { generation: number; executed: string[] };
+  __AKAN_CSR_LAST_UPDATE__?: { generation: number; executed: string[]; appliedAt?: number; refreshedAt?: number };
   document: {
     currentScript: unknown;
     head: { appendChild(node: unknown): unknown };
@@ -71,6 +102,7 @@ export interface CsrDevRuntimeHost {
   };
   location: { reload(): void };
   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;
 }
@@ -80,6 +112,10 @@ export const installCsrDevRuntime = (host: CsrDevRuntimeHost): void => {
   const modulePrefix = "akan-module:";
   const maxInvalidateRounds = 8;
 
+  const maxCatchUp = 40;
+
+  class MissingModuleError extends Error {}
+
   class HotContext implements CsrHotContext {
     selfAccepted = false;
     invalidated = false;
@@ -117,6 +153,16 @@ export const installCsrDevRuntime = (host: CsrDevRuntimeHost): void => {
 
   class CsrDevRegistry implements CsrDevRuntimeApi {
     #factories = new Map<string, CsrModuleFactory>();
+    #waiters = new Map<string, (() => void)[]>();
+    
+    #roots = new Set<string>();
+    #started = false;
+    #startFailed = false;
+    
+    #failed = new Set<string>();
+    #library: { vendorFile?: string; epoch?: number } = {};
+    #target = 0;
+    #early: CsrUpdateMessage[] = [];
     #helperFactories = new Map<string, () => Record<string, unknown>>();
     #helperValues = new Map<string, Record<string, unknown>>();
     #cache = new Map<string, ModuleRecord>();
@@ -128,6 +174,10 @@ export const installCsrDevRuntime = (host: CsrDevRuntimeHost): void => {
     #patchQueue: Promise<void> = Promise.resolve();
     #settling: Promise<void> = Promise.resolve();
     #reloading = false;
+    #markStarted: () => void = () => undefined;
+    readonly #whenStarted = new Promise<void>((resolve) => {
+      this.#markStarted = resolve;
+    });
 
     get generation() {
       return this.#generation;
@@ -135,6 +185,7 @@ export const installCsrDevRuntime = (host: CsrDevRuntimeHost): void => {
 
     define(id: string, factory: CsrModuleFactory) {
       this.#factories.set(id, factory);
+      this.#settleWaiters([id]);
     }
 
     defineHelpers(hash: string, factory: () => Record<string, unknown>) {
@@ -156,10 +207,85 @@ export const installCsrDevRuntime = (host: CsrDevRuntimeHost): void => {
       const entry = script?.dataset.akanCsrEntry;
       if (!entry) throw new Error("[akan-csr] the app script carries no data-akan-csr-entry");
       this.#generation = generation;
-      this.#refresh = this.#load(refresh).exports as RefreshRuntime;
-      
-      this.#refresh.injectIntoGlobalHook(host);
-      this.#load(entry);
+      this.#run(entry, () => {
+        const runtime = this.#load(refresh).exports as RefreshRuntime;
+        
+        runtime.injectIntoGlobalHook(host);
+        this.#refresh = runtime;
+      });
+    }
+
+    startLibrary({ generation, refresh, bootstrap, vendorFile, epoch }: LibraryStart) {
+      this.#library = { vendorFile, epoch };
+      this.#generation = generation;
+      this.#run(bootstrap, () => {
+        this.#refresh = this.#load(refresh).exports as RefreshRuntime;
+      });
+    }
+
+    #run(entry: string, loadRefresh: () => void) {
+      try {
+        loadRefresh();
+        this.#load(entry);
+      } catch (error) {
+        this.#startFailed = true;
+        throw error;
+      } finally {
+        this.#begin();
+      }
+    }
+
+    provide(id: string, namespace: unknown) {
+      if (this.#cache.has(id)) return;
+      const view: Record<string, unknown> = {};
+      Object.defineProperty(view, "__esModule", { value: true });
+      if (namespace != null && (typeof namespace === "object" || typeof namespace === "function"))
+        for (const key of Object.keys(namespace))
+          Object.defineProperty(view, key, {
+            get: () => (namespace as Record<string, unknown>)[key],
+            enumerable: true,
+          });
+      const record = new ModuleRecord(id, undefined);
+      record.exports = view;
+      this.#cache.set(id, record);
+    }
+
+    require(id: string) {
+      this.#roots.add(id);
+      return this.#surfaced(id, () => this.#load(id)).exports;
+    }
+
+    #surfaced<T>(id: string, load: () => T): T {
+      try {
+        const loaded = load();
+        this.#failed.delete(id);
+        return loaded;
+      } catch (error) {
+        const fixable = error instanceof MissingModuleError || !id.includes("node_modules/");
+        if (!id.startsWith("stub:") && fixable) this.#failed.add(id);
+        throw error;
+      }
+    }
+
+    has(id: string) {
+      return this.#cache.has(id) || this.#factories.has(id);
+    }
+
+    whenDefined(id: string) {
+      if (this.has(id)) return Promise.resolve();
+      return new Promise<void>((resolve, reject) => {
+        
+        const timer = host.setTimeout(() => {
+          this.#failed.add(id);
+          reject(new MissingModuleError(`[akan-csr] no module registered as ${id}, and no update brought one`));
+        }, 20_000);
+        const waiters = this.#waiters.get(id) ?? [];
+        waiters.push(() => {
+          host.clearTimeout(timer);
+          resolve();
+        });
+        this.#waiters.set(id, waiters);
+      });
     }
 
     update(generation: number, factories: Record<string, CsrModuleFactory>) {
@@ -170,7 +296,14 @@ export const installCsrDevRuntime = (host: CsrDevRuntimeHost): void => {
       }
       const ids = Object.keys(factories);
       for (const id of ids) this.#factories.set(id, factories[id] as CsrModuleFactory);
+      this.#settleWaiters(ids);
       this.#generation = generation;
+
+      const [broken] = this.#failed;
+      if (broken) {
+        this.#reload(`${broken} failed to run, and generation ${generation} may fix it`);
+        return;
+      }
       this.#executed = [];
       const threw = (error: unknown) =>
         this.#reload(
@@ -182,7 +315,7 @@ export const installCsrDevRuntime = (host: CsrDevRuntimeHost): void => {
       } catch (error) {
         threw(error);
       }
-      host.__AKAN_CSR_LAST_UPDATE__ = { generation, executed: this.#executed.slice() };
+      host.__AKAN_CSR_LAST_UPDATE__ = { generation, executed: this.#executed.slice(), appliedAt: Date.now() };
       if (pending.length > 0) this.#settling = Promise.all(pending).then(() => this.#scheduleRefresh(), threw);
     }
 
@@ -193,22 +326,84 @@ export const installCsrDevRuntime = (host: CsrDevRuntimeHost): void => {
     }
 
     hot(message: CsrUpdateMessage) {
-      if (message.reload) {
-        this.#reload(message.reason ?? "the dev server asked for a reload");
+      
+      if (!this.#started) {
+        this.#early.push(message);
+        return;
+      }
+      
+      if (this.#startFailed && message.reload && message.generation >= this.#generation) {
+        this.#reload(`the app failed to start, and generation ${message.generation} was rebuilt`);
         return;
       }
       if (message.generation <= this.#generation) return;
+      if (message.reload || this.#startFailed) {
+        this.#reload(
+          this.#startFailed
+            ? `the app failed to start, and generation ${message.generation} arrived`
+            : (message.reason ?? "the dev server asked for a reload"),
+        );
+        return;
+      }
+      
+      if (message.generation <= this.#target) return;
       const url = message.url;
       if (!url) {
         this.#reload(`generation ${message.generation} arrived without a patch`);
         return;
       }
-      
-      this.#patchQueue = this.#patchQueue.then(() => this.#loadPatch(url)).then(() => this.#settling);
+      const generation = message.generation;
+      this.#target = Math.max(this.#target, generation);
+
+      this.#patchQueue = this.#patchQueue
+        .then(() => (generation > this.#target ? undefined : this.#loadPatch(url)))
+        .then(() => this.#settling);
+    }
+
+    catchUp(generation: number, prefix: string) {
+      if (!this.#started) return;
+      const from = Math.max(this.#generation, this.#target) + 1;
+      if (generation - from >= maxCatchUp) {
+        this.#reload(`missed ${generation - from + 1} updates while disconnected`);
+        return;
+      }
+      for (let next = from; next <= generation; next += 1)
+        this.hot({ generation: next, url: `${prefix}patch-${next}.js` });
     }
 
     inspect() {
-      return { generation: this.#generation, executed: this.#executed.slice(), modules: this.#cache.size };
+      return {
+        generation: this.#generation,
+        target: Math.max(this.#generation, this.#target),
+        started: this.#started,
+        failed: this.#startFailed,
+        vendorFile: this.#library.vendorFile,
+        epoch: this.#library.epoch,
+        executed: this.#executed.slice(),
+        modules: this.#cache.size,
+      };
+    }
+
+    whenSettled(): Promise<void> {
+      if (!this.#started && this.#early.length > 0) return this.#whenStarted.then(() => this.whenSettled());
+      return this.#patchQueue.then(() => this.#settling);
+    }
+
+    #begin() {
+      this.#started = true;
+      const early = this.#early;
+      this.#early = [];
+      for (const message of early) this.hot(message);
+      this.#markStarted();
+    }
+
+    #settleWaiters(ids: string[]) {
+      for (const id of ids) {
+        const waiters = this.#waiters.get(id);
+        if (!waiters) continue;
+        this.#waiters.delete(id);
+        for (const settle of waiters) settle();
+      }
     }
 
     readonly toESM = (mod: unknown, _isNodeMode?: number): unknown => {
@@ -237,7 +432,7 @@ export const installCsrDevRuntime = (host: CsrDevRuntimeHost): void => {
       return secondTarget;
     };
 
-    #loadPatch(url: string) {
+    #loadPatch(url: string, retried = false): Promise<void> {
       return new Promise<void>((resolve) => {
         const script = host.document.createElement("script");
         script.src = url;
@@ -246,8 +441,21 @@ export const installCsrDevRuntime = (host: CsrDevRuntimeHost): void => {
           resolve();
         };
         script.onerror = () => {
-          this.#reload(`patch ${url} failed to load`);
-          resolve();
+          script.remove();
+          const failed = () => {
+            this.#reload(`patch ${url} failed to load`);
+            resolve();
+          };
+          const probe = host.fetch?.(url, { method: "HEAD", cache: "no-store" });
+          if (!probe) return failed();
+          probe.then(
+            (response) => (response.ok && !retried ? resolve(this.#loadPatch(url, true)) : failed()),
+            
+            () => {
+              this.#target = this.#generation;
+              resolve();
+            },
+          );
         };
         host.document.head.appendChild(script);
       });
@@ -272,13 +480,17 @@ export const installCsrDevRuntime = (host: CsrDevRuntimeHost): void => {
       const cached = this.#cache.get(id);
       if (cached) return cached;
       const factory = this.#factories.get(id);
-      if (!factory) throw new Error(`[akan-csr] no module registered as ${id}`);
+      if (!factory) throw new MissingModuleError(`[akan-csr] no module registered as ${id}`);
       const record = new ModuleRecord(id, this.#hotData.get(id));
       this.#cache.set(id, record);
       const requireFromHere = this.#requireFrom(id);
       const register = (type: unknown, localId: string) => this.#refresh?.register(type, `${id} ${localId}`);
       const signature = () => this.#refresh?.createSignatureFunctionForTransform() ?? ((type: unknown) => type);
-      const importFromHere = (specifier: string) => new Promise((resolve) => resolve(requireFromHere(specifier)));
+      const importFromHere = (specifier: string) =>
+        new Promise((resolve) => {
+          const target = specifier.startsWith(modulePrefix) ? specifier.slice(modulePrefix.length) : specifier;
+          resolve(this.#surfaced(target, () => requireFromHere(specifier)));
+        });
       try {
         factory.call(record.exports, requireFromHere, record, record.exports, register, signature, importFromHere);
       } catch (error) {
@@ -357,6 +569,7 @@ export const installCsrDevRuntime = (host: CsrDevRuntimeHost): void => {
       this.#refreshTimer = host.setTimeout(() => {
         this.#refreshTimer = null;
         this.#refresh?.performReactRefresh();
+        if (host.__AKAN_CSR_LAST_UPDATE__) host.__AKAN_CSR_LAST_UPDATE__.refreshedAt = Date.now();
       }, 16);
     }
 
@@ -377,6 +590,8 @@ export const installCsrDevRuntime = (host: CsrDevRuntimeHost): void => {
           [...plan.boundaries].map((id) => [id, [...(this.#cache.get(id)?.parents ?? [])]] as const),
         );
         this.#dispose(plan.outdated);
+
+        if ([...plan.boundaries].some((id) => this.#roots.has(id))) this.#scheduleRefresh();
         const invalidated: string[] = [];
         for (const id of plan.boundaries) {
           const record = this.#load(id);
@@ -387,6 +602,7 @@ export const installCsrDevRuntime = (host: CsrDevRuntimeHost): void => {
         pending = [];
         for (const id of invalidated) {
           const parents = [...(this.#cache.get(id)?.parents ?? [])];
+          if (parents.length === 0 && this.#roots.has(id)) continue;
           if (parents.length === 0) {
             this.#reload(`${id} changed its exports and nothing above it can take the update`);
             return [];
@@ -434,7 +650,11 @@ export const installCsrDevRuntime = (host: CsrDevRuntimeHost): void => {
           boundaries.add(id);
           continue;
         }
-        if (record.parents.size === 0) return { reload: `no component boundary above ${id}` };
+        if (record.parents.size === 0) {
+          if (!this.#roots.has(id)) return { reload: `no component boundary above ${id}` };
+          boundaries.add(id);
+          continue;
+        }
         for (const parentId of record.parents) {
           if (!this.#cache.get(parentId)?.hot.acceptedDeps.has(id)) {
             queue.push(parentId);

package/server/hmr/csrDevShell.ts

@@ -1,6 +1,8 @@
+import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveStaticPath } from "../staticPath";
 import {
+  appGenerationOf,
   CSR_DEV_APP_FILE,
   CSR_DEV_DIRNAME,
   CSR_DEV_MANIFEST_FILE,
@@ -19,14 +21,42 @@ export interface CsrDevShellRenderOptions {
   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 class CsrDevShell {
   static readonly #runtimeHash = Bun.hash(CSR_DEV_RUNTIME_SCRIPT).toString(36);
   static readonly #servedFile = /^(app\.js|vendor-[\w-]+\.js|patch-\d+\.js|assets\/[\w.-]+)$/;
   static readonly #sourceMapFile = /^(app\.js|patch-\d+\.js)\.map$/;
   readonly #dir: string;
+  readonly #routePrefix: string;
+  readonly #appWaitMs: number;
+  readonly #appPollMs: number;
+  readonly #bootWaitMs: number;
+  
+  readonly #sourceMaps = new Map<string, { stamp: string; body: string }>();
 
-  constructor(artifactDir: string) {
-    this.#dir = path.join(artifactDir, CSR_DEV_DIRNAME);
+  constructor(
+    artifactDir: string,
+    {
+      dirName = CSR_DEV_DIRNAME,
+      routePrefix = CSR_DEV_ROUTE_PREFIX,
+      appWaitMs = 2_000,
+      appPollMs = 20,
+      bootWaitMs = 60_000,
+    }: CsrDevShellOptions = {},
+  ) {
+    this.#dir = path.join(artifactDir, dirName);
+    this.#routePrefix = routePrefix;
+    this.#appWaitMs = appWaitMs;
+    this.#appPollMs = appPollMs;
+    this.#bootWaitMs = bootWaitMs;
   }
 
   async readManifest(): Promise<CsrDevManifest | null> {
@@ -52,19 +82,22 @@ export class CsrDevShell {
 ${stylesheet}  </head>
   <body>
     <div id="root"></div>
-    <script src="${CSR_DEV_ROUTE_PREFIX}runtime.js?v=${CsrDevShell.#runtimeHash}"></script>
-    <script src="${CSR_DEV_ROUTE_PREFIX}${CsrDevShell.#attr(manifest.vendorFile)}"></script>
-    <script src="${CSR_DEV_ROUTE_PREFIX}${CSR_DEV_APP_FILE}?g=${manifest.generation}" data-akan-csr-entry="${CsrDevShell.#attr(entry)}"></script>
+    <script src="${this.#routePrefix}runtime.js?v=${CsrDevShell.#runtimeHash}"></script>
+    <script src="${this.#routePrefix}${CsrDevShell.#attr(manifest.vendorFile)}"></script>
+    <script src="${this.#routePrefix}${CSR_DEV_APP_FILE}?g=${manifest.generation}" data-akan-csr-entry="${CsrDevShell.#attr(entry)}"></script>
   </body>
 </html>
 `;
   }
 
   async serve(req: Request): Promise<Response> {
-    const name = new URL(req.url).pathname.slice(CSR_DEV_ROUTE_PREFIX.length);
+    const url = new URL(req.url);
+    const name = url.pathname.slice(this.#routePrefix.length);
     if (name === "runtime.js") return CsrDevShell.#js(CSR_DEV_RUNTIME_SCRIPT, "public, max-age=31536000, immutable");
+    if (name === "boot.json") return await this.#serveBoot(url.searchParams.get("wait"), req.signal);
     if (CsrDevShell.#sourceMapFile.test(name)) return await this.#serveSourceMap(name);
     if (!CsrDevShell.#servedFile.test(name)) return new Response("Not Found", { status: 404 });
+    if (name === CSR_DEV_APP_FILE) await this.#waitForApp(Number(url.searchParams.get("g")), req.signal);
     const filePath = resolveStaticPath(this.#dir, name);
     const file = filePath ? Bun.file(filePath) : null;
     if (!file || !(await file.exists())) return new Response("Not Found", { status: 404 });
@@ -74,11 +107,58 @@ ${stylesheet}  </head>
     return CsrDevShell.#js(file, cacheControl);
   }
 
+  async #waitForApp(generation: number, signal?: AbortSignal): Promise<void> {
+    if (!Number.isInteger(generation) || generation <= 0) return;
+    const deadline = Date.now() + this.#appWaitMs;
+    for (;;) {
+      const manifest = await this.readManifest();
+      if (!manifest || manifest.generation < generation || appGenerationOf(manifest) >= generation) return;
+      if (Date.now() >= deadline || signal?.aborted) return;
+      await Bun.sleep(this.#appPollMs);
+    }
+  }
+
+  async #serveBoot(wait: string | null, signal?: AbortSignal): Promise<Response> {
+    const asked = wait === null ? Number.NaN : Number(wait);
+    const waitMs = Number.isInteger(asked) ? Math.min(Math.max(asked, 0), this.#bootWaitMs) : this.#bootWaitMs;
+    const deadline = Date.now() + waitMs;
+    for (;;) {
+      const manifest = await this.readManifest();
+      if (manifest) {
+        const body = JSON.stringify({
+          generation: manifest.generation,
+          vendorFile: manifest.vendorFile,
+          epoch: manifest.epoch ?? null,
+        });
+        return new Response(body, { headers: CsrDevShell.#headers("application/json", "no-store") });
+      }
+      if (Date.now() >= deadline || signal?.aborted) return new Response("Service Unavailable", { status: 503 });
+      await Bun.sleep(this.#appPollMs * 5);
+    }
+  }
+
   async #serveSourceMap(name: string): Promise<Response> {
     const generatedFile = name.slice(0, -".map".length);
-    const layoutFile = Bun.file(path.join(this.#dir, `${generatedFile}.layout.json`));
-    if (!(await layoutFile.exists())) return new Response("Not Found", { status: 404 });
-    const layout = (await layoutFile.json()) as CsrDevLayout;
+    const layoutPath = path.join(this.#dir, `${generatedFile}.layout.json`);
+    const stat = await fs.stat(layoutPath).catch(() => null);
+    if (!stat) return new Response("Not Found", { status: 404 });
+    const stamp = `${stat.ino}:${stat.size}:${stat.mtimeMs}`;
+    const cached = this.#sourceMaps.get(generatedFile);
+    const body = cached?.stamp === stamp ? cached.body : await this.#mergeSourceMap(generatedFile, layoutPath);
+    if (!body) return new Response("Not Found", { status: 404 });
+    this.#sourceMaps.delete(generatedFile);
+    this.#sourceMaps.set(generatedFile, { stamp, body });
+    for (const oldest of this.#sourceMaps.keys()) {
+      if (this.#sourceMaps.size <= 4) break;
+      this.#sourceMaps.delete(oldest);
+    }
+    return new Response(body, { headers: CsrDevShell.#headers("application/json", "no-store") });
+  }
+
+  async #mergeSourceMap(generatedFile: string, layoutPath: string): Promise<string | null> {
+    const layoutText = await fs.readFile(layoutPath, "utf8").catch(() => null);
+    if (!layoutText) return null;
+    const layout = JSON.parse(layoutText) as CsrDevLayout;
     const sections = await Promise.all(
       layout.modules.map(async ([id, line]) => {
         const file = Bun.file(path.join(this.#dir, csrDevModuleFile(id, ".js.map")));
@@ -90,7 +170,7 @@ ${stylesheet}  </head>
       sections.filter((section) => section !== null),
       layout.lineCount,
     );
-    return new Response(JSON.stringify(map), { headers: CsrDevShell.#headers("application/json", "no-store") });
+    return JSON.stringify(map);
   }
 
   static #js(body: string | Blob, cacheControl: string): Response {

package/server/hmr/devArtifactPruner.ts

@@ -0,0 +1,77 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Logger } from "akanjs/common";
+import type { CssAsset } from "../types";
+
+export class DevArtifactPruner {
+  
+  static readonly #defaultGraceMs = 60_000;
+  static readonly #pagesFile = /^pages-[^/\\]+\.js$/;
+  readonly #logger = new Logger("DevArtifactPruner");
+  readonly #artifactDir: string;
+  readonly #graceMs: number;
+  #pruning: Promise<void> = Promise.resolve();
+
+  constructor(artifactDir: string, { graceMs = DevArtifactPruner.#defaultGraceMs }: { graceMs?: number } = {}) {
+    this.#artifactDir = path.resolve(artifactDir);
+    this.#graceMs = graceMs;
+  }
+
+  prunePages(runningPath: string): Promise<void> {
+    return this.#queue(async () => {
+      const running = await fs.stat(runningPath).catch(() => null);
+      if (!running) return;
+      const keep = new Set([path.resolve(runningPath), ...(await this.#baseArtifact()).pages]);
+      const serverDir = path.join(this.#artifactDir, "server");
+      const before = Math.min(running.mtimeMs, Date.now() - this.#graceMs);
+      await this.#removeOlder(serverDir, (name) => DevArtifactPruner.#pagesFile.test(name), keep, before);
+    });
+  }
+
+  pruneStyles(cssAssets: Record<string, CssAsset>): Promise<void> {
+    return this.#queue(async () => {
+      const current = Object.values(cssAssets).map((asset) => path.join(this.#artifactDir, asset.cssRelPath));
+      const keep = new Set([...current, ...(await this.#baseArtifact()).styles]);
+      const stylesDir = path.join(this.#artifactDir, "styles");
+      await this.#removeOlder(stylesDir, (name) => name.endsWith(".css"), keep, Date.now() - this.#graceMs);
+    });
+  }
+
+  #queue(prune: () => Promise<void>): Promise<void> {
+    this.#pruning = this.#pruning.then(prune).catch((error: unknown) => {
+      this.#logger.verbose(`[dev-artifact] prune skipped: ${String(error)}`);
+    });
+    return this.#pruning;
+  }
+
+  async #removeOlder(dir: string, matches: (name: string) => boolean, keep: Set<string>, before: number) {
+    const names = await fs.readdir(dir).catch(() => [] as string[]);
+    let removed = 0;
+    for (const name of names) {
+      const file = path.join(dir, name);
+      if (!matches(name) || keep.has(file)) continue;
+      const stat = await fs.stat(file).catch(() => null);
+      if (!stat || stat.mtimeMs >= before) continue;
+      
+      if (
+        await fs.rm(file, { force: true }).then(
+          () => true,
+          () => false,
+        )
+      )
+        removed += 1;
+    }
+    if (removed > 0) this.#logger.verbose(`[dev-artifact] removed ${removed} superseded file(s) from ${dir}`);
+  }
+
+  async #baseArtifact(): Promise<{ pages: string[]; styles: string[] }> {
+    const text = await fs.readFile(path.join(this.#artifactDir, "base-artifact.json"), "utf8").catch(() => null);
+    const artifact = text
+      ? (JSON.parse(text) as { pagesBundlePath?: string; cssAssets?: Record<string, CssAsset> })
+      : null;
+    return {
+      pages: artifact?.pagesBundlePath ? [path.resolve(this.#artifactDir, artifact.pagesBundlePath)] : [],
+      styles: Object.values(artifact?.cssAssets ?? {}).map((asset) => path.join(this.#artifactDir, asset.cssRelPath)),
+    };
+  }
+}