akanjs 3.0.0-alpha.64 → 3.0.0-alpha.65

package/index.ts

@@ -24,6 +24,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 +180,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
@@ -197,7 +217,10 @@ export interface LibConfigContext {
   readonly type: "lib";
 }
 
-export type AppConfigInput = DeepPartial<AppConfigResult> & { plugins?: AkanPlugin[] };
+export type AppConfigInput = Omit<DeepPartial<AppConfigResult>, "web"> & {
+  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.65",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/akanApp.ts

@@ -11,6 +11,7 @@ import { resolveEncodedSidecar } from "./assetEncoding";
 import { isPortInUseError } from "./lifecycle/portInUse";
 import { RotatingLogWriter } from "./logging/rotatingLogWriter";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
+import { getWebConfigFromEnv } from "./types";
 
 interface ChildState {
   idx: number;
@@ -103,6 +104,8 @@ 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 #children = new Map<number, ChildState>();
   readonly #roomChildren = new Map<string, Set<number>>();
@@ -555,6 +558,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";
@@ -28,7 +29,13 @@ 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 {
+  getWebConfigFromEnv,
+  type HttpRoutes,
+  type LocalPublish,
+  type SignalRoutes,
+  type WebsocketRoutes,
+} from "./types";
 import type { WebRouter } from "./webRouter";
 
 export interface AkanServerProps extends AkanLibProps {
@@ -135,6 +142,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();
 
@@ -184,6 +193,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 +271,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 +280,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 +295,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 = {
@@ -412,7 +442,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 });
@@ -638,6 +668,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/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/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

@@ -593,14 +593,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

@@ -25,6 +25,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 +178,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
@@ -190,7 +210,8 @@ export interface LibConfigContext {
     readonly name: string;
     readonly type: "lib";
 }
-export type AppConfigInput = DeepPartial<AppConfigResult> & {
+export type AppConfigInput = Omit<DeepPartial<AppConfigResult>, "web"> & {
+    web?: AkanWebOption;
     plugins?: AkanPlugin[];
 };
 export type LibConfigInput = DeepPartial<LibConfigResult> & {

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/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

@@ -114,8 +114,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;