akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/server/animatedImage.ts

@@ -1,9 +1,4 @@
-/**
- * `Bun.Image.metadata()` reports only `{ width, height, format }` — there is no frame count — and an
- * animated GIF decodes to its first frame without erroring. So an optimizer that re-encodes whatever
- * decodes would silently drop the animation. These readers answer the question from the container bytes
- * instead, so an animated source can be passed through untouched.
- */
+
 
 /** Sub-blocks are a `[length][bytes]…[0]` chain, so a frame's payload cannot be skipped by size alone. */
 const skipGifSubBlocks = (buffer: Buffer, start: number): number => {
@@ -19,10 +14,6 @@ const skipGifSubBlocks = (buffer: Buffer, start: number): number => {
 
 const colorTableSize = (packed: number): number => ((packed & 0x80) === 0 ? 0 : 3 * 2 ** ((packed & 0x07) + 1));
 
-/**
- * Walks the GIF block stream to count image descriptors. Counting raw `0x2C` bytes would overcount —
- * the byte occurs freely inside colour tables and LZW payloads — so every block has to be stepped over.
- */
 const hasMultipleGifFrames = (buffer: Buffer): boolean => {
   if (buffer.length < 13) return false;
   let offset = 6;
@@ -77,7 +68,7 @@ export const isAnimatedImage = (buffer: Buffer, contentType: string): boolean =>
     if (contentType === "image/png") return hasPngAnimationControl(buffer);
     return false;
   } catch {
-
+    
     return true;
   }
 };

package/server/artifact/builderRpc.ts

@@ -6,57 +6,36 @@ import type {
   BuilderMessage,
   BuilderReq,
   BuilderRes,
+  BuildRouteClientResult,
   BuildRouteResultPayload,
   CssPayload,
   DevBuildStatus,
   PagesBundlePayload,
 } from "./ipcTypes";
-import type { BuildRouteClientResult } from "./manifestTypes";
 
 export interface BuilderRpcEventHandlers {
-  /**
-   * Filesystem batch invalidation from the builder's watcher. The backend
-   * should treat this as a hint to clear its route cache and broadcast a
-   * dev reload to connected HMR clients.
-   */
+  /** A watcher batch changed files: clear the route cache and broadcast a dev reload. */
   onInvalidate?: (event: { kinds: ("code" | "css" | "config")[]; files: string[]; generation?: number }) => void;
-  /** Builder proactively recompiled CSS; payload includes base64 bytes. */
   onCssUpdated?: (css: CssPayload) => void;
-  /**
-   * Builder emitted a freshly bundled `pages-*.js`. Backend should
-   * re-import it (e.g. by calling `RscWorker.reload({ pagesBundlePath,
-   * buildId })`) so new user code takes effect without spawning a new
-   * worker subprocess.
-   */
+  /** A fresh `pages-*.js` bundle: re-import it in the running worker (`RscWorker.reload`) rather than respawning. */
   onPagesUpdated?: (bundle: PagesBundlePayload) => void;
-  /** Builder reported a dev build phase success/failure. */
   onBuildStatus?: (status: DevBuildStatus) => void;
 }
 
-/**
- * Typed RPC facade around the raw `BuilderTransport`. Handles the
- * correlation-id bookkeeping (request promise + resolver map) and exposes
- * a narrow surface matching the three builder operations.
- *
- * Only one `BuilderRpc` instance should exist per backend process. It
- * subscribes to the transport at construction and unsubscribes on
- * `dispose()`.
- */
+/** One per backend process: subscribes to the IPC channel on construction and unsubscribes on `dispose()`. */
 export class BuilderRpc {
   readonly #logger = new Logger("BuilderRpc");
   readonly #pending = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
   readonly #offMessage: () => void;
-  readonly #proc = process;
   readonly #send: (msg: BuilderReq | BuilderCsrReq) => void;
   #nextId = 1;
   #disposed = false;
 
   constructor(handlers: BuilderRpcEventHandlers = {}) {
-    if (!this.#proc.send)
+    if (!process.send)
       throw new Error("[builder] process.send unavailable — backend must be spawned by the CLI with ipc enabled");
-    this.#send = this.#proc.send.bind(this.#proc);
+    this.#send = process.send.bind(process);
     this.#offMessage = this.#listen((msg) => {
-      
       if (msg.type === "build-route-res" || msg.type === "build-csr-res") {
         const res = msg as BuilderRes | BuilderCsrRes;
         const waiter = this.#pending.get(res.id);
@@ -66,11 +45,10 @@ export class BuilderRpc {
         else waiter.resolve(res.type === "build-route-res" ? res.data : undefined);
         return;
       }
-      
       const ev = msg as BuilderEvent;
       switch (ev.type) {
         case "builder-ready":
-          this.#logger.verbose(`[builder] builder ready buildId=${ev.buildId}`);
+          this.#logger.verbose("[builder] builder ready");
           return;
         case "invalidate":
           handlers.onInvalidate?.({ kinds: ev.kinds, files: ev.files, generation: ev.generation });
@@ -84,20 +62,21 @@ export class BuilderRpc {
         case "build-status":
           handlers.onBuildStatus?.(ev.data);
           return;
-        default:
-          return;
       }
     });
   }
 
   async buildRoute(
     routeId: string,
-    { seeds, knownEntries, generation }: { seeds: string[]; knownEntries: Set<string>; generation?: number },
+    {
+      seeds,
+      graphSeeds,
+      knownEntries,
+      generation,
+    }: { seeds: string[]; graphSeeds?: string[]; knownEntries: Set<string>; generation?: number },
   ): Promise<BuildRouteClientResult> {
-    if (this.#disposed) throw new Error("[builder] rpc is disposed");
-    const id = this.#nextId++;
-    const payload = await this.#request<BuildRouteResultPayload>(id, `build-route ${routeId}`, () =>
-      this.#send({ type: "build-route", id, routeId, seeds, knownEntries: [...knownEntries], generation }),
+    const payload = await this.#request<BuildRouteResultPayload>(`build-route ${routeId}`, (id) =>
+      this.#send({ type: "build-route", id, routeId, seeds, graphSeeds, knownEntries: [...knownEntries], generation }),
     );
     return {
       manifestDelta: payload.manifestDelta,
@@ -109,39 +88,20 @@ export class BuilderRpc {
     };
   }
 
-  /**
-   * Ask the builder to build the dev CSR artifact and keep it in sync from now on. The builder skips
-   * CSR by default (a full minified browser-target build of every page, ~350 MB per save), so the
-   * first `/__csr` or `?csr=true` request has nothing to serve until this resolves.
-   */
+  /** Arms dev CSR, which the builder skips by default (a full browser build per save), and keeps it in sync after. */
   async buildCsr(reason: string): Promise<void> {
-    if (this.#disposed) throw new Error("[builder] rpc is disposed");
-    const id = this.#nextId++;
-    await this.#request<void>(id, `build-csr (${reason})`, () => this.#send({ type: "build-csr", id, reason }));
+    await this.#request<void>(`build-csr (${reason})`, (id) => this.#send({ type: "build-csr", id, reason }));
   }
 
-  /**
-   * How long to wait for the builder before failing a request. `AKAN_BUILDER_RPC_TIMEOUT_MS` overrides.
-   *
-   * Generous, because a cold CSR build of every page legitimately takes tens of seconds; the point is not
-   * to be tight but to be finite.
-   */
   static #timeoutMs(): number {
     const configured = Number(process.env.AKAN_BUILDER_RPC_TIMEOUT_MS);
     if (Number.isFinite(configured) && configured > 0) return configured;
     return 120_000;
   }
 
-  /**
-   * One builder request, which fails rather than waiting forever.
-   *
-   * Nothing answers a request whose builder exits after receiving it: the dev host replies `ok:false` only
-   * when the *send* fails, and it does not track in-flight ids. The builder exits routinely — it is recycled
-   * every few builds once its RSS passes the ceiling — so a page request that happens to be mid route-build
-   * left this promise pending forever, and the browser tab span with no error, no log and nothing to retry.
-   * Observed from the other side as a `fetch` that sat for 225s against a 60s budget.
-   */
-  async #request<T>(id: number, label: string, send: () => void): Promise<T> {
+  async #request<T>(label: string, send: (id: number) => void): Promise<T> {
+    if (this.#disposed) throw new Error("[builder] rpc is disposed");
+    const id = this.#nextId++;
     const timeoutMs = BuilderRpc.#timeoutMs();
     return await new Promise<T>((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -164,7 +124,7 @@ export class BuilderRpc {
           reject(error);
         },
       });
-      send();
+      send(id);
     });
   }
 
@@ -181,10 +141,10 @@ export class BuilderRpc {
       if (!msg || typeof msg !== "object") return;
       listener(msg as BuilderMessage);
     };
-    this.#proc.on("message", handler);
+    process.on("message", handler);
     return () => {
-      if (this.#proc.off) this.#proc.off("message", handler);
-      else if (this.#proc.removeListener) this.#proc.removeListener("message", handler);
+      if (process.off) process.off("message", handler);
+      else if (process.removeListener) process.removeListener("message", handler);
     };
   }
 }

package/server/artifact/index.ts

@@ -1,6 +1,5 @@
 export * from "./builderRpc";
 export * from "./ipcTypes";
-export * from "./manifestTypes";
 export * from "./routeClientCache";
 export * from "./routeSeedIndexStore";
 export * from "./routesManifestStore";

package/server/artifact/ipcTypes.ts

@@ -1,3 +1,5 @@
+import type { SsrManifest } from "../ssrTypes";
+
 export interface BuildRouteResultPayload {
   manifestDelta: Record<string, { id: string; chunks: string[]; name: string; async: boolean }>;
   ssrManifestDelta: Record<string, Record<string, { id: string; chunks: string[]; name: string; async: boolean }>>;
@@ -9,13 +11,7 @@ export interface BuildRouteResultPayload {
   generation?: number;
 }
 
-/**
- * Marks a frontend payload that re-announces a freshly booted artifact rather than reporting an edit.
- * A recycled builder rebuilds every artifact from scratch, but a running backend read
- * `base-artifact.json` once at boot and never re-reads it, so the new state has to be pushed. The
- * host drops such a payload when the hashed output did not actually move, which keeps a clean
- * recycle invisible to connected browsers.
- */
+/** 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";
 
 export interface CssPayload {
@@ -61,6 +57,7 @@ export type BuilderReq = {
   id: number;
   routeId: string;
   seeds: string[];
+  graphSeeds?: string[];
   knownEntries: string[];
   generation?: number;
 };
@@ -69,24 +66,14 @@ export type BuilderRes =
   | { type: "build-route-res"; id: number; ok: true; data: BuildRouteResultPayload }
   | { type: "build-route-res"; id: number; ok: false; error: string };
 
-/**
- * Dev CSR artifacts are only reachable through the opt-in `/__csr` and `?csr=true` routes (mobile
- * local dev points a device WebView at the latter), so the builder skips them until a request
- * actually needs one. The first such request arms the builder through this pair and waits for the
- * build, after which every save keeps CSR in sync.
- */
+/** Sent by the first `/__csr` or `?csr=true` request (a device WebView in mobile dev) to arm the lazy dev CSR build. */
 export type BuilderCsrReq = { type: "build-csr"; id: number; reason: string };
 
 export type BuilderCsrRes =
   | { type: "build-csr-res"; id: number; ok: true }
   | { type: "build-csr-res"; id: number; ok: false; error: string };
 
-/**
- * Asks the builder to finish its queued work and exit, which is the only way bundler memory is
- * returned to the OS (see `BuilderMetrics`). The host's existing restart path brings up a
- * replacement, so a graceful drain — rather than a kill — keeps a rebuild in flight from being
- * truncated.
- */
+/** Drain and exit (the only way bundler memory returns to the OS); draining, not killing, keeps a rebuild whole. */
 export type BuilderControl = { type: "builder-shutdown"; reason: string };
 
 export interface PagesBundlePayload {
@@ -97,17 +84,9 @@ export interface PagesBundlePayload {
   reason?: BuilderStateReason;
 }
 
-/**
- * `Bun.build` retains native bundler arenas that `Bun.gc(true)` never reclaims — the JS heap stays flat
- * while RSS climbs. **How much comes back without exiting is platform-specific**: measured on Bun
- * 1.3.14, macOS returns none of it (0% after 60s idle) while Linux purges 46-59% after ~10-15s idle.
- * The dev host recycles past a ceiling to bound the macOS case.
- *
- * Because this is only reported when the builder's queues drain, `rssBytes` is a *peak* sample. On
- * Linux it goes stale within seconds, so the host re-reads the builder's RSS from the OS before acting
- * on it. See `local/optimize-resource/09-linux-retention-measurement.md`.
- */
+/** `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. */
   generation: number;
@@ -116,7 +95,7 @@ export interface BuilderMetrics {
 }
 
 export type BuilderEvent =
-
+  
   | { type: "builder-ready"; buildId?: string }
   | { type: "backend-ready"; pid: number }
   | {
@@ -132,3 +111,21 @@ export type BuilderEvent =
   | { type: "builder-metrics"; data: BuilderMetrics };
 
 export type BuilderMessage = BuilderReq | BuilderRes | BuilderCsrReq | BuilderCsrRes | BuilderControl | BuilderEvent;
+
+export interface ClientManifestEntry {
+  id: string;
+  chunks: string[];
+  name: string;
+  async?: boolean;
+}
+
+export type ClientManifest = Record<string, ClientManifestEntry>;
+
+export interface BuildRouteClientResult {
+  manifestDelta: ClientManifest;
+  ssrManifestDelta: SsrManifest;
+  newEntries: string[];
+  discoveredEntries?: string[];
+  clientDeps: string[];
+  clientDepsByEntry?: Record<string, string[]>;
+}

package/server/artifact/routeClientCache.ts

@@ -1,13 +1,9 @@
 import { Logger } from "akanjs/common";
 import type { SsrManifest } from "../ssrTypes";
-import type { BuildRouteClientResult, ClientManifest } from "./manifestTypes";
+import type { BuildRouteClientResult, ClientManifest } from "./ipcTypes";
 import type { RoutesManifest } from "./routesManifestStore";
 
-/**
- * Snapshot of every per-route build's accumulated output for one HMR
- * generation. Callers should take a `snapshot()` before rendering so an
- * invalidate cannot mutate the manifest while a request is consuming it.
- */
+/** One HMR generation's merged route builds; render from a `snapshot()`, which an invalidate cannot mutate. */
 export interface MergedManifest {
   generation: number;
   clientManifest: ClientManifest;
@@ -40,12 +36,7 @@ export class RouteClientCache {
   readonly #logger = new Logger("RouteClientCache");
   readonly #built = new Map<string, BuildRouteClientResult>();
   readonly #building = new Map<string, PendingBuild>();
-  merged: MergedManifest = {
-    generation: 0,
-    clientManifest: {},
-    ssrManifest: { moduleLoading: null, moduleMap: {} },
-    knownEntries: new Set<string>(),
-  };
+  merged: MergedManifest = this.#getEmptyMerged(0);
   readonly #buildRoute: RouteBuildFn;
   readonly #onMerge?: OnMergeFn;
   #revision = 0;
@@ -55,11 +46,7 @@ export class RouteClientCache {
     this.#onMerge = onMerge;
   }
 
-  /**
-   * Bumped on every mutation of `merged`, including a delta merge that leaves `generation` where it was. It lets a
-   * consumer memoize work derived from the manifest — merging the runtime manifest over it, say — without having to
-   * copy the manifest to find out whether anything changed. In production nothing after `seed` moves it at all.
-   */
+  /** Bumped on every change to `merged`, even a delta merge that keeps `generation`: a memo key for derived work. */
   get revision(): number {
     return this.#revision;
   }
@@ -132,7 +119,11 @@ export class RouteClientCache {
       );
       return delta;
     }
-    for (const [key, row] of Object.entries(delta.manifestDelta)) this.merged.clientManifest[key] = row;
+    for (const [key, row] of Object.entries(delta.manifestDelta)) {
+      const previous = this.merged.clientManifest[key];
+      if (previous && previous.id !== row.id) delete this.merged.ssrManifest.moduleMap[previous.id];
+      this.merged.clientManifest[key] = row;
+    }
     for (const [url, byName] of Object.entries(delta.ssrManifestDelta.moduleMap))
       this.merged.ssrManifest.moduleMap[url] = byName;
     for (const entry of delta.newEntries) this.merged.knownEntries.add(entry);
@@ -145,14 +136,14 @@ export class RouteClientCache {
     return delta;
   }
 
+  #dropBuilt(predicate: (routeId: string) => boolean): string[] {
+    const dropped = [...this.#built.keys()].filter((routeId) => predicate(routeId));
+    for (const id of dropped) this.#built.delete(id);
+    return dropped;
+  }
+
   invalidate(predicate: (routeId: string) => boolean): string[] {
-    const dropped: string[] = [];
-    for (const id of [...this.#built.keys()]) {
-      if (predicate(id)) {
-        this.#built.delete(id);
-        dropped.push(id);
-      }
-    }
+    const dropped = this.#dropBuilt(predicate);
     if (dropped.length > 0) {
       this.#rebuildKnownEntriesPreservingManifest(this.merged.generation + 1);
       this.#building.clear();
@@ -163,13 +154,7 @@ export class RouteClientCache {
 
   invalidateClientEntries({ routePredicate, staleEntries }: InvalidateClientEntriesOptions): string[] {
     const normalizedStaleEntries = new Set([...staleEntries].map((entry) => RouteClientCache.#normalizePath(entry)));
-    const dropped: string[] = [];
-    for (const id of [...this.#built.keys()]) {
-      if (routePredicate(id)) {
-        this.#built.delete(id);
-        dropped.push(id);
-      }
-    }
+    const dropped = this.#dropBuilt(routePredicate);
     if (dropped.length === 0 && normalizedStaleEntries.size === 0) return dropped;
 
     this.#rebuildKnownEntriesPreservingManifest(this.merged.generation + 1, normalizedStaleEntries);
@@ -181,11 +166,7 @@ export class RouteClientCache {
   }
 
   clear(): string[] {
-    const dropped: string[] = [];
-    for (const id of [...this.#built.keys()]) {
-      this.#built.delete(id);
-      dropped.push(id);
-    }
+    const dropped = this.#dropBuilt(() => true);
     const nextGeneration = this.merged.generation + 1;
     this.merged = this.#getEmptyMerged(nextGeneration);
     this.#revision += 1;

package/server/artifact/routeSeedIndexStore.ts

@@ -1,17 +1,7 @@
 import path from "node:path";
 import { matchRoutePattern } from "akanjs/common";
+import { matchRoutePrefix } from "../../common/routeConvention";
 
-/**
- * Runtime counterpart to `akanjs/devkit`'s `routeSeedIndex.ts`. The index
- * itself is computed at build time by the CLI (which walks the `pages`
- * registry and parses loader sources) and serialized to
- * `route-seed-index.json`. The server only loads that JSON at boot and matches
- * incoming pathnames against its route seed entries.
- *
- * Keeping this runtime-safe means `akanjs/server` never has to reach into
- * `app/pages.ts` or Function.prototype.toString() — which is what made the
- * previous in-process computation prone to drifting from the build pipeline.
- */
 export interface RouteSeedEntry {
   routeId: string;
   pattern: string;
@@ -69,11 +59,6 @@ export class RouteSeedIndexStore {
     };
   }
 
-  /**
-   * Match `pathname` against every registered route pattern using the same
-   * `:param` semantics as route tree matching. Returns the first entry that
-   * matches, along with the extracted parameters.
-   */
   static match(pathname: string, entries: RouteSeedEntry[]): MatchedRoute | null {
     for (const entry of entries) {
       const params = matchRoutePattern(entry.pattern ?? entry.routeId, pathname);
@@ -86,7 +71,7 @@ export class RouteSeedIndexStore {
     const candidates = entries
       .map((entry) => ({
         entry,
-        params: RouteSeedIndexStore.#matchRoutePrefix(entry.pattern ?? entry.routeId, pathname),
+        params: matchRoutePrefix(entry.pattern ?? entry.routeId, pathname),
       }))
       .filter((entry): entry is { entry: RouteSeedEntry; params: Record<string, string> } => Boolean(entry.params))
       .sort((a, b) => {
@@ -98,24 +83,6 @@ export class RouteSeedIndexStore {
     return candidates[0] ?? null;
   }
 
-  static #matchRoutePrefix(pattern: string, pathname: string): Record<string, string> | null {
-    const patternParts = pattern.split("/").filter(Boolean);
-    const pathParts = pathname.split("/").filter(Boolean);
-    if (patternParts.length > pathParts.length) return null;
-    const params: Record<string, string> = {};
-    for (let index = 0; index < patternParts.length; index++) {
-      const patternPart = patternParts[index];
-      const pathPart = pathParts[index];
-      if (!patternPart || !pathPart) return null;
-      if (patternPart.startsWith(":")) {
-        params[patternPart.slice(1)] = decodeURIComponent(pathPart);
-        continue;
-      }
-      if (patternPart !== pathPart) return null;
-    }
-    return params;
-  }
-
   static #normalizeArtifactPath(artifactPath: string, artifactDir: string): string {
     if (path.isAbsolute(artifactPath)) return artifactPath;
     return path.resolve(artifactDir, artifactPath);

package/server/artifact/routesManifestStore.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import type { SsrManifest, SsrManifestEntry } from "../ssrTypes";
-import type { ClientManifest } from "./manifestTypes";
+import type { ClientManifest } from "./ipcTypes";
 
 export interface RoutesManifest {
   routeIds: string[];
@@ -18,7 +18,9 @@ export class RoutesManifestStore {
     return {
       ...manifest,
       clientManifest: RoutesManifestStore.#serializeClientManifest(manifest.clientManifest, normalizedArtifactDir),
-      ssrManifest: RoutesManifestStore.#serializeSsrManifest(manifest.ssrManifest, normalizedArtifactDir),
+      ssrManifest: RoutesManifestStore.#mapSsrManifest(manifest.ssrManifest, (artifactPath) =>
+        RoutesManifestStore.#serializeArtifactPath(artifactPath, normalizedArtifactDir),
+      ),
       knownEntries: manifest.knownEntries.map((entry) =>
         RoutesManifestStore.#serializeArtifactPath(entry, normalizedArtifactDir),
       ),
@@ -38,8 +40,10 @@ export class RoutesManifestStore {
   static normalize(manifest: SerializedRoutesManifest, artifactDir: string): RoutesManifest {
     return {
       ...manifest,
-      clientManifest: RoutesManifestStore.#normalizeClientManifest(manifest.clientManifest),
-      ssrManifest: RoutesManifestStore.#normalizeSsrManifest(manifest.ssrManifest, artifactDir),
+      clientManifest: { ...manifest.clientManifest },
+      ssrManifest: RoutesManifestStore.#mapSsrManifest(manifest.ssrManifest, (artifactPath) =>
+        RoutesManifestStore.#normalizeArtifactPath(artifactPath, artifactDir),
+      ),
       knownEntries: (manifest.knownEntries ?? []).map((entry) =>
         RoutesManifestStore.#normalizeStoredPath(entry, artifactDir),
       ),
@@ -54,42 +58,13 @@ export class RoutesManifestStore {
     return serialized;
   }
 
-  static #normalizeClientManifest(clientManifest: ClientManifest): ClientManifest {
-    const normalized: ClientManifest = {};
-    for (const [key, row] of Object.entries(clientManifest)) {
-      normalized[key] = row;
-    }
-    return normalized;
-  }
-
-  static #serializeSsrManifest(ssrManifest: SsrManifest, artifactDir: string): SsrManifest {
-    const moduleMap: SsrManifest["moduleMap"] = {};
-    for (const [entryUrl, byName] of Object.entries(ssrManifest.moduleMap)) {
-      const serializedByName: Record<string, SsrManifestEntry> = {};
-      for (const [name, entry] of Object.entries(byName)) {
-        serializedByName[name] = {
-          ...entry,
-          id: RoutesManifestStore.#serializeArtifactPath(entry.id, artifactDir),
-          chunks: entry.chunks.map((chunk) => RoutesManifestStore.#serializeArtifactPath(chunk, artifactDir)),
-        };
-      }
-      moduleMap[entryUrl] = serializedByName;
-    }
-    return { ...ssrManifest, moduleMap };
-  }
-
-  static #normalizeSsrManifest(ssrManifest: SsrManifest, artifactDir: string): SsrManifest {
+  static #mapSsrManifest(ssrManifest: SsrManifest, mapPath: (artifactPath: string) => string): SsrManifest {
     const moduleMap: SsrManifest["moduleMap"] = {};
     for (const [entryUrl, byName] of Object.entries(ssrManifest.moduleMap)) {
-      const normalizedByName: Record<string, SsrManifestEntry> = {};
-      for (const [name, entry] of Object.entries(byName)) {
-        normalizedByName[name] = {
-          ...entry,
-          id: RoutesManifestStore.#normalizeArtifactPath(entry.id, artifactDir),
-          chunks: entry.chunks.map((chunk) => RoutesManifestStore.#normalizeArtifactPath(chunk, artifactDir)),
-        };
-      }
-      moduleMap[entryUrl] = normalizedByName;
+      const mappedByName: Record<string, SsrManifestEntry> = {};
+      for (const [name, entry] of Object.entries(byName))
+        mappedByName[name] = { ...entry, id: mapPath(entry.id), chunks: entry.chunks.map((chunk) => mapPath(chunk)) };
+      moduleMap[entryUrl] = mappedByName;
     }
     return { ...ssrManifest, moduleMap };
   }

package/server/binaryPubsub.ts

@@ -1,12 +1,5 @@
 import { Logger } from "akanjs/common";
 
-/**
- * Sends binary pubsub frames and absorbs a slow subscriber. `Server.publish` reports `-1` when the socket is
- * backpressured, `0` when the room has no subscriber, and the byte count otherwise — so a room that cannot
- * keep up parks its newest frame here and every earlier one is dropped, rather than queueing behind the
- * slowest subscriber until the send buffer is the stream. Bun fires `drain` per socket when its buffer
- * empties; that is what flushes the parked frames.
- */
 export class BinaryPubsub {
   readonly #logger = new Logger("BinaryPubsub");
   readonly #pending = new Map<string, Uint8Array>();
@@ -27,7 +20,6 @@ export class BinaryPubsub {
     this.#pending.set(roomId, frame);
   }
 
-  /** Retries every parked room. A room still backpressured re-parks itself and waits for the next drain. */
   flush() {
     if (!this.#pending.size) return;
     for (const [roomId, frame] of [...this.#pending]) {
@@ -40,7 +32,6 @@ export class BinaryPubsub {
     this.#pending.clear();
   }
 
-  /** True when at least one server refused the frame for backpressure, which is the only case worth parking. */
   #send(roomId: string, frame: Uint8Array): boolean {
     let backpressured = false;
     for (const server of this.#servers) {