arcway 0.1.21 → 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/package.json

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

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

@@ -351,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');
@@ -394,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) {

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-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,
@@ -22,6 +23,32 @@ 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');
@@ -30,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),
@@ -59,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),
@@ -74,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
@@ -192,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 };