akanjs 2.2.4-rc.4 → 2.2.4

package/server/artifact/routeClientCache.test.ts

@@ -0,0 +1,265 @@
+import { describe, expect, test } from "bun:test";
+import { RouteClientCache } from "./routeClientCache";
+import type { RoutesManifest } from "./routesManifestStore";
+
+const emptySsrManifest = { moduleLoading: null, moduleMap: {} };
+
+describe("RouteClientCache", () => {
+  test("seeds existing manifests and returns isolated snapshots", async () => {
+    const manifest: RoutesManifest = {
+      routeIds: ["/seeded"],
+      clientManifest: {
+        "apps/demo/Page.tsx#default": {
+          id: "/_akan/client/page.js",
+          chunks: ["/_akan/client/page.js"],
+          name: "default",
+          async: true,
+        },
+      },
+      ssrManifest: {
+        moduleLoading: null,
+        moduleMap: { "/_akan/client/page.js": { default: { id: "page.ssr.js", chunks: [], name: "default" } } },
+      },
+      knownEntries: ["/repo/apps/demo/Page.tsx"],
+    };
+    const cache = new RouteClientCache({
+      buildRoute: async () => {
+        throw new Error("seeded routes should not rebuild");
+      },
+    });
+
+    cache.seed(manifest);
+    await cache.ensure("/seeded", []);
+    const snapshot = cache.snapshot();
+    snapshot.knownEntries.add("/mutated");
+
+    expect(cache.snapshot().knownEntries.has("/mutated")).toBe(false);
+    expect(cache.snapshot().clientManifest).toEqual(manifest.clientManifest);
+  });
+
+  test("deduplicates concurrent builds and retries failures", async () => {
+    let attempts = 0;
+    const cache = new RouteClientCache({
+      buildRoute: async (routeId, info) => {
+        attempts += 1;
+        if (attempts === 1) throw new Error("boom");
+        return {
+          manifestDelta: {
+            [`${routeId}#default`]: {
+              id: `/_akan/client/${attempts}.js`,
+              chunks: [`/_akan/client/${attempts}.js`],
+              name: "default",
+            },
+          },
+          ssrManifestDelta: emptySsrManifest,
+          newEntries: [...info.knownEntries, `/repo${routeId}.tsx`],
+          clientDeps: [],
+        };
+      },
+    });
+
+    await expect(cache.ensure("/retry", [])).rejects.toThrow("boom");
+    const [first, second] = await Promise.all([cache.ensure("/retry", []), cache.ensure("/retry", [])]);
+
+    expect(first).toBe(second);
+    expect(attempts).toBe(2);
+    expect(cache.snapshot().knownEntries.has("/repo/retry.tsx")).toBe(true);
+  });
+
+  test("invalidates built routes, ignores stale builds, and clears generations", async () => {
+    let resolveBuild:
+      | ((value: Awaited<ReturnType<Parameters<typeof RouteClientCache>[0]["buildRoute"]>>) => void)
+      | null = null;
+    const cache = new RouteClientCache({
+      buildRoute: async (routeId, { generation }) =>
+        await new Promise((resolve) => {
+          resolveBuild = () =>
+            resolve({
+              manifestDelta: { [`${routeId}#${generation}`]: { id: "stale.js", chunks: [], name: "default" } },
+              ssrManifestDelta: emptySsrManifest,
+              newEntries: [`/repo/${routeId}-${generation}.tsx`],
+              clientDeps: [],
+            });
+        }),
+    });
+
+    const pending = cache.ensure("/slow", []);
+    expect(cache.clear()).toEqual([]);
+    resolveBuild?.({ manifestDelta: {}, ssrManifestDelta: emptySsrManifest, newEntries: [], clientDeps: [] });
+    await pending;
+
+    expect(cache.snapshot().clientManifest).toEqual({});
+    expect(cache.snapshot().knownEntries.size).toBe(0);
+
+    const immediate = new RouteClientCache({
+      buildRoute: async (routeId) => ({
+        manifestDelta: { [routeId]: { id: "fresh.js", chunks: [], name: "default" } },
+        ssrManifestDelta: emptySsrManifest,
+        newEntries: [`/repo/${routeId}.tsx`],
+        clientDeps: [],
+      }),
+    });
+    await immediate.ensure("/a", []);
+    await immediate.ensure("/b", []);
+    expect(immediate.invalidate((routeId) => routeId === "/a")).toEqual(["/a"]);
+    expect(immediate.snapshot().knownEntries).toEqual(new Set(["/repo//a.tsx", "/repo//b.tsx"]));
+    expect(immediate.clear().sort()).toEqual(["/b"]);
+    expect(immediate.snapshot().generation).toBe(2);
+  });
+
+  test("client entry invalidation drops only stale entries and manifest rows", async () => {
+    const cache = new RouteClientCache({
+      buildRoute: async (routeId) => ({
+        manifestDelta: {
+          [`/repo${routeId}.tsx#default`]: {
+            id: `/_akan/client${routeId}.js`,
+            chunks: [`/_akan/client${routeId}.js`, `/_akan/client/chunk${routeId}.js`],
+            name: "default",
+          },
+        },
+        ssrManifestDelta: {
+          moduleLoading: null,
+          moduleMap: {
+            [`/_akan/client${routeId}.js`]: {
+              default: { id: `ssr${routeId}.js`, chunks: [], name: "default" },
+            },
+          },
+        },
+        newEntries: [`/repo${routeId}.tsx`],
+        clientDeps: [],
+      }),
+    });
+    await cache.ensure("/a", []);
+    await cache.ensure("/b", []);
+
+    expect(
+      cache.invalidateClientEntries({
+        routePredicate: (routeId) => routeId === "/a",
+        staleEntries: ["/repo/a.tsx"],
+      }),
+    ).toEqual(["/a"]);
+
+    const snapshot = cache.snapshot();
+    expect(snapshot.knownEntries).toEqual(new Set(["/repo/b.tsx"]));
+    expect(snapshot.clientManifest["/repo/a.tsx#default"]).toBeUndefined();
+    expect(snapshot.clientManifest["/repo/b.tsx#default"]).toBeDefined();
+    expect(snapshot.ssrManifest.moduleMap["/_akan/client/a.js"]).toBeUndefined();
+    expect(snapshot.ssrManifest.moduleMap["/_akan/client/b.js"]).toBeDefined();
+  });
+
+  test("route invalidation preserves known entries and manifest rows for server-only edits", async () => {
+    const cache = new RouteClientCache({
+      buildRoute: async (routeId) => ({
+        manifestDelta: {
+          [`/repo${routeId}.tsx#default`]: {
+            id: `/_akan/client${routeId}.js`,
+            chunks: [`/_akan/client${routeId}.js`],
+            name: "default",
+          },
+        },
+        ssrManifestDelta: emptySsrManifest,
+        newEntries: [`/repo${routeId}.tsx`],
+        clientDeps: [],
+      }),
+    });
+    await cache.ensure("/a", []);
+
+    expect(cache.invalidate((routeId) => routeId === "/a")).toEqual(["/a"]);
+    const snapshot = cache.snapshot();
+    expect(snapshot.knownEntries).toEqual(new Set(["/repo/a.tsx"]));
+    expect(snapshot.clientManifest["/repo/a.tsx#default"]).toBeDefined();
+  });
+
+  test("client entry invalidation also removes rows by stale chunk urls", async () => {
+    const cache = new RouteClientCache({
+      buildRoute: async () => ({
+        manifestDelta: {
+          "/repo/Entry.tsx#default": {
+            id: "/_akan/client/entry.js",
+            chunks: ["/_akan/client/entry.js", "/_akan/client/shared.js"],
+            name: "default",
+          },
+          "/repo/Entry.tsx#Named": {
+            id: "/_akan/client/shared.js",
+            chunks: ["/_akan/client/shared.js"],
+            name: "Named",
+          },
+          "/repo/Other.tsx#default": {
+            id: "/_akan/client/other.js",
+            chunks: ["/_akan/client/other.js"],
+            name: "default",
+          },
+        },
+        ssrManifestDelta: {
+          moduleLoading: null,
+          moduleMap: {
+            "/_akan/client/entry.js": {
+              default: { id: "entry.ssr.js", chunks: [], name: "default" },
+            },
+            "/_akan/client/shared.js": {
+              Named: { id: "named.ssr.js", chunks: [], name: "Named" },
+            },
+            "/_akan/client/other.js": {
+              default: { id: "other.ssr.js", chunks: [], name: "default" },
+            },
+          },
+        },
+        newEntries: ["/repo/Entry.tsx", "/repo/Other.tsx"],
+        clientDeps: [],
+      }),
+    });
+    await cache.ensure("/a", []);
+
+    cache.invalidateClientEntries({
+      routePredicate: (routeId) => routeId === "/a",
+      staleEntries: ["/repo/Entry.tsx"],
+    });
+
+    const snapshot = cache.snapshot();
+    expect(Object.keys(snapshot.clientManifest).sort()).toEqual(["/repo/Other.tsx#default"]);
+    expect(Object.keys(snapshot.ssrManifest.moduleMap).sort()).toEqual(["/_akan/client/other.js"]);
+    expect(snapshot.knownEntries).toEqual(new Set(["/repo/Other.tsx"]));
+  });
+
+  test("shared entries can be discovered by later routes without rebuilding the shared entry", async () => {
+    const builds: Array<{ routeId: string; knownEntries: string[] }> = [];
+    const cache = new RouteClientCache({
+      buildRoute: async (routeId, { knownEntries }) => {
+        builds.push({ routeId, knownEntries: [...knownEntries].sort() });
+        if (routeId === "/a") {
+          return {
+            manifestDelta: {
+              "/repo/Shared.tsx#default": {
+                id: "/_akan/client/shared.js",
+                chunks: ["/_akan/client/shared.js"],
+                name: "default",
+              },
+            },
+            ssrManifestDelta: emptySsrManifest,
+            newEntries: ["/repo/Shared.tsx"],
+            discoveredEntries: ["/repo/Shared.tsx"],
+            clientDeps: ["/repo/Shared.tsx"],
+            clientDepsByEntry: { "/repo/Shared.tsx": ["/repo/Shared.tsx"] },
+          };
+        }
+        return {
+          manifestDelta: {},
+          ssrManifestDelta: emptySsrManifest,
+          newEntries: [],
+          discoveredEntries: ["/repo/Shared.tsx"],
+          clientDeps: [],
+          clientDepsByEntry: {},
+        };
+      },
+    });
+
+    await cache.ensure("/a", []);
+    await cache.ensure("/b", []);
+
+    expect(builds).toEqual([
+      { routeId: "/a", knownEntries: [] },
+      { routeId: "/b", knownEntries: ["/repo/Shared.tsx"] },
+    ]);
+    expect(cache.snapshot().knownEntries).toEqual(new Set(["/repo/Shared.tsx"]));
+  });
+});

package/server/artifact/routeSeedIndex.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+import { RouteSeedIndexStore } from "./routeSeedIndexStore";
+
+describe("route seed index artifact paths", () => {
+  test("restores relative seed paths from the artifact directory", () => {
+    const artifactDir = "/repo/dist/apps/akan/.akan/artifact";
+    const normalized = RouteSeedIndexStore.normalize(
+      {
+        entries: [
+          {
+            routeId: "/profile",
+            pattern: "/profile",
+            seeds: ["../generated/implicit-root-layout.tsx", "../../../../../apps/akan/page/profile.tsx"],
+          },
+        ],
+        globalLayoutFiles: ["../generated/implicit-root-layout.tsx"],
+      },
+      artifactDir,
+    );
+
+    expect(normalized.entries[0]?.seeds).toEqual([
+      "/repo/dist/apps/akan/.akan/generated/implicit-root-layout.tsx",
+      "/repo/apps/akan/page/profile.tsx",
+    ]);
+    expect(normalized.globalLayoutFiles).toEqual(["/repo/dist/apps/akan/.akan/generated/implicit-root-layout.tsx"]);
+  });
+
+  test("restores slim production seed index defaults", () => {
+    const normalized = RouteSeedIndexStore.normalize(
+      {
+        entries: [{ routeId: "/:lang/profile" }],
+      },
+      "/repo/dist/apps/akan/.akan/artifact",
+    );
+
+    expect(normalized).toEqual({
+      entries: [{ routeId: "/:lang/profile", pattern: "/:lang/profile", seeds: [] }],
+      globalLayoutFiles: [],
+    });
+    expect(RouteSeedIndexStore.match("/ko/profile", normalized.entries)?.entry.routeId).toBe("/:lang/profile");
+  });
+
+  test("finds the nearest route seed prefix for unmatched layout fallbacks", () => {
+    const entries = [
+      { routeId: "/:lang/blog", pattern: "/:lang/blog", seeds: ["blog-layout"] },
+      { routeId: "/:lang/blog/benchmark", pattern: "/:lang/blog/benchmark", seeds: ["benchmark-page"] },
+      { routeId: "/:lang/docs", pattern: "/:lang/docs", seeds: ["docs-layout"] },
+    ];
+
+    const matched = RouteSeedIndexStore.matchPrefix("/ko/blog/missing", entries);
+
+    expect(matched?.entry.routeId).toBe("/:lang/blog");
+    expect(matched?.params).toEqual({ lang: "ko" });
+    expect(RouteSeedIndexStore.matchPrefix("/ko/unknown/missing", entries)).toBeNull();
+  });
+});

package/server/artifact/routesManifest.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import { type RoutesManifest, RoutesManifestStore } from "./routesManifestStore";
+
+describe("routes manifest artifact paths", () => {
+  test("serializes file-system paths relative to the artifact directory and restores them", () => {
+    const artifactDir = "/repo/dist/apps/akan/.akan/artifact";
+    const clientEntry = "apps/akan/ui/ProfileCard.tsx#default";
+    const knownEntry = "/repo/apps/akan/ui/ProfileCard.tsx";
+    const ssrEntry = "/repo/dist/apps/akan/.akan/artifact/client-ssr/ProfileCard-abc.js";
+    const manifest: RoutesManifest = {
+      routeIds: ["/profile"],
+      clientManifest: {
+        [clientEntry]: {
+          id: "/_akan/client/abc.js",
+          chunks: ["/_akan/client/abc.js", "/_akan/client/chunks/def.js"],
+          name: "default",
+          async: true,
+        },
+      },
+      ssrManifest: {
+        moduleLoading: null,
+        moduleMap: {
+          "/_akan/client/abc.js": {
+            default: {
+              id: ssrEntry,
+              chunks: [ssrEntry, ssrEntry],
+              name: "default",
+              async: true,
+            },
+          },
+        },
+      },
+      knownEntries: [knownEntry],
+    };
+
+    const serialized = RoutesManifestStore.serialize(manifest, artifactDir);
+
+    expect(Object.keys(serialized.clientManifest)).toEqual(["apps/akan/ui/ProfileCard.tsx#default"]);
+    expect(serialized.clientManifest["apps/akan/ui/ProfileCard.tsx#default"]?.id).toBe("/_akan/client/abc.js");
+    expect(serialized.ssrManifest.moduleMap["/_akan/client/abc.js"]?.default.id).toBe("client-ssr/ProfileCard-abc.js");
+    expect(serialized.knownEntries).toEqual(["../../../../../apps/akan/ui/ProfileCard.tsx"]);
+    expect(JSON.stringify(serialized)).not.toContain("/repo/");
+
+    expect(RoutesManifestStore.normalize(serialized, artifactDir)).toEqual({
+      ...manifest,
+      clientManifest: serialized.clientManifest,
+      knownEntries: manifest.knownEntries,
+    });
+  });
+
+  test("normalizes manifests without production-only known entries", () => {
+    const artifactDir = "/repo/dist/apps/akan/.akan/artifact";
+    const normalized = RoutesManifestStore.normalize(
+      {
+        routeIds: ["/profile"],
+        clientManifest: {},
+        ssrManifest: { moduleLoading: null, moduleMap: {} },
+      },
+      artifactDir,
+    );
+
+    expect(normalized.knownEntries).toEqual([]);
+  });
+});

package/server/decorators.ts

@@ -1,4 +1,4 @@
-
+// TODO: Deprecate this decorators
 
 type DecoratedInstance = {
   logger?: { warn?: (message: string) => void; trace?: (message: string) => void };

package/server/di/diLifecycle.contract.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { BackendEnv } from "akanjs/base";
+import { SolidPubSub } from "akanjs/service";
+import { AkanLib } from "../akanLib";
+import { AkanOption } from "../akanOption";
+import { HostBasePathWebProxy, LocaleWebProxy } from "../proxy";
+import {
+  ServerResolverTestEndpoint,
+  ServerResolverTestInternal,
+  ServerResolverTestServerSignal,
+  ServerResolverTestSlice,
+  serverResolverTestConstant,
+  serverResolverTestDatabase,
+  serverResolverTestServiceModel,
+  validId,
+} from "../resolver/resolver.contract.fixture";
+
+describe("DiLifecycle declaration-to-runtime contract", () => {
+  test("prepends default web proxies before library proxies", async () => {
+    process.env.AKAN_PUBLIC_APP_NAME = "serverLifecycle";
+    process.env.AKAN_PUBLIC_REPO_NAME = "akan";
+    process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+    process.env.AKAN_PUBLIC_ENV = "local";
+    process.env.AKAN_PUBLIC_OPERATION_MODE = "local";
+    process.env.SERVER_MODE = "all";
+    process.env.NODE_ENV = "test";
+    const { DiLifecycle } = await import("./diLifecycle");
+
+    class CustomWebProxy {
+      static readonly refName = "CustomWebProxy";
+      use() {}
+    }
+
+    const env = {
+      repoName: "akan",
+      serveDomain: "example.com",
+      appName: "serverLifecycle",
+      environment: "local",
+      operationMode: "local",
+      tunnelUsername: "root",
+      tunnelPassword: "akan",
+    } satisfies BackendEnv;
+    const lib = new AkanLib("serverLifecycleTest", {
+      databases: [],
+      services: [],
+      scalars: [],
+      option: new AkanOption().applyWebProxy(CustomWebProxy),
+    });
+
+    const lifecycle = new DiLifecycle(env, "all", lib);
+
+    expect(lifecycle.webProxies).toEqual([LocaleWebProxy, HostBasePathWebProxy, CustomWebProxy]);
+  });
+
+  test("assembles AkanLib declarations into registry, live services, and routes", async () => {
+    process.env.AKAN_PUBLIC_APP_NAME = "serverLifecycle";
+    process.env.AKAN_PUBLIC_REPO_NAME = "akan";
+    process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+    process.env.AKAN_PUBLIC_ENV = "local";
+    process.env.AKAN_PUBLIC_OPERATION_MODE = "local";
+    process.env.SERVER_MODE = "all";
+    process.env.NODE_ENV = "test";
+    const { DiLifecycle } = await import("./diLifecycle");
+
+    const tmp = await mkdtemp(join(tmpdir(), "akan-server-di-"));
+    const env = {
+      repoName: "akan",
+      serveDomain: "example.com",
+      appName: "serverLifecycle",
+      environment: "local",
+      operationMode: "local",
+      tunnelUsername: "root",
+      tunnelPassword: "akan",
+      workspaceRoot: tmp,
+      database: {
+        sqlite: {
+          filePath: join(tmp, "akan.db"),
+          journalMode: "WAL",
+          busyTimeoutMs: 1000,
+          synchronous: "NORMAL",
+          foreignKeys: true,
+        },
+      },
+      solid: {
+        filePath: join(tmp, "solid.db"),
+        journalMode: "WAL",
+        busyTimeoutMs: 1000,
+        synchronous: "NORMAL",
+        cleanupIntervalMs: 60_000,
+        queuePollIntervalMs: 60_000,
+        queueLeaseMs: 30_000,
+      },
+    } satisfies BackendEnv & { workspaceRoot: string };
+    const lib = new AkanLib("serverLifecycleTest", {
+      databases: [
+        {
+          constant: serverResolverTestConstant,
+          database: serverResolverTestDatabase,
+          service: serverResolverTestServiceModel,
+          signal: {
+            endpoint: ServerResolverTestEndpoint,
+            slice: ServerResolverTestSlice,
+            internal: ServerResolverTestInternal,
+            server: ServerResolverTestServerSignal,
+          },
+        },
+      ],
+      services: [],
+      scalars: [],
+      option: new AkanOption(),
+    });
+    const lifecycle = new DiLifecycle(env, "all", lib);
+
+    try {
+      const routes = await lifecycle.initializeAll();
+
+      expect(lifecycle.registry.adaptorCls.has("serverResolverTestItemModel")).toBe(true);
+      expect(lifecycle.live.adaptor.has("serverResolverTestItemModel")).toBe(true);
+      expect(lifecycle.registry.serviceCls.has("serverResolverTestItem")).toBe(true);
+      expect(lifecycle.live.service.has("serverResolverTestItem")).toBe(true);
+      expect(lifecycle.registry.serverSignalCls.has("serverResolverTestItemSignal")).toBe(true);
+      expect(lifecycle.registry.internalCls.has("serverResolverTestItemInternal")).toBe(true);
+      expect(lifecycle.live.internal.has("serverResolverTestItemInternal")).toBe(true);
+      expect(lifecycle.registry.endpointCls.has("serverResolverTestItemEndpoint")).toBe(true);
+      expect(lifecycle.live.sliceCls.has("serverResolverTestItem")).toBe(true);
+
+      expect(Object.keys(routes.routes ?? {})).toEqual(
+        expect.arrayContaining([
+          "/getTitle/:id",
+          "/serverResolverTestItem/updateTitle/:id",
+          "/serverResolverTestItem/serverResolverTestItem/:serverResolverTestItemId",
+          "/serverResolverTestItem/serverResolverTestItemListInCategory",
+        ]),
+      );
+      expect(Object.keys(routes.wsRoutes ?? {})).toEqual(expect.arrayContaining(["roomFeed", "echoMessage"]));
+      expect(routes.routeOptions?.["/getTitle/:id"]).toEqual({ globalPrefix: false });
+
+      const service = lifecycle.live.service.get("serverResolverTestItem") as {
+        createServerResolverTestItem(data: Record<string, unknown>): Promise<Record<string, unknown>>;
+        listInCategory(...args: unknown[]): Promise<unknown[]>;
+      };
+      const created = await service.createServerResolverTestItem({
+        ownerId: validId,
+        category: "news",
+        title: "Alpha",
+        resolvedLabel: "resolved",
+        count: 1,
+        tags: ["featured"],
+        nested: { label: "Nested" },
+      });
+      expect(created).toMatchObject({
+        category: "news",
+        parentPostCreate: true,
+        childPostCreate: true,
+      });
+      expect(await service.listInCategory("news", false, { limit: 10 })).toHaveLength(1);
+
+      const websocket = lifecycle.registry.adaptor.get(SolidPubSub) as SolidPubSub | undefined;
+      expect(websocket).toBeDefined();
+    } finally {
+      await lifecycle.destroyAll();
+      await rm(tmp, { recursive: true, force: true });
+    }
+  });
+});

package/server/di/diLifecycle.ts

@@ -94,12 +94,12 @@ export class DiLifecycle {
       });
       this.webProxies.push(...lib.option.getWebProxies());
       lib.database.forEach((mod) => {
-        
+        //TODO: change enable as a function
         if (!mod.service.srv.enabled) return;
         this.#database.set(mod.constant.refName, mod);
       });
       lib.service.forEach((mod) => {
-        
+        //TODO: change enable as a function
         if (!mod.service.srv.enabled) return;
         this.#service.set(mod.service.srv.refName, mod);
       });
@@ -144,7 +144,7 @@ export class DiLifecycle {
     };
   }
   async destroyAll() {
-    
+    // 1. Run destroy internals (scheduled jobs, etc.)
     const internalNow = Date.now();
     this.logger.verbose("Running destroy internals...");
     try {
@@ -154,16 +154,19 @@ export class DiLifecycle {
     }
     this.logger.verbose(`Destroy internals in ${Date.now() - internalNow}ms`);
 
+    // 2. Destroy services (reverse order)
     const serviceNow = Date.now();
     this.logger.verbose("Destroying services...");
     await this.destroyServices();
     this.logger.verbose(`Destroy services in ${Date.now() - serviceNow}ms`);
 
+    // 3. Destroy adaptors (reverse order)
     const adaptorNow = Date.now();
     this.logger.verbose("Destroying adaptors...");
     await this.destroyAdaptors();
     this.logger.verbose(`Destroy adaptors in ${Date.now() - adaptorNow}ms`);
 
+    // 4. Destroy external uses (SDK clients, API wrappers, etc.)
     const usesNow = Date.now();
     this.logger.verbose("Destroying uses...");
     await this.destroyUses();

package/server/hmr/clientScript.ts

@@ -1,5 +1,20 @@
-
-
+// Browser-side HMR client. Delivered as a classic inline <script> (appended
+// to the RSC bootstrap content) so it starts listening before any module
+// script runs. Keep it small and free of dependencies — we cannot rely on any
+// framework code being available when this executes.
+//
+// Protocol (see wsHub.ts `HmrMessage` for the TypeScript shape):
+//   { type: "hello", buildId, cssAssets }  → initial handshake on connect
+//   { type: "reload", buildId }          → full page refresh
+//   { type: "rsc-refresh", buildId }     → full page refresh
+//   { type: "client-refresh", buildId }  → full page refresh
+//   { type: "css-update", cssAssets }    → atomic current-subroute <link> swap, no reload
+//   { type: "error", message }           → forwarded build error, console only
+//
+// The server-rendered HTML tags the "active" stylesheet with
+// data-akan-css="active" (see rscWorker.tsx) so swapCss can remove the stale
+// one after the new stylesheet has finished loading without a flash of
+// unstyled content.
 export const HMR_CLIENT_SCRIPT = `(function(){
   if (self.__AKAN_HMR_INSTALLED__) return;
   self.__AKAN_HMR_INSTALLED__ = true;
@@ -19,6 +34,8 @@ export const HMR_CLIENT_SCRIPT = `(function(){
   var overlayJobs = {};
   self.__AKAN_HMR_PHASE__ = null;
 
+  // Bun's React Fast Refresh transform can emit top-level calls to these globals
+  // even when we fall back to full reload instead of applying React Refresh.
   self.$RefreshReg$ = self.$RefreshReg$ || function(){};
   self.$RefreshSig$ = self.$RefreshSig$ || function(){ return function(type){ return type; }; };
 
@@ -73,6 +90,7 @@ export const HMR_CLIENT_SCRIPT = `(function(){
     setTimeout(connect, delay);
   }
 
+  // goseoghyeon: CSR route registry keeps stale module refs, so JS/RSC HMR uses full reload for now.
   function reloadForHmr(msg){
     try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}
     if (msg && msg.buildId != null) lastBuildId = msg.buildId;

package/server/hmr/devHmrController.ts

@@ -363,6 +363,9 @@ export class DevHmrController {
     ];
     if (files.some((file) => runtimeRoots.some((needle) => path.resolve(file).includes(needle)))) return true;
 
+    // A route source file that is not in the current seed index is likely a
+    // newly added route/layout. The backend's route seed index is static for
+    // this process, so a full reload is the safer recovery path.
     return (
       routeIds === undefined &&
       files.some((file) => path.resolve(file).includes(`${path.sep}page${path.sep}`) && /\.(tsx|ts|jsx|js)$/.test(file))
@@ -379,6 +382,7 @@ export class DevHmrController {
       try {
         return new URL(`${protoFallback}://${hostFallback}`).origin;
       } catch {
+        /* fallthrough */
       }
     }
     return parsed.origin;