akanjs 3.0.0-beta.2 → 3.0.0-beta.21

package/server/di/predefinedAdaptor.ts

@@ -1,4 +1,5 @@
 import type { DatabaseMode } from "akanjs";
+import { DatabaseModes } from "akanjs/base";
 import {
   type AdaptorCls,
   BlobStorage,
@@ -10,13 +11,12 @@ import {
   ConsoleLogger,
   type DatabaseAdaptor,
   DatabaseAdaptorRole,
-  DeepseekLlm,
   JsonCompressor,
-  LibsqlDatabase,
   type LlmAdaptor,
   LlmAdaptorRole,
   type LoggingAdaptor,
   LoggingAdaptorRole,
+  OpenaiLlm,
   PostgresDatabase,
   type QueueAdaptor,
   QueueAdaptorRole,
@@ -34,6 +34,7 @@ import {
   type WebsocketAdaptor,
   WebsocketAdaptorRole,
 } from "akanjs/service";
+import { collectAdaptors } from "./resolveHierarchy";
 
 export interface PredefinedAdaptor {
   database: AdaptorCls<DatabaseAdaptor>;
@@ -68,14 +69,19 @@ export const predefinedAdaptor = {
   logging: ConsoleLogger,
   websocket: SolidPubSub,
   compress: JsonCompressor,
-  llm: DeepseekLlm,
+  llm: OpenaiLlm,
+};
+
+export const collectPredefinedDependencies = (adaptors: PredefinedAdaptor): AdaptorCls[] => {
+  const roles = new Set<AdaptorCls>(Object.values(predefinedAdaptorRole));
+  return [...collectAdaptors(Object.values(adaptors))].filter((adaptor) => !roles.has(adaptor));
 };
 
 export const getPredefinedAdaptor = (mode: DatabaseMode = "single"): PredefinedAdaptor => {
-  if (mode === "single") return predefinedAdaptor;
+  if (DatabaseModes.parse(mode, "The database mode") === "single") return predefinedAdaptor;
   return {
     ...predefinedAdaptor,
-    database: mode === "cluster" ? PostgresDatabase : LibsqlDatabase,
+    database: mode === "cluster" ? PostgresDatabase : SqliteDatabase,
     cache: RedisCache,
     queue: BullQueue,
     websocket: WebSocketRedisAdaptor,

package/server/di/resolveHierarchy.ts

@@ -1,13 +1,11 @@
+import { INJECT_META } from "akanjs/base";
+import { type AdaptorCls, CacheAdaptorRole, type InjectInfo, type ServiceCls } from "akanjs/service";
+
 export interface DependencyNode {
   key: string;
   dependencies: string[];
 }
 
-/**
- * Groups nodes into sequential stages where all nodes within a stage
- * can be initialized concurrently (all their dependencies are satisfied
- * by earlier stages).
- */
 export function topologicalStages<T extends DependencyNode>(graph: Map<string, T>): string[][] {
   const inDegree = new Map<string, number>();
   const dependents = new Map<string, string[]>();
@@ -87,3 +85,114 @@ export function traceCycle<T extends DependencyNode>(graph: Map<string, T>, cand
 
   return candidates;
 }
+
+interface ServiceNode extends DependencyNode {
+  service: ServiceCls;
+}
+
+export interface ServiceHierarchy {
+  graph: Map<string, ServiceNode>;
+  stages: string[][];
+}
+
+export function resolveServiceHierarchy(serviceMap: Map<string, ServiceCls>): ServiceHierarchy {
+  const graph = new Map<string, ServiceNode>();
+
+  for (const [key, service] of serviceMap) {
+    const injectMap: Record<string, InjectInfo> = service[INJECT_META] ?? {};
+    const dependencies: string[] = [];
+
+    for (const [propKey, { type }] of Object.entries(injectMap)) {
+      if (type !== "service" && type !== "database") continue;
+      const depKey = propKey.replace(type === "service" ? /Service$/ : /Model$/, "");
+      if (serviceMap.has(depKey) && depKey !== key) dependencies.push(depKey);
+    }
+
+    graph.set(key, { key, service, dependencies });
+  }
+  const stages = topologicalStages(graph);
+
+  return { graph, stages };
+}
+
+interface AdaptorNode extends DependencyNode {
+  adaptor: AdaptorCls;
+}
+
+export interface AdaptorHierarchy {
+  graph: Map<string, AdaptorNode>;
+  stages: string[][];
+}
+
+export function collectAdaptors(sources: { [INJECT_META]: Record<string, InjectInfo> }[]): Set<AdaptorCls> {
+  const discovered = new Set<AdaptorCls>();
+
+  function scan(injectMap: Record<string, InjectInfo>) {
+    for (const injectInfo of Object.values(injectMap)) {
+      if (injectInfo.type === "plug" && injectInfo.adaptor && !discovered.has(injectInfo.adaptor)) {
+        discovered.add(injectInfo.adaptor);
+        scan(injectInfo.adaptor[INJECT_META] ?? {});
+      }
+    }
+  }
+
+  for (const source of sources) {
+    scan(source[INJECT_META] ?? {});
+  }
+
+  return discovered;
+}
+
+export function resolveAdaptorHierarchy(
+  adaptorMap: Map<string, AdaptorCls>,
+  adaptorRole: Map<AdaptorCls, AdaptorCls> = new Map(),
+): AdaptorHierarchy {
+  const classToKey = new Map<AdaptorCls, string>();
+  for (const [key, adaptor] of adaptorMap) {
+    classToKey.set(adaptor, key);
+  }
+  for (const [role, provider] of adaptorRole) {
+    const providerKey = classToKey.get(provider);
+    if (providerKey) classToKey.set(role, providerKey);
+  }
+
+  const graph = new Map<string, AdaptorNode>();
+
+  for (const [key, adaptor] of adaptorMap) {
+    const injectMap: Record<string, InjectInfo> = adaptor[INJECT_META] ?? {};
+    const dependencies: string[] = [];
+    const addDependency = (depKey: string) => {
+      if (depKey !== key && !dependencies.includes(depKey)) dependencies.push(depKey);
+    };
+
+    for (const [propKey, injectInfo] of Object.entries(injectMap)) {
+      if (injectInfo.type === "plug") {
+        if (!injectInfo.adaptor) continue;
+        const depKey = classToKey.get(injectInfo.adaptor);
+        if (!depKey) {
+          throw new Error(
+            `Adaptor "${key}" has a plug dependency (property "${propKey}") ` +
+              `on adaptor "${injectInfo.adaptor.refName}" which is not registered.`,
+          );
+        }
+        addDependency(depKey);
+      } else if (injectInfo.type === "use") {
+        if (adaptorMap.has(propKey) && propKey !== key) {
+          addDependency(propKey);
+        }
+      } else if (injectInfo.type === "memory") {
+        const depKey = classToKey.get(CacheAdaptorRole);
+        if (!depKey) {
+          throw new Error(`Adaptor "${key}" has a memory dependency but cache adaptor role is not registered.`);
+        }
+        addDependency(depKey);
+      }
+    }
+
+    graph.set(key, { key, adaptor, dependencies });
+  }
+
+  const stages = topologicalStages(graph);
+
+  return { graph, stages };
+}

package/server/di/utils.ts

@@ -1,5 +1,5 @@
 import { INJECT_META } from "akanjs/base";
-import { lowerlize } from "akanjs/common";
+import { lowerlize, toError } from "akanjs/common";
 import { ConstantRegistry } from "akanjs/constant";
 import type { InjectInfo } from "akanjs/service";
 import type { DatabaseModule, ServiceModule } from "../akanLib";
@@ -68,12 +68,6 @@ export const getModuleDependencyRefNames = (mod: DatabaseModule | ServiceModule)
   return dependencies;
 };
 
-/**
- * The modules a cascade edge forces this one to be mounted with: a `removeRef` target and a monomorphic
- * `removeWith` owner both fail `CascadeRunner.seal` when they are absent, so they are boot dependencies the
- * inject graph cannot see. A polymorphic owner is exempt — an enum list spans optional modules by design, and
- * `cascade: "removeWithAny"` names no module at all.
- */
 export const getModuleCascadeRefNames = (mod: DatabaseModule | ServiceModule) => {
   const dependencies = new Set<string>();
   if (!("constant" in mod)) return dependencies;
@@ -92,10 +86,6 @@ export interface Registration {
   owner: string;
 }
 
-/**
- * A key registered twice is silently last-write-wins everywhere downstream — an app that meant to add a second
- * adaptor gets one, and the other's `onInit` never runs. Refuse the boot instead, naming both claimants.
- */
 export const assertUniqueRegistrations = (kind: string, registrations: Registration[]) => {
   const claimed = new Map<string, string>();
   const clashes: string[] = [];
@@ -108,30 +98,24 @@ export const assertUniqueRegistrations = (kind: string, registrations: Registrat
   throw new Error(`[DI:${kind}] ${clashes.length} duplicate registration(s):\n${clashes.join("\n")}`);
 };
 
-/**
- * Run every task in parallel and, if any rejects, throw a single
- * `AggregateError` that enumerates every failing label + cause. This replaces
- * the previous `Promise.all` flow where a second concurrent failure in the
- * same stage would hide the first, making boot errors hard to localize.
- */
 export const runStage = async (stageLabel: string, tasks: StageTask[]): Promise<void> => {
   if (tasks.length === 0) return;
   const settled = await Promise.allSettled(tasks.map((t) => t.run()));
-  const failures: { label: string; reason: unknown }[] = [];
-  settled.forEach((res, i) => {
-    if (res.status === "rejected") {
-      const task = tasks[i];
-      failures.push({ label: task ? task.label : `#${i}`, reason: res.reason });
-    }
-  });
+  const failures = settled.flatMap((res, i) =>
+    res.status === "rejected" ? [{ label: tasks[i]?.label ?? `#${i}`, reason: res.reason }] : [],
+  );
+  throwStageFailures(stageLabel, failures, tasks.length);
+};
+
+export const throwStageFailures = (
+  stageLabel: string,
+  failures: { label: string; reason: unknown }[],
+  total: number,
+) => {
   if (failures.length === 0) return;
   const summary = failures.map((f) => `  • ${f.label}: ${reasonMessage(f.reason)}`).join("\n");
   const errors = failures.map((f) => toError(f.reason));
-  throw new AggregateError(errors, `[DI:${stageLabel}] ${failures.length}/${tasks.length} task(s) failed:\n${summary}`);
-};
-
-export const toError = (reason: unknown): Error => {
-  return reason instanceof Error ? reason : new Error(String(reason));
+  throw new AggregateError(errors, `[DI:${stageLabel}] ${failures.length}/${total} task(s) failed:\n${summary}`);
 };
 
 export const reasonMessage = (reason: unknown): string => {

package/server/head.tsx

@@ -0,0 +1,53 @@
+import type { Head, ResolvedHead, ResolveHeadResult } from "akanjs/client";
+import { isRecord } from "akanjs/common";
+import { AKAN_RSC_HEAD_SNAPSHOT_VERSION, type AkanHeadSnapshotV1 } from "./routeState";
+
+export function createAkanLocaleAlternateHeadSnapshot(languages: Record<string, string>): AkanHeadSnapshotV1 {
+  return {
+    version: AKAN_RSC_HEAD_SNAPSHOT_VERSION,
+    nodes: Object.entries(languages).map(([lang, href]) => ({
+      tag: "link",
+      attrs: { rel: "alternate", hrefLang: lang, href },
+    })),
+  };
+}
+
+export function mergeAkanHeadSnapshots(
+  ...snapshots: Array<AkanHeadSnapshotV1 | null | undefined>
+): AkanHeadSnapshotV1 | undefined {
+  const nodes = snapshots.flatMap((snapshot) => snapshot?.nodes ?? []);
+  return snapshots.some(Boolean) ? { version: AKAN_RSC_HEAD_SNAPSHOT_VERSION, nodes } : undefined;
+}
+
+export function renderAkanHeadSnapshot(snapshot: AkanHeadSnapshotV1): Head {
+  return (
+    <>
+      {snapshot.nodes.map((node, index) => {
+        const key = `${node.tag}:${index}`;
+        const marker = { "data-akan-head": "route", "data-akan-head-key": key };
+        if (node.tag === "title") {
+          return (
+            <title key={key} {...marker}>
+              {node.text ?? ""}
+            </title>
+          );
+        }
+        if (node.tag === "meta") return <meta key={key} {...node.attrs} {...marker} />;
+        return <link key={key} {...node.attrs} {...marker} />;
+      })}
+    </>
+  );
+}
+
+export function shouldRenderLocaleAlternates(options: { isSpecialRoute?: boolean }): boolean {
+  return options.isSpecialRoute !== true;
+}
+
+function isResolvedHead(value: unknown): value is ResolvedHead {
+  return isRecord(value) && "node" in value;
+}
+
+export function resolveHeadResult(value: ResolveHeadResult): ResolvedHead {
+  if (isResolvedHead(value)) return value;
+  return { node: value };
+}

package/server/hmr/clientScript.ts

@@ -1,15 +1,9 @@
-
-
-const SYNC_NAVIGATION_ENABLED =
-  process.env.AKAN_PUBLIC_SYNC_NAVIGATION === "true" ||
-  process.env.AKAN_PUBLIC_SYNC_NAVIGATION === "1" ||
-  process.env.SYNC_DOMAIN === "true" ||
-  process.env.SYNC_DOMAIN === "1";
+import { isSyncNavigationEnabled } from "./wsHub";
 
 export const HMR_CLIENT_SCRIPT = `(function(){
   if (self.__AKAN_HMR_INSTALLED__) return;
   self.__AKAN_HMR_INSTALLED__ = true;
-  var syncNavigationEnabled = ${JSON.stringify(SYNC_NAVIGATION_ENABLED)};
+  var syncNavigationEnabled = ${JSON.stringify(isSyncNavigationEnabled())};
   var syncNavigationClientId = Math.random().toString(36).slice(2) + Date.now().toString(36);
   var proto = location.protocol === "https:" ? "wss:" : "ws:";
   var url = proto + "//" + location.host + "/_akan/hmr";

package/server/hmr/devHmrController.ts

@@ -10,8 +10,7 @@ import {
 } from "../artifact";
 import type { RscWorker } from "../rscWorkerHost";
 import type { RenderState } from "../types";
-import type { ChangeKind } from "./changeBatch";
-import { type HmrMessage, type HmrWsData, HmrWsHub } from "./wsHub";
+import { type ChangeKind, type HmrMessage, type HmrWsData, HmrWsHub } from "./wsHub";
 
 const APP_RUNTIME_METADATA_BASENAMES = new Set(["dict.ts", "sig.ts", "useClient.ts"]);
 
@@ -74,6 +73,7 @@ export function devBuildStatusToHmrMessage(
 }
 
 export interface DevHmrControllerOptions {
+  artifactDir: string;
   renderState: RenderState;
   rsc: RscWorker;
   seedIndex: RouteSeedIndex;
@@ -82,6 +82,7 @@ export interface DevHmrControllerOptions {
 
 export class DevHmrController {
   readonly #logger = new Logger("DevHmrController");
+  readonly #artifactDir: string;
   readonly #renderState: RenderState;
   readonly #rsc: RscWorker;
   readonly #seedIndex: RouteSeedIndex;
@@ -99,11 +100,14 @@ export class DevHmrController {
   readonly #dirty = new Set<Exclude<ChangeKind, "ignore">>();
   readonly #dirtyFiles = new Set<string>();
   readonly #buildStatusByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>();
+  #graphSeeds: string[];
 
-  constructor({ renderState, rsc, seedIndex, upgradeHmrWs }: DevHmrControllerOptions) {
+  constructor({ artifactDir, renderState, rsc, seedIndex, upgradeHmrWs }: DevHmrControllerOptions) {
+    this.#artifactDir = artifactDir;
     this.#renderState = renderState;
     this.#rsc = rsc;
     this.#seedIndex = seedIndex;
+    this.#graphSeeds = DevHmrController.#graphSeedsOf(seedIndex);
     this.#upgradeHmrWs = upgradeHmrWs;
     this.#builderRpc = this.#createBuilderRpc();
     this.routeCache = this.#createRouteCache();
@@ -121,13 +125,8 @@ export class DevHmrController {
     this.#builderRpc.dispose();
   }
 
-  broadcastError(message: string): void {
-    this.#hub.broadcast({ type: "error", message });
-  }
-
   handleWs(req: Request): Response | undefined {
-    const upgraded = this.#upgradeHmrWs(req, { kind: "akan-hmr", openedAt: Date.now() });
-    if (upgraded) return;
+    if (this.#upgradeHmrWs(req, { kind: "akan-hmr", openedAt: Date.now() })) return;
     return new Response("Failed to upgrade HMR WebSocket", { status: 500 });
   }
 
@@ -142,14 +141,15 @@ export class DevHmrController {
       if (!DevHmrController.#isTrustedRscTarget(clientOrigin, targetUrl))
         return new Response("Bad Request", { status: 400 });
       const manifest = await this.ensureRoute(targetUrl);
+      const chunks = DevHmrController.clientChunkUrls(manifest.clientManifest);
       this.#logger.verbose(
-        `[hmr] client-refresh metadata route=${targetUrl.pathname} chunks=${DevHmrController.clientChunkUrls(manifest.clientManifest).length} in ${Date.now() - started}ms`,
+        `[hmr] client-refresh metadata route=${targetUrl.pathname} chunks=${chunks.length} in ${Date.now() - started}ms`,
       );
       return new Response(
         JSON.stringify({
           buildId: this.#renderState.buildId,
           generation: manifest.generation,
-          chunks: DevHmrController.clientChunkUrls(manifest.clientManifest),
+          chunks,
           routeIds: this.routeIdsForPath(targetUrl.pathname),
         }),
         { headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" } },
@@ -163,7 +163,9 @@ export class DevHmrController {
 
   async ensureRoute(url: URL) {
     const started = Date.now();
-    const matched = RouteSeedIndexStore.match(url.pathname, this.#seedIndex.entries);
+    const matched =
+      RouteSeedIndexStore.match(url.pathname, this.#seedIndex.entries) ??
+      RouteSeedIndexStore.matchPrefix(url.pathname, this.#seedIndex.entries);
     if (matched) await this.routeCache.ensure(matched.entry.routeId, matched.entry.seeds);
     this.#logger.verbose(
       `[route-cache] ensure pathname=${url.pathname} routeId=${matched?.entry.routeId ?? "(none)"} in ${Date.now() - started}ms`,
@@ -187,10 +189,6 @@ export class DevHmrController {
     return [...urls];
   }
 
-  static shouldFullReloadForRuntimeMetadata(files: string[]): boolean {
-    return files.some(isAkanRuntimeMetadataFile);
-  }
-
   #createBuilderRpc() {
     return new BuilderRpc({
       onInvalidate: (ev) => {
@@ -218,16 +216,16 @@ export class DevHmrController {
       onPagesUpdated: async ({ bundlePath, buildId, generation, changedFiles }) => {
         const started = Date.now();
         const files = changedFiles ?? [];
-        const runtimeMetadataChanged = DevHmrController.shouldFullReloadForRuntimeMetadata(files);
-        const staleClientEntries = runtimeMetadataChanged ? new Set<string>() : this.#staleClientEntriesForFiles(files);
-        const routeIds = runtimeMetadataChanged ? undefined : this.#routeIdsForFiles(files, staleClientEntries);
-        const fastRefreshCandidate = !runtimeMetadataChanged && this.#isFastRefreshCandidate(files);
+        const routeTreeChanged = await this.#reloadSeedIndex();
+        const runtimeMetadataChanged = files.some(isAkanRuntimeMetadataFile);
+        const clearAll = routeTreeChanged || runtimeMetadataChanged;
+        const staleClientEntries = clearAll ? new Set<string>() : this.#staleClientEntriesForFiles(files);
+        const routeIds = clearAll ? undefined : this.#routeIdsForFiles(files, staleClientEntries);
+        const fastRefreshCandidate = !clearAll && this.#isFastRefreshCandidate(files);
         this.#logger.verbose(
-          `[SSR] pages-updated bundlePath=${bundlePath} buildId=${buildId} generation=${generation ?? "(unknown)"} files=${files.length} routes=${routeIds?.length ?? 0} fastRefresh=${fastRefreshCandidate} staleEntries=${staleClientEntries.size} runtimeMetadata=${runtimeMetadataChanged}`,
+          `[SSR] pages-updated bundlePath=${bundlePath} buildId=${buildId} generation=${generation ?? "(unknown)"} files=${files.length} routes=${routeIds?.length ?? 0} fastRefresh=${fastRefreshCandidate} staleEntries=${staleClientEntries.size} runtimeMetadata=${runtimeMetadataChanged} routeTree=${routeTreeChanged}`,
         );
-        const dropped = this.#invalidateRoutes(files, routeIds, staleClientEntries, {
-          forceClear: runtimeMetadataChanged,
-        });
+        const dropped = this.#invalidateRoutes(files, routeIds, staleClientEntries, { forceClear: clearAll });
         this.#renderState.buildId = buildId;
         const manifest = this.routeCache.snapshot();
         const reloadStarted = Date.now();
@@ -238,7 +236,7 @@ export class DevHmrController {
           pagesBundlePath: bundlePath,
         });
         this.#logger.verbose(`[SSR] rsc reload buildId=${buildId} in ${Date.now() - reloadStarted}ms`);
-        const shouldReload = runtimeMetadataChanged || this.#shouldFullReloadForFiles(files, routeIds);
+        const shouldReload = clearAll || this.#shouldFullReloadForFiles(files, routeIds);
         if (shouldReload) this.#hub.broadcast({ type: "reload", buildId });
         else if (fastRefreshCandidate)
           this.#hub.broadcast({ type: "client-refresh", buildId, generation, changedFiles, routeIds });
@@ -250,6 +248,21 @@ export class DevHmrController {
     });
   }
 
+  async #reloadSeedIndex(): Promise<boolean> {
+    const next = await RouteSeedIndexStore.load(this.#artifactDir).catch((err: unknown) => {
+      this.#logger.warn(`[hmr] route seed index unreadable; keeping the boot one: ${String(err)}`);
+      return null;
+    });
+    if (!next || JSON.stringify(next) === JSON.stringify(this.#seedIndex)) return false;
+    Object.assign(this.#seedIndex, next);
+    this.#graphSeeds = DevHmrController.#graphSeedsOf(next);
+    return true;
+  }
+
+  static #graphSeedsOf(seedIndex: RouteSeedIndex): string[] {
+    return [...new Set([...seedIndex.globalLayoutFiles, ...seedIndex.entries.flatMap((e) => e.seeds)])];
+  }
+
   #recordBuildStatus(status: DevBuildStatus): void {
     const previous = this.#buildStatusByPhase.get(status.phase);
     this.#buildStatusByPhase.set(status.phase, status);
@@ -265,7 +278,12 @@ export class DevHmrController {
     return new RouteClientCache({
       buildRoute: async (routeId, { seeds, knownEntries, generation }) => {
         const expandedSeeds = [...new Set([...this.#seedIndex.globalLayoutFiles, ...seeds])];
-        return this.#builderRpc.buildRoute(routeId, { seeds: expandedSeeds, knownEntries, generation });
+        return this.#builderRpc.buildRoute(routeId, {
+          seeds: expandedSeeds,
+          graphSeeds: this.#graphSeeds,
+          knownEntries,
+          generation,
+        });
       },
       onMerge: async (routeId, { delta, merged, generation }) => {
         const removedEntries = this.#rememberClientEntries(routeId, delta.discoveredEntries ?? delta.newEntries);
@@ -369,26 +387,24 @@ export class DevHmrController {
     for (const [entry, entryDeps] of Object.entries(depsByEntry)) {
       const resolvedEntry = path.resolve(entry);
       this.#recentClientEntries.add(resolvedEntry);
-      const entryRouteIds = this.#clientEntryRouteIds.get(resolvedEntry) ?? new Set<string>();
-      entryRouteIds.add(routeId);
-      this.#clientEntryRouteIds.set(resolvedEntry, entryRouteIds);
+      DevHmrController.#addTo(this.#clientEntryRouteIds, resolvedEntry, routeId);
       for (const dep of entryDeps) {
         const resolvedDep = path.resolve(dep);
         this.#recentClientFiles.add(resolvedDep);
-        const entries = this.#clientFileEntries.get(resolvedDep) ?? new Set<string>();
-        entries.add(resolvedEntry);
-        this.#clientFileEntries.set(resolvedDep, entries);
+        DevHmrController.#addTo(this.#clientFileEntries, resolvedDep, resolvedEntry);
       }
     }
     for (const dep of deps) {
       const resolved = path.resolve(dep);
       this.#recentClientFiles.add(resolved);
-      const routeIds = this.#clientFileRouteIds.get(resolved) ?? new Set<string>();
-      routeIds.add(routeId);
-      this.#clientFileRouteIds.set(resolved, routeIds);
+      DevHmrController.#addTo(this.#clientFileRouteIds, resolved, routeId);
     }
   }
 
+  static #addTo(map: Map<string, Set<string>>, key: string, value: string) {
+    map.set(key, (map.get(key) ?? new Set<string>()).add(value));
+  }
+
   #rememberClientEntries(routeId: string, entries: string[]): Set<string> {
     const nextEntries = new Set(entries.map((entry) => path.resolve(entry)));
     const previousEntries = this.#clientEntriesByRouteId.get(routeId) ?? new Set<string>();
@@ -405,9 +421,7 @@ export class DevHmrController {
     for (const entry of entries) {
       const resolvedEntry = path.resolve(entry);
       this.#recentClientEntries.add(resolvedEntry);
-      const routeIds = this.#clientEntryRouteIds.get(resolvedEntry) ?? new Set<string>();
-      routeIds.add(routeId);
-      this.#clientEntryRouteIds.set(resolvedEntry, routeIds);
+      DevHmrController.#addTo(this.#clientEntryRouteIds, resolvedEntry, routeId);
     }
     return orphanedEntries;
   }
@@ -448,9 +462,9 @@ export class DevHmrController {
   #shouldFullReloadForFiles(files: string[], routeIds: string[] | undefined): boolean {
     if (files.length === 0) return false;
     const runtimeRoots = [
-      `${path.sep}pkgs${path.sep}akanjs${path.sep}server${path.sep}src${path.sep}hmr${path.sep}`,
-      `${path.sep}pkgs${path.sep}akanjs${path.sep}server${path.sep}src${path.sep}rscClient.tsx`,
-      `${path.sep}pkgs${path.sep}akanjs${path.sep}server${path.sep}src${path.sep}ssrFromRscRenderer.tsx`,
+      `${path.sep}pkgs${path.sep}akanjs${path.sep}server${path.sep}hmr${path.sep}`,
+      `${path.sep}pkgs${path.sep}akanjs${path.sep}server${path.sep}rscClient.tsx`,
+      `${path.sep}pkgs${path.sep}akanjs${path.sep}server${path.sep}ssrFromRscRenderer.tsx`,
     ];
     if (files.some((file) => runtimeRoots.some((needle) => path.resolve(file).includes(needle)))) return true;
     if (files.some((file) => path.basename(file).endsWith(".signal.ts"))) return true;

package/server/hmr/wsHub.ts

@@ -1,6 +1,13 @@
 import { Logger } from "akanjs/common";
 import type { BuildPhase } from "../artifact";
 
+export type ChangeKind = "code" | "css" | "config" | "ignore";
+
+export interface ChangeBatch {
+  files: string[];
+  kinds: Set<Exclude<ChangeKind, "ignore">>;
+}
+
 export interface HmrWsData {
   kind: "akan-hmr";
   openedAt: number;
@@ -41,10 +48,6 @@ export class HmrWsHub {
   readonly #conns = new Set<Bun.ServerWebSocket<HmrWsData>>();
   #publish: ((topic: string, payload: string) => void) | null = null;
 
-  get size(): number {
-    return this.#conns.size;
-  }
-
   setPublisher(publish: (topic: string, payload: string) => void): void {
     this.#publish = publish;
   }
@@ -61,8 +64,7 @@ export class HmrWsHub {
   }
 
   broadcast(msg: HmrMessage): void {
-    const payload = JSON.stringify(msg);
-    this.#publish?.(HMR_WS_TOPIC, payload);
+    this.#publish?.(HMR_WS_TOPIC, JSON.stringify(msg));
   }
 
   handleMessage(message: string): void {
@@ -78,7 +80,7 @@ export class HmrWsHub {
   }
 }
 
-const isSyncNavigationEnabled = () =>
+export const isSyncNavigationEnabled = () =>
   process.env.AKAN_PUBLIC_SYNC_NAVIGATION === "true" ||
   process.env.AKAN_PUBLIC_SYNC_NAVIGATION === "1" ||
   process.env.SYNC_DOMAIN === "true" ||