@rivetjs/router 0.1.0-alpha.0 → 0.1.0-alpha.1

package/adapters/files.d.ts

@@ -3,5 +3,18 @@ export interface StaticFile {
     readonly path: string;
     readonly headers: Record<string, string>;
 }
+/** A response encoding the adapters produce. */
+export type Encoding = "zstd" | "br" | "gzip" | null;
+/**
+ * `q` per content coding of an `Accept-Encoding` header, parsed once per distinct string (browsers send a handful;
+ * bounded: client-controlled text). `weightOf` applies `*` to codings the header does not name.
+ */
+export declare function acceptWeights(header: string): Map<string, number>;
+export declare const weightOf: (accepted: Map<string, number>, name: string) => number;
+/**
+ * Pick `zstd`, `br` or `gzip` from an Accept-Encoding header: the highest `q` (a tie: `zstd`, then `br`); q=0 excludes.
+ * `zstd: false` never picks zstd (`serve({ compress: { zstd: false } })`).
+ */
+export declare function negotiate(header: string | null | undefined, zstd?: boolean): Encoding;
 /** Index `client` (served under `base`); returns the per-request lookup. */
 export declare function staticFiles(client: string, base: string, immutable: readonly string[]): (request: Request, pathname: string) => StaticFile | 304 | null;

package/adapters/files.js

@@ -2,7 +2,7 @@
 // runtimes implement `node:fs` / `node:path`), looked up per GET/HEAD by URL path. Same rules as the
 // node adapter: below the base only, no `\0` or dot segments (except a root `.well-known/`), hashed
 // `<base>/assets/` immutable, everything else `no-cache` + weak ETag (304 on `If-None-Match`),
-// precompressed `.br` / `.gz` siblings when the client accepts them. Directory pages
+// precompressed `.zst` / `.br` / `.gz` siblings when the client accepts them (zstd first). Directory pages
 // (`a/index.html`, `a.html`, as the static adapter writes them) answer at `/a` and `/a/`.
 import { readdirSync, realpathSync, statSync } from "node:fs";
 import { extname, join, relative, sep } from "node:path";
@@ -28,6 +28,45 @@ const MIME = {
     ".woff2": "font/woff2",
     ".woff": "font/woff",
 };
+/**
+ * `q` per content coding of an `Accept-Encoding` header, parsed once per distinct string (browsers send a handful;
+ * bounded: client-controlled text). `weightOf` applies `*` to codings the header does not name.
+ */
+export function acceptWeights(header) {
+    let accepted = weights.get(header);
+    if (accepted === undefined) {
+        accepted = new Map();
+        for (const part of header.toLowerCase().split(",")) {
+            const [name, ...params] = part.trim().split(";");
+            const q = params.map((p) => /^\s*q=([\d.]+)\s*$/.exec(p)).find(Boolean);
+            accepted.set(name.trim(), q ? Number(q[1]) : 1);
+        }
+        if (weights.size < 64)
+            weights.set(header, accepted);
+    }
+    return accepted;
+}
+const weights = new Map();
+export const weightOf = (accepted, name) => accepted.get(name) ?? accepted.get("*") ?? 0;
+/**
+ * Pick `zstd`, `br` or `gzip` from an Accept-Encoding header: the highest `q` (a tie: `zstd`, then `br`); q=0 excludes.
+ * `zstd: false` never picks zstd (`serve({ compress: { zstd: false } })`).
+ */
+export function negotiate(header, zstd = true) {
+    if (!header)
+        return null;
+    const memo = zstd ? negotiated : negotiatedNoZstd;
+    let hit = memo.get(header);
+    if (hit === undefined) {
+        const accepted = acceptWeights(header);
+        const zs = zstd ? weightOf(accepted, "zstd") : 0, br = weightOf(accepted, "br"), gzip = weightOf(accepted, "gzip");
+        hit = zs > 0 && zs >= br && zs >= gzip ? "zstd" : br > 0 && br >= gzip ? "br" : gzip > 0 ? "gzip" : null;
+        if (memo.size < 64)
+            memo.set(header, hit);
+    }
+    return hit;
+}
+const negotiated = new Map(), negotiatedNoZstd = new Map();
 /** Index `client` (served under `base`); returns the per-request lookup. */
 export function staticFiles(client, base, immutable) {
     const files = new Map();
@@ -47,6 +86,8 @@ export function staticFiles(client, base, immutable) {
             continue;
         if (/\.(br|gz)$/.test(key) && names.has(full.slice(0, -3)))
             continue;
+        if (key.endsWith(".zst") && names.has(full.slice(0, -4)))
+            continue;
         const info = statSync(full);
         const url = base + "/" + key;
         const file = {
@@ -55,6 +96,7 @@ export function staticFiles(client, base, immutable) {
             etag: `W/"${info.size.toString(16)}-${Math.floor(info.mtimeMs).toString(16)}"`,
             modified: info.mtime.toUTCString(),
             immutable: immutable.some((prefix) => url.startsWith(prefix)),
+            ...(names.has(full + ".zst") ? { zst: full + ".zst" } : {}),
             ...(names.has(full + ".br") ? { br: full + ".br" } : {}),
             ...(names.has(full + ".gz") ? { gz: full + ".gz" } : {}),
         };
@@ -89,13 +131,23 @@ export function staticFiles(client, base, immutable) {
             ETag: file.etag,
             "Last-Modified": file.modified,
         };
-        if (file.br || file.gz) {
+        if (file.zst || file.br || file.gz) {
             headers.Vary = "Accept-Encoding";
-            const accept = request.headers.get("accept-encoding") ?? "";
-            const encoding = file.br && /\bbr\b/.test(accept) ? "br" : file.gz && /\bgzip\b/.test(accept) ? "gzip" : null;
-            if (encoding) {
+            // The best-weighted coding among the siblings that exist (`q=0` excludes; a tie: zstd, then br).
+            const accepted = acceptWeights(request.headers.get("accept-encoding") ?? "");
+            let path, encoding = "", best = 0;
+            for (const [name, sibling] of [
+                ["zstd", file.zst],
+                ["br", file.br],
+                ["gzip", file.gz],
+            ]) {
+                const q = sibling ? weightOf(accepted, name) : 0;
+                if (q > best)
+                    ((best = q), (path = sibling), (encoding = name));
+            }
+            if (path) {
                 headers["Content-Encoding"] = encoding;
-                return { path: encoding === "br" ? file.br : file.gz, headers };
+                return { path, headers };
             }
         }
         return { path: file.path, headers };

package/adapters/node.d.ts

@@ -2,7 +2,10 @@ import { type IncomingMessage, type Server, type ServerResponse } from "node:htt
 import type { BodyLimit } from "../server/security.js";
 import type { ErrorInfo } from "../server/handler.js";
 import type { AppConfig } from "../server/app.js";
-/** Per-request context passed to the handler. */
+/**
+ * Per-request context passed to the handler. It never carries `locals`: the adapter fills nothing from request
+ * headers, query or body. A handler that renders with its own data forwards `{ ...context, locals }` to the app.
+ */
 export interface RequestContext {
     /** Fresh CSP nonce (base64) for inline scripts the handler emits. */
     readonly nonce: string;
@@ -11,6 +14,13 @@ export interface RequestContext {
 }
 /** A request handler (web `Request` → `Response`) served by the Node adapter. */
 export type Handler = (request: Request, context: RequestContext) => Response | Promise<Response>;
+/** `serve({ compress })` as an object: which codecs and whether immutable files' compressed copies are written to disk. */
+export interface CompressOptions {
+    /** Offer `zstd` (default true). `false`: brotli / gzip only. */
+    zstd?: boolean;
+    /** Write immutable files' compressed copies next to them on their first request (default true). */
+    precompress?: boolean;
+}
 /** Options of `serve()`. */
 export interface ServeOptions {
     handler: Handler;
@@ -28,8 +38,16 @@ export interface ServeOptions {
      * later are not served. `"fs"`: look each GET up on disk (a directory that changes while serving).
      */
     static?: "index" | "fs";
-    /** Compress responses by `Accept-Encoding` (default true). */
-    compress?: boolean;
+    /**
+     * Compress responses by `Accept-Encoding` (default true): `zstd` when the client accepts it (level 1 for bodies of
+     * 256 KiB and more, 3 below; streamed bodies by what is collected when streaming starts), else brotli (q4), else gzip
+     * (6). Immutable `client` files are precompressed once per file at the best quality (brotli q11, zstd 19, gzip 9) on
+     * their first request and written next to the file (`.br` / `.zst` / `.gz`, hidden temp + rename; a read-only
+     * directory keeps them in memory only), so the next process start serves them from disk; build-time siblings are
+     * used as they are. `{ zstd: false }`: brotli / gzip only (no zstd work at all); `{ precompress: false }`: nothing
+     * written to disk. `false`: no compression (a proxy that compresses).
+     */
+    compress?: boolean | CompressOptions;
     /**
      * Send `103 Early Hints` when the app asks (`createApp({ earlyHints })`; `start({ earlyHints })` sets both), to
      * HTTP/1.1 clients only (1xx are not allowed for 1.0). Browsers use 103s over HTTP/2+ only: behind a proxy or CDN
@@ -97,8 +115,7 @@ export interface PrimaryServing {
     /** Drain every worker (each within its `grace`), then resolve once all exited. */
     close(): Promise<void>;
 }
-/** Pick `br` or `gzip` from an Accept-Encoding header: the higher `q` (a tie: `br`); q=0 excludes. */
-export declare function negotiate(header: string | null | undefined): "br" | "gzip" | null;
+export { negotiate, type Encoding } from "./files.js";
 /** `If-None-Match` (a list, `*`, weak or strong tags) matches `etag` (weak comparison, as for GET). */
 export declare function etagMatches(header: string | undefined, etag: string): boolean;
 /**

package/adapters/node.js

@@ -1,14 +1,15 @@
 // Node HTTP adapter: serves built client assets and streams a web-standard handler's Responses.
 import { createServer } from "node:http";
 import { createReadStream, readdirSync, realpathSync, statSync } from "node:fs";
-import { readFile, realpath, stat } from "node:fs/promises";
-import { extname, join, resolve, sep } from "node:path";
+import { readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join, resolve, sep } from "node:path";
 import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
-import { brotliCompress, brotliCompressSync, constants as zlib, createBrotliCompress, createGzip, gzip, gzipSync } from "node:zlib";
+import { brotliCompress, brotliCompressSync, constants as zlib, createBrotliCompress, createGzip, createZstdCompress, gzip, gzipSync, zstdCompress, zstdCompressSync, } from "node:zlib";
 import { promisify } from "node:util";
 import { availableParallelism } from "node:os";
 import { loadBuild } from "./build.js";
+import { negotiate } from "./files.js";
 import { normalizeBase } from "../shared/base.js";
 import { nonce } from "../shared/nonce.js";
 import { DIRECT_BODY } from "../server/body.js";
@@ -41,32 +42,9 @@ const MIME = {
 };
 const COMPRESSIBLE = /^(text\/|application\/(json|javascript|xml|manifest\+json|wasm)|image\/svg\+xml)/;
 const MIN_COMPRESS = 1024;
-const brotli = promisify(brotliCompress), gz = promisify(gzip);
-/** Pick `br` or `gzip` from an Accept-Encoding header: the higher `q` (a tie: `br`); q=0 excludes. */
-export function negotiate(header) {
-    if (!header)
-        return null;
-    // Browsers send a handful of distinct headers: parse once per string (bounded: client-controlled text).
-    let hit = negotiated.get(header);
-    if (hit === undefined) {
-        hit = parseEncoding(header);
-        if (negotiated.size < 64)
-            negotiated.set(header, hit);
-    }
-    return hit;
-}
-const negotiated = new Map();
-function parseEncoding(header) {
-    const accepted = new Map();
-    for (const part of header.toLowerCase().split(",")) {
-        const [name, ...params] = part.trim().split(";");
-        const q = params.map((p) => /^\s*q=([\d.]+)\s*$/.exec(p)).find(Boolean);
-        accepted.set(name.trim(), q ? Number(q[1]) : 1);
-    }
-    const weight = (name) => accepted.get(name) ?? accepted.get("*") ?? 0;
-    const br = weight("br"), gzip = weight("gzip");
-    return br > 0 && br >= gzip ? "br" : gzip > 0 ? "gzip" : null;
-}
+const brotli = promisify(brotliCompress), gz = promisify(gzip), zstd = promisify(zstdCompress);
+// `negotiate` / `Encoding` live in `files.ts` (pure; shared with the Bun / Deno static index) and stay exported here.
+export { negotiate } from "./files.js";
 /** `If-None-Match` (a list, `*`, weak or strong tags) matches `etag` (weak comparison, as for GET). */
 export function etagMatches(header, etag) {
     if (!header)
@@ -103,17 +81,34 @@ export function byteRange(header, size) {
     return [start, end];
 }
 // Bodies up to this size that finish before the event loop turns are compressed in one synchronous
-// call (tens of microseconds for a page; a streaming compressor costs ~0.5 ms to set up).
+// call (tens of microseconds for a page; a streaming compressor costs ~0.5 ms to set up). zstd −1 runs at
+// ≈ 350 MB/s here, so its one-shot call stays synchronous up to `ZSTD_SYNC` (the thread-pool round trip of the async
+// convenience path cost ≈ +1 ms on a 757 KB page through the adapter: `docs/design/research/2026-10-18-floor-first.md` §9).
 const ONE_SHOT_SYNC = 256 * 1024;
+const ZSTD_SYNC = 4 * 1024 * 1024;
+// Per-request codec levels (floor-first X1, `docs/design/research/2026-10-18-floor-first.md` §8): zstd −1 on large
+// bodies (0.18× brotli q5's CPU at +10 % bytes on a 757 KB table), −3 on content-sized ones (0.5× at +14 %); brotli
+// q4 is the brotli sweet spot (0.54×) for clients without zstd; gzip last.
+const LARGE_BODY = 256 * 1024;
 const HTML_BROTLI = { [zlib.BROTLI_PARAM_QUALITY]: 4, [zlib.BROTLI_PARAM_MODE]: zlib.BROTLI_MODE_TEXT };
+const zstdLevel = (size) => ({ [zlib.ZSTD_c_compressionLevel]: size >= LARGE_BODY ? 1 : 3 });
 function compressOnce(encoding, body) {
+    if (encoding === "zstd") {
+        const params = zstdLevel(body.length);
+        return body.length > ZSTD_SYNC ? zstd(body, { params }) : zstdCompressSync(body, { params });
+    }
     const params = { ...HTML_BROTLI, [zlib.BROTLI_PARAM_SIZE_HINT]: body.length };
     if (body.length > ONE_SHOT_SYNC)
         return encoding === "br" ? brotli(body, { params }) : gz(body, { level: 6 });
     return encoding === "br" ? brotliCompressSync(body, { params }) : gzipSync(body, { level: 6 });
 }
-/** Streaming compressor that flushes every chunk, so streamed HTML reaches the browser promptly. */
-function compressor(encoding) {
+/**
+ * Streaming compressor that flushes every chunk, so streamed HTML reaches the browser promptly. `collected`: bytes
+ * in hand when streaming starts (a body already past `LARGE_BODY` takes zstd's large-body level).
+ */
+function compressor(encoding, collected = 0) {
+    if (encoding === "zstd")
+        return createZstdCompress({ flush: zlib.ZSTD_e_flush, params: zstdLevel(collected) });
     return encoding === "br"
         ? createBrotliCompress({
             flush: zlib.BROTLI_OPERATION_FLUSH,
@@ -121,7 +116,33 @@ function compressor(encoding) {
         })
         : createGzip({ flush: zlib.Z_SYNC_FLUSH, level: 6 });
 }
-/** The one dot-named directory served (RFC 8615: `security.txt`, `assetlinks.json`, ACME challenges), at the root only. */
+/** Best-quality compression of a body compressed once and reused (client files, stored pages): brotli q11, zstd 19, gzip 9. */
+function compressBest(encoding, body) {
+    if (encoding === "zstd")
+        return zstd(body, { params: { [zlib.ZSTD_c_compressionLevel]: 19 } });
+    if (encoding === "br")
+        return brotli(body, {
+            params: { [zlib.BROTLI_PARAM_QUALITY]: 11, [zlib.BROTLI_PARAM_MODE]: zlib.BROTLI_MODE_TEXT, [zlib.BROTLI_PARAM_SIZE_HINT]: body.length },
+        });
+    return gz(body, { level: 9 });
+}
+const SIBLING = { zstd: ".zst", br: ".br", gzip: ".gz" };
+/**
+ * Write a compressed copy next to its file (hidden temp name, then rename: a concurrent reader or worker never sees a
+ * partial file; the temp is never served). False when the directory is not writable.
+ */
+async function persist(path, bytes) {
+    const temp = join(dirname(path), `.${basename(path)}.${process.pid}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}.tmp`);
+    try {
+        await writeFile(temp, bytes);
+        await rename(temp, path);
+        return true;
+    }
+    catch {
+        await rm(temp, { force: true }).catch(() => { });
+        return false;
+    }
+}
 /** Bytes a streamed direct body may queue in the response before the renderer waits for `drain`. */
 const MAX_BUFFERED = 256 * 1024;
 /**
@@ -226,7 +247,7 @@ function sendDirect(attach, res, response, request, headers, encoding, vary) {
             vary();
         }
         head();
-        const packer = encoding ? compressor(encoding) : null;
+        const packer = encoding ? compressor(encoding, size) : null;
         if (packer)
             pipeline(packer, res).catch(close);
         const to = (target = packer ?? res);
@@ -299,6 +320,7 @@ function sendDirect(attach, res, response, request, headers, encoding, vary) {
     }
     return result;
 }
+/** The one dot-named directory served (RFC 8615: `security.txt`, `assetlinks.json`, ACME challenges), at the root only. */
 const WELL_KNOWN = ".well-known";
 /** Dot-named path segments are refused, except a leading `.well-known`. */
 const hidden = (decoded) => {
@@ -322,10 +344,11 @@ function indexFiles(client) {
         return out;
     }
     const inside = (real) => real === root || real.startsWith(root + sep);
-    const sizeOf = (path) => {
+    /** Size of a precompressed sibling, −1 when absent or older than its source (a copy-over deploy left a stale copy). */
+    const sizeOf = (path, sourceMtime) => {
         try {
             const info = statSync(path);
-            return info.isFile() ? info.size : -1;
+            return info.isFile() && info.mtimeMs >= sourceMtime ? info.size : -1;
         }
         catch {
             return -1;
@@ -363,7 +386,14 @@ function indexFiles(client) {
                 open.delete(real);
             }
             else if (info.isFile())
-                out.set(name, { path: real, size: info.size, mtime: info.mtimeMs, br: sizeOf(real + ".br"), gz: sizeOf(real + ".gz") });
+                out.set(name, {
+                    path: real,
+                    size: info.size,
+                    mtime: info.mtimeMs,
+                    zstd: sizeOf(real + ".zst", info.mtimeMs),
+                    br: sizeOf(real + ".br", info.mtimeMs),
+                    gzip: sizeOf(real + ".gz", info.mtimeMs),
+                });
         }
     };
     walk(root, "", new Set([root]));
@@ -428,7 +458,11 @@ function drain(req) {
 }
 /** Create the Node request listener (exposed for custom servers and tests). */
 export function createListener(options) {
-    const { handler, compress = true, earlyHints = false, onError = (error) => console.error(error) } = options;
+    const { handler, earlyHints = false, onError = (error) => console.error(error) } = options;
+    const compress = options.compress !== false;
+    const codecs = typeof options.compress === "object" ? options.compress : null;
+    const withZstd = codecs?.zstd !== false;
+    const precompress = compress && codecs?.precompress !== false;
     const prefix = normalizeBase(options.base);
     const immutable = options.immutable ?? ((pathname) => pathname.startsWith(prefix + "/assets/"));
     // Header names compare case-insensitively: `res.writeHead` sends differently cased keys as separate
@@ -491,6 +525,7 @@ export function createListener(options) {
     let draining = false, inflight = 0, wake = null;
     const memory = options.idleMemory !== false && idleMemorySupported() ? idleMemory(() => inflight) : null;
     const cache = new Map(); // compressed static bodies by path|etag|encoding
+    const pending = new Map(); // compressions in flight by the same key: N concurrent first requests compress once
     const index = client && options.static !== "fs" ? indexFiles(client) : null;
     const metas = new WeakMap();
     /** Resolve a URL path to a file inside the client directory; null when absent or escaping. */
@@ -581,29 +616,41 @@ export function createListener(options) {
                 await pipeline(createReadStream(found.path, { start: from, end: to }), res);
             return true;
         }
-        const encoding = compress && COMPRESSIBLE.test(type) && found.size >= MIN_COMPRESS ? negotiate(req.headers["accept-encoding"]) : null;
+        const encoding = compress && COMPRESSIBLE.test(type) && found.size >= MIN_COMPRESS ? negotiate(req.headers["accept-encoding"], withZstd) : null;
         if (encoding) {
-            const ext = encoding === "br" ? ".br" : ".gz";
-            // Prefer a build-time precompressed sibling; otherwise compress once and keep it in memory.
-            const sibling = (encoding === "br" ? found.br : found.gz) ??
-                (await stat(found.path + ext).then((s) => (s.isFile() ? s.size : -1), () => -1));
-            let body;
-            if (sibling >= 0)
-                body = await readFile(found.path + ext);
-            else {
-                const key = found.path + "|" + etag + "|" + encoding;
-                let cached = cache.get(key);
-                if (!cached) {
-                    const raw = await readFile(found.path);
-                    cached =
-                        encoding === "br"
-                            ? await brotli(raw, { params: { [zlib.BROTLI_PARAM_QUALITY]: 11, [zlib.BROTLI_PARAM_SIZE_HINT]: raw.length } })
-                            : await gz(raw, { level: 9 });
-                    if (cache.size > 512)
-                        cache.clear();
-                    cache.set(key, cached);
+            const ext = SIBLING[encoding];
+            // A copy compressed in this process (bounded memory), else a precompressed sibling on disk (build-time, or
+            // written by an earlier process), else compress once at the best quality: kept in memory, and for an immutable
+            // file written next to it (hidden temp + rename) so later starts read it from disk.
+            const key = found.path + "|" + etag + "|" + encoding;
+            let body = cache.get(key);
+            if (!body) {
+                // A sibling older than its source is a stale copy (copy-over deploy): ignored and overwritten below.
+                const sibling = found[encoding] ??
+                    (await stat(found.path + ext).then((s) => (s.isFile() && s.mtimeMs >= found.mtime ? s.size : -1), () => -1));
+                if (sibling >= 0)
+                    body = await readFile(found.path + ext);
+                else {
+                    let job = pending.get(key);
+                    if (!job) {
+                        job = readFile(found.path)
+                            .then((raw) => compressBest(encoding, raw))
+                            .then((bytes) => {
+                            if (cache.size > 512)
+                                cache.clear();
+                            cache.set(key, bytes);
+                            if (precompress && immutable(pathname))
+                                void persist(found.path + ext, bytes).then((written) => {
+                                    if (written && index)
+                                        found[encoding] = bytes.length;
+                                });
+                            return bytes;
+                        })
+                            .finally(() => pending.delete(key));
+                        pending.set(key, job);
+                    }
+                    body = await job;
                 }
-                body = cached;
             }
             res.writeHead(200, { ...headers, "Content-Encoding": encoding, "Content-Length": String(body.length) });
             res.end(req.method === "HEAD" ? undefined : body);
@@ -656,18 +703,14 @@ export function createListener(options) {
             return;
         }
         const encoding = compress && req.method !== "HEAD" && page.body.byteLength >= MIN_COMPRESS && COMPRESSIBLE.test(out.plain["content-type"] ?? "")
-            ? negotiate(req.headers["accept-encoding"])
+            ? negotiate(req.headers["accept-encoding"], withZstd)
             : null;
         if (!encoding) {
             res.writeHead(200, { ...out.plain, age, "x-rivet-cache": "HIT", "content-length": String(page.body.byteLength) });
             res.end(req.method === "HEAD" ? undefined : page.body);
             return;
         }
-        const body = await (out[encoding] ??= (encoding === "br"
-            ? brotli(page.body, {
-                params: { [zlib.BROTLI_PARAM_QUALITY]: 11, [zlib.BROTLI_PARAM_MODE]: zlib.BROTLI_MODE_TEXT, [zlib.BROTLI_PARAM_SIZE_HINT]: page.body.byteLength },
-            })
-            : gz(page.body, { level: 9 })).then((packed) => (page.charge(packed.length), packed)));
+        const body = await (out[encoding] ??= compressBest(encoding, page.body).then((packed) => (page.charge(packed.length), packed)));
         res.writeHead(200, { ...out.plain, age, "x-rivet-cache": "HIT", "content-encoding": encoding, "content-length": String(body.length) });
         res.end(body);
     }
@@ -686,7 +729,7 @@ export function createListener(options) {
             headers["set-cookie"] = cookies;
         const type = response.headers.get("content-type") ?? "";
         const body = response.body;
-        const encoding = compress && body && !response.headers.has("content-encoding") && COMPRESSIBLE.test(type) ? negotiate(req.headers["accept-encoding"]) : null;
+        const encoding = compress && body && !response.headers.has("content-encoding") && COMPRESSIBLE.test(type) ? negotiate(req.headers["accept-encoding"], withZstd) : null;
         const vary = () => (headers.vary = response.headers.has("vary") ? response.headers.get("vary") + ", Accept-Encoding" : "Accept-Encoding");
         if (!body || req.method === "HEAD") {
             if (encoding)
@@ -747,10 +790,13 @@ export function createListener(options) {
             res.end(chunks[chunks.length - 1]);
             return;
         }
+        let collected = 0;
         if (encoding) {
             delete headers["content-length"];
             headers["content-encoding"] = encoding;
             vary();
+            for (const chunk of chunks)
+                collected += chunk.byteLength;
         }
         res.writeHead(response.status, response.statusText || undefined, headers);
         const rest = pending;
@@ -764,7 +810,7 @@ export function createListener(options) {
                 request.signal.removeEventListener("abort", cancel);
             }
         })(), { objectMode: false });
-        await (encoding ? pipeline(source, compressor(encoding), res) : pipeline(source, res));
+        await (encoding ? pipeline(source, compressor(encoding, collected), res) : pipeline(source, res));
     }
     const reject = (res, status, message) => void res.writeHead(status, { ...base, "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store", Connection: "close" }).end(message);
     const listener = (req, res) => {

package/adapters/static.js

@@ -154,7 +154,7 @@ export async function prerender(options) {
             // Layout loaders/guards run per request too: the CSR shell would skip them.
             const layouts = await Promise.all(route.layouts.map(loadServer));
             if ([module, ...layouts].some((m) => m?.load || m?.guard))
-                throw new Error(`Route ${route.id} needs a server (serverLoad/serverGuard on it or a layout, without prerender); use the node adapter or add serverEntries()`);
+                throw new Error(`Route ${route.id} needs a server (a load(…) / guard(…) export on it or a layout, without prerender); use the node adapter or add an entries(…) export`);
             if (!report.fallback.includes(route.id))
                 report.fallback.push(route.id);
             continue;

package/adapters/target-build.d.ts

@@ -38,8 +38,11 @@ export interface VercelAdapterOptions extends TargetOptions {
     readonly isr?: {
         readonly expiration: number | false;
     };
-    /** Brotli/gzip in the Node.js function (default true; see `@rivetjs/router/vercel`). */
-    readonly compress?: boolean;
+    /** zstd / brotli / gzip in the Node.js function (default true; `{ zstd: false }` for brotli / gzip only; see `@rivetjs/router/vercel`). */
+    readonly compress?: boolean | {
+        readonly zstd?: boolean;
+        readonly precompress?: boolean;
+    };
 }
 /**
  * Netlify, Frameworks API (https://docs.netlify.com/build/frameworks/frameworks-api/): a

package/adapters/vercel.d.ts

@@ -4,6 +4,7 @@ import type { ErrorInfo } from "../server/handler.js";
 import type { BodyLimit } from "../server/security.js";
 import type { AppConfig } from "../server/app.js";
 import { type BuildManifests } from "./assemble.js";
+import { type CompressOptions } from "./node.js";
 export interface VercelOptions {
     /** Fixed public origin; default: the request's `Host` + `X-Forwarded-Proto` (Vercel's proxy sets both). */
     origin?: string;
@@ -19,11 +20,12 @@ export interface VercelOptions {
     /** Preload planner (`createApp` `preload`): `background` byte budget of idle-time visible prefetch, `lean` (nothing before an interaction); per page when a function. */
     preload?: AppConfig["preload"];
     /**
-     * Brotli/gzip in the function (default true, as the node adapter). Vercel's CDN documents its
+     * zstd / brotli / gzip in the function (default true, as the node adapter; `{ zstd, precompress }` as there — the
+     * function has no client files, so nothing is written). Vercel's CDN documents its
      * automatic compression by MIME allowlist (https://vercel.com/docs/compression), which does not list
      * `text/html`; an encoded response passes through as is.
      */
-    compress?: boolean;
+    compress?: boolean | CompressOptions;
     /** Set when the build has ISR pages: their prerender functions get the page path as `__rivet_path`. */
     isr?: unknown;
 }

package/adapters/vercel.js

@@ -30,7 +30,7 @@ export function create(entry, build, options = {}) {
         trustProxy: 1,
         // A function instance has no idle phase worth shrinking the heap for.
         idleMemory: false,
-        ...(options.compress === false ? { compress: false } : {}),
+        ...(options.compress !== undefined ? { compress: options.compress } : {}),
         ...(options.origin ? { origin: options.origin } : {}),
         ...(options.headers ? { headers: options.headers } : {}),
         ...(options.onError ? { onError: options.onError } : {}),

package/build/codegen.d.ts

@@ -66,6 +66,19 @@ export interface CodegenOptions {
      * they do not make a page resumable: inert pages ship zero JS). Default: `false` in `static` mode.
      */
     clientRouter?: boolean;
+    /**
+     * Document routes (routes-relative page files; `build/reach.ts`): their browser graph reaches a server-only module, so
+     * links to them load documents — rows of the client's match table are `_endpoint` (no interception, data request or
+     * chunk prefetch) and document prefetch takes them. Absent / empty: output unchanged.
+     */
+    documents?: readonly string[];
+    /**
+     * `rivetRouter({ resume: { model: "derived" } })` (M2 R5, server / static modes): `app.tsx` default-exports `Root`, the
+     * page's independent root boundary — props = the route payload as data (`s`), from which the browser's adopt run
+     * rebuilds the router (browser history) and the first load of each level (`revived`, no data request); the server entry
+     * renders `<Root s={…} />`. Absent: output unchanged.
+     */
+    derived?: boolean;
 }
 export interface Generated {
     /** File name (relative to outDir) → contents. */