akanjs 3.0.0-alpha.2 → 3.0.0-alpha.21

package/server/akanApp.ts

@@ -7,6 +7,7 @@ import type { AkanChildRole, AkanChildStatus, AkanIpcMessage, AkanMetricsReport,
 import { isTraceEnabled } from "akanjs/signal";
 import { makeAkanChildProxyHeaders } from "./akanAppHeaders";
 import type { BuilderCsrReq, BuilderCsrRes, BuilderMessage, BuilderReq, BuilderRes } from "./artifact";
+import { resolveEncodedSidecar } from "./assetEncoding";
 import { isPortInUseError } from "./lifecycle/portInUse";
 import { RotatingLogWriter } from "./logging/rotatingLogWriter";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
@@ -75,6 +76,8 @@ export class AkanApp {
   /** Hosted by `akan start`: crash loops should yield to the dev host, which restarts on file edits. */
   readonly #devHosted = process.env.AKAN_COMMAND_TYPE === "start";
   readonly #healthTimeoutMs = AkanApp.#parseHealthTimeoutMs();
+  /** Child stderr is bundler/runtime noise the gateway cannot act on; it still reaches the rotating log file. */
+  readonly #printChildStderr = process.env.AKAN_CHILD_STDERR === "1";
   readonly #serverPath: string;
   readonly #artifactDir: string;
   readonly #replica: AkanReplicaConfig;
@@ -156,10 +159,16 @@ export class AkanApp {
     return Math.max(min, parsed);
   }
 
+  /**
+   * The command that started this gateway outranks an inherited `NODE_ENV`: the command is a statement about
+   * this run, while the env var can arrive from a shell export, a CI image, or the workspace `.env` Bun loads
+   * on its own. Handing a dev child `NODE_ENV=production` makes it serve from the production route cache and
+   * throw on every route, since only `akan build` writes the routes manifest that cache expects.
+   */
   static #defaultChildNodeEnv() {
-    if (process.env.NODE_ENV) return process.env.NODE_ENV;
     if (process.env.AKAN_COMMAND_TYPE === "start") return "development";
     if (process.env.AKAN_COMMAND_TYPE === "build") return "production";
+    if (process.env.NODE_ENV) return process.env.NODE_ENV;
     return Bun.main.endsWith(".js") ? "production" : "development";
   }
 
@@ -585,7 +594,11 @@ export class AkanApp {
       const result = ws.send(event.data as string | ArrayBuffer);
       if (result === 0) upstream.close();
     });
-    upstream.addEventListener("close", (event) => ws.close(event.code, event.reason));
+    upstream.addEventListener("close", (event) => {
+      const code = AkanApp.#sendableCloseCode(event.code);
+      if (code === undefined) ws.close();
+      else ws.close(code, event.reason);
+    });
     upstream.addEventListener("error", () => ws.close(1011, "upstream websocket error"));
     Object.assign(ws.data, { pending });
   }
@@ -605,8 +618,15 @@ export class AkanApp {
     else ws.data.pending?.push(payload as string | ArrayBuffer);
   }
 
+  static #sendableCloseCode(code: number): number | undefined {
+    const sendable = (code >= 1000 && code <= 1014 && (code < 1004 || code > 1006)) || (code >= 3000 && code <= 4999);
+    return sendable ? code : undefined;
+  }
+
   #handleWsClose(ws: Bun.ServerWebSocket<GatewayWsData>, code: number, reason: string) {
-    ws.data.upstream.close(code, reason);
+    const upstreamCode = AkanApp.#sendableCloseCode(code);
+    if (upstreamCode === undefined) ws.data.upstream.close();
+    else ws.data.upstream.close(upstreamCode, reason);
     const child = this.#children.get(ws.data.childIdx);
     if (child) child.metrics.activeWebSockets = Math.max(0, (child.metrics.activeWebSockets ?? 1) - 1);
   }
@@ -808,41 +828,17 @@ export class AkanApp {
     const headers = new Headers({ "Content-Type": options.contentType });
     if (options.cacheControl) headers.set("Cache-Control", options.cacheControl);
 
-    const gzipPath = `${filePath}.gz`;
-    if (this.#acceptsGzip(req) && this.#isCompressible(options.contentType)) {
-      const gzipFile = Bun.file(gzipPath);
-      if (await gzipFile.exists()) {
-        const gzipBytes = await gzipFile.bytes();
-        headers.set("Content-Encoding", "gzip");
-        headers.set("Content-Length", String(gzipBytes.byteLength));
-        headers.set("Vary", "Accept-Encoding");
-        return new Response(this.#toArrayBuffer(gzipBytes), { headers });
-      }
+    const sidecar = await resolveEncodedSidecar(req, filePath, options.contentType);
+    if (sidecar) {
+      headers.set("Content-Encoding", sidecar.encoding);
+      headers.set("Content-Length", String(sidecar.bytes.byteLength));
+      headers.set("Vary", "Accept-Encoding");
+      return new Response(sidecar.bytes, { headers });
     }
 
     return new Response(Bun.file(filePath).stream(), { headers });
   }
 
-  #acceptsGzip(req: Request): boolean {
-    const acceptEncoding = req.headers.get("accept-encoding") ?? "";
-    return /\bgzip\b/.test(acceptEncoding);
-  }
-
-  #isCompressible(contentType: string): boolean {
-    const type = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
-    return (
-      type.startsWith("text/") ||
-      type === "application/javascript" ||
-      type === "application/json" ||
-      type === "application/manifest+json" ||
-      type === "image/svg+xml"
-    );
-  }
-
-  #toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
-    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
-  }
-
   #safeResolve(baseDir: string, urlPath: string): string | null {
     let decoded: string;
     try {
@@ -1240,7 +1236,7 @@ export class AkanApp {
 
   #writeChildOutputLineRaw(idx: number, role: AkanChildRole, type: "stdout" | "stderr", line: string) {
     const prefixedLine = `[child:${idx} ${role}] [${type}] ${line}`;
-    process[type].write(prefixedLine);
+    if (type === "stdout" || this.#printChildStderr) process[type].write(prefixedLine);
     this.#logWriter?.write(`${idx}-${role}`, AkanApp.#stripAnsi(prefixedLine));
   }
 

package/server/akanOption.ts

@@ -1,17 +1,35 @@
-import type { BaseEnv, PromiseOrObject } from "akanjs/base";
-import type { MiddlewareCls } from "akanjs/signal";
+import type { BackendEnv, PromiseOrObject } from "akanjs/base";
+import type { Adaptor, AdaptorCls, LlmOption } from "akanjs/service";
+import type { AgentRelayPolicy, MiddlewareCls } from "akanjs/signal";
+import type { McpServerOption } from "./akanServer";
 import type { WebProxyRegistration } from "./proxy";
 import { HostBasePathWebProxy, LocaleWebProxy } from "./proxy";
 
-/** App/library server option builder for use objects, signal middleware, and web proxies. */
-export class AkanOption<Env extends BaseEnv = BaseEnv> {
+export interface AdaptorOverride {
+  role: AdaptorCls;
+  adaptor: AdaptorCls;
+}
+
+/**
+ * App/library server option builder: use objects, signal middleware, adaptor overrides, web proxies, and the
+ * server settings an app owns — MCP, the agent relay's access policy, and the LLM the relay speaks to.
+ */
+export class AkanOption<Env = unknown> {
   readonly #getUses: ((env: Env) => Record<string, PromiseOrObject<unknown>>)[];
   readonly #middlewares: MiddlewareCls[] = [];
+  readonly #adaptorOverrides: AdaptorOverride[] = [];
   readonly #webProxies: WebProxyRegistration[] = [];
+  readonly #getLlms: ((env: Env) => LlmOption)[] = [];
+  #mcp: boolean | McpServerOption | undefined;
+  #agentAccess: AgentRelayPolicy | null | undefined;
   constructor() {
     this.#getUses = [];
   }
-  use(fnOrObject: ((env: Env) => Record<string, PromiseOrObject<unknown>>) | Record<string, PromiseOrObject<unknown>>) {
+  use(
+    fnOrObject:
+      | ((env: Env & BackendEnv) => Record<string, PromiseOrObject<unknown>>)
+      | Record<string, PromiseOrObject<unknown>>,
+  ) {
     if (typeof fnOrObject === "function")
       this.#getUses.push(fnOrObject as (env: Env) => Record<string, PromiseOrObject<unknown>>);
     else this.#getUses.push(() => fnOrObject);
@@ -21,22 +39,62 @@ export class AkanOption<Env extends BaseEnv = BaseEnv> {
     this.#middlewares.push(...middlewares);
     return this;
   }
+  /** Rebinds a predefined adaptor role (e.g. `LlmAdaptorRole`) to the app's own implementation. Last writer wins. */
+  applyAdaptor<T extends Adaptor>(role: AdaptorCls<T>, adaptor: AdaptorCls<T>) {
+    this.#adaptorOverrides.push({ role: role as AdaptorCls, adaptor: adaptor as AdaptorCls });
+    return this;
+  }
   applyWebProxy(...proxies: WebProxyRegistration[]) {
     this.#webProxies.push(...proxies);
     return this;
   }
-  getUses(env: Env): Record<string, PromiseOrObject<unknown>> {
+  /**
+   * MCP server settings for the app mounting this option, merged over the `AKAN_MCP_*` environment and under an
+   * option the server is constructed with. The app's own `option.ts` is the last lib the server reads, so it wins
+   * over every library it depends on.
+   */
+  setMcp(mcp: boolean | McpServerOption = true) {
+    this.#mcp = mcp;
+    return this;
+  }
+  /**
+   * Who may spend the LLM key through the `runAgentTurn` relay — the `AgentRelayAccess` policy, which defaults to
+   * allowing everyone because the framework has no account model to gate on. `null` reopens it.
+   */
+  setAgentAccess(policy: AgentRelayPolicy | null) {
+    this.#agentAccess = policy;
+    return this;
+  }
+  /** Settings for whichever adaptor fills `LlmAdaptorRole`, injected into it as the `llmOption` use. */
+  setLlm(llmOrFn: LlmOption | ((env: Env) => LlmOption)) {
+    if (typeof llmOrFn === "function") this.#getLlms.push(llmOrFn);
+    else this.#getLlms.push(() => llmOrFn);
+    return this;
+  }
+  getUses(env: Env & BackendEnv): Record<string, PromiseOrObject<unknown>> {
     const uses = this.#getUses.map((fn) => fn(env));
     return Object.assign({}, ...uses);
   }
   getMiddlewares(): MiddlewareCls[] {
     return this.#middlewares;
   }
+  getAdaptorOverrides(): AdaptorOverride[] {
+    return this.#adaptorOverrides;
+  }
   getWebProxies(): WebProxyRegistration[] {
     return this.#webProxies;
   }
+  getMcp(): boolean | McpServerOption | undefined {
+    return this.#mcp;
+  }
+  getAgentAccess(): AgentRelayPolicy | null | undefined {
+    return this.#agentAccess;
+  }
+  getLlm(env: Env & BackendEnv): LlmOption {
+    return Object.assign({}, ...this.#getLlms.map((fn) => fn(env)));
+  }
 }
 
 export function createDefaultAkanOption() {
-  return new AkanOption<BaseEnv>().applyWebProxy(LocaleWebProxy, HostBasePathWebProxy);
+  return new AkanOption().applyWebProxy(LocaleWebProxy, HostBasePathWebProxy);
 }

package/server/akanServer.ts

@@ -1,5 +1,6 @@
 import { type BaseEnv, getEnv } from "akanjs/base";
 import { Logger } from "akanjs/common";
+import { DictionaryLookup } from "akanjs/dictionary";
 import type {
   Adaptor,
   AdaptorCls,
@@ -10,6 +11,7 @@ import type {
   SolidConfig,
 } from "akanjs/service";
 import type { ServerSignal, ServerSignalCls, WebsocketPublishData } from "akanjs/signal";
+import { AgentRelayAccess } from "../signal/guards";
 import { createOpenApiDocument } from "../signal/openapi";
 import { FetchSerializer } from "../signal/serializer";
 import type { AkanLib, AkanLibProps } from "./akanLib";
@@ -19,6 +21,7 @@ import { DiLifecycle } from "./di/diLifecycle";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub";
 import { isPortInUseError } from "./lifecycle/portInUse";
 import { ShutdownManager } from "./lifecycle/shutdownManager";
+import { type McpAuthOption, McpRouter } from "./mcp";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
 import { WebProxyRunner } from "./proxy";
 import { SignalResolver } from "./resolver";
@@ -36,6 +39,44 @@ export interface AkanServerProps extends AkanLibProps {
 
 export interface AkanServerOptions {
   openapi?: boolean;
+  /** `/mcp` is mounted by default; `false` takes it off, and the object form carries the rest of its settings. */
+  mcp?: boolean | McpServerOption;
+}
+
+export interface McpServerOption {
+  enabled?: boolean;
+  /**
+   * Drops every mutation from the catalogue whatever its guards allow — for a deployment that must not be able to
+   * write, such as a read replica or a demo. Off by default, and reported per endpoint in the boot log, because a
+   * switch that silently unlists a published endpoint cannot tell its author why it vanished.
+   */
+  readOnly?: boolean;
+  /**
+   * Mount path, `/mcp` by default. The published OAuth resource identifier follows it, so changing it changes
+   * the `aud` a token has to carry.
+   */
+  path?: string;
+  /** Reported as `serverInfo.version`. Defaults to `0.0.0`, the same placeholder the OpenAPI document uses. */
+  version?: string;
+  /**
+   * Free-text usage guidance handed to the model alongside the tool list — the one place to say what this app
+   * is for and which tool to reach for first. Defaults to a bare one-liner naming the app.
+   */
+  instructions?: string;
+  /**
+   * Extra origins allowed past the DNS-rebinding check, beyond the server's own host. Needed only for a
+   * browser-hosted MCP client; native ones send no `Origin` at all.
+   */
+  allowedOrigins?: string[];
+  /** Entries per catalogue page. A client that wants the whole list follows `nextCursor` until it stops. */
+  pageSize?: number;
+  /**
+   * The one language the catalogue and its error text are written in, `en` by default. Server-wide on purpose:
+   * the document is built once at boot and cached by clients, and it is read by a model rather than by a person.
+   */
+  language?: string;
+  /** OAuth resource-server identity: which issuers a client may authenticate with, and the scopes to demand. */
+  auth?: McpAuthOption;
 }
 
 interface AkanAppPrepared {
@@ -76,6 +117,10 @@ export class AkanServer {
   prefix = "/api";
   websocketPrefix = "/ws";
   openapi = AkanServer.#isOpenApiEnvEnabled();
+  mcp = AkanServer.#isEnvOn("AKAN_MCP", "AKAN_PUBLIC_MCP");
+  mcpReadOnly = AkanServer.#isEnvEnabled("AKAN_MCP_READONLY", "AKAN_PUBLIC_MCP_READONLY");
+  mcpAuth: McpAuthOption = AkanServer.#mcpAuthFromEnv();
+  mcpOption: Omit<McpServerOption, "enabled" | "readOnly" | "auth"> = AkanServer.#mcpOptionFromEnv();
   serverMode: "federation" | "batch" | "all";
   shutdownTimeoutMs = AkanServer.#defaultShutdownTimeoutMs();
 
@@ -84,7 +129,7 @@ export class AkanServer {
   #metricsTimer: Timer | null = null;
   constructor(
     name = "AkanServer",
-    env: BaseEnv = getEnv(),
+    env = {},
     serverMode: "federation" | "batch" | "all" = (process.env.SERVER_MODE as
       | "federation"
       | "batch"
@@ -96,8 +141,16 @@ export class AkanServer {
     this.name = name;
     this.logger = new Logger(name);
     this.libs = libs;
-    this.env = { ...env };
+    this.env = Object.assign(getEnv(), env);
     this.openapi = options?.openapi ?? this.openapi;
+    
+    libs.forEach((lib) => {
+      const mcp = lib.option.getMcp();
+      if (mcp !== undefined) this.setMcp(mcp);
+      const agentAccess = lib.option.getAgentAccess();
+      if (agentAccess !== undefined) AgentRelayAccess.use(agentAccess);
+    });
+    this.setMcp(options?.mcp ?? this.mcp);
     this.serverMode = serverMode;
     this.#di = new DiLifecycle(this.env, serverMode, ...libs);
   }
@@ -114,6 +167,16 @@ export class AkanServer {
     this.openapi = openapi;
     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);
+    if (typeof mcp === "boolean") return this;
+    const { enabled: _enabled, readOnly, auth, ...rest } = mcp;
+    if (readOnly !== undefined) this.mcpReadOnly = readOnly;
+    if (auth) this.mcpAuth = { ...this.mcpAuth, ...AkanServer.#defined(auth) };
+    this.mcpOption = { ...this.mcpOption, ...AkanServer.#defined(rest) };
+    return this;
+  }
   setDatabaseConfig(database: DatabaseConfig) {
     if (this.status !== "stopped") throw new Error("Database config must be set before app initialization.");
     this.env.database = database;
@@ -460,12 +523,30 @@ export class AkanServer {
                   title: `${this.env.appName} API`,
                   version: "0.0.0",
                   servers: this.#getOpenApiServers(),
+                  resolveDescription: AkanServer.#createDescriptionResolver(),
                 }),
               ),
           },
         }
       : {};
 
+    const mcpRouter =
+      this.mcp && this.serverMode !== "batch"
+        ? new McpRouter({
+            registry: this.#di.registry,
+            env: this.env,
+            live: this.#di.live,
+            middleware: new Map(this.#di.modules.middleware),
+            instructions: `Domain tools for the ${this.env.appName} app.`,
+            ...this.mcpOption,
+            readOnly: this.mcpReadOnly,
+            auth: this.mcpAuth,
+          })
+        : null;
+    const mcpRoutes: HttpRoutes = mcpRouter?.createRoutes() ?? {};
+
+    mcpRouter?.report();
+
     const devtoolsRoutes = new DevtoolsRouter({
       di: this.#di,
       env: this.env,
@@ -476,7 +557,17 @@ export class AkanServer {
       openapi: this.openapi,
       getStatus: () => this.status,
     }).createRoutes();
-    return { ...openapiRoutes, ...devtoolsRoutes };
+    return { ...openapiRoutes, ...mcpRoutes, ...devtoolsRoutes };
+  }
+
+  /**
+   * Rebuilt per request rather than cached on the instance: libs register their dictionaries at module-evaluation
+   * time, and the document itself is already re-serialized per request, so a stale snapshot would be the only
+   * thing here that could disagree with the rest of the response.
+   */
+  static #createDescriptionResolver() {
+    const lookup = new DictionaryLookup();
+    return (key: string) => lookup.text(key);
   }
 
   #getOpenApiServers() {
@@ -494,14 +585,88 @@ export class AkanServer {
 
   static #isServerOptions(value: AkanLib | AkanServerOptions | undefined): value is AkanServerOptions {
     return Boolean(
-      value && !("database" in value) && !("service" in value) && !("scalar" in value) && "openapi" in value,
+      value &&
+        !("database" in value) &&
+        !("service" in value) &&
+        !("scalar" in value) &&
+        ("openapi" in value || "mcp" in value),
     );
   }
 
   static #isOpenApiEnvEnabled() {
-    return [process.env.AKAN_OPENAPI, process.env.AKAN_PUBLIC_OPENAPI].some(
-      (value) => value === "true" || value === "1",
-    );
+    return AkanServer.#isEnvEnabled("AKAN_OPENAPI", "AKAN_PUBLIC_OPENAPI");
+  }
+
+  static #isEnvEnabled(...names: string[]) {
+    return names.some((name) => process.env[name] === "true" || process.env[name] === "1");
+  }
+
+  /**
+   * On unless the env says otherwise, which is the opposite of `#isEnvEnabled`.
+   *
+   * MCP exposure follows an endpoint's guards rather than an opt-in, so there is nothing an app has to declare for
+   * its catalogue to be right — and a switch that must be found before anything works is a switch most deployments
+   * never find. `AKAN_MCP=false` is the way off.
+   */
+  static #isEnvOn(...names: string[]) {
+    return !names.some((name) => process.env[name] === "false" || process.env[name] === "0");
+  }
+
+  /** Both differ per environment, so they belong in env rather than in the app's source alongside the switch. */
+  static #mcpAuthFromEnv(): McpAuthOption {
+    const authorizationServers = AkanServer.#envList("AKAN_MCP_AUTH_SERVERS");
+    const scopes = AkanServer.#envList("AKAN_MCP_SCOPES");
+    return {
+      ...(authorizationServers?.length ? { authorizationServers } : {}),
+      ...(scopes?.length ? { scopes } : {}),
+      ...(process.env.AKAN_MCP_RESOURCE ? { resource: process.env.AKAN_MCP_RESOURCE } : {}),
+    };
+  }
+
+  /**
+   * The rest of `McpServerOption`, spelled as environment — the channel a deployment configures what the source
+   * does not through, and the only one a child of the gateway is handed. An app writes these in its `option.ts`,
+   * which merges over this: a value written in code wins over the env of the same name.
+   */
+  /**
+   * Keys whose value is `undefined` are dropped before the merge. "An option written in code wins over the env of
+   * the same name" is the contract, and a spread reads an explicitly-`undefined` property as a value — so
+   * `{ path: undefined }` from a caller assembling options conditionally erased what the environment supplied.
+   */
+  static #defined<T extends object>(source: T): Partial<T> {
+    return Object.fromEntries(Object.entries(source).filter(([, value]) => value !== undefined)) as Partial<T>;
+  }
+
+  static #mcpOptionFromEnv(): Omit<McpServerOption, "enabled" | "readOnly" | "auth"> {
+    const allowedOrigins = AkanServer.#envList("AKAN_MCP_ALLOWED_ORIGINS");
+    const pageSize = Number(process.env.AKAN_MCP_PAGE_SIZE);
+    return {
+      ...AkanServer.#mcpPathFromEnv(),
+      ...(process.env.AKAN_MCP_VERSION ? { version: process.env.AKAN_MCP_VERSION } : {}),
+      ...(process.env.AKAN_MCP_INSTRUCTIONS ? { instructions: process.env.AKAN_MCP_INSTRUCTIONS } : {}),
+      ...(allowedOrigins?.length ? { allowedOrigins } : {}),
+      ...(Number.isInteger(pageSize) && pageSize > 0 ? { pageSize } : {}),
+      ...(process.env.AKAN_MCP_LANGUAGE ? { language: process.env.AKAN_MCP_LANGUAGE } : {}),
+    };
+  }
+
+  /**
+   * Both consumers build their path by concatenation — the route key, and the RFC 9728 metadata path the resource
+   * identifier is inserted into — so `AKAN_MCP_PATH=mcp` served a route named `mcp` and published its metadata at
+   * `/.well-known/oauth-protected-resourcemcp`, which no client would ever look for. Normalized rather than
+   * rejected: the intent is unambiguous, and a server that refuses to boot over a missing slash is worse.
+   */
+  static #mcpPathFromEnv() {
+    const path = process.env.AKAN_MCP_PATH?.trim();
+    if (!path) return {};
+    return { path: path.startsWith("/") ? path : `/${path}` };
+  }
+
+  static #envList(name: string) {
+    return process.env[name]
+      ?.split(",")
+      .map((entry) => entry.trim())
+      .filter(Boolean);
   }
 
   /**

package/server/animatedImage.ts

@@ -0,0 +1,83 @@
+/**
+ * `Bun.Image.metadata()` reports only `{ width, height, format }` — there is no frame count — and an
+ * animated GIF decodes to its first frame without erroring. So an optimizer that re-encodes whatever
+ * decodes would silently drop the animation. These readers answer the question from the container bytes
+ * instead, so an animated source can be passed through untouched.
+ */
+
+/** Sub-blocks are a `[length][bytes]…[0]` chain, so a frame's payload cannot be skipped by size alone. */
+const skipGifSubBlocks = (buffer: Buffer, start: number): number => {
+  let offset = start;
+  while (offset < buffer.length) {
+    const size = buffer[offset];
+    offset += 1;
+    if (size === undefined || size === 0) return offset;
+    offset += size;
+  }
+  return offset;
+};
+
+const colorTableSize = (packed: number): number => ((packed & 0x80) === 0 ? 0 : 3 * 2 ** ((packed & 0x07) + 1));
+
+/**
+ * Walks the GIF block stream to count image descriptors. Counting raw `0x2C` bytes would overcount —
+ * the byte occurs freely inside colour tables and LZW payloads — so every block has to be stepped over.
+ */
+const hasMultipleGifFrames = (buffer: Buffer): boolean => {
+  if (buffer.length < 13) return false;
+  let offset = 6;
+  offset += 7 + colorTableSize(buffer[offset + 4] ?? 0);
+  let frames = 0;
+  while (offset < buffer.length) {
+    const block = buffer[offset];
+    offset += 1;
+    if (block === 0x3b) break;
+    if (block === 0x21) {
+      offset = skipGifSubBlocks(buffer, offset + 1);
+      continue;
+    }
+    if (block !== 0x2c) break;
+    frames += 1;
+    if (frames > 1) return true;
+    offset += 9 + colorTableSize(buffer[offset + 8] ?? 0);
+    offset = skipGifSubBlocks(buffer, offset + 1);
+  }
+  return frames > 1;
+};
+
+/** An animated WebP is an extended (`VP8X`) file carrying an `ANIM` chunk; a still one never has it. */
+const hasWebpAnimChunk = (buffer: Buffer): boolean => {
+  let offset = 12;
+  while (offset + 8 <= buffer.length) {
+    const id = buffer.toString("ascii", offset, offset + 4);
+    if (id === "ANIM") return true;
+    const size = buffer.readUInt32LE(offset + 4);
+    offset += 8 + size + (size % 2);
+  }
+  return false;
+};
+
+/** APNG marks itself with an `acTL` chunk, which the spec requires before the first `IDAT`. */
+const hasPngAnimationControl = (buffer: Buffer): boolean => {
+  let offset = 8;
+  while (offset + 8 <= buffer.length) {
+    const size = buffer.readUInt32BE(offset);
+    const id = buffer.toString("ascii", offset + 4, offset + 8);
+    if (id === "acTL") return true;
+    if (id === "IDAT" || id === "IEND") return false;
+    offset += 12 + size;
+  }
+  return false;
+};
+
+export const isAnimatedImage = (buffer: Buffer, contentType: string): boolean => {
+  try {
+    if (contentType === "image/gif") return hasMultipleGifFrames(buffer);
+    if (contentType === "image/webp") return hasWebpAnimChunk(buffer);
+    if (contentType === "image/png") return hasPngAnimationControl(buffer);
+    return false;
+  } catch {
+
+    return true;
+  }
+};

package/server/artifact/routeClientCache.ts

@@ -48,12 +48,22 @@ export class RouteClientCache {
   };
   readonly #buildRoute: RouteBuildFn;
   readonly #onMerge?: OnMergeFn;
+  #revision = 0;
 
   constructor({ buildRoute, onMerge }: RouteClientCacheOptions) {
     this.#buildRoute = buildRoute;
     this.#onMerge = onMerge;
   }
 
+  /**
+   * Bumped on every mutation of `merged`, including a delta merge that leaves `generation` where it was. It lets a
+   * consumer memoize work derived from the manifest — merging the runtime manifest over it, say — without having to
+   * copy the manifest to find out whether anything changed. In production nothing after `seed` moves it at all.
+   */
+  get revision(): number {
+    return this.#revision;
+  }
+
   #getEmptyDelta(): BuildRouteClientResult {
     return {
       manifestDelta: {},
@@ -75,6 +85,7 @@ export class RouteClientCache {
     Object.assign(this.merged.ssrManifest.moduleMap, manifest.ssrManifest.moduleMap);
     for (const abs of manifest.knownEntries) this.merged.knownEntries.add(abs);
     for (const routeId of manifest.routeIds) this.#built.set(routeId, this.#getEmptyDelta());
+    this.#revision += 1;
   }
 
   async ensure(routeId: string, seeds: string[]): Promise<MergedManifest> {
@@ -125,6 +136,7 @@ export class RouteClientCache {
     for (const [url, byName] of Object.entries(delta.ssrManifestDelta.moduleMap))
       this.merged.ssrManifest.moduleMap[url] = byName;
     for (const entry of delta.newEntries) this.merged.knownEntries.add(entry);
+    this.#revision += 1;
     this.#built.set(routeId, delta);
     this.#logger.verbose(
       `[route-cache] build done routeId=${routeId} generation=${generation} entries=+${delta.newEntries.length} deps=${delta.clientDeps.length} in ${Date.now() - started}ms`,
@@ -176,6 +188,7 @@ export class RouteClientCache {
     }
     const nextGeneration = this.merged.generation + 1;
     this.merged = this.#getEmptyMerged(nextGeneration);
+    this.#revision += 1;
     this.#building.clear();
     this.#logger.verbose(`[route-cache] cleared generation=${nextGeneration} dropped=${dropped.length}`);
     return dropped;
@@ -209,6 +222,7 @@ export class RouteClientCache {
       ),
     };
     this.merged = next;
+    this.#revision += 1;
   }
 
   static #normalizePath(filePath: string): string {

package/server/assetEncoding.ts

@@ -0,0 +1,47 @@
+const COMPRESSIBLE_TYPES = new Set([
+  "application/javascript",
+  "application/json",
+  "application/manifest+json",
+  "image/svg+xml",
+]);
+
+/**
+ * br is tried first: it is ~15% smaller than gzip across the artifact and ~22% on the CSS bundle.
+ * The gzip sidecar stays the fallback because browsers only advertise `br` on secure origins, so a
+ * plain-http dev server or an intermediary that rewrites Accept-Encoding still gets a compressed body.
+ */
+const SIDECAR_ENCODINGS = [
+  { encoding: "br", ext: ".br", accept: /(?:^|,)\s*(?:br|\*)(?![\w-])\s*(?:;\s*q=([\d.]+))?/i },
+  { encoding: "gzip", ext: ".gz", accept: /(?:^|,)\s*(?:gzip|\*)(?![\w-])\s*(?:;\s*q=([\d.]+))?/i },
+] as const;
+
+export interface EncodedSidecar {
+  bytes: ArrayBuffer;
+  encoding: string;
+}
+
+export const isCompressibleContentType = (contentType: string): boolean => {
+  const type = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+  return type.startsWith("text/") || COMPRESSIBLE_TYPES.has(type);
+};
+
+/** Picks the best precompressed sidecar the caller accepts, or null to serve the file as-is. */
+export const resolveEncodedSidecar = async (
+  req: Request,
+  filePath: string,
+  contentType: string,
+): Promise<EncodedSidecar | null> => {
+  if (!isCompressibleContentType(contentType)) return null;
+  const acceptEncoding = req.headers.get("accept-encoding") ?? "";
+  for (const { encoding, ext, accept } of SIDECAR_ENCODINGS) {
+    const match = accept.exec(acceptEncoding);
+    
+    if (!match || (match[1] !== undefined && Number.parseFloat(match[1]) <= 0)) continue;
+    const file = Bun.file(`${filePath}${ext}`);
+    if (!(await file.exists())) continue;
+    const bytes = await file.bytes();
+    const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+    return { bytes: buffer, encoding };
+  }
+  return null;
+};