arcway 0.1.15 → 0.1.16

package/client/page-loader.js

@@ -1,3 +1,5 @@
+import { compileRoutePattern, extractRouteParams } from './route-pattern.js';
+
 const moduleCache = new Map();
 const patternCache = new Map();
 
@@ -34,43 +36,11 @@ function readClientManifest() {
   }
 }
 
-function compilePattern(pattern) {
-  const paramNames = [];
-  let catchAllParam;
-
-  const regexStr = pattern.replace(
-    /\/:([^/]+)|\/\*(\w+)\?|\/\*(\w+)/g,
-    (match, singleParam, optCatchAll, reqCatchAll) => {
-      if (singleParam) {
-        paramNames.push(singleParam);
-        return '/([^/]+)';
-      }
-      if (optCatchAll) {
-        paramNames.push(optCatchAll);
-        catchAllParam = optCatchAll;
-        return '(?:/(.+))?';
-      }
-      if (reqCatchAll) {
-        paramNames.push(reqCatchAll);
-        catchAllParam = reqCatchAll;
-        return '/(.+)';
-      }
-      return match;
-    },
-  );
-
-  return {
-    regex: new RegExp(`^${regexStr}\\/?$`),
-    paramNames,
-    catchAllParam,
-  };
-}
-
 function matchClientRoute(manifest, pathname) {
   for (const route of manifest.routes) {
     let compiled = patternCache.get(route.pattern);
     if (!compiled) {
-      compiled = compilePattern(route.pattern);
+      compiled = compileRoutePattern(route.pattern);
       patternCache.set(route.pattern, compiled);
     }
     const { regex, paramNames, catchAllParam } = compiled;
@@ -78,20 +48,8 @@ function matchClientRoute(manifest, pathname) {
     const match = regex.exec(pathname);
     if (!match) continue;
 
-    const params = {};
-    try {
-      for (let i = 0; i < paramNames.length; i++) {
-        const name = paramNames[i];
-        const raw = match[i + 1];
-        if (name === catchAll) {
-          params[name] = raw ? raw.split('/').map(decodeURIComponent) : [];
-        } else {
-          params[name] = decodeURIComponent(raw);
-        }
-      }
-    } catch {
-      continue;
-    }
+    const params = extractRouteParams(match, paramNames, catchAll);
+    if (!params) continue;
 
     return { route, params };
   }
@@ -146,7 +104,6 @@ async function loadPage(manifest, pathname) {
 }
 
 export {
-  compilePattern,
   loadLoadingComponents,
   loadPage,
   matchClientRoute,

package/client/route-pattern.js

@@ -0,0 +1,48 @@
+function compileRoutePattern(pattern) {
+  const paramNames = [];
+  let catchAllParam;
+  let isOptionalCatchAll = false;
+  const regexStr = pattern.replace(
+    /\/:([^/]+)|\/\*(\w+)\?|\/\*(\w+)/g,
+    (match, singleParam, optCatchAll, reqCatchAll) => {
+      if (singleParam) {
+        paramNames.push(singleParam);
+        return '/([^/]+)';
+      }
+      if (optCatchAll) {
+        paramNames.push(optCatchAll);
+        catchAllParam = optCatchAll;
+        isOptionalCatchAll = true;
+        return '(?:/(.+))?';
+      }
+      if (reqCatchAll) {
+        paramNames.push(reqCatchAll);
+        catchAllParam = reqCatchAll;
+        return '/(.+)';
+      }
+      return match;
+    },
+  );
+  const regex = new RegExp(`^${regexStr}/?$`);
+  return { regex, paramNames, catchAllParam, isOptionalCatchAll };
+}
+
+function extractRouteParams(match, paramNames, catchAllParam) {
+  const params = {};
+  try {
+    for (let i = 0; i < paramNames.length; i++) {
+      const name = paramNames[i];
+      const raw = match[i + 1];
+      if (name === catchAllParam) {
+        params[name] = raw ? raw.split('/').map(decodeURIComponent) : [];
+      } else {
+        params[name] = decodeURIComponent(raw);
+      }
+    }
+  } catch {
+    return null;
+  }
+  return params;
+}
+
+export { compileRoutePattern, extractRouteParams };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcway",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "A convention-based framework for building modular monoliths with strict domain boundaries.",
   "license": "MIT",
   "type": "module",
@@ -96,7 +96,6 @@
     "swr": "^2.3.3",
     "tailwind-merge": "^3.4.1",
     "tailwindcss": "^4.1.18",
-    "tailwindcss-animate": "^1.0.7",
     "vaul": "^1.1.2",
     "ws": "^8.19.0",
     "zod": "^3.24.0"
@@ -114,10 +113,8 @@
     }
   },
   "devDependencies": {
-    "@chromatic-com/storybook": "^5.0.1",
     "@storybook/addon-a11y": "^10.2.8",
     "@storybook/addon-docs": "^10.2.8",
-    "@storybook/addon-onboarding": "^10.2.8",
     "@storybook/addon-vitest": "^10.2.8",
     "@storybook/react-vite": "^10.2.8",
     "@tailwindcss/vite": "^4.1.18",

package/server/docs/openapi.js

@@ -50,6 +50,89 @@ function buildQueryParameters(route) {
     return [];
   }
 }
+function buildOperationId(method, openApiPath) {
+  const path = openApiPath.replace(/[{}\/]/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '');
+  return `${method}_${path}`;
+}
+
+function tryConvertSchema(schema) {
+  if (!schema) return undefined;
+  try {
+    return typeToOpenAPISchema(schema);
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveTags(route) {
+  const tags = route.config.meta?.tags;
+  if (tags && tags.length > 0) return tags;
+  return [route.pattern.split('/')[1] || 'default'];
+}
+
+function buildRequestBody(bodySchema) {
+  const converted = tryConvertSchema(bodySchema);
+  if (!converted) return undefined;
+  return {
+    required: true,
+    content: { 'application/json': { schema: converted } },
+  };
+}
+
+const VALIDATION_ERROR_RESPONSE = {
+  description: 'Validation error',
+  content: {
+    'application/json': {
+      schema: {
+        type: 'object',
+        properties: {
+          error: {
+            type: 'object',
+            properties: {
+              code: { type: 'string' },
+              message: { type: 'string' },
+              details: {},
+            },
+          },
+        },
+      },
+    },
+  },
+};
+
+const DEFAULT_SUCCESS_SCHEMA = { type: 'object', properties: { data: {} } };
+
+function buildResponses(routeSchema) {
+  const successSchema = tryConvertSchema(routeSchema?.response) ?? DEFAULT_SUCCESS_SCHEMA;
+  const responses = {
+    200: {
+      description: 'Successful response',
+      content: { 'application/json': { schema: successSchema } },
+    },
+  };
+  if (routeSchema?.body || routeSchema?.query) {
+    responses[400] = VALIDATION_ERROR_RESPONSE;
+  }
+  return responses;
+}
+
+function buildOperation(route, method, openApiPath) {
+  const operation = { operationId: buildOperationId(method, openApiPath) };
+  const meta = route.config.meta;
+  if (meta?.summary) operation.summary = meta.summary;
+  if (meta?.description) operation.description = meta.description;
+  operation.tags = resolveTags(route);
+
+  const parameters = [...buildPathParameters(route), ...buildQueryParameters(route)];
+  if (parameters.length > 0) operation.parameters = parameters;
+
+  const requestBody = buildRequestBody(route.config.schema?.body);
+  if (requestBody) operation.requestBody = requestBody;
+
+  operation.responses = buildResponses(route.config.schema);
+  return operation;
+}
+
 function generateOpenAPISpec(routes, info) {
   const spec = {
     openapi: '3.0.3',
@@ -63,90 +146,8 @@ function generateOpenAPISpec(routes, info) {
   for (const route of routes) {
     const openApiPath = toOpenAPIPath(route.pattern);
     const method = route.method.toLowerCase();
-    if (!spec.paths[openApiPath]) {
-      spec.paths[openApiPath] = {};
-    }
-    const operation = {
-      operationId: `${method}_${openApiPath
-        .replace(/[{}\/]/g, '_')
-        .replace(/_+/g, '_')
-        .replace(/^_|_$/g, '')}`,
-    };
-    const meta = route.config.meta;
-    if (meta?.summary) operation.summary = meta.summary;
-    if (meta?.description) operation.description = meta.description;
-    if (meta?.tags && meta.tags.length > 0) {
-      operation.tags = meta.tags;
-    } else {
-      const firstSegment = route.pattern.split('/')[1] || 'default';
-      operation.tags = [firstSegment];
-    }
-    const parameters = [...buildPathParameters(route), ...buildQueryParameters(route)];
-    if (parameters.length > 0) {
-      operation.parameters = parameters;
-    }
-    if (route.config.schema?.body) {
-      try {
-        const bodySchema = typeToOpenAPISchema(route.config.schema.body);
-        operation.requestBody = {
-          required: true,
-          content: {
-            'application/json': {
-              schema: bodySchema,
-            },
-          },
-        };
-      } catch {}
-    }
-    const responseSchema = route.config.schema?.response
-      ? (() => {
-          try {
-            return typeToOpenAPISchema(route.config.schema.response);
-          } catch {
-            return void 0;
-          }
-        })()
-      : void 0;
-    operation.responses = {
-      200: {
-        description: 'Successful response',
-        content: {
-          'application/json': {
-            schema: responseSchema ?? {
-              type: 'object',
-              properties: {
-                data: {},
-              },
-            },
-          },
-        },
-      },
-      ...(route.config.schema?.body || route.config.schema?.query
-        ? {
-            400: {
-              description: 'Validation error',
-              content: {
-                'application/json': {
-                  schema: {
-                    type: 'object',
-                    properties: {
-                      error: {
-                        type: 'object',
-                        properties: {
-                          code: { type: 'string' },
-                          message: { type: 'string' },
-                          details: {},
-                        },
-                      },
-                    },
-                  },
-                },
-              },
-            },
-          }
-        : {}),
-    };
-    spec.paths[openApiPath][method] = operation;
+    if (!spec.paths[openApiPath]) spec.paths[openApiPath] = {};
+    spec.paths[openApiPath][method] = buildOperation(route, method, openApiPath);
   }
   return spec;
 }

package/server/logger/index.js

@@ -22,6 +22,23 @@ function wrapPino(p) {
   };
 }
 
+const QUERY_FILTERS = {
+  level: (v) => (e) => e.level === v,
+  logger: (v) => (e) => e.logger === v,
+  requestId: (v) => (e) => e.data?.requestId === v,
+  message: (v) => (e) => e.message === v,
+  method: (v) => (e) => e.data?.method === v.toUpperCase(),
+  path: (v) => (e) => e.data?.path?.includes(v),
+  status: (v) => (e) => e.data?.status === v,
+  minDurationMs: (v) => (e) => e.data?.durationMs >= v,
+  eventName: (v) => (e) =>
+    e.data?.eventName === v || e.data?.eventName?.includes(v),
+  since: (v) => {
+    const sinceTs = new Date(v).getTime();
+    return (e) => new Date(e.timestamp).getTime() >= sinceTs;
+  },
+};
+
 class Logger {
   _base;
   _ring;
@@ -89,22 +106,13 @@ class Logger {
   query(filters) {
     if (!this._ring) return [];
     let entries = this._ring.toArray();
-    if (filters?.level) entries = entries.filter((e) => e.level === filters.level);
-    if (filters?.logger) entries = entries.filter((e) => e.logger === filters.logger);
-    if (filters?.requestId) entries = entries.filter((e) => e.data?.requestId === filters.requestId);
-    if (filters?.message) entries = entries.filter((e) => e.message === filters.message);
-    if (filters?.method) entries = entries.filter((e) => e.data?.method === filters.method.toUpperCase());
-    if (filters?.path) entries = entries.filter((e) => e.data?.path?.includes(filters.path));
-    if (filters?.status) entries = entries.filter((e) => e.data?.status === filters.status);
-    if (filters?.minDurationMs) entries = entries.filter((e) => e.data?.durationMs >= filters.minDurationMs);
-    if (filters?.eventName) {
-      entries = entries.filter((e) => e.data?.eventName === filters.eventName || e.data?.eventName?.includes(filters.eventName));
-    }
-    if (filters?.since) {
-      const sinceTs = new Date(filters.since).getTime();
-      entries = entries.filter((e) => new Date(e.timestamp).getTime() >= sinceTs);
+    if (!filters) return entries;
+    for (const [key, makePredicate] of Object.entries(QUERY_FILTERS)) {
+      const value = filters[key];
+      if (value === undefined || value === null || value === '' || value === false) continue;
+      entries = entries.filter(makePredicate(value));
     }
-    if (filters?.limit && filters.limit > 0) entries = entries.slice(-filters.limit);
+    if (filters.limit && filters.limit > 0) entries = entries.slice(-filters.limit);
     return entries;
   }
 

package/server/pages/build-cache.js

@@ -260,6 +260,52 @@ async function storeMultiFileCache({
   });
 }
 
+// Walk every cache entry in <rootDir>/node_modules/.cache/arcway-pages/<kind>
+// and drop any whose recorded inputs no longer hash to the stored value (or
+// whose inputs are gone). Used by tests that intentionally mutate fixture
+// sources to keep cross-fork cache state consistent. Best-effort: missing
+// bucket → returns {removed: 0, kept: 0}; individual unlink failures are
+// swallowed since a concurrent worker may already be removing the same entry.
+async function pruneStaleCache({ rootDir, kind }) {
+  const bucket = bucketDir(rootDir, kind);
+  let entries;
+  try {
+    entries = await fs.readdir(bucket);
+  } catch (err) {
+    if (err.code === 'ENOENT') return { removed: 0, kept: 0 };
+    throw err;
+  }
+
+  const metaFiles = entries.filter((f) => f.endsWith('.meta.json'));
+  let removed = 0;
+  let kept = 0;
+
+  for (const metaFile of metaFiles) {
+    const metaPath = path.join(bucket, metaFile);
+    const meta = await readJson(metaPath);
+    const stale =
+      !meta ||
+      !Array.isArray(meta.inputs) ||
+      (await hashInputs(meta.inputs)) !== meta.inputsHash;
+
+    if (!stale) {
+      kept += 1;
+      continue;
+    }
+
+    const baseKey = metaFile.slice(0, -'.meta.json'.length);
+    await Promise.allSettled([
+      fs.rm(metaPath, { force: true }),
+      fs.rm(path.join(bucket, `${baseKey}.js`), { force: true }),
+      fs.rm(path.join(bucket, `${baseKey}.js.map`), { force: true }),
+      fs.rm(path.join(bucket, baseKey), { recursive: true, force: true }),
+    ]);
+    removed += 1;
+  }
+
+  return { removed, kept };
+}
+
 export {
   buildWithCache,
   computeConfigHash,
@@ -269,6 +315,7 @@ export {
   sha256,
   hashInputs,
   lookupMultiFileCache,
+  pruneStaleCache,
   restoreMultiFileCache,
   storeMultiFileCache,
 };

package/server/pages/build-client.js

@@ -222,6 +222,52 @@ async function createClientBuildContext(
   return { rebuild, dispose };
 }
 
+async function tryRestoreClientFromCache({ rootDir, clientDir, coarseKey }) {
+  const lookup = await lookupMultiFileCache({ rootDir, kind: 'client', coarseKey });
+  if (!lookup.hit) return { hit: false, bucket: lookup.bucket };
+  await restoreMultiFileCache({
+    cacheDir: lookup.cacheDir,
+    outputs: lookup.meta.outputs,
+    destDir: clientDir,
+  });
+  return { hit: true, bucket: lookup.bucket, metadata: deserializeMetadata(lookup.meta.metadata) };
+}
+
+async function storeClientInCache({
+  bucket,
+  coarseKey,
+  clientDir,
+  tempDir,
+  result,
+  metadata,
+}) {
+  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,
+    coarseKey,
+    destDir: clientDir,
+    outputs,
+    inputs,
+    metadata: serializeMetadata(metadata),
+  });
+}
+
+async function runClientEsbuild(plan, esbuildOptions, tempDir) {
+  await fs.mkdir(tempDir, { recursive: true });
+  await writeHydrationEntries(plan);
+  const result = await esbuild.build(esbuildOptions);
+  await fs.rm(tempDir, { recursive: true, force: true });
+  return result;
+}
+
 async function buildClientBundles(
   pages,
   layouts,
@@ -238,76 +284,54 @@ async function buildClientBundles(
   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.
+  // devMode skips the cache because the watcher owns incremental rebuilds via
+  // esbuild.context(); we also return the metafile directly in dev for HMR diffing.
   const useCache = !devMode;
+  const coarseKey = useCache
+    ? computeClientCoarseKey({
+        target,
+        minify,
+        devMode,
+        nodeEnv,
+        reactAlias,
+        pages,
+        layouts,
+        loadings,
+        hydrationContents: plan.files.map((f) => ({
+          name: path.basename(f.entryPath),
+          content: f.content,
+        })),
+      })
+    : null;
+
   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);
-    }
+    const restored = await tryRestoreClientFromCache({ rootDir, clientDir, coarseKey });
+    if (restored.hit) return restored.metadata;
+    cacheBucket = restored.bucket;
   }
 
-  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 esbuildOptions = buildClientEsbuildOptions({
+    entryPoints: plan.entryPoints,
+    clientDir,
+    target,
+    minify,
+    devMode,
+    nodeEnv,
+    reactAlias,
+    rootDir,
+  });
+  const result = await runClientEsbuild(plan, esbuildOptions, tempDir);
   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({
+    await storeClientInCache({
       bucket: cacheBucket,
       coarseKey,
-      destDir: clientDir,
-      outputs,
-      inputs,
-      metadata: serializeMetadata(metadata),
+      clientDir,
+      tempDir,
+      result,
+      metadata,
     });
   }
 

package/server/pages/pages-router.js

@@ -1,4 +1,4 @@
-import { buildPages } from './build.js';
+import { createPagesBuildContext } from './build-context.js';
 import { createPagesHandler } from './handler.js';
 import { createPagesWatcher } from './watcher.js';
 
@@ -10,6 +10,7 @@ class PagesRouter {
   fileWatcher;
   handler = null;
   watcher = null;
+  pagesBuildContext = null;
 
   constructor(config, { rootDir, log, mode, fileWatcher, appContext }) {
     this.config = config;
@@ -26,14 +27,19 @@ class PagesRouter {
 
     let initialClientMetafile;
     if (isDev) {
+      // Dev mode owns a long-lived `createPagesBuildContext()` so the watcher
+      // can do incremental `ctx.rebuild()` on file change instead of a cold
+      // `buildPages()`. The initial rebuild bootstraps the outDir and captures
+      // the client metafile used for HMR diffs.
       try {
-        const result = await buildPages({
+        this.pagesBuildContext = await createPagesBuildContext({
           rootDir,
           pagesDir: config.pages.dir,
           fonts: config.pages?.fonts,
           minify: false,
           devMode: true,
         });
+        const result = await this.pagesBuildContext.rebuild();
         initialClientMetafile = result.clientMetafile;
       } catch (err) {
         log.error('Pages build failed', { error: String(err) });
@@ -59,6 +65,7 @@ class PagesRouter {
         fonts: config.pages?.fonts,
         initialClientMetafile,
         fileWatcher,
+        pagesBuildContext: this.pagesBuildContext,
       });
       log.info('Pages: watching for changes (HMR enabled)');
     }
@@ -74,6 +81,10 @@ class PagesRouter {
       await this.watcher.close();
       this.watcher = null;
     }
+    if (this.pagesBuildContext) {
+      await this.pagesBuildContext.dispose();
+      this.pagesBuildContext = null;
+    }
   }
 }
 

package/server/pages/watcher.js

@@ -3,13 +3,18 @@ import { buildPages } from './build.js';
 import { diffClientMetafiles } from './hmr.js';
 
 function createPagesWatcher(options) {
-  const { rootDir, handler, log, fonts, fileWatcher } = options;
+  const { rootDir, handler, log, fonts, fileWatcher, pagesBuildContext } = options;
   let building = false;
   let pendingRebuild = false;
   let pendingStructuralChange = false;
   let prevClientMetafile = options.initialClientMetafile;
   const outDir = path.resolve(rootDir, '.build/pages');
 
+  async function runBuild() {
+    if (pagesBuildContext) return pagesBuildContext.rebuild();
+    return buildPages({ rootDir, fonts, minify: false, devMode: true });
+  }
+
   async function rebuild(isStructuralChange) {
     if (building) {
       pendingRebuild = true;
@@ -19,7 +24,7 @@ function createPagesWatcher(options) {
     building = true;
     try {
       const start = Date.now();
-      const result = await buildPages({ rootDir, fonts, minify: false, devMode: true });
+      const result = await runBuild();
       handler.reload();
       const elapsed = Date.now() - start;
       if (handler.emitEvent && prevClientMetafile && result.clientMetafile && !isStructuralChange) {

package/server/router/api-router.js

@@ -1,7 +1,6 @@
-import { Readable } from 'node:stream';
-import { pipeline } from 'node:stream/promises';
 import { discoverRoutes, matchRoute, compilePattern } from './routes.js';
 import { discoverMiddleware, getMiddlewareForRoute, buildMiddlewareChain } from './middleware.js';
+import { sendJson, serializeResponse } from './http-helpers.js';
 import { ErrorCodes } from '../constants.js';
 import { sealSession, buildSessionSetCookie, buildSessionClearCookie } from '../session/index.js';
 import { flattenHeaders } from '../session/helpers.js';
@@ -31,54 +30,6 @@ function applyPrefix(routes, middleware, prefix) {
   }
 }
 
-function sendJson(res, statusCode, body, headers) {
-  const json = JSON.stringify(body);
-  res.writeHead(statusCode, {
-    'Content-Type': 'application/json',
-    'Content-Length': Buffer.byteLength(json),
-    ...headers,
-  });
-  res.end(json);
-}
-
-const validateRequest = validateRequestSchema;
-
-async function serializeResponse(res, response, responseHeaders, statusCode) {
-  const customContentType = responseHeaders['Content-Type'] || responseHeaders['content-type'];
-  if (!customContentType || customContentType.includes('application/json')) {
-    const responseBody = response.error ? { error: response.error } : (response.data ?? null);
-    sendJson(res, statusCode, responseBody, responseHeaders);
-    return;
-  }
-
-  const body = response.error
-    ? typeof response.error === 'string'
-      ? response.error
-      : JSON.stringify(response.error)
-    : (response.data ?? '');
-
-  if (Buffer.isBuffer(body)) {
-    res.writeHead(statusCode, { 'Content-Length': body.length, ...responseHeaders });
-    res.end(body);
-    return;
-  }
-  if (body instanceof Readable) {
-    res.writeHead(statusCode, responseHeaders);
-    await pipeline(body, res);
-    return;
-  }
-  if (typeof body === 'object' && body !== null && typeof body.getReader === 'function') {
-    const nodeStream = Readable.fromWeb(body);
-    res.writeHead(statusCode, responseHeaders);
-    await pipeline(nodeStream, res);
-    return;
-  }
-
-  const raw = typeof body === 'string' ? body : String(body);
-  res.writeHead(statusCode, { 'Content-Length': Buffer.byteLength(raw), ...responseHeaders });
-  res.end(raw);
-}
-
 class ApiRouter {
   _config;
   _log;
@@ -213,7 +164,7 @@ class ApiRouter {
 
     // ── Validation ──
     const mergedQuery = { ...(req.query ?? {}), ...params };
-    const validated = validateRequest(route.config.schema, mergedQuery, body);
+    const validated = validateRequestSchema(route.config.schema, mergedQuery, body);
     if (validated.error) {
       sendJson(res, 400, { error: validated.error });
       return true;

package/server/router/http-helpers.js

@@ -0,0 +1,107 @@
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { ErrorCodes } from '../constants.js';
+
+function readBody(req, maxBodySize) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let totalBytes = 0;
+    function cleanup() {
+      req.removeListener('data', onData);
+      req.removeListener('end', onEnd);
+      req.removeListener('error', onError);
+    }
+    function onData(chunk) {
+      totalBytes += chunk.length;
+      if (totalBytes > maxBodySize) {
+        cleanup();
+        req.destroy();
+        reject(new Error(ErrorCodes.BODY_TOO_LARGE));
+        return;
+      }
+      chunks.push(chunk);
+    }
+    function onEnd() {
+      cleanup();
+      resolve(Buffer.concat(chunks).toString('utf-8'));
+    }
+    function onError(err) {
+      cleanup();
+      reject(err);
+    }
+    req.on('data', onData);
+    req.on('end', onEnd);
+    req.on('error', onError);
+  });
+}
+
+function parseQuery(url) {
+  const idx = url.indexOf('?');
+  if (idx === -1) return {};
+  const params = new URLSearchParams(url.slice(idx + 1));
+  const result = {};
+  for (const [key, value] of params) {
+    result[key] = value;
+  }
+  return result;
+}
+
+function parseBody(rawBody, contentType) {
+  if (rawBody.length === 0) return undefined;
+  if (contentType.includes('application/json')) {
+    try {
+      return JSON.parse(rawBody);
+    } catch {
+      throw new Error(ErrorCodes.INVALID_JSON);
+    }
+  }
+  return rawBody;
+}
+
+function sendJson(res, statusCode, body, headers) {
+  const json = JSON.stringify(body);
+  res.writeHead(statusCode, {
+    'Content-Type': 'application/json',
+    'Content-Length': Buffer.byteLength(json),
+    ...headers,
+  });
+  res.end(json);
+}
+
+async function serializeResponse(res, response, responseHeaders, statusCode) {
+  const customContentType = responseHeaders['Content-Type'] || responseHeaders['content-type'];
+  if (!customContentType || customContentType.includes('application/json')) {
+    const responseBody = response.error ? { error: response.error } : (response.data ?? null);
+    sendJson(res, statusCode, responseBody, responseHeaders);
+    return;
+  }
+
+  const body = response.error
+    ? typeof response.error === 'string'
+      ? response.error
+      : JSON.stringify(response.error)
+    : (response.data ?? '');
+
+  if (Buffer.isBuffer(body)) {
+    res.writeHead(statusCode, { 'Content-Length': body.length, ...responseHeaders });
+    res.end(body);
+    return;
+  }
+  if (body instanceof Readable) {
+    res.writeHead(statusCode, responseHeaders);
+    await pipeline(body, res);
+    return;
+  }
+  if (typeof body === 'object' && body !== null && typeof body.getReader === 'function') {
+    const nodeStream = Readable.fromWeb(body);
+    res.writeHead(statusCode, responseHeaders);
+    await pipeline(nodeStream, res);
+    return;
+  }
+
+  const raw = typeof body === 'string' ? body : String(body);
+  res.writeHead(statusCode, { 'Content-Length': Buffer.byteLength(raw), ...responseHeaders });
+  res.end(raw);
+}
+
+export { readBody, parseQuery, parseBody, sendJson, serializeResponse };

package/server/router/routes.js

@@ -1,3 +1,4 @@
+import { compileRoutePattern, extractRouteParams } from '#client/route-pattern.js';
 import { discoverModules } from '../discovery.js';
 const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
 function filePathToPattern(relativePath) {
@@ -27,52 +28,13 @@ function matchPattern(items, pathname) {
   for (const item of items) {
     const m = item.regex.exec(pathname);
     if (!m) continue;
-    const params = {};
-    try {
-      for (let i = 0; i < item.paramNames.length; i++) {
-        const name = item.paramNames[i];
-        const raw = m[i + 1];
-        if (name === item.catchAllParam) {
-          params[name] = raw ? raw.split('/').map(decodeURIComponent) : [];
-        } else {
-          params[name] = decodeURIComponent(raw);
-        }
-      }
-    } catch {
-      continue;
-    }
+    const params = extractRouteParams(m, item.paramNames, item.catchAllParam);
+    if (!params) continue;
     return { match: item, params };
   }
   return null;
 }
-function compilePattern(pattern) {
-  const paramNames = [];
-  let catchAllParam;
-  let isOptionalCatchAll = false;
-  const regexStr = pattern.replace(
-    /\/:([^/]+)|\/\*(\w+)\?|\/\*(\w+)/g,
-    (match, singleParam, optCatchAll, reqCatchAll) => {
-      if (singleParam) {
-        paramNames.push(singleParam);
-        return '/([^/]+)';
-      }
-      if (optCatchAll) {
-        paramNames.push(optCatchAll);
-        catchAllParam = optCatchAll;
-        isOptionalCatchAll = true;
-        return '(?:/(.+))?';
-      }
-      if (reqCatchAll) {
-        paramNames.push(reqCatchAll);
-        catchAllParam = reqCatchAll;
-        return '/(.+)';
-      }
-      return match;
-    },
-  );
-  const regex = new RegExp(`^${regexStr}/?$`);
-  return { regex, paramNames, catchAllParam, isOptionalCatchAll };
-}
+const compilePattern = compileRoutePattern;
 async function discoverRoutes(apiDir) {
   const entries = await discoverModules(apiDir, { recursive: true, label: 'route file' });
   const routes = [];

package/server/web-server.js

@@ -1,55 +1,11 @@
 import { randomUUID } from 'node:crypto';
 import { createHttpServer, listen, closeServer } from './server.js';
 import { buildCorsHeaders, buildPreflightHeaders } from './router/cors.js';
+import { readBody, parseQuery, parseBody } from './router/http-helpers.js';
 import { parseCookies, resolveSession, flattenHeaders } from './session/helpers.js';
-import { sealSession, buildSessionSetCookie, buildSessionClearCookie } from './session/index.js';
 import { ErrorCodes } from './constants.js';
 import { toErrorMessage } from './helpers.js';
 
-function readBody(req, maxBodySize) {
-  return new Promise((resolve, reject) => {
-    const chunks = [];
-    let totalBytes = 0;
-    function cleanup() {
-      req.removeListener('data', onData);
-      req.removeListener('end', onEnd);
-      req.removeListener('error', onError);
-    }
-    function onData(chunk) {
-      totalBytes += chunk.length;
-      if (totalBytes > maxBodySize) {
-        cleanup();
-        req.destroy();
-        reject(new Error(ErrorCodes.BODY_TOO_LARGE));
-        return;
-      }
-      chunks.push(chunk);
-    }
-    function onEnd() {
-      cleanup();
-      resolve(Buffer.concat(chunks).toString('utf-8'));
-    }
-    function onError(err) {
-      cleanup();
-      reject(err);
-    }
-    req.on('data', onData);
-    req.on('end', onEnd);
-    req.on('error', onError);
-  });
-}
-
-function parseQuery(url) {
-  const idx = url.indexOf('?');
-  if (idx === -1) return {};
-  const params = new URLSearchParams(url.slice(idx + 1));
-  const result = {};
-  for (const [key, value] of params) {
-    result[key] = value;
-  }
-  return result;
-}
-
 class WebServer {
   config;
   log;
@@ -187,20 +143,9 @@ class WebServer {
 
     // Body (POST/PUT/PATCH only)
     if (method === 'POST' || method === 'PUT' || method === 'PATCH') {
-      const rawBody = await readBody(req, maxBodySize);
-      req.rawBody = rawBody;
-      if (rawBody.length > 0) {
-        const contentType = req.headers['content-type'] ?? '';
-        if (contentType.includes('application/json')) {
-          try {
-            req.body = JSON.parse(rawBody);
-          } catch {
-            throw new Error(ErrorCodes.INVALID_JSON);
-          }
-        } else {
-          req.body = rawBody;
-        }
-      }
+      req.rawBody = await readBody(req, maxBodySize);
+      const parsed = parseBody(req.rawBody, req.headers['content-type'] ?? '');
+      if (parsed !== undefined) req.body = parsed;
     }
   }