akanjs 2.2.4-rc.4 → 2.2.4

package/fetch/fetchType/appliedReturn.type.ts

@@ -106,3 +106,4 @@ export type InitReturn<
   [K in `${RefName}List${_CapitalizedSuffix}`]: DataList<_Light>;
 } & { [K in `${RefName}Insight${_CapitalizedSuffix}`]: Insight };
 
+// ============= Method Generators =============

package/fetch/fetchType/endpointFetch.type.ts

@@ -24,6 +24,7 @@ type PubsubSubscribeFn<E> = (
   ...args: [...EndpInfoArgs<E>, handleEvent: (data: EndpInfoReturns<E>) => PromiseOrObject<void>, options?: FetchPolicy]
 ) => () => void;
 
+// Keys kept as-is: query / mutation / message (emit)
 type PrimaryFetchType<EInfoObj extends { [key: string]: EndpointInfo }> = {
   [K in keyof EInfoObj as EndpInfoType<EInfoObj[K]> extends "query" | "mutation" | "message" ? K : never]: EndpInfoType<
     EInfoObj[K]
@@ -34,6 +35,7 @@ type PrimaryFetchType<EInfoObj extends { [key: string]: EndpointInfo }> = {
       : never;
 };
 
+// Keys remapped to `subscribe${Key}`
 type PubsubFetchType<EInfoObj extends { [key: string]: EndpointInfo }> = {
   [K in keyof EInfoObj as EndpInfoType<EInfoObj[K]> extends "pubsub"
     ? K extends string
@@ -42,6 +44,7 @@ type PubsubFetchType<EInfoObj extends { [key: string]: EndpointInfo }> = {
     : never]: PubsubSubscribeFn<EInfoObj[K]>;
 };
 
+// Keys remapped to `listen${Key}`
 type MessageListenFetchType<EInfoObj extends { [key: string]: EndpointInfo }> = {
   [K in keyof EInfoObj as EndpInfoType<EInfoObj[K]> extends "message"
     ? K extends string

package/fetch/fetchType/sliceFetch.type.ts

@@ -5,6 +5,8 @@ import type { DatabaseModel, ExtractSort, FilterInstance } from "akanjs/document
 import type { SliceCls, SliceInfoArgs } from "akanjs/signal";
 import type { ClientEdit, ClientInit, ClientView, EditReturn, InitReturn, ViewReturn } from "./appliedReturn.type";
 
+// Shortcut accessors — avoids re-typing the long lookup path and lets TS
+// memoize each access once per SlceCls instantiation.
 type _SliceMap<S extends SliceCls> = S[typeof SLICE_META];
 type _RefName<S extends SliceCls> = S["srv"]["cnst"]["refName"];
 type _Cap<S extends SliceCls> = S["srv"]["cnst"]["_CapitalizedRefName"];
@@ -21,6 +23,11 @@ type _Sort<S extends SliceCls> = S["srv"]["db"]["_Sort"];
 type _LightWithId<S extends SliceCls> = _Light<S> extends { id: string } ? _Light<S> : { id: string };
 type _SliceFetchInitOption<S extends SliceCls> = FetchInitOption<_Input<S>, _Filter<S>, _DefaultInput<S>, _Sort<S>>;
 
+// The 4 dynamic parts below are each a single homomorphic mapped type over
+// `keyof SliceMap`, which preserves each result key's declaration trace
+// (better hover, slightly better go-to-def) and avoids the
+// `UnionToIntersection`/`MergedValues` blow-up.
+
 type SliceListFetch<S extends SliceCls> = {
   [Suffix in keyof _SliceMap<S> as Suffix extends string ? `${_RefName<S>}List${Capitalize<Suffix>}` : never]: (
     ...args: [
@@ -138,6 +145,7 @@ type AppliedBaseSliceFetchType<
 } & {
   [K in `get${_CapitalizedRefName}Edit`]: (id: string, option?: FetchPolicy) => ClientEdit<RefName, Full>;
 } & {
+  // TODO: migrate this to shared
   [K in `add${_CapitalizedRefName}Files`]: (
     fileList: FileList,
     parentId?: string,

package/fetch/requestStorage.ts

@@ -15,7 +15,11 @@ declare global {
 let _requestStorage: RequestStorage | null = null;
 if (typeof window === "undefined") {
   try {
-
+    // Keep this module synchronous. CSR builds import `akanjs/fetch` through
+    // Bun's HMR runtime, and a top-level `await import("node:async_hooks")`
+    // turns the whole `export *` chain into an async module. Named imports
+    // from that chain can then be observed as `null` during evaluation
+    // (notably `FetchClient` in `akanjs/client/useClient.ts`).
     const { AsyncLocalStorage } = require("node:async_hooks") as typeof import("node:async_hooks");
     globalThis.__AKAN_REQUEST_STORAGE__ ??= new AsyncLocalStorage() as RequestStorage;
     _requestStorage = globalThis.__AKAN_REQUEST_STORAGE__;
@@ -57,6 +61,10 @@ export function pushRequestFallback(req: Request): () => void {
   };
 }
 
+// Lightweight server-side helpers for server components to read the incoming
+// request's headers/cookies. Kept in akanjs/fetch (no heavy client deps) so
+// they can be imported from inside the RSC worker without pulling `akanjs/
+// client`'s useClient macro chain.
 /** Returns the active server request from AsyncLocalStorage or the fallback stack. */
 export function getRequest(): Request | undefined {
   return requestStorage?.getStore() ?? globalThis.__AKAN_REQUEST_FALLBACK_STACK__?.at(-1);
@@ -104,7 +112,7 @@ export function parseCookieHeader(cookieHeader: string): Map<string, CookieEntry
     if (eq === -1) continue;
     const name = trimmed.slice(0, eq).trim();
     const raw = trimmed.slice(eq + 1).trim();
-    
+    // Support the `j:<json>` convention used elsewhere in akanjs.
     const value = raw.startsWith("j:")
       ? (() => {
           try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.2.4-rc.4",
+  "version": "2.2.4",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -15,140 +15,98 @@
   },
   "exports": {
     ".": {
-      "types": "./types/index.d.ts",
       "import": "./index.ts",
+      "types": "./index.ts",
       "default": "./index.ts"
     },
     "./package.json": "./package.json",
     "./base": {
-      "types": "./types/base/index.d.ts",
       "import": "./base/index.ts",
+      "types": "./base/index.ts",
       "default": "./base/index.ts"
     },
     "./common": {
-      "types": "./types/common/index.d.ts",
       "import": "./common/index.ts",
+      "types": "./common/index.ts",
       "default": "./common/index.ts"
     },
-    "./common/*": {
-      "types": "./types/common/*.d.ts",
-      "import": "./common/*",
-      "default": "./common/*"
-    },
-    "./common/*.ts": {
-      "types": "./types/common/*.d.ts",
-      "import": "./common/*.ts",
-      "default": "./common/*.ts"
-    },
-    "./common/*.tsx": {
-      "types": "./types/common/*.d.ts",
-      "import": "./common/*.tsx",
-      "default": "./common/*.tsx"
-    },
+    "./common/*": "./common/*",
     "./fetch": {
-      "types": "./types/fetch/index.d.ts",
       "import": "./fetch/index.ts",
+      "types": "./fetch/index.ts",
       "default": "./fetch/index.ts"
     },
     "./document": {
-      "types": "./types/document/index.d.ts",
       "import": "./document/index.ts",
+      "types": "./document/index.ts",
       "default": "./document/index.ts"
     },
     "./signal": {
-      "types": "./types/signal/index.d.ts",
       "import": "./signal/index.ts",
+      "types": "./signal/index.ts",
       "default": "./signal/index.ts"
     },
     "./store": {
-      "types": "./types/store/index.d.ts",
       "import": "./store/index.ts",
+      "types": "./store/index.ts",
       "default": "./store/index.ts"
     },
     "./ui": {
-      "types": "./types/ui/index.d.ts",
       "import": "./ui/index.ts",
+      "types": "./ui/index.ts",
       "default": "./ui/index.ts"
     },
-    "./ui/*": {
-      "types": "./types/ui/*.d.ts",
-      "import": "./ui/*",
-      "default": "./ui/*"
-    },
-    "./ui/*.ts": {
-      "types": "./types/ui/*.d.ts",
-      "import": "./ui/*.ts",
-      "default": "./ui/*.ts"
-    },
-    "./ui/*.tsx": {
-      "types": "./types/ui/*.d.ts",
-      "import": "./ui/*.tsx",
-      "default": "./ui/*.tsx"
-    },
+    "./ui/*": "./ui/*",
     "./client": {
-      "types": "./types/client/index.d.ts",
       "import": "./client/index.ts",
+      "types": "./client/index.ts",
       "default": "./client/index.ts"
     },
     "./client/capacitor": {
-      "types": "./types/client/capacitor.d.ts",
       "import": "./client/capacitor.ts",
+      "types": "./client/capacitor.ts",
       "default": "./client/capacitor.ts"
     },
     "./capacitor.base.config": {
-      "types": "./types/capacitor.base.config.d.ts",
       "import": "./capacitor.base.config.ts",
+      "types": "./capacitor.base.config.ts",
       "default": "./capacitor.base.config.ts"
     },
     "./webkit": {
-      "types": "./types/webkit/index.d.ts",
       "import": "./webkit/index.ts",
+      "types": "./webkit/index.ts",
       "default": "./webkit/index.ts"
     },
-    "./webkit/*": {
-      "types": "./types/webkit/*.d.ts",
-      "import": "./webkit/*",
-      "default": "./webkit/*"
-    },
-    "./webkit/*.ts": {
-      "types": "./types/webkit/*.d.ts",
-      "import": "./webkit/*.ts",
-      "default": "./webkit/*.ts"
-    },
-    "./webkit/*.tsx": {
-      "types": "./types/webkit/*.d.ts",
-      "import": "./webkit/*.tsx",
-      "default": "./webkit/*.tsx"
-    },
+    "./webkit/*": "./webkit/*",
     "./server": {
-      "types": "./types/server/index.d.ts",
       "import": "./server/index.ts",
+      "types": "./server/index.ts",
       "default": "./server/index.ts"
     },
     "./service": {
-      "types": "./types/service/index.d.ts",
       "import": "./service/index.ts",
+      "types": "./service/index.ts",
       "default": "./service/index.ts"
     },
     "./constant": {
-      "types": "./types/constant/index.d.ts",
       "import": "./constant/index.ts",
+      "types": "./constant/index.ts",
       "default": "./constant/index.ts"
     },
     "./dictionary": {
-      "types": "./types/dictionary/index.d.ts",
       "import": "./dictionary/index.ts",
+      "types": "./dictionary/index.ts",
       "default": "./dictionary/index.ts"
     },
     "./test": {
-      "types": "./types/test/index.d.ts",
       "import": "./test/index.ts",
+      "types": "./test/index.ts",
       "default": "./test/index.ts"
     },
     "./ui/styles.css": "./ui/styles.css",
     "./server/rsc-worker": {
-      "types": "./types/server/rscWorker.d.ts",
       "import": "./server/rscWorker.tsx",
+      "types": "./server/rscWorker.tsx",
       "default": "./server/rscWorker.tsx"
     }
   },
@@ -328,6 +286,5 @@
   },
   "engines": {
     "bun": ">=1.3.13"
-  },
-  "main": "./index.ts"
-}
+  }
+}

package/server/akanApp.test.ts

@@ -0,0 +1,130 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { AkanApp } from "./akanApp";
+import { makeAkanChildProxyHeaders } from "./akanAppHeaders";
+
+const tempRoots: string[] = [];
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const waitFor = async <T>(fn: () => Promise<T | null>, timeoutMs = 5_000): Promise<T> => {
+  const started = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    const value = await fn();
+    if (value) return value;
+    await wait(50);
+  }
+  throw new Error(`Timed out after ${timeoutMs}ms`);
+};
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("makeAkanChildProxyHeaders", () => {
+  test("preserves public forwarded host and protocol for child requests", () => {
+    const req = new Request("http://akan-internal/", {
+      headers: {
+        connection: "keep-alive",
+        host: "internal.example",
+        "x-forwarded-for": "203.0.113.10",
+        "x-forwarded-host": "akanjs.com",
+        "x-forwarded-proto": "https",
+        "x-real-ip": "10.0.0.5",
+      },
+    });
+
+    const headers = makeAkanChildProxyHeaders(req, 2);
+
+    expect(headers.get("connection")).toBeNull();
+    expect(headers.get("host")).toBe("akan-child");
+    expect(headers.get("x-forwarded-for")).toBe("203.0.113.10, 10.0.0.5");
+    expect(headers.get("x-forwarded-host")).toBe("akanjs.com");
+    expect(headers.get("x-forwarded-proto")).toBe("https");
+    expect(headers.get("x-akan-child-idx")).toBe("2");
+  });
+
+  test("falls back to request host and protocol without upstream forwarded headers", () => {
+    const req = new Request("http://internal.example/", {
+      headers: {
+        host: "internal.example",
+      },
+    });
+
+    const headers = makeAkanChildProxyHeaders(req, 0);
+
+    expect(headers.get("x-forwarded-host")).toBe("internal.example");
+    expect(headers.get("x-forwarded-proto")).toBe("http");
+  });
+});
+
+describe("AkanApp", () => {
+  test("restarts only the crashed replica", async () => {
+    const root = await mkdtemp(path.join(tmpdir(), "akan-app-restart-"));
+    tempRoots.push(root);
+    const counterPath = path.join(root, "counter.txt");
+    const serverPath = path.join(root, "server.ts");
+    const runtimeDir = path.join(root, "runtime");
+    const port = 24_000 + Math.floor(Math.random() * 10_000);
+
+    await Bun.write(
+      serverPath,
+      `
+        const counterPath = ${JSON.stringify(counterPath)};
+        export const server = {
+          async start() {
+            const file = Bun.file(counterPath);
+            const previous = await file.exists() ? Number(await file.text()) : 0;
+            const next = previous + 1;
+            await Bun.write(counterPath, String(next));
+            const http = Bun.serve({
+              unix: process.env.AKAN_CHILD_SOCKET,
+              fetch() { return new Response("ok"); },
+            });
+            process.on("message", (message) => {
+              if (!message || typeof message !== "object") return;
+              if (message.type === "health.ping") {
+                process.send?.({ type: "health.pong", nonce: message.nonce, sentAt: message.sentAt, pid: process.pid });
+              }
+              if (message.type === "shutdown") {
+                http.stop(true);
+                process.exit(0);
+              }
+            });
+            process.send?.({
+              type: "ready",
+              pid: process.pid,
+              replicaIdx: Number(process.env.AKAN_REPLICA_IDX ?? 0),
+              role: process.env.SERVER_MODE ?? "all",
+              upstream: { type: "unix", socketPath: process.env.AKAN_CHILD_SOCKET },
+              healthPath: "/_akan/app/child-health",
+            });
+            if (next === 1) setTimeout(() => process.exit(1), 50);
+          },
+        };
+      `,
+    );
+
+    const app = new AkanApp(serverPath, { replica: 1, runtimeDir, port });
+    const running = app.start();
+    try {
+      const health = await waitFor(async () => {
+        const res = await fetch(`http://127.0.0.1:${port}/_akan/app/health`).catch(() => null);
+        if (!res?.ok) return null;
+        const body = (await res.json()) as {
+          children: Array<{ ready: boolean; restartCount: number; restartPending: boolean }>;
+        };
+        const child = body.children[0];
+        return child?.ready && child.restartCount > 0 && !child.restartPending ? body : null;
+      }, 6_000);
+
+      expect(health.children[0]?.restartCount).toBeGreaterThanOrEqual(1);
+      expect(await Bun.file(counterPath).text()).toBe("2");
+    } finally {
+      await app.stop();
+      await Promise.race([running, wait(1_000)]);
+    }
+  });
+});

package/server/akanApp.ts

@@ -154,7 +154,7 @@ export class AkanApp {
     process.on("SIGINT", () => this.#handleShutdownSignal("SIGINT"));
     process.on("SIGTERM", () => this.#handleShutdownSignal("SIGTERM"));
     await new Promise<void>((resolve) => {
-      
+      // Keep the orchestrator alive while child processes run.
       this.#resolveStopped = resolve;
     });
   }
@@ -360,6 +360,7 @@ export class AkanApp {
     try {
       await rm(socketPath, { force: true });
     } catch {
+      // Best-effort cleanup for stale Unix sockets.
     }
   }
 
@@ -588,7 +589,8 @@ export class AkanApp {
 
   #proxyResponse(upstreamRes: Response): Response {
     const headers = new Headers(upstreamRes.headers);
-
+    // Bun fetch transparently decompresses upstream bodies but keeps these
+    // headers, which makes browsers try to decode an already-decoded payload.
     headers.delete("content-encoding");
     headers.delete("content-length");
     this.#rewriteInternalLocation(headers);
@@ -606,6 +608,7 @@ export class AkanApp {
       const parsed = new URL(location);
       if (parsed.hostname === "akan-child") headers.set("location", `${parsed.pathname}${parsed.search}${parsed.hash}`);
     } catch {
+      // Relative redirects are already safe to pass through.
     }
   }
 

package/server/akanLib.ts

@@ -19,6 +19,7 @@ export interface ServiceModule {
 export interface ScalarModule {
   constant: ScalarConstantModel;
   database: DatabaseCls;
+  // internal?: InternalCls;
 }
 
 export interface AkanLibProps {

package/server/akanServer.test.ts

@@ -0,0 +1,157 @@
+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";
+
+const createEnv = (tmp: string) =>
+  ({
+    repoName: "akan",
+    serveDomain: "example.com",
+    appName: "serverGet",
+    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 setAkanEnv = () => {
+  process.env.AKAN_PUBLIC_APP_NAME = "serverGet";
+  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 loadRuntime = async () => {
+  const [
+    { SolidPubSub, WebsocketAdaptorRole },
+    { AkanLib },
+    { AkanOption },
+    { AkanServer },
+    {
+      ServerResolverTestEndpoint,
+      ServerResolverTestInternal,
+      ServerResolverTestServerSignal,
+      ServerResolverTestService,
+      ServerResolverTestSlice,
+      serverResolverTestConstant,
+      serverResolverTestDatabase,
+      serverResolverTestServiceModel,
+    },
+  ] = await Promise.all([
+    import("akanjs/service"),
+    import("./akanLib"),
+    import("./akanOption"),
+    import("./akanServer"),
+    import("./resolver/resolver.contract.fixture"),
+  ]);
+
+  const createLib = () =>
+    new AkanLib("serverGetTest", {
+      databases: [
+        {
+          constant: serverResolverTestConstant,
+          database: serverResolverTestDatabase,
+          service: serverResolverTestServiceModel,
+          signal: {
+            endpoint: ServerResolverTestEndpoint,
+            slice: ServerResolverTestSlice,
+            internal: ServerResolverTestInternal,
+            server: ServerResolverTestServerSignal,
+          },
+        },
+      ],
+      services: [],
+      scalars: [],
+      option: new AkanOption(),
+    });
+
+  return {
+    SolidPubSub,
+    WebsocketAdaptorRole,
+    AkanServer,
+    ServerResolverTestServerSignal,
+    ServerResolverTestService,
+    createLib,
+  };
+};
+
+describe("AkanServer DI lookup", () => {
+  test("gets service, server signal, and adaptor instances", async () => {
+    setAkanEnv();
+    const {
+      SolidPubSub,
+      WebsocketAdaptorRole,
+      AkanServer,
+      ServerResolverTestServerSignal,
+      ServerResolverTestService,
+      createLib,
+    } = await loadRuntime();
+
+    const tmp = await mkdtemp(join(tmpdir(), "akan-server-get-"));
+    const server = new AkanServer("serverGet", createEnv(tmp), "all", createLib());
+
+    try {
+      await server.start({ listen: false });
+
+      const serviceByClass = server.get(ServerResolverTestService);
+      expect(serviceByClass).toBe(server.getService("serverResolverTestItem"));
+      expect(server.getService("serverResolverTestItemService")).toBe(serviceByClass);
+
+      const signalByClass = server.get(ServerResolverTestServerSignal);
+      expect(server.getSignal("serverResolverTestItem")).toBe(signalByClass);
+      expect(server.getSignal("serverResolverTestItemSignal")).toBe(signalByClass);
+
+      const adaptorByClass = server.get(SolidPubSub);
+      expect(server.get(WebsocketAdaptorRole)).toBe(adaptorByClass);
+      expect(server.getAdaptor("solidPubsub")).toBe(adaptorByClass);
+    } finally {
+      await server.stop();
+      await rm(tmp, { recursive: true, force: true });
+    }
+  });
+
+  test("throws clear errors before initialization and for missing dependencies", async () => {
+    setAkanEnv();
+    const { AkanServer, createLib } = await loadRuntime();
+    const tmp = await mkdtemp(join(tmpdir(), "akan-server-get-"));
+    const server = new AkanServer("serverGet", createEnv(tmp), "all", createLib());
+
+    try {
+      expect(() => server.getService("serverResolverTestItem")).toThrow(
+        'Service "serverResolverTestItem" is not initialized while AkanServer status is "stopped"',
+      );
+
+      await server.start({ listen: false });
+
+      expect(() => server.getService("missing")).toThrow('Service "missing" is not registered.');
+      expect(() => server.getSignal("missing")).toThrow('Server signal "missingSignal" is not registered.');
+      expect(() => server.getAdaptor("missing")).toThrow('Adaptor "missing" is not registered.');
+    } finally {
+      await server.stop();
+      await rm(tmp, { recursive: true, force: true });
+    }
+  });
+});

package/server/akanServer.ts

@@ -41,7 +41,8 @@ interface AkanAppPrepared {
 
 export class AkanServer {
   status: "stopped" | "initializing" | "initialized" | "starting" | "running" | "stopping" = "stopped";
-
+  // Union the app-signal data shape with the HMR channel's data shape so
+  // `server.upgrade(...)` type-checks for both.
   #server: Bun.Server<{ createdAt: number } | HmrWsData> | null = null;
   #wsServer: Bun.Server<{ createdAt: number } | HmrWsData> | null = null;
   #prepared: AkanAppPrepared | null = null;
@@ -173,10 +174,10 @@ export class AkanServer {
         hmrState: webRouter ? { state: webRouter.renderState } : null,
         logger: this.logger,
       }),
-      
+      // `data` is typed by the upgrade call site; the runtime default is unused.
       data: {},
     } as Bun.WebSocketHandler<{ createdAt: number } | HmrWsData>;
-    
+    // `builderRpc` lives in `#prepared` only so `stop()` can dispose it.
     this.#server = Bun.serve({
       idleTimeout: 0,
       ...(unix ? { unix } : { port }),

package/server/artifact/builderRpc.ts

@@ -51,7 +51,7 @@ export class BuilderRpc {
       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.#offMessage = this.#listen((msg) => {
-      
+      // Responses: look up the pending promise by id and settle.
       if (msg.type === "build-route-res") {
         const res = msg as BuilderRes;
         const waiter = this.#pending.get(res.id);
@@ -61,7 +61,7 @@ export class BuilderRpc {
         else waiter.reject(new Error(`[builder] ${res.type} failed: ${res.error}`));
         return;
       }
-      
+      // Broadcast events: dispatch to subscriber hooks.
       const ev = msg as BuilderEvent;
       switch (ev.type) {
         case "builder-ready":

package/server/artifact/ipcTypes.ts

@@ -16,6 +16,8 @@ export interface CssPayload {
   changedFiles?: string[];
 }
 
+// --- backend → builder (request/response) -------------------------------
+
 export type BuilderReq = {
   type: "build-route";
   id: number;
@@ -29,6 +31,8 @@ export type BuilderRes =
   | { type: "build-route-res"; id: number; ok: true; data: BuildRouteResultPayload }
   | { type: "build-route-res"; id: number; ok: false; error: string };
 
+// --- builder → backend (unsolicited events) -----------------------------
+
 export interface PagesBundlePayload {
   bundlePath: string;
   buildId: number;