webspresso 0.0.112 → 0.0.113

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 {
@@ -811,6 +853,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'] || '/';
@@ -894,6 +939,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 +959,8 @@ function createFragmentRefreshHandler(config) {
       });
 
       const results = {};
+      const fragmentErrors = {};
+      let firstError = null;
 
       for (const reqItem of requestedFragments) {
         const fragName = reqItem.name.trim();
@@ -932,34 +981,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/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' }),
         },
       },
     };

package/core/orm/json-fields.js

@@ -3,6 +3,8 @@
  * @module core/orm/json-fields
  */
 
+const { getZodDef, getZodInner, getZodTypeName } = require('../validation/zod-introspect');
+
 /**
  * Get JSON column names from model
  * @param {import('./types').ModelDefinition} model - Model definition
@@ -31,16 +33,15 @@ function getJsonColumns(model) {
   if (model && model.schema && model.schema.shape) {
     for (const [name, fieldSchema] of Object.entries(model.schema.shape)) {
       let current = fieldSchema;
-      while (current && current._def) {
-        if (current._def.innerType) {
-          current = current._def.innerType;
-        } else if (current._def.schema) {
-          current = current._def.schema;
+      while (current && getZodDef(current)) {
+        const inner = getZodInner(current);
+        if (inner) {
+          current = inner;
         } else {
           break;
         }
       }
-      const typeName = current?._def?.typeName;
+      const typeName = getZodTypeName(current);
       if (typeName === 'ZodRecord' || typeName === 'ZodObject' || typeName === 'ZodArray') {
         jsonCols.add(name);
       }

package/core/orm/schema-helpers.js

@@ -5,6 +5,13 @@
  */
 
 const { safeJsonParse } = require('../utils/json');
+const {
+  getZodDef,
+  getZodTypeName,
+  getZodInner,
+  getZodEnumValues,
+  isZodInt,
+} = require('../validation/zod-introspect');
 
 const METADATA_MARKER = '__wdb__';
 const metaWeakMap = new WeakMap();
@@ -665,10 +672,7 @@ function createSchemaHelpers(z) {
      */
     json(options = {}) {
       const { nullable = false, ...rest } = options;
-      let schema = z.unknown();
-      if (nullable) {
-        schema = schema.nullable().optional();
-      }
+      let schema = nullable ? z.unknown().nullable().optional() : z.unknown().optional();
       return createSchemaBuilder(schema, {
         type: 'json',
         nullable,
@@ -888,14 +892,14 @@ function extractColumnsFromSchema(schema) {
     // Unwrap optional/nullable wrappers to get to the base schema
     let current = schemaToCheck;
     let isNullable = false;
-    while (current && current._def) {
-      if (current._def.typeName === 'ZodNullable' || current._def.typeName === 'ZodOptional') {
+    while (current && getZodDef(current)) {
+      const currentType = getZodTypeName(current);
+      if (currentType === 'ZodNullable' || currentType === 'ZodOptional') {
         isNullable = true;
       }
-      if (current._def.innerType) {
-        current = current._def.innerType;
-      } else if (current._def.schema) {
-        current = current._def.schema;
+      const inner = getZodInner(current);
+      if (inner) {
+        current = inner;
       } else {
         break;
       }
@@ -905,16 +909,15 @@ function extractColumnsFromSchema(schema) {
     const meta = getColumnMeta(schemaToCheck) || (current ? getColumnMeta(current) : null);
     if (meta) {
       columns.set(key, meta);
-    } else if (current && current._def && current._def.typeName) {
-      const typeName = current._def.typeName;
+    } else if (current && getZodTypeName(current)) {
+      const typeName = getZodTypeName(current);
       let inferred = null;
       switch (typeName) {
         case 'ZodString':
           inferred = { type: 'string', maxLength: 255, nullable: isNullable };
           break;
         case 'ZodNumber': {
-          const isInt = current._def.checks?.some((c) => c.kind === 'int');
-          inferred = { type: isInt ? 'integer' : 'float', nullable: isNullable };
+          inferred = { type: isZodInt(current) ? 'integer' : 'float', nullable: isNullable };
           break;
         }
         case 'ZodBoolean':
@@ -924,7 +927,7 @@ function extractColumnsFromSchema(schema) {
           inferred = { type: 'timestamp', nullable: isNullable };
           break;
         case 'ZodEnum':
-          inferred = { type: 'enum', enumValues: current._def.values || [], nullable: isNullable };
+          inferred = { type: 'enum', enumValues: getZodEnumValues(current), nullable: isNullable };
           break;
         case 'ZodArray':
           inferred = { type: 'files', nullable: isNullable };

package/core/orm/utils/nanoid.js

@@ -63,14 +63,13 @@ function resolveNanoidSize(arg) {
  * @param {typeof import('zod').z} zod
  */
 function extendZ(zod) {
-  return new Proxy(zod, {
-    get(target, prop, receiver) {
-      if (prop === 'nanoid') {
-        return function nanoid(arg) {
-          return zodNanoid(zod, resolveNanoidSize(arg));
-        };
-      }
-      return Reflect.get(target, prop, receiver);
+  return Object.create(zod, {
+    nanoid: {
+      value: function nanoid(arg) {
+        return zodNanoid(zod, resolveNanoidSize(arg));
+      },
+      enumerable: true,
+      configurable: true,
     },
   });
 }

package/core/services/validator.js

@@ -293,7 +293,18 @@ function validateServiceInput(schema, input, serviceName, options = {}) {
   // 1. Zod schema validation
   if (compiled instanceof z.ZodType || typeof compiled.safeParse === 'function') {
     try {
-      const result = compiled.safeParse(sanitized);
+      let result;
+      if (compiled._zod && typeof compiled._zod.run === 'function') {
+        const rawRun = compiled._zod.run({ value: sanitized, issues: [] }, { async: true });
+        if (rawRun instanceof Promise) {
+          // Attach no-op catch so async refinements rejected during sync preflight don't emit UnhandledRejection
+          rawRun.catch(() => {});
+          throw new Error('Encountered Promise during synchronous parse');
+        }
+        result = rawRun.issues.length ? compiled.safeParse(sanitized) : { success: true, data: rawRun.value };
+      } else {
+        result = compiled.safeParse(sanitized);
+      }
       if (!result.success) {
         const { message, fields, fieldErrors } = formatZodErrors(result.error, serviceName);
         throw createServiceValidationError(message, {

package/core/validation/apply.js

@@ -6,6 +6,9 @@
  * @module core/validation/apply
  */
 
+const { ensureZodCompat } = require('./zod-introspect');
+ensureZodCompat();
+
 const EMPTY_INPUT = Object.freeze({
   body: undefined,
   params: undefined,