@pylonsync/functions 0.22.47 → 0.22.58

package/src/ssr-offline-shell.test.ts

@@ -0,0 +1,253 @@
+// Offline apps (`buildManifest({ offline })`), render side:
+//
+//   - A render the service worker asked for (`x-pylon-offline-shell: 1`) is
+//     marked keepable only when its HTML is the same for every signed-in
+//     user, and then its hydration data carries the signed-in bit and no
+//     identity. A page that reads props.auth, serverData, headers or cookies
+//     is refused.
+//   - Every page of an offline app gets the install tags and tells the
+//     client to register the worker.
+//   - The files the worker precaches for a route are exactly the files the
+//     route's HTML loads (Plan 012 step 2).
+//
+// ssr-runtime.ts pulls in runtime.ts (the bun runner entrypoint, which runs
+// main() on import), so each render runs in a child process, like
+// ssr-page-host.test.ts.
+
+import { expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { offlineWorkerConfig } from "./ssr-offline";
+import { routeAssetUrls } from "./ssr-route-assets";
+
+const SSR_RUNTIME = join(import.meta.dir, "ssr-runtime.ts");
+const PKG_NODE_MODULES = join(import.meta.dir, "..", "node_modules");
+
+interface Frame {
+  type: string;
+  headers?: Record<string, string>;
+  data?: string;
+}
+
+const BUNDLE_MANIFEST = {
+  build_id: "b1",
+  outdir: ".pylon/client-build",
+  public_prefix: "/_pylon/build/",
+  polyfills: "polyfills-aaaa1111.js",
+  routes: {
+    "app/page": {
+      file: "client-entry-app__page-bbbb2222.js",
+      imports: ["chunks/chunk-cccc3333.js", "chunks/chunk-dddd4444.js"],
+      css: ["styles-eeee5555.css"],
+      path: "/",
+    },
+  },
+  fonts: {
+    faces: [],
+    variables: [],
+    preload: ["fonts/inter-ffff6666.woff2"],
+  },
+  offline: {
+    name: "Field Sales",
+    shortName: "Sales",
+    themeColor: "#0b2545",
+    icons: [
+      { src: "/icons/192.png", sizes: "192x192", type: "image/png" },
+      { src: "/icons/512.png", sizes: "512x512", type: "image/png" },
+    ],
+    startUrl: "/",
+    routes: ["/"],
+    version: "v1",
+    builtAt: "2026-10-22T12:00:00.000Z",
+  },
+};
+
+function makeApp(pageBody: string, manifest: object = BUNDLE_MANIFEST): string {
+  const dir = mkdtempSync(join(tmpdir(), "pylon-offline-shell-"));
+  mkdirSync(join(dir, "app"), { recursive: true });
+  mkdirSync(join(dir, ".pylon", "client-build"), { recursive: true });
+  symlinkSync(PKG_NODE_MODULES, join(dir, "node_modules"), "dir");
+  writeFileSync(
+    join(dir, "app", "layout.tsx"),
+    `export default function Layout({ children }: any) {
+  return <html><head><title>t</title></head><body>{children}</body></html>;
+}
+`,
+  );
+  writeFileSync(
+    join(dir, "app", "page.tsx"),
+    `export default function Page(props: any) {
+${pageBody}
+}
+`,
+  );
+  writeFileSync(join(dir, ".pylon", "client-build", "styles-eeee5555.css"), "p{color:red}");
+  writeFileSync(
+    join(dir, ".pylon", "client-build", "manifest.json"),
+    JSON.stringify(manifest),
+  );
+  return dir;
+}
+
+const SIGNED_IN = {
+  user_id: "u_ana",
+  is_admin: false,
+  tenant_id: "t_veritas",
+  roles: ["rep"],
+};
+
+async function render(
+  dir: string,
+  opts: { shell?: boolean; auth?: object; env?: Record<string, string> } = {},
+): Promise<{ start: Frame | undefined; html: string; data: any }> {
+  const headers: Record<string, string> = { host: "app.example" };
+  if (opts.shell) headers["x-pylon-offline-shell"] = "1";
+  const auth = opts.auth ?? SIGNED_IN;
+  const msg = {
+    type: "render_route",
+    call_id: "c1",
+    component: "app/page",
+    layouts: ["app/layout"],
+    route_path: "/",
+    url: "/",
+    host: "app.example",
+    params: {},
+    search_params: {},
+    headers,
+    cookies: { sid: "secret-session" },
+    auth,
+    session_present: !!(auth as any).user_id,
+  };
+  const probe = `
+import { handleRenderRoute } from ${JSON.stringify(SSR_RUNTIME)};
+const frames = [];
+await handleRenderRoute(${JSON.stringify(msg)}, (m) => frames.push(m));
+console.error("FRAMES " + JSON.stringify(frames));
+setTimeout(() => process.exit(0), 50);
+`;
+  const probePath = join(dir, `probe-${Math.random().toString(36).slice(2)}.ts`);
+  writeFileSync(probePath, probe);
+  const proc = Bun.spawn(["bun", "run", probePath], {
+    cwd: dir,
+    env: { ...process.env, PYLON_DEV_MODE: "0", ...(opts.env ?? {}) },
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [out, err] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const code = await proc.exited;
+  const line = err.split("\n").find((l) => l.includes("FRAMES "));
+  if (code !== 0 || !line) {
+    throw new Error(`probe failed (exit ${code})\nstdout: ${out}\nstderr: ${err}`);
+  }
+  const frames = JSON.parse(line.slice(line.indexOf("FRAMES ") + 7)) as Frame[];
+  const html = frames
+    .filter((f) => f.type === "render_chunk")
+    .map((f) => Buffer.from(f.data!, "base64").toString("utf8"))
+    .join("");
+  const match = html.match(/<script id="__PYLON_DATA__"[^>]*>([\s\S]*?)<\/script>/);
+  return {
+    start: frames.find((f) => f.type === "response_start"),
+    html,
+    data: match ? JSON.parse(match[1]) : null,
+  };
+}
+
+const SESSION_ONLY_PAGE = `return <p>{props.session.exists ? "signed in" : "signed out"}</p>;`;
+
+test("a shell request for a page that reads only the signed-in bit is kept, without identity", async () => {
+  const dir = makeApp(SESSION_ONLY_PAGE);
+  const { start, html, data } = await render(dir, { shell: true });
+  expect(start?.headers?.["x-pylon-offline-shell"]).toBe("1");
+  expect(html).toContain("signed in");
+  expect(data.props.auth).toEqual({ signedIn: true });
+  expect(data.props.session).toEqual({ exists: true });
+  expect(html).not.toContain("u_ana");
+  expect(html).not.toContain("t_veritas");
+  expect(html).not.toContain("secret-session");
+});
+
+test("a page that reads props.auth is refused, with the reason", async () => {
+  const dir = makeApp(`return <p>{props.auth.userId ?? "anon"}</p>;`);
+  const { start } = await render(dir, { shell: true });
+  expect(start?.headers?.["x-pylon-offline-shell"]).toBe("refused; the page read props.auth");
+});
+
+test("a page that reads serverData is refused", async () => {
+  const dir = makeApp(`props.serverData.list("Lead"); return <p>x</p>;`);
+  const { start } = await render(dir, { shell: true });
+  expect(start?.headers?.["x-pylon-offline-shell"]).toBe("refused; the page read serverData");
+});
+
+test("a page that reads cookies is refused", async () => {
+  const dir = makeApp(`return <p>{String(props.cookies.theme)}</p>;`);
+  const { start } = await render(dir, { shell: true });
+  expect(start?.headers?.["x-pylon-offline-shell"]).toBe(
+    "refused; the page read request headers or cookies",
+  );
+});
+
+test("an ordinary request carries no shell verdict and keeps its real auth", async () => {
+  const dir = makeApp(SESSION_ONLY_PAGE);
+  const { start, data } = await render(dir);
+  expect(start?.headers?.["x-pylon-offline-shell"]).toBeUndefined();
+  expect(data.props.auth.user_id).toBe("u_ana");
+});
+
+test("every page of an offline app gets the install tags and the register flag", async () => {
+  const dir = makeApp(SESSION_ONLY_PAGE);
+  const { html, data } = await render(dir);
+  expect(html).toContain('<link rel="manifest" href="/manifest.webmanifest">');
+  expect(html).toContain('<meta name="theme-color" content="#0b2545">');
+  expect(html).toContain('<meta name="apple-mobile-web-app-title" content="Sales">');
+  expect(html).toContain('<link rel="apple-touch-icon" href="/icons/512.png">');
+  expect(data.offline).toEqual({
+    dev: false,
+    version: "v1",
+    builtAt: "2026-10-22T12:00:00.000Z",
+  });
+
+  const dev = await render(dir, { env: { PYLON_DEV_MODE: "1" } });
+  expect(dev.data.offline.dev).toBe(true);
+});
+
+test("an app without offline gets neither", async () => {
+  const { offline: _o, ...plain } = BUNDLE_MANIFEST;
+  const dir = makeApp(SESSION_ONLY_PAGE, plain);
+  const { html, data } = await render(dir);
+  expect(html).not.toContain('rel="manifest"');
+  expect(data.offline).toBeUndefined();
+});
+
+test("the worker precaches exactly the files the route's HTML loads", async () => {
+  const dir = makeApp(SESSION_ONLY_PAGE);
+  const { html } = await render(dir);
+  // Every build file the page references: stylesheets, modulepreloads,
+  // font preloads, module scripts.
+  const loaded = new Set<string>();
+  for (const m of html.matchAll(/<(?:link|script)\b[^>]*?(?:href|src)="(\/_pylon\/build\/[^"]+)"/g)) {
+    loaded.add(m[1]);
+  }
+  // The stylesheet is a link by default; record it whether linked or inlined.
+  for (const m of html.matchAll(/data-pylon-css="([^"]+)"/g)) loaded.add(`/_pylon/build/${m[1]}`);
+  const listed = routeAssetUrls(BUNDLE_MANIFEST, "app/page");
+  expect(new Set(listed)).toEqual(loaded);
+  expect(loaded.size).toBe(6);
+
+  const { config } = await offlineWorkerConfig(BUNDLE_MANIFEST, {
+    name: "Field Sales",
+    startUrl: "/",
+    display: "standalone",
+    routes: ["/"],
+    icons: BUNDLE_MANIFEST.offline.icons,
+  });
+  for (const url of loaded) expect(config.precache).toContain(url);
+  expect(config.precache).toContain("/_pylon/build/manifest.json");
+  expect(config.precache).toContain("/manifest.webmanifest");
+  expect(config.precache).toContain("/icons/512.png");
+  expect(config.shells).toEqual(["/"]);
+});

package/src/ssr-offline.ts

@@ -0,0 +1,311 @@
+// Build-time and render-time pieces of `buildManifest({ offline })`.
+//
+//   - `readManifestOffline`: the `offline` block of pylon.manifest.json.
+//   - `buildOfflineWorker`: computes the service worker config for one client
+//     build (the precache list comes from `routeAssetUrls`, the same list the
+//     SSR render emits tags for) and writes `pylon-sw.js` into the build,
+//     with `pylon-version.json` beside it (served at `/_pylon/version`).
+//   - `offlineHeadTags`: the install tags every page's `<head>` gets.
+//
+// The worker itself is offline-sw.ts. The Rust host serves
+// `/manifest.webmanifest`, `/pylon-sw.js` and `/_pylon/version`
+// (crates/runtime/src/frontend/offline.rs).
+
+import { renderServiceWorker, type ServiceWorkerConfig } from "./offline-sw";
+import { matchRoute } from "./ssr-route-match";
+import { routeAssetUrls, type RouteAssetManifest } from "./ssr-route-assets";
+
+/** `buildManifest({ offline })` as the SDK writes it to pylon.manifest.json. */
+export interface ManifestOfflineInput {
+  name: string;
+  shortName?: string;
+  description?: string;
+  icons?: Array<{ src: string; sizes: string; type?: string; purpose?: string }>;
+  themeColor?: string;
+  backgroundColor?: string;
+  startUrl: string;
+  display: string;
+  routes: string[];
+}
+
+/** What the bundle manifest keeps for the render and the client runtime. */
+export interface BundleOffline {
+  name: string;
+  shortName?: string;
+  themeColor?: string;
+  icons?: Array<{ src: string; sizes: string; type?: string; purpose?: string }>;
+  startUrl: string;
+  routes: string[];
+  /** The service worker's version (its cache names carry it). */
+  version: string;
+  /** When this build was made (ISO 8601). Not part of `version`: two
+   *  machines that build the same app get the same version. */
+  builtAt: string;
+}
+
+/** `pylon-version.json` in the client build, served at `/_pylon/version`.
+ *  `useAppUpdate` in @pylonsync/react polls it. */
+export interface BuildVersionFile {
+  version: string;
+  builtAt: string;
+  /** Hash of what a home-screen app reads only when it is added (see
+   *  `installIdentity`). */
+  install: string;
+}
+
+/** The file the runtime serves at `/_pylon/version`. */
+export const VERSION_FILE = "pylon-version.json";
+
+/** How long a navigation to an offline route waits for the network before
+ *  the worker shows the kept page. Long enough for a slow but working
+ *  connection to win; short enough that a dead one does not leave a blank
+ *  screen. */
+export const NAVIGATION_TIMEOUT_MS = 3000;
+
+/** The `offline` block of `<cwd>/pylon.manifest.json`, or null. */
+export function readManifestOffline(
+  fs: any,
+  path: any,
+  cwd: string,
+  manifestPath: string = path.join(cwd, "pylon.manifest.json"),
+): ManifestOfflineInput | null {
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    const m = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    const o = m?.offline;
+    if (!o || typeof o.name !== "string") return null;
+    return {
+      ...o,
+      startUrl: typeof o.startUrl === "string" ? o.startUrl : "/",
+      display: typeof o.display === "string" ? o.display : "standalone",
+      routes: Array.isArray(o.routes) ? o.routes : [],
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Every route pattern in `routes` that names a page in this build, with
+ *  the page's component. A pattern with no page is reported, not dropped
+ *  silently. */
+export function resolveOfflineRoutes(
+  manifest: RouteAssetManifest,
+  routes: string[],
+): { matched: Array<{ pattern: string; component: string }>; unknown: string[] } {
+  const matched: Array<{ pattern: string; component: string }> = [];
+  const unknown: string[] = [];
+  for (const pattern of routes) {
+    const component = Object.keys(manifest.routes).find(
+      (c) => manifest.routes[c]?.path === pattern,
+    );
+    if (component) {
+      matched.push({ pattern, component });
+      continue;
+    }
+    // A concrete path (`/leads/today`) served by a dynamic page.
+    const m = matchRoute(manifest as any, pattern);
+    if (m) matched.push({ pattern, component: m.component });
+    else unknown.push(pattern);
+  }
+  return { matched, unknown };
+}
+
+/** True for a pattern with a dynamic segment: one shell cannot serve it. */
+export function isDynamicPattern(pattern: string): boolean {
+  return /\[[^\]]+\]/.test(pattern);
+}
+
+/**
+ * Hash of what iOS reads from the web app manifest and the head tags only
+ * when the app is added to the home screen: the name, the short name, the
+ * display mode, the start URL and the icons (with the bytes of each icon
+ * file in `public/`). When it changes, an installed app keeps the old
+ * values until it is removed and added again.
+ *
+ * The manifest is the one the runtime serves: `public/manifest.webmanifest`,
+ * then `<appDir>/manifest.webmanifest`, else the `offline` config (see
+ * `web_manifest_source` in crates/runtime/src/frontend/offline.rs).
+ */
+export async function installIdentity(
+  fs: any,
+  path: any,
+  cwd: string,
+  appDirRel: string,
+  offline: ManifestOfflineInput,
+): Promise<string> {
+  let served: any = null;
+  for (const candidate of [
+    path.join(cwd, "public", "manifest.webmanifest"),
+    path.join(cwd, appDirRel, "manifest.webmanifest"),
+  ]) {
+    if (!fs.existsSync(candidate)) continue;
+    try {
+      served = JSON.parse(fs.readFileSync(candidate, "utf8"));
+    } catch {
+      served = { unreadable: fs.readFileSync(candidate, "utf8") };
+    }
+    break;
+  }
+  const { createHash } = await import("node:crypto");
+  const iconContent = (src: unknown): string | null => {
+    if (typeof src !== "string" || !src.startsWith("/") || src.startsWith("//")) return null;
+    const file = path.join(cwd, "public", src.split(/[?#]/)[0]);
+    if (!fs.existsSync(file)) return null;
+    return createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+  };
+  const icons = (list: unknown) =>
+    (Array.isArray(list) ? list : []).map((icon: any) => ({
+      src: icon?.src ?? null,
+      sizes: icon?.sizes ?? null,
+      purpose: icon?.purpose ?? null,
+      content: iconContent(icon?.src),
+    }));
+  const identity = served
+    ? {
+        name: served.name ?? null,
+        shortName: served.short_name ?? null,
+        display: served.display ?? null,
+        startUrl: served.start_url ?? null,
+        icons: icons(served.icons),
+        unreadable: served.unreadable ?? null,
+      }
+    : {
+        name: offline.name,
+        shortName: offline.shortName ?? offline.name,
+        display: offline.display,
+        startUrl: offline.startUrl,
+        icons: icons(offline.icons),
+      };
+  // The head tags come from the `offline` config even when the app ships its
+  // own manifest file.
+  const touch = touchIcon(offline.icons);
+  const head = {
+    title: offline.shortName ?? offline.name,
+    touchIcon: touch,
+    touchIconContent: iconContent(touch),
+  };
+  return createHash("sha256")
+    .update(JSON.stringify({ identity, head }))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+/** The service worker config for this build. `install` is
+ *  `installIdentity`; it is part of the version, so a manifest change
+ *  installs a new worker (which precaches the new manifest). */
+export async function offlineWorkerConfig(
+  manifest: RouteAssetManifest,
+  offline: ManifestOfflineInput,
+  install: string = "",
+): Promise<{ config: ServiceWorkerConfig; unknownRoutes: string[] }> {
+  const prefix = manifest.public_prefix || "/_pylon/build/";
+  const { matched, unknown } = resolveOfflineRoutes(manifest, offline.routes);
+  const precache = new Set<string>();
+  // The client runtime loads the bundle manifest before it can render a
+  // route; it is always same-origin.
+  precache.add("/_pylon/build/manifest.json");
+  for (const { component } of matched) {
+    for (const url of routeAssetUrls(manifest, component)) precache.add(url);
+  }
+  precache.add("/manifest.webmanifest");
+  for (const icon of offline.icons ?? []) precache.add(icon.src);
+  const startPath = offline.startUrl.split(/[?#]/)[0] || "/";
+  const shells = matched
+    .map((m) => m.pattern)
+    .filter((p) => !isDynamicPattern(p));
+  if (!shells.includes(startPath)) shells.unshift(startPath);
+  const base = {
+    buildPrefix: prefix,
+    precache: Array.from(precache).sort(),
+    shells,
+    routes: offline.routes,
+    startPath,
+    navigationTimeoutMs: NAVIGATION_TIMEOUT_MS,
+  };
+  // Content-derived: the build files are content-hashed, so the same build
+  // gives the same version on every machine and every boot. A version that
+  // changed per boot would reinstall the worker on every deploy machine.
+  const { createHash } = await import("node:crypto");
+  const version = createHash("sha256")
+    .update(JSON.stringify({ ...base, install }))
+    .digest("hex")
+    .slice(0, 16);
+  return { config: { version, ...base }, unknownRoutes: unknown };
+}
+
+/** Write `pylon-sw.js` and `pylon-version.json` into `outdir` and return
+ *  the bundle manifest's `offline` block. `cwd` and `appDirRel` locate the
+ *  app's own manifest file and its icons. */
+export async function buildOfflineWorker(
+  fs: any,
+  path: any,
+  outdir: string,
+  manifest: RouteAssetManifest,
+  offline: ManifestOfflineInput,
+  cwd: string,
+  appDirRel: string,
+): Promise<BundleOffline> {
+  const install = await installIdentity(fs, path, cwd, appDirRel, offline);
+  const { config, unknownRoutes } = await offlineWorkerConfig(manifest, offline, install);
+  if (unknownRoutes.length > 0) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[pylon offline] offline.routes names no page for: ${unknownRoutes.join(", ")}. ` +
+        "Those paths will not open offline.",
+    );
+  }
+  fs.writeFileSync(path.join(outdir, "pylon-sw.js"), renderServiceWorker(config), "utf8");
+  const versionFile: BuildVersionFile = {
+    version: config.version,
+    builtAt: new Date().toISOString(),
+    install,
+  };
+  fs.writeFileSync(path.join(outdir, VERSION_FILE), JSON.stringify(versionFile), "utf8");
+  return {
+    name: offline.name,
+    ...(offline.shortName ? { shortName: offline.shortName } : {}),
+    ...(offline.themeColor ? { themeColor: offline.themeColor } : {}),
+    ...(offline.icons && offline.icons.length > 0 ? { icons: offline.icons } : {}),
+    startUrl: offline.startUrl,
+    routes: offline.routes,
+    version: config.version,
+    builtAt: versionFile.builtAt,
+  };
+}
+
+function attr(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/** The largest square icon, for `apple-touch-icon` (iOS does not read the
+ *  web app manifest's icons). */
+function touchIcon(icons: BundleOffline["icons"]): string | null {
+  let best: { src: string; size: number } | null = null;
+  for (const icon of icons ?? []) {
+    if (icon.purpose && !icon.purpose.split(" ").includes("any")) continue;
+    for (const s of icon.sizes.split(" ")) {
+      const m = s.match(/^(\d+)x(\d+)$/);
+      const size = m && m[1] === m[2] ? Number(m[1]) : 0;
+      if (size > 0 && (!best || size > best.size)) best = { src: icon.src, size };
+    }
+  }
+  return best ? best.src : null;
+}
+
+/** `<head>` tags that make the app installable. */
+export function offlineHeadTags(offline: BundleOffline): string {
+  let tags = `<link rel="manifest" href="/manifest.webmanifest">`;
+  if (offline.themeColor) {
+    tags += `<meta name="theme-color" content="${attr(offline.themeColor)}">`;
+  }
+  tags += `<meta name="mobile-web-app-capable" content="yes">`;
+  tags += `<meta name="apple-mobile-web-app-capable" content="yes">`;
+  tags += `<meta name="apple-mobile-web-app-title" content="${attr(offline.shortName ?? offline.name)}">`;
+  const icon = touchIcon(offline.icons);
+  if (icon) tags += `<link rel="apple-touch-icon" href="${attr(icon)}">`;
+  return tags;
+}

package/src/ssr-precompress.test.ts

@@ -0,0 +1,49 @@
+// Build-time brotli and gzip copies of the client build's text files.
+
+import { afterEach, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import zlib from "node:zlib";
+import { MIN_COMPRESS_BYTES, precompressBuild } from "./ssr-precompress";
+
+let dir = "";
+afterEach(() => {
+  if (dir) fs.rmSync(dir, { recursive: true, force: true });
+  dir = "";
+});
+
+const js = "export const rows = [" + Array.from({ length: 400 }, (_, i) => `{id:${i},name:"row ${i}"}`).join(",") + "];\n";
+
+test("writes .br and .gz copies that decompress to the file", () => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), "pylon-precompress-"));
+  fs.mkdirSync(path.join(dir, "chunks"));
+  fs.writeFileSync(path.join(dir, "chunks", "chunk-abcd1234.js"), js);
+  fs.writeFileSync(path.join(dir, "styles-abcd1234.css"), "a{color:red}".repeat(200));
+
+  const result = precompressBuild(fs, path, zlib, dir);
+  expect(result.files).toBe(2);
+  expect(result.brotliBytes).toBeLessThan(result.bytes);
+
+  const file = path.join(dir, "chunks", "chunk-abcd1234.js");
+  expect(zlib.brotliDecompressSync(fs.readFileSync(file + ".br")).toString()).toBe(js);
+  expect(zlib.gunzipSync(fs.readFileSync(file + ".gz")).toString()).toBe(js);
+  expect(fs.statSync(file + ".br").size).toBeLessThan(js.length / 4);
+});
+
+test("skips small files, binary formats and copies that would not be smaller", () => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), "pylon-precompress-"));
+  fs.writeFileSync(path.join(dir, "tiny-abcd1234.js"), "x".repeat(MIN_COMPRESS_BYTES - 1));
+  fs.writeFileSync(path.join(dir, "font-abcd1234.woff2"), js);
+  // Random bytes do not compress.
+  const noise = Buffer.from(Array.from({ length: 4096 }, () => Math.floor(Math.random() * 256)));
+  fs.writeFileSync(path.join(dir, "noise-abcd1234.js"), noise);
+
+  const result = precompressBuild(fs, path, zlib, dir);
+  expect(result.files).toBe(0);
+  expect(fs.readdirSync(dir).sort()).toEqual([
+    "font-abcd1234.woff2",
+    "noise-abcd1234.js",
+    "tiny-abcd1234.js",
+  ]);
+});

package/src/ssr-precompress.ts

@@ -0,0 +1,67 @@
+// Brotli and gzip copies of the client build's text files, written at build
+// time. The runtime sends `<file>.br` or `<file>.gz` with Content-Encoding
+// when the browser accepts it (serve_pylon_client_bundle in
+// crates/runtime/src/frontend.rs), so no request pays to compress.
+
+/** Extensions worth compressing. Images and fonts are compressed already. */
+const COMPRESSIBLE = new Set([".js", ".mjs", ".css", ".json", ".map", ".svg", ".wasm", ".txt", ".html"]);
+
+/** Smaller files gain less than the bytes of the encoding headers. */
+export const MIN_COMPRESS_BYTES = 1024;
+
+export interface PrecompressResult {
+  /** Files that got at least one compressed copy. */
+  files: number;
+  /** Total bytes of those files, and of their brotli copies. */
+  bytes: number;
+  brotliBytes: number;
+}
+
+/**
+ * Write `<file>.br` (brotli, quality 11) and `<file>.gz` (gzip, level 9)
+ * next to every compressible file in `outdir` of at least
+ * `MIN_COMPRESS_BYTES`. A copy that is not smaller than the file is not
+ * written. Copies left by an earlier build are replaced.
+ */
+export function precompressBuild(fs: any, path: any, zlib: any, outdir: string): PrecompressResult {
+  const result: PrecompressResult = { files: 0, bytes: 0, brotliBytes: 0 };
+  const walk = (dir: string) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (!entry.isFile() || !COMPRESSIBLE.has(path.extname(entry.name))) continue;
+      const data: Uint8Array = fs.readFileSync(full);
+      if (data.length < MIN_COMPRESS_BYTES) continue;
+      const br: Uint8Array = zlib.brotliCompressSync(data, {
+        params: {
+          [zlib.constants.BROTLI_PARAM_QUALITY]: 11,
+          [zlib.constants.BROTLI_PARAM_SIZE_HINT]: data.length,
+        },
+      });
+      const gz: Uint8Array = zlib.gzipSync(data, { level: 9 });
+      let wrote = false;
+      for (const [ext, copy] of [
+        [".br", br],
+        [".gz", gz],
+      ] as const) {
+        const target = full + ext;
+        if (copy.length < data.length) {
+          fs.writeFileSync(target, copy);
+          wrote = true;
+        } else if (fs.existsSync(target)) {
+          fs.unlinkSync(target);
+        }
+      }
+      if (wrote) {
+        result.files++;
+        result.bytes += data.length;
+        result.brotliBytes += Math.min(br.length, data.length);
+      }
+    }
+  };
+  walk(outdir);
+  return result;
+}