arcway 0.1.20 → 0.1.22

package/server/pages/build-css.js

@@ -53,7 +53,7 @@ function computeCssCoarseKey({ minify, fontFaceCss, stylesPath }) {
   );
 }
 
-async function buildCssBundle(pagesDir, outDir, minify, stylesPath, fontFaceCss, rootDir) {
+async function buildCssBundle(pagesDir, outDir, minify, stylesPath, fontFaceCss, rootDir, limit = (fn) => fn()) {
   try {
     await fs.access(pagesDir);
   } catch {
@@ -61,6 +61,12 @@ async function buildCssBundle(pagesDir, outDir, minify, stylesPath, fontFaceCss,
   }
 
   const clientDir = path.join(outDir, 'client');
+  // rootDir == the project root — same directory tailwind v4's auto-content
+  // detection walks up to find (it stops at the nearest package.json). Keep
+  // the scan root separate from the cache-root default: if the caller didn't
+  // pass rootDir, fall back to pagesDir for scanning (narrower, safe for
+  // tests) while still letting the cache default to outDir's parent.
+  const tokenScanRoot = rootDir ?? pagesDir;
   rootDir = rootDir ?? path.dirname(outDir);
   const coarseKey = computeCssCoarseKey({ minify, fontFaceCss, stylesPath });
 
@@ -73,14 +79,22 @@ async function buildCssBundle(pagesDir, outDir, minify, stylesPath, fontFaceCss,
   for (const f of cssFiles) inputs.push(f);
 
   // Virtual input: a digest over every string-literal token found in the
-  // JSX/TS source tree under pagesDir. Tailwind's class-name emission depends
-  // only on which tokens appear in scanned files — not on surrounding code
-  // structure — so the digest captures the only source signal that actually
-  // matters for CSS output. Editing handler logic, comments, or whitespace
-  // leaves this digest unchanged and the CSS cache is reused.
-  const classTokensDigest = await hashClassTokens(pagesDir);
+  // JSX/TS source tree under tokenScanRoot. Tailwind's class-name emission
+  // depends only on which tokens appear in scanned files — not on surrounding
+  // code structure — so the digest captures the only source signal that
+  // actually matters for CSS output. Editing handler logic, comments, or
+  // whitespace leaves this digest unchanged and the CSS cache is reused.
+  //
+  // Must match tailwind v4's effective scan scope: auto-content detection
+  // walks up from the CSS entry file to the nearest package.json, so a new
+  // arbitrary-value class in a sibling dir (e.g. components/ alongside pages/)
+  // IS picked up by tailwind but must also be reflected in this digest —
+  // otherwise an incremental rebuild hits the cache and silently restores
+  // stale CSS missing the new rule. Scanning rootDir (the project root)
+  // covers pagesDir + every sibling source tree, matching tailwind's scope.
+  const classTokensDigest = await hashClassTokens(tokenScanRoot);
   const virtualInputs = [
-    { name: `${path.resolve(pagesDir)}::class-tokens`, digest: classTokensDigest },
+    { name: `${path.resolve(tokenScanRoot)}::class-tokens`, digest: classTokensDigest },
   ];
 
   const lookup = await lookupMultiFileCache({ rootDir, kind: 'css', coarseKey, virtualInputs });
@@ -112,7 +126,7 @@ async function buildCssBundle(pagesDir, outDir, minify, stylesPath, fontFaceCss,
   });
   let css = fontFaceCss ? `${fontFaceCss}\n\n${result.css}` : result.css;
   if (minify) {
-    const minified = await esbuild.transform(css, { loader: 'css', minify: true });
+    const minified = await limit(() => esbuild.transform(css, { loader: 'css', minify: true }));
     css = minified.code;
   }
   const hash = crypto.createHash('sha256').update(css).digest('hex').slice(0, 8);

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-server.js

@@ -45,76 +45,89 @@ function plainEsbuildOptions(entry, outFile, target) {
   };
 }
 
-async function buildServerBundles(pages, outDir, target, { rootDir, devMode, minify } = {}) {
+// Identity wrapper for the `limit` option. When `buildPages()` passes a shared
+// `p-limit` instance, every esbuild invocation inside this file passes through
+// it so the whole build respects a single concurrency budget. When callers (or
+// direct tests) omit `limit`, the identity wrapper keeps today's unbounded
+// fan-out intact.
+const identityLimit = (fn) => fn();
+
+async function buildServerBundles(pages, outDir, target, { rootDir, devMode, minify, limit = identityLimit } = {}) {
   const serverDir = path.join(outDir, 'server');
   const resultMap = new Map();
   await Promise.all(
-    pages.map(async (page) => {
-      const outName = patternToFileName(page.pattern);
-      const outFile = path.join(serverDir, `${outName}.js`);
-      await buildWithCache({
-        rootDir: rootDir ?? outDir,
-        kind: 'server',
-        entryPath: page.filePath,
-        outFile,
-        esbuildOptions: jsxEsbuildOptions(page.filePath, outFile, target),
-        esbuild,
-        devMode,
-        minify,
-      });
-      resultMap.set(page.pattern, path.relative(outDir, outFile).replace(/\\/g, '/'));
-    }),
+    pages.map((page) =>
+      limit(async () => {
+        const outName = patternToFileName(page.pattern);
+        const outFile = path.join(serverDir, `${outName}.js`);
+        await buildWithCache({
+          rootDir: rootDir ?? outDir,
+          kind: 'server',
+          entryPath: page.filePath,
+          outFile,
+          esbuildOptions: jsxEsbuildOptions(page.filePath, outFile, target),
+          esbuild,
+          devMode,
+          minify,
+        });
+        resultMap.set(page.pattern, path.relative(outDir, outFile).replace(/\\/g, '/'));
+      }),
+    ),
   );
   return resultMap;
 }
 
-async function buildLayoutServerBundles(layouts, outDir, target, { rootDir, devMode, minify } = {}) {
+async function buildLayoutServerBundles(layouts, outDir, target, { rootDir, devMode, minify, limit = identityLimit } = {}) {
   const serverDir = path.join(outDir, 'server');
   const resultMap = new Map();
   await Promise.all(
-    layouts.map(async (layout) => {
-      const outName = layoutDirToFileName(layout.dirPath);
-      const outFile = path.join(serverDir, `_layout_${outName}.js`);
-      await buildWithCache({
-        rootDir: rootDir ?? outDir,
-        kind: 'layout',
-        entryPath: layout.filePath,
-        outFile,
-        esbuildOptions: jsxEsbuildOptions(layout.filePath, outFile, target),
-        esbuild,
-        devMode,
-        minify,
-      });
-      resultMap.set(layout.dirPath, path.relative(outDir, outFile).replace(/\\/g, '/'));
-    }),
+    layouts.map((layout) =>
+      limit(async () => {
+        const outName = layoutDirToFileName(layout.dirPath);
+        const outFile = path.join(serverDir, `_layout_${outName}.js`);
+        await buildWithCache({
+          rootDir: rootDir ?? outDir,
+          kind: 'layout',
+          entryPath: layout.filePath,
+          outFile,
+          esbuildOptions: jsxEsbuildOptions(layout.filePath, outFile, target),
+          esbuild,
+          devMode,
+          minify,
+        });
+        resultMap.set(layout.dirPath, path.relative(outDir, outFile).replace(/\\/g, '/'));
+      }),
+    ),
   );
   return resultMap;
 }
 
-async function buildMiddlewareServerBundles(middlewares, outDir, target, { rootDir, devMode, minify } = {}) {
+async function buildMiddlewareServerBundles(middlewares, outDir, target, { rootDir, devMode, minify, limit = identityLimit } = {}) {
   const serverDir = path.join(outDir, 'server');
   const resultMap = new Map();
   await Promise.all(
-    middlewares.map(async (mw) => {
-      const outName = layoutDirToFileName(mw.dirPath);
-      const outFile = path.join(serverDir, `_middleware_${outName}.js`);
-      await buildWithCache({
-        rootDir: rootDir ?? outDir,
-        kind: 'middleware',
-        entryPath: mw.filePath,
-        outFile,
-        esbuildOptions: plainEsbuildOptions(mw.filePath, outFile, target),
-        esbuild,
-        devMode,
-        minify,
-      });
-      resultMap.set(mw.dirPath, path.relative(outDir, outFile).replace(/\\/g, '/'));
-    }),
+    middlewares.map((mw) =>
+      limit(async () => {
+        const outName = layoutDirToFileName(mw.dirPath);
+        const outFile = path.join(serverDir, `_middleware_${outName}.js`);
+        await buildWithCache({
+          rootDir: rootDir ?? outDir,
+          kind: 'middleware',
+          entryPath: mw.filePath,
+          outFile,
+          esbuildOptions: plainEsbuildOptions(mw.filePath, outFile, target),
+          esbuild,
+          devMode,
+          minify,
+        });
+        resultMap.set(mw.dirPath, path.relative(outDir, outFile).replace(/\\/g, '/'));
+      }),
+    ),
   );
   return resultMap;
 }
 
-async function buildErrorPageBundles(errorPages, outDir, target, { rootDir, devMode, minify } = {}) {
+async function buildErrorPageBundles(errorPages, outDir, target, { rootDir, devMode, minify, limit = identityLimit } = {}) {
   const serverDir = path.join(outDir, 'server');
   const result = {};
   const builds = [];
@@ -125,20 +138,22 @@ async function buildErrorPageBundles(errorPages, outDir, target, { rootDir, devM
     builds.push({ filePath: errorPages.notFoundPage, outName: '_404', key: 'notFound' });
   }
   await Promise.all(
-    builds.map(async (build) => {
-      const outFile = path.join(serverDir, `${build.outName}.js`);
-      await buildWithCache({
-        rootDir: rootDir ?? outDir,
-        kind: 'errorPage',
-        entryPath: build.filePath,
-        outFile,
-        esbuildOptions: jsxEsbuildOptions(build.filePath, outFile, target),
-        esbuild,
-        devMode,
-        minify,
-      });
-      result[build.key] = path.relative(outDir, outFile);
-    }),
+    builds.map((build) =>
+      limit(async () => {
+        const outFile = path.join(serverDir, `${build.outName}.js`);
+        await buildWithCache({
+          rootDir: rootDir ?? outDir,
+          kind: 'errorPage',
+          entryPath: build.filePath,
+          outFile,
+          esbuildOptions: jsxEsbuildOptions(build.filePath, outFile, target),
+          esbuild,
+          devMode,
+          minify,
+        });
+        result[build.key] = path.relative(outDir, outFile);
+      }),
+    ),
   );
   return result;
 }
@@ -148,6 +163,8 @@ export {
   buildLayoutServerBundles,
   buildMiddlewareServerBundles,
   buildServerBundles,
+  jsxEsbuildOptions,
   layoutDirToFileName,
   patternToFileName,
+  plainEsbuildOptions,
 };

package/server/pages/build.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import fs from 'node:fs/promises';
 import crypto from 'node:crypto';
+import pLimit from 'p-limit';
 import {
   discoverPages,
   discoverLayouts,
@@ -21,6 +22,33 @@ 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';
+// Resolve the effective build-concurrency bound for a `buildPages()` call.
+// Precedence: explicit `options.concurrency` → `ARCWAY_BUILD_CONCURRENCY` env
+// → `Infinity` (unbounded, today's behavior). Only positive integers count;
+// anything else (NaN, 0, negatives, floats, non-numeric strings) falls through
+// so a typo can't accidentally throttle a real user's build.
+function resolveBuildConcurrency(optionValue) {
+  if (Number.isInteger(optionValue) && optionValue > 0) return optionValue;
+  const envRaw = process.env.ARCWAY_BUILD_CONCURRENCY;
+  if (envRaw) {
+    const trimmed = envRaw.trim();
+    if (/^\d+$/.test(trimmed)) {
+      const n = Number.parseInt(trimmed, 10);
+      if (Number.isInteger(n) && n > 0) return n;
+    }
+  }
+  return Infinity;
+}
+
+// When concurrency is Infinity we return a zero-overhead identity wrapper so
+// `limit(fn)` is byte-equivalent to calling `fn()` directly — no `p-limit`
+// queue allocation, no semantic change from today's unbounded `Promise.all`.
+function createLimit(concurrency) {
+  if (concurrency === Infinity) return (fn) => fn();
+  return pLimit(concurrency);
+}
+
 async function buildPages(options) {
   const { rootDir } = options;
   const pagesDir = options.pagesDir ?? path.join(rootDir, 'pages');
@@ -29,6 +57,7 @@ async function buildPages(options) {
   const clientTarget = options.clientTarget ?? 'es2022';
   const minify = options.minify ?? true;
   const devMode = options.devMode ?? false;
+  const limit = createLimit(resolveBuildConcurrency(options.concurrency));
   const [pages, layouts, loadings, middlewares, errorPages, stylesPath] = await Promise.all([
     discoverPages(pagesDir),
     discoverLayouts(pagesDir),
@@ -38,7 +67,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
@@ -58,7 +87,7 @@ async function buildPages(options) {
       if (fontResult.fontFaceCss) fontFaceCss = fontResult.fontFaceCss;
       if (fontResult.preloadHtml) fontPreloadHtml = fontResult.preloadHtml;
     }
-    const serverCacheOpts = { rootDir, devMode, minify };
+    const serverCacheOpts = { rootDir, devMode, minify, limit };
     builds.push(
       buildServerBundles(pages, buildDir, serverTarget, serverCacheOpts),
       buildLayoutServerBundles(layouts, buildDir, serverTarget, serverCacheOpts),
@@ -73,9 +102,10 @@ async function buildPages(options) {
         loadings,
         minify ? 'production' : 'development',
         devMode,
+        limit,
       ),
       buildErrorPageBundles(errorPages, buildDir, serverTarget, serverCacheOpts),
-      buildCssBundle(pagesDir, buildDir, minify, stylesPath, fontFaceCss, rootDir),
+      buildCssBundle(pagesDir, buildDir, minify, stylesPath, fontFaceCss, rootDir, limit),
     );
     if (devMode) builds.push(buildHmrRuntimeBundle(buildDir));
     // Fail fast: `Promise.all` rejects the moment any build throws, so a broken
@@ -107,6 +137,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
@@ -183,4 +221,4 @@ function rewriteMetafilePaths(metafile, fromDir, toDir) {
   return { ...metafile, outputs };
 }
 import { patternToFileName } from './build-server.js';
-export { buildPages, patternToFileName, buildPagesIdle };
+export { buildPages, patternToFileName, buildPagesIdle, resolveBuildConcurrency, createLimit };

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/discovery.js

@@ -92,6 +92,103 @@ async function discoverErrorPages(pagesDir) {
   }
   return result;
 }
+// Given a changed file path and an in-memory pages manifest, return the set of
+// manifest entries whose server bundles must be rebuilt. Used by the lazy dev
+// context (#250) so a watcher file-change event can mark only the affected
+// pages/layouts/middlewares stale rather than forcing a full-graph rebuild.
+//
+// Cascade rules:
+//   - Page source edited → the one page whose `srcPath` matches.
+//   - Layout source edited → the layout itself plus every descendant page
+//     (any entry whose `layoutDirs` contains that layout's `dirPath`).
+//   - Middleware source edited → the middleware itself plus every descendant
+//     page (any entry whose `middlewareDirs` contains that middleware's
+//     `dirPath`).
+//   - Anything else → empty. Callers decide whether unrelated file changes
+//     warrant a full re-discovery (e.g. a new page file appeared).
+//
+// All path comparisons go through `path.resolve()` to normalize mixed
+// absolute/relative inputs. `manifest.layouts` and `manifest.middlewares` may
+// be supplied as Maps (the lazy context shape) or plain arrays of
+// `{ dirPath, srcPath }` tuples — both are handled.
+function mapFileToAffected(filePath, manifest) {
+  const result = { pages: [], layouts: [], middlewares: [] };
+  if (!filePath || !manifest) return result;
+  const target = path.resolve(filePath);
+  const entries = manifest.entries ?? [];
+
+  for (const entry of entries) {
+    if (entry.srcPath && path.resolve(entry.srcPath) === target) {
+      result.pages.push(entry.pattern);
+      return result;
+    }
+  }
+
+  const layoutEntries = asDirPathList(manifest.layouts);
+  const hitLayout = layoutEntries.find(
+    (l) => l.srcPath && path.resolve(l.srcPath) === target,
+  );
+  if (hitLayout) {
+    result.layouts.push(hitLayout.dirPath);
+    for (const entry of entries) {
+      if ((entry.layoutDirs ?? []).includes(hitLayout.dirPath)) {
+        result.pages.push(entry.pattern);
+      }
+    }
+    return result;
+  }
+
+  const middlewareEntries = asDirPathList(manifest.middlewares);
+  const hitMw = middlewareEntries.find(
+    (m) => m.srcPath && path.resolve(m.srcPath) === target,
+  );
+  if (hitMw) {
+    result.middlewares.push(hitMw.dirPath);
+    for (const entry of entries) {
+      if ((entry.middlewareDirs ?? []).includes(hitMw.dirPath)) {
+        result.pages.push(entry.pattern);
+      }
+    }
+    return result;
+  }
+
+  return result;
+}
+
+// Accept either Map<dirPath, { srcPath, … }> (lazy context shape) or a plain
+// array of `{ dirPath, srcPath }` tuples (what `discoverLayouts` emits) so the
+// helper works from either side of the refactor without adaptor code.
+function asDirPathList(source) {
+  if (!source) return [];
+  if (Array.isArray(source)) return source;
+  if (source instanceof Map) {
+    return Array.from(source, ([dirPath, value]) => ({ dirPath, ...value }));
+  }
+  return [];
+}
+
+// Construct an in-memory manifest entry for a page. Shared between the
+// lazy context's initial discovery pass and `rediscover()` so both code
+// paths produce structurally identical entries (same chain resolution,
+// same default flags). Resolves layout/middleware/loading dirs against
+// the discovered chain lists rather than the in-memory manifest, which
+// keeps the helper pure.
+function buildPageManifestEntry(page, { layouts, middlewares, loadings }) {
+  return {
+    pattern: page.pattern,
+    paramNames: page.paramNames,
+    ...(page.catchAllParam ? { catchAllParam: page.catchAllParam } : {}),
+    srcPath: path.resolve(page.filePath),
+    layoutDirs: resolveLayoutChain(page.pattern, layouts).map((l) => l.dirPath),
+    middlewareDirs: resolvePageMiddlewareChain(page.pattern, middlewares).map((m) => m.dirPath),
+    loadingDirs: resolveLoadingChain(page.pattern, loadings).map((l) => l.dirPath),
+    sharedChunks: [],
+    sharedCssChunks: [],
+    built: false,
+    stale: false,
+  };
+}
+
 async function discoverStyles(pagesDir) {
   const stylesPath = path.join(pagesDir, '_styles.css');
   try {
@@ -107,12 +204,14 @@ function matchPage(pages, pathname) {
   return { page: result.match, params: result.params };
 }
 export {
+  buildPageManifestEntry,
   discoverErrorPages,
   discoverLayouts,
   discoverLoadings,
   discoverPageMiddleware,
   discoverPages,
   discoverStyles,
+  mapFileToAffected,
   matchPage,
   resolveLayoutChain,
   resolveLoadingChain,