akanjs 2.2.4-rc.5 → 2.2.4

package/server/routeTree.test.tsx

@@ -0,0 +1,198 @@
+import type { ReactNode } from "react";
+import { renderToReadableStream } from "react-dom/server.browser";
+import { RouteElementComposer } from "./routeElementComposer";
+import { RouteTreeBuilder } from "./routeTreeBuilder";
+
+async function renderToText(node: ReactNode): Promise<string> {
+  return new Response(await renderToReadableStream(node)).text();
+}
+
+describe("RouteTreeBuilder implicit locale", () => {
+  test("matches locale-prefixed routes while keeping special routes at root", () => {
+    const routes = new RouteTreeBuilder({
+      "./__root_layout.tsx": async () => ({ default: ({ children }: { children: ReactNode }) => children }),
+      "./foo.tsx": async () => ({ default: () => null }),
+      "./robots.txt.tsx": async () => ({ default: () => null }),
+    }).build();
+
+    const matched = RouteTreeBuilder.match("/ko/foo", routes);
+    expect(matched?.params).toEqual({ lang: "ko" });
+    expect(matched?.pathRoute.path).toBe("/:lang/foo");
+    expect(matched?.pathRoute.renderRootLayouts).toHaveLength(1);
+
+    const robots = RouteTreeBuilder.match("/robots.txt", routes);
+    expect(robots?.params).toEqual({});
+    expect(robots?.pathRoute.isSpecialRoute).toBe(true);
+    expect(robots?.pathRoute.renderRootLayouts).toHaveLength(0);
+  });
+
+  test("uses the nearest route head without merging parents", async () => {
+    const prevBasePaths = process.env.AKAN_PUBLIC_BASE_PATHS;
+    process.env.AKAN_PUBLIC_BASE_PATHS = "foo";
+    try {
+      const routes = new RouteTreeBuilder({
+        "./__root_layout.tsx": async () => ({
+          default: ({ children }: { children: ReactNode }) => children,
+          head: "root",
+        }),
+        "./foo/__root_layout.tsx": async () => ({
+          default: ({ children }: { children: ReactNode }) => children,
+          head: "foo-root",
+        }),
+        "./foo/bar.tsx": async () => ({ default: () => null }),
+        "./foo/baz.tsx": async () => ({ default: () => null, head: "baz-page" }),
+      }).build();
+
+      const bar = RouteTreeBuilder.match("/ko/foo/bar", routes);
+      const baz = RouteTreeBuilder.match("/ko/foo/baz", routes);
+      expect(
+        bar &&
+          (await RouteElementComposer.resolveHead({ pathRoute: bar.pathRoute, params: bar.params, searchParams: {} })),
+      ).toBe("foo-root");
+      expect(
+        baz &&
+          (await RouteElementComposer.resolveHead({ pathRoute: baz.pathRoute, params: baz.params, searchParams: {} })),
+      ).toBe("baz-page");
+    } finally {
+      process.env.AKAN_PUBLIC_BASE_PATHS = prevBasePaths;
+    }
+  });
+
+  test("supports route groups, repeated search params, and cached lazy modules", async () => {
+    let loadCount = 0;
+    const routes = new RouteTreeBuilder({
+      "./__root_layout.tsx": async () => ({ default: ({ children }: { children: ReactNode }) => children }),
+      "./(marketing)/about.tsx": async () => {
+        loadCount += 1;
+        return { default: () => null, head: "about" };
+      },
+    }).build();
+    const matched = RouteTreeBuilder.match("/ko/about", routes);
+
+    expect(matched?.pathRoute.path).toBe("/:lang/about");
+    expect(RouteTreeBuilder.parseSearchParams("?tag=a&tag=b&sort=latest")).toEqual({
+      tag: ["a", "b"],
+      sort: "latest",
+    });
+
+    expect(
+      matched &&
+        (await RouteElementComposer.resolveHead({
+          pathRoute: matched.pathRoute,
+          params: matched.params,
+          searchParams: {},
+        })),
+    ).toBe("about");
+    expect(
+      matched &&
+        (await RouteElementComposer.resolveHead({
+          pathRoute: matched.pathRoute,
+          params: matched.params,
+          searchParams: {},
+        })),
+    ).toBe("about");
+    expect(loadCount).toBe(1);
+    expect(RouteTreeBuilder.getCacheStats()).toMatchObject({
+      moduleCount: 2,
+      loadedModuleCount: 1,
+      cacheHits: 1,
+      cacheMisses: 1,
+    });
+  });
+
+  test("rejects duplicate route patterns and unsupported page exports", () => {
+    expect(() =>
+      new RouteTreeBuilder({
+        "./users/[id].tsx": async () => ({ default: () => null }),
+        "./users/:id.tsx": async () => ({ default: () => null }),
+      }).build(),
+    ).toThrow();
+
+    const routes = new RouteTreeBuilder({
+      "./bad.tsx": async () => ({ default: () => null, loader: () => null }) as never,
+    }).build();
+    const matched = RouteTreeBuilder.match("/ko/bad", routes);
+
+    expect(
+      matched &&
+        RouteElementComposer.resolveHead({ pathRoute: matched.pathRoute, params: matched.params, searchParams: {} }),
+    ).rejects.toThrow('[route-convention] unsupported export "loader"');
+
+    const routesWithBadFallback = new RouteTreeBuilder({
+      "./bad-fallback.tsx": async () => ({ default: () => null, NotFound: () => null }) as never,
+    }).build();
+    const badFallback = RouteTreeBuilder.match("/ko/bad-fallback", routesWithBadFallback);
+    expect(
+      badFallback &&
+        RouteElementComposer.resolveHead({
+          pathRoute: badFallback.pathRoute,
+          params: badFallback.params,
+          searchParams: {},
+        }),
+    ).rejects.toThrow('[route-convention] unsupported export "NotFound"');
+  });
+
+  test("composes nearest layout NotFound and Error fallbacks", async () => {
+    const builder = new RouteTreeBuilder({
+      "./__root_layout.tsx": async () => ({
+        default: ({ children }: { children: ReactNode }) => <main>root:{children}</main>,
+        NotFound: ({ pathname }: { pathname: string }) => <p>root missing {pathname}</p>,
+      }),
+      "./docs/_layout.tsx": async () => ({
+        default: ({ children }: { children: ReactNode }) => <section>docs:{children}</section>,
+        NotFound: ({ pathname, params }: { pathname: string; params: Record<string, string> }) => (
+          <p>
+            docs missing {params.lang}:{pathname}
+          </p>
+        ),
+        Error: ({ error }: { error?: unknown }) => (
+          <p>docs error {error instanceof Error ? error.message : "unknown"}</p>
+        ),
+      }),
+      "./docs/guide.tsx": async () => ({ default: () => <article>guide</article> }),
+    });
+    const routes = builder.build();
+    const matched = RouteTreeBuilder.match("/ko/docs/guide", routes);
+    if (!matched) throw new Error("route did not match");
+
+    const notFound = await RouteElementComposer.composeFallback({
+      kind: "not-found",
+      route: matched.pathRoute,
+      params: matched.params,
+      searchParams: {},
+      pathname: "/ko/docs/guide",
+    });
+    const error = await RouteElementComposer.composeFallback({
+      kind: "error",
+      route: matched.pathRoute,
+      params: matched.params,
+      searchParams: {},
+      pathname: "/ko/docs/guide",
+      error: new Error("boom"),
+    });
+
+    const notFoundHtml = await renderToText(notFound);
+    const errorHtml = await renderToText(error);
+    expect(notFoundHtml).toContain("root:");
+    expect(notFoundHtml).toContain("docs:");
+    expect(notFoundHtml).toContain("docs missing");
+    expect(notFoundHtml).toContain("/ko/docs/guide");
+    expect(errorHtml).toContain("docs error");
+    expect(errorHtml).toContain("boom");
+
+    const unmatched = RouteTreeBuilder.matchFallback("/ko/docs/missing/path", builder.getFallbackRoutes());
+    expect(unmatched?.fallbackRoute.path).toBe("/:lang/docs");
+    const unmatchedNotFound =
+      unmatched &&
+      (await RouteElementComposer.composeFallback({
+        kind: "not-found",
+        route: unmatched.fallbackRoute,
+        params: unmatched.params,
+        searchParams: {},
+        pathname: "/ko/docs/missing/path",
+      }));
+    const unmatchedHtml = await renderToText(unmatchedNotFound);
+    expect(unmatchedHtml).toContain("docs missing");
+    expect(unmatchedHtml).toContain("/ko/docs/missing/path");
+  });
+});

package/server/routing/apiRouter.test.ts

@@ -0,0 +1,136 @@
+import { getDefaultInjectRegistry } from "akanjs/service";
+import { AkanResponse, WebProxyRunner } from "../proxy";
+import type { HttpRoutes, WebsocketRoutes } from "../types";
+
+describe("ApiRouter.buildRoutes", () => {
+  test("keeps the global prefix by default", async () => {
+    process.env.AKAN_PUBLIC_APP_NAME = "test";
+    const { ApiRouter } = await import("./apiRouter");
+    const routes = ApiRouter.buildRoutes({
+      prefix: "/api",
+      websocketPrefix: "/ws",
+      routes: { "/admin/ping": () => new Response("ok") } as HttpRoutes,
+      renderEnvRoutes: {},
+      upgradeAppWs: () => false,
+    });
+
+    expect(Object.keys(routes)).toContain("/api/admin/ping");
+  });
+
+  test("allows selected endpoints to skip the global prefix", async () => {
+    process.env.AKAN_PUBLIC_APP_NAME = "test";
+    const { ApiRouter } = await import("./apiRouter");
+    const routes = ApiRouter.buildRoutes({
+      prefix: "/api",
+      websocketPrefix: "/ws",
+      routes: { "/sitemap.xml": () => new Response("ok") } as HttpRoutes,
+      routeOptions: { "/sitemap.xml": { globalPrefix: false } },
+      renderEnvRoutes: { "/*": () => new Response("fallback") } as HttpRoutes,
+      upgradeAppWs: () => false,
+    });
+
+    expect(Object.keys(routes)).toContain("/sitemap.xml");
+    expect(Object.keys(routes)).not.toContain("/api/sitemap.xml");
+  });
+
+  test("wraps only render routes with the web proxy runner", async () => {
+    process.env.AKAN_PUBLIC_APP_NAME = "test";
+    const { ApiRouter } = await import("./apiRouter");
+    class RewriteRenderProxy {
+      static refName = "rewriteRenderProxy";
+      use() {
+        return AkanResponse.rewrite("http://localhost/rendered", { request: { headers: { "x-proxy": "1" } } });
+      }
+    }
+    const routes = ApiRouter.buildRoutes({
+      prefix: "/api",
+      websocketPrefix: "/ws",
+      routes: { "/ping": () => Response.json("api") } as HttpRoutes,
+      renderEnvRoutes: {
+        "/*": (req) => Response.json({ url: req.url, proxy: req.headers.get("x-proxy") }),
+      } as HttpRoutes,
+      upgradeAppWs: () => false,
+      webProxyRunner: new WebProxyRunner([RewriteRenderProxy]),
+    });
+
+    expect(await (await (routes["/api/ping"] as () => Response)()).json()).toBe("api");
+    const renderResponse = await (routes["/*"] as (req: Request) => Response | Promise<Response>)(
+      new Request("http://localhost/dashboard"),
+    );
+    expect(await renderResponse.json()).toEqual({ url: "http://localhost/rendered", proxy: "1" });
+  });
+});
+
+describe("ApiRouter.buildWebsocketHandlers", () => {
+  test("dispatches app websocket messages and returns route errors", async () => {
+    process.env.AKAN_PUBLIC_APP_NAME = "test";
+    const { ApiRouter } = await import("./apiRouter");
+    const sent: string[] = [];
+    const loggerErrors: string[] = [];
+    const ws = {
+      data: {},
+      send: (message: string) => sent.push(message),
+    } as unknown as Bun.ServerWebSocket<unknown>;
+    const handlers = ApiRouter.buildWebsocketHandlers({
+      wsRoutes: {
+        echo: async (_ws, data, event) => ({ event, data }),
+      } as WebsocketRoutes,
+      registry: getDefaultInjectRegistry(),
+      hmrHub: null,
+      hmrState: null,
+      logger: { error: (message: string) => loggerErrors.push(message) } as never,
+    });
+
+    await handlers.message?.(ws, JSON.stringify({ key: "echo", data: ["hello"] }));
+    const originalConsoleError = console.error;
+    console.error = () => undefined;
+    try {
+      await handlers.message?.(ws, JSON.stringify({ key: "missing", data: [] }));
+    } finally {
+      console.error = originalConsoleError;
+    }
+
+    expect(JSON.parse(sent[0] ?? "{}")).toEqual({ event: "message", data: ["hello"] });
+    expect(JSON.parse(sent[1] ?? "{}").error).toBe('WebSocket route "missing" is not registered');
+    expect(loggerErrors).toEqual(['WebSocket route "missing" is not registered']);
+  });
+
+  test("keeps HMR websocket traffic separate from app signal routes", async () => {
+    process.env.AKAN_PUBLIC_APP_NAME = "test";
+    const { ApiRouter } = await import("./apiRouter");
+    const sent: string[] = [];
+    let attached = false;
+    let detached = false;
+    const ws = {
+      data: { kind: "akan-hmr" },
+      send: (message: string) => sent.push(message),
+    } as unknown as Bun.ServerWebSocket<unknown>;
+    const handlers = ApiRouter.buildWebsocketHandlers({
+      wsRoutes: {
+        hmrShouldNotRun: () => {
+          throw new Error("should not run");
+        },
+      } as WebsocketRoutes,
+      registry: getDefaultInjectRegistry(),
+      hmrHub: {
+        attach: () => {
+          attached = true;
+        },
+        detach: () => {
+          detached = true;
+        },
+      } as never,
+      hmrState: { state: { buildId: 7, cssAssets: {} } },
+      logger: { error: () => undefined } as never,
+    });
+
+    handlers.open?.(ws);
+    await handlers.message?.(ws, JSON.stringify({ key: "hmrShouldNotRun" }));
+    handlers.close?.(ws);
+
+    expect(attached).toBe(true);
+    expect(detached).toBe(true);
+    expect(JSON.parse(sent[0] ?? "{}")).toEqual({ type: "hello", buildId: 7, cssAssets: {} });
+    expect(sent).toHaveLength(1);
+  });
+});

package/server/routing/apiRouter.ts

@@ -109,7 +109,9 @@ export class ApiRouter {
   }: WebsocketHandlersInputs): Bun.WebSocketHandler<WsTaggedData> {
     return {
       open: (ws) => {
-
+        // HMR sockets live in a separate logical channel from the app's signal
+        // websockets. We tag them via `data.kind === "akan-hmr"` at upgrade
+        // time so the dispatcher can skip signal handling.
         const data = ws.data as WsTaggedData | undefined;
         if (data?.kind === "akan-hmr" && hmrHub && hmrState) {
           hmrHub.attach(ws as unknown as Bun.ServerWebSocket<HmrWsData>);
@@ -126,7 +128,7 @@ export class ApiRouter {
       },
       message: async (ws, message) => {
         const data = ws.data as WsTaggedData | undefined;
-        if (data?.kind === "akan-hmr") return; 
+        if (data?.kind === "akan-hmr") return; // dev HMR is one-way (server→client)
         try {
           if (typeof message === "string") {
             const msg = JSON.parse(message) as WebsocketReqData;

package/server/rscClient.tsx

@@ -67,7 +67,13 @@ async function fetchRsc(href: string, options: { buildId?: number } = {}): Promi
     return { type: "redirected" };
   }
   if (!res.ok || !res.body) throw new Error(`[rscClient] RSC fetch failed ${res.status} ${res.statusText}`);
-
+  // Buffer the entire Flight payload before constructing the thenable. The root
+  // `use(thenable)` lives at the document root with no Suspense boundary above it
+  // (see Root / ssrFromRscRenderer), so any mid-render suspension during a client
+  // navigation transition has no fallback and can leave the transition stuck —
+  // committing only when a later navigation flushes the pending lane. Materializing
+  // the payload up front means all RSC rows are present and every referenced client
+  // module `import()` starts immediately, so the committed render does not suspend.
   const buffer = await res.arrayBuffer();
   const completeStream = new ReadableStream<Uint8Array>({
     start(controller) {

package/server/rscWorkerHost.ts

@@ -98,7 +98,9 @@ export class RscWorker {
 
   #status: WorkerStatus = "starting";
   #killed = false;
-
+  // Render sends issued while the worker is starting / restarting are queued
+  // here and flushed on the next `ready`. Each closure re-checks `#pending` so
+  // cancelled streams don't forward a stale request to the new worker.
   #queuedSends: Array<() => void> = [];
   #restartAttempts = 0;
   #restartCount = 0;
@@ -138,7 +140,9 @@ export class RscWorker {
 
   render(req: Request): ReadableStream<Uint8Array> {
     const requestId = crypto.randomUUID();
-
+    // Serialize headers so the worker can rebuild a Request mirror inside its
+    // own `requestStorage` scope. Without this, server components running in
+    // the worker cannot read cookies/auth headers of the incoming request.
     const headers: Array<[string, string]> = [];
     req.headers.forEach((value, key) => {
       headers.push([key, value]);
@@ -152,7 +156,10 @@ export class RscWorker {
           onError: (msg) => controller.error(new Error(msg)),
         });
         const send = () => {
-
+          // The stream may have been cancelled, or the worker may have died
+          // again between queueing and flushing — both cases drop silently
+          // (the pending entry is already gone / will be handled by the exit
+          // path).
           if (!this.#pending.has(requestId)) return;
           try {
             this.#proc.send({ type: "render", requestId, url: req.url, method: req.method, headers });
@@ -305,6 +312,8 @@ export class RscWorker {
     try {
       this.#proc.send({ type: "updateCssAssets", cssAssets });
     } catch {
+      // If the worker died mid-send we'll pick up the new value on the next
+      // `hello` after restart; nothing to do here.
     }
   }
 
@@ -320,10 +329,15 @@ export class RscWorker {
     this.#cssAssets = input.cssAssets ?? this.#cssAssets;
     this.#pagesBundleBuildId = input.buildId;
     if (input.pagesBundlePath) this.#pagesBundlePath = input.pagesBundlePath;
-
+    // While restarting / starting, the new worker will pick up the latest
+    // `#clientManifest` / `#cssAssets` / `#pagesBundlePath` via the `init` reply
+    // to its first `hello`, so callers don't need to wait on an explicit
+    // `reloaded` ack.
     if (this.#status !== "ready") return Promise.resolve();
     return new Promise<void>((resolve, reject) => {
-
+      // If a previous reload was still in flight, supersede it — the latest
+      // build strictly implies the earlier one completed from the caller's
+      // perspective.
       if (this.#pendingReload) this.#pendingReload.resolve();
       this.#pendingReload = { resolve, reject, targetBuildId: input.buildId };
       try {
@@ -372,7 +386,10 @@ export class RscWorker {
     if (proc !== this.#proc) return;
     switch (message.type) {
       case "hello":
-
+        // Re-injecting `#clientManifest` / `#cssAssets` here is what makes crash
+        // recovery transparent: after a respawn the new worker's first act is
+        // to ask for config, and it receives the latest manifest the host has
+        // accumulated via `reload(...)`.
         this.#proc.send({
           type: "init",
           clientManifest: this.#clientManifest,
@@ -417,7 +434,8 @@ export class RscWorker {
         return;
       case "error":
         if (message.requestId === "__init__") {
-
+          // Init errors are surfaced on `ready` only for the very first spawn;
+          // subsequent restarts swallow them and let exponential backoff retry.
           if (!this.#readyResolved) this.#rejectReady(new Error(String(message.message)));
           else this.#logger.error(`[rsc] worker init error on restart: ${message.message}`);
           return;
@@ -491,7 +509,9 @@ export class RscWorker {
   }
 
   #handleExit(proc: Bun.Subprocess<"ignore", "inherit", "inherit">, code: number | null): void {
-
+    // Stale exits from a proc we've already replaced can still fire if the
+    // old subprocess was slow to cleanup; ignore them so we don't
+    // double-schedule a restart.
     if (proc !== this.#proc) return;
 
     const err = new Error(`rsc worker exited with code ${code}`);
@@ -501,7 +521,8 @@ export class RscWorker {
       this.#pendingReload.reject(err);
       this.#pendingReload = null;
     }
-
+    // Drop any sends that were queued against the dead worker. Callers own
+    // their streams and will see the `onError` above.
     this.#queuedSends = [];
 
     if (this.#killed) {
@@ -518,7 +539,7 @@ export class RscWorker {
       this.#status = "stopped";
       const msg = `[rsc] worker failed ${attempt} restarts; giving up. SSR will return errors until the server restarts.`;
       this.#logger.error(msg);
-      
+      // Surface a rejection on the initial `ready` if we never succeeded.
       this.#rejectReady(new Error(msg));
       return;
     }
@@ -588,9 +609,10 @@ export class RscWorker {
         const raw = fs.readFileSync(filePath, "utf8").trim();
         if (!raw || raw === "max") continue;
         const parsed = Number.parseInt(raw, 10);
-        
+        // Ignore host-level sentinel values that are effectively unlimited.
         if (Number.isFinite(parsed) && parsed > 0 && parsed < 1024 ** 5) return parsed;
       } catch {
+        // cgroup files are best-effort; explicit env thresholds still work.
       }
     }
     return null;

package/server/sitemap.test.ts

@@ -0,0 +1,61 @@
+import { createDefaultSitemapUrls, createSitemapXml, getSitemapBasePath } from "./sitemap";
+
+describe("sitemap fallback helpers", () => {
+  const i18n = { defaultLocale: "en", locales: ["en", "ko"] };
+
+  test("creates escaped XML with unique sorted URLs", () => {
+    const xml = createSitemapXml(["https://example.com/b?x=1&y=2", "https://example.com/a", "https://example.com/a"]);
+
+    expect(xml).toContain("<loc>https://example.com/a</loc>");
+    expect(xml).toContain("<loc>https://example.com/b?x=1&amp;y=2</loc>");
+    expect(xml.match(/<url>/g)).toHaveLength(2);
+  });
+
+  test("expands only static locale routes", () => {
+    const urls = createDefaultSitemapUrls({
+      origin: "https://example.com",
+      entries: [
+        { routeId: "/:lang", pattern: "/:lang", seeds: [] },
+        { routeId: "/:lang/about", pattern: "/:lang/about", seeds: [] },
+        { routeId: "/:lang/post/:postId", pattern: "/:lang/post/:postId", seeds: [] },
+        { routeId: "/robots.txt", pattern: "/robots.txt", seeds: [] },
+      ],
+      i18n,
+    });
+
+    expect(urls).toEqual([
+      "https://example.com/en",
+      "https://example.com/ko",
+      "https://example.com/en/about",
+      "https://example.com/ko/about",
+    ]);
+  });
+
+  test("uses base path only for filtering subroute sitemap entries", () => {
+    const urls = createDefaultSitemapUrls({
+      origin: "https://example.com/",
+      basePath: "akanjs",
+      entries: [
+        { routeId: "/:lang/akanjs", pattern: "/:lang/akanjs", seeds: [] },
+        { routeId: "/:lang/akanjs/about", pattern: "/:lang/akanjs/about", seeds: [] },
+        { routeId: "/:lang/thin/about", pattern: "/:lang/thin/about", seeds: [] },
+        { routeId: "/:lang/akanjs/post/:postId", pattern: "/:lang/akanjs/post/:postId", seeds: [] },
+      ],
+      i18n,
+    });
+
+    expect(urls).toEqual([
+      "https://example.com/en",
+      "https://example.com/ko",
+      "https://example.com/en/about",
+      "https://example.com/ko/about",
+    ]);
+  });
+
+  test("recognizes root and subroute sitemap paths", () => {
+    expect(getSitemapBasePath("/sitemap.xml", [])).toBeNull();
+    expect(getSitemapBasePath("/sitemap.xml", ["akanjs"])).toBeUndefined();
+    expect(getSitemapBasePath("/sitemap.xml", ["akanjs"], "akanjs")).toBe("akanjs");
+    expect(getSitemapBasePath("/akanjs/sitemap.xml", ["akanjs"], "akanjs")).toBeUndefined();
+  });
+});

package/server/ssrFromRscRenderer.tsx

@@ -12,6 +12,11 @@ export class SsrFromRscRenderer {
     ssrChunkCacheHitCount: 0,
   };
 
+  // Inline bootstrap that runs as a classic script BEFORE any <script type="module">.
+  // - Installs the webpack runtime shims that react-server-dom-webpack/client.browser
+  //   needs at module initialization time.
+  // - Creates a tiny queue so <script>self.__RSC_PUSH__(...)</script> tags
+  //   emitted after the HTML shell can be buffered until rscClient picks them up.
   static readonly #clientBootstrap = `(function(){
   var registry = new Map();
   function load(id) {
@@ -53,7 +58,8 @@ export class SsrFromRscRenderer {
   }
 
   async render(input: SsrFromRscInput): Promise<ReadableStream<Uint8Array>> {
-
+    // Split the RSC stream: one branch drives the server-side SSR render, the
+    // other is relayed to the client as inline <script> tags for hydration.
     const [rscForSsr, rscForClient] = input.rscStream.tee();
 
     const ssrNodeStream = Readable.fromWeb(rscForSsr as never);
@@ -97,6 +103,19 @@ export class SsrFromRscRenderer {
     if (g.__rsc_ssr_shims_installed__) return;
     g.__rsc_ssr_shims_installed__ = true;
 
+    // SSR-side webpack runtime shims. We use dynamic `import()` rather than
+    // `require()` because client component chunks may transitively use
+    // top-level await, which Bun's `require()` refuses to load.
+    //
+    // `chunks`/`id` entries in the ssrManifest are absolute filesystem paths
+    // to server-importable client chunks. These may differ from the browser
+    // chunks referenced by the Flight client manifest because the browser build
+    // can rely on import maps while this SSR pass is loaded directly by Bun.
+    // HMR cache-busting is filename-based: each rebuild emits a new
+    // content-hashed chunk filename, which means a new import
+    // specifier, which bypasses Bun's module cache naturally. The
+    // `?v=<digits>` stripping below is defensive for any caller that still
+    // appends a version query to keep the pre-existing registry keys stable.
     const registry = new Map<string, Record<string, unknown>>();
     g.__webpack_chunk_load__ = async (chunkId: string) => {
       if (registry.has(chunkId)) {
@@ -187,7 +206,8 @@ export class SsrFromRscRenderer {
             if (tail) controller.enqueue(encoder.encode(tail));
             return;
           }
-
+          // `<head>` never appeared — e.g. error shell. Emit buffered bytes
+          // verbatim so we don't swallow the document.
           const tail = decoder.decode();
           const rest = withHtmlTheme(buffered + tail);
           if (rest) controller.enqueue(encoder.encode(rest));
@@ -200,10 +220,20 @@ export class SsrFromRscRenderer {
     return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
   }
 
+  // React-server-dom-webpack/server emits a Flight hint of the form
+  // `:HL["<href>","stylesheet"]\n` for every `<link rel="stylesheet">` in the
+  // server tree. That string is forwarded verbatim to the browser which then
+  // calls `ReactDOM.preload(href, "stylesheet")`, creating an invalid
+  // `<link rel="preload" as="stylesheet">` (valid preload `as` is `"style"`).
+  // The SSR-side Fizz dispatcher happens to tolerate this, but Chromium logs
+  // `<link rel=preload> must have a valid "as" value`. Rewrite the hint for
+  // the browser-bound stream to use the spec-correct `"style"`; the SSR-bound
+  // tee is left untouched so we don't alter React's server behavior.
   static #sanitizeFlightForClient(stream: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
     const decoder = new TextDecoder();
     const encoder = new TextEncoder();
-
+    // Matches just the trailing `,"stylesheet"]` of an HL hint line. The href is
+    // left alone; only the `as` slot is rewritten.
     const hlStylesheetRe = /(:HL\["[^"\\]*(?:\\.[^"\\]*)*",)"stylesheet"(\])/g;
 
     return stream.pipeThrough(
@@ -253,6 +283,8 @@ export class SsrFromRscRenderer {
             reader.releaseLock();
           }
 
+          // Inline RSC scripts must not be interleaved with arbitrary HTML bytes:
+          // Fizz may split inside SVG path data or attributes, corrupting markup.
           const rscReader = rscClientStream.getReader();
           try {
             while (true) {