webspresso 0.0.112 → 0.0.114

package/src/dev/api-typegen.js

@@ -163,21 +163,39 @@ function extractUrlParamNames(routePath) {
  * @param {import('zod').ZodTypeAny | null} zSchema
  * @returns {{ acceptsFormData: boolean, fields: Record<string, { type: string, required: boolean, isFile: boolean, isArray: boolean }> | null, isStrictObject: boolean }}
  */
+const {
+  getZodDef,
+  getZodTypeName,
+  getZodInner,
+  getZodArrayElement,
+  getZodObjectShape,
+} = require('../../core/validation/zod-introspect');
+
+function unwrapZodObject(zSchema) {
+  let current = zSchema;
+  while (current && getZodDef(current)) {
+    const tName = getZodTypeName(current);
+    if (tName === 'ZodEffects' || tName === 'ZodOptional' || tName === 'ZodDefault' || tName === 'ZodPipeline') {
+      current = getZodInner(current);
+    } else {
+      break;
+    }
+  }
+  return current;
+}
+
 function inspectBodySchemaFields(zSchema) {
-  if (!zSchema || !zSchema._def) {
+  if (!zSchema || !getZodDef(zSchema)) {
     return { acceptsFormData: false, fields: null, isStrictObject: false };
   }
 
-  let current = zSchema;
-  while (current && current._def && (current._def.typeName === 'ZodEffects' || current._def.typeName === 'ZodOptional' || current._def.typeName === 'ZodDefault')) {
-    current = current._def.schema || current._def.innerType;
-  }
+  const current = unwrapZodObject(zSchema);
 
-  if (!current || !current._def || current._def.typeName !== 'ZodObject') {
+  if (!current || getZodTypeName(current) !== 'ZodObject') {
     return { acceptsFormData: false, fields: null, isStrictObject: false };
   }
 
-  const shape = typeof current.shape === 'function' ? current.shape() : current.shape;
+  const shape = getZodObjectShape(current);
   if (!shape || typeof shape !== 'object') {
     return { acceptsFormData: false, fields: {}, isStrictObject: true };
   }
@@ -190,18 +208,16 @@ function inspectBodySchemaFields(zSchema) {
     let required = true;
     let isArray = false;
 
-    while (inner && inner._def) {
-      const tName = inner._def.typeName;
+    while (inner && getZodDef(inner)) {
+      const tName = getZodTypeName(inner);
       if (tName === 'ZodOptional' || tName === 'ZodDefault') {
         required = false;
-        inner = inner._def.innerType;
-      } else if (tName === 'ZodNullable') {
-        inner = inner._def.innerType;
-      } else if (tName === 'ZodEffects') {
-        inner = inner._def.schema;
+        inner = getZodInner(inner);
+      } else if (tName === 'ZodNullable' || tName === 'ZodEffects' || tName === 'ZodPipeline') {
+        inner = getZodInner(inner);
       } else if (tName === 'ZodArray') {
         isArray = true;
-        inner = inner._def.type;
+        inner = getZodArrayElement(inner);
       } else {
         break;
       }
@@ -213,7 +229,7 @@ function inspectBodySchemaFields(zSchema) {
     );
     if (isFile) acceptsFormData = true;
 
-    const baseTypeName = inner && inner._def ? inner._def.typeName : 'ZodUnknown';
+    const baseTypeName = getZodTypeName(inner) || 'ZodUnknown';
     let scalarKind = 'string';
     if (isFile) scalarKind = 'file';
     else if (baseTypeName === 'ZodNumber') scalarKind = 'number';
@@ -271,12 +287,9 @@ function inferHandlerWireResponse(handlerFn, fileSource, schemas, zodToTsTypeFn)
   // 2. Build local variable type table from `req.input.body.<prop>` and literal assignments
   const bodyFieldTypes = {};
   if (schemas && schemas.bodySchema) {
-    let current = schemas.bodySchema;
-    while (current && current._def && (current._def.typeName === 'ZodEffects' || current._def.typeName === 'ZodOptional' || current._def.typeName === 'ZodDefault')) {
-      current = current._def.schema || current._def.innerType;
-    }
-    if (current && current._def && current._def.typeName === 'ZodObject') {
-      const shape = typeof current.shape === 'function' ? current.shape() : current.shape;
+    const current = unwrapZodObject(schemas.bodySchema);
+    if (current && getZodTypeName(current) === 'ZodObject') {
+      const shape = getZodObjectShape(current);
       if (shape) {
         for (const [k, v] of Object.entries(shape)) {
           bodyFieldTypes[k] = zodToTsTypeFn(v, 2, 'wire');
@@ -1141,6 +1154,50 @@ function checkTemplateFormContracts(rootDir, options = {}) {
       continue;
     }
 
+    // Validate new client-behavior data-w-* attributes (skipping dynamic {{ ... }} / {% ... %} values)
+    const ignoreAttrRe = /\bdata-w-ignore\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
+    let attrMatch;
+    while ((attrMatch = ignoreAttrRe.exec(content)) !== null) {
+      const val = (attrMatch[1] ?? attrMatch[2] ?? '').trim().toLowerCase();
+      if (!val || val.includes('{{') || val.includes('{%')) continue;
+      if (val !== 'children' && val !== 'self' && val !== 'all' && val !== 'both') {
+        warnings.push({
+          code: 'INVALID_DATA_W_IGNORE',
+          file: relFile,
+          value: val,
+          message: `Template "${relFile}" uses unsupported data-w-ignore="${val}". Expected "children", "self", or "all".`,
+        });
+      }
+    }
+
+    const delayAttrRe = /\bdata-w-loading-delay\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
+    while ((attrMatch = delayAttrRe.exec(content)) !== null) {
+      const val = (attrMatch[1] ?? attrMatch[2] ?? '').trim();
+      if (!val || val.includes('{{') || val.includes('{%')) continue;
+      if (!/^\d+(?:\.\d+)?(?:ms|s)?$/i.test(val)) {
+        warnings.push({
+          code: 'INVALID_LOADING_DELAY',
+          file: relFile,
+          value: val,
+          message: `Template "${relFile}" uses invalid data-w-loading-delay="${val}". Expected a non-negative number or duration (e.g. "200", "200ms", "1s").`,
+        });
+      }
+    }
+
+    const errorModeRe = /\bdata-w-error-mode\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
+    while ((attrMatch = errorModeRe.exec(content)) !== null) {
+      const val = (attrMatch[1] ?? attrMatch[2] ?? '').trim().toLowerCase();
+      if (!val || val.includes('{{') || val.includes('{%')) continue;
+      if (val !== 'touched' && val !== 'always') {
+        warnings.push({
+          code: 'INVALID_ERROR_MODE',
+          file: relFile,
+          value: val,
+          message: `Template "${relFile}" uses unsupported data-w-error-mode="${val}". Expected "touched" or "always".`,
+        });
+      }
+    }
+
     let formMatch;
     while ((formMatch = formRegex.exec(content)) !== null) {
       const formAttrs = formMatch[1] || '';

package/src/dev/typegen.js

@@ -13,6 +13,16 @@ const { hasServiceRegistry, getServiceRegistry } = require('../../core/context')
 const { scanRoutes } = require('../../src/discovery/scan-routes');
 const { compileRouteTable } = require('../../src/routing/route-table');
 const { z } = require('../../core/validation');
+const {
+  getZodDef,
+  getZodTypeName,
+  getZodInner,
+  getZodArrayElement,
+  getZodObjectShape,
+  getZodEnumValues,
+  getZodLiteralValue,
+  isZodCoerced,
+} = require('../../core/validation/zod-introspect');
 const {
   collectApiRouteContracts: collectApiRouteContractsRaw,
   generateApiDeclarationCode,
@@ -49,7 +59,7 @@ function inferZodTransformOutputType(transformFn, innerSchema, indent, mode) {
     return mode === 'wire' ? 'string' : 'Date';
   }
   // Try executing transform on a safe dummy sample if innerSchema is primitive
-  const innerType = innerSchema && innerSchema._def && innerSchema._def.typeName;
+  const innerType = getZodTypeName(innerSchema);
   try {
     let sample;
     if (innerType === 'ZodString') sample = '1';
@@ -79,14 +89,14 @@ function inferZodTransformOutputType(transformFn, innerSchema, indent, mode) {
  * @returns {boolean}
  */
 function isZodFieldOptional(zField, mode = 'output') {
-  if (!zField || !zField._def) return false;
-  const t = zField._def.typeName;
+  const t = getZodTypeName(zField);
+  if (!t) return false;
   if (t === 'ZodOptional') return true;
   if (t === 'ZodDefault') {
     return mode === 'input';
   }
-  if (t === 'ZodEffects' && zField._def.schema) {
-    return isZodFieldOptional(zField._def.schema, mode);
+  if ((t === 'ZodEffects' || t === 'ZodPipeline') && getZodInner(zField)) {
+    return isZodFieldOptional(getZodInner(zField), mode);
   }
   return false;
 }
@@ -95,13 +105,13 @@ function isZodFieldOptional(zField, mode = 'output') {
  * Unwraps outer `ZodOptional` / `ZodDefault` for property type emission inside `ZodObject`.
  */
 function unwrapOptionalOrDefault(zField, mode = 'output') {
-  if (!zField || !zField._def) return zField;
-  const t = zField._def.typeName;
+  const t = getZodTypeName(zField);
+  if (!t) return zField;
   if (t === 'ZodOptional') {
-    return zField._def.innerType;
+    return getZodInner(zField);
   }
   if (t === 'ZodDefault' && mode === 'input') {
-    return zField._def.innerType;
+    return getZodInner(zField);
   }
   return zField;
 }
@@ -114,8 +124,9 @@ function unwrapOptionalOrDefault(zField, mode = 'output') {
  * @returns {string}
  */
 function zodToTsType(zType, indent = 0, mode = 'output') {
-  if (!zType || !zType._def) return 'unknown';
-  const typeName = zType._def.typeName;
+  const def = getZodDef(zType);
+  const typeName = getZodTypeName(zType);
+  if (!def || !typeName) return 'unknown';
   const spaces = '  '.repeat(indent);
   const nextSpaces = '  '.repeat(indent + 1);
 
@@ -128,12 +139,12 @@ function zodToTsType(zType, indent = 0, mode = 'output') {
     case 'ZodString':
       return 'string';
     case 'ZodNumber':
-      if (mode === 'input' && zType._def.coerce) {
+      if (mode === 'input' && isZodCoerced(zType)) {
         return 'number | string';
       }
       return 'number';
     case 'ZodBoolean':
-      if (mode === 'input' && zType._def.coerce) {
+      if (mode === 'input' && isZodCoerced(zType)) {
         return 'boolean | string';
       }
       return 'boolean';
@@ -155,48 +166,63 @@ function zodToTsType(zType, indent = 0, mode = 'output') {
       return 'unknown';
     case 'ZodNever':
       return 'never';
-    case 'ZodLiteral':
-      return typeof zType._def.value === 'string'
-        ? `'${zType._def.value}'`
-        : String(zType._def.value);
+    case 'ZodLiteral': {
+      const litVal = getZodLiteralValue(zType);
+      return typeof litVal === 'string' ? `'${litVal}'` : String(litVal);
+    }
     case 'ZodEnum':
-      return (zType._def.values || []).map((v) => `'${v}'`).join(' | ') || 'string';
+      return getZodEnumValues(zType).map((v) => `'${v}'`).join(' | ') || 'string';
     case 'ZodNativeEnum':
       return 'number | string';
     case 'ZodArray':
-      return `Array<${zodToTsType(zType._def.type, indent, mode)}>`;
+      return `Array<${zodToTsType(getZodArrayElement(zType), indent, mode)}>`;
     case 'ZodOptional':
-      return `${zodToTsType(zType._def.innerType, indent, mode)} | undefined`;
+      return `${zodToTsType(getZodInner(zType), indent, mode)} | undefined`;
     case 'ZodNullable':
-      return `${zodToTsType(zType._def.innerType, indent, mode)} | null`;
+      return `${zodToTsType(getZodInner(zType), indent, mode)} | null`;
     case 'ZodDefault':
-      return zodToTsType(zType._def.innerType, indent, mode);
+      return zodToTsType(getZodInner(zType), indent, mode);
+    case 'ZodPipeline': {
+      const inDef = getZodDef(def.in);
+      const outDef = getZodDef(def.out);
+      if (mode === 'input') {
+        if (inDef && inDef.type === 'transform' && def.out) {
+          return `${zodToTsType(def.out, indent, mode)} | string`;
+        }
+        return zodToTsType(def.in, indent, mode);
+      }
+      if (outDef && outDef.type === 'transform' && typeof outDef.transform === 'function') {
+        return inferZodTransformOutputType(outDef.transform, def.in, indent, mode);
+      }
+      return zodToTsType(def.out || def.in, indent, mode);
+    }
     case 'ZodEffects': {
       if (mode === 'input') {
-        if (zType._def.effect && zType._def.effect.type === 'preprocess') {
-          return `${zodToTsType(zType._def.schema, indent, mode)} | string`;
+        if (def.effect && def.effect.type === 'preprocess') {
+          return `${zodToTsType(def.schema, indent, mode)} | string`;
         }
-        return zodToTsType(zType._def.schema, indent, mode);
+        return zodToTsType(def.schema, indent, mode);
       }
-      if (zType._def.effect && zType._def.effect.type === 'transform') {
+      if (def.effect && def.effect.type === 'transform') {
         return inferZodTransformOutputType(
-          zType._def.effect.transform,
-          zType._def.schema,
+          def.effect.transform,
+          def.schema,
           indent,
           mode
         );
       }
-      return zodToTsType(zType._def.schema, indent, mode);
+      return zodToTsType(def.schema, indent, mode);
     }
     case 'ZodUnion':
     case 'ZodDiscriminatedUnion':
-      return (zType._def.options || []).map((opt) => zodToTsType(opt, indent, mode)).join(' | ') || 'unknown';
+      return (def.options || []).map((opt) => zodToTsType(opt, indent, mode)).join(' | ') || 'unknown';
     case 'ZodObject': {
-      const shape = typeof zType.shape === 'function' ? zType.shape() : zType.shape;
+      const shape = getZodObjectShape(zType);
       if (!shape || Object.keys(shape).length === 0) return 'Record<string, unknown>';
       const entries = [];
       for (const [k, v] of Object.entries(shape)) {
-        if (mode === 'wire' && v && v._def && (v._def.typeName === 'ZodUndefined' || v._def.typeName === 'ZodVoid')) {
+        const vType = getZodTypeName(v);
+        if (mode === 'wire' && (vType === 'ZodUndefined' || vType === 'ZodVoid')) {
           continue;
         }
         const isOpt = isZodFieldOptional(v, mode);
@@ -209,7 +235,7 @@ function zodToTsType(zType, indent = 0, mode = 'output') {
       return `{\n${entries.join('\n')}\n${spaces}}`;
     }
     case 'ZodRecord':
-      return `Record<string, ${zodToTsType(zType._def.valueType, indent, mode)}>`;
+      return `Record<string, ${zodToTsType(def.valueType, indent, mode)}>`;
     default:
       return 'unknown';
   }
@@ -247,8 +273,8 @@ function collectModelMetadata(modelsDir) {
       const columns = [];
       if (model.schema && model.schema.shape) {
         for (const [colName, colZod] of Object.entries(model.schema.shape)) {
-          const isOpt = colZod?._def?.typeName === 'ZodOptional';
-          const innerZod = isOpt ? colZod._def.innerType : colZod;
+          const isOpt = getZodTypeName(colZod) === 'ZodOptional';
+          const innerZod = isOpt ? getZodInner(colZod) : colZod;
           columns.push({
             name: colName,
             isOptional: isOpt,

package/src/dev-reload/index.js

@@ -168,8 +168,39 @@ const CLIENT_RUNTIME_SCRIPT = `(function() {
     document.addEventListener('keydown', onKeyDown);
   }
 
+  function saveScrollPosition() {
+    try {
+      if (typeof window.sessionStorage !== 'undefined') {
+        window.sessionStorage.setItem('__ws_dev_scroll', JSON.stringify({
+          url: window.location.pathname + window.location.search,
+          x: window.scrollX || 0,
+          y: window.scrollY || 0,
+        }));
+      }
+    } catch (_) {}
+  }
+
+  function restoreScrollPosition() {
+    try {
+      if (typeof window.sessionStorage === 'undefined') return;
+      var raw = window.sessionStorage.getItem('__ws_dev_scroll');
+      if (!raw) return;
+      window.sessionStorage.removeItem('__ws_dev_scroll');
+      var pos = JSON.parse(raw);
+      if (pos && pos.url === (window.location.pathname + window.location.search)) {
+        var apply = function() { window.scrollTo(pos.x || 0, pos.y || 0); };
+        if (typeof window.requestAnimationFrame === 'function') {
+          window.requestAnimationFrame(apply);
+        } else {
+          apply();
+        }
+      }
+    } catch (_) {}
+  }
+
   function safeReload(reason) {
     clearOverlay();
+    saveScrollPosition();
     var reasonMsg = reason ? ' (' + reason + ')' : '';
     console.log('[Webspresso] 🔄 Reloading page' + reasonMsg + '...');
 
@@ -246,10 +277,15 @@ const CLIENT_RUNTIME_SCRIPT = `(function() {
     };
   }
 
+  function init() {
+    restoreScrollPosition();
+    connect();
+  }
+
   if (document.readyState === 'loading') {
-    document.addEventListener('DOMContentLoaded', connect);
+    document.addEventListener('DOMContentLoaded', init);
   } else {
-    connect();
+    init();
   }
 })();
 `;
@@ -290,6 +326,7 @@ function createDevReloadHub(config = {}) {
   const autoInject = options.autoInject !== false;
   const watchPublicAll = options.watchPublicAll === true;
   const extraWatch = Array.isArray(options.watch) ? options.watch : [];
+  let ignoreClientFiles = Boolean(options.ignoreClientFiles);
 
   const templateExtensions = new Set(
     (Array.isArray(options.templateExtensions)
@@ -393,6 +430,9 @@ function createDevReloadHub(config = {}) {
     setDevMetaProvider: (fn) => {
       getDevMetaCallback = fn;
     },
+    setIgnoreClientFiles: (flag) => {
+      ignoreClientFiles = Boolean(flag);
+    },
     invalidateTemplateCache,
     triggerTemplateReload: (filename, reason = 'template') => {
       onTemplateFileChanged(filename, reason);
@@ -594,6 +634,7 @@ function createDevReloadHub(config = {}) {
     if (watchTemplates && viewsDir && fs.existsSync(viewsDir)) {
       watchDirectory(viewsDir, (eventType, filename) => {
         if (!filename || shouldIgnore(filename)) return;
+        if (ignoreClientFiles && filename.includes('.client.')) return;
         const ext = path.extname(filename).toLowerCase();
         if (ext === '.css') {
           onCssFileChanged(filename);
@@ -607,6 +648,7 @@ function createDevReloadHub(config = {}) {
     if (watchTemplates && pagesDir && fs.existsSync(pagesDir)) {
       watchDirectory(pagesDir, (eventType, filename) => {
         if (!filename || shouldIgnore(filename)) return;
+        if (ignoreClientFiles && filename.includes('.client.')) return;
         const ext = path.extname(filename).toLowerCase();
         if (ext === '.css') {
           onCssFileChanged(filename);

package/src/file-router.js

@@ -1998,12 +1998,30 @@ function mountPages(app, options) {
       resolveMiddlewareList: (mwList) => resolveMiddlewares(mwList, middlewares),
     });
 
-    const { rateLimit } = require('../core/rate-limit');
-    const fragmentLimiter = rateLimit({
-      window: 60000,
-      limit: 300,
-      skip: () => process.env.NODE_ENV === 'test',
-    });
+    let fragmentLimiter;
+    try {
+      const expressRateLimit = require('express-rate-limit');
+      const rateLimitFn = expressRateLimit.rateLimit || expressRateLimit;
+      if (typeof rateLimitFn === 'function') {
+        fragmentLimiter = rateLimitFn({
+          windowMs: 60000,
+          limit: 300,
+          standardHeaders: 'draft-7',
+          legacyHeaders: false,
+          skip: () => process.env.NODE_ENV === 'test',
+        });
+      }
+    } catch (_e) {
+      // Fall back to built-in core/rate-limit when express-rate-limit peer is not installed
+    }
+    if (!fragmentLimiter) {
+      const { rateLimit } = require('../core/rate-limit');
+      fragmentLimiter = rateLimit({
+        window: 60000,
+        limit: 300,
+        skip: () => process.env.NODE_ENV === 'test',
+      });
+    }
 
     if (typeof app.get === 'function') {
       app.get('/__webspresso/fragments', fragmentLimiter, fragmentRefreshHandler);

package/src/routing/mount-discovered-routes.js

@@ -120,12 +120,30 @@ function mountDiscoveredRoutes(app, routeTable, context) {
       resolveMiddlewareList: (mwList) => resolveMiddlewares(mwList, context.middlewares || {}),
     });
 
-    const { rateLimit } = require('../../core/rate-limit');
-    const fragmentLimiter = rateLimit({
-      window: 60000,
-      limit: 300,
-      skip: () => process.env.NODE_ENV === 'test',
-    });
+    let fragmentLimiter;
+    try {
+      const expressRateLimit = require('express-rate-limit');
+      const rateLimitFn = expressRateLimit.rateLimit || expressRateLimit;
+      if (typeof rateLimitFn === 'function') {
+        fragmentLimiter = rateLimitFn({
+          windowMs: 60000,
+          limit: 300,
+          standardHeaders: 'draft-7',
+          legacyHeaders: false,
+          skip: () => process.env.NODE_ENV === 'test',
+        });
+      }
+    } catch (_e) {
+      // Fall back to built-in core/rate-limit when express-rate-limit peer is not installed
+    }
+    if (!fragmentLimiter) {
+      const { rateLimit } = require('../../core/rate-limit');
+      fragmentLimiter = rateLimit({
+        window: 60000,
+        limit: 300,
+        skip: () => process.env.NODE_ENV === 'test',
+      });
+    }
 
     app.get('/__webspresso/fragments', fragmentLimiter, fragmentRefreshHandler);
     app.post('/__webspresso/fragments', fragmentLimiter, fragmentRefreshHandler);

package/src/server.js

@@ -24,7 +24,7 @@ const { resolveClientRuntime } = require('./client-runtime/resolve');
 const { mountPages, detectLocale, loadI18n, createTranslator } = require('./file-router');
 const { configureAssets, createHelpers, getScriptInjector, AssetManager } = require('./helpers');
 const { createDevReloadHub } = require('./dev-reload');
-const { createDevBundler } = require('./bundle');
+const { createDevBundler, findDefaultEntryPoints } = require('./bundle');
 const { registerClearHook } = require('./njk-frontmatter');
 const { createPluginManager } = require('./plugin-manager');
 const { createServiceRegistry } = require('./services');
@@ -1558,15 +1558,19 @@ function createApp(options = {}) {
   // Client-side JS incremental bundler (esbuild context() API)
   const bundleOption = options.bundle;
   const isBundleExplicit = bundleOption === true || (typeof bundleOption === 'object' && bundleOption.enabled !== false);
-  const isBundleDisabled = bundleOption === false;
+  const isBundleDisabled = bundleOption === false || (typeof bundleOption === 'object' && bundleOption.enabled === false);
+  const shouldAutoBundle = bundleOption === undefined && isDev && !isTest && findDefaultEntryPoints(rootDir).length > 0;
 
-  if (isBundleExplicit && !isBundleDisabled) {
+  if ((isBundleExplicit || shouldAutoBundle) && !isBundleDisabled) {
     const bundlerOpts = typeof bundleOption === 'object' ? { ...bundleOption } : {};
     if (!bundlerOpts.cwd) bundlerOpts.cwd = rootDir;
     const devBundler = createDevBundler(bundlerOpts, devReloadHub);
     app.devBundler = devBundler;
 
     if (devBundler.isAvailable() && bundlerOpts.watch !== false && isDev && !isTest) {
+      if (devReloadHub && typeof devReloadHub.setIgnoreClientFiles === 'function') {
+        devReloadHub.setIgnoreClientFiles(true);
+      }
       devBundler.startWatch().catch((err) => {
         if (logging) console.error('[Webspresso Bundler] Watch error:', err.message);
       });
@@ -1577,6 +1581,58 @@ function createApp(options = {}) {
     }
   }
 
+  // Auto-refresh generated TypeScript types & typed API client in dev mode when models/services/api routes change
+  if (isDev && !isTest && options.typegen !== false) {
+    const typegenWatchDirs = [
+      path.join(rootDir, 'models'),
+      path.join(rootDir, 'services'),
+      path.join(rootDir, 'pages', 'api'),
+    ].filter((d) => fs.existsSync(d));
+
+    if (typegenWatchDirs.length > 0) {
+      const typegenWatchers = [];
+      let typegenTimer = null;
+      const scheduleTypegenRefresh = () => {
+        if (typegenTimer) clearTimeout(typegenTimer);
+        typegenTimer = setTimeout(() => {
+          typegenTimer = null;
+          try {
+            const { generateTypes } = require('./dev/typegen');
+            generateTypes({ rootDir, silent: true });
+            const hasGeneratedClient =
+              fs.existsSync(path.join(rootDir, '.webspresso', 'client.ts')) ||
+              fs.existsSync(path.join(rootDir, 'src', 'client.ts'));
+            if (hasGeneratedClient) {
+              const { generateClient } = require('./dev/client-gen');
+              generateClient({ rootDir, silent: true });
+            }
+          } catch (_) {}
+        }, 250);
+        if (typeof typegenTimer.unref === 'function') typegenTimer.unref();
+      };
+
+      for (const watchDir of typegenWatchDirs) {
+        try {
+          const w = fs.watch(watchDir, { recursive: true }, (_evt, filename) => {
+            if (!filename || filename.includes('node_modules') || filename.includes('.webspresso')) return;
+            scheduleTypegenRefresh();
+          });
+          w.on('error', () => {});
+          typegenWatchers.push(w);
+        } catch (_) {}
+      }
+
+      if (shutdownManager) {
+        shutdownManager.registerDisposer('devTypegen', () => {
+          if (typegenTimer) clearTimeout(typegenTimer);
+          for (const w of typegenWatchers) {
+            try { w.close(); } catch (_) {}
+          }
+        });
+      }
+    }
+  }
+
   // Configure Nunjucks with viewsDir priority and circular extension guard
   const templateDirs = [viewsDir, pagesDir].filter(Boolean);
   if (templateDirs.length === 0) {