arcway 0.1.14 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcway",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "A convention-based framework for building modular monoliths with strict domain boundaries.",
   "license": "MIT",
   "type": "module",

package/server/boot/index.js

@@ -59,8 +59,8 @@ async function boot(options) {
   });
   await jobRunner.init();
 
-  const fileWatcher = new FileWatcher(rootDir, { log });
-  await fileWatcher.start();
+  const fileWatcher = mode === 'development' ? new FileWatcher(rootDir, { log }) : null;
+  if (fileWatcher) await fileWatcher.start();
 
   const appContext = { db, redis, events, queue, cache, files, mail, log, fileWatcher };
 
@@ -68,13 +68,14 @@ async function boot(options) {
 
   const apiRouter = new ApiRouter(config.api, {
     log,
+    mode,
     fileWatcher,
     appContext,
     sessionConfig: config.session,
   });
   await apiRouter.init();
 
-  const pagesRouter = new PagesRouter(config, { rootDir, log, fileWatcher, appContext });
+  const pagesRouter = new PagesRouter(config, { rootDir, log, mode, fileWatcher, appContext });
   await pagesRouter.init();
 
   const healthDeps = {
@@ -117,7 +118,7 @@ async function boot(options) {
     await pagesRouter.close();
     await apiRouter.close();
     await webServer.close();
-    await fileWatcher.close();
+    if (fileWatcher) await fileWatcher.close();
     await destroyInfrastructure(infrastructure);
     await mcpRouter.cleanup(rootDir);
   };

package/server/pages/build-cache.js

@@ -194,10 +194,81 @@ async function buildWithCache({
   return { cacheHit: false, metafile: result.metafile };
 }
 
+// Multi-file cache for bundles with several output files (client build with
+// code-splitting). Each cache entry lives under <bucket>/<coarseKey>/ and the
+// index is a sidecar <bucket>/<coarseKey>.meta.json.
+async function lookupMultiFileCache({ rootDir, kind, coarseKey }) {
+  const bucket = bucketDir(rootDir, kind);
+  const metaPath = path.join(bucket, `${coarseKey}.meta.json`);
+  const cacheDir = path.join(bucket, coarseKey);
+  const meta = await readJson(metaPath);
+  if (!meta) return { hit: false, bucket, cacheDir, metaPath };
+  const currentHash = await hashInputs(meta.inputs);
+  if (currentHash === null || currentHash !== meta.inputsHash) {
+    return { hit: false, bucket, cacheDir, metaPath };
+  }
+  // Sanity-check every recorded output file still exists in the cache dir.
+  for (const rel of meta.outputs) {
+    try {
+      await fs.access(path.join(cacheDir, rel));
+    } catch {
+      return { hit: false, bucket, cacheDir, metaPath };
+    }
+  }
+  return { hit: true, bucket, cacheDir, metaPath, meta };
+}
+
+async function restoreMultiFileCache({ cacheDir, outputs, destDir }) {
+  await fs.mkdir(destDir, { recursive: true });
+  await Promise.all(
+    outputs.map(async (rel) => {
+      const src = path.join(cacheDir, rel);
+      const dst = path.join(destDir, rel);
+      await fs.mkdir(path.dirname(dst), { recursive: true });
+      await fs.cp(src, dst);
+    }),
+  );
+}
+
+async function storeMultiFileCache({
+  bucket,
+  coarseKey,
+  destDir,
+  outputs,
+  inputs,
+  metadata,
+}) {
+  const cacheDir = path.join(bucket, coarseKey);
+  await fs.rm(cacheDir, { recursive: true, force: true });
+  await fs.mkdir(cacheDir, { recursive: true });
+  await Promise.all(
+    outputs.map(async (rel) => {
+      const src = path.join(destDir, rel);
+      const dst = path.join(cacheDir, rel);
+      await fs.mkdir(path.dirname(dst), { recursive: true });
+      await cpAtomic(src, dst);
+    }),
+  );
+  const inputsHash = await hashInputs(inputs);
+  const metaPath = path.join(bucket, `${coarseKey}.meta.json`);
+  await writeJsonAtomic(metaPath, {
+    inputs,
+    inputsHash,
+    outputs,
+    metadata,
+    mtime: Date.now(),
+  });
+}
+
 export {
   buildWithCache,
   computeConfigHash,
   cacheRoot,
   entryKey,
   ESBUILD_VERSION,
+  sha256,
+  hashInputs,
+  lookupMultiFileCache,
+  restoreMultiFileCache,
+  storeMultiFileCache,
 };

package/server/pages/build-client.js

@@ -6,73 +6,137 @@ import { resolveLayoutChain, resolveLoadingChain } from './discovery.js';
 import { clientIsolationPlugin } from './build-plugins.js';
 import { patternToFileName, layoutDirToFileName } from './build-server.js';
 import { reactRefreshPlugin } from './hmr.js';
-async function buildClientBundles(
-  pages,
-  layouts,
-  outDir,
-  target,
-  minify,
-  rootDir,
-  loadings = [],
-  nodeEnv = 'production',
-  devMode = false,
-) {
-  const clientDir = path.join(outDir, 'client');
-  const bundles = new Map();
-  const navBundles = new Map();
-  const layoutNavBundles = new Map();
-  const loadingNavBundles = new Map();
+import {
+  sha256,
+  ESBUILD_VERSION,
+  lookupMultiFileCache,
+  restoreMultiFileCache,
+  storeMultiFileCache,
+} from './build-cache.js';
+
+// 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
+// before running esbuild.
+function planHydrationEntries(pages, layouts, loadings, tempDir) {
+  const files = [];
   const entryPoints = {};
-  const tempDir = path.join(outDir, '.hydration-entries');
-  await fs.mkdir(tempDir, { recursive: true });
+  const entryToPattern = new Map();
+  const entryToNavPattern = new Map();
+  const entryToLayoutDir = new Map();
+  const entryToLoadingDir = new Map();
+
   for (const page of pages) {
     const outName = patternToFileName(page.pattern);
     const layoutChain = resolveLayoutChain(page.pattern, layouts);
     const loadingChain = resolveLoadingChain(page.pattern, loadings);
-    const entryContent = generateHydrationEntry(page.filePath, layoutChain, loadingChain);
+    const content = generateHydrationEntry(page.filePath, layoutChain, loadingChain);
     const entryPath = path.join(tempDir, `${outName}.tsx`);
-    await fs.mkdir(path.dirname(entryPath), { recursive: true });
-    await fs.writeFile(entryPath, entryContent);
+    files.push({ entryPath, content });
     entryPoints[outName] = entryPath;
+    entryToPattern.set(entryPath, page.pattern);
   }
   for (const page of pages) {
     const navName = `nav_${patternToFileName(page.pattern)}`;
     const importPath = page.filePath.replace(/\\/g, '/');
-    const navContent = `export { default } from '${importPath}';
-`;
+    const content = `export { default } from '${importPath}';\n`;
     const navPath = path.join(tempDir, `${navName}.tsx`);
-    await fs.mkdir(path.dirname(navPath), { recursive: true });
-    await fs.writeFile(navPath, navContent);
+    files.push({ entryPath: navPath, content });
     entryPoints[navName] = navPath;
+    entryToNavPattern.set(navPath, page.pattern);
   }
   for (const layout of layouts) {
     const layoutName = `nav_layout_${layoutDirToFileName(layout.dirPath)}`;
     const importPath = layout.filePath.replace(/\\/g, '/');
-    const navContent = `export { default } from '${importPath}';
-`;
+    const content = `export { default } from '${importPath}';\n`;
     const navPath = path.join(tempDir, `${layoutName}.tsx`);
-    await fs.mkdir(path.dirname(navPath), { recursive: true });
-    await fs.writeFile(navPath, navContent);
+    files.push({ entryPath: navPath, content });
     entryPoints[layoutName] = navPath;
+    entryToLayoutDir.set(navPath, layout.dirPath);
   }
   for (const loading of loadings) {
     const loadingName = `nav_loading_${layoutDirToFileName(loading.dirPath)}`;
     const importPath = loading.filePath.replace(/\\/g, '/');
-    const navContent = `export { default } from '${importPath}';
-`;
+    const content = `export { default } from '${importPath}';\n`;
     const navPath = path.join(tempDir, `${loadingName}.tsx`);
-    await fs.mkdir(path.dirname(navPath), { recursive: true });
-    await fs.writeFile(navPath, navContent);
+    files.push({ entryPath: navPath, content });
     entryPoints[loadingName] = navPath;
+    entryToLoadingDir.set(navPath, loading.dirPath);
   }
+  return { files, entryPoints, entryToPattern, entryToNavPattern, entryToLayoutDir, entryToLoadingDir };
+}
+
+function resolveReactAlias(rootDir) {
   const projectRequire = createRequire(path.join(rootDir, 'package.json'));
-  const reactAlias = {};
+  const alias = {};
   for (const pkg of ['react', 'react-dom']) {
     try {
-      reactAlias[pkg] = path.dirname(projectRequire.resolve(`${pkg}/package.json`));
+      alias[pkg] = path.dirname(projectRequire.resolve(`${pkg}/package.json`));
     } catch {}
   }
-  const result = await esbuild.build({
+  return alias;
+}
+
+// Cache key is derived from everything that could change the client bundle
+// output set except for the actual source-file contents (those are tracked
+// as the invalidation inputs list and re-hashed on lookup).
+function computeClientCoarseKey({
+  target,
+  minify,
+  devMode,
+  nodeEnv,
+  reactAlias,
+  pages,
+  layouts,
+  loadings,
+  hydrationContents,
+}) {
+  return sha256(
+    JSON.stringify({
+      esbuildVersion: ESBUILD_VERSION,
+      target: target ?? '',
+      minify: !!minify,
+      devMode: !!devMode,
+      nodeEnv: nodeEnv ?? '',
+      reactAlias,
+      pages: pages.map((p) => ({ pattern: p.pattern, filePath: path.resolve(p.filePath) })),
+      layouts: layouts.map((l) => ({ dirPath: l.dirPath, filePath: path.resolve(l.filePath) })),
+      loadings: loadings.map((l) => ({ dirPath: l.dirPath, filePath: path.resolve(l.filePath) })),
+      hydrationContents,
+    }),
+  );
+}
+
+function serializeMetadata(meta) {
+  return {
+    bundles: [...meta.bundles.entries()],
+    navBundles: [...meta.navBundles.entries()],
+    layoutNavBundles: [...meta.layoutNavBundles.entries()],
+    loadingNavBundles: [...meta.loadingNavBundles.entries()],
+    sharedChunks: meta.sharedChunks,
+  };
+}
+
+function deserializeMetadata(raw) {
+  return {
+    bundles: new Map(raw.bundles),
+    navBundles: new Map(raw.navBundles),
+    layoutNavBundles: new Map(raw.layoutNavBundles),
+    loadingNavBundles: new Map(raw.loadingNavBundles),
+    sharedChunks: raw.sharedChunks,
+  };
+}
+
+function buildClientEsbuildOptions({
+  entryPoints,
+  clientDir,
+  target,
+  minify,
+  devMode,
+  nodeEnv,
+  reactAlias,
+  rootDir,
+}) {
+  return {
     entryPoints,
     outdir: clientDir,
     format: 'esm',
@@ -90,25 +154,174 @@ async function buildClientBundles(
     alias: reactAlias,
     define: { 'process.env.NODE_ENV': JSON.stringify(nodeEnv) },
     plugins: [...(devMode ? [reactRefreshPlugin(rootDir)] : []), clientIsolationPlugin()],
-  });
-  await fs.rm(tempDir, { recursive: true, force: true });
-  const entryToPattern = new Map();
-  const entryToNavPattern = new Map();
-  const entryToLayoutDir = new Map();
-  for (const page of pages) {
-    const outName = patternToFileName(page.pattern);
-    entryToPattern.set(path.join(tempDir, `${outName}.tsx`), page.pattern);
-    entryToNavPattern.set(path.join(tempDir, `nav_${outName}.tsx`), page.pattern);
+  };
+}
+
+async function writeHydrationEntries(plan) {
+  await Promise.all(
+    plan.files.map(async (f) => {
+      await fs.mkdir(path.dirname(f.entryPath), { recursive: true });
+      await fs.writeFile(f.entryPath, f.content);
+    }),
+  );
+}
+
+// Long-lived esbuild context for the client bundle. Used by the dev watcher so
+// file-change rebuilds call `ctx.rebuild()` (incremental) instead of spinning up
+// a fresh esbuild per change. The context is bound to the specific
+// pages/layouts/loadings set; structural changes (add/remove page) require
+// disposing and recreating.
+async function createClientBuildContext(
+  pages,
+  layouts,
+  outDir,
+  target,
+  minify,
+  rootDir,
+  loadings = [],
+  nodeEnv = 'production',
+  devMode = false,
+) {
+  const clientDir = path.join(outDir, 'client');
+  const tempDir = path.join(outDir, '.hydration-entries');
+  const plan = planHydrationEntries(pages, layouts, loadings, tempDir);
+  const reactAlias = resolveReactAlias(rootDir);
+
+  await fs.mkdir(clientDir, { recursive: true });
+  await fs.mkdir(tempDir, { recursive: true });
+  await writeHydrationEntries(plan);
+
+  const ctx = await esbuild.context(
+    buildClientEsbuildOptions({
+      entryPoints: plan.entryPoints,
+      clientDir,
+      target,
+      minify,
+      devMode,
+      nodeEnv,
+      reactAlias,
+      rootDir,
+    }),
+  );
+
+  let disposed = false;
+
+  async function rebuild() {
+    const result = await ctx.rebuild();
+    const metadata = extractMetadata(result, plan, outDir);
+    return { ...metadata, metafile: result.metafile };
   }
-  for (const layout of layouts) {
-    const layoutName = `nav_layout_${layoutDirToFileName(layout.dirPath)}`;
-    entryToLayoutDir.set(path.join(tempDir, `${layoutName}.tsx`), layout.dirPath);
+
+  async function dispose() {
+    if (disposed) return;
+    disposed = true;
+    await ctx.dispose();
+    await fs.rm(tempDir, { recursive: true, force: true });
   }
-  const entryToLoadingDir = new Map();
-  for (const loading of loadings) {
-    const loadingName = `nav_loading_${layoutDirToFileName(loading.dirPath)}`;
-    entryToLoadingDir.set(path.join(tempDir, `${loadingName}.tsx`), loading.dirPath);
+
+  return { rebuild, dispose };
+}
+
+async function buildClientBundles(
+  pages,
+  layouts,
+  outDir,
+  target,
+  minify,
+  rootDir,
+  loadings = [],
+  nodeEnv = 'production',
+  devMode = false,
+) {
+  const clientDir = path.join(outDir, 'client');
+  const tempDir = path.join(outDir, '.hydration-entries');
+  const plan = planHydrationEntries(pages, layouts, loadings, tempDir);
+  const reactAlias = resolveReactAlias(rootDir);
+
+  // Cache is keyed on the full build intent (including exact hydration-entry
+  // contents). devMode skips the cache because the watcher will eventually own
+  // incremental rebuilds via esbuild.context() (Phase 4) and we also return
+  // the metafile directly in dev mode for HMR diffing.
+  const useCache = !devMode;
+  let cacheBucket;
+  let coarseKey;
+  if (useCache) {
+    coarseKey = computeClientCoarseKey({
+      target,
+      minify,
+      devMode,
+      nodeEnv,
+      reactAlias,
+      pages,
+      layouts,
+      loadings,
+      hydrationContents: plan.files.map((f) => ({
+        name: path.basename(f.entryPath),
+        content: f.content,
+      })),
+    });
+    const lookup = await lookupMultiFileCache({ rootDir, kind: 'client', coarseKey });
+    cacheBucket = lookup.bucket;
+    if (lookup.hit) {
+      await restoreMultiFileCache({
+        cacheDir: lookup.cacheDir,
+        outputs: lookup.meta.outputs,
+        destDir: clientDir,
+      });
+      return deserializeMetadata(lookup.meta.metadata);
+    }
+  }
+
+  await fs.mkdir(tempDir, { recursive: true });
+  await writeHydrationEntries(plan);
+
+  const result = await esbuild.build(
+    buildClientEsbuildOptions({
+      entryPoints: plan.entryPoints,
+      clientDir,
+      target,
+      minify,
+      devMode,
+      nodeEnv,
+      reactAlias,
+      rootDir,
+    }),
+  );
+  await fs.rm(tempDir, { recursive: true, force: true });
+
+  const metadata = extractMetadata(result, plan, outDir);
+
+  if (useCache) {
+    const outputs = Object.keys(result.metafile.outputs)
+      .map((p) => path.relative(clientDir, path.resolve(p)).replace(/\\/g, '/'))
+      .filter((rel) => !rel.startsWith('..'));
+    // Track only inputs on the real filesystem — the ephemeral hydration entries
+    // inside `tempDir` are re-generated each build from a stable content plan,
+    // so their paths change every run and can't stably invalidate the cache.
+    const inputs = Object.keys(result.metafile.inputs)
+      .map((p) => (path.isAbsolute(p) ? p : path.resolve(p)))
+      .filter((p) => !p.startsWith(tempDir));
+    await storeMultiFileCache({
+      bucket: cacheBucket,
+      coarseKey,
+      destDir: clientDir,
+      outputs,
+      inputs,
+      metadata: serializeMetadata(metadata),
+    });
   }
+
+  return {
+    ...metadata,
+    ...(devMode ? { metafile: result.metafile } : {}),
+  };
+}
+
+function extractMetadata(result, plan, outDir) {
+  const bundles = new Map();
+  const navBundles = new Map();
+  const layoutNavBundles = new Map();
+  const loadingNavBundles = new Map();
   const sharedChunks = [];
   for (const [outputPath, meta] of Object.entries(result.metafile.outputs)) {
     const relPath = path.relative(outDir, outputPath).replace(/\\/g, '/');
@@ -119,41 +332,24 @@ async function buildClientBundles(
     }
     if (meta.entryPoint) {
       const absEntry = path.resolve(meta.entryPoint);
-      for (const [entryPath, pattern] of entryToPattern) {
-        if (absEntry === entryPath) {
-          bundles.set(pattern, relPath);
-          break;
-        }
-      }
-      for (const [entryPath, pattern] of entryToNavPattern) {
-        if (absEntry === entryPath) {
-          navBundles.set(pattern, relPath);
-          break;
-        }
-      }
-      for (const [entryPath, dirPath] of entryToLayoutDir) {
-        if (absEntry === entryPath) {
-          layoutNavBundles.set(dirPath, relPath);
-          break;
-        }
-      }
-      for (const [entryPath, dirPath] of entryToLoadingDir) {
-        if (absEntry === entryPath) {
-          loadingNavBundles.set(dirPath, relPath);
-          break;
-        }
+      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;
     }
   }
-  return {
-    bundles,
-    navBundles,
-    layoutNavBundles,
-    loadingNavBundles,
-    sharedChunks,
-    ...(devMode ? { metafile: result.metafile } : {}),
-  };
+  return { bundles, navBundles, layoutNavBundles, loadingNavBundles, sharedChunks };
 }
+
 function generateHydrationEntry(componentPath, layouts = [], loadings = []) {
   const importPath = componentPath.replace(/\\/g, '/');
   const imports = [
@@ -184,4 +380,4 @@ const props = propsEl ? JSON.parse(propsEl.textContent || '{}') : {};
 hydrateRoot(container!, <ApiProvider><Router initialPath={window.location.pathname} initialParams={props} initialComponent={Component} initialLayouts={${layoutsArray}} initialLoadings={${loadingsArray}} /></ApiProvider>);
 `;
 }
-export { buildClientBundles, generateHydrationEntry };
+export { buildClientBundles, createClientBuildContext, generateHydrationEntry };

package/server/pages/build-context.js

@@ -0,0 +1,172 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import {
+  discoverPages,
+  discoverLayouts,
+  discoverLoadings,
+  discoverPageMiddleware,
+  discoverErrorPages,
+  discoverStyles,
+} from './discovery.js';
+import {
+  buildServerBundles,
+  buildLayoutServerBundles,
+  buildMiddlewareServerBundles,
+  buildErrorPageBundles,
+} from './build-server.js';
+import { createClientBuildContext } from './build-client.js';
+import { buildCssBundle } from './build-css.js';
+import { generateManifest } from './build-manifest.js';
+import { resolveFonts } from './fonts.js';
+import { buildHmrRuntimeBundle } from './hmr.js';
+
+// Long-lived build context for dev-watch mode. Unlike `buildPages()`, which
+// rebuilds every esbuild graph from scratch, this keeps an incremental
+// `esbuild.context()` alive for the client bundle so file-change rebuilds are
+// near-instant. Server, layout, middleware, CSS, and error-page bundles reuse
+// the persistent on-disk cache (phase 2/3), which already handles per-entry
+// invalidation cheaply. The dev outDir is written in place — the atomic staging
+// swap is a prod-safety feature that conflicts with esbuild's requirement for a
+// stable outdir across rebuilds.
+async function createPagesBuildContext(options) {
+  const { rootDir } = options;
+  const pagesDir = options.pagesDir ?? path.join(rootDir, 'pages');
+  const outDir = path.resolve(rootDir, options.outDir ?? '.build/pages');
+  const serverTarget = options.serverTarget ?? 'node22';
+  const clientTarget = options.clientTarget ?? 'es2022';
+  const minify = options.minify ?? false;
+  const devMode = options.devMode ?? true;
+
+  let fontFaceCss;
+  let fontPreloadHtml;
+  if (options.fonts && options.fonts.length > 0) {
+    const publicDir = path.join(rootDir, 'public');
+    const fontResult = await resolveFonts(options.fonts, publicDir);
+    if (fontResult.fontFaceCss) fontFaceCss = fontResult.fontFaceCss;
+    if (fontResult.preloadHtml) fontPreloadHtml = fontResult.preloadHtml;
+  }
+
+  let clientCtx = null;
+  let lastStructuralKey = null;
+  let lastResult = null;
+  let disposed = false;
+
+  async function ensureClientContext(pages, layouts, loadings) {
+    const structuralKey = computeStructuralKey(pages, layouts, loadings);
+    if (clientCtx !== null && structuralKey === lastStructuralKey) return;
+    if (clientCtx) {
+      await clientCtx.dispose();
+      clientCtx = null;
+    }
+    clientCtx = await createClientBuildContext(
+      pages,
+      layouts,
+      outDir,
+      clientTarget,
+      minify,
+      rootDir,
+      loadings,
+      minify ? 'production' : 'development',
+      devMode,
+    );
+    lastStructuralKey = structuralKey;
+  }
+
+  async function rebuild() {
+    if (disposed) throw new Error('createPagesBuildContext: context has been disposed');
+
+    const [pages, layouts, loadings, middlewares, errorPages, stylesPath] = await Promise.all([
+      discoverPages(pagesDir),
+      discoverLayouts(pagesDir),
+      discoverLoadings(pagesDir),
+      discoverPageMiddleware(pagesDir),
+      discoverErrorPages(pagesDir),
+      discoverStyles(pagesDir),
+    ]);
+
+    if (pages.length === 0) {
+      lastResult = { pageCount: 0, outDir, manifest: { entries: [], sharedChunks: [] } };
+      return lastResult;
+    }
+
+    await fs.mkdir(path.join(outDir, 'server'), { recursive: true });
+    await fs.mkdir(path.join(outDir, 'client'), { recursive: true });
+
+    await ensureClientContext(pages, layouts, loadings);
+
+    const serverCacheOpts = { rootDir, devMode, minify };
+    const builds = [
+      buildServerBundles(pages, outDir, serverTarget, serverCacheOpts),
+      buildLayoutServerBundles(layouts, outDir, serverTarget, serverCacheOpts),
+      buildMiddlewareServerBundles(middlewares, outDir, serverTarget, serverCacheOpts),
+      clientCtx.rebuild(),
+      buildErrorPageBundles(errorPages, outDir, serverTarget, serverCacheOpts),
+      buildCssBundle(pagesDir, outDir, minify, stylesPath, fontFaceCss, rootDir),
+    ];
+    if (devMode) builds.push(buildHmrRuntimeBundle(outDir));
+
+    const [
+      serverResult,
+      layoutServerResult,
+      middlewareServerResult,
+      clientResult,
+      errorBundles,
+      cssBundle,
+    ] = await Promise.all(builds);
+
+    const manifest = generateManifest(
+      pages,
+      layouts,
+      loadings,
+      middlewares,
+      serverResult,
+      layoutServerResult,
+      middlewareServerResult,
+      clientResult,
+    );
+    if (errorBundles.error) manifest.errorBundle = errorBundles.error;
+    if (errorBundles.notFound) manifest.notFoundBundle = errorBundles.notFound;
+    if (cssBundle) manifest.cssBundle = cssBundle;
+    if (fontPreloadHtml) manifest.fontPreloadHtml = fontPreloadHtml;
+
+    await fs.writeFile(
+      path.join(outDir, 'pages-manifest.json'),
+      JSON.stringify(manifest, null, 2),
+    );
+
+    lastResult = {
+      pageCount: pages.length,
+      outDir,
+      manifest,
+      ...(clientResult.metafile ? { clientMetafile: clientResult.metafile } : {}),
+    };
+    return lastResult;
+  }
+
+  async function dispose() {
+    if (disposed) return;
+    disposed = true;
+    if (clientCtx) {
+      await clientCtx.dispose();
+      clientCtx = null;
+    }
+  }
+
+  return {
+    rebuild,
+    dispose,
+    get currentResult() {
+      return lastResult;
+    },
+  };
+}
+
+function computeStructuralKey(pages, layouts, loadings) {
+  return JSON.stringify({
+    p: pages.map((p) => p.pattern).sort(),
+    l: layouts.map((l) => l.dirPath).sort(),
+    ld: loadings.map((l) => l.dirPath).sort(),
+  });
+}
+
+export { createPagesBuildContext };

package/server/pages/build-css.js

@@ -5,13 +5,80 @@ import { createRequire } from 'node:module';
 import esbuild from 'esbuild';
 import postcss from 'postcss';
 import tailwindPostcss from '@tailwindcss/postcss';
-async function buildCssBundle(pagesDir, outDir, minify, stylesPath, fontFaceCss) {
+import {
+  sha256,
+  lookupMultiFileCache,
+  restoreMultiFileCache,
+  storeMultiFileCache,
+} from './build-cache.js';
+
+// Shallow-walk the pages dir and return every source-shaped file. Used as the
+// cache-invalidation input set when tailwind will scan it via @source.
+async function collectTailwindSources(pagesDir) {
+  const out = [];
+  async function walk(dir) {
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (e.name === 'node_modules' || e.name.startsWith('.')) continue;
+        await walk(full);
+      } else if (e.isFile()) {
+        if (/\.(jsx?|tsx?|mjs|cjs|css)$/i.test(e.name)) {
+          out.push(full);
+        }
+      }
+    }
+  }
+  await walk(pagesDir);
+  return out;
+}
+
+function computeCssCoarseKey({ minify, fontFaceCss, stylesPath }) {
+  return sha256(
+    JSON.stringify({
+      minify: !!minify,
+      fontFaceCss: fontFaceCss ?? '',
+      stylesPath: stylesPath ? path.resolve(stylesPath) : null,
+    }),
+  );
+}
+
+async function buildCssBundle(pagesDir, outDir, minify, stylesPath, fontFaceCss, rootDir) {
   try {
     await fs.access(pagesDir);
   } catch {
-    // Pages directory doesn't exist — no CSS to build
     return void 0;
   }
+
+  const clientDir = path.join(outDir, 'client');
+  rootDir = rootDir ?? path.dirname(outDir);
+  const coarseKey = computeCssCoarseKey({ minify, fontFaceCss, stylesPath });
+
+  // Inputs that should invalidate the cache on content change.
+  const inputs = [];
+  if (stylesPath) {
+    inputs.push(path.resolve(stylesPath));
+  } else {
+    const scanned = await collectTailwindSources(pagesDir);
+    for (const f of scanned) inputs.push(f);
+  }
+
+  const lookup = await lookupMultiFileCache({ rootDir, kind: 'css', coarseKey });
+  if (lookup.hit) {
+    await restoreMultiFileCache({
+      cacheDir: lookup.cacheDir,
+      outputs: lookup.meta.outputs,
+      destDir: clientDir,
+    });
+    return lookup.meta.metadata.cssBundleRel;
+  }
+
   let cssSource;
   if (stylesPath) {
     cssSource = `@import ${JSON.stringify(stylesPath)};`;
@@ -29,19 +96,28 @@ async function buildCssBundle(pagesDir, outDir, minify, stylesPath, fontFaceCss)
     from: stylesPath ?? path.join(pagesDir, '__virtual_entry.css'),
     to: path.join(outDir, 'client', 'styles.css'),
   });
-  let css = fontFaceCss
-    ? `${fontFaceCss}
-
-${result.css}`
-    : result.css;
+  let css = fontFaceCss ? `${fontFaceCss}\n\n${result.css}` : result.css;
   if (minify) {
     const minified = await esbuild.transform(css, { loader: 'css', minify: true });
     css = minified.code;
   }
   const hash = crypto.createHash('sha256').update(css).digest('hex').slice(0, 8);
   const cssFileName = `styles-${hash}.css`;
-  const outFile = path.join(outDir, 'client', cssFileName);
+  const outFile = path.join(clientDir, cssFileName);
+  await fs.mkdir(clientDir, { recursive: true });
   await fs.writeFile(outFile, css);
-  return `client/${cssFileName}`;
+  const cssBundleRel = `client/${cssFileName}`;
+
+  await storeMultiFileCache({
+    bucket: lookup.bucket,
+    coarseKey,
+    destDir: clientDir,
+    outputs: [cssFileName],
+    inputs,
+    metadata: { cssBundleRel },
+  });
+
+  return cssBundleRel;
 }
+
 export { buildCssBundle };

package/server/pages/build.js

@@ -74,7 +74,7 @@ async function buildPages(options) {
         devMode,
       ),
       buildErrorPageBundles(errorPages, buildDir, serverTarget, serverCacheOpts),
-      buildCssBundle(pagesDir, buildDir, minify, stylesPath, fontFaceCss),
+      buildCssBundle(pagesDir, buildDir, minify, stylesPath, fontFaceCss, rootDir),
     );
     if (devMode) builds.push(buildHmrRuntimeBundle(buildDir));
     // Fail fast: `Promise.all` rejects the moment any build throws, so a broken
@@ -123,13 +123,24 @@ async function buildPages(options) {
     // before removing the directory — otherwise `fs.rm` races the writes and
     // fails with ENOTEMPTY. The cleanup is fire-and-forget so the caller sees
     // the original error immediately; the unique staging-dir suffix means any
-    // lingering files can't pollute a subsequent `buildPages` call.
-    void Promise.allSettled(builds).then(() =>
+    // lingering files can't pollute a subsequent `buildPages` call. Pending
+    // cleanups are tracked so tests can await quiescence.
+    const cleanup = Promise.allSettled(builds).then(() =>
       fs.rm(buildDir, { recursive: true, force: true }).catch(() => {}),
     );
+    pendingCleanups.add(cleanup);
+    cleanup.finally(() => pendingCleanups.delete(cleanup));
     throw err;
   }
 }
+// Tracks fire-and-forget cleanup promises from failed builds so tests can
+// await `buildPagesIdle()` and see a clean `.build` dir.
+const pendingCleanups = new Set();
+async function buildPagesIdle() {
+  while (pendingCleanups.size > 0) {
+    await Promise.allSettled([...pendingCleanups]);
+  }
+}
 // Serialize concurrent swaps targeting the same outDir. Without this, two
 // parallel `buildPages` calls against the same outDir race between the
 // `fs.rm(outDir)` and `fs.rename(buildDir, outDir)` steps: both rm's succeed,
@@ -161,4 +172,4 @@ function rewriteMetafilePaths(metafile, fromDir, toDir) {
   return { ...metafile, outputs };
 }
 import { patternToFileName } from './build-server.js';
-export { buildPages, patternToFileName };
+export { buildPages, patternToFileName, buildPagesIdle };

package/server/pages/handler.js

@@ -19,7 +19,8 @@ function createPagesHandler(options) {
   const manifestPath = path.join(outDir, 'pages-manifest.json');
   const sessionConfig = options.session;
   const appContext = options.appContext ?? null;
-  const devMode = options.devMode ?? false;
+  const mode = options.mode ?? 'production';
+  const devMode = mode === 'development';
   if (!fs.existsSync(manifestPath)) {
     return null;
   }
@@ -139,12 +140,11 @@ function createPagesHandler(options) {
       );
     } catch (err) {
       if (manifest.errorBundle && !res.headersSent) {
-        const errorMessage =
-          process.env.NODE_ENV === 'production'
-            ? 'An unexpected error occurred'
-            : err instanceof Error
-              ? err.message
-              : String(err);
+        const errorMessage = devMode
+          ? err instanceof Error
+            ? err.message
+            : String(err)
+          : 'An unexpected error occurred';
         await renderErrorPage(
           manifest.errorBundle,
           500,

package/server/pages/pages-router.js

@@ -6,21 +6,23 @@ class PagesRouter {
   config;
   rootDir;
   log;
+  mode;
   fileWatcher;
   handler = null;
   watcher = null;
 
-  constructor(config, { rootDir, log, fileWatcher, appContext }) {
+  constructor(config, { rootDir, log, mode, fileWatcher, appContext }) {
     this.config = config;
     this.rootDir = rootDir;
     this.log = log;
+    this.mode = mode ?? 'production';
     this.fileWatcher = fileWatcher ?? null;
     this.appContext = appContext ?? null;
   }
 
   async init() {
-    const { config, rootDir, log, fileWatcher } = this;
-    const isDev = fileWatcher !== null;
+    const { config, rootDir, log, mode, fileWatcher } = this;
+    const isDev = mode === 'development';
 
     let initialClientMetafile;
     if (isDev) {
@@ -42,14 +44,14 @@ class PagesRouter {
       rootDir,
       session: config.session,
       appContext: this.appContext,
-      devMode: isDev,
+      mode,
     });
 
     if (!this.handler) return;
 
     log.info('Pages: SSR enabled');
 
-    if (isDev) {
+    if (isDev && fileWatcher) {
       this.watcher = createPagesWatcher({
         rootDir,
         handler: this.handler,

package/server/router/api-router.js

@@ -82,6 +82,7 @@ async function serializeResponse(res, response, responseHeaders, statusCode) {
 class ApiRouter {
   _config;
   _log;
+  _mode;
   _fileWatcher;
   _appContext;
   _sessionConfig;
@@ -91,9 +92,10 @@ class ApiRouter {
   _reloading = false;
   _pendingReload = false;
 
-  constructor(config, { log, fileWatcher, appContext, sessionConfig } = {}) {
+  constructor(config, { log, mode, fileWatcher, appContext, sessionConfig } = {}) {
     this._config = config;
     this._log = log;
+    this._mode = mode ?? 'production';
     this._fileWatcher = fileWatcher ?? null;
     this._appContext = appContext ?? null;
     this._sessionConfig = sessionConfig ?? null;
@@ -176,7 +178,7 @@ class ApiRouter {
     this._prefix = normalizePrefix(this._config.pathPrefix);
     this._log?.info('Discovering routes...');
     await this._discover();
-    if (this._fileWatcher) {
+    if (this._mode === 'development' && this._fileWatcher) {
       this._fileWatcher.subscribe('routes', {
         dirs: ['api'],
         extensions: ['.js'],
@@ -303,7 +305,7 @@ class ApiRouter {
   }
 
   async close() {
-    if (this._fileWatcher) {
+    if (this._mode === 'development' && this._fileWatcher) {
       this._fileWatcher.unsubscribe('routes');
     }
   }

package/server/session/index.js

@@ -28,6 +28,7 @@ function resolveSessionConfig(config, mode) {
     password: config.password,
     cookieName: config.cookieName ?? 'arcway.session',
     ttl: config.ttl ?? 14 * 24 * 3600,
+    mode: mode ?? 'production',
     cookie: {
       httpOnly: config.cookie?.httpOnly ?? true,
       secure: config.cookie?.secure ?? mode === 'production',
@@ -46,7 +47,7 @@ async function unsealSession(cookieValue, config) {
     });
     return data && typeof data === 'object' ? data : {};
   } catch (err) {
-    if (process.env.NODE_ENV !== 'production') {
+    if (config.mode === 'development') {
       const reason = toErrorMessage(err);
       console.warn(`[arcway] Failed to unseal session cookie: ${reason}`);
     }