arcway 0.1.20 → 0.1.22

package/README.md

@@ -96,6 +96,10 @@ project-root/
 ├── listeners/                    # Event subscribers (folder path = event name)
 │   └── users/
 │       └── created.js            # Handles 'users/created' event
+├── hooks/                        # Lifecycle hooks (init / ready / shutdown)
+│   ├── init.js                   # Runs before listeners/jobs/routers are wired
+│   ├── ready.js                  # Runs after the server is listening
+│   └── shutdown.js               # Runs at the top of graceful shutdown
 ├── jobs/                         # Background job definitions
 │   └── send-welcome-email.js
 ├── migrations/                   # Database migrations (timestamp-ordered)
@@ -135,6 +139,15 @@ export default {
   database: {
     client: 'postgres',     // 'sqlite', 'postgres', 'mysql'
     connection: 'postgres://user:pass@localhost/mydb',
+    hooks: {                // Forwarded verbatim to knex — postProcessResponse,
+                            // wrapIdentifier, asyncStackTraces, log, debug.
+      postProcessResponse: (result, ctx) => {
+        if (ctx?.table === 'users' && Array.isArray(result)) {
+          return result.map((row) => ({ ...row, createdAt: new Date(row.created_at) }));
+        }
+        return result;
+      },
+    },
   },
   session: {
     password: 'at-least-32-character-secret-here!!',
@@ -253,6 +266,38 @@ export const POST = {
 };
 ```
 
+### Database hooks & per-table decoding
+
+Knex's `postProcessResponse` hook (plus `wrapIdentifier`, `log`, `debug`, and
+`asyncStackTraces`) can be set under `database.hooks` in `arcway.config.js` and
+are forwarded to the underlying knex instance.
+
+To make `postProcessResponse` useful without threading context at every call
+site, arcway auto-stamps `.queryContext({ table })` on every `ctx.db(name)`
+builder. Your hook can key on `ctx.table` to decode rows centrally:
+
+```js
+// arcway.config.js
+database: {
+  hooks: {
+    postProcessResponse: (result, ctx) => {
+      if (!ctx?.table || !Array.isArray(result)) return result;
+      const decode = decoders[ctx.table];
+      return decode ? result.map(decode) : result;
+    },
+  },
+},
+```
+
+`ctx.db.raw(...)`, `ctx.db({ alias: ... })`, and subquery builders are not
+stamped — hooks should pass those through with `if (!ctx?.table) return result`.
+To carry additional context alongside the auto-stamp, merge instead of replace:
+
+```js
+const builder = ctx.db('orders');
+builder.queryContext({ ...builder.queryContext(), userId: ctx.req.session.userId });
+```
+
 ### Handler Context
 
 Every route handler receives a `ctx` object with infrastructure and request data:
@@ -410,21 +455,37 @@ export default async (ctx) => {
 
 The listener context includes all infrastructure (`db`, `events`, `cache`, `queue`, `files`, `mail`, `log`) plus `event: { name, payload }`.
 
-### System Lifecycle Events
+## Lifecycle Hooks
 
-Special listeners in `listeners/system/` handle lifecycle events:
+Lifecycle hooks live in the top-level `hooks/` directory. Each file default-exports an `async` function that receives the **real, mutable `appContext`** — the same object downstream subsystems (listeners, jobs, routes) read services from at call time. Mutations (e.g. wrapping `appContext.db`) persist for the lifetime of the process.
+
+```
+project-root/
+└── hooks/
+    ├── init.js      — after infrastructure, before listeners/jobs/routers are wired
+    ├── ready.js     — after the HTTP server is listening and the job runner has started
+    └── shutdown.js  — at the top of graceful shutdown, before any teardown
+```
 
 ```js
-// listeners/system/init.js — runs before server starts
-export default async (ctx) => { /* setup */ };
+// hooks/init.js — wrap services, register global resources
+export default async (appContext) => {
+  appContext.db = wrapWithTenancy(appContext.db);
+};
 
-// listeners/system/ready.js — runs after server is listening
-export default async (ctx) => { /* post-boot */ };
+// hooks/ready.js — post-boot work (warmups, one-shot recovery)
+export default async (appContext) => {
+  await recoverOrphanedTasks(appContext);
+};
 
-// listeners/system/shutdown.js — runs during graceful shutdown
-export default async (ctx) => { /* cleanup */ };
+// hooks/shutdown.js — flush and cleanup before infrastructure is destroyed
+export default async (appContext) => {
+  await appContext.cache.flush();
+};
 ```
 
+Hooks are optional — missing files are silently skipped. An existing file must default-export a function; otherwise boot fails fast.
+
 ## Jobs
 
 Background jobs support one-off queuing and cron scheduling.

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.20",
+  "version": "0.1.22",
   "description": "A convention-based framework for building modular monoliths with strict domain boundaries.",
   "license": "MIT",
   "type": "module",
@@ -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/boot/hooks.js

@@ -0,0 +1,19 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { loadModule } from '../module-loader.js';
+
+async function runHook(name, appContext, rootDir) {
+  const filePath = path.join(rootDir, 'hooks', `${name}.js`);
+  try {
+    await fs.access(filePath);
+  } catch {
+    return;
+  }
+  const mod = await loadModule(filePath);
+  if (typeof mod.default !== 'function') {
+    throw new Error(`hooks/${name}.js must default-export an async function`);
+  }
+  await mod.default(appContext);
+}
+
+export { runHook };

package/server/boot/index.js

@@ -13,6 +13,7 @@ import { SystemRouter } from '../system-routes/index.js';
 import { StaticRouter } from '../static/index.js';
 import { WsRouter } from '../ws/ws-router.js';
 import { createWsBackplane } from '../ws/backplane.js';
+import { runHook } from './hooks.js';
 import path from 'node:path';
 
 async function boot(options) {
@@ -25,14 +26,25 @@ async function boot(options) {
   const infrastructure = await createInfrastructure(config, { runMigrations: true });
   const { db, redis, queue, cache, files, mail, events, log } = infrastructure;
 
-  const mcpRouter = new McpRouter(config.mcp, { log });
-
   if (envFiles.length > 0) log.info('Env files loaded', { envFiles });
 
+  const fileWatcher = mode === 'development' ? new FileWatcher(rootDir, { log }) : null;
+  if (fileWatcher) await fileWatcher.start();
+
+  // Single mutable appContext reference. Handed to every subsystem that needs
+  // framework services and to the init/ready/shutdown hooks. Mutations from
+  // the init hook (e.g. wrapping `appContext.db`) persist for process lifetime
+  // because downstream consumers read properties off this reference at use time.
+  const appContext = { db, redis, events, queue, cache, files, mail, log, fileWatcher };
+
+  await runHook('init', appContext, rootDir);
+
+  const mcpRouter = new McpRouter(config.mcp, { log });
+
   const eventHandler = new EventHandler(config.events, {
     events,
     log,
-    appContext: { db, events, queue, cache, files, mail, log },
+    appContext,
   });
   await eventHandler.init();
 
@@ -60,11 +72,6 @@ async function boot(options) {
   });
   await jobRunner.init();
 
-  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 };
-
   // ── Routers ──
 
   const apiRouter = new ApiRouter(config.api, {
@@ -115,7 +122,10 @@ async function boot(options) {
 
   jobRunner.start();
 
+  await runHook('ready', appContext, rootDir);
+
   const shutdown = async () => {
+    await runHook('shutdown', appContext, rootDir);
     await jobRunner.shutdown();
     if (workerPool) await workerPool.shutdown();
     await pagesRouter.close();

package/server/context.js

@@ -18,6 +18,16 @@ function trackDb(db) {
     apply(target, thisArg, args) {
       const builder = Reflect.apply(target, thisArg, args);
       if (builder && typeof builder.then === 'function' && typeof builder.select === 'function') {
+        // Auto-stamp `.queryContext({ table })` for the canonical `db(name)` form
+        // so `postProcessResponse(result, ctx)` hooks can route on table without
+        // every call site having to thread it manually. Only stamp when the
+        // first arg is a string table name — db({ alias: … }) / db.raw(…) /
+        // subquery forms intentionally carry no table. Guard on queryContext
+        // existence so mock builders without it (see context tests) still work.
+        const [name] = args;
+        if (typeof name === 'string' && typeof builder.queryContext === 'function') {
+          builder.queryContext({ table: name });
+        }
         return wrapBuilder(builder, stats);
       }
       return builder;

package/server/db/index.js

@@ -26,12 +26,21 @@ async function createDB(config, { log } = {}) {
   const client = config.client;
   const isSqlite = client === 'better-sqlite3' || client === 'sqlite3';
   const connection = config.connection;
+  // Knex top-level hooks (postProcessResponse, wrapIdentifier, asyncStackTraces,
+  // log, debug) control per-query/row transformations and are forwarded verbatim
+  // from `config.hooks`. `hooks` is spread *first* so arcway's own keys
+  // (client/connection/useNullAsDefault) always win — user error can't reroute
+  // the client or break the sqlite default. The canonical use case is a
+  // `postProcessResponse(result, ctx)` that reads `ctx.table` (auto-stamped in
+  // context.js) to decode rows without per-call-site boilerplate.
+  const hooks = config.hooks ?? {};
 
   if (isSqlite && connection?.filename) {
     fsSync.mkdirSync(path.dirname(connection.filename), { recursive: true });
   }
 
   const db = knex({
+    ...hooks,
     client,
     connection,
     ...(isSqlite ? { useNullAsDefault: true } : {}),

package/server/events/handler.js

@@ -51,7 +51,6 @@ class EventHandler {
       if (!exported) throw new Error(`Listener file at ${filePath} must have a default export`);
 
       const event = listenerPathToEvent(relativePath);
-      if (event.startsWith('system/') || event === 'system') continue;
 
       const items = Array.isArray(exported) ? exported : [exported];
       for (let i = 0; i < items.length; i++) {

package/server/pages/arcway-endpoint.js

@@ -0,0 +1,58 @@
+// Dev-only internal endpoints under `/_arcway/*`. A thin sync view over the
+// lazy build context: manifest.json is a single JSON snapshot; `events` is an
+// SSE stream of `update` events (built / invalidate / startup). Consumers
+// include dev overlays, prefetchers, and any tooling that wants real-time
+// build state without polling.
+//
+// The endpoint returns `true` if it handled the request, so the caller can
+// chain it in front of the route matcher and bail out before any page
+// rendering happens. Anything outside `/_arcway/*` is a pass-through.
+
+function createArcwayDevEndpoint(lazyContext) {
+  return function handle(req, res) {
+    const method = req.method ?? 'GET';
+    if (method !== 'GET') return false;
+    const url = req.url ?? '/';
+    const pathname = url.split('?')[0];
+
+    if (pathname === '/_arcway/manifest.json') {
+      const snapshot = lazyContext.getManifestJson();
+      const body = JSON.stringify(snapshot);
+      res.writeHead(200, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Cache-Control': 'no-store',
+        'Content-Length': Buffer.byteLength(body),
+      });
+      res.end(body);
+      return true;
+    }
+
+    if (pathname === '/_arcway/events') {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream; charset=utf-8',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive',
+        // Disables proxy buffering (nginx, etc.) so events arrive in real
+        // time in dev. Harmless when no proxy sits in front.
+        'X-Accel-Buffering': 'no',
+      });
+      // Retry directive + initial comment keeps EventSource from opening a
+      // second connection if the first one stalls before the first event.
+      res.write('retry: 2000\n\n');
+      res.write(': connected\n\n');
+
+      const off = lazyContext.on('update', (event) => {
+        if (res.writableEnded) return;
+        res.write(`event: update\ndata: ${JSON.stringify(event)}\n\n`);
+      });
+      req.on('close', () => {
+        off();
+      });
+      return true;
+    }
+
+    return false;
+  };
+}
+
+export { createArcwayDevEndpoint };

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 };
@@ -278,6 +351,7 @@ async function buildClientBundles(
   loadings = [],
   nodeEnv = 'production',
   devMode = false,
+  limit = (fn) => fn(),
 ) {
   const clientDir = path.join(outDir, 'client');
   const tempDir = path.join(outDir, '.hydration-entries');
@@ -321,7 +395,7 @@ async function buildClientBundles(
     reactAlias,
     rootDir,
   });
-  const result = await runClientEsbuild(plan, esbuildOptions, tempDir);
+  const result = await limit(() => runClientEsbuild(plan, esbuildOptions, tempDir));
   const metadata = extractMetadata(result, plan, outDir);
 
   if (useCache) {
@@ -346,32 +420,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;
     }