cogsbox-state 0.5.435 → 0.5.436

package/src/CogsState.tsx

@@ -26,12 +26,18 @@ import { ValidationWrapper } from './Functions.js';
 import { isDeepEqual, transformStateFunc } from './utility.js';
 import superjson from 'superjson';
 import { v4 as uuidv4 } from 'uuid';
-import { z } from 'zod';
 
-import { formRefStore, getGlobalStore, type ComponentsType } from './store.js';
+import {
+  formRefStore,
+  getGlobalStore,
+  ValidationStatus,
+  type ComponentsType,
+} from './store.js';
 import { useCogsConfig } from './CogsStateClient.js';
 import { applyPatch, compare, Operation } from 'fast-json-patch';
 import { useInView } from 'react-intersection-observer';
+import * as z3 from 'zod/v3';
+import * as z4 from 'zod/v4';
 
 type Prettify<T> = T extends any ? { [K in keyof T]: T[K] } : never;
 
@@ -217,12 +223,15 @@ export type FormOptsType = {
   validation?: {
     hideMessage?: boolean;
     message?: string;
-    stretch?: boolean;
+
     props?: GenericObject;
     disable?: boolean;
   };
 
   debounceTime?: number;
+  sync?: {
+    allowInvalidValues?: boolean; // default: false
+  };
 };
 
 export type FormControl<T> = (obj: FormElementParams<T>) => JSX.Element;
@@ -248,6 +257,7 @@ export type EndType<T, IsArrayElement = false> = {
   _stateKey: string;
   formElement: (control: FormControl<T>, opts?: FormOptsType) => JSX.Element;
   get: () => T;
+  getState: () => T;
   $get: () => T;
   $derive: <R>(fn: EffectFunction<T, R>) => R;
 
@@ -317,13 +327,17 @@ type EffectiveSetStateArg<
     ? InsertParams<InferArrayElement<T>>
     : never
   : UpdateArg<T>;
+type UpdateOptions = {
+  updateType: 'insert' | 'cut' | 'update';
 
+  sync?: boolean;
+};
 type EffectiveSetState<TStateObject> = (
   newStateOrFunction:
     | EffectiveSetStateArg<TStateObject, 'update'>
     | EffectiveSetStateArg<TStateObject, 'insert'>,
   path: string[],
-  updateObj: { updateType: 'update' | 'insert' | 'cut' },
+  updateObj: UpdateOptions,
   validationKey?: string
 ) => void;
 
@@ -346,11 +360,6 @@ export type ReactivityType =
   | 'all'
   | Array<Prettify<'none' | 'component' | 'deps' | 'all'>>;
 
-type ValidationOptionsType = {
-  key?: string;
-  zodSchema?: z.ZodTypeAny;
-  onBlur?: boolean;
-};
 // Define the return type of the sync hook locally
 type SyncApi = {
   updateState: (data: { operation: any }) => void;
@@ -358,6 +367,13 @@ type SyncApi = {
   clientId: string | null;
   subscribers: string[];
 };
+type ValidationOptionsType = {
+  key?: string;
+  zodSchemaV3?: z3.ZodType<any, any, any>;
+  zodSchemaV4?: z4.ZodType<any, any, any>;
+
+  onBlur?: boolean;
+};
 export type OptionsType<T extends unknown = unknown> = {
   log?: boolean;
   componentId?: string;
@@ -402,7 +418,7 @@ export type OptionsType<T extends unknown = unknown> = {
     key: string | ((state: T) => string);
     onChange?: (state: T) => void;
   };
-  formElements?: FormsElementsType;
+  formElements?: FormsElementsType<T>;
 
   reactiveDeps?: (state: T) => any[] | true;
   reactiveType?: ReactivityType;
@@ -412,15 +428,6 @@ export type OptionsType<T extends unknown = unknown> = {
   dependencies?: any[];
 };
 
-export type ValidationWrapperOptions<T extends unknown = unknown> = {
-  children: React.ReactNode;
-  active: boolean;
-  stretch?: boolean;
-  path: string[];
-  message?: string;
-  data?: T;
-  key?: string;
-};
 export type SyncRenderOptions<T extends unknown = unknown> = {
   children: React.ReactNode;
   time: number;
@@ -428,8 +435,16 @@ export type SyncRenderOptions<T extends unknown = unknown> = {
   key?: string;
 };
 
-type FormsElementsType<T extends unknown = unknown> = {
-  validation?: (options: ValidationWrapperOptions<T>) => React.ReactNode;
+type FormsElementsType<T> = {
+  validation?: (options: {
+    children: React.ReactNode;
+    status: ValidationStatus; // Instead of 'active' boolean
+
+    path: string[];
+    message?: string;
+    data?: T;
+    key?: string;
+  }) => React.ReactNode;
   syncRender?: (options: SyncRenderOptions<T>) => React.ReactNode;
 };
 
@@ -518,9 +533,32 @@ export function addStateOptions<T extends unknown>(
 ) {
   return { initialState: initialState, formElements, validation } as T;
 }
+type UseCogsStateHook<T extends Record<string, any>> = <
+  StateKey extends keyof TransformedStateType<T>,
+>(
+  stateKey: StateKey,
+  options?: Prettify<OptionsType<TransformedStateType<T>[StateKey]>>
+) => StateObject<TransformedStateType<T>[StateKey]>;
+
+// Define the type for the options setter using the Transformed state
+type SetCogsOptionsFunc<T extends Record<string, any>> = <
+  StateKey extends keyof TransformedStateType<T>,
+>(
+  stateKey: StateKey,
+  options: OptionsType<TransformedStateType<T>[StateKey]>
+) => void;
+
+// Define the final API object shape
+type CogsApi<T extends Record<string, any>> = {
+  useCogsState: UseCogsStateHook<T>;
+  setCogsOptions: SetCogsOptionsFunc<T>;
+};
 export const createCogsState = <State extends Record<StateKeys, unknown>>(
   initialState: State,
-  opt?: { formElements?: FormsElementsType; validation?: ValidationOptionsType }
+  opt?: {
+    formElements?: FormsElementsType<State>;
+    validation?: ValidationOptionsType;
+  }
 ) => {
   let newInitialState = initialState;
 
@@ -575,12 +613,12 @@ export const createCogsState = <State extends Record<StateKeys, unknown>>(
 
   const useCogsState = <StateKey extends StateKeys>(
     stateKey: StateKey,
-    options?: OptionsType<(typeof statePart)[StateKey]>
+    options?: Prettify<OptionsType<(typeof statePart)[StateKey]>>
   ) => {
     const [componentId] = useState(options?.componentId ?? uuidv4());
     setOptions({
       stateKey,
-      options,
+      options: options as any,
       initialOptionsPart,
     });
 
@@ -621,7 +659,7 @@ export const createCogsState = <State extends Record<StateKeys, unknown>>(
     notifyComponents(stateKey as string);
   }
 
-  return { useCogsState, setCogsOptions };
+  return { useCogsState, setCogsOptions } as CogsApi<State>;
 };
 
 const {
@@ -1241,9 +1279,7 @@ export function useCogsStateFn<TStateObject extends unknown>(
       ...rootMeta,
       components,
     });
-
     forceUpdate({});
-
     return () => {
       const meta = getGlobalStore.getState().getShadowMetadata(thisKey, []);
       const component = meta?.components?.get(componentKey);
@@ -1282,8 +1318,7 @@ export function useCogsStateFn<TStateObject extends unknown>(
   const effectiveSetState = (
     newStateOrFunction: UpdateArg<TStateObject> | InsertParams<TStateObject>,
     path: string[],
-    updateObj: { updateType: 'insert' | 'cut' | 'update' },
-    validationKey?: string
+    updateObj: UpdateOptions
   ) => {
     const fullPath = [thisKey, ...path].join('.');
     if (Array.isArray(path)) {
@@ -1349,9 +1384,9 @@ export function useCogsStateFn<TStateObject extends unknown>(
         break;
       }
     }
+    const shouldSync = updateObj.sync !== false;
 
-    console.log('sdadasdasd', syncApiRef.current, newUpdate);
-    if (syncApiRef.current && syncApiRef.current.connected) {
+    if (shouldSync && syncApiRef.current && syncApiRef.current.connected) {
       syncApiRef.current.updateState({ operation: newUpdate });
     }
     // Handle signals - reuse shadowMeta from the beginning
@@ -1519,59 +1554,18 @@ export function useCogsStateFn<TStateObject extends unknown>(
         });
       }
     }
-    if (
-      updateObj.updateType === 'update' &&
-      (validationKey || latestInitialOptionsRef.current?.validation?.key) &&
-      path
-    ) {
-      removeValidationError(
-        (validationKey || latestInitialOptionsRef.current?.validation?.key) +
-          '.' +
-          path.join('.')
-      );
-    }
-    const arrayWithoutIndex = path.slice(0, path.length - 1);
-    if (
-      updateObj.updateType === 'cut' &&
-      latestInitialOptionsRef.current?.validation?.key
-    ) {
-      removeValidationError(
-        latestInitialOptionsRef.current?.validation?.key +
-          '.' +
-          arrayWithoutIndex.join('.')
-      );
-    }
-    if (
-      updateObj.updateType === 'insert' &&
-      latestInitialOptionsRef.current?.validation?.key
-    ) {
-      const getValidation = getValidationErrors(
-        latestInitialOptionsRef.current?.validation?.key +
-          '.' +
-          arrayWithoutIndex.join('.')
-      );
-
-      getValidation.filter((k) => {
-        let length = k?.split('.').length;
-        const v = ''; // Placeholder as `v` is not used from getValidationErrors
 
-        if (
-          k == arrayWithoutIndex.join('.') &&
-          length == arrayWithoutIndex.length - 1
-        ) {
-          let newKey = k + '.' + arrayWithoutIndex;
-          removeValidationError(k!);
-          addValidationError(newKey, v!);
-        }
-      });
-    }
     // Assumes `isDeepEqual` is available in this scope.
     // Assumes `isDeepEqual` is available in this scope.
 
-    const newState = store.getShadowValue(thisKey);
-    const rootMeta = store.getShadowMetadata(thisKey, []);
+    const newState = getGlobalStore.getState().getShadowValue(thisKey);
+    const rootMeta = getGlobalStore.getState().getShadowMetadata(thisKey, []);
     const notifiedComponents = new Set<string>();
-
+    console.log(
+      'rootMeta',
+      thisKey,
+      getGlobalStore.getState().shadowStateStore
+    );
     if (!rootMeta?.components) {
       return newState;
     }
@@ -1579,28 +1573,39 @@ export function useCogsStateFn<TStateObject extends unknown>(
     // --- PASS 1: Notify specific subscribers based on update type ---
 
     if (updateObj.updateType === 'update') {
-      // ALWAYS notify components subscribed to the exact path being updated.
-      // This is the crucial part that handles primitives, as well as updates
-      // to an object or array treated as a whole.
-      if (shadowMeta?.pathComponents) {
-        shadowMeta.pathComponents.forEach((componentId) => {
-          // If this component was already notified, skip.
-          if (notifiedComponents.has(componentId)) {
-            return;
-          }
-          const component = rootMeta.components?.get(componentId);
-          if (component) {
-            const reactiveTypes = Array.isArray(component.reactiveType)
-              ? component.reactiveType
-              : [component.reactiveType || 'component'];
+      // --- Bubble-up Notification ---
+      // When a nested property changes, notify components listening at that exact path,
+      // and also "bubble up" to notify components listening on parent paths.
+      // e.g., an update to `user.address.street` notifies listeners of `street`, `address`, and `user`.
+      let currentPath = [...path]; // Create a mutable copy of the path
+
+      while (true) {
+        const currentPathMeta = store.getShadowMetadata(thisKey, currentPath);
+
+        if (currentPathMeta?.pathComponents) {
+          currentPathMeta.pathComponents.forEach((componentId) => {
+            if (notifiedComponents.has(componentId)) {
+              return; // Avoid sending redundant notifications
+            }
+            const component = rootMeta.components?.get(componentId);
+            if (component) {
+              const reactiveTypes = Array.isArray(component.reactiveType)
+                ? component.reactiveType
+                : [component.reactiveType || 'component'];
 
-            // Check if the component has reactivity enabled
-            if (!reactiveTypes.includes('none')) {
-              component.forceUpdate();
-              notifiedComponents.add(componentId);
+              // This notification logic applies to components that depend on object structures.
+              if (!reactiveTypes.includes('none')) {
+                component.forceUpdate();
+                notifiedComponents.add(componentId);
+              }
             }
-          }
-        });
+          });
+        }
+
+        if (currentPath.length === 0) {
+          break; // We've reached the root, stop bubbling.
+        }
+        currentPath.pop(); // Go up one level for the next iteration.
       }
 
       // ADDITIONALLY, if the payload is an object, perform a deep-check and
@@ -1880,12 +1885,16 @@ const registerComponentDependency = (
   dependencyPath: string[]
 ) => {
   const fullComponentId = `${stateKey}////${componentId}`;
-  const rootMeta = getGlobalStore.getState().getShadowMetadata(stateKey, []);
+  const { addPathComponent, getShadowMetadata } = getGlobalStore.getState();
+
+  // First, check if the component should even be registered.
+  // This check is safe to do outside the setter.
+  const rootMeta = getShadowMetadata(stateKey, []);
   const component = rootMeta?.components?.get(fullComponentId);
 
   if (
     !component ||
-    component.reactiveType == 'none' ||
+    component.reactiveType === 'none' ||
     !(
       Array.isArray(component.reactiveType)
         ? component.reactiveType
@@ -1895,23 +1904,9 @@ const registerComponentDependency = (
     return;
   }
 
-  const pathKey = [stateKey, ...dependencyPath].join('.');
-
-  // Add to component's paths (existing logic)
-  component.paths.add(pathKey);
-
-  // NEW: Also store componentId at the path level
-  const pathMeta =
-    getGlobalStore.getState().getShadowMetadata(stateKey, dependencyPath) || {};
-  const pathComponents = pathMeta.pathComponents || new Set<string>();
-  pathComponents.add(fullComponentId);
-
-  getGlobalStore.getState().setShadowMetadata(stateKey, dependencyPath, {
-    ...pathMeta,
-    pathComponents,
-  });
+  // Now, call the single, safe, atomic function to perform the update.
+  addPathComponent(stateKey, dependencyPath, fullComponentId);
 };
-
 const notifySelectionComponents = (
   stateKey: string,
   parentPath: string[],
@@ -2184,13 +2179,16 @@ function createProxyHandler<T>(
         }
         if (prop === 'showValidationErrors') {
           return () => {
-            const init = getGlobalStore
-              .getState()
-              .getInitialOptions(stateKey)?.validation;
-            if (!init?.key) throw new Error('Validation key not found');
-            return getGlobalStore
+            const meta = getGlobalStore
               .getState()
-              .getValidationErrors(init.key + '.' + path.join('.'));
+              .getShadowMetadata(stateKey, path);
+            if (
+              meta?.validation?.status === 'VALIDATION_FAILED' &&
+              meta.validation.message
+            ) {
+              return [meta.validation.message];
+            }
+            return [];
           };
         }
         if (Array.isArray(currentState)) {
@@ -3019,7 +3017,6 @@ function createProxyHandler<T>(
                         e.type === 'REMOVE' ||
                         e.type === 'CLEAR_SELECTION'
                       ) {
-                        console.log('sssssssssssssssssssssssssssss', e);
                         forceUpdate({});
                       }
                     });
@@ -3221,15 +3218,12 @@ function createProxyHandler<T>(
           }
           if (prop === 'cutSelected') {
             return () => {
-              const baseArrayKeys =
-                getGlobalStore.getState().getShadowMetadata(stateKey, path)
-                  ?.arrayKeys || [];
               const validKeys = applyTransforms(
                 stateKey,
                 path,
                 meta?.transforms
               );
-              console.log('validKeys', validKeys);
+
               if (!validKeys || validKeys.length === 0) return;
 
               const indexKeyToCut = getGlobalStore
@@ -3239,13 +3233,15 @@ function createProxyHandler<T>(
               let indexToCut = validKeys.findIndex(
                 (key) => key === indexKeyToCut
               );
-              console.log('indexToCut', indexToCut);
+
               const pathForCut = validKeys[
                 indexToCut == -1 ? validKeys.length - 1 : indexToCut
               ]
                 ?.split('.')
                 .slice(1);
-              console.log('pathForCut', pathForCut);
+              getGlobalStore
+                .getState()
+                .clearSelectedIndex({ arrayKey: stateKeyPathKey });
               effectiveSetState(currentState, pathForCut!, {
                 updateType: 'cut',
               });
@@ -3371,6 +3367,14 @@ function createProxyHandler<T>(
               .getShadowValue(stateKeyPathKey, meta?.validIds);
           };
         }
+        if (prop === 'getState') {
+          return () => {
+            return getGlobalStore
+              .getState()
+              .getShadowValue(stateKeyPathKey, meta?.validIds);
+          };
+        }
+
         if (prop === '$derive') {
           return (fn: any) =>
             $cogsSignal({
@@ -3481,8 +3485,9 @@ function createProxyHandler<T>(
           }
           if (prop === 'applyJsonPatch') {
             return (patches: Operation[]) => {
-              // 1. Get the current state object that the proxy points to.
               const store = getGlobalStore.getState();
+              const rootMeta = store.getShadowMetadata(stateKey, []);
+              if (!rootMeta?.components) return;
 
               const convertPath = (jsonPath: string): string[] => {
                 if (!jsonPath || jsonPath === '/') return [];
@@ -3492,6 +3497,8 @@ function createProxyHandler<T>(
                   .map((p) => p.replace(/~1/g, '/').replace(/~0/g, '~'));
               };
 
+              const notifiedComponents = new Set<string>();
+
               for (const patch of patches) {
                 const relativePath = convertPath(patch.path);
 
@@ -3504,18 +3511,64 @@ function createProxyHandler<T>(
                       value: any;
                     };
                     store.updateShadowAtPath(stateKey, relativePath, value);
-                    store.markAsDirty(stateKey, relativePath, { bubble: true }); // Or handle status differently for server patches
+                    store.markAsDirty(stateKey, relativePath, { bubble: true });
+
+                    // Bubble up - notify components at this path and all parent paths
+                    let currentPath = [...relativePath];
+                    while (true) {
+                      const pathMeta = store.getShadowMetadata(
+                        stateKey,
+                        currentPath
+                      );
+                      console.log('pathMeta', pathMeta);
+                      if (pathMeta?.pathComponents) {
+                        pathMeta.pathComponents.forEach((componentId) => {
+                          if (!notifiedComponents.has(componentId)) {
+                            const component =
+                              rootMeta.components?.get(componentId);
+                            if (component) {
+                              component.forceUpdate();
+                              notifiedComponents.add(componentId);
+                            }
+                          }
+                        });
+                      }
+
+                      if (currentPath.length === 0) break;
+                      currentPath.pop(); // Go up one level
+                    }
                     break;
                   }
                   case 'remove': {
-                    store.removeShadowArrayElement(stateKey, relativePath);
                     const parentPath = relativePath.slice(0, -1);
+                    store.removeShadowArrayElement(stateKey, relativePath);
                     store.markAsDirty(stateKey, parentPath, { bubble: true });
+
+                    // Bubble up from parent path
+                    let currentPath = [...parentPath];
+                    while (true) {
+                      const pathMeta = store.getShadowMetadata(
+                        stateKey,
+                        currentPath
+                      );
+                      if (pathMeta?.pathComponents) {
+                        pathMeta.pathComponents.forEach((componentId) => {
+                          if (!notifiedComponents.has(componentId)) {
+                            const component =
+                              rootMeta.components?.get(componentId);
+                            if (component) {
+                              component.forceUpdate();
+                              notifiedComponents.add(componentId);
+                            }
+                          }
+                        });
+                      }
+
+                      if (currentPath.length === 0) break;
+                      currentPath.pop();
+                    }
                     break;
                   }
-                  // NOTE: 'move' and 'copy' operations should be deconstructed into 'remove' and 'add'
-                  // by the server before broadcasting for maximum compatibility. Your server's use
-                  // of `compare()` already does this, so we don't need to handle them here.
                 }
               }
             };
@@ -3525,20 +3578,40 @@ function createProxyHandler<T>(
               const init = getGlobalStore
                 .getState()
                 .getInitialOptions(stateKey)?.validation;
-              if (!init?.zodSchema || !init?.key)
-                throw new Error('Zod schema or validation key not found');
+
+              // UPDATED: Select v4 schema, with a fallback to v3
+              const zodSchema = init?.zodSchemaV4 || init?.zodSchemaV3;
+
+              if (!zodSchema || !init?.key) {
+                throw new Error(
+                  'Zod schema (v3 or v4) or validation key not found'
+                );
+              }
 
               removeValidationError(init.key);
               const thisObject = getGlobalStore
                 .getState()
                 .getShadowValue(stateKey);
-              const result = init.zodSchema.safeParse(thisObject);
+
+              // Use the selected schema for parsing
+              const result = zodSchema.safeParse(thisObject);
 
               if (!result.success) {
-                result.error.errors.forEach((error) => {
-                  const fullErrorPath = [init.key, ...error.path].join('.');
-                  addValidationError(fullErrorPath, error.message);
-                });
+                // This logic already handles both v3 and v4 error types correctly
+                if ('issues' in result.error) {
+                  // Zod v4 error
+                  result.error.issues.forEach((error) => {
+                    const fullErrorPath = [init.key, ...error.path].join('.');
+                    addValidationError(fullErrorPath, error.message);
+                  });
+                } else {
+                  // Zod v3 error
+                  (result.error as any).errors.forEach((error: any) => {
+                    const fullErrorPath = [init.key, ...error.path].join('.');
+                    addValidationError(fullErrorPath, error.message);
+                  });
+                }
+
                 notifyComponents(stateKey);
                 return false;
               }
@@ -3631,20 +3704,14 @@ function createProxyHandler<T>(
         if (prop === 'formElement') {
           return (child: FormControl<T>, formOpts?: FormOptsType) => {
             return (
-              <ValidationWrapper
-                formOpts={formOpts}
-                path={path}
+              <FormElementWrapper
                 stateKey={stateKey}
-              >
-                <FormElementWrapper
-                  stateKey={stateKey}
-                  path={path}
-                  rebuildStateShape={rebuildStateShape}
-                  setState={effectiveSetState}
-                  formOpts={formOpts}
-                  renderFn={child as any}
-                />
-              </ValidationWrapper>
+                path={path}
+                rebuildStateShape={rebuildStateShape}
+                setState={effectiveSetState}
+                formOpts={formOpts}
+                renderFn={child as any}
+              />
             );
           };
         }
@@ -4203,6 +4270,7 @@ function ListItemWrapper({
 
   return <div ref={setRefs}>{children}</div>;
 }
+
 function FormElementWrapper({
   stateKey,
   path,
@@ -4248,7 +4316,9 @@ function FormElementWrapper({
     const unsubscribe = getGlobalStore
       .getState()
       .subscribeToPath(stateKeyPathKey, (newValue) => {
-        forceUpdate({});
+        if (!isCurrentlyDebouncing.current && localValue !== newValue) {
+          forceUpdate({});
+        }
       });
     return () => {
       unsubscribe();
@@ -4261,6 +4331,10 @@ function FormElementWrapper({
 
   const debouncedUpdate = useCallback(
     (newValue: any) => {
+      const currentType = typeof globalStateValue;
+      if (currentType === 'number' && typeof newValue === 'string') {
+        newValue = newValue === '' ? 0 : Number(newValue);
+      }
       setLocalValue(newValue);
       isCurrentlyDebouncing.current = true;
 
@@ -4272,19 +4346,188 @@ function FormElementWrapper({
 
       debounceTimeoutRef.current = setTimeout(() => {
         isCurrentlyDebouncing.current = false;
+
+        // Update state
         setState(newValue, path, { updateType: 'update' });
+
+        // Perform LIVE validation (gentle)
+        const { getInitialOptions, setShadowMetadata, getShadowMetadata } =
+          getGlobalStore.getState();
+        const validationOptions = getInitialOptions(stateKey)?.validation;
+        const zodSchema =
+          validationOptions?.zodSchemaV4 || validationOptions?.zodSchemaV3;
+
+        if (zodSchema) {
+          const fullState = getGlobalStore.getState().getShadowValue(stateKey);
+          const result = zodSchema.safeParse(fullState);
+
+          const currentMeta = getShadowMetadata(stateKey, path) || {};
+
+          if (!result.success) {
+            const errors =
+              'issues' in result.error
+                ? result.error.issues
+                : (result.error as any).errors;
+            const pathErrors = errors.filter(
+              (error: any) =>
+                JSON.stringify(error.path) === JSON.stringify(path)
+            );
+
+            if (pathErrors.length > 0) {
+              setShadowMetadata(stateKey, path, {
+                ...currentMeta,
+                validation: {
+                  status: 'INVALID_LIVE',
+                  message: pathErrors[0]?.message,
+                  validatedValue: newValue,
+                },
+              });
+            } else {
+              // This field has no errors - clear validation
+              setShadowMetadata(stateKey, path, {
+                ...currentMeta,
+                validation: {
+                  status: 'VALID_LIVE',
+                  validatedValue: newValue,
+                },
+              });
+            }
+          } else {
+            // Validation passed - clear any existing errors
+            setShadowMetadata(stateKey, path, {
+              ...currentMeta,
+              validation: {
+                status: 'VALID_LIVE',
+                validatedValue: newValue,
+              },
+            });
+          }
+        }
       }, debounceTime);
+      forceUpdate({});
     },
-    [setState, path, formOpts?.debounceTime]
+    [setState, path, formOpts?.debounceTime, stateKey]
   );
 
-  const immediateUpdate = useCallback(() => {
+  // --- NEW onBlur HANDLER ---
+  // This replaces the old commented-out method with a modern approach.
+  const handleBlur = useCallback(async () => {
+    console.log('handleBlur triggered');
+
+    // Commit any pending changes
     if (debounceTimeoutRef.current) {
       clearTimeout(debounceTimeoutRef.current);
+      debounceTimeoutRef.current = null;
       isCurrentlyDebouncing.current = false;
       setState(localValue, path, { updateType: 'update' });
     }
-  }, [setState, path, localValue]);
+
+    const { getInitialOptions } = getGlobalStore.getState();
+    const validationOptions = getInitialOptions(stateKey)?.validation;
+    const zodSchema =
+      validationOptions?.zodSchemaV4 || validationOptions?.zodSchemaV3;
+
+    if (!zodSchema) return;
+
+    // Get the full path including stateKey
+
+    // Update validation state to "validating"
+    const currentMeta = getGlobalStore
+      .getState()
+      .getShadowMetadata(stateKey, path);
+    getGlobalStore.getState().setShadowMetadata(stateKey, path, {
+      ...currentMeta,
+      validation: {
+        status: 'DIRTY',
+        validatedValue: localValue,
+      },
+    });
+
+    // Validate full state
+    const fullState = getGlobalStore.getState().getShadowValue(stateKey);
+    const result = zodSchema.safeParse(fullState);
+    console.log('result ', result);
+    if (!result.success) {
+      const errors =
+        'issues' in result.error
+          ? result.error.issues
+          : (result.error as any).errors;
+
+      console.log('All validation errors:', errors);
+      console.log('Current blur path:', path);
+
+      // Find errors for this specific path
+      const pathErrors = errors.filter((error: any) => {
+        console.log('Processing error:', error);
+
+        // For array paths, we need to translate indices to ULIDs
+        if (path.some((p) => p.startsWith('id:'))) {
+          console.log('Detected array path with ULID');
+
+          // This is an array item path like ["id:xyz", "name"]
+          const parentPath = path[0]!.startsWith('id:')
+            ? []
+            : path.slice(0, -1);
+
+          console.log('Parent path:', parentPath);
+
+          const arrayMeta = getGlobalStore
+            .getState()
+            .getShadowMetadata(stateKey, parentPath);
+
+          console.log('Array metadata:', arrayMeta);
+
+          if (arrayMeta?.arrayKeys) {
+            const itemKey = [stateKey, ...path.slice(0, -1)].join('.');
+            const itemIndex = arrayMeta.arrayKeys.indexOf(itemKey);
+
+            console.log('Item key:', itemKey, 'Index:', itemIndex);
+
+            // Compare with Zod path
+            const zodPath = [...parentPath, itemIndex, ...path.slice(-1)];
+            const match =
+              JSON.stringify(error.path) === JSON.stringify(zodPath);
+
+            console.log('Zod path comparison:', {
+              zodPath,
+              errorPath: error.path,
+              match,
+            });
+            return match;
+          }
+        }
+
+        const directMatch = JSON.stringify(error.path) === JSON.stringify(path);
+        console.log('Direct path comparison:', {
+          errorPath: error.path,
+          currentPath: path,
+          match: directMatch,
+        });
+        return directMatch;
+      });
+
+      console.log('Filtered path errors:', pathErrors);
+      // Update shadow metadata with validation result
+      getGlobalStore.getState().setShadowMetadata(stateKey, path, {
+        ...currentMeta,
+        validation: {
+          status: 'VALIDATION_FAILED',
+          message: pathErrors[0]?.message,
+          validatedValue: localValue,
+        },
+      });
+    } else {
+      // Validation passed
+      getGlobalStore.getState().setShadowMetadata(stateKey, path, {
+        ...currentMeta,
+        validation: {
+          status: 'VALID_PENDING_SYNC',
+          validatedValue: localValue,
+        },
+      });
+    }
+    forceUpdate({});
+  }, [stateKey, path, localValue, setState]);
 
   const baseState = rebuildStateShape({
     currentState: globalStateValue,
@@ -4300,7 +4543,8 @@ function FormElementWrapper({
           onChange: (e: any) => {
             debouncedUpdate(e.target.value);
           },
-          onBlur: immediateUpdate,
+          // 5. Wire the new onBlur handler to the input props.
+          onBlur: handleBlur,
           ref: formRefStore
             .getState()
             .getFormRef(stateKey + '.' + path.join('.')),
@@ -4311,9 +4555,12 @@ function FormElementWrapper({
     },
   });
 
-  return <>{renderFn(stateWithInputProps)}</>;
+  return (
+    <ValidationWrapper formOpts={formOpts} path={path} stateKey={stateKey}>
+      {renderFn(stateWithInputProps)}
+    </ValidationWrapper>
+  );
 }
-
 function useRegisterComponent(
   stateKey: string,
   componentId: string,
@@ -4322,25 +4569,19 @@ function useRegisterComponent(
   const fullComponentId = `${stateKey}////${componentId}`;
 
   useLayoutEffect(() => {
-    const rootMeta = getGlobalStore.getState().getShadowMetadata(stateKey, []);
-    const components = rootMeta?.components || new Map();
+    const { registerComponent, unregisterComponent } =
+      getGlobalStore.getState();
 
-    components.set(fullComponentId, {
+    // Call the safe, centralized function to register
+    registerComponent(stateKey, fullComponentId, {
       forceUpdate: () => forceUpdate({}),
       paths: new Set(),
       reactiveType: ['component'],
     });
 
-    getGlobalStore.getState().setShadowMetadata(stateKey, [], {
-      ...rootMeta,
-      components,
-    });
-
+    // The cleanup now calls the safe, centralized unregister function
     return () => {
-      const meta = getGlobalStore.getState().getShadowMetadata(stateKey, []);
-      if (meta?.components) {
-        meta.components.delete(fullComponentId);
-      }
+      unregisterComponent(stateKey, fullComponentId);
     };
-  }, [stateKey, fullComponentId]);
+  }, [stateKey, fullComponentId]); // Dependencies are stable and correct
 }