akanjs 3.0.0-alpha.64 → 3.0.0-alpha.66

package/index.ts

@@ -4,14 +4,37 @@ import type { AkanImageConfig } from "akanjs/server";
 export const archs = ["amd64", "arm64"] as const;
 export type Arch = (typeof archs)[number];
 
-export interface DockerConfig {
-  content: string;
+/** One image step. The object form runs only on the matching `TARGETARCH` leg of a multi-arch build. */
+export type DockerRun = string | { [key in Arch]?: string };
+
+/** The pieces Akan assembles a Dockerfile from. */
+export interface DockerImageConfig {
   image: string | { [key in Arch]?: string };
-  preRuns: (string | { [key in Arch]?: string })[];
-  postRuns: (string | { [key in Arch]?: string })[];
+  /** Runs before `bun install`, so a system package a native dependency needs is there for the install. */
+  preRuns: DockerRun[];
+  /** Runs after `bun install`, before the app files are copied. */
+  postRuns: DockerRun[];
   command: string[];
 }
 
+/**
+ * A whole Dockerfile as a string, or the parts Akan assembles one from. The string form is taken verbatim —
+ * nothing is merged into it, including the steps a lib contributes through its own `docker`.
+ */
+export type DockerConfig = string | DockerImageConfig;
+
+/** What an `akan.config.ts` may write for `docker`: a whole Dockerfile, or any subset of the parts. */
+export type DockerOption = string | Partial<DockerImageConfig>;
+
+/**
+ * A lib's contribution to the image of every app that mounts it — a lib never picks the base image or the
+ * command, only the steps its own runtime needs.
+ */
+export interface LibDockerConfig {
+  preRuns: DockerRun[];
+  postRuns: DockerRun[];
+}
+
 export interface AkanRouteDomains {
   main?: string[];
   develop?: string[];
@@ -24,6 +47,24 @@ export interface AkanRouteConfig {
   domains: AkanRouteDomains;
 }
 
+/**
+ * Which web surfaces an app serves, resolved. `ssr` is the RSC/SSR route renderer and everything it needs —
+ * the pages bundle, the client bundles, the RSC worker process. `csr` is the single-file SPA shell that the
+ * Capacitor mobile build ships and that `/__csr` serves.
+ */
+export interface AkanWebConfig {
+  ssr: boolean;
+  csr: boolean;
+}
+
+/**
+ * What an `akan.config.ts` may write. `false` is an API-only app — no web artifact is built and no web route
+ * is mounted; `true` (the default) is both surfaces. The object form keeps SSR and toggles only the CSR
+ * bundle, which is the whole range there is: the CSR bundle inlines the stylesheet the SSR build compiles, so
+ * CSR without SSR would ship an unstyled app and is not expressible here.
+ */
+export type AkanWebOption = boolean | { csr: boolean };
+
 export type DatabaseMode = "single" | "multiple" | "cluster";
 export type MobileEnv = "local" | "debug" | "develop" | "main";
 export type MobilePermission = "camera" | "contacts" | "location" | "push" | "speech";
@@ -162,6 +203,8 @@ export interface AkanPlugin {
 export interface AppConfigResult {
   docker: DockerConfig;
   defaultDatabaseMode: DatabaseMode;
+  /** Web surfaces built into the app and mounted at boot. Both default to `true`. */
+  web: AkanWebConfig;
   routes?: AkanRouteConfig[];
   /**
    * Mounts `libs/<lib>/page` into this app under `page/(libs)/(<lib>)` on sync. `true` takes every lib
@@ -181,6 +224,8 @@ export interface AppConfigResult {
 
 export interface LibConfigResult {
   externalLibs: string[];
+  /** Image steps every app that mounts this lib inherits, unless that app declares a whole Dockerfile. */
+  docker: LibDockerConfig;
 }
 
 export type DeepPartial<T> = {
@@ -197,7 +242,11 @@ export interface LibConfigContext {
   readonly type: "lib";
 }
 
-export type AppConfigInput = DeepPartial<AppConfigResult> & { plugins?: AkanPlugin[] };
+export type AppConfigInput = Omit<DeepPartial<AppConfigResult>, "docker" | "web"> & {
+  docker?: DockerOption;
+  web?: AkanWebOption;
+  plugins?: AkanPlugin[];
+};
 export type LibConfigInput = DeepPartial<LibConfigResult> & { plugins?: AkanPlugin[] };
 export type AppConfig = AppConfigInput | ((app: AppConfigContext) => AppConfigInput);
 export type LibConfig = LibConfigInput | ((lib: LibConfigContext) => LibConfigInput);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.64",
+  "version": "3.0.0-alpha.66",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -166,6 +166,11 @@
       "import": "./server/rscWorker.tsx",
       "default": "./server/rscWorker.tsx"
     },
+    "./server/akanApp": {
+      "types": "./types/server/akanApp.d.ts",
+      "import": "./server/akanApp.ts",
+      "default": "./server/akanApp.ts"
+    },
     "./server/memoryLimit": {
       "types": "./types/server/memoryLimit.d.ts",
       "import": "./server/memoryLimit.ts",

package/server/akanApp.ts

@@ -4,13 +4,15 @@ import { mkdir, readdir, rm } from "node:fs/promises";
 import path from "node:path";
 import { Logger } from "akanjs/common";
 import type { AkanChildRole, AkanChildStatus, AkanIpcMessage, AkanMetricsReport, AkanUpstream } from "akanjs/service";
-import { isTraceEnabled } from "akanjs/signal";
+import { isTraceEnabled } from "../signal/trace";
 import { makeAkanChildProxyHeaders } from "./akanAppHeaders";
 import type { BuilderCsrReq, BuilderCsrRes, BuilderMessage, BuilderReq, BuilderRes } from "./artifact";
 import { resolveEncodedSidecar } from "./assetEncoding";
 import { isPortInUseError } from "./lifecycle/portInUse";
+import { resolveRuntimeDir } from "./lifecycle/runtimeDir";
 import { RotatingLogWriter } from "./logging/rotatingLogWriter";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
+import { getWebConfigFromEnv } from "./types";
 
 interface ChildState {
   idx: number;
@@ -35,6 +37,11 @@ interface ChildState {
   lastErrorMessage?: string;
 }
 
+/** The shape `#startSolo` needs off `server.ts`; the module itself is loaded by path, so it has no type here. */
+interface SoloServer {
+  start: (options: { listen: boolean }) => Promise<unknown>;
+}
+
 interface GatewayWsData {
   childIdx: number;
   upstream: WebSocket;
@@ -71,6 +78,13 @@ export interface AkanAppOptions {
    * module. Handed down as `AKAN_MODULES`, since each replica builds its own container.
    */
   modules?: string[];
+  /**
+   * Run the one replica in this process instead of spawning it — see `#startSolo`. Defaults on for a single
+   * traffic replica the environment configured, and off whenever `replica` is passed here, because code that
+   * states a topology is asking for the gateway that serves it. `AKAN_SOLO=false` turns it off; like
+   * `AKAN_SSR`, the env can only narrow, so it cannot force a gateway's replicas into one process.
+   */
+  solo?: boolean;
 }
 
 interface AkanReplicaConfig {
@@ -103,7 +117,10 @@ export class AkanApp {
   readonly #port: number;
   readonly #wsBasePort: number;
   readonly #openapi?: boolean;
+  /** The gateway hands `/_akan/client|styles|fonts` straight off disk, so it needs the same answer its children do. */
+  readonly #web = getWebConfigFromEnv();
   readonly #modules: string[];
+  readonly #solo: boolean;
   readonly #children = new Map<number, ChildState>();
   readonly #roomChildren = new Map<string, Set<number>>();
   readonly #childRooms = new Map<number, Set<string>>();
@@ -135,17 +152,29 @@ export class AkanApp {
     this.#serverPath = AkanApp.#resolveServerPath(resolvedOptions.serverPath ?? serverPath);
     this.#artifactDir = path.resolve(path.dirname(this.#serverPath), ".akan", "artifact");
     this.#replica = AkanApp.#parseReplicaConfig(resolvedOptions.replica);
-    this.#runtimeDir = path.resolve(
-      resolvedOptions.runtimeDir ??
-        process.env.AKAN_RUNTIME_DIR ??
-        (process.env.NODE_ENV === "production"
-          ? path.resolve(process.cwd(), "runtime")
-          : path.resolve(process.cwd(), "local", "apps", process.env.AKAN_PUBLIC_APP_NAME ?? "unknown", "runtime")),
-    );
+    this.#runtimeDir = resolveRuntimeDir(resolvedOptions.runtimeDir);
     this.#port = Number(resolvedOptions.port ?? process.env.PORT ?? 8282);
     this.#wsBasePort = Number(resolvedOptions.wsBasePort ?? process.env.AKAN_WS_BASE_PORT ?? this.#port + 10_000);
     this.#openapi = resolvedOptions.openapi;
     this.#modules = resolvedOptions.modules ?? [];
+    this.#solo = AkanApp.#resolveSolo(resolvedOptions, this.#replica);
+  }
+
+  /**
+   * One replica that serves traffic means there is nothing to balance and nothing to fan pubsub out to, so the
+   * gateway is a second Bun runtime and a proxy hop in front of the only server there is. Measured on
+   * `apps/akan`: 28MB of RSS and half the requests per second.
+   *
+   * A batch-only replica is excluded because it never listens — keeping the gateway is what leaves something
+   * bound to answer `/_akan/app/health`. `akan start` is excluded because the gateway is also the dev host's
+   * builder relay, its crash page, and what holds the port across a child restart.
+   */
+  static #resolveSolo(options: AkanAppOptions, replica: AkanReplicaConfig) {
+    if (options.solo !== undefined) return options.solo;
+    if (process.env.AKAN_SOLO === "false" || process.env.AKAN_SOLO === "0") return false;
+    if (process.env.AKAN_COMMAND_TYPE === "start") return false;
+    if (options.replica !== undefined) return false;
+    return replica.total === 1 && replica.batch === 0;
   }
 
   static #resolveServerPath(serverPath: string) {
@@ -212,6 +241,7 @@ export class AkanApp {
   }
 
   async start() {
+    if (this.#solo) return await this.#startSolo();
     await this.#prepareRuntimeDir();
     this.#startFileLogging();
     for (let idx = 0; idx < this.#replica.total; idx++) this.#spawn(idx);
@@ -239,6 +269,25 @@ export class AkanApp {
     });
   }
 
+  async #startSolo() {
+    const role = this.#getRole(0);
+
+    Object.assign(process.env, {
+      NODE_ENV: AkanApp.#defaultChildNodeEnv(),
+      AKAN_REPLICA: this.#replica.value,
+      AKAN_REPLICA_IDX: "0",
+      AKAN_APP_DIR: path.dirname(this.#serverPath),
+      SERVER_MODE: role,
+      ...(this.#openapi === undefined ? {} : { AKAN_OPENAPI: this.#openapi ? "true" : "false" }),
+      ...(this.#modules.length ? { AKAN_MODULES: this.#modules.join(",") } : {}),
+    });
+    this.logger.info(`Starting ${role} replica in this process (solo); set AKAN_SOLO=false for the gateway`);
+    const mod = (await import(this.#serverPath)) as { server?: SoloServer; app?: SoloServer };
+    const server = mod.server ?? mod.app;
+    if (!server?.start) throw new Error("server.ts must export server or app with start()");
+    await server.start({ listen: true });
+  }
+
   async stop(signal = "SIGTERM") {
     if (this.#stopping) return;
     this.#stopping = true;
@@ -555,6 +604,7 @@ export class AkanApp {
   }
 
   async #serveImmutableArtifact(req: Request, url: URL): Promise<Response | null> {
+    if (!this.#web.ssr) return null;
     const clientPrefix = "/_akan/client/";
     if (url.pathname.startsWith(clientPrefix)) {
       const filePath = this.#safeResolve(

package/server/akanServer.ts

@@ -1,3 +1,4 @@
+import type { AkanWebConfig, AkanWebOption } from "akanjs";
 import { type BackendEnv, type BaseEnv, getEnv } from "akanjs/base";
 import { Logger, websocketBinaryFrameContract } from "akanjs/common";
 import { DictionaryLookup } from "akanjs/dictionary";
@@ -5,6 +6,7 @@ import type {
   Adaptor,
   AdaptorCls,
   AkanIpcMessage,
+  AkanMetricsReport,
   DatabaseConfig,
   Service,
   ServiceCls,
@@ -14,6 +16,7 @@ import type { ServerSignal, ServerSignalCls, WebsocketPublishData } from "akanjs
 import { AgentRelayAccess } from "../signal/guards";
 import { createOpenApiDocument } from "../signal/openapi";
 import { FetchSerializer } from "../signal/serializer";
+import { SignalContext } from "../signal/signalContext";
 import type { AkanLib, AkanLibProps } from "./akanLib";
 import type { BuilderRpc } from "./artifact";
 import { BinaryPubsub } from "./binaryPubsub";
@@ -21,14 +24,23 @@ import { DevtoolsRouter } from "./devtools";
 import { DiLifecycle } from "./di/diLifecycle";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub";
 import { isPortInUseError } from "./lifecycle/portInUse";
+import { resolveRuntimeDir } from "./lifecycle/runtimeDir";
 import { ShutdownManager } from "./lifecycle/shutdownManager";
+import { RotatingLogWriter } from "./logging/rotatingLogWriter";
 import { type McpAuthOption, McpRouter } from "./mcp";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
 import { WebProxyRunner } from "./proxy";
 import { SignalResolver } from "./resolver";
 import { ApiRouter } from "./routing/apiRouter";
 import type { AppWsData } from "./routing/appWsData";
-import type { HttpRoutes, LocalPublish, SignalRoutes, WebsocketRoutes } from "./types";
+import { createSoloAppRoutes } from "./routing/soloAppRoutes";
+import {
+  getWebConfigFromEnv,
+  type HttpRoutes,
+  type LocalPublish,
+  type SignalRoutes,
+  type WebsocketRoutes,
+} from "./types";
 import type { WebRouter } from "./webRouter";
 
 export interface AkanServerProps extends AkanLibProps {
@@ -135,6 +147,8 @@ export class AkanServer {
   mcpAuth: McpAuthOption = AkanServer.#mcpAuthFromEnv();
   mcpOption: Omit<McpServerOption, "enabled" | "readOnly" | "auth"> = AkanServer.#mcpOptionFromEnv();
   serverMode: "federation" | "batch" | "all";
+  /** Resolved at `init`: what this process actually serves, after env and artifact availability. */
+  web: AkanWebConfig = getWebConfigFromEnv();
   modules: string[];
   shutdownTimeoutMs = AkanServer.#defaultShutdownTimeoutMs();
 
@@ -142,6 +156,16 @@ export class AkanServer {
   #localPublish: LocalPublish | null = null;
   readonly #binaryPubsub = new BinaryPubsub();
   #metricsTimer: Timer | null = null;
+  /**
+   * No gateway socket means nothing is proxying this process, so it owns the whole surface: the
+   * `/_akan/app/*` observability routes the gateway would have answered, and the rotating log file the
+   * gateway would have written. Derived rather than declared — a spawned child always carries the socket,
+   * so the two modes cannot disagree about which one this is.
+   */
+  readonly #solo = !process.env.AKAN_CHILD_SOCKET;
+  #logWriter: RotatingLogWriter | null = null;
+  #removeLogSink: (() => void) | null = null;
+  #lastMetrics: AkanMetricsReport = {};
   constructor(
     name = "AkanServer",
     env: BackendEnv = {},
@@ -184,6 +208,12 @@ export class AkanServer {
     this.openapi = openapi;
     return this;
   }
+  /** Narrows the web surface this process serves. Never widens it past what the build produced. */
+  setWeb(web: AkanWebOption = true) {
+    if (this.status !== "stopped") throw new Error("Web config must be set before app initialization.");
+    this.web = AkanServer.#narrowWeb(this.web, web);
+    return this;
+  }
   setMcp(mcp: boolean | McpServerOption = true) {
     if (this.status !== "stopped") throw new Error("MCP config must be set before app initialization.");
     this.mcp = typeof mcp === "boolean" ? mcp : (mcp.enabled ?? true);
@@ -256,7 +286,7 @@ export class AkanServer {
     };
   }
 
-  async init({ routes: initRoutes = true, web = true }: { routes?: boolean; web?: boolean } = {}) {
+  async init({ routes: initRoutes = true, web }: { routes?: boolean; web?: AkanWebOption } = {}) {
     if (this.status !== "stopped") throw new Error("AkanServer is not able to init. It is already running.");
     this.status = "initializing";
     const { routes, wsRoutes, routeOptions } = await this.#di.initializeAll();
@@ -265,7 +295,8 @@ export class AkanServer {
       this.status = "initialized";
       return this;
     }
-    if (!web) {
+    const requestedWeb = AkanServer.#narrowWeb(this.web, web);
+    const noWeb = () => {
       this.#prepared = {
         routes,
         routeOptions,
@@ -279,11 +310,25 @@ export class AkanServer {
       };
       this.status = "initialized";
       return this;
+    };
+    if (!requestedWeb.ssr) {
+      this.web = requestedWeb;
+      this.logger.info("web off: serving api only (AKAN_SSR=false, or a build with `web: false`)");
+      return noWeb();
     }
     const { WebRouter } = await import("./webRouter");
     const webRouter = await WebRouter.create({
+      web: requestedWeb,
       upgradeHmrWs: (req, data) => this.#server?.upgrade(req, { data }) ?? false,
     });
+
+    if (!webRouter) {
+      this.web = { ssr: false, csr: false };
+      this.logger.warn("web off: no build artifact under .akan/artifact; serving api only");
+      return noWeb();
+    }
+    this.web = webRouter.web;
+    this.logger.info(`web on: ssr=${this.web.ssr} csr=${this.web.csr}`);
     const { renderEnvRoutes, hmrHub, builderRpc } = await webRouter.initializeRoute();
     const webProxyRunner = WebProxyRunner.create(this.#di.webProxies);
     this.#prepared = {
@@ -306,6 +351,7 @@ export class AkanServer {
       throw new Error("AkanServer is not able to listen. Call `init` first.");
     }
     this.status = "starting";
+    this.#startFileLogging();
     const port = process.env.AKAN_CHILD_SOCKET
       ? undefined
       : Number(process.env.AKAN_CHILD_WS_PORT || process.env.PORT || 8282);
@@ -371,6 +417,8 @@ export class AkanServer {
 
     const server = this.#server;
     const wsServer = this.#wsServer;
+
+    SignalContext.setHttpPeerResolver((req) => server?.requestIP(req as Bun.BunRequest) ?? null);
     hmrHub?.setPublisher((topic, payload) => {
       server?.publish(topic, payload);
       wsServer?.publish(topic, payload);
@@ -412,7 +460,7 @@ export class AkanServer {
     return this;
   }
 
-  async start({ listen, web = true }: { listen?: boolean; web?: boolean } = {}) {
+  async start({ listen, web }: { listen?: boolean; web?: AkanWebOption } = {}) {
     const isNoListenCommand = process.env.AKAN_COMMAND_TYPE === "script" || process.env.AKAN_COMMAND_TYPE === "console";
     const shouldListen = (listen ?? !isNoListenCommand) && this.serverMode !== "batch";
     await this.init({ routes: shouldListen, web });
@@ -454,9 +502,11 @@ export class AkanServer {
       this.#wsServer?.stop(true);
       this.#server = null;
       this.#wsServer = null;
+      SignalContext.setHttpPeerResolver(null);
 
       this.#prepared?.webRouter?.dispose();
       await this.#withShutdownTimeout(this.#di.destroyAll());
+      await this.#stopFileLogging();
       this.#prepared = null;
       this.status = "stopped";
       this.logger.info(`Shutdown completed successfully in ${Date.now() - now}ms`);
@@ -517,6 +567,7 @@ export class AkanServer {
       pubsubCoalesceCount: this.#binaryPubsub.coalescedCount,
       ...(this.#prepared?.webRouter?.getMetrics() ?? {}),
     });
+    this.#lastMetrics = metrics;
     process.send?.({ type: "metrics.report", pid: process.pid, metrics } satisfies AkanIpcMessage);
     if (process.env.AKAN_MEMORY_LOG === "1") {
       this.logger.info(`memory role=${this.serverMode} ${ProcessMetricsCollector.format(metrics)}`);
@@ -570,6 +621,15 @@ export class AkanServer {
           })
         : null;
     const mcpRoutes: HttpRoutes = mcpRouter?.createRoutes() ?? {};
+    const soloRoutes: HttpRoutes = this.#solo
+      ? createSoloAppRoutes(() => ({
+          role: this.serverMode,
+          running: this.status === "running",
+          status: this.status,
+          port: this.#server?.port ?? null,
+          metrics: this.#lastMetrics,
+        }))
+      : {};
 
     mcpRouter?.report();
 
@@ -583,7 +643,24 @@ export class AkanServer {
       openapi: this.openapi,
       getStatus: () => this.status,
     }).createRoutes();
-    return { ...openapiRoutes, ...mcpRoutes, ...devtoolsRoutes };
+    return { ...openapiRoutes, ...mcpRoutes, ...devtoolsRoutes, ...soloRoutes };
+  }
+
+  #startFileLogging() {
+    if (!this.#solo || this.#logWriter) return;
+    this.#logWriter = RotatingLogWriter.fromRuntimeDir(resolveRuntimeDir());
+    if (!this.#logWriter) return;
+    this.#removeLogSink = Logger.addSink((entry) => {
+      this.#logWriter?.write(this.serverMode, entry.plainMessage);
+    });
+  }
+
+  async #stopFileLogging() {
+    this.#removeLogSink?.();
+    this.#removeLogSink = null;
+    const writer = this.#logWriter;
+    this.#logWriter = null;
+    await writer?.close();
   }
 
   /**
@@ -638,6 +715,13 @@ export class AkanServer {
     return !names.some((name) => process.env[name] === "false" || process.env[name] === "0");
   }
 
+  /** Narrows only — a surface the build or the env left out cannot be switched back on here. */
+  static #narrowWeb(current: AkanWebConfig, web: AkanWebOption | undefined): AkanWebConfig {
+    if (web === undefined || web === true) return current;
+    if (web === false) return { ssr: false, csr: false };
+    return { ssr: current.ssr, csr: web.csr && current.csr };
+  }
+
   /** Named rather than defaulted: an absent env must leave the option unset so a value written in code still wins. */
   static #isEnvOff(...names: string[]) {
     return names.some((name) => process.env[name] === "false" || process.env[name] === "0");

package/server/lifecycle/runtimeDir.ts

@@ -0,0 +1,14 @@
+import path from "node:path";
+
+/**
+ * Where a replica keeps its child sockets and rotating logs. Both the gateway and a solo server resolve it,
+ * and they must land on the same directory: switching between the two modes must not move the log file.
+ */
+export const resolveRuntimeDir = (runtimeDir?: string): string =>
+  path.resolve(
+    runtimeDir ??
+      process.env.AKAN_RUNTIME_DIR ??
+      (process.env.NODE_ENV === "production"
+        ? path.resolve(process.cwd(), "runtime")
+        : path.resolve(process.cwd(), "local", "apps", process.env.AKAN_PUBLIC_APP_NAME ?? "unknown", "runtime")),
+  );

package/server/processMetricsCollector.ts

@@ -1,5 +1,5 @@
 import type { AkanMetricsReport } from "akanjs/service";
-import { getTraceSnapshot, isTraceEnabled } from "akanjs/signal";
+import { getTraceSnapshot, isTraceEnabled } from "../signal/trace";
 
 type BunJscHeapStats = {
   heapSize?: number;

package/server/resolver/signal.resolver.ts

@@ -9,6 +9,7 @@ import {
   INTERNAL_META,
   Int,
   PrimitiveRegistry,
+  type PromiseOrObject,
   SLICE_META,
 } from "akanjs/base";
 import { capitalize, Logger } from "akanjs/common";
@@ -331,6 +332,42 @@ export class SignalResolver {
     Bun.ServerWebSocket<unknown>,
     Map<string, SignalContext<WebSocketExecutionContext>>
   >();
+  /**
+   * Message contexts that registered a lifecycle handler. A message context is otherwise dropped the moment it
+   * answers, so `ws.on("disconnect", …)` from one would land in an object nothing reads again — a silent
+   * no-op beside the same call working from a pubsub subscribe.
+   */
+  static #liveWsMessageCtx = new WeakMap<Bun.ServerWebSocket<unknown>, Set<SignalContext<WebSocketExecutionContext>>>();
+  static #retainWsContext(ws: Bun.ServerWebSocket<unknown>, context: SignalContext<WebSocketExecutionContext>) {
+    const wsCtx = context.getWebSocketContext();
+    if (!wsCtx.onDisconnect.size && !wsCtx.onUnsubscribe.size) return;
+    const contexts = SignalResolver.#liveWsMessageCtx.get(ws) ?? new Set<SignalContext<WebSocketExecutionContext>>();
+    contexts.add(context);
+    SignalResolver.#liveWsMessageCtx.set(ws, contexts);
+  }
+  /**
+   * Cleanup handlers belong to the app, so one that throws must not take the rest of the teardown with it: a
+   * rejection here would skip `unregisterSocket` and leak the socket's room membership in Redis for good.
+   *
+   * A close ends both the subscription and the connection, so it passes both events — and a handler registered
+   * for both, the way a cleanup that must happen either way is written, runs once rather than twice.
+   */
+  static async #runLifecycleHandlers(
+    contexts: Iterable<SignalContext<WebSocketExecutionContext>>,
+    events: ("unsubscribe" | "disconnect")[],
+  ) {
+    const handlers = new Set<() => PromiseOrObject<void>>();
+    for (const event of events)
+      for (const context of contexts) {
+        const wsCtx = context.getWebSocketContext();
+        for (const handler of event === "disconnect" ? wsCtx.onDisconnect : wsCtx.onUnsubscribe) handlers.add(handler);
+      }
+    if (!handlers.size) return;
+    const results = await Promise.allSettled([...handlers].map(async (handler) => await handler()));
+    for (const result of results)
+      if (result.status === "rejected")
+        SignalResolver.logger.error(`WebSocket cleanup handler failed: ${result.reason}`);
+  }
   /**
    * A path may legitimately carry several methods — a `query` GET and a `mutation` POST sharing a custom `path` —
    * so methods merge rather than replace. The same method twice leaves one of the two endpoints unreachable with
@@ -451,10 +488,7 @@ export class SignalResolver {
               const roomCtxMap = SignalResolver.#liveWsPubsubRoomCtx.get(ws);
               if (roomCtxMap) {
                 const roomCtx = roomCtxMap.get(roomId);
-                if (roomCtx) {
-                  const unsubscribeHandlers = [...roomCtx.getWebSocketContext().onUnsubscribe.values()];
-                  await Promise.all(unsubscribeHandlers.map((handler) => handler()));
-                }
+                if (roomCtx) await SignalResolver.#runLifecycleHandlers([roomCtx], ["unsubscribe"]);
                 roomCtxMap.delete(roomId);
                 if (roomCtxMap.size === 0) SignalResolver.#liveWsPubsubRoomCtx.delete(ws);
                 
@@ -474,6 +508,7 @@ export class SignalResolver {
               { endpointInfo, adaptor: endpoint, registry, env, live, middleware },
             ).init();
             const result = (await context.exec()) as object | object[];
+            SignalResolver.#retainWsContext(ws, context as SignalContext<WebSocketExecutionContext>);
             const messageData: WebsocketMessageData = { type: "msg", key, data: result };
             return messageData;
           };
@@ -535,7 +570,7 @@ export class SignalResolver {
     for (const [roomId, roomCtx] of [...roomCtxMap]) {
       if (await roomCtx.authorize()) continue;
       ws.unsubscribe(roomId);
-      await Promise.all([...roomCtx.getWebSocketContext().onUnsubscribe.values()].map((handler) => handler()));
+      await SignalResolver.#runLifecycleHandlers([roomCtx], ["unsubscribe"]);
       roomCtxMap.delete(roomId);
       websocket.leaveRoom(ws, roomId);
       revokedRooms.push(roomId);
@@ -550,18 +585,13 @@ export class SignalResolver {
   }
 
   static async handleWsClose(ws: Bun.ServerWebSocket<any>, registry: InjectRegistry) {
-    const roomCtxMap = SignalResolver.#liveWsPubsubRoomCtx.get(ws);
-    if (roomCtxMap) {
-      const unsubscribeHandlers = [...roomCtxMap.values()].flatMap((roomCtx) => [
-        ...roomCtx.getWebSocketContext().onUnsubscribe.values(),
-      ]);
-      await Promise.all(unsubscribeHandlers.map((handler) => handler()));
-      const disconnectHandlers = [...roomCtxMap.values()].flatMap((roomCtx) => [
-        ...roomCtx.getWebSocketContext().onDisconnect.values(),
-      ]);
-      await Promise.all(disconnectHandlers.map((handler) => handler()));
-    }
+    const contexts = [
+      ...(SignalResolver.#liveWsPubsubRoomCtx.get(ws)?.values() ?? []),
+      ...(SignalResolver.#liveWsMessageCtx.get(ws) ?? []),
+    ];
+    await SignalResolver.#runLifecycleHandlers(contexts, ["unsubscribe", "disconnect"]);
     SignalResolver.#liveWsPubsubRoomCtx.delete(ws);
+    SignalResolver.#liveWsMessageCtx.delete(ws);
 
     await SignalResolver.#getWebsocket(registry).unregisterSocket(ws);
     SignalResolver.logger.verbose(`WebSocket disconnected from all rooms`);

package/server/routing/soloAppRoutes.ts

@@ -0,0 +1,46 @@
+import type { AkanChildRole, AkanMetricsReport } from "akanjs/service";
+import type { HttpRoutes } from "../types";
+
+export interface SoloAppStatus {
+  role: AkanChildRole;
+  running: boolean;
+  status: string;
+  port: number | null;
+  metrics: AkanMetricsReport;
+}
+
+/**
+ * The gateway's `/_akan/app/*` surface, answered by a process nothing is proxying. The payload keeps the
+ * gateway's own shape — a `children` array with this process as its only entry — so a probe, a k8s check and
+ * `akan` tooling read one contract whether or not a gateway is in front.
+ */
+export const createSoloAppRoutes = (read: () => SoloAppStatus): HttpRoutes => {
+  const child = () => {
+    const { role, running, status, port } = read();
+    return {
+      idx: 0,
+      role,
+      status: running ? "healthy" : status,
+      ready: running,
+      pid: process.pid,
+      upstream: { type: "tcp" as const, host: "127.0.0.1", port },
+    };
+  };
+  return {
+    "/_akan/app/health": {
+      GET: () => Response.json({ status: read().status, pid: process.pid, solo: true, children: [child()] }),
+    },
+    "/_akan/app/metrics": {
+      GET: () =>
+        Response.json({
+          rooms: 0,
+          sockets: 0,
+          solo: true,
+          gateway: null,
+          proxyHop: null,
+          children: [{ ...child(), metrics: read().metrics }],
+        }),
+    },
+    "/_akan/bench/ping": { GET: () => new Response("ok") },
+  };
+};

package/server/types.tsx

@@ -1,3 +1,4 @@
+import type { AkanWebConfig } from "akanjs";
 import type { PromiseOrObject } from "akanjs/base";
 import type { AkanI18nConfig } from "akanjs/common";
 import type { ClientManifest } from "./artifact";
@@ -102,6 +103,28 @@ export type BaseBuildArtifact = {
   i18n: AkanI18nConfig;
   imageConfig: AkanImageConfig;
   deepLinkAssociations?: MobileDeepLinkAssociation[];
+  /**
+   * Which surfaces this artifact was built for. Absent on an artifact written before the option existed,
+   * which is read as both on — the shape every such build actually has.
+   */
+  web?: AkanWebConfig;
+};
+
+export const resolveWebConfig = (web: Partial<AkanWebConfig> | undefined): AkanWebConfig => ({
+  ssr: web?.ssr ?? true,
+  csr: web?.csr ?? true,
+});
+
+/**
+ * `AKAN_SSR` / `AKAN_CSR`, both on unless the env says otherwise — the same shape `AKAN_MCP` uses, because a
+ * switch a deployment has to find before anything works is a switch most deployments never find. Read by the
+ * gateway and by every replica, so both agree on what the pod serves.
+ */
+export const getWebConfigFromEnv = (): AkanWebConfig => {
+  const off = (name: string) => process.env[name] === "false" || process.env[name] === "0";
+  const ssr = !off("AKAN_SSR");
+  
+  return { ssr, csr: ssr && !off("AKAN_CSR") };
 };
 
 export interface MobileDeepLinkAssociation {

package/server/webRouter.ts

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import type { AkanWebConfig } from "akanjs";
 import { getEnv } from "akanjs/base";
 import {
   type AkanI18nConfig,
@@ -54,7 +55,7 @@ import { createDefaultSitemapXml, getSitemapBasePath } from "./sitemap";
 import { SsrFromRscRenderer } from "./ssrFromRscRenderer";
 import type { RscTraceMetadata, SsrManifest } from "./ssrTypes";
 import { createSubRouteIndexResponse, createSystemPageResponse, getSystemPageHomeHref } from "./systemPages";
-import type { BaseBuildArtifact, HttpRoutes, RenderState } from "./types";
+import { type BaseBuildArtifact, type HttpRoutes, type RenderState, resolveWebConfig } from "./types";
 
 const CLIENT_CLOSED_REQUEST_STATUS = 499;
 export const DEFAULT_HTML_RESULT_CACHE_MAX_BODY_BYTES = 2 * 1024 * 1024;
@@ -262,11 +263,13 @@ export interface SsrRoutesResult {
 }
 
 export interface SsrRoutesInputs {
+  web: AkanWebConfig;
   upgradeHmrWs: (req: Request, data: HmrWsData) => boolean;
 }
 
 interface WebRouterOptions {
   artifact: BaseBuildArtifact;
+  web: AkanWebConfig;
   cssBytesByUrl: Record<string, Uint8Array>;
   rsc: RscWorker;
   seedIndex: RouteSeedIndex;
@@ -319,9 +322,12 @@ export class WebRouter {
   #htmlCacheBypass = 0;
   #runtimeManifest: { revision: number; manifest: MergedManifest } | null = null;
   renderState: RenderState;
+  /** What this router actually mounts, already intersected with what the artifact carries. */
+  readonly web: AkanWebConfig;
   #seedIndex: RouteSeedIndex;
-  constructor({ artifact, cssBytesByUrl, rsc, seedIndex, upgradeHmrWs }: WebRouterOptions) {
+  constructor({ artifact, web, cssBytesByUrl, rsc, seedIndex, upgradeHmrWs }: WebRouterOptions) {
     this.#logger.verbose(`[SSR] loaded ${Object.keys(cssBytesByUrl).length} CSS assets`);
+    this.web = web;
     if (process.env.NODE_ENV === "production" && !this.#prodMode)
       this.#logger.warn("[SSR] NODE_ENV=production ignored under `akan start`; serving in dev mode");
     this.#artifact = artifact;
@@ -382,14 +388,16 @@ export class WebRouter {
     });
 
     const renderEnvRoutes: HttpRoutes = {
-      "/__csr": async () => {
-        this.#requestStats.csr += 1;
-        const csrHtml = await this.#resolveCsrHtml(csrOutputDir, "/");
-        const csrFile = csrHtml ? Bun.file(csrHtml) : null;
-        const htmlText =
-          csrFile && (await csrFile.exists())
-            ? await csrFile.text()
-            : `<!doctype html>
+      ...(this.web.csr
+        ? {
+            "/__csr": async () => {
+              this.#requestStats.csr += 1;
+              const csrHtml = await this.#resolveCsrHtml(csrOutputDir, "/");
+              const csrFile = csrHtml ? Bun.file(csrHtml) : null;
+              const htmlText =
+                csrFile && (await csrFile.exists())
+                  ? await csrFile.text()
+                  : `<!doctype html>
 <html lang="en">
   <head>
     <meta charset="utf-8" />
@@ -402,10 +410,12 @@ export class WebRouter {
     <script type="module" src="/csr.js"></script>
   </body>
 </html>`;
-        return new Response(this.#withCsrHmr(htmlText), {
-          headers: { "Content-Type": "text/html; charset=utf-8" },
-        });
-      },
+              return new Response(this.#withCsrHmr(htmlText), {
+                headers: { "Content-Type": "text/html; charset=utf-8" },
+              });
+            },
+          }
+        : {}),
       [`${clientServePrefix}/*`]: async (req) => {
         this.#requestStats.staticAsset += 1;
         const url = new URL(req.url);
@@ -526,20 +536,20 @@ export class WebRouter {
           return imageOptimizer.handle(req);
         }
 
-        const isCsr = url.searchParams.get("csr") === "true";
-        if (isCsr) {
-          this.#requestStats.csr += 1;
-          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" },
-          });
-        }
+        if (this.web.csr) {
+          const isCsr = url.searchParams.get("csr") === "true";
+          if (isCsr) {
+            this.#requestStats.csr += 1;
+            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" },
+            });
+          }
 
-        const csrAssetPath = path.extname(url.pathname) ? WebRouter.#safeResolve(csrOutputDir, url.pathname) : null;
-        if (csrAssetPath) {
-          if (await Bun.file(csrAssetPath).exists()) {
+          const csrAssetPath = path.extname(url.pathname) ? WebRouter.#safeResolve(csrOutputDir, url.pathname) : null;
+          if (csrAssetPath && (await Bun.file(csrAssetPath).exists())) {
             this.#requestStats.staticAsset += 1;
             return WebRouter.#fileResponse(req, csrAssetPath, {
               contentType: Bun.file(csrAssetPath).type || "application/octet-stream",
@@ -1034,18 +1044,24 @@ export class WebRouter {
     });
   }
 
-  static async create({ upgradeHmrWs }: SsrRoutesInputs) {
+  /**
+   * `null` when the build produced no web artifact — an api-only build, or a workspace with no `page/` at all.
+   * The caller boots without a web surface instead of failing on the missing file.
+   */
+  static async create({ web, upgradeHmrWs }: SsrRoutesInputs): Promise<WebRouter | null> {
     const artifactDir = WebRouter.#resolveArtifactDir();
-    const artifact = WebRouter.#normalizeArtifact(
-      (await Bun.file(path.join(artifactDir, "base-artifact.json")).json()) as BaseBuildArtifact,
-      artifactDir,
-    );
+    const artifactFile = Bun.file(path.join(artifactDir, "base-artifact.json"));
+    if (!(await artifactFile.exists())) return null;
+    const artifact = WebRouter.#normalizeArtifact((await artifactFile.json()) as BaseBuildArtifact, artifactDir);
+    const builtWeb = resolveWebConfig(artifact.web);
+    if (!builtWeb.ssr) return null;
     const cssBytesByUrl = await WebRouter.#loadCssBytesByUrl(artifact, artifactDir);
     const rsc = new RscWorker(artifact);
     await rsc.ready;
     const seedIndex = await RouteSeedIndexStore.load(artifactDir);
     return new WebRouter({
       artifact,
+      web: { ssr: true, csr: web.csr && builtWeb.csr },
       cssBytesByUrl,
       rsc,
       seedIndex,

package/signal/internalArg.ts

@@ -38,10 +38,9 @@ export class Ip implements InternalArg<string | null> {
  * Injects websocket state, this connection's id, and subscription hooks into message/pubsub handlers.
  * `socketId` is the one `AppWsData` minted at the handshake, so a handler never reads `ws.data` to
  * tell two callers apart — and never mints an id of its own, which would not match the room bookkeeping.
+ * `on`/`off` register cleanup that runs when the room is unsubscribed or the socket closes.
  */
 export class Ws implements InternalArg {
-  onDisconnect?: () => void;
-  onUnsubscribe?: () => void;
   getArg(context: SignalContext) {
     const webSocketContext = context.getWebSocketContext<{ socketId: string }>();
     const ws = webSocketContext.ws;

package/signal/signalContext.ts

@@ -27,6 +27,9 @@ import { isTraceEnabled, runWithTrace, SignalTrace, traceSpan } from "./trace";
 
 export type SignalTransportType = "http" | "websocket";
 
+/** What `Bun.Server.requestIP` reports for the socket a request arrived on. */
+export type HttpPeerResolver = (req: Request) => { address: string; port: number } | null;
+
 const httpEndpointTypes = new Set<EndpointType>(["query", "mutation", "prompt"]);
 
 interface WebSocketRequest {
@@ -203,6 +206,16 @@ export class SignalContext<
    * hold for the life of the process. Building both per request cost an instance, a handler and a closure on every
    * call for every registered middleware — and `Logging` is registered by default.
    */
+  static #httpPeer: HttpPeerResolver | null = null;
+  /**
+   * Lets the http branch of `getClientIp` reach the socket the way the websocket branch already reaches
+   * `ws.remoteAddress`. Registered by whichever `Bun.serve` is listening, because only the server can answer
+   * `requestIP`. Behind the federation gateway this never fires — the gateway always writes `x-real-ip` —
+   * so it is the answer for a process nothing is proxying.
+   */
+  static setHttpPeerResolver(resolve: HttpPeerResolver | null) {
+    SignalContext.#httpPeer = resolve;
+  }
   static #middlewareHandlers = new WeakMap<MiddlewareCls, WeakMap<object, Promise<MiddlewareHandler>>>();
   static #getMiddlewareHandler(MiddlewareCls: MiddlewareCls, env: BackendEnv): Promise<MiddlewareHandler> {
     const byEnv =
@@ -440,14 +453,23 @@ export class SignalContext<
    * because a loopback-looking address for an unknown caller is the failure this replaced.
    */
   getClientIp(): string | null {
-    if (this.transport === "http") return clientAddressFromHeaders(this.getHttpContext().req.headers);
+    if (this.transport === "http") {
+      const { req } = this.getHttpContext();
+      const forwarded = clientAddressFromHeaders(req.headers);
+      if (forwarded) return forwarded;
+      const peer = SignalContext.#httpPeer?.(req);
+      return peer ? normalizeIpAddress(peer.address) : null;
+    }
     const { ws } = this.getWebSocketContext<{ headers?: Headers }>();
     const forwarded = ws.data.headers ? clientAddressFromHeaders(ws.data.headers) : null;
     return forwarded ?? (ws.remoteAddress ? normalizeIpAddress(ws.remoteAddress) : null);
   }
   /** The caller's source port as the nearest proxy recorded it, else this socket's own. */
   getClientPort(): number | null {
-    if (this.transport === "http") return clientPortFromHeaders(this.getHttpContext().req.headers);
+    if (this.transport === "http") {
+      const { req } = this.getHttpContext();
+      return clientPortFromHeaders(req.headers) ?? SignalContext.#httpPeer?.(req)?.port ?? null;
+    }
     const { ws } = this.getWebSocketContext<{ headers?: Headers }>();
     return (ws.data.headers ? clientPortFromHeaders(ws.data.headers) : null) ?? null;
   }
@@ -593,14 +615,15 @@ export class WebSocketExecutionContext<Appended = unknown> {
       nullable: endpointInfo.returns.nullable,
     }) as unknown as Response;
   }
-  on(event: "disconnect" | "unsubscribe", handler: () => void) {
+
+  on = (event: "disconnect" | "unsubscribe", handler: () => PromiseOrObject<void>) => {
     if (event === "disconnect") this.onDisconnect.add(handler);
     else this.onUnsubscribe.add(handler);
-  }
-  off(event: "disconnect" | "unsubscribe", handler: () => void) {
+  };
+  off = (event: "disconnect" | "unsubscribe", handler: () => PromiseOrObject<void>) => {
     if (event === "disconnect") this.onDisconnect.delete(handler);
     else this.onUnsubscribe.delete(handler);
-  }
+  };
 }
 
 export class ResolveFieldContext {

package/types/index.d.ts

@@ -2,19 +2,36 @@ import type { AkanI18nConfig } from "akanjs/common";
 import type { AkanImageConfig } from "akanjs/server";
 export declare const archs: readonly ["amd64", "arm64"];
 export type Arch = (typeof archs)[number];
-export interface DockerConfig {
-    content: string;
+/** One image step. The object form runs only on the matching `TARGETARCH` leg of a multi-arch build. */
+export type DockerRun = string | {
+    [key in Arch]?: string;
+};
+/** The pieces Akan assembles a Dockerfile from. */
+export interface DockerImageConfig {
     image: string | {
         [key in Arch]?: string;
     };
-    preRuns: (string | {
-        [key in Arch]?: string;
-    })[];
-    postRuns: (string | {
-        [key in Arch]?: string;
-    })[];
+    /** Runs before `bun install`, so a system package a native dependency needs is there for the install. */
+    preRuns: DockerRun[];
+    /** Runs after `bun install`, before the app files are copied. */
+    postRuns: DockerRun[];
     command: string[];
 }
+/**
+ * A whole Dockerfile as a string, or the parts Akan assembles one from. The string form is taken verbatim —
+ * nothing is merged into it, including the steps a lib contributes through its own `docker`.
+ */
+export type DockerConfig = string | DockerImageConfig;
+/** What an `akan.config.ts` may write for `docker`: a whole Dockerfile, or any subset of the parts. */
+export type DockerOption = string | Partial<DockerImageConfig>;
+/**
+ * A lib's contribution to the image of every app that mounts it — a lib never picks the base image or the
+ * command, only the steps its own runtime needs.
+ */
+export interface LibDockerConfig {
+    preRuns: DockerRun[];
+    postRuns: DockerRun[];
+}
 export interface AkanRouteDomains {
     main?: string[];
     develop?: string[];
@@ -25,6 +42,24 @@ export interface AkanRouteConfig {
     basePath?: string;
     domains: AkanRouteDomains;
 }
+/**
+ * Which web surfaces an app serves, resolved. `ssr` is the RSC/SSR route renderer and everything it needs —
+ * the pages bundle, the client bundles, the RSC worker process. `csr` is the single-file SPA shell that the
+ * Capacitor mobile build ships and that `/__csr` serves.
+ */
+export interface AkanWebConfig {
+    ssr: boolean;
+    csr: boolean;
+}
+/**
+ * What an `akan.config.ts` may write. `false` is an API-only app — no web artifact is built and no web route
+ * is mounted; `true` (the default) is both surfaces. The object form keeps SSR and toggles only the CSR
+ * bundle, which is the whole range there is: the CSR bundle inlines the stylesheet the SSR build compiles, so
+ * CSR without SSR would ship an unstyled app and is not expressible here.
+ */
+export type AkanWebOption = boolean | {
+    csr: boolean;
+};
 export type DatabaseMode = "single" | "multiple" | "cluster";
 export type MobileEnv = "local" | "debug" | "develop" | "main";
 export type MobilePermission = "camera" | "contacts" | "location" | "push" | "speech";
@@ -160,6 +195,8 @@ export interface AkanPlugin {
 export interface AppConfigResult {
     docker: DockerConfig;
     defaultDatabaseMode: DatabaseMode;
+    /** Web surfaces built into the app and mounted at boot. Both default to `true`. */
+    web: AkanWebConfig;
     routes?: AkanRouteConfig[];
     /**
      * Mounts `libs/<lib>/page` into this app under `page/(libs)/(<lib>)` on sync. `true` takes every lib
@@ -178,6 +215,8 @@ export interface AppConfigResult {
 }
 export interface LibConfigResult {
     externalLibs: string[];
+    /** Image steps every app that mounts this lib inherits, unless that app declares a whole Dockerfile. */
+    docker: LibDockerConfig;
 }
 export type DeepPartial<T> = {
     [P in keyof T]?: T[P] extends unknown[] ? T[P] : T[P] extends object ? DeepPartial<T[P]> : T[P];
@@ -190,7 +229,9 @@ export interface LibConfigContext {
     readonly name: string;
     readonly type: "lib";
 }
-export type AppConfigInput = DeepPartial<AppConfigResult> & {
+export type AppConfigInput = Omit<DeepPartial<AppConfigResult>, "docker" | "web"> & {
+    docker?: DockerOption;
+    web?: AkanWebOption;
     plugins?: AkanPlugin[];
 };
 export type LibConfigInput = DeepPartial<LibConfigResult> & {

package/types/server/akanApp.d.ts

@@ -12,6 +12,13 @@ export interface AkanAppOptions {
      * module. Handed down as `AKAN_MODULES`, since each replica builds its own container.
      */
     modules?: string[];
+    /**
+     * Run the one replica in this process instead of spawning it — see `#startSolo`. Defaults on for a single
+     * traffic replica the environment configured, and off whenever `replica` is passed here, because code that
+     * states a topology is asking for the gateway that serves it. `AKAN_SOLO=false` turns it off; like
+     * `AKAN_SSR`, the env can only narrow, so it cannot force a gateway's replicas into one process.
+     */
+    solo?: boolean;
 }
 /** Gateway/orchestrator that starts Akan child servers and proxies HTTP/WebSocket traffic. */
 export declare class AkanApp {

package/types/server/akanServer.d.ts

@@ -1,3 +1,4 @@
+import type { AkanWebConfig, AkanWebOption } from "akanjs";
 import { type BackendEnv, type BaseEnv } from "akanjs/base";
 import { Logger } from "akanjs/common";
 import type { Adaptor, AdaptorCls, DatabaseConfig, Service, ServiceCls, SolidConfig } from "akanjs/service";
@@ -89,12 +90,16 @@ export declare class AkanServer {
     mcpAuth: McpAuthOption;
     mcpOption: Omit<McpServerOption, "enabled" | "readOnly" | "auth">;
     serverMode: "federation" | "batch" | "all";
+    /** Resolved at `init`: what this process actually serves, after env and artifact availability. */
+    web: AkanWebConfig;
     modules: string[];
     shutdownTimeoutMs: number;
     constructor(name?: string, env?: BackendEnv, serverMode?: "federation" | "batch" | "all", ...libsOrOptions: (AkanLib | AkanServerOptions)[]);
     setPrefix(prefix: string): this;
     setWebsocketPrefix(websocketPrefix: string): this;
     setOpenApi(openapi?: boolean): this;
+    /** Narrows the web surface this process serves. Never widens it past what the build produced. */
+    setWeb(web?: AkanWebOption): this;
     setMcp(mcp?: boolean | McpServerOption): this;
     setDatabaseConfig(database: DatabaseConfig): this;
     setSolidConfig(solid: SolidConfig): this;
@@ -108,12 +113,12 @@ export declare class AkanServer {
     inspectConsole(): AkanServerConsoleInfo;
     init({ routes: initRoutes, web }?: {
         routes?: boolean;
-        web?: boolean;
+        web?: AkanWebOption;
     }): Promise<this>;
     listen(): Promise<this>;
     start({ listen, web }?: {
         listen?: boolean;
-        web?: boolean;
+        web?: AkanWebOption;
     }): Promise<this>;
     stop(): Promise<void>;
 }

package/types/server/lifecycle/runtimeDir.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Where a replica keeps its child sockets and rotating logs. Both the gateway and a solo server resolve it,
+ * and they must land on the same directory: switching between the two modes must not move the log file.
+ */
+export declare const resolveRuntimeDir: (runtimeDir?: string) => string;

package/types/server/routing/soloAppRoutes.d.ts

@@ -0,0 +1,15 @@
+import type { AkanChildRole, AkanMetricsReport } from "akanjs/service";
+import type { HttpRoutes } from "../types.d.ts";
+export interface SoloAppStatus {
+    role: AkanChildRole;
+    running: boolean;
+    status: string;
+    port: number | null;
+    metrics: AkanMetricsReport;
+}
+/**
+ * The gateway's `/_akan/app/*` surface, answered by a process nothing is proxying. The payload keeps the
+ * gateway's own shape — a `children` array with this process as its only entry — so a probe, a k8s check and
+ * `akan` tooling read one contract whether or not a gateway is in front.
+ */
+export declare const createSoloAppRoutes: (read: () => SoloAppStatus) => HttpRoutes;

package/types/server/types.d.ts

@@ -1,3 +1,4 @@
+import type { AkanWebConfig } from "akanjs";
 import type { PromiseOrObject } from "akanjs/base";
 import type { AkanI18nConfig } from "akanjs/common";
 import type { ClientManifest } from "./artifact.d.ts";
@@ -61,7 +62,19 @@ export type BaseBuildArtifact = {
     i18n: AkanI18nConfig;
     imageConfig: AkanImageConfig;
     deepLinkAssociations?: MobileDeepLinkAssociation[];
+    /**
+     * Which surfaces this artifact was built for. Absent on an artifact written before the option existed,
+     * which is read as both on — the shape every such build actually has.
+     */
+    web?: AkanWebConfig;
 };
+export declare const resolveWebConfig: (web: Partial<AkanWebConfig> | undefined) => AkanWebConfig;
+/**
+ * `AKAN_SSR` / `AKAN_CSR`, both on unless the env says otherwise — the same shape `AKAN_MCP` uses, because a
+ * switch a deployment has to find before anything works is a switch most deployments never find. Read by the
+ * gateway and by every replica, so both agree on what the pod serves.
+ */
+export declare const getWebConfigFromEnv: () => AkanWebConfig;
 export interface MobileDeepLinkAssociation {
     targetName: string;
     appId: string;

package/types/server/webRouter.d.ts

@@ -1,3 +1,4 @@
+import type { AkanWebConfig } from "akanjs";
 import { type AkanI18nConfig } from "akanjs/common";
 import { type AkanRequestStore } from "akanjs/fetch";
 import type { AkanMetricsReport } from "akanjs/service";
@@ -5,7 +6,7 @@ import { type BuilderRpc, type RouteSeedIndex } from "./artifact.d.ts";
 import { type RouteCacheInvalidation, type RouteCacheRenderState } from "./cachePolicy.d.ts";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub.d.ts";
 import { type RscRedirectMethod, type RscRedirectStatus, type RscRenderResult, RscWorker } from "./rscWorkerHost.d.ts";
-import type { BaseBuildArtifact, HttpRoutes, RenderState } from "./types.d.ts";
+import { type BaseBuildArtifact, type HttpRoutes, type RenderState } from "./types.d.ts";
 export declare const DEFAULT_HTML_RESULT_CACHE_MAX_BODY_BYTES: number;
 export declare function createRscRedirectResponse(location: string, method: RscRedirectMethod, status?: RscRedirectStatus): Response;
 export declare function createRscStreamResponse(stream: BodyInit, status?: number): Response;
@@ -49,10 +50,12 @@ export interface SsrRoutesResult {
     builderRpc: BuilderRpc | null;
 }
 export interface SsrRoutesInputs {
+    web: AkanWebConfig;
     upgradeHmrWs: (req: Request, data: HmrWsData) => boolean;
 }
 interface WebRouterOptions {
     artifact: BaseBuildArtifact;
+    web: AkanWebConfig;
     cssBytesByUrl: Record<string, Uint8Array>;
     rsc: RscWorker;
     seedIndex: RouteSeedIndex;
@@ -61,7 +64,9 @@ interface WebRouterOptions {
 export declare class WebRouter {
     #private;
     renderState: RenderState;
-    constructor({ artifact, cssBytesByUrl, rsc, seedIndex, upgradeHmrWs }: WebRouterOptions);
+    /** What this router actually mounts, already intersected with what the artifact carries. */
+    readonly web: AkanWebConfig;
+    constructor({ artifact, web, cssBytesByUrl, rsc, seedIndex, upgradeHmrWs }: WebRouterOptions);
     initializeRoute(): Promise<{
         renderEnvRoutes: Bun.Serve.Routes<unknown, string> | Bun.Serve.RoutesWithUpgrade<unknown, string>;
         hmrHub: HmrWsHub | null;
@@ -71,6 +76,10 @@ export declare class WebRouter {
     getMetrics(): AkanMetricsReport;
     /** @internal Clears or scopes invalidation for local route result caches owned by the host and RSC worker. */
     invalidateRouteCaches(invalidation?: string | RouteCacheInvalidation): void;
-    static create({ upgradeHmrWs }: SsrRoutesInputs): Promise<WebRouter>;
+    /**
+     * `null` when the build produced no web artifact — an api-only build, or a workspace with no `page/` at all.
+     * The caller boots without a web surface instead of failing on the missing file.
+     */
+    static create({ web, upgradeHmrWs }: SsrRoutesInputs): Promise<WebRouter | null>;
 }
 export {};

package/types/signal/internalArg.d.ts

@@ -32,17 +32,16 @@ export declare class Ip implements InternalArg<string | null> {
  * Injects websocket state, this connection's id, and subscription hooks into message/pubsub handlers.
  * `socketId` is the one `AppWsData` minted at the handshake, so a handler never reads `ws.data` to
  * tell two callers apart — and never mints an id of its own, which would not match the room bookkeeping.
+ * `on`/`off` register cleanup that runs when the room is unsubscribed or the socket closes.
  */
 export declare class Ws implements InternalArg {
-    onDisconnect?: () => void;
-    onUnsubscribe?: () => void;
     getArg(context: SignalContext): {
         ws: Bun.ServerWebSocket<{
             socketId: string;
         }>;
         socketId: string;
         subscribe: boolean;
-        on: (event: "disconnect" | "unsubscribe", handler: () => void) => void;
-        off: (event: "disconnect" | "unsubscribe", handler: () => void) => void;
+        on: (event: "disconnect" | "unsubscribe", handler: () => PromiseOrObject<void>) => void;
+        off: (event: "disconnect" | "unsubscribe", handler: () => PromiseOrObject<void>) => void;
     };
 }

package/types/signal/signalContext.d.ts

@@ -5,6 +5,11 @@ import type { Internal, InternalInfo, MiddlewareCls } from ".";
 import type { EndpointInfo } from "./endpointInfo.d.ts";
 import { SignalTrace } from "./trace.d.ts";
 export type SignalTransportType = "http" | "websocket";
+/** What `Bun.Server.requestIP` reports for the socket a request arrived on. */
+export type HttpPeerResolver = (req: Request) => {
+    address: string;
+    port: number;
+} | null;
 interface WebSocketRequest {
     ws: Bun.ServerWebSocket<unknown>;
     data: unknown[];
@@ -53,6 +58,13 @@ export declare class SignalContext<Ctx extends HttpExecutionContext | WebSocketE
      * closed with no arguments, so evaluating one here would delete every legitimate entry from the listing.
      */
     canListForAccount(): Promise<boolean>;
+    /**
+     * Lets the http branch of `getClientIp` reach the socket the way the websocket branch already reaches
+     * `ws.remoteAddress`. Registered by whichever `Bun.serve` is listening, because only the server can answer
+     * `requestIP`. Behind the federation gateway this never fires — the gateway always writes `x-real-ip` —
+     * so it is the answer for a process nothing is proxying.
+     */
+    static setHttpPeerResolver(resolve: HttpPeerResolver | null): void;
     exec(): Promise<Response | undefined>;
     static try(endpoint: Adaptor, endpointInfo: EndpointInfo, key: string, fn: () => Promise<Response | undefined>): Promise<Response | undefined>;
     static resolveReturn(value: unknown, { signalContext, returnRef, arrDepth, registry, live, }: {
@@ -114,8 +126,8 @@ export declare class WebSocketExecutionContext<Appended = unknown> {
     constructor(wsReq: WebSocketRequest);
     getArgs(endpointInfo: EndpointInfo): Promise<unknown[]>;
     makeResponse(result: unknown, endpointInfo: EndpointInfo): Response;
-    on(event: "disconnect" | "unsubscribe", handler: () => void): void;
-    off(event: "disconnect" | "unsubscribe", handler: () => void): void;
+    on: (event: "disconnect" | "unsubscribe", handler: () => PromiseOrObject<void>) => void;
+    off: (event: "disconnect" | "unsubscribe", handler: () => PromiseOrObject<void>) => void;
 }
 export declare class ResolveFieldContext {
     signalContext: SignalContext | null;