akanjs 2.4.0 → 2.4.1-rc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.4.0",
+  "version": "2.4.1-rc.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/akanApp.ts

@@ -4,7 +4,7 @@ import { Logger } from "akanjs/common";
 import type { AkanChildRole, AkanChildStatus, AkanIpcMessage, AkanMetricsReport, AkanUpstream } from "akanjs/service";
 import { isTraceEnabled } from "akanjs/signal";
 import { makeAkanChildProxyHeaders } from "./akanAppHeaders";
-import type { BuilderMessage, BuilderReq, BuilderRes } from "./artifact";
+import type { BuilderCsrReq, BuilderCsrRes, BuilderMessage, BuilderReq, BuilderRes } from "./artifact";
 import { isPortInUseError } from "./lifecycle/portInUse";
 import { RotatingLogWriter } from "./logging/rotatingLogWriter";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
@@ -935,7 +935,8 @@ export class AkanApp {
         if (child && proc) void this.#scheduleChildRestart(child, proc, "child-error");
         return;
       case "build-route":
-        this.#forwardBuildRoute(idx, message);
+      case "build-csr":
+        this.#forwardBuilderReq(idx, message);
         return;
     }
   }
@@ -951,7 +952,8 @@ export class AkanApp {
         this.#fanoutToFederation(message);
         return;
       case "build-route-res":
-        this.#forwardBuildRouteResponse(message);
+      case "build-csr-res":
+        this.#forwardBuilderRes(message);
         return;
     }
   }
@@ -1134,22 +1136,22 @@ export class AkanApp {
     }
   }
 
-  #forwardBuildRoute(childIdx: number, message: BuilderReq) {
+  #forwardBuilderReq(childIdx: number, message: BuilderReq | BuilderCsrReq) {
     const gatewayReqId = this.#nextBuilderReqId++;
     this.#builderReqMap.set(gatewayReqId, { childIdx, childLocalId: message.id });
-    process.send?.({ ...message, id: gatewayReqId } satisfies BuilderReq);
+    process.send?.({ ...message, id: gatewayReqId } satisfies BuilderReq | BuilderCsrReq);
   }
 
-  #forwardBuildRouteResponse(message: BuilderRes) {
+  #forwardBuilderRes(message: BuilderRes | BuilderCsrRes) {
     const request = this.#builderReqMap.get(message.id);
     if (!request) {
-      this.logger.warn(`No child found for build-route response id=${message.id}`);
+      this.logger.warn(`No child found for ${message.type} id=${message.id}`);
       return;
     }
     this.#builderReqMap.delete(message.id);
     const child = this.#children.get(request.childIdx);
     if (!child || child.proc.killed) return;
-    this.#sendToChild(child, { ...message, id: request.childLocalId } satisfies BuilderRes);
+    this.#sendToChild(child, { ...message, id: request.childLocalId } satisfies BuilderRes | BuilderCsrRes);
   }
 
   #fanoutToFederation(message: AkanIpcMessage | BuilderMessage, exceptIdx?: number) {

package/server/artifact/builderRpc.ts

@@ -1,5 +1,7 @@
 import { Logger } from "akanjs/common";
 import type {
+  BuilderCsrReq,
+  BuilderCsrRes,
   BuilderEvent,
   BuilderMessage,
   BuilderReq,
@@ -45,7 +47,7 @@ export class BuilderRpc {
   readonly #pending = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
   readonly #offMessage: () => void;
   readonly #proc = process;
-  readonly #send: (msg: BuilderReq) => void;
+  readonly #send: (msg: BuilderReq | BuilderCsrReq) => void;
   #nextId = 1;
   #disposed = false;
 
@@ -55,13 +57,13 @@ export class BuilderRpc {
     this.#send = this.#proc.send.bind(this.#proc);
     this.#offMessage = this.#listen((msg) => {
       
-      if (msg.type === "build-route-res") {
-        const res = msg as BuilderRes;
+      if (msg.type === "build-route-res" || msg.type === "build-csr-res") {
+        const res = msg as BuilderRes | BuilderCsrRes;
         const waiter = this.#pending.get(res.id);
         if (!waiter) return;
         this.#pending.delete(res.id);
-        if (res.ok) waiter.resolve(res.data);
-        else waiter.reject(new Error(`[builder] ${res.type} failed: ${res.error}`));
+        if (!res.ok) waiter.reject(new Error(`[builder] ${res.type} failed: ${res.error}`));
+        else waiter.resolve(res.type === "build-route-res" ? res.data : undefined);
         return;
       }
       
@@ -108,6 +110,20 @@ export class BuilderRpc {
     };
   }
 
+  /**
+   * Ask the builder to build the dev CSR artifact and keep it in sync from now on. The builder skips
+   * CSR by default (a full minified browser-target build of every page, ~350 MB per save), so the
+   * first `/__csr` or `?csr=true` request has nothing to serve until this resolves.
+   */
+  async buildCsr(reason: string): Promise<void> {
+    if (this.#disposed) throw new Error("[builder] rpc is disposed");
+    const id = this.#nextId++;
+    await new Promise<void>((resolve, reject) => {
+      this.#pending.set(id, { resolve: resolve as (v: unknown) => void, reject });
+      this.#send({ type: "build-csr", id, reason });
+    });
+  }
+
   dispose(): void {
     if (this.#disposed) return;
     this.#disposed = true;

package/server/artifact/ipcTypes.ts

@@ -59,6 +59,18 @@ export type BuilderRes =
   | { type: "build-route-res"; id: number; ok: true; data: BuildRouteResultPayload }
   | { type: "build-route-res"; id: number; ok: false; error: string };
 
+/**
+ * Dev CSR artifacts are only reachable through the opt-in `/__csr` and `?csr=true` routes (mobile
+ * local dev points a device WebView at the latter), so the builder skips them until a request
+ * actually needs one. The first such request arms the builder through this pair and waits for the
+ * build, after which every save keeps CSR in sync.
+ */
+export type BuilderCsrReq = { type: "build-csr"; id: number; reason: string };
+
+export type BuilderCsrRes =
+  | { type: "build-csr-res"; id: number; ok: true }
+  | { type: "build-csr-res"; id: number; ok: false; error: string };
+
 export interface PagesBundlePayload {
   bundlePath: string;
   buildId: number;
@@ -80,4 +92,4 @@ export type BuilderEvent =
   | { type: "pages-updated"; data: PagesBundlePayload }
   | { type: "build-status"; data: DevBuildStatus };
 
-export type BuilderMessage = BuilderReq | BuilderRes | BuilderEvent;
+export type BuilderMessage = BuilderReq | BuilderRes | BuilderCsrReq | BuilderCsrRes | BuilderEvent;

package/server/resolver/signal.resolver.ts

@@ -11,9 +11,10 @@ import {
   SLICE_META,
 } from "akanjs/base";
 import { capitalize, Logger } from "akanjs/common";
-import { serialize } from "akanjs/constant";
+import { deserialize, serialize } from "akanjs/constant";
 import { documentQueryHelper } from "akanjs/document";
 import {
+  type AkanJob,
   type AkanJobOptions,
   type InjectRegistry,
   type LiveRegistry,
@@ -97,21 +98,22 @@ export class SignalResolver {
   static resolveSchedule(internalCls: InternalCls, internal: Internal, serverMode: "federation" | "batch" | "all") {
     const internalMeta = internalCls[INTERNAL_META] as { [key: string]: InternalInfo };
     Object.entries(internalMeta).forEach(([key, internalInfo]) => {
-      const { enabled, operationMode, serverMode: targetServerMode } = internalInfo.signalOption;
-      if (!enabled) return;
-      else if (operationMode && !operationMode.includes(getEnv().operationMode)) return;
-      else if (
-        targetServerMode &&
-        targetServerMode !== "all" &&
-        serverMode !== "all" &&
-        targetServerMode !== serverMode
-      )
+      const skip = SignalResolver.#getScheduleSkipReason(internalInfo, serverMode);
+      if (skip) {
+        SignalResolver.#warnMissingProcessWorker(key, internalInfo, skip);
         return;
+      }
       switch (internalInfo.type) {
-        case "process":
+        case "process": {
           if (!internalInfo.execFn) throw new Error(`Exec function is not set for ${key}`);
-          internal.queue.registerProcessWorker(key, internalInfo.execFn.bind(internal));
+          const execFn = internalInfo.execFn.bind(internal);
+
+          internal.queue.registerProcessWorker(
+            key,
+            async (job) => await execFn(...SignalResolver.#getJobArgs(key, internalInfo, job), job),
+          );
           break;
+        }
         case "init":
           internal.schedule.registerInit(key, () => internalInfo.execFn?.bind(internal)());
           break;
@@ -150,6 +152,52 @@ export class SignalResolver {
       }
     });
   }
+  /** Why an internal is not scheduled on this server, or null when it is. `placement` marks a deliberate role split. */
+  static #getScheduleSkipReason(
+    internalInfo: InternalInfo,
+    serverMode: "federation" | "batch" | "all",
+  ): { reason: string; placement: boolean } | null {
+    const { enabled, operationMode, serverMode: targetServerMode } = internalInfo.signalOption;
+    if (!enabled) return { reason: "the internal is disabled (`enabled: false`)", placement: false };
+    if (operationMode && !operationMode.includes(getEnv().operationMode))
+      return {
+        reason: `operationMode "${getEnv().operationMode}" is not in [${operationMode.join(", ")}]`,
+        placement: true,
+      };
+    if (targetServerMode && targetServerMode !== "all" && serverMode !== "all" && targetServerMode !== serverMode)
+      return {
+        reason: `serverMode is "${serverMode}" but the internal declares "${targetServerMode}"`,
+        placement: true,
+      };
+    return null;
+  }
+
+  /**
+   * A `process` producer is installed on every server regardless of placement, so a skipped worker means this
+   * server can enqueue jobs that nothing here consumes. Surface that asymmetry instead of failing silently.
+   */
+  static #warnMissingProcessWorker(
+    key: string,
+    internalInfo: InternalInfo,
+    { reason, placement }: { reason: string; placement: boolean },
+  ) {
+    if (internalInfo.type !== "process") return;
+    const message = `No worker registered for process internal "${key}" because ${reason}. Jobs enqueued here stay pending unless another server consumes them.`;
+    if (placement) SignalResolver.logger.verbose(message);
+    else SignalResolver.logger.warn(message);
+  }
+
+  /** Maps a job payload back onto the internal's declared `msg` args, deserializing each to its declared type. */
+  static #getJobArgs(key: string, internalInfo: InternalInfo, job: AkanJob): unknown[] {
+    const data = Array.isArray(job.data) ? (job.data as unknown[]) : job.data === undefined ? [] : [job.data];
+    return internalInfo.args.map((arg, idx) =>
+      deserialize(arg.argRef, arg.arrDepth, data[idx], {
+        key: `${key}.${arg.name}`,
+        nullable: arg.option?.nullable,
+      }),
+    );
+  }
+
   static resolveSlice(sliceCls: SliceCls): EndpointCls {
     const sliceMeta = sliceCls[SLICE_META] as { [key: string]: SliceInfo };
     const cnst = sliceCls.srv.cnst;

package/server/rscWorkerHost.ts

@@ -309,6 +309,8 @@ export interface RscWorkerOptions {
 type WorkerStatus = "starting" | "ready" | "restarting" | "stopped";
 
 export class RscWorker {
+  static readonly #devMaxReloads = 10;
+  static readonly #devMaxRssBytes = 768 * 1024 * 1024;
   readonly ready: Promise<void>;
   #logger = new Logger("RscWorker");
 
@@ -332,6 +334,8 @@ export class RscWorker {
   #restartAttempts = 0;
   #restartCount = 0;
   #recycleCount = 0;
+  #reloadsSinceSpawn = 0;
+  #lastRecycleAtMono: number | null = null;
   #lastRecycleReason: string | undefined;
   #lastWorkerMetrics: AkanMetricsReport = {};
   #hostPendingChunkOverflowCount = 0;
@@ -498,6 +502,7 @@ export class RscWorker {
     }
     this.#lastRecycleReason = reason;
     this.#recycleCount += 1;
+    this.#lastRecycleAtMono = performance.now();
     const oldPid = this.#proc.pid;
     this.#logger.info(`[rsc] rolling recycle worker reason=${reason} oldPid=${oldPid}`);
     this.#status = "restarting";
@@ -535,6 +540,11 @@ export class RscWorker {
     if (input.pagesBundlePath) this.#pagesBundlePath = input.pagesBundlePath;
 
     if (this.#status !== "ready") return Promise.resolve();
+
+    if (this.#shouldRecycleForReloadAccumulation() && this.restartWhenIdle("pages-reload-accumulation")) {
+      return Promise.resolve();
+    }
+    this.#reloadsSinceSpawn += 1;
     return new Promise<void>((resolve, reject) => {
 
       if (this.#pendingReload) this.#pendingReload.resolve();
@@ -556,6 +566,7 @@ export class RscWorker {
 
   #spawn(): Bun.Subprocess<"ignore", "inherit", "inherit"> {
     this.#status = "starting";
+    this.#reloadsSinceSpawn = 0;
     const workerPath = this.#resolveWorkerPath();
     let proc!: Bun.Subprocess<"ignore", "inherit", "inherit">;
     const earlyMessages: RscInMsg[] = [];
@@ -786,6 +797,15 @@ export class RscWorker {
     }, delay);
   }
 
+  #shouldRecycleForReloadAccumulation(): boolean {
+    const maxReloads = RscWorker.#getRscMaxReloads();
+    if (!maxReloads || this.#reloadsSinceSpawn < maxReloads) return false;
+
+    const sinceLastRecycleMs = this.#lastRecycleAtMono === null ? null : performance.now() - this.#lastRecycleAtMono;
+    if (sinceLastRecycleMs !== null && sinceLastRecycleMs < RscWorker.#getRscMinRecycleIntervalMs()) return false;
+    return true;
+  }
+
   #maybeRecycleFromMetrics(metrics: AkanMetricsReport): void {
     if (this.#pending.size > 0) return;
     const maxRssBytes = RscWorker.#getRscMaxRssBytes();
@@ -846,6 +866,20 @@ export class RscWorker {
     return RscWorker.#parsePositiveIntEnv("AKAN_RSC_WORKER_RECYCLE_GRACE_MS") ?? 5_000;
   }
 
+  /**
+   * Reloads tolerated before the worker is recycled instead of reloaded in place. Production imports
+   * the pages bundle once at boot and never reloads, so the threshold only applies to dev.
+   */
+  static #getRscMaxReloads(): number | null {
+    if (process.env.AKAN_RSC_WORKER_MAX_RELOADS !== undefined)
+      return RscWorker.#parsePositiveIntEnv("AKAN_RSC_WORKER_MAX_RELOADS");
+    return RscWorker.#isProductionRuntime() ? null : RscWorker.#devMaxReloads;
+  }
+
+  static #getRscMinRecycleIntervalMs(): number {
+    return RscWorker.#parsePositiveIntEnv("AKAN_RSC_WORKER_MIN_RECYCLE_INTERVAL_MS") ?? 1_000;
+  }
+
   static #getRscMaxRssBytes(): number | null {
     const explicitMb = RscWorker.#parsePositiveIntEnv("AKAN_RSC_WORKER_MAX_RSS_MB");
     if (explicitMb) return explicitMb * 1024 * 1024;
@@ -853,9 +887,10 @@ export class RscWorker {
     const explicitBytes = RscWorker.#parseBytesEnv("AKAN_RSC_WORKER_MAX_RSS");
     if (explicitBytes) return explicitBytes;
 
-    if (!RscWorker.#isProductionRuntime()) return null;
     const memoryLimitBytes = RscWorker.#parseBytesEnv("AKAN_MEMORY_LIMIT") ?? RscWorker.#readCgroupMemoryLimitBytes();
-    return memoryLimitBytes ? Math.floor(memoryLimitBytes * 0.55) : null;
+    if (memoryLimitBytes) return Math.floor(memoryLimitBytes * 0.55);
+
+    return RscWorker.#isProductionRuntime() ? null : RscWorker.#devMaxRssBytes;
   }
 
   static #getRscMaxRouteModules(): number | null {

package/server/webRouter.ts

@@ -273,6 +273,8 @@ export class WebRouter {
   #builderRpc: BuilderRpc | null;
   #routeCache: RouteClientCache;
   #devHmr: DevHmrController | null = null;
+  #csrArmed = false;
+  #csrOnDemandBuild: Promise<unknown> | null = null;
   readonly #requestStats = {
     fullSsr: 0,
     rscNavigation: 0,
@@ -340,7 +342,7 @@ export class WebRouter {
     const renderEnvRoutes: HttpRoutes = {
       "/__csr": async () => {
         this.#requestStats.csr += 1;
-        const csrHtml = WebRouter.#resolveCsrHtmlPath(csrOutputDir, "/", this.#artifact);
+        const csrHtml = await this.#resolveCsrHtml(csrOutputDir, "/");
         const csrFile = csrHtml ? Bun.file(csrHtml) : null;
         const htmlText =
           csrFile && (await csrFile.exists())
@@ -476,8 +478,8 @@ export class WebRouter {
         const isCsr = url.searchParams.get("csr") === "true";
         if (isCsr) {
           this.#requestStats.csr += 1;
-          const csrHtml = WebRouter.#resolveCsrHtmlPath(csrOutputDir, url.pathname, this.#artifact);
-          if (!csrHtml) return new Response("Not Found", { status: 404 });
+          const csrHtml = await this.#resolveCsrHtml(csrOutputDir, url.pathname);
+          if (!csrHtml) return this.#csrUnavailableResponse(url.pathname);
           const html = await Bun.file(csrHtml).text();
           return new Response(this.#withCsrHmr(html), {
             headers: { "Content-Type": "text/html; charset=utf-8" },
@@ -884,6 +886,41 @@ export class WebRouter {
     if (this.#prodMode) return html;
     return WebRouter.#injectBeforeBodyEnd(html, `<script>${HMR_CLIENT_SCRIPT}</script>`);
   }
+  /**
+   * Resolve a CSR html file, asking the builder to build the artifact first if it is not there yet.
+   * Dev CSR is only reachable through `/__csr` and `?csr=true`, so the builder skips it until one of
+   * them is requested; the first request pays for the build and every save keeps it in sync after.
+   */
+  async #resolveCsrHtml(csrOutputDir: string, pathname: string): Promise<string | null> {
+    const resolved = WebRouter.#resolveCsrHtmlPath(csrOutputDir, pathname, this.#artifact);
+    if (resolved) return resolved;
+    await this.#armCsrArtifact(pathname);
+    return WebRouter.#resolveCsrHtmlPath(csrOutputDir, pathname, this.#artifact);
+  }
+  #armCsrArtifact(reason: string): Promise<unknown> {
+    const rpc = this.#builderRpc;
+
+    if (this.#csrArmed || !rpc) return Promise.resolve();
+    this.#csrOnDemandBuild ??= rpc
+      .buildCsr(reason)
+      .then(() => {
+        this.#csrArmed = true;
+        this.#logger.info(`[csr] dev CSR artifact built on demand (${reason})`);
+      })
+      .catch((err: unknown) => {
+        this.#logger.error(`[csr] on-demand build failed: ${err instanceof Error ? err.message : String(err)}`);
+      })
+      .finally(() => {
+        this.#csrOnDemandBuild = null;
+      });
+    return this.#csrOnDemandBuild;
+  }
+  #csrUnavailableResponse(pathname: string): Response {
+    if (this.#prodMode) return new Response("Not Found", { status: 404 });
+    const message = `No CSR artifact for ${pathname}. Dev CSR is built on demand; check the dev server log for a csr-build failure and verify the basePath in the URL.`;
+    this.#logger.warn(`[csr] ${message}`);
+    return new Response(message, { status: 404, headers: { "Content-Type": "text/plain; charset=utf-8" } });
+  }
   static #injectBeforeBodyEnd(html: string, snippet: string): string {
     const matches = [...html.matchAll(/<\/body\s*>/gi)];
     const last = matches.at(-1);

package/service/predefinedAdaptor/queue.adaptor.ts

@@ -9,7 +9,7 @@ type QueueLike = {
 type WorkerLike = AkanWorker;
 type WorkerConstructor = new (
   name: string,
-  handler: (job: AkanJob) => Promise<void>,
+  handler: (job: AkanJob) => Promise<unknown>,
   options: { connection: unknown },
 ) => WorkerLike;
 type QueueConstructor = new (
@@ -23,7 +23,7 @@ type BullmqModule = {
 const bullmqPackage = "bullmq";
 
 export interface QueueAdaptor {
-  registerProcessWorker(key: string, handler: (job: AkanJob) => Promise<void>): AkanWorker;
+  registerProcessWorker(key: string, handler: (job: AkanJob) => Promise<unknown>): AkanWorker;
   registerProcessQueue(key: string, args: unknown[], jobOptions?: AkanJobOptions): Promise<AkanJob>;
 }
 
@@ -34,28 +34,38 @@ export class BullQueue
   }))
   implements QueueAdaptor
 {
-  #queue!: QueueLike;
+  #queues = new Map<string, QueueLike>();
+  #Queue!: QueueConstructor;
   #Worker!: WorkerConstructor;
 
   override async onInit(): Promise<void> {
     const { Queue, Worker } = (await import(bullmqPackage)) as BullmqModule;
+    this.#Queue = Queue;
     this.#Worker = Worker;
-    this.#queue = new Queue(this.prefix, {
+  }
+
+  #queueName(key: string) {
+    return `${this.prefix}:${key}`;
+  }
+  getQueue(key: string): QueueLike {
+    const name = this.#queueName(key);
+    const queue = this.#queues.get(name);
+    if (queue) return queue;
+    const newQueue = new this.#Queue(name, {
       connection: this.redis,
       defaultJobOptions: { removeOnComplete: true, removeOnFail: true },
     });
+    this.#queues.set(name, newQueue);
+    return newQueue;
   }
-  getQueue(): QueueLike {
-    return this.#queue;
-  }
-  registerProcessWorker(key: string, handler: (job: AkanJob) => Promise<void>): WorkerLike {
-    const worker = new this.#Worker(`${this.prefix}:${key}`, handler, {
+  registerProcessWorker(key: string, handler: (job: AkanJob) => Promise<unknown>): WorkerLike {
+    const worker = new this.#Worker(this.#queueName(key), handler, {
       connection: this.redis,
     });
     return worker;
   }
   async registerProcessQueue(key: string, args: unknown[], jobOptions?: AkanJobOptions): Promise<AkanJob> {
-    const job = await this.#queue.add(`${this.prefix}:${key}`, args, jobOptions);
+    const job = await this.getQueue(key).add(key, args, jobOptions);
     return job as unknown as AkanJob;
   }
 }

package/service/predefinedAdaptor/solidQueue.adaptor.ts

@@ -21,7 +21,7 @@ class SolidWorker implements AkanWorker {
   constructor(
     private readonly queue: SolidQueue,
     private readonly name: string,
-    private readonly handler: (job: AkanJob) => Promise<void>,
+    private readonly handler: (job: AkanJob) => Promise<unknown>,
     pollIntervalMs: number,
   ) {
     this.#timer = setInterval(() => void this.pump(), pollIntervalMs);
@@ -116,7 +116,7 @@ export class SolidQueue
     this.#db?.close();
   }
 
-  registerProcessWorker(key: string, handler: (job: AkanJob) => Promise<void>): AkanWorker {
+  registerProcessWorker(key: string, handler: (job: AkanJob) => Promise<unknown>): AkanWorker {
     const worker = new SolidWorker(this, key, handler, this.config.queuePollIntervalMs);
     this.#workers.set(key, worker);
     return worker;
@@ -169,7 +169,7 @@ export class SolidQueue
     }
   }
 
-  async runJob(job: AkanJob, handler: (job: AkanJob) => Promise<void>) {
+  async runJob(job: AkanJob, handler: (job: AkanJob) => Promise<unknown>) {
     try {
       await handler({ ...job, data: job.data });
       this.#db

package/signal/internalInfo.ts

@@ -255,6 +255,7 @@ export const buildInternal = {
     signalOption?: SignalOption<Returns, Nullable>,
   ) =>
     new InternalInfo("process", returnRef, {
+      enabled: true,
       serverMode: "all",
       ...signalOption,
     }),

package/types/server/artifact/builderRpc.d.ts

@@ -40,5 +40,11 @@ export declare class BuilderRpc {
         knownEntries: Set<string>;
         generation?: number;
     }): Promise<BuildRouteClientResult>;
+    /**
+     * Ask the builder to build the dev CSR artifact and keep it in sync from now on. The builder skips
+     * CSR by default (a full minified browser-target build of every page, ~350 MB per save), so the
+     * first `/__csr` or `?csr=true` request has nothing to serve until this resolves.
+     */
+    buildCsr(reason: string): Promise<void>;
     dispose(): void;
 }

package/types/server/artifact/ipcTypes.d.ts

@@ -64,6 +64,27 @@ export type BuilderRes = {
     ok: false;
     error: string;
 };
+/**
+ * Dev CSR artifacts are only reachable through the opt-in `/__csr` and `?csr=true` routes (mobile
+ * local dev points a device WebView at the latter), so the builder skips them until a request
+ * actually needs one. The first such request arms the builder through this pair and waits for the
+ * build, after which every save keeps CSR in sync.
+ */
+export type BuilderCsrReq = {
+    type: "build-csr";
+    id: number;
+    reason: string;
+};
+export type BuilderCsrRes = {
+    type: "build-csr-res";
+    id: number;
+    ok: true;
+} | {
+    type: "build-csr-res";
+    id: number;
+    ok: false;
+    error: string;
+};
 export interface PagesBundlePayload {
     bundlePath: string;
     buildId: number;
@@ -92,4 +113,4 @@ export type BuilderEvent = {
     type: "build-status";
     data: DevBuildStatus;
 };
-export type BuilderMessage = BuilderReq | BuilderRes | BuilderEvent;
+export type BuilderMessage = BuilderReq | BuilderRes | BuilderCsrReq | BuilderCsrRes | BuilderEvent;

package/types/service/predefinedAdaptor/queue.adaptor.d.ts

@@ -5,7 +5,7 @@ type QueueLike = {
 };
 type WorkerLike = AkanWorker;
 export interface QueueAdaptor {
-    registerProcessWorker(key: string, handler: (job: AkanJob) => Promise<void>): AkanWorker;
+    registerProcessWorker(key: string, handler: (job: AkanJob) => Promise<unknown>): AkanWorker;
     registerProcessQueue(key: string, args: unknown[], jobOptions?: AkanJobOptions): Promise<AkanJob>;
 }
 declare const BullQueue_base: import("..").AdaptorCls<{}, {
@@ -15,8 +15,8 @@ declare const BullQueue_base: import("..").AdaptorCls<{}, {
 export declare class BullQueue extends BullQueue_base implements QueueAdaptor {
     #private;
     onInit(): Promise<void>;
-    getQueue(): QueueLike;
-    registerProcessWorker(key: string, handler: (job: AkanJob) => Promise<void>): WorkerLike;
+    getQueue(key: string): QueueLike;
+    registerProcessWorker(key: string, handler: (job: AkanJob) => Promise<unknown>): WorkerLike;
     registerProcessQueue(key: string, args: unknown[], jobOptions?: AkanJobOptions): Promise<AkanJob>;
 }
 export {};

package/types/service/predefinedAdaptor/solidQueue.adaptor.d.ts

@@ -10,10 +10,10 @@ export declare class SolidQueue extends SolidQueue_base implements QueueAdaptor
     #private;
     onInit(): Promise<void>;
     onDestroy(): Promise<void>;
-    registerProcessWorker(key: string, handler: (job: AkanJob) => Promise<void>): AkanWorker;
+    registerProcessWorker(key: string, handler: (job: AkanJob) => Promise<unknown>): AkanWorker;
     registerProcessQueue(key: string, args: unknown[], jobOptions?: AkanJobOptions): Promise<AkanJob>;
     wake(name?: string): void;
     claimJob(name: string): AkanJob | null;
-    runJob(job: AkanJob, handler: (job: AkanJob) => Promise<void>): Promise<void>;
+    runJob(job: AkanJob, handler: (job: AkanJob) => Promise<unknown>): Promise<void>;
 }
 export {};