cogsbox-state 0.5.434 → 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 } from 'fast-json-patch';
+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;
@@ -231,7 +240,7 @@ export type UpdateArg<S> = S | ((prevState: S) => S);
 export type InsertParams<S> =
   | S
   | ((prevState: { state: S; uuid: string }) => S);
-export type UpdateType<T> = (payload: UpdateArg<T>) => void;
+export type UpdateType<T> = (payload: UpdateArg<T>) => { synced: () => void };
 
 export type InsertType<T> = (payload: InsertParams<T>, index?: number) => void;
 export type InsertTypeObj<T> = (payload: InsertParams<T>) => void;
@@ -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,16 +360,24 @@ export type ReactivityType =
   | 'all'
   | Array<Prettify<'none' | 'component' | 'deps' | 'all'>>;
 
+// Define the return type of the sync hook locally
+type SyncApi = {
+  updateState: (data: { operation: any }) => void;
+  connected: boolean;
+  clientId: string | null;
+  subscribers: string[];
+};
 type ValidationOptionsType = {
   key?: string;
-  zodSchema?: z.ZodTypeAny;
+  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;
-  serverSync?: ServerSyncType<T>;
+  cogsSync?: (stateObject: StateObject<T>) => SyncApi;
   validation?: ValidationOptionsType;
 
   serverState?: {
@@ -396,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;
@@ -405,29 +427,7 @@ export type OptionsType<T extends unknown = unknown> = {
   defaultState?: T;
   dependencies?: any[];
 };
-export type ServerSyncType<T> = {
-  testKey?: string;
-  syncKey: (({ state }: { state: T }) => string) | string;
-  syncFunction: ({ state }: { state: T }) => void;
-  debounce?: number;
-
-  snapshot?: {
-    name: (({ state }: { state: T }) => string) | string;
-    stateKeys: StateKeys[];
-    currentUrl: string;
-    currentParams?: URLSearchParams;
-  };
-};
 
-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;
@@ -435,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;
 };
 
@@ -525,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;
 
@@ -582,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,
     });
 
@@ -628,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 {
@@ -782,12 +813,172 @@ export const notifyComponent = (stateKey: string, componentId: string) => {
     }
   }
 };
+function markEntireStateAsServerSynced(
+  stateKey: string,
+  path: string[],
+  data: any,
+  timestamp: number
+) {
+  const store = getGlobalStore.getState();
+
+  // Mark current path as synced
+  const currentMeta = store.getShadowMetadata(stateKey, path);
+  store.setShadowMetadata(stateKey, path, {
+    ...currentMeta,
+    isDirty: false,
+    stateSource: 'server',
+    lastServerSync: timestamp || Date.now(),
+  });
+
+  // If it's an array, mark each item as synced
+  if (Array.isArray(data)) {
+    const arrayMeta = store.getShadowMetadata(stateKey, path);
+    if (arrayMeta?.arrayKeys) {
+      arrayMeta.arrayKeys.forEach((itemKey, index) => {
+        const itemPath = itemKey.split('.').slice(1);
+        const itemData = data[index];
+        if (itemData !== undefined) {
+          markEntireStateAsServerSynced(
+            stateKey,
+            itemPath,
+            itemData,
+            timestamp
+          );
+        }
+      });
+    }
+  }
+  // If it's an object, mark each field as synced
+  else if (data && typeof data === 'object' && data.constructor === Object) {
+    Object.keys(data).forEach((key) => {
+      const fieldPath = [...path, key];
+      const fieldData = data[key];
+      markEntireStateAsServerSynced(stateKey, fieldPath, fieldData, timestamp);
+    });
+  }
+}
+
+const _notifySubscribedComponents = (
+  stateKey: string,
+  path: string[],
+  updateType: 'update' | 'insert' | 'cut',
+  oldValue: any,
+  newValue: any
+) => {
+  const store = getGlobalStore.getState();
+  const rootMeta = store.getShadowMetadata(stateKey, []);
+  if (!rootMeta?.components) {
+    return;
+  }
+
+  const notifiedComponents = new Set<string>();
+  const shadowMeta = store.getShadowMetadata(stateKey, path);
+
+  // --- PASS 1: Notify specific subscribers based on update type ---
+
+  if (updateType === 'update') {
+    if (shadowMeta?.pathComponents) {
+      shadowMeta.pathComponents.forEach((componentId) => {
+        if (notifiedComponents.has(componentId)) return;
+        const component = rootMeta.components?.get(componentId);
+        if (component) {
+          const reactiveTypes = Array.isArray(component.reactiveType)
+            ? component.reactiveType
+            : [component.reactiveType || 'component'];
+          if (!reactiveTypes.includes('none')) {
+            component.forceUpdate();
+            notifiedComponents.add(componentId);
+          }
+        }
+      });
+    }
+
+    if (
+      newValue &&
+      typeof newValue === 'object' &&
+      !isArray(newValue) &&
+      oldValue &&
+      typeof oldValue === 'object' &&
+      !isArray(oldValue)
+    ) {
+      const changedSubPaths = getDifferences(newValue, oldValue);
+      changedSubPaths.forEach((subPathString) => {
+        const subPath = subPathString.split('.');
+        const fullSubPath = [...path, ...subPath];
+        const subPathMeta = store.getShadowMetadata(stateKey, fullSubPath);
+        if (subPathMeta?.pathComponents) {
+          subPathMeta.pathComponents.forEach((componentId) => {
+            if (notifiedComponents.has(componentId)) return;
+            const component = rootMeta.components?.get(componentId);
+            if (component) {
+              const reactiveTypes = Array.isArray(component.reactiveType)
+                ? component.reactiveType
+                : [component.reactiveType || 'component'];
+              if (!reactiveTypes.includes('none')) {
+                component.forceUpdate();
+                notifiedComponents.add(componentId);
+              }
+            }
+          });
+        }
+      });
+    }
+  } else if (updateType === 'insert' || updateType === 'cut') {
+    const parentArrayPath = updateType === 'insert' ? path : path.slice(0, -1);
+    const parentMeta = store.getShadowMetadata(stateKey, parentArrayPath);
+    if (parentMeta?.pathComponents) {
+      parentMeta.pathComponents.forEach((componentId) => {
+        if (!notifiedComponents.has(componentId)) {
+          const component = rootMeta.components?.get(componentId);
+          if (component) {
+            component.forceUpdate();
+            notifiedComponents.add(componentId);
+          }
+        }
+      });
+    }
+  }
+
+  // --- PASS 2: Notify global subscribers ('all', 'deps') ---
+
+  rootMeta.components.forEach((component, componentId) => {
+    if (notifiedComponents.has(componentId)) {
+      return;
+    }
+
+    const reactiveTypes = Array.isArray(component.reactiveType)
+      ? component.reactiveType
+      : [component.reactiveType || 'component'];
+
+    if (reactiveTypes.includes('all')) {
+      component.forceUpdate();
+      notifiedComponents.add(componentId);
+      return;
+    }
+
+    if (reactiveTypes.includes('deps')) {
+      if (component.depsFunction) {
+        const currentState = store.getShadowValue(stateKey);
+        const newDeps = component.depsFunction(currentState);
+        let shouldUpdate = false;
+        if (newDeps === true || !isDeepEqual(component.prevDeps, newDeps)) {
+          if (Array.isArray(newDeps)) component.prevDeps = newDeps;
+          shouldUpdate = true;
+        }
+        if (shouldUpdate) {
+          component.forceUpdate();
+          notifiedComponents.add(componentId);
+        }
+      }
+    }
+  });
+};
 
 export function useCogsStateFn<TStateObject extends unknown>(
   stateObject: TStateObject,
   {
     stateKey,
-    serverSync,
+
     localStorage,
     formElements,
     reactiveDeps,
@@ -901,7 +1092,6 @@ export function useCogsStateFn<TStateObject extends unknown>(
     const unsubscribe = getGlobalStore
       .getState()
       .subscribeToPath(thisKey, (event) => {
-        // REPLACEMENT STARTS HERE
         if (event?.type === 'SERVER_STATE_UPDATE') {
           const serverStateData = event.serverState;
 
@@ -912,7 +1102,6 @@ export function useCogsStateFn<TStateObject extends unknown>(
             const newOptions = { serverState: serverStateData };
             setAndMergeOptions(thisKey, newOptions);
 
-            // Check for a merge request.
             const mergeConfig =
               typeof serverStateData.merge === 'object'
                 ? serverStateData.merge
@@ -920,20 +1109,17 @@ export function useCogsStateFn<TStateObject extends unknown>(
                   ? { strategy: 'append' }
                   : null;
 
-            // Get the current array and the new data.
             const currentState = getGlobalStore
               .getState()
               .getShadowValue(thisKey);
             const incomingData = serverStateData.data;
 
-            // *** THE REAL FIX: PERFORM INCREMENTAL INSERTS ***
             if (
               mergeConfig &&
               Array.isArray(currentState) &&
               Array.isArray(incomingData)
             ) {
               const keyField = mergeConfig.key || 'id';
-
               const existingIds = new Set(
                 currentState.map((item: any) => item[keyField])
               );
@@ -941,21 +1127,72 @@ export function useCogsStateFn<TStateObject extends unknown>(
               const newUniqueItems = incomingData.filter((item: any) => {
                 return !existingIds.has(item[keyField]);
               });
-              console.log('newUniqueItems', newUniqueItems);
+
               if (newUniqueItems.length > 0) {
                 newUniqueItems.forEach((item) => {
                   getGlobalStore
                     .getState()
                     .insertShadowArrayElement(thisKey, [], item);
+
+                  // MARK NEW SERVER ITEMS AS SYNCED
+                  const arrayMeta = getGlobalStore
+                    .getState()
+                    .getShadowMetadata(thisKey, []);
+
+                  if (arrayMeta?.arrayKeys) {
+                    const newItemKey =
+                      arrayMeta.arrayKeys[arrayMeta.arrayKeys.length - 1];
+                    if (newItemKey) {
+                      const newItemPath = newItemKey.split('.').slice(1);
+
+                      // Mark the new server item as synced, not dirty
+                      getGlobalStore
+                        .getState()
+                        .setShadowMetadata(thisKey, newItemPath, {
+                          isDirty: false,
+                          stateSource: 'server',
+                          lastServerSync:
+                            serverStateData.timestamp || Date.now(),
+                        });
+
+                      // Also mark all its child fields as synced if it's an object
+                      const itemValue = getGlobalStore
+                        .getState()
+                        .getShadowValue(newItemKey);
+                      if (
+                        itemValue &&
+                        typeof itemValue === 'object' &&
+                        !Array.isArray(itemValue)
+                      ) {
+                        Object.keys(itemValue).forEach((fieldKey) => {
+                          const fieldPath = [...newItemPath, fieldKey];
+                          getGlobalStore
+                            .getState()
+                            .setShadowMetadata(thisKey, fieldPath, {
+                              isDirty: false,
+                              stateSource: 'server',
+                              lastServerSync:
+                                serverStateData.timestamp || Date.now(),
+                            });
+                        });
+                      }
+                    }
+                  }
                 });
-              } else {
-                // No new items, no need to do anything.
-                return;
               }
             } else {
+              // For replace strategy or initial load
               getGlobalStore
                 .getState()
                 .initializeShadowState(thisKey, incomingData);
+
+              // Mark the entire state tree as synced from server
+              markEntireStateAsServerSynced(
+                thisKey,
+                [],
+                incomingData,
+                serverStateData.timestamp
+              );
             }
 
             const meta = getGlobalStore
@@ -1012,7 +1249,6 @@ export function useCogsStateFn<TStateObject extends unknown>(
   useLayoutEffect(() => {
     if (noStateKey) {
       setAndMergeOptions(thisKey as string, {
-        serverSync,
         formElements,
         defaultState,
         localStorage,
@@ -1043,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);
@@ -1079,11 +1313,12 @@ export function useCogsStateFn<TStateObject extends unknown>(
       }
     };
   }, []);
+
+  const syncApiRef = useRef<SyncApi | null>(null);
   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)) {
@@ -1122,24 +1357,38 @@ export function useCogsStateFn<TStateObject extends unknown>(
         store.insertShadowArrayElement(thisKey, path, newUpdate.newValue);
         // The array at `path` has been modified. Mark it AND all its parents as dirty.
         store.markAsDirty(thisKey, path, { bubble: true });
+
+        // ALSO mark the newly inserted item itself as dirty
+        // Get the new item's path and mark it as dirty
+        const arrayMeta = store.getShadowMetadata(thisKey, path);
+        if (arrayMeta?.arrayKeys) {
+          const newItemKey =
+            arrayMeta.arrayKeys[arrayMeta.arrayKeys.length - 1];
+          if (newItemKey) {
+            const newItemPath = newItemKey.split('.').slice(1); // Remove stateKey
+            store.markAsDirty(thisKey, newItemPath, { bubble: false });
+          }
+        }
         break;
       }
       case 'cut': {
-        // The item is at `path`, so the parent array is at `path.slice(0, -1)`
         const parentArrayPath = path.slice(0, -1);
+
         store.removeShadowArrayElement(thisKey, path);
-        // The parent array has been modified. Mark it AND all its parents as dirty.
         store.markAsDirty(thisKey, parentArrayPath, { bubble: true });
         break;
       }
       case 'update': {
         store.updateShadowAtPath(thisKey, path, newUpdate.newValue);
-        // The item at `path` was updated. Mark it AND all its parents as dirty.
         store.markAsDirty(thisKey, path, { bubble: true });
         break;
       }
     }
+    const shouldSync = updateObj.sync !== false;
 
+    if (shouldSync && syncApiRef.current && syncApiRef.current.connected) {
+      syncApiRef.current.updateState({ operation: newUpdate });
+    }
     // Handle signals - reuse shadowMeta from the beginning
     if (shadowMeta?.signals && shadowMeta.signals.length > 0) {
       // Use updatedShadowValue if we need the new value, otherwise use payload
@@ -1305,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;
     }
@@ -1365,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'];
-
-            // Check if the component has reactivity enabled
-            if (!reactiveTypes.includes('none')) {
-              component.forceUpdate();
-              notifiedComponents.add(componentId);
+      // --- 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'];
+
+              // 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
@@ -1581,6 +1800,11 @@ export function useCogsStateFn<TStateObject extends unknown>(
     );
   }, [thisKey, sessionId]);
 
+  const cogsSyncFn = latestInitialOptionsRef.current?.cogsSync;
+  if (cogsSyncFn) {
+    syncApiRef.current = cogsSyncFn(updaterFinal);
+  }
+
   return updaterFinal;
 }
 
@@ -1661,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
@@ -1676,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[],
@@ -1896,21 +2110,56 @@ function createProxyHandler<T>(
             }
           };
         }
+        // Fixed getStatus function in createProxyHandler
         if (prop === '_status' || prop === 'getStatus') {
           const getStatusFunc = () => {
             const shadowMeta = getGlobalStore
               .getState()
-              .getShadowMetadata(stateKey, []);
+              .getShadowMetadata(stateKey, path);
+            const value = getGlobalStore
+              .getState()
+              .getShadowValue(stateKeyPathKey);
 
-            if (shadowMeta?.stateSource === 'server' && !shadowMeta.isDirty) {
-              return 'synced';
-            } else if (shadowMeta?.isDirty) {
+            // Priority 1: Explicitly dirty items
+            if (shadowMeta?.isDirty === true) {
               return 'dirty';
-            } else if (shadowMeta?.stateSource === 'localStorage') {
+            }
+
+            // Priority 2: Explicitly synced items (isDirty: false)
+            if (shadowMeta?.isDirty === false) {
+              return 'synced';
+            }
+
+            // Priority 3: Items from server source (should be synced even without explicit isDirty flag)
+            if (shadowMeta?.stateSource === 'server') {
+              return 'synced';
+            }
+
+            // Priority 4: Items restored from localStorage
+            if (shadowMeta?.stateSource === 'localStorage') {
               return 'restored';
-            } else if (shadowMeta?.stateSource === 'default') {
+            }
+
+            // Priority 5: Items from default/initial state
+            if (shadowMeta?.stateSource === 'default') {
+              return 'fresh';
+            }
+
+            // Priority 6: Check if this is part of initial server load
+            // Look up the tree to see if parent has server source
+            const rootMeta = getGlobalStore
+              .getState()
+              .getShadowMetadata(stateKey, []);
+            if (rootMeta?.stateSource === 'server' && !shadowMeta?.isDirty) {
+              return 'synced';
+            }
+
+            // Priority 7: If no metadata exists but value exists, it's probably fresh
+            if (value !== undefined && !shadowMeta) {
               return 'fresh';
             }
+
+            // Fallback
             return 'unknown';
           };
 
@@ -1930,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)) {
@@ -2457,6 +2709,49 @@ function createProxyHandler<T>(
                 },
                 rebuildStateShape,
               });
+          } // In createProxyHandler -> handler -> get -> if (Array.isArray(currentState))
+
+          if (prop === 'stateFind') {
+            return (
+              callbackfn: (value: any, index: number) => boolean
+            ): StateObject<any> | undefined => {
+              // 1. Use the correct set of keys: filtered/sorted from meta, or all keys from the store.
+              const arrayKeys =
+                meta?.validIds ??
+                getGlobalStore.getState().getShadowMetadata(stateKey, path)
+                  ?.arrayKeys;
+
+              if (!arrayKeys) {
+                return undefined;
+              }
+
+              // 2. Iterate through the keys, get the value for each, and run the callback.
+              for (let i = 0; i < arrayKeys.length; i++) {
+                const itemKey = arrayKeys[i];
+                if (!itemKey) continue; // Safety check
+
+                const itemValue = getGlobalStore
+                  .getState()
+                  .getShadowValue(itemKey);
+
+                // 3. If the callback returns true, we've found our item.
+                if (callbackfn(itemValue, i)) {
+                  // Get the item's path relative to the stateKey (e.g., ['messages', '42'] -> ['42'])
+                  const itemPath = itemKey.split('.').slice(1);
+
+                  // 4. Rebuild a new, fully functional StateObject for just that item and return it.
+                  return rebuildStateShape({
+                    currentState: itemValue,
+                    path: itemPath,
+                    componentId: componentId,
+                    meta, // Pass along meta for potential further chaining
+                  });
+                }
+              }
+
+              // 5. If the loop finishes without finding anything, return undefined.
+              return undefined;
+            };
           }
           if (prop === 'stateFilter') {
             return (callbackfn: (value: any, index: number) => boolean) => {
@@ -2691,13 +2986,13 @@ function createProxyHandler<T>(
                     arrayValues: freshValues || [],
                   };
                 }, [cacheKey, updateTrigger]);
-
+                console.log('freshValues', validIds, arrayValues);
                 useEffect(() => {
                   const unsubscribe = getGlobalStore
                     .getState()
                     .subscribeToPath(stateKeyPathKey, (e) => {
                       // A data change has occurred for the source array.
-                      console.log('statelsit subscribed to path', e);
+
                       if (e.type === 'GET_SELECTED') {
                         return;
                       }
@@ -2716,7 +3011,12 @@ function createProxyHandler<T>(
                           }
                         }
                       }
-                      if (e.type === 'INSERT') {
+
+                      if (
+                        e.type === 'INSERT' ||
+                        e.type === 'REMOVE' ||
+                        e.type === 'CLEAR_SELECTION'
+                      ) {
                         forceUpdate({});
                       }
                     });
@@ -2741,7 +3041,7 @@ function createProxyHandler<T>(
                     validIds: validIds,
                   },
                 });
-
+                console.log('sssssssssssssssssssssssssssss', arraySetter);
                 return (
                   <>
                     {arrayValues.map((item, localIndex) => {
@@ -2918,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
@@ -2936,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',
               });
@@ -3068,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({
@@ -3177,13 +3484,93 @@ function createProxyHandler<T>(
             };
           }
           if (prop === 'applyJsonPatch') {
-            return (patches: any[]) => {
-              const currentState = getGlobalStore
-                .getState()
-                .getShadowValue(stateKeyPathKey, meta?.validIds);
-              const newState = applyPatch(currentState, patches).newDocument;
+            return (patches: Operation[]) => {
+              const store = getGlobalStore.getState();
+              const rootMeta = store.getShadowMetadata(stateKey, []);
+              if (!rootMeta?.components) return;
+
+              const convertPath = (jsonPath: string): string[] => {
+                if (!jsonPath || jsonPath === '/') return [];
+                return jsonPath
+                  .split('/')
+                  .slice(1)
+                  .map((p) => p.replace(/~1/g, '/').replace(/~0/g, '~'));
+              };
 
-              notifyComponents(stateKey);
+              const notifiedComponents = new Set<string>();
+
+              for (const patch of patches) {
+                const relativePath = convertPath(patch.path);
+
+                switch (patch.op) {
+                  case 'add':
+                  case 'replace': {
+                    const { value } = patch as {
+                      op: 'add' | 'replace';
+                      path: string;
+                      value: any;
+                    };
+                    store.updateShadowAtPath(stateKey, relativePath, value);
+                    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': {
+                    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;
+                  }
+                }
+              }
             };
           }
           if (prop === 'validateZodSchema') {
@@ -3191,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;
               }
@@ -3247,9 +3654,38 @@ function createProxyHandler<T>(
         if (prop === '_path') return path;
         if (prop === 'update') {
           return (payload: UpdateArg<T>) => {
+            // Step 1: This is the same. It performs the data update.
             effectiveSetState(payload as any, path, { updateType: 'update' });
+
+            return {
+              /**
+               * Marks this specific item, which was just updated, as 'synced' (not dirty).
+               */
+              synced: () => {
+                // This function "remembers" the path of the item that was just updated.
+                const shadowMeta = getGlobalStore
+                  .getState()
+                  .getShadowMetadata(stateKey, path);
+
+                // It updates ONLY the metadata for that specific item.
+                getGlobalStore.getState().setShadowMetadata(stateKey, path, {
+                  ...shadowMeta,
+                  isDirty: false, // EXPLICITLY set to false, not just undefined
+                  stateSource: 'server', // Mark as coming from server
+                  lastServerSync: Date.now(), // Add timestamp
+                });
+
+                // Force a re-render for components watching this path
+                const fullPath = [stateKey, ...path].join('.');
+                getGlobalStore.getState().notifyPathSubscribers(fullPath, {
+                  type: 'SYNC_STATUS_CHANGE',
+                  isDirty: false,
+                });
+              },
+            };
           };
         }
+
         if (prop === 'toggle') {
           const currentValueAtPath = getGlobalStore
             .getState()
@@ -3268,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}
+              />
             );
           };
         }
@@ -3782,6 +4212,7 @@ function ListItemWrapper({
   const hasReportedInitialHeight = useRef(false);
   const fullKey = [stateKey, ...itemPath].join('.');
   useRegisterComponent(stateKey, itemComponentId, forceUpdate);
+
   const setRefs = useCallback(
     (element: HTMLDivElement | null) => {
       elementRef.current = element;
@@ -3839,6 +4270,7 @@ function ListItemWrapper({
 
   return <div ref={setRefs}>{children}</div>;
 }
+
 function FormElementWrapper({
   stateKey,
   path,
@@ -3884,7 +4316,9 @@ function FormElementWrapper({
     const unsubscribe = getGlobalStore
       .getState()
       .subscribeToPath(stateKeyPathKey, (newValue) => {
-        forceUpdate({});
+        if (!isCurrentlyDebouncing.current && localValue !== newValue) {
+          forceUpdate({});
+        }
       });
     return () => {
       unsubscribe();
@@ -3897,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;
 
@@ -3908,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,
@@ -3936,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('.')),
@@ -3947,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,
@@ -3958,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
 }