arcway 0.1.19 → 0.1.21

package/client/dynamic.js

@@ -0,0 +1,48 @@
+import { createElement, lazy, Suspense } from 'react';
+
+const isServer = typeof window === 'undefined';
+
+// `arcway/dynamic` — component-level lazy loading with an SSR escape hatch.
+//
+// Returns a React component. Default behavior mirrors `React.lazy` wrapped in
+// a local `<Suspense>` so callers don't have to place their own boundary:
+//
+//   const Heavy = dynamic(() => import('./heavy.js'), { loading: Skeleton });
+//
+// `ssr: false` disables server rendering of the lazy child: under Node the
+// component short-circuits to the loading fallback (or null), and the loader
+// is never invoked server-side. The chunk is therefore absent from the SSR
+// payload and is fetched on the client on first mount.
+export default function dynamic(loader, opts = {}) {
+  const { ssr = true, loading } = opts;
+  const Fallback = loading ?? null;
+  const fallbackElement = Fallback ? createElement(Fallback) : null;
+
+  if (!ssr) {
+    // On the server we want zero loader activity and zero Suspense churn —
+    // just the fallback (or empty). On the client we still lazy-load so the
+    // chunk stays out of the initial payload; Suspense wraps it locally.
+    if (isServer) {
+      const ServerStub = () => fallbackElement;
+      ServerStub.displayName = 'DynamicServerStub';
+      return ServerStub;
+    }
+    const Lazy = lazy(loader);
+    const ClientOnly = (props) =>
+      createElement(Suspense, { fallback: fallbackElement }, createElement(Lazy, props));
+    ClientOnly.displayName = 'DynamicClientOnly';
+    return ClientOnly;
+  }
+
+  // Default SSR path: React.lazy + local Suspense. Under streaming SSR
+  // (renderToPipeableStream) the fallback is emitted first and the resolved
+  // chunk streams in when the loader promise settles. Under sync
+  // renderToString() the fallback is the final output, which is the expected
+  // behavior — pages needing a single-pass SSR render should use `ssr: false`
+  // or pre-import the module.
+  const Lazy = lazy(loader);
+  const Dynamic = (props) =>
+    createElement(Suspense, { fallback: fallbackElement }, createElement(Lazy, props));
+  Dynamic.displayName = 'Dynamic';
+  return Dynamic;
+}

package/client/router.js

@@ -103,7 +103,16 @@ function Router({
     return () => window.removeEventListener('manifest-update', onManifestUpdate);
   }, []);
 
-  const applyLoaded = useCallback((loaded, newPath) => {
+  // `bumpQuery` controls whether `queryVersion` is incremented atomically
+  // with the page-state updates. It lives inside the same `startTransition`
+  // so React commits the new `pathname` and the re-read of
+  // `window.location.search` (triggered by `queryVersion`) in one go. Keeping
+  // the bump outside the transition raced at default priority and produced
+  // an interim render where `pathname` was stale but `useSearchParams` had
+  // already moved to the new query string — see the
+  // `query-version-outside-navigation-transition` bug report for the
+  // downstream data-corruption pattern that unlocked.
+  const applyLoaded = useCallback((loaded, newPath, bumpQuery = false) => {
     startTransition(() => {
       setPathname(newPath);
       setPageState({
@@ -113,6 +122,7 @@ function Router({
         params: loaded.params,
       });
       setIsNavigating(false);
+      if (bumpQuery) setQueryVersion((v) => v + 1);
     });
   }, []);
 
@@ -179,8 +189,7 @@ function Router({
           return;
         }
 
-        applyLoaded(loaded, pathOnly);
-        if (search !== currentSearch) setQueryVersion((v) => v + 1);
+        applyLoaded(loaded, pathOnly, search !== currentSearch);
 
         if (scroll) {
           window.scrollTo(0, 0);
@@ -216,8 +225,7 @@ function Router({
       try {
         const loaded = await loadPage(manifest, newPath);
         if (loaded) {
-          applyLoaded(loaded, newPath);
-          setQueryVersion((v) => v + 1);
+          applyLoaded(loaded, newPath, true);
         } else {
           window.location.reload();
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcway",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "A convention-based framework for building modular monoliths with strict domain boundaries.",
   "license": "MIT",
   "type": "module",
@@ -12,7 +12,7 @@
     "README.md"
   ],
   "bin": {
-    "arcway": "./server/bin/solo.js"
+    "arcway": "server/bin/solo.js"
   },
   "imports": {
     "#server/*": "./server/*",
@@ -23,6 +23,7 @@
     "./internals": "./server/internals.js",
     "./lib/vault": "./server/lib/vault/index.js",
     "./lib/client": "./client/index.js",
+    "./dynamic": "./client/dynamic.js",
     "./ui": "./client/ui/index.js",
     "./middlewares": "./server/middlewares/index.js",
     "./ui/theme.css": "./client/ui/theme.css",
@@ -78,6 +79,7 @@
     "lucide-react": "^0.564.0",
     "mailparser": "^3.9.3",
     "nanoid": "^5.1.6",
+    "negotiator": "^1.0.0",
     "nodemailer": "^8.0.1",
     "p-limit": "^7.3.0",
     "pg": "^8.13.0",

package/server/pages/build-client.js

@@ -13,6 +13,12 @@ import {
   restoreMultiFileCache,
   storeMultiFileCache,
 } from './build-cache.js';
+import { computeEntryChunks } from './chunk-graph.js';
+
+// Bump when the shape produced by `extractMetadata` / the serialized cache
+// payload changes in a way that would make an old cache entry decode into a
+// broken manifest. Prevents a stale v1 cache from ever satisfying a v2 build.
+const METADATA_VERSION = 3;
 
 // Build a deterministic plan of the hydration entries that will be written
 // into the staging dir. Computed up-front so we can derive a cache key
@@ -93,6 +99,7 @@ function computeClientCoarseKey({
   return sha256(
     JSON.stringify({
       esbuildVersion: ESBUILD_VERSION,
+      metadataVersion: METADATA_VERSION,
       target: target ?? '',
       minify: !!minify,
       devMode: !!devMode,
@@ -112,7 +119,8 @@ function serializeMetadata(meta) {
     navBundles: [...meta.navBundles.entries()],
     layoutNavBundles: [...meta.layoutNavBundles.entries()],
     loadingNavBundles: [...meta.loadingNavBundles.entries()],
-    sharedChunks: meta.sharedChunks,
+    entryChunks: [...meta.entryChunks.entries()],
+    entryCssChunks: [...meta.entryCssChunks.entries()],
   };
 }
 
@@ -122,7 +130,8 @@ function deserializeMetadata(raw) {
     navBundles: new Map(raw.navBundles),
     layoutNavBundles: new Map(raw.layoutNavBundles),
     loadingNavBundles: new Map(raw.loadingNavBundles),
-    sharedChunks: raw.sharedChunks,
+    entryChunks: new Map(raw.entryChunks),
+    entryCssChunks: new Map(raw.entryCssChunks),
   };
 }
 
@@ -205,10 +214,18 @@ async function createClientBuildContext(
   );
 
   let disposed = false;
+  // Files scheduled for deletion at the end of the NEXT rebuild. The
+  // one-generation hold gives in-flight requests from the previous HTML a
+  // chance to still complete against the old hashed chunk before we unlink
+  // it. See the commentary on `collectStaleOutputs` for why this is
+  // necessary in dev but not in prod.
+  let pendingStale = new Set();
 
   async function rebuild() {
     const result = await ctx.rebuild();
     const metadata = extractMetadata(result, plan, outDir);
+    await unlinkAll(pendingStale);
+    pendingStale = await collectStaleOutputs(result.metafile, clientDir);
     return { ...metadata, metafile: result.metafile };
   }
 
@@ -222,6 +239,62 @@ async function createClientBuildContext(
   return { rebuild, dispose };
 }
 
+async function unlinkAll(absPaths) {
+  await Promise.all(
+    [...absPaths].map((p) =>
+      fs.unlink(p).catch((err) => {
+        // Missing files are expected when a subsequent rebuild reshapes the
+        // output set further before our GC pass runs; anything else is
+        // logged implicitly via the returned promise (non-fatal).
+        if (err?.code !== 'ENOENT') throw err;
+      }),
+    ),
+  );
+}
+
+// Incremental esbuild builds reuse the same `outdir` across rebuilds (the
+// context requires a stable outdir), so each new hashed chunk lands alongside
+// its predecessor and `chunks/` grows forever. Compute the set of files
+// currently on disk but *not* in the metafile's output set — those are the
+// stale artifacts to GC on the next rebuild.
+//
+// Prod does not need this: `buildPages()` stages into a unique dir and does
+// an atomic rename, so the served clientDir always contains exactly the
+// current build's outputs.
+async function collectStaleOutputs(metafile, clientDir) {
+  const currentOutputs = new Set(
+    Object.keys(metafile.outputs ?? {}).map((p) => path.resolve(p)),
+  );
+  // Scope the scan to directories esbuild actually writes to. This keeps
+  // sibling artifacts owned by other build steps (e.g. the HMR runtime under
+  // `client/hmr/`) out of the GC set, since they will never appear in the
+  // client esbuild metafile.
+  const dirs = new Set();
+  for (const outPath of currentOutputs) dirs.add(path.dirname(outPath));
+
+  const stale = new Set();
+  for (const dir of dirs) {
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      if (err?.code === 'ENOENT') continue;
+      throw err;
+    }
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      const abs = path.join(dir, entry.name);
+      if (!currentOutputs.has(abs)) stale.add(abs);
+    }
+  }
+  // `clientDir` is passed for future scoping hooks (e.g. whitelisting) but
+  // is intentionally unused today — the dirname set above already bounds the
+  // scan tightly and never escapes clientDir because every metafile output
+  // sits under it.
+  void clientDir;
+  return stale;
+}
+
 async function tryRestoreClientFromCache({ rootDir, clientDir, coarseKey }) {
   const lookup = await lookupMultiFileCache({ rootDir, kind: 'client', coarseKey });
   if (!lookup.hit) return { hit: false, bucket: lookup.bucket };
@@ -346,32 +419,43 @@ function extractMetadata(result, plan, outDir) {
   const navBundles = new Map();
   const layoutNavBundles = new Map();
   const loadingNavBundles = new Map();
-  const sharedChunks = [];
+  // Map<outputKey, pattern> so we can look up which page pattern owns a given
+  // esbuild entry output when we walk the per-entry chunk closure below.
+  const entryKeyToPattern = new Map();
   for (const [outputPath, meta] of Object.entries(result.metafile.outputs)) {
-    const relPath = path.relative(outDir, outputPath).replace(/\\/g, '/');
     if (outputPath.endsWith('.map')) continue;
-    if (relPath.startsWith('client/chunks/')) {
-      sharedChunks.push(relPath);
-      continue;
-    }
-    if (meta.entryPoint) {
-      const absEntry = path.resolve(meta.entryPoint);
-      const pattern =
-        plan.entryToPattern.get(absEntry) ?? plan.entryToNavPattern.get(absEntry);
-      if (plan.entryToPattern.has(absEntry)) {
-        bundles.set(plan.entryToPattern.get(absEntry), relPath);
-      } else if (plan.entryToNavPattern.has(absEntry)) {
-        navBundles.set(plan.entryToNavPattern.get(absEntry), relPath);
-      } else if (plan.entryToLayoutDir.has(absEntry)) {
-        layoutNavBundles.set(plan.entryToLayoutDir.get(absEntry), relPath);
-      } else if (plan.entryToLoadingDir.has(absEntry)) {
-        loadingNavBundles.set(plan.entryToLoadingDir.get(absEntry), relPath);
-      }
-      // pattern variable intentionally unused when none of the maps match
-      void pattern;
+    const relPath = path.relative(outDir, outputPath).replace(/\\/g, '/');
+    if (relPath.startsWith('client/chunks/')) continue;
+    if (!meta.entryPoint) continue;
+    const absEntry = path.resolve(meta.entryPoint);
+    if (plan.entryToPattern.has(absEntry)) {
+      const pattern = plan.entryToPattern.get(absEntry);
+      bundles.set(pattern, relPath);
+      entryKeyToPattern.set(outputPath, pattern);
+    } else if (plan.entryToNavPattern.has(absEntry)) {
+      navBundles.set(plan.entryToNavPattern.get(absEntry), relPath);
+    } else if (plan.entryToLayoutDir.has(absEntry)) {
+      layoutNavBundles.set(plan.entryToLayoutDir.get(absEntry), relPath);
+    } else if (plan.entryToLoadingDir.has(absEntry)) {
+      loadingNavBundles.set(plan.entryToLoadingDir.get(absEntry), relPath);
     }
   }
-  return { bundles, navBundles, layoutNavBundles, loadingNavBundles, sharedChunks };
+  // Per-entry chunk closure keyed by page pattern so the manifest only lists
+  // the chunks a given page actually imports, rather than dumping every chunk
+  // from every entry on every page. Only hydration entries (mapped to a page
+  // pattern) participate — nav/layout/loading bundles are loaded lazily at
+  // navigation time and resolve their own chunks then.
+  const clientDir = path.join(outDir, 'client');
+  const perEntry = computeEntryChunks(result.metafile, clientDir);
+  const entryChunks = new Map();
+  const entryCssChunks = new Map();
+  for (const [entryKey, { js, css }] of perEntry.entries()) {
+    const pattern = entryKeyToPattern.get(entryKey);
+    if (!pattern) continue;
+    entryChunks.set(pattern, js);
+    entryCssChunks.set(pattern, css);
+  }
+  return { bundles, navBundles, layoutNavBundles, loadingNavBundles, entryChunks, entryCssChunks };
 }
 
 function generateHydrationEntry(componentPath, layouts = [], loadings = []) {

package/server/pages/build-context.js

@@ -85,7 +85,7 @@ async function createPagesBuildContext(options) {
     ]);
 
     if (pages.length === 0) {
-      lastResult = { pageCount: 0, outDir, manifest: { entries: [], sharedChunks: [] } };
+      lastResult = { pageCount: 0, outDir, manifest: { entries: [] } };
       return lastResult;
     }
 

package/server/pages/build-manifest.js

@@ -34,6 +34,8 @@ function generateManifest(
     const middlewareServerBundlePaths = middlewareChain
       .map((m) => middlewareServerBundles.get(m.dirPath))
       .filter((p) => p !== void 0);
+    const sharedChunks = clientResult.entryChunks?.get(page.pattern) ?? [];
+    const sharedCssChunks = clientResult.entryCssChunks?.get(page.pattern) ?? [];
     entries.push({
       pattern: page.pattern,
       paramNames: page.paramNames,
@@ -45,11 +47,10 @@ function generateManifest(
       layoutClientBundles: layoutClientBundlePaths,
       loadingClientBundles: loadingClientBundlePaths,
       middlewareServerBundles: middlewareServerBundlePaths,
+      sharedChunks,
+      sharedCssChunks,
     });
   }
-  return {
-    entries,
-    sharedChunks: clientResult.sharedChunks,
-  };
+  return { entries };
 }
 export { generateManifest };

package/server/pages/build.js

@@ -21,6 +21,7 @@ import { generateManifest } from './build-manifest.js';
 import { resolveFonts } from './fonts.js';
 import { buildHmrRuntimeBundle } from './hmr.js';
 import { enforceCacheBudget } from './build-cache.js';
+import { precompressAssets } from './compress.js';
 async function buildPages(options) {
   const { rootDir } = options;
   const pagesDir = options.pagesDir ?? path.join(rootDir, 'pages');
@@ -38,7 +39,7 @@ async function buildPages(options) {
     discoverStyles(pagesDir),
   ]);
   if (pages.length === 0) {
-    return { pageCount: 0, outDir, manifest: { entries: [], sharedChunks: [] } };
+    return { pageCount: 0, outDir, manifest: { entries: [] } };
   }
   // Build into a uniquely-suffixed staging directory and atomically swap into place
   // only after every step succeeds. If the build fails partway through, the previous
@@ -107,6 +108,14 @@ async function buildPages(options) {
       path.join(buildDir, 'pages-manifest.json'),
       JSON.stringify(manifest, null, 2),
     );
+    // Pre-compress client assets before the atomic swap so the swapped-in
+    // directory already contains .br/.gz siblings and the static handler
+    // never sees a window where only the raw file is servable. Dev rebuilds
+    // skip this — brotli-11 is expensive and offers no runtime value under
+    // `npm run dev`, which serves identity anyway.
+    if (!devMode) {
+      await precompressAssets(path.join(buildDir, 'client'));
+    }
     await atomicSwap(outDir, buildDir);
     // Keep the on-disk cache bounded. Fire-and-forget so the build returns
     // immediately; eviction is idempotent across concurrent builds and any

package/server/pages/chunk-graph.js

@@ -0,0 +1,59 @@
+import path from 'node:path';
+
+// Given an esbuild metafile and the directory its outputs were emitted into,
+// compute the transitive closure of `chunks/*` outputs reachable from each
+// entry-point output. Returned paths are `client/…` relative to the page
+// build root so they can be dropped straight into the manifest/SSR script
+// tags without additional rewriting.
+//
+// JS and CSS chunks are kept in separate buckets because SSR renders them
+// with different tag types (`<script type="module">` vs `<link rel="stylesheet">`).
+// Mixing them produces a strict-MIME console error on every page load because
+// browsers refuse to execute `text/css` as a module script.
+function computeEntryChunks(metafile, clientDir) {
+  const outputs = metafile?.outputs ?? {};
+  const resolvedClientDir = path.resolve(clientDir);
+
+  const chunkKeys = new Set();
+  const entryKeys = new Set();
+  for (const [key, meta] of Object.entries(outputs)) {
+    if (key.endsWith('.map')) continue;
+    const abs = path.resolve(key);
+    const rel = path.relative(resolvedClientDir, abs).replace(/\\/g, '/');
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) continue;
+    if (rel.startsWith('chunks/')) {
+      chunkKeys.add(key);
+    } else if (meta?.entryPoint) {
+      entryKeys.add(key);
+    }
+  }
+
+  const result = new Map();
+  for (const entryKey of entryKeys) {
+    const visited = new Set([entryKey]);
+    const queue = [entryKey];
+    const js = [];
+    const css = [];
+    while (queue.length > 0) {
+      const cur = queue.shift();
+      const meta = outputs[cur];
+      if (!meta) continue;
+      for (const imp of meta.imports ?? []) {
+        const target = imp.path;
+        if (!target || visited.has(target)) continue;
+        visited.add(target);
+        queue.push(target);
+        if (chunkKeys.has(target)) {
+          const rel = path.relative(resolvedClientDir, path.resolve(target)).replace(/\\/g, '/');
+          const outRel = `client/${rel}`;
+          if (outRel.endsWith('.css')) css.push(outRel);
+          else js.push(outRel);
+        }
+      }
+    }
+    result.set(entryKey, { js, css });
+  }
+  return result;
+}
+
+export { computeEntryChunks };

package/server/pages/compress.js

@@ -0,0 +1,103 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { brotliCompress, gzip, constants } from 'node:zlib';
+import { promisify } from 'node:util';
+
+const brotliCompressAsync = promisify(brotliCompress);
+const gzipAsync = promisify(gzip);
+
+const DEFAULT_EXTENSIONS = new Set(['.js', '.css', '.map', '.svg', '.json', '.html']);
+const PRECOMPRESSED_SUFFIXES = ['.br', '.gz'];
+const DEFAULT_THRESHOLD = 1024;
+const DEFAULT_CONCURRENCY = 4;
+
+async function precompressAssets(clientDir, opts = {}) {
+  const threshold = opts.threshold ?? DEFAULT_THRESHOLD;
+  const concurrency = Math.max(1, opts.concurrency ?? DEFAULT_CONCURRENCY);
+  const extensions = opts.extensions ? new Set(opts.extensions) : DEFAULT_EXTENSIONS;
+
+  const targets = [];
+  await walk(clientDir, extensions, targets);
+
+  const jobs = [];
+  for (const file of targets) {
+    let stat;
+    try {
+      stat = await fs.stat(file);
+    } catch {
+      continue;
+    }
+    if (stat.size < threshold) continue;
+
+    const mtimeMs = stat.mtimeMs;
+    if (!(await isFresh(file + '.br', mtimeMs))) {
+      jobs.push({ file, outPath: file + '.br', kind: 'br' });
+    }
+    if (!(await isFresh(file + '.gz', mtimeMs))) {
+      jobs.push({ file, outPath: file + '.gz', kind: 'gz' });
+    }
+  }
+
+  let cursor = 0;
+  const runOne = async () => {
+    while (cursor < jobs.length) {
+      const job = jobs[cursor++];
+      await compressOne(job);
+    }
+  };
+  const workerCount = Math.min(concurrency, jobs.length);
+  await Promise.all(Array.from({ length: workerCount }, runOne));
+
+  return { compressed: jobs.length };
+}
+
+async function compressOne({ file, outPath, kind }) {
+  const data = await fs.readFile(file);
+  let encoded;
+  if (kind === 'br') {
+    encoded = await brotliCompressAsync(data, {
+      params: {
+        [constants.BROTLI_PARAM_QUALITY]: constants.BROTLI_MAX_QUALITY,
+        [constants.BROTLI_PARAM_SIZE_HINT]: data.length,
+      },
+    });
+  } else {
+    encoded = await gzipAsync(data, { level: constants.Z_BEST_COMPRESSION });
+  }
+  await fs.writeFile(outPath, encoded);
+  // The artifact naturally picks up a write-time mtime strictly later than
+  // the source mtime, which is exactly what `isFresh` relies on.
+}
+
+async function isFresh(outPath, srcMtimeMs) {
+  try {
+    const stat = await fs.stat(outPath);
+    return stat.mtimeMs >= srcMtimeMs;
+  } catch {
+    return false;
+  }
+}
+
+async function walk(dir, extensions, acc) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await walk(full, extensions, acc);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    // Skip previously emitted compressed artifacts so we never compress a .br
+    // into a .br.br on a subsequent run.
+    if (PRECOMPRESSED_SUFFIXES.some((s) => entry.name.endsWith(s))) continue;
+    const ext = path.extname(entry.name).toLowerCase();
+    if (extensions.has(ext)) acc.push(full);
+  }
+}
+
+export { precompressAssets };

package/server/pages/handler.js

@@ -6,6 +6,7 @@ import { compilePattern, sortBySpecificity, matchPattern } from '../router/route
 import { parseCookies, resolveSession, flattenHeaders } from '../session/helpers.js';
 import {
   buildCssLinkTag,
+  buildRouteCssLinkTags,
   buildScriptTags,
   loadComponent,
   renderErrorPage,
@@ -186,6 +187,8 @@ function compileRoutes(manifest) {
       clientBundle: entry.clientBundle,
       layoutServerBundles: entry.layoutServerBundles ?? [],
       middlewareServerBundles: entry.middlewareServerBundles ?? [],
+      sharedChunks: entry.sharedChunks ?? [],
+      sharedCssChunks: entry.sharedCssChunks ?? [],
     };
   });
   sortBySpecificity(routes);
@@ -269,6 +272,7 @@ export {
   MIME_TYPES,
   buildClientManifestJson,
   buildCssLinkTag,
+  buildRouteCssLinkTags,
   buildScriptTags,
   createPagesHandler,
   matchPageRoute,

package/server/pages/ssr.js

@@ -72,6 +72,11 @@ function buildCssLinkTag(manifest) {
   if (!manifest.cssBundle) return '';
   return `<link rel="stylesheet" href="/static/${manifest.cssBundle}" />`;
 }
+function buildRouteCssLinkTags(route) {
+  const chunks = route?.sharedCssChunks ?? [];
+  if (chunks.length === 0) return '';
+  return chunks.map((c) => `<link rel="stylesheet" href="/static/${c}" />`).join('\n');
+}
 function buildFontPreloadTags(manifest) {
   return manifest.fontPreloadHtml ?? '';
 }
@@ -80,9 +85,13 @@ function buildLiveReloadScript() {
 (function(){var es=new EventSource("/__livereload");es.onmessage=function(e){if(e.data==="reload")window.location.reload()};es.onerror=function(){es.close()}})();
 </script>`;
 }
-function buildScriptTags(route, manifest) {
+function buildScriptTags(route) {
   const tags = [];
-  for (const chunk of manifest.sharedChunks) {
+  for (const chunk of route.sharedChunks ?? []) {
+    // Defense-in-depth: upstream splits JS/CSS into separate manifest fields
+    // so a `.css` should never appear here. Skip any stragglers to guarantee
+    // the browser never sees a `<script type="module" src=".css">` tag.
+    if (chunk.endsWith('.css')) continue;
     tags.push(`<script type="module" src="/static/${chunk}"></script>`);
   }
   tags.push(`<script type="module" src="/static/${route.clientBundle}"></script>`);
@@ -146,8 +155,10 @@ async function renderPage(
       layoutComponents.push(Layout);
     }
   }
-  const scriptTags = buildScriptTags(route, manifest);
-  const cssLinkTag = buildCssLinkTag(manifest);
+  const scriptTags = buildScriptTags(route);
+  const manifestCssTag = buildCssLinkTag(manifest);
+  const routeCssTags = buildRouteCssLinkTags(route);
+  const cssLinkTag = [manifestCssTag, routeCssTags].filter(Boolean).join('\n');
   const fontPreloadTags = buildFontPreloadTags(manifest);
   const envScriptTag = buildEnvScriptTag(collectPublicEnv());
   const hmrTag = devMode ? buildHmrScript() : '';
@@ -267,6 +278,7 @@ export {
   buildCssLinkTag,
   buildFontPreloadTags,
   buildHtmlShell,
+  buildRouteCssLinkTags,
   buildScriptTags,
   loadComponent,
   renderErrorPage,

package/server/pages/static.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import fs from 'node:fs';
+import Negotiator from 'negotiator';
 const MIME_TYPES = {
   '.html': 'text/html',
   '.css': 'text/css',
@@ -23,7 +24,25 @@ const MIME_TYPES = {
   '.webm': 'video/webm',
   '.pdf': 'application/pdf',
 };
-function serveStaticAsset(pathname, res, outDir) {
+// Text-like payloads that benefit from pre-compression. Image/font binaries
+// either have their own compression (woff2, webp) or compress poorly enough
+// that the cost isn't worth the Vary-header cache fanout.
+const COMPRESSIBLE_TYPES = new Set([
+  'text/html',
+  'text/css',
+  'text/plain',
+  'application/javascript',
+  'application/json',
+  'application/xml',
+  'image/svg+xml',
+]);
+function negotiateEncoding(req) {
+  if (!req || !req.headers) return null;
+  const best = new Negotiator(req).encodings(['br', 'gzip', 'identity'])[0];
+  if (best === 'br' || best === 'gzip') return best;
+  return null;
+}
+function serveStaticAsset(pathname, res, outDir, req) {
   const relativePath = pathname.slice('/static/'.length);
   const normalized = path.normalize(relativePath);
   if (normalized.startsWith('..') || path.isAbsolute(normalized)) {
@@ -55,11 +74,39 @@ function serveStaticAsset(pathname, res, outDir) {
   const cacheControl = hasContentHash
     ? 'public, max-age=31536000, immutable'
     : 'public, max-age=3600';
-  res.writeHead(200, {
+  const compressible = COMPRESSIBLE_TYPES.has(contentType);
+  let servePath = filePath;
+  let contentEncoding = null;
+  if (compressible) {
+    const preferred = negotiateEncoding(req);
+    if (preferred === 'br' && fs.existsSync(filePath + '.br')) {
+      servePath = filePath + '.br';
+      contentEncoding = 'br';
+    } else if (preferred === 'gzip' && fs.existsSync(filePath + '.gz')) {
+      servePath = filePath + '.gz';
+      contentEncoding = 'gzip';
+    } else if (preferred === 'br' && fs.existsSync(filePath + '.gz')) {
+      // Client lists br first but we only shipped .gz; gzip is still a win
+      // over identity and avoids on-the-fly compression.
+      servePath = filePath + '.gz';
+      contentEncoding = 'gzip';
+    }
+  }
+  const headers = {
     'Content-Type': contentType,
     'Cache-Control': cacheControl,
-  });
-  const stream = fs.createReadStream(filePath);
+  };
+  if (compressible) headers['Vary'] = 'Accept-Encoding';
+  if (contentEncoding) headers['Content-Encoding'] = contentEncoding;
+  try {
+    const stat = fs.statSync(servePath);
+    headers['Content-Length'] = String(stat.size);
+  } catch {
+    // If stat fails here after existsSync passed, fall through without the
+    // header; the pipe below will still error cleanly on the caller's side.
+  }
+  res.writeHead(200, headers);
+  const stream = fs.createReadStream(servePath);
   stream.pipe(res);
   return true;
 }

package/server/static/index.js

@@ -21,7 +21,7 @@ class StaticRouter {
 
     // Built bundles: /static/client/*
     if (pathname.startsWith('/static/client/')) {
-      return serveStaticAsset(pathname, res, this.outDir);
+      return serveStaticAsset(pathname, res, this.outDir, req);
     }
 
     // Public files: /* (fallback)