akanjs 3.0.0-alpha.63 → 3.0.0-alpha.65

package/base/primitiveRegistry.ts

@@ -44,7 +44,7 @@ export class PrimitiveRegistry {
   }
 }
 
-export type PrimitiveValue = string | number | boolean | Dayjs | Date | null | undefined;
+export type PrimitiveValue = string | number | boolean | Dayjs | Date | Uint8Array | null | undefined;
 export class PrimitiveScalar {
   static refName: string;
   static [SERVER_VALUE]: unknown;
@@ -176,6 +176,49 @@ export class Any extends PrimitiveScalar {
 }
 PrimitiveRegistry.register(Any);
 
+type NodeBuffer = Uint8Array & { toString(encoding: string): string };
+interface BufferCtor {
+  from(buffer: ArrayBufferLike, byteOffset: number, length: number): NodeBuffer;
+  from(text: string, encoding: string): NodeBuffer;
+}
+
+export class Binary extends PrimitiveScalar {
+  static override refName: "Binary" = "Binary";
+  static override [SERVER_VALUE]: Uint8Array;
+  static override [CLIENT_VALUE]: Uint8Array;
+  static override [DEFAULT_VALUE]: Uint8Array | null = null;
+  static override [PURIFIED_VALUE]: Uint8Array | null = null;
+  static override [EXAMPLE_VALUE]: string = "AAEC";
+
+  static override validate(value: Uint8Array | string): boolean {
+    return value instanceof Uint8Array || typeof value === "string";
+  }
+  static override parseValue(input: Uint8Array | string): Uint8Array {
+    return typeof input === "string" ? Binary.#fromBase64(input) : input;
+  }
+  static override serializeValue(value: Uint8Array | string): string {
+    return typeof value === "string" ? value : Binary.#toBase64(value);
+  }
+
+  static #toBase64(bytes: Uint8Array): string {
+    const buffer = (globalThis as { Buffer?: BufferCtor }).Buffer;
+    if (buffer) return buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64");
+    let binary = "";
+    for (let idx = 0; idx < bytes.length; idx += 0x8000)
+      binary += String.fromCharCode(...bytes.subarray(idx, idx + 0x8000));
+    return btoa(binary);
+  }
+  static #fromBase64(text: string): Uint8Array {
+    const buffer = (globalThis as { Buffer?: BufferCtor }).Buffer;
+    if (buffer) return buffer.from(text, "base64");
+    const binary = atob(text);
+    const bytes = new Uint8Array(binary.length);
+    for (let idx = 0; idx < binary.length; idx += 1) bytes[idx] = binary.charCodeAt(idx);
+    return bytes;
+  }
+}
+PrimitiveRegistry.register(Binary);
+
 export class Upload extends PrimitiveScalar {
   static override refName: "Upload" = "Upload";
   static override [SERVER_VALUE]: File;
@@ -354,4 +397,4 @@ Object.assign(Date, {
 });
 PrimitiveRegistry.register(Date);
 
-export type DefaultPrimitiveName = "String" | "Boolean" | "Date" | "Int" | "Float" | "ID" | "Any" | "Upload";
+export type DefaultPrimitiveName = "String" | "Boolean" | "Date" | "Int" | "Float" | "ID" | "Any" | "Binary" | "Upload";

package/common/clientAddress.ts

@@ -0,0 +1,40 @@
+/** Headers a proxy hop writes so the next hop can still name the original caller. */
+export const forwardedHeaders = [
+  "x-real-ip",
+  "x-forwarded-for",
+  "x-forwarded-port",
+  "x-forwarded-host",
+  "x-forwarded-proto",
+] as const;
+
+/**
+ * An IPv4 client reaching a dual-stack listener is reported as `::ffff:203.0.113.10`. That form is not a
+ * valid destination for a `udp4` socket and does not compare equal to the same address written plainly, so
+ * it is unwrapped at every boundary rather than at each call site that happens to remember.
+ */
+export const normalizeIpAddress = (address: string): string => {
+  const trimmed = address.trim();
+  const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(trimmed);
+  return mapped?.[1] ?? trimmed;
+};
+
+/**
+ * The caller's address as the nearest proxy recorded it. `x-real-ip` is one hop's word for who the client is
+ * and wins; `x-forwarded-for` is a chain appended left to right, so its *first* entry is the original client
+ * and everything after it is a proxy.
+ *
+ * Returns `null` rather than a placeholder. A socket peer behind a proxy is the proxy, so `127.0.0.1` here
+ * would be indistinguishable from a genuinely local caller — and that is the failure this exists to prevent.
+ */
+export const clientAddressFromHeaders = (headers: Headers): string | null => {
+  const realIp = headers.get("x-real-ip")?.trim();
+  if (realIp) return normalizeIpAddress(realIp);
+  const forwarded = headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+  return forwarded ? normalizeIpAddress(forwarded) : null;
+};
+
+/** The client port the nearest proxy recorded, for correlating a connection with a peer's own logs. */
+export const clientPortFromHeaders = (headers: Headers): number | null => {
+  const port = Number(headers.get("x-forwarded-port"));
+  return Number.isInteger(port) && port > 0 && port <= 65535 ? port : null;
+};

package/common/index.ts

@@ -1,5 +1,11 @@
 export { applyMixins } from "./applyMixins";
 export { capitalize } from "./capitalize";
+export {
+  clientAddressFromHeaders,
+  clientPortFromHeaders,
+  forwardedHeaders,
+  normalizeIpAddress,
+} from "./clientAddress";
 export { deepObjectify } from "./deepObjectify";
 export {
   type FileUploadCapability,
@@ -76,3 +82,4 @@ export {
   type WebsocketAuthRequest,
   websocketAuthContract,
 } from "./websocketAuth";
+export { type WebsocketBinaryFrame, websocketBinaryFrameContract } from "./websocketBinaryFrame";

package/common/mcpExposure.ts

@@ -67,6 +67,8 @@ export const mcpRefusalOf = (endpoint: McpExposureEndpoint, { readOnly }: McpExp
     return "this deployment is read-only, which drops every endpoint that is not a query.";
   if (endpoint.returns.refName === "Any" || endpoint.returns.refName === "Upload")
     return `a return typed \`${endpoint.returns.refName}\` cannot be described to a model.`;
+  if (endpoint.returns.refName === "Binary")
+    return "a return typed `Binary` is raw bytes, which cost a model its window and tell it nothing.";
   if (endpoint.fileUpload || endpoint.args.some((arg) => arg.refName === "Upload"))
     return "a file upload has no MCP representation.";
   if (endpoint.type === "mutation" && !endpoint.guards.some((name) => name !== "Public"))

package/common/websocketBinaryFrame.ts

@@ -0,0 +1,46 @@
+export interface WebsocketBinaryFrame {
+  roomId: string;
+  payload: Uint8Array;
+}
+
+const MAGIC = 0xab;
+const KIND_PUB = 0x01;
+const HEADER_BYTES = 4;
+const MAX_ROOM_BYTES = 0xffff;
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/**
+ * Framework-owned binary pubsub frame, shared by the publisher and the client dispatcher. A room whose whole
+ * return is `Binary` sends its bytes in a websocket binary frame instead of the JSON `{ type: "pub" }` envelope,
+ * because `Buffer.toJSON()` turns bytes into `{ type: "Buffer", data: number[] }` — 3.6x the wire and ~300x the
+ * encode cost on a 64 KB payload, and a shape `JSON.parse` never restores.
+ *
+ * Text and binary frames coexist on one socket, so this is additive: every JSON endpoint is untouched, and a
+ * federation gateway relays a binary frame unchanged with no code of its own.
+ */
+export const websocketBinaryFrameContract = {
+  encode: ({ roomId, payload }: WebsocketBinaryFrame): Uint8Array => {
+    const room = encoder.encode(roomId);
+    if (room.length > MAX_ROOM_BYTES) throw new Error(`Room id is too long to frame: ${roomId}`);
+    const frame = new Uint8Array(HEADER_BYTES + room.length + payload.length);
+    frame[0] = MAGIC;
+    frame[1] = KIND_PUB;
+    frame[2] = room.length >> 8;
+    frame[3] = room.length & 0xff;
+    frame.set(room, HEADER_BYTES);
+    frame.set(payload, HEADER_BYTES + room.length);
+    return frame;
+  },
+  decode: (data: ArrayBuffer | Uint8Array): WebsocketBinaryFrame | null => {
+    const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+    if (bytes.length < HEADER_BYTES || bytes[0] !== MAGIC || bytes[1] !== KIND_PUB) return null;
+    const roomBytes = (bytes[2] << 8) | bytes[3];
+    if (bytes.length < HEADER_BYTES + roomBytes) return null;
+    return {
+      roomId: decoder.decode(bytes.subarray(HEADER_BYTES, HEADER_BYTES + roomBytes)),
+      payload: bytes.subarray(HEADER_BYTES + roomBytes),
+    };
+  },
+} as const;

package/constant/via.ts

@@ -1,4 +1,5 @@
 import {
+  Binary,
   CLIENT_VALUE,
   type Cls,
   DEFAULT_VALUE,
@@ -439,7 +440,9 @@ const applyConstantStatics = <Model>(model: ConstantCls<Model>, fieldMap: FieldO
       return { ...defaultValue };
     },
   });
-  Object.entries(fieldMap).forEach(([, field]) => {
+  Object.entries(fieldMap).forEach(([key, field]) => {
+    if ((field.modelRef as unknown) === Binary || (field.of as unknown) === Binary)
+      throw new Error(`Field "${key}" is Binary, which is not storable. Reference the File model instead.`);
     if (field.enum) model.enums.add(field.enum);
     if (!field.isClass) return;
     if (field.isScalar) model.children.add(field.modelRef);

package/fetch/client/wsClient.ts

@@ -1,4 +1,4 @@
-import { Logger, websocketAuthContract } from "akanjs/common";
+import { Logger, websocketAuthContract, websocketBinaryFrameContract } from "akanjs/common";
 import type {
   WebsocketAuthAck,
   WebsocketMessageData,
@@ -85,6 +85,7 @@ export class WsClient {
     if (this.#destroyed) return;
 
     this.#ws = new WebSocket(this.url);
+    this.#ws.binaryType = "arraybuffer";
     this.#ws.onopen = (e) => {
       this.#reconnectAttempts = 0;
       this.connected = true;
@@ -101,7 +102,13 @@ export class WsClient {
     };
     this.#ws.onmessage = (e) => {
       try {
-        const parsed = typeof e.data === "string" ? JSON.parse(e.data) : e.data;
+        if (typeof e.data !== "string") {
+          const frame = websocketBinaryFrameContract.decode(e.data as ArrayBuffer);
+          if (frame) this.#handlePubsub(frame.roomId, frame.payload);
+          else this.logger.warn("Unknown binary WebSocket frame");
+          return;
+        }
+        const parsed = JSON.parse(e.data) as { error?: unknown } & WebsocketResData;
         if (parsed?.error) {
           throw this.#restoreError(parsed);
         }

package/fetch/fetchType/appliedReturn.type.ts

@@ -16,6 +16,13 @@ export interface QuerySetting {
    * now — `() => [dayjs().subtract(1, "hour")]` — current at the moment the user asks for it.
    */
   args?: unknown[] | (() => unknown[]);
+  /**
+   * The same list under the name the rest of the framework already uses for it — the `queryArgsOf<Model>` state
+   * key, `refresh<Model>({ queryArgs })`, and a field's own `.meta(...)` declaration. Accepted so a query a
+   * field declares is one of these as it stands, rather than something every caller has to rename by hand.
+   * `args` wins when both are given.
+   */
+  queryArgs?: unknown[] | (() => unknown[]);
 }
 
 export type ServerInit<

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.63",
+  "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>>();
@@ -547,7 +550,7 @@ export class AkanApp {
     if (this.#isWebSocketPath(url.pathname)) return this.#upgradeWebSocket(req, server);
     const assetResponse = await this.#serveImmutableArtifact(req, url);
     if (assetResponse) return assetResponse;
-    return await this.#proxyHttp(req);
+    return await this.#proxyHttp(req, server);
   }
 
   #isWebSocketPath(pathname: string) {
@@ -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(
@@ -592,7 +596,7 @@ export class AkanApp {
     if (!child || !upstream) return new Response("No websocket upstream is ready", { status: 503 });
     const url = new URL(req.url);
     const upstreamWs = new WebSocket(`ws://${upstream.host}:${upstream.port}${url.pathname}${url.search}`, {
-      headers: this.#makeProxyHeaders(req, child.idx),
+      headers: this.#makeProxyHeaders(req, child.idx, server),
     } as unknown as string[]);
 
     const upgraded = server.upgrade(req, { data: { childIdx: child.idx, upstream: upstreamWs } });
@@ -691,14 +695,14 @@ export class AkanApp {
     };
   }
 
-  async #proxyHttp(req: Request): Promise<Response> {
+  async #proxyHttp(req: Request, server: Bun.Server<GatewayWsData>): Promise<Response> {
     const child = this.#pickFederationChild();
     if (!child?.upstream || child.upstream.type !== "unix") {
       return this.#respondWithCrashPage(req) ?? new Response("No healthy federation child is ready", { status: 503 });
     }
     const url = new URL(req.url);
     const upstreamUrl = `http://akan-child${url.pathname}${url.search}`;
-    const headers = this.#makeProxyHeaders(req, child.idx);
+    const headers = this.#makeProxyHeaders(req, child.idx, server);
     child.metrics.activeRequests = (child.metrics.activeRequests ?? 0) + 1;
     child.metrics.totalRequests = (child.metrics.totalRequests ?? 0) + 1;
     const traced = isTraceEnabled();
@@ -867,8 +871,8 @@ export class AkanApp {
     return resolved;
   }
 
-  #makeProxyHeaders(req: Request, childIdx: number) {
-    return makeAkanChildProxyHeaders(req, childIdx);
+  #makeProxyHeaders(req: Request, childIdx: number, server?: Bun.Server<GatewayWsData>) {
+    return makeAkanChildProxyHeaders(req, childIdx, server?.requestIP(req));
   }
 
   #invalidateFederationChildCache() {

package/server/akanAppHeaders.ts

@@ -1,3 +1,5 @@
+import { normalizeIpAddress } from "akanjs/common";
+
 const HOP_BY_HOP_HEADERS = new Set([
   "connection",
   "keep-alive",
@@ -9,13 +11,23 @@ const HOP_BY_HOP_HEADERS = new Set([
   "upgrade",
 ]);
 
-export function makeAkanChildProxyHeaders(req: Request, childIdx: number): Headers {
+/** What `Server.requestIP` reports for the socket this hop accepted. */
+export interface ProxyClientPeer {
+  address: string;
+  port: number;
+  family: string;
+}
+
+export function makeAkanChildProxyHeaders(req: Request, childIdx: number, peer?: ProxyClientPeer | null): Headers {
   const headers = new Headers(req.headers);
   for (const key of HOP_BY_HOP_HEADERS) headers.delete(key);
   const forwardedFor = headers.get("x-forwarded-for");
-  const clientAddress = headers.get("x-real-ip") ?? "127.0.0.1";
+
+  const clientAddress = headers.get("x-real-ip") ?? (peer ? normalizeIpAddress(peer.address) : "127.0.0.1");
   const host = headers.get("host");
+  headers.set("x-real-ip", clientAddress);
   headers.set("x-forwarded-for", forwardedFor ? `${forwardedFor}, ${clientAddress}` : clientAddress);
+  if (peer && !headers.has("x-forwarded-port")) headers.set("x-forwarded-port", String(peer.port));
   headers.set("x-forwarded-host", headers.get("x-forwarded-host") ?? host ?? new URL(req.url).host);
   headers.set(
     "x-forwarded-proto",

package/server/akanServer.ts

@@ -1,5 +1,6 @@
+import type { AkanWebConfig, AkanWebOption } from "akanjs";
 import { type BackendEnv, type BaseEnv, getEnv } from "akanjs/base";
-import { Logger } from "akanjs/common";
+import { Logger, websocketBinaryFrameContract } from "akanjs/common";
 import { DictionaryLookup } from "akanjs/dictionary";
 import type {
   Adaptor,
@@ -16,6 +17,7 @@ import { createOpenApiDocument } from "../signal/openapi";
 import { FetchSerializer } from "../signal/serializer";
 import type { AkanLib, AkanLibProps } from "./akanLib";
 import type { BuilderRpc } from "./artifact";
+import { BinaryPubsub } from "./binaryPubsub";
 import { DevtoolsRouter } from "./devtools";
 import { DiLifecycle } from "./di/diLifecycle";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub";
@@ -27,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, 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 {
@@ -134,11 +142,14 @@ 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();
 
   #di: DiLifecycle;
-  #localPublish: ((roomId: string, data: object | object[]) => void) | null = null;
+  #localPublish: LocalPublish | null = null;
+  readonly #binaryPubsub = new BinaryPubsub();
   #metricsTimer: Timer | null = null;
   constructor(
     name = "AkanServer",
@@ -182,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);
@@ -254,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();
@@ -263,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,
@@ -277,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 = {
@@ -318,6 +350,7 @@ export class AkanServer {
         hmrHub,
         hmrState: webRouter ? { state: webRouter.renderState } : null,
         logger: this.logger,
+        onDrain: () => this.#binaryPubsub.flush(),
       }),
       
       data: {},
@@ -375,16 +408,20 @@ export class AkanServer {
 
     const websocket = this.#di.getWebsocketAdaptor();
     if (!websocket) throw new Error("WebSocket Redis adaptor is not registered");
-    SignalResolver.setLocalPublish((roomId, data) => {
-      const publishData: WebsocketPublishData = { type: "pub", roomId, data };
-      server?.publish(roomId, JSON.stringify(publishData));
-      wsServer?.publish(roomId, JSON.stringify(publishData));
-    }, websocket);
-    this.#localPublish = (roomId, data) => {
+    this.#binaryPubsub.setServers(server, wsServer);
+    const localPublish: LocalPublish = (roomId, data) => {
+      if (data instanceof Uint8Array) {
+        this.#binaryPubsub.publish(roomId, websocketBinaryFrameContract.encode({ roomId, payload: data }), {
+          coalesce: SignalResolver.coalescesRoom(roomId),
+        });
+        return;
+      }
       const publishData: WebsocketPublishData = { type: "pub", roomId, data };
       server?.publish(roomId, JSON.stringify(publishData));
       wsServer?.publish(roomId, JSON.stringify(publishData));
     };
+    SignalResolver.setLocalPublish(localPublish, websocket);
+    this.#localPublish = localPublish;
 
     this.status = "running";
     this.#startMetricsReporting();
@@ -405,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 });
@@ -479,7 +516,8 @@ export class AkanServer {
 
   #handleIpcMessage(message: AkanIpcMessage) {
     if (!message || typeof message !== "object") return;
-    if (message.type === "pubsub.deliver") this.#localPublish?.(message.roomId, message.data as object | object[]);
+    if (message.type === "pubsub.deliver")
+      this.#localPublish?.(message.roomId, message.data as object | object[] | Uint8Array);
     else if (message.type === "health.ping")
       process.send?.({
         type: "health.pong",
@@ -506,6 +544,7 @@ export class AkanServer {
   async #reportMetrics() {
     const metrics = await ProcessMetricsCollector.collect({
       role: this.serverMode,
+      pubsubCoalesceCount: this.#binaryPubsub.coalescedCount,
       ...(this.#prepared?.webRouter?.getMetrics() ?? {}),
     });
     process.send?.({ type: "metrics.report", pid: process.pid, metrics } satisfies AkanIpcMessage);
@@ -629,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/binaryPubsub.ts

@@ -0,0 +1,55 @@
+import { Logger } from "akanjs/common";
+
+/**
+ * Sends binary pubsub frames and absorbs a slow subscriber. `Server.publish` reports `-1` when the socket is
+ * backpressured, `0` when the room has no subscriber, and the byte count otherwise — so a room that cannot
+ * keep up parks its newest frame here and every earlier one is dropped, rather than queueing behind the
+ * slowest subscriber until the send buffer is the stream. Bun fires `drain` per socket when its buffer
+ * empties; that is what flushes the parked frames.
+ */
+export class BinaryPubsub {
+  readonly #logger = new Logger("BinaryPubsub");
+  readonly #pending = new Map<string, Uint8Array>();
+  #servers: Bun.Server<unknown>[] = [];
+  #coalescedCount = 0;
+
+  get coalescedCount() {
+    return this.#coalescedCount;
+  }
+
+  setServers(...servers: (Bun.Server<never> | null)[]) {
+    this.#servers = servers.filter((server): server is Bun.Server<never> => !!server) as Bun.Server<unknown>[];
+  }
+
+  publish(roomId: string, frame: Uint8Array, { coalesce = false }: { coalesce?: boolean } = {}) {
+    if (!this.#send(roomId, frame) || !coalesce) return;
+    if (this.#pending.has(roomId)) this.#coalescedCount += 1;
+    this.#pending.set(roomId, frame);
+  }
+
+  /** Retries every parked room. A room still backpressured re-parks itself and waits for the next drain. */
+  flush() {
+    if (!this.#pending.size) return;
+    for (const [roomId, frame] of [...this.#pending]) {
+      this.#pending.delete(roomId);
+      if (this.#send(roomId, frame)) this.#pending.set(roomId, frame);
+    }
+  }
+
+  clear() {
+    this.#pending.clear();
+  }
+
+  /** True when at least one server refused the frame for backpressure, which is the only case worth parking. */
+  #send(roomId: string, frame: Uint8Array): boolean {
+    let backpressured = false;
+    for (const server of this.#servers) {
+      try {
+        if (server.publish(roomId, frame) === -1) backpressured = true;
+      } catch (error) {
+        this.#logger.warn(`Binary publish failed for ${roomId}: ${error instanceof Error ? error.message : error}`);
+      }
+    }
+    return backpressured;
+  }
+}