webspresso 0.0.112 → 0.0.114

package/core/client/index.js

@@ -192,9 +192,26 @@ function createClientRuntime(options = {}) {
         controllers.mountSubtree(addedEl);
       }
     },
-    onAfterPatch(patchedEl) {
+    getPatchHookContext() {
+      return controllers ? controllers.getActivePatchHookContext() : null;
+    },
+    onBeforePatch(patchedEl, inst, meta) {
+      if (controllers) {
+        controllers.notifyBeforePatch(patchedEl, {
+          fragmentId: inst && inst.instanceId ? inst.instanceId : null,
+          fragmentName: inst && inst.name ? inst.name : null,
+          hookChainDepth: meta && meta.hookChainDepth ? meta.hookChainDepth : 0,
+        });
+      }
+    },
+    onAfterPatch(patchedEl, inst, meta) {
       if (controllers) {
         controllers.mountSubtree(patchedEl);
+        controllers.notifyAfterPatch(patchedEl, {
+          fragmentId: inst && inst.instanceId ? inst.instanceId : null,
+          fragmentName: inst && inst.name ? inst.name : null,
+          hookChainDepth: meta && meta.hookChainDepth ? meta.hookChainDepth : 0,
+        });
       }
     },
   });

package/core/client/server-fragments.js

@@ -118,6 +118,9 @@ function defineFragment(config = {}) {
         : config.persist !== undefined
           ? config.persist
           : undefined,
+    lazy: config.lazy !== undefined ? Boolean(config.lazy) : undefined,
+    placeholder: config.placeholder !== undefined ? config.placeholder : undefined,
+    placeholderTemplate: config.placeholderTemplate !== undefined ? config.placeholderTemplate : undefined,
   };
 }
 
@@ -403,6 +406,7 @@ function wrapFragmentRootHtml({
   refetchInterval,
   refetchIntervalInBackground,
   persistInput,
+  lazy,
 }) {
   const safeTag = /^[a-zA-Z][a-zA-Z0-9-]*$/.test(tag || 'div') ? tag : 'div';
   const attrs = [
@@ -449,6 +453,10 @@ function wrapFragmentRootHtml({
     attrs.push(`data-w-persist-input="${escapeHtmlAttr(persistAttrVal)}"`);
   }
 
+  if (lazy) {
+    attrs.push('data-w-lazy="visible"');
+  }
+
   if (className) {
     attrs.push(`class="${escapeHtmlAttr(className)}"`);
   }
@@ -512,10 +520,18 @@ async function executeAndRenderFragment({
   // 3. Validate & coerce fragment input
   const validatedInput = validateFragmentInput(name, fragmentDef, rawInput);
 
-  // 4. Execute fragment loader (`load(fragmentCtx)`)
+  const isLazy = Boolean(options.lazy !== undefined ? options.lazy : fragmentDef.lazy);
+  const isRefreshTarget = Boolean(
+    req &&
+      req.__isWebspressoFragmentRefresh &&
+      (!req.__refreshedFragmentIds || req.__refreshedFragmentIds.has(instanceId))
+  );
+  const renderAsLazyPlaceholder = isLazy && !isRefreshTarget;
+
+  // 4. Execute fragment loader (`load(fragmentCtx)`) unless rendering initial lazy placeholder
   const loadStart = Date.now();
   let fragmentData = {};
-  if (typeof fragmentDef.load === 'function') {
+  if (!renderAsLazyPlaceholder && typeof fragmentDef.load === 'function') {
     const fragmentCtx = {
       ...ctx,
       req,
@@ -535,20 +551,45 @@ async function executeAndRenderFragment({
   }
   const loadMs = Math.max(0, Date.now() - loadStart);
 
-  // 5. Render fragment template via Nunjucks
+  // 5. Render fragment template (or lazy placeholder) via Nunjucks
   const renderStart = Date.now();
-  const templateCtx = {
-    ...(res && res.locals ? res.locals : {}),
-    ...baseRenderCtx,
-    ...fragmentData,
-    fragmentInput: validatedInput,
-    fragmentId: instanceId,
-    fragmentName: name,
-  };
+  let innerHtml = '';
+  if (renderAsLazyPlaceholder) {
+    const phTemplate = options.placeholderTemplate || fragmentDef.placeholderTemplate;
+    const phOption = options.placeholder !== undefined ? options.placeholder : fragmentDef.placeholder;
+    if (typeof phTemplate === 'string' && phTemplate.trim()) {
+      const cleanPh = phTemplate.trim().replace(/^\/+/, '');
+      if (cleanPh.includes('..')) {
+        throw new BadRequestError(`Invalid placeholder template path for fragment "${name}".`);
+      }
+      innerHtml = nunjucksEnv.render(cleanPh, {
+        ...(res && res.locals ? res.locals : {}),
+        ...baseRenderCtx,
+        fragmentInput: validatedInput,
+        fragmentId: instanceId,
+        fragmentName: name,
+      });
+    } else if (typeof phOption === 'function') {
+      innerHtml = String(phOption({ input: validatedInput, instanceId, name }) || '');
+    } else if (typeof phOption === 'string') {
+      innerHtml = phOption;
+    } else {
+      innerHtml = '<div class="w-fragment-placeholder" role="status" aria-busy="true" aria-live="polite" style="min-height:48px">Loading...</div>';
+    }
+  } else {
+    const templateCtx = {
+      ...(res && res.locals ? res.locals : {}),
+      ...baseRenderCtx,
+      ...fragmentData,
+      fragmentInput: validatedInput,
+      fragmentId: instanceId,
+      fragmentName: name,
+    };
 
-  let innerHtml = nunjucksEnv.render(cleanTemplate, templateCtx);
-  // Resolve any nested async SSR fragments inside this fragment
-  innerHtml = await resolvePendingSsrFragments(innerHtml, req);
+    innerHtml = nunjucksEnv.render(cleanTemplate, templateCtx);
+    // Resolve any nested async SSR fragments inside this fragment
+    innerHtml = await resolvePendingSsrFragments(innerHtml, req);
+  }
   const renderMs = Math.max(0, Date.now() - renderStart);
 
   if (renderedInstanceIds) {
@@ -591,6 +632,7 @@ async function executeAndRenderFragment({
         : options.persist !== undefined
           ? options.persist
           : fragmentDef.persistInput,
+    lazy: renderAsLazyPlaceholder,
   });
 
   return {
@@ -604,6 +646,17 @@ async function executeAndRenderFragment({
   };
 }
 
+function getPluginRegisteredFragment(name) {
+  try {
+    const { getPluginManager } = require('../plugins/plugin-manager');
+    const pm = typeof getPluginManager === 'function' ? getPluginManager() : null;
+    if (pm && typeof pm.getFragment === 'function') {
+      return pm.getFragment(name) || null;
+    }
+  } catch (_e) {}
+  return null;
+}
+
 /**
  * Create the `fsy.fragment(name, input?, options?)` template helper for a page render pass.
  * Uses the exact same `executeAndRenderFragment` pipeline for initial SSR as subsequent refreshes!
@@ -623,7 +676,9 @@ function attachSsrFragmentHelper({ req, res, ctx, pageMod, pagePath, nunjucksEnv
 
   function renderFragmentHelper(name, rawInput = {}, options = {}) {
     const cleanName = String(name || '').trim();
-    const fragmentDef = fragmentsMap[cleanName];
+    const fragmentDef =
+      (Object.prototype.hasOwnProperty.call(fragmentsMap, cleanName) ? fragmentsMap[cleanName] : null) ||
+      getPluginRegisteredFragment(cleanName);
     if (!fragmentDef) {
       throw new NotFoundError(
         `Fragment "${cleanName}" is not defined in fragments export for page "${pagePath}".`
@@ -811,6 +866,9 @@ function createFragmentRefreshHandler(config) {
     const startTotal = Date.now();
     try {
       const isGet = req.method === 'GET';
+      if (!isGet && req.headers && req.headers['sec-fetch-site'] === 'cross-site') {
+        throw new ForbiddenError('Cross-site fragment refresh requests are forbidden.');
+      }
       const payload = isGet ? req.query || {} : req.body || {};
 
       const pagePath = payload.pagePath || payload.page || req.headers['x-webspresso-page'] || '/';
@@ -853,9 +911,10 @@ function createFragmentRefreshHandler(config) {
       req.params = { ...(req.params || {}), ...params };
 
       const pageMod = typeof entry.getPageMod === 'function' ? entry.getPageMod() : entry.pageMod;
-      const fragmentsMap = (pageMod && pageMod.fragments) || {};
+      const pageFragmentsMap = (pageMod && pageMod.fragments) || {};
+      const fragmentsMap = { ...pageFragmentsMap };
 
-      // Validate that all requested fragments are registered on this page BEFORE running loaders
+      // Validate that all requested fragments are registered on this page (or by a plugin) BEFORE running loaders
       // (Rejects arbitrary template paths or unknown fragment names)
       for (const item of requestedFragments) {
         if (!item || typeof item.name !== 'string' || !item.name.trim()) {
@@ -865,7 +924,12 @@ function createFragmentRefreshHandler(config) {
           throw new BadRequestError('Client cannot specify arbitrary template paths in fragment refresh requests.');
         }
         if (!Object.prototype.hasOwnProperty.call(fragmentsMap, item.name)) {
-          throw new NotFoundError(`Fragment "${item.name}" is not registered on page "${entry.routePath}".`);
+          const pluginFrag = getPluginRegisteredFragment(item.name);
+          if (pluginFrag) {
+            fragmentsMap[item.name] = pluginFrag;
+          } else {
+            throw new NotFoundError(`Fragment "${item.name}" is not registered on page "${entry.routePath}".`);
+          }
         }
       }
 
@@ -894,6 +958,8 @@ function createFragmentRefreshHandler(config) {
       const ctx = typeof buildContext === 'function' ? buildContext(req, res, { fsy }) : { req, res, fsy };
       ensureRequestMemo(req, ctx);
 
+      req.__isWebspressoFragmentRefresh = true;
+      req.__refreshedFragmentIds = new Set(requestedFragments.map((it) => it.instanceId || `${it.name}:default`));
       req.__fragmentChildInputs =
         payload.childInputs && typeof payload.childInputs === 'object' && !isArray(payload.childInputs)
           ? payload.childInputs
@@ -912,6 +978,8 @@ function createFragmentRefreshHandler(config) {
       });
 
       const results = {};
+      const fragmentErrors = {};
+      let firstError = null;
 
       for (const reqItem of requestedFragments) {
         const fragName = reqItem.name.trim();
@@ -932,34 +1000,51 @@ function createFragmentRefreshHandler(config) {
               : rawFragDef.middleware || [],
         };
 
-        const rendered = await executeAndRenderFragment({
-          name: fragName,
-          fragmentDef: fragDef,
-          instanceId,
-          pagePath,
-          rawInput: reqItem.input || {},
-          req,
-          res,
-          ctx,
-          nunjucksEnv,
-          baseRenderCtx: { fsy },
-          renderedInstanceIds,
-        });
+        try {
+          const rendered = await executeAndRenderFragment({
+            name: fragName,
+            fragmentDef: fragDef,
+            instanceId,
+            pagePath,
+            rawInput: reqItem.input || {},
+            req,
+            res,
+            ctx,
+            nunjucksEnv,
+            baseRenderCtx: { fsy },
+            renderedInstanceIds,
+          });
+
+          results[instanceId] = {
+            instanceId: rendered.instanceId,
+            name: rendered.name,
+            html: rendered.html,
+            input: rendered.input,
+            loadMs: rendered.loadMs,
+            renderMs: rendered.renderMs,
+          };
+        } catch (fragErr) {
+          if (!firstError) firstError = fragErr;
+          fragmentErrors[instanceId] = {
+            instanceId,
+            name: fragName,
+            status: fragErr.statusCode || fragErr.status || 500,
+            code: fragErr.code || 'FRAGMENT_REFRESH_ERROR',
+            message: fragErr.message || `Failed to render fragment "${fragName}"`,
+          };
+        }
+      }
 
-        results[instanceId] = {
-          instanceId: rendered.instanceId,
-          name: rendered.name,
-          html: rendered.html,
-          input: rendered.input,
-          loadMs: rendered.loadMs,
-          renderMs: rendered.renderMs,
-        };
+      if (firstError && Object.keys(results).length === 0) {
+        return next(firstError);
       }
 
       const totalMs = Math.max(0, Date.now() - startTotal);
       res.setHeader('Cache-Control', 'no-store');
+      const hasPartialErrors = Object.keys(fragmentErrors).length > 0;
       return res.status(200).json({
-        ok: true,
+        ok: !hasPartialErrors,
+        ...(hasPartialErrors ? { partial: true, errors: fragmentErrors } : {}),
         pagePath,
         totalMs,
         fragments: results,

package/core/client/utils.js

@@ -185,7 +185,12 @@ function parseDataValue(val) {
   if (val === 'undefined') return undefined;
   if (/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/.test(val)) {
     const num = Number(val);
-    if (isNumber(num)) return num;
+    if (isNumber(num)) {
+      if (/^-?(?:0|[1-9]\d*)$/.test(val) && !Number.isSafeInteger(num)) {
+        return val;
+      }
+      return num;
+    }
   }
   if ((val.startsWith('{') && val.endsWith('}')) || (val.startsWith('[') && val.endsWith(']'))) {
     try {
@@ -350,9 +355,31 @@ function uid(prefix = 'id', len = 5) {
   return `${prefix}_${Date.now()}_${randomId(len)}`;
 }
 
+/**
+ * Parse a delay/duration attribute such as `"200"`, `"200ms"`, or `"1s"` into milliseconds.
+ *
+ * @param {string|number|null|undefined} raw
+ * @param {number} [fallback=0]
+ * @returns {number}
+ */
+function parseDelayMs(raw, fallback = 0) {
+  if (raw === null || raw === undefined || raw === '') return fallback;
+  if (typeof raw === 'number') return Number.isFinite(raw) && raw >= 0 ? raw : fallback;
+  const s = String(raw).trim().toLowerCase();
+  if (!s) return fallback;
+  const msMatch = s.match(/^(\d+(?:\.\d+)?)\s*ms$/);
+  if (msMatch) return Math.max(0, Math.round(Number(msMatch[1])));
+  const sMatch = s.match(/^(\d+(?:\.\d+)?)\s*s$/);
+  if (sMatch) return Math.max(0, Math.round(Number(sMatch[1]) * 1000));
+  const num = Number(s);
+  return Number.isFinite(num) && num >= 0 ? Math.round(num) : fallback;
+}
+
 /**
  * Apply or restore automatic busy/loading state (`data-w-busy`, `aria-busy`, `disabled`,
  * `data-w-loading-text` / `data-w-disable-with`, and `data-w-loading-class`) on an interactive element.
+ * Respects `data-w-loading-delay` for visual indicators (`loading-text`, `loading-class`) while
+ * applying `data-w-busy`, `aria-busy`, and `disabled` double-submit protection immediately.
  *
  * @param {Element|null|undefined} el
  * @param {boolean} isBusy
@@ -360,6 +387,29 @@ function uid(prefix = 'id', len = 5) {
 function setElementBusyState(el, isBusy) {
   if (!el || typeof el.setAttribute !== 'function') return;
 
+  const applyVisualBusy = () => {
+    const tag = el.tagName || '';
+    const loadingText = el.getAttribute('data-w-loading-text') ?? el.getAttribute('data-w-disable-with');
+    if (loadingText !== null) {
+      if (tag === 'INPUT' && (el.type === 'submit' || el.type === 'button')) {
+        el.__wOrigValue = el.value;
+        el.value = loadingText;
+      } else {
+        el.__wOrigText = el.textContent;
+        el.textContent = loadingText;
+      }
+    }
+
+    const loadingClass = safeTrim(el.getAttribute('data-w-loading-class'));
+    if (loadingClass && el.classList) {
+      const classes = loadingClass.split(/\s+/).filter(Boolean);
+      el.__wAddedClasses = classes;
+      for (let i = 0; i < classes.length; i++) {
+        el.classList.add(classes[i]);
+      }
+    }
+  };
+
   if (isBusy) {
     el.__wBusyCount = (el.__wBusyCount || 0) + 1;
     if (el.__wBusyCount > 1) return;
@@ -386,24 +436,22 @@ function setElementBusyState(el, isBusy) {
       el.setAttribute('aria-disabled', 'true');
     }
 
-    const loadingText = el.getAttribute('data-w-loading-text') ?? el.getAttribute('data-w-disable-with');
-    if (loadingText !== null) {
-      if (tag === 'INPUT' && (el.type === 'submit' || el.type === 'button')) {
-        el.__wOrigValue = el.value;
-        el.value = loadingText;
-      } else {
-        el.__wOrigText = el.textContent;
-        el.textContent = loadingText;
-      }
+    const delayMs = parseDelayMs(el.getAttribute('data-w-loading-delay'), 0);
+    el.__wBusyGen = (el.__wBusyGen || 0) + 1;
+    if (el.__wBusyTimer) {
+      clearTimeout(el.__wBusyTimer);
+      el.__wBusyTimer = null;
     }
 
-    const loadingClass = safeTrim(el.getAttribute('data-w-loading-class'));
-    if (loadingClass && el.classList) {
-      const classes = loadingClass.split(/\s+/).filter(Boolean);
-      el.__wAddedClasses = classes;
-      for (let i = 0; i < classes.length; i++) {
-        el.classList.add(classes[i]);
-      }
+    if (delayMs > 0) {
+      const gen = el.__wBusyGen;
+      el.__wBusyTimer = setTimeout(() => {
+        el.__wBusyTimer = null;
+        if (el.__wBusyGen !== gen || !el.__wActionBusy || el.isConnected === false) return;
+        applyVisualBusy();
+      }, delayMs);
+    } else {
+      applyVisualBusy();
     }
   } else {
     if (!el.__wBusyCount) return;
@@ -411,6 +459,12 @@ function setElementBusyState(el, isBusy) {
     if (el.__wBusyCount > 0) return;
 
     el.__wActionBusy = false;
+    el.__wBusyGen = (el.__wBusyGen || 0) + 1;
+    if (el.__wBusyTimer) {
+      clearTimeout(el.__wBusyTimer);
+      el.__wBusyTimer = null;
+    }
+
     el.removeAttribute('data-w-busy');
     el.removeAttribute('aria-busy');
 
@@ -459,6 +513,7 @@ module.exports = {
   parseDataValue,
   decorateElement,
   parseDurationMs,
+  parseDelayMs,
   parseRefetchMode,
   randomId,
   uid,

package/core/console/commands.js

@@ -6,6 +6,8 @@
  * @module core/console/commands
  */
 
+const fs = require('fs');
+const path = require('path');
 const { discoverAppRoutes } = require('../../src/discovery/scan-routes');
 
 /**
@@ -50,9 +52,12 @@ function registerConsoleCommands(replServer, { context, meta, rootDir }) {
         } else {
           console.log(`\n⚙️  Registered Services (${services.length}):`);
           for (const s of services) {
-            console.log(`  • \x1b[32m${s.name}\x1b[0m ${s.description ? `(${s.description})` : ''}`);
+            const name = typeof s === 'string' ? s : (s?.name || String(s));
+            const desc = typeof s === 'object' && s?.description ? `(${s.description})` : '';
+            console.log(`  • \x1b[32m${name}\x1b[0m ${desc}`);
           }
-          console.log('\n  Tip: Call a service with: await service(\'' + services[0].name + '\', payload)\n');
+          const firstName = typeof services[0] === 'string' ? services[0] : (services[0]?.name || String(services[0]));
+          console.log('\n  Tip: Call a service with: await service(\'' + firstName + '\', payload)\n');
         }
       }
       this.displayPrompt();
@@ -64,7 +69,14 @@ function registerConsoleCommands(replServer, { context, meta, rootDir }) {
     help: 'Scan and list all application API endpoints and SSR pages',
     action() {
       try {
-        const result = discoverAppRoutes({ rootDir });
+        const pagesApiDir = ['src/pages/api', 'pages/api']
+          .map((rel) => path.join(rootDir, rel))
+          .find((p) => fs.existsSync(p));
+        const hasStandaloneApi = ['src/api', 'api'].some((rel) => fs.existsSync(path.join(rootDir, rel)));
+        const result = discoverAppRoutes({
+          rootDir,
+          ...(!hasStandaloneApi && pagesApiDir ? { api: { dir: pagesApiDir, prefix: '/api' } } : {}),
+        });
         const descriptors = result.descriptors || [];
 
         if (descriptors.length === 0) {
@@ -101,10 +113,19 @@ function registerConsoleCommands(replServer, { context, meta, rootDir }) {
   replServer.defineCommand('flags', {
     help: 'List all active feature flags and targeting rules',
     action() {
-      if (!context.flags || typeof context.flags.list !== 'function') {
+      if (!context.flags) {
         console.log('\n⚠️  No feature flags configured.\n');
       } else {
-        const flags = context.flags.list();
+        const flags = typeof context.flags.list === 'function'
+          ? context.flags.list()
+          : (typeof context.flags.store?.getAll === 'function'
+            ? context.flags.store.getAll()
+            : (typeof context.flags.getAllFlags === 'function' ? context.flags.getAllFlags() : null));
+        if (!flags || typeof flags !== 'object') {
+          console.log('\n⚠️  No feature flags configured.\n');
+          this.displayPrompt();
+          return;
+        }
         const entries = Object.entries(flags);
         if (entries.length === 0) {
           console.log('\n⚠️  No feature flags registered.\n');

package/core/console/repl.js

@@ -7,6 +7,7 @@
  * @module core/console/repl
  */
 
+const fs = require('fs');
 const repl = require('repl');
 const path = require('path');
 const { buildConsoleContext } = require('./context');
@@ -67,7 +68,12 @@ async function startConsole(options = {}) {
   if (options.history !== false && typeof replServer.setupHistory === 'function') {
     const historyPath = options.historyPath || path.resolve(meta.rootDir, '.webspresso_history');
     try {
-      replServer.setupHistory(historyPath, () => {});
+      if (fs.existsSync(path.dirname(historyPath))) {
+        const res = replServer.setupHistory(historyPath, () => {});
+        if (res && typeof res.catch === 'function') {
+          res.catch(() => {});
+        }
+      }
     } catch (_) {
       // Gracefully continue without persistent history if write fails
     }

package/core/http/pipeline.js

@@ -229,13 +229,71 @@ async function executeApiPipeline(params) {
       req.service.invalidateTags = req.service.invalidateByTags;
     }
 
+    const rawValidateHeader = req && req.headers ? req.headers['x-webspresso-validate-fields'] : null;
+    const hasValidateHeader = Boolean(rawValidateHeader && String(rawValidateHeader).trim());
+    if (hasValidateHeader && !(apiDef && apiDef.validateFields)) {
+      if (res && typeof res.status === 'function' && typeof res.json === 'function') {
+        return res.status(400).json({
+          status: 400,
+          error: 'Field validation not enabled on this endpoint',
+          message: 'Field validation not enabled on this endpoint',
+          code: 'FIELD_VALIDATION_NOT_ENABLED',
+        });
+      }
+      const err = new Error('Field validation not enabled on this endpoint');
+      err.status = 400;
+      throw err;
+    }
+
+    const isFieldValidationRequest = Boolean(hasValidateHeader && apiDef && apiDef.validateFields);
+    const requestedValidateFields = isFieldValidationRequest
+      ? String(rawValidateHeader).split(',').map((s) => s.trim()).filter(Boolean)
+      : [];
+    const allowedValidateFields =
+      isFieldValidationRequest && Array.isArray(apiDef.validateFields)
+        ? requestedValidateFields.filter((f) => apiDef.validateFields.includes(f))
+        : requestedValidateFields;
+    const fieldValidationErrors = {};
+
     // 2. Schema validation
     const pagesDir = context.pagesDir || appOptions.pagesDir || 'pages';
     const routeDir = descriptor._routeDir !== undefined
       ? descriptor._routeDir
       : (descriptor._routeDir = descriptor.file ? path.dirname(descriptor.file) : '');
 
-    if (compiledSchema) {
+    if (isFieldValidationRequest) {
+      req.input = {
+        body: req.body,
+        params: req.params,
+        query: req.query,
+      };
+      if (compiledSchema && compiledSchema.body) {
+        let issues = null;
+        if (typeof compiledSchema.body.safeParse === 'function') {
+          const parsed = compiledSchema.body.safeParse(req.body);
+          if (parsed.success) {
+            req.input.body = parsed.data;
+          } else if (parsed.error && Array.isArray(parsed.error.issues)) {
+            issues = parsed.error.issues;
+          }
+        } else if (typeof compiledSchema.body.parse === 'function') {
+          try {
+            req.input.body = compiledSchema.body.parse(req.body);
+          } catch (parseErr) {
+            if (Array.isArray(parseErr?.issues)) issues = parseErr.issues;
+          }
+        }
+        if (issues) {
+          const translated = translateValidationIssues(issues, { req, pagesDir, routeDir, isDev });
+          for (const issue of translated) {
+            const pathKey = Array.isArray(issue.path) && issue.path.length > 0 ? String(issue.path[0]) : null;
+            if (pathKey && allowedValidateFields.includes(pathKey) && !fieldValidationErrors[pathKey]) {
+              fieldValidationErrors[pathKey] = issue.message || 'Invalid value';
+            }
+          }
+        }
+      }
+    } else if (compiledSchema) {
       try {
         validateRequestInput(req, compiledSchema);
       } catch (err) {
@@ -348,6 +406,29 @@ async function executeApiPipeline(params) {
         if (res && (res.headersSent || res.writableEnded || res.finished)) return;
       }
 
+      if (isFieldValidationRequest) {
+        if (typeof apiDef.validate === 'function') {
+          const customErrs = await apiDef.validate(apiCtx, allowedValidateFields);
+          if (customErrs && typeof customErrs === 'object') {
+            for (const [k, v] of Object.entries(customErrs)) {
+              if (allowedValidateFields.includes(k) && v && !fieldValidationErrors[k]) {
+                fieldValidationErrors[k] = String(v);
+              }
+            }
+          }
+        }
+        const payload = {
+          ok: Object.keys(fieldValidationErrors).length === 0,
+          valid: Object.keys(fieldValidationErrors).length === 0,
+          errors: fieldValidationErrors,
+          validatedFields: allowedValidateFields,
+        };
+        if (res && typeof res.status === 'function' && typeof res.json === 'function') {
+          return res.status(200).json(payload);
+        }
+        return payload;
+      }
+
       const result = await handlerFn(req, res, apiCtx);
 
       // 5. Auto-respond if handler returned a value and response not yet sent

package/core/openapi/build-from-api-routes.js

@@ -7,7 +7,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { zodToJsonSchema } = require('zod-to-json-schema');
+const { zodToJsonSchemaCompat, getZodTypeName } = require('../validation/zod-introspect');
 const { compileSchema } = require('../compileSchema');
 const { generateOrmOpenApiSchemas } = require('./orm-components');
 
@@ -100,13 +100,13 @@ function inferOperationTags(routePath, explicitTags) {
  * @returns {object[]}
  */
 function expandZodObjectToParameters(zodObj, where) {
-  if (!zodObj || zodObj._def?.typeName !== 'ZodObject') return [];
+  if (!zodObj || getZodTypeName(zodObj) !== 'ZodObject') return [];
   const shape = zodObj.shape;
   return Object.entries(shape).map(([name, zType]) => ({
     name,
     in: where,
     required: where === 'path' ? true : !zType.isOptional(),
-    schema: zodToJsonSchema(zType, { target: 'openApi3', $refStrategy: 'none' }),
+    schema: zodToJsonSchemaCompat(zType, { target: 'openApi3', $refStrategy: 'none' }),
   }));
 }
 
@@ -169,7 +169,7 @@ function buildOperation(route, compiled, mod = null) {
       description: 'OK',
       content: {
         'application/json': {
-          schema: zodToJsonSchema(compiled.response, { target: 'openApi3', $refStrategy: 'none' }),
+          schema: zodToJsonSchemaCompat(compiled.response, { target: 'openApi3', $refStrategy: 'none' }),
         },
       },
     };
@@ -188,7 +188,7 @@ function buildOperation(route, compiled, mod = null) {
     op.requestBody = {
       content: {
         'application/json': {
-          schema: zodToJsonSchema(compiled.body, { target: 'openApi3', $refStrategy: 'none' }),
+          schema: zodToJsonSchemaCompat(compiled.body, { target: 'openApi3', $refStrategy: 'none' }),
         },
       },
     };