cogsbox-state 0.5.471 → 0.5.473

package/src/CogsState.tsx

@@ -1,5 +1,6 @@
 'use client';
-
+import { pluginStore } from './pluginStore';
+import { FormWrapperParams, type CogsPlugin } from './plugins';
 import {
   createElement,
   startTransition,
@@ -15,10 +16,11 @@ import {
 } from 'react';
 
 import {
-  getDifferences,
-  isArray,
+  transformStateFunc,
   isFunction,
   type GenericObject,
+  isArray,
+  getDifferences,
 } from './utility.js';
 import {
   FormElementWrapper,
@@ -26,13 +28,13 @@ import {
   MemoizedCogsItemWrapper,
   ValidationWrapper,
 } from './Components.js';
-import { isDeepEqual, transformStateFunc } from './utility.js';
+import { isDeepEqual } from './utility.js';
 import superjson from 'superjson';
 import { v4 as uuidv4 } from 'uuid';
 
 import {
-  formRefStore,
   getGlobalStore,
+  updateShadowTypeInfo,
   ValidationError,
   ValidationSeverity,
   ValidationStatus,
@@ -44,7 +46,9 @@ import { Operation } from 'fast-json-patch';
 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;
+import { runValidation } from './validation';
+
+export type Prettify<T> = T extends any ? { [K in keyof T]: T[K] } : never;
 
 export type VirtualViewOptions = {
   itemHeight?: number;
@@ -80,7 +84,11 @@ export type FormElementParams<T> = StateObject<T> & {
         HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement
       >
     ) => void;
-    onBlur?: () => void;
+    onBlur?: (
+      event: React.FocusEvent<
+        HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement
+      >
+    ) => void;
   };
 };
 
@@ -97,37 +105,7 @@ type CutFunctionType<T> = (
 ) => StateObject<T>;
 
 export type InferArrayElement<T> = T extends (infer U)[] ? U : never;
-type ArraySpecificPrototypeKeys =
-  | 'concat'
-  | 'copyWithin'
-  | 'fill'
-  | 'find'
-  | 'findIndex'
-  | 'flat'
-  | 'flatMap'
-  | 'includes'
-  | 'indexOf'
-  | 'join'
-  | 'keys'
-  | 'lastIndexOf'
-  | 'map'
-  | 'pop'
-  | 'push'
-  | 'reduce'
-  | 'reduceRight'
-  | 'reverse'
-  | 'shift'
-  | 'slice'
-  | 'some'
-  | 'sort'
-  | 'splice'
-  | 'unshift'
-  | 'values'
-  | 'entries'
-  | 'every'
-  | 'filter'
-  | 'forEach'
-  | 'with';
+
 export type StreamOptions<T, R = T> = {
   bufferSize?: number;
   flushInterval?: number;
@@ -158,6 +136,7 @@ export type ArrayEndType<TShape extends unknown> = {
     $_index: number;
   } & EndType<Prettify<InferArrayElement<TShape>>>;
   $insert: InsertType<Prettify<InferArrayElement<TShape>>>;
+  $insertMany: (payload: InferArrayElement<TShape>[]) => void;
   $cut: CutFunctionType<TShape>;
   $cutSelected: () => void;
   $cutByValue: (value: string | number | boolean) => void;
@@ -243,8 +222,20 @@ export type InsertTypeObj<T> = (payload: InsertParams<T>) => void;
 
 type EffectFunction<T, R> = (state: T, deps: any[]) => R;
 export type EndType<T, IsArrayElement = false> = {
-  $addZodValidation: (errors: ValidationError[]) => void;
+  $getPluginMetaData: (pluginName: string) => Record<string, any>;
+  $addPluginMetaData: (key: string, data: Record<string, any>) => void;
+  $removePluginMetaData: (key: string) => void;
+  $setOptions: (options: OptionsType<T>) => void;
+
+  $addZodValidation: (
+    errors: ValidationError[],
+    source?: 'client' | 'sync_engine' | 'api'
+  ) => void;
   $clearZodValidation: (paths?: string[]) => void;
+  $applyOperation: (
+    operation: UpdateTypeDetail,
+    metaData?: Record<string, any>
+  ) => void;
   $applyJsonPatch: (patches: any[]) => void;
   $update: UpdateType<T>;
   $_path: string[];
@@ -265,7 +256,14 @@ export type EndType<T, IsArrayElement = false> = {
   $isSelected: boolean;
   $setSelected: (value: boolean) => void;
   $toggleSelected: () => void;
-  $getFormRef: () => React.RefObject<any> | undefined;
+  $formInput: {
+    setDisabled: (isDisabled: boolean) => void;
+    focus: () => void;
+    blur: () => void;
+    scrollIntoView: (options?: ScrollIntoViewOptions) => void;
+    click: () => void;
+    selectText: () => void;
+  };
   $removeStorage: () => void;
   $sync: () => void;
   $validationWrapper: ({
@@ -287,7 +285,7 @@ export type StateObject<T> = (T extends any[]
       : never) &
   EndType<T, true> & {
     $toggle: T extends boolean ? () => void : never;
-    $getAllFormRefs: () => Map<string, React.RefObject<any>>;
+
     $_componentId: string | null;
     $getComponents: () => ComponentsType;
 
@@ -295,6 +293,7 @@ export type StateObject<T> = (T extends any[]
     $updateInitialState: (newState: T | null) => {
       fetchId: (field: keyof T) => string | number;
     };
+    $initializeAndMergeShadowState: (newState: any | null) => void;
     $_isLoading: boolean;
     $_serverState: T;
     $revertToInitialState: (obj?: { validationKey?: string }) => T;
@@ -321,10 +320,13 @@ type EffectiveSetStateArg<
     ? InsertParams<InferArrayElement<T>>
     : never
   : UpdateArg<T>;
-type UpdateOptions = {
-  updateType: 'insert' | 'cut' | 'update';
 
-  sync?: boolean;
+type UpdateOptions = {
+  updateType: 'insert' | 'cut' | 'update' | 'insert_many';
+  validationTrigger?: 'onBlur' | 'onChange' | 'programmatic';
+  itemId?: string;
+  index?: number;
+  metaData?: Record<string, any>;
 };
 type EffectiveSetState<TStateObject> = (
   newStateOrFunction:
@@ -332,21 +334,24 @@ type EffectiveSetState<TStateObject> = (
     | EffectiveSetStateArg<TStateObject, 'insert'>
     | null,
   path: string[],
-  updateObj: UpdateOptions,
+  updateObj: UpdateOptions, // Now includes itemId
   validationKey?: string
 ) => void;
 
 export type UpdateTypeDetail = {
   timeStamp: number;
   stateKey: string;
-  updateType: 'update' | 'insert' | 'cut';
+  updateType: 'update' | 'insert' | 'cut' | 'insert_many';
   path: string[];
   status: 'new' | 'sent' | 'synced';
   oldValue: any;
   newValue: any;
   userId?: number;
-};
 
+  itemId?: string;
+  insertAfterId?: string;
+  metaData?: Record<string, any>;
+};
 export type ReactivityUnion = 'none' | 'component' | 'deps' | 'all';
 export type ReactivityType =
   | 'none'
@@ -356,20 +361,16 @@ export type ReactivityType =
   | 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;
   zodSchemaV3?: z3.ZodType<any, any, any>;
   zodSchemaV4?: z4.ZodType<any, any, any>;
-
-  onBlur?: boolean;
+  onBlur?: 'error' | 'warning';
+  onChange?: 'error' | 'warning';
+  blockSync?: boolean;
 };
-type UseSyncType<T> = (state: T, a: SyncOptionsType<any>) => SyncApi;
+
 type SyncOptionsType<TApiParams> = {
   apiParams: TApiParams;
   stateKey?: string;
@@ -380,12 +381,23 @@ type SyncOptionsType<TApiParams> = {
   connect?: boolean;
   inMemoryState?: boolean;
 };
-export type OptionsType<T extends unknown = unknown, TApiParams = never> = {
+
+export type CreateStateOptionsType<
+  T extends unknown = unknown,
+  TPlugins extends readonly CogsPlugin<any, any, any, any, any>[] = [],
+> = {
+  formElements?: FormsElementsType<T, TPlugins>;
+  validation?: ValidationOptionsType;
+  plugins?: TPlugins;
+};
+export type OptionsType<
+  T extends unknown = unknown,
+  TApiParams = never,
+> = CreateStateOptionsType & {
   log?: boolean;
   componentId?: string;
   syncOptions?: SyncOptionsType<TApiParams>;
 
-  validation?: ValidationOptionsType;
   serverState?: {
     id?: string | number;
     data?: T;
@@ -414,12 +426,10 @@ export type OptionsType<T extends unknown = unknown, TApiParams = never> = {
   };
   middleware?: ({ update }: { update: UpdateTypeDetail }) => void;
 
-  modifyState?: (state: T) => T;
   localStorage?: {
     key: string | ((state: T) => string);
     onChange?: (state: T) => void;
   };
-  formElements?: FormsElementsType<T>;
 
   reactiveDeps?: (state: T) => any[] | true;
   reactiveType?: ReactivityType;
@@ -430,14 +440,11 @@ export type OptionsType<T extends unknown = unknown, TApiParams = never> = {
   dependencies?: any[];
 };
 
-export type SyncRenderOptions<T extends unknown = unknown> = {
-  children: React.ReactNode;
-  time: number;
-  data?: T;
-  key?: string;
-};
-
-type FormsElementsType<T> = {
+export type FormsElementsType<
+  TState,
+  TPlugins extends readonly CogsPlugin<any, any, any, any, any>[] = [],
+> = {
+  // These optional, built-in wrappers are unchanged.
   validation?: (options: {
     children: React.ReactNode;
     status: ValidationStatus;
@@ -445,28 +452,32 @@ type FormsElementsType<T> = {
     hasErrors: boolean;
     hasWarnings: boolean;
     allErrors: ValidationError[];
-
     path: string[];
     message?: string;
-    getData?: () => T;
+    getData?: () => TState;
   }) => React.ReactNode;
-  syncRender?: (options: SyncRenderOptions<T>) => React.ReactNode;
-};
-
-export type InitialStateInnerType<T extends unknown = unknown> = {
-  initialState: T;
-} & OptionsType<T>;
-
-export type InitialStateType<T> = {
-  [key: string]: InitialStateInnerType<T>;
-};
-
-export type AllStateTypes<T extends unknown> = Record<string, T>;
-
-export type CogsInitialState<T> = {
-  initialState: T;
-  formElements?: FormsElementsType<T>;
+  syncRender?: (options: {
+    children: React.ReactNode;
+    time: number;
+    data?: TState;
+    key?: string;
+  }) => React.ReactNode;
+} & {
+  // For each plugin `P` in the TPlugins array...
+  [P in TPlugins[number] as P['name']]?: P['formWrapper'] extends (
+    // ...check if its `formWrapper` property is a function...
+    arg: any
+  ) => any
+    ? // ...if it is, infer the type of its FIRST PARAMETER. This is the key.
+      Parameters<P['formWrapper']>[0]
+    : // Otherwise, the type is invalid.
+      never;
 };
+export type CogsInitialState<T> =
+  | {
+      initialState: T;
+    }
+  | CreateStateOptionsType<T>;
 
 export type TransformedStateType<T> = {
   [P in keyof T]: T[P] extends CogsInitialState<infer U> ? U : T[P];
@@ -479,6 +490,7 @@ const {
   setShadowMetadata,
   getShadowValue,
   initializeShadowState,
+  initializeAndMergeShadowState,
   updateShadowAtPath,
   insertShadowArrayElement,
   insertManyShadowArrayElements,
@@ -493,8 +505,14 @@ const {
   clearSelectedIndex,
   getSyncInfo,
   notifyPathSubscribers,
+  getPluginMetaDataMap,
+  setPluginMetaData,
+  removePluginMetaData,
   // Note: The old functions are no longer imported under their original names
 } = getGlobalStore.getState();
+
+const { notifyUpdate } = pluginStore.getState();
+
 function getArrayData(stateKey: string, path: string[], meta?: MetaData) {
   const shadowMeta = getShadowMetadata(stateKey, path);
   const isArray = !!shadowMeta?.arrayKeys;
@@ -537,11 +555,23 @@ function findArrayItem(
 function setAndMergeOptions(stateKey: string, newOptions: OptionsType<any>) {
   const initialOptions = getInitialOptions(stateKey as string) || {};
 
-  setInitialStateOptions(stateKey as string, {
+  const mergedOptions = {
     ...initialOptions,
     ...newOptions,
-  });
+  };
+
+  // FIX: Apply the same default onBlur logic here too
+  if (
+    (mergedOptions.validation?.zodSchemaV4 ||
+      mergedOptions.validation?.zodSchemaV3) &&
+    !mergedOptions.validation?.onBlur
+  ) {
+    mergedOptions.validation.onBlur = 'error';
+  }
+
+  setInitialStateOptions(stateKey as string, mergedOptions);
 }
+
 function setOptions<StateKey, Opt>({
   stateKey,
   options,
@@ -554,92 +584,134 @@ function setOptions<StateKey, Opt>({
   const initialOptions = getInitialOptions(stateKey as string) || {};
   const initialOptionsPartState = initialOptionsPart[stateKey as string] || {};
 
-  const mergedOptions = { ...initialOptionsPartState, ...initialOptions };
-
+  let mergedOptions = { ...initialOptionsPartState, ...initialOptions };
   let needToAdd = false;
+
   if (options) {
-    for (const key in options) {
-      if (!mergedOptions.hasOwnProperty(key)) {
-        needToAdd = true;
-        mergedOptions[key] = options[key as keyof typeof options];
-      } else {
-        if (
-          key == 'localStorage' &&
-          options[key] &&
-          mergedOptions[key].key !== options[key]?.key
-        ) {
-          needToAdd = true;
-          mergedOptions[key] = options[key];
-        }
-        if (
-          key == 'defaultState' &&
-          options[key] &&
-          mergedOptions[key] !== options[key] &&
-          !isDeepEqual(mergedOptions[key], options[key])
-        ) {
-          needToAdd = true;
-          mergedOptions[key] = options[key];
+    const deepMerge = (target: any, source: any) => {
+      for (const key in source) {
+        if (source.hasOwnProperty(key)) {
+          if (
+            source[key] instanceof Object &&
+            !Array.isArray(source[key]) &&
+            target[key] instanceof Object
+          ) {
+            if (!isDeepEqual(target[key], source[key])) {
+              deepMerge(target[key], source[key]);
+              needToAdd = true;
+            }
+          } else {
+            if (target[key] !== source[key]) {
+              target[key] = source[key];
+              needToAdd = true;
+            }
+          }
         }
       }
-    }
+      return target;
+    };
+
+    mergedOptions = deepMerge(mergedOptions, options);
   }
 
-  // Always preserve syncOptions if it exists in mergedOptions but not in options
-  if (
-    mergedOptions.syncOptions &&
-    (!options || !options.hasOwnProperty('syncOptions'))
-  ) {
-    needToAdd = true;
+  // Set default onBlur
+  if (mergedOptions.validation) {
+    const onBlurProvided =
+      options?.validation?.hasOwnProperty('onBlur') ||
+      initialOptions?.validation?.hasOwnProperty('onBlur') ||
+      initialOptionsPartState?.validation?.hasOwnProperty('onBlur');
+
+    if (!onBlurProvided) {
+      mergedOptions.validation.onBlur = 'error';
+      needToAdd = true;
+    }
   }
 
   if (needToAdd) {
     setInitialStateOptions(stateKey as string, mergedOptions);
+
+    // NEW: Update type info if validation schema was added
+    const hadSchema =
+      initialOptions?.validation?.zodSchemaV4 ||
+      initialOptions?.validation?.zodSchemaV3;
+    const hasNewSchemaV4 =
+      mergedOptions.validation?.zodSchemaV4 &&
+      !initialOptions?.validation?.zodSchemaV4;
+    const hasNewSchemaV3 =
+      mergedOptions.validation?.zodSchemaV3 &&
+      !initialOptions?.validation?.zodSchemaV3;
+
+    if (!hadSchema && (hasNewSchemaV4 || hasNewSchemaV3)) {
+      if (hasNewSchemaV4) {
+        updateShadowTypeInfo(
+          stateKey as string,
+          mergedOptions.validation.zodSchemaV4,
+          'zod4'
+        );
+      } else if (hasNewSchemaV3) {
+        updateShadowTypeInfo(
+          stateKey as string,
+          mergedOptions.validation.zodSchemaV3,
+          'zod3'
+        );
+      }
+
+      // Notify components to re-render with updated validation
+      notifyComponents(stateKey as string);
+    }
   }
-}
 
-export function addStateOptions<T extends unknown>(
+  return mergedOptions;
+}
+export function addStateOptions<T>(
   initialState: T,
-  { formElements, validation }: OptionsType<T>
+  options: CreateStateOptionsType<T>
 ) {
-  return { initialState: initialState, formElements, validation } as T;
+  return {
+    ...options,
+    initialState,
+    _addStateOptions: true,
+  };
 }
+export type PluginData = {
+  plugin: CogsPlugin<any, any, any, any, any>;
+  options: any;
+  hookData?: any;
+};
 
-// 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;
+////////////////////////////////
 
-export const createCogsState = <State extends Record<StateKeys, unknown>>(
+export const createCogsState = <
+  State extends Record<string, unknown>,
+  const TPlugins extends readonly CogsPlugin<string, any, any, any, any>[] = [],
+>(
   initialState: State,
   opt?: {
-    formElements?: FormsElementsType<State>;
+    plugins?: TPlugins;
+    formElements?: FormsElementsType<State, TPlugins>;
     validation?: ValidationOptionsType;
-    __fromSyncSchema?: boolean;
-    __syncNotifications?: Record<string, Function>;
-    __apiParamsMap?: Record<string, any>;
-    __useSync?: UseSyncType<State>;
-    __syncSchemas?: Record<string, any>;
   }
 ) => {
-  let newInitialState = initialState;
-  const [statePart, initialOptionsPart] =
-    transformStateFunc<State>(newInitialState);
+  type PluginOptions = {
+    [K in TPlugins[number] as K['name']]?: K extends CogsPlugin<
+      string,
+      infer O,
+      any,
+      any,
+      any
+    >
+      ? O
+      : never;
+  };
 
-  if (opt?.__fromSyncSchema && opt?.__syncNotifications) {
-    getGlobalStore
-      .getState()
-      .setInitialStateOptions('__notifications', opt.__syncNotifications);
+  if (opt?.plugins) {
+    pluginStore.getState().setRegisteredPlugins(opt.plugins as any);
   }
 
-  if (opt?.__fromSyncSchema && opt?.__apiParamsMap) {
-    getGlobalStore
-      .getState()
-      .setInitialStateOptions('__apiParamsMap', opt.__apiParamsMap);
-  }
+  const [statePart, initialOptionsPart] =
+    transformStateFunc<State>(initialState);
 
+  // FIX: Store options INCLUDING validation for each state key
   Object.keys(statePart).forEach((key) => {
     let existingOptions = initialOptionsPart[key] || {};
 
@@ -654,61 +726,77 @@ export const createCogsState = <State extends Record<StateKeys, unknown>>(
       };
     }
 
-    if (opt?.validation) {
-      mergedOptions.validation = {
-        ...opt.validation,
-        ...(existingOptions.validation || {}),
-      };
+    mergedOptions.validation = {
+      onBlur: 'error',
+      ...opt?.validation,
+      ...(existingOptions.validation || {}),
+    };
 
-      if (opt.validation.key && !existingOptions.validation?.key) {
-        mergedOptions.validation.key = `${opt.validation.key}.${key}`;
-      }
-    }
-    if (opt?.__syncSchemas?.[key]?.schemas?.validation) {
-      mergedOptions.validation = {
-        zodSchemaV4: opt.__syncSchemas[key].schemas.validation,
-        ...existingOptions.validation,
-      };
+    if (opt?.validation?.key && !existingOptions.validation?.key) {
+      mergedOptions.validation.key = `${opt.validation.key}.${key}`;
     }
-    if (Object.keys(mergedOptions).length > 0) {
-      const existingGlobalOptions = getInitialOptions(key);
 
-      if (!existingGlobalOptions) {
-        setInitialStateOptions(key, mergedOptions);
-      } else {
-        // Merge with existing global options
-        setInitialStateOptions(key, {
+    const existingGlobalOptions = getInitialOptions(key);
+
+    const finalOptions = existingGlobalOptions
+      ? {
           ...existingGlobalOptions,
           ...mergedOptions,
-        });
-      }
-    }
+          formElements: {
+            ...existingGlobalOptions.formElements,
+            ...mergedOptions.formElements,
+          },
+          validation: {
+            ...existingGlobalOptions.validation,
+            ...mergedOptions.validation,
+          },
+        }
+      : mergedOptions;
+
+    setInitialStateOptions(key, finalOptions);
   });
 
   Object.keys(statePart).forEach((key) => {
     initializeShadowState(key, statePart[key]);
   });
-
+  type Prettify<T> = {
+    [K in keyof T]: T[K];
+  } & {};
   type StateKeys = keyof typeof statePart;
 
   const useCogsState = <StateKey extends StateKeys>(
     stateKey: StateKey,
-    options?: Prettify<OptionsType<(typeof statePart)[StateKey]>>
+    options?: Prettify<
+      OptionsType<(typeof statePart)[StateKey], never> & {
+        [PName in keyof PluginOptions]?: PluginOptions[PName] extends infer P
+          ? P extends Record<string, any>
+            ? {
+                [K in keyof P]: P[K] extends { __key: 'keyed'; map: infer TMap }
+                  ? StateKey extends keyof TMap
+                    ? TMap[StateKey]
+                    : never
+                  : P[K];
+              }
+            : P
+          : never;
+      }
+    >
   ) => {
     const [componentId] = useState(options?.componentId ?? uuidv4());
 
-    setOptions({
+    const currentOptions = setOptions({
       stateKey,
       options,
       initialOptionsPart,
     });
+
+    const optionsRef = useRef(currentOptions);
+    optionsRef.current = currentOptions;
+
     const thiState =
       getShadowValue(stateKey as string, []) || statePart[stateKey as string];
-    const partialState = options?.modifyState
-      ? options.modifyState(thiState)
-      : thiState;
 
-    const updater = useCogsStateFn<(typeof statePart)[StateKey]>(partialState, {
+    const updater = useCogsStateFn<(typeof statePart)[StateKey]>(thiState, {
       stateKey: stateKey as string,
       syncUpdate: options?.syncUpdate,
       componentId,
@@ -719,14 +807,30 @@ export const createCogsState = <State extends Record<StateKeys, unknown>>(
       defaultState: options?.defaultState as any,
       dependencies: options?.dependencies,
       serverState: options?.serverState,
-      syncOptions: options?.syncOptions,
-      __useSync: opt?.__useSync as UseSyncType<(typeof statePart)[StateKey]>,
     });
 
+    useEffect(() => {
+      if (options) {
+        pluginStore
+          .getState()
+          .setPluginOptionsForState(stateKey as string, options);
+      }
+    }, [stateKey, options]);
+    useEffect(() => {
+      console.log('adding handler 1', stateKey, updater);
+      pluginStore
+        .getState()
+        .stateHandlers.set(stateKey as string, updater as any);
+
+      return () => {
+        pluginStore.getState().stateHandlers.delete(stateKey as string);
+      };
+    }, [stateKey, updater]);
+
     return updater;
   };
 
-  function setCogsOptions<StateKey extends StateKeys>(
+  function setCogsOptionsByKey<StateKey extends StateKeys>(
     stateKey: StateKey,
     options: OptionsType<(typeof statePart)[StateKey]>
   ) {
@@ -739,93 +843,53 @@ export const createCogsState = <State extends Record<StateKeys, unknown>>(
     notifyComponents(stateKey as string);
   }
 
-  return { useCogsState, setCogsOptions } as CogsApi<State, never>;
-};
-type UseCogsStateHook<
-  T extends Record<string, any>,
-  TApiParamsMap extends Record<string, any> = never,
-> = <StateKey extends keyof TransformedStateType<T> & string>(
-  stateKey: StateKey,
-  options?: [TApiParamsMap] extends [never]
-    ? // When TApiParamsMap is never (no sync)
-      Prettify<OptionsType<TransformedStateType<T>[StateKey]>>
-    : // When TApiParamsMap exists (sync enabled)
-      StateKey extends keyof TApiParamsMap
-      ? Prettify<
-          OptionsType<
-            TransformedStateType<T>[StateKey],
-            TApiParamsMap[StateKey]
-          > & {
-            syncOptions: Prettify<SyncOptionsType<TApiParamsMap[StateKey]>>;
-          }
-        >
-      : Prettify<OptionsType<TransformedStateType<T>[StateKey]>>
-) => StateObject<TransformedStateType<T>[StateKey]>;
-
-// Update CogsApi to default to never instead of Record<string, never>
-type CogsApi<
-  T extends Record<string, any>,
-  TApiParamsMap extends Record<string, any> = never,
-> = {
-  useCogsState: UseCogsStateHook<T, TApiParamsMap>;
-  setCogsOptions: SetCogsOptionsFunc<T>;
-};
-type GetParamType<SchemaEntry> = SchemaEntry extends {
-  api?: { queryData?: { _paramType?: infer P } };
-}
-  ? P
-  : never;
-
-export function createCogsStateFromSync<
-  TSyncSchema extends {
-    schemas: Record<
-      string,
-      {
-        schemas: { defaultValues: any };
-        api?: {
-          queryData?: any;
+  function setCogsFormElements(
+    formElements: FormsElementsType<State, TPlugins>
+  ) {
+    // Get the current list of registered plugins from the store.
+    const currentPlugins = pluginStore.getState().registeredPlugins;
+
+    // Create a new array by mapping over the current plugins.
+    // This is crucial for immutability and ensuring Zustand detects the change.
+    const updatedPlugins = currentPlugins.map((plugin) => {
+      // Check if the formElements object has a wrapper for this specific plugin by name.
+      if (formElements.hasOwnProperty(plugin.name)) {
+        // If it does, return a *new* plugin object.
+        // Spread the existing plugin properties and add/overwrite the formWrapper.
+        return {
+          ...plugin,
+          formWrapper: formElements[plugin.name as keyof typeof formElements],
         };
-        [key: string]: any;
       }
-    >;
-    notifications: Record<string, any>;
-  },
->(
-  syncSchema: TSyncSchema,
-  useSync: UseSyncType<any>
-): CogsApi<
-  {
-    [K in keyof TSyncSchema['schemas']]: TSyncSchema['schemas'][K]['schemas']['defaultValues'];
-  },
-  {
-    [K in keyof TSyncSchema['schemas']]: GetParamType<
-      TSyncSchema['schemas'][K]
-    >;
-  }
-> {
-  const schemas = syncSchema.schemas;
-  const initialState: any = {};
-  const apiParamsMap: any = {};
-
-  // Extract defaultValues AND apiParams from each entry
-  for (const key in schemas) {
-    const entry = schemas[key];
-    initialState[key] = entry?.schemas?.defaultValues || {};
-
-    // Extract apiParams from the api.queryData._paramType
-    if (entry?.api?.queryData?._paramType) {
-      apiParamsMap[key] = entry.api.queryData._paramType;
-    }
-  }
+      // If there's no new wrapper for this plugin, return the original object.
+      return plugin;
+    });
 
-  return createCogsState(initialState, {
-    __fromSyncSchema: true,
-    __syncNotifications: syncSchema.notifications,
-    __apiParamsMap: apiParamsMap,
-    __useSync: useSync,
-    __syncSchemas: schemas,
-  }) as any;
-}
+    // Use the store's dedicated setter function to update the registered plugins list.
+    // This will trigger a state update that components listening to the store will react to.
+    pluginStore.getState().setRegisteredPlugins(updatedPlugins as any);
+
+    // For good measure and consistency, we should still update the formElements
+    // in the initial options, in case any other part of the system relies on it.
+    const allStateKeys = Object.keys(statePart);
+    allStateKeys.forEach((key) => {
+      const existingOptions = getInitialOptions(key) || {};
+      const finalOptions = {
+        ...existingOptions,
+        formElements: {
+          ...(existingOptions.formElements || {}),
+          ...formElements,
+        },
+      };
+      setInitialStateOptions(key, finalOptions);
+    });
+  }
+  return {
+    useCogsState,
+    setCogsOptionsByKey,
+    setCogsFormElements,
+  };
+};
 
 const saveToLocalStorage = <T,>(
   state: T,
@@ -997,35 +1061,14 @@ let isFlushScheduled = false;
 function scheduleFlush() {
   if (!isFlushScheduled) {
     isFlushScheduled = true;
-    queueMicrotask(flushQueue);
+    console.log('Scheduling flush');
+    queueMicrotask(() => {
+      console.log('Actually flushing');
+      flushQueue();
+    });
   }
 }
-function handleUpdate(
-  stateKey: string,
-  path: string[],
-  payload: any
-): { type: 'update'; oldValue: any; newValue: any; shadowMeta: any } {
-  // ✅ FIX: Get the old value before the update.
-  const oldValue = getGlobalStore.getState().getShadowValue(stateKey, path);
-
-  const newValue = isFunction(payload) ? payload(oldValue) : payload;
-
-  // ✅ FIX: The new `updateShadowAtPath` handles metadata preservation automatically.
-  // The manual loop has been removed.
-  updateShadowAtPath(stateKey, path, newValue);
-
-  markAsDirty(stateKey, path, { bubble: true });
 
-  // Return the metadata of the node *after* the update.
-  const newShadowMeta = getShadowMetadata(stateKey, path);
-
-  return {
-    type: 'update',
-    oldValue: oldValue,
-    newValue,
-    shadowMeta: newShadowMeta,
-  };
-}
 // 2. Update signals
 function updateSignals(shadowMeta: any, displayValue: any) {
   if (!shadowMeta?.signals?.length) return;
@@ -1127,79 +1170,165 @@ function getComponentNotifications(
         }
       });
     }
-  } else if (result.type === 'insert' || result.type === 'cut') {
-    // For array structural changes (add/remove), notify components listening to the parent array.
+  } else if (
+    result.type === 'insert' ||
+    result.type === 'cut' ||
+    result.type === 'insert_many'
+  ) {
+    // This path is the array itself (e.g., ['pets'])
     const parentArrayPath = result.type === 'insert' ? path : path.slice(0, -1);
-    const parentMeta = getShadowMetadata(stateKey, parentArrayPath);
-
-    if (parentMeta?.pathComponents) {
-      parentMeta.pathComponents.forEach((componentId: string) => {
-        const component = rootMeta.components?.get(componentId);
-        // NEW: Add component to the set
-        if (component) {
-          componentsToNotify.add(component);
-        }
-      });
+
+    // --- FIX: ADD BUBBLE-UP LOGIC HERE ---
+    // Start from the array's path and go up to the root
+    let currentPath = [...parentArrayPath];
+    while (true) {
+      const pathMeta = getShadowMetadata(stateKey, currentPath);
+
+      if (pathMeta?.pathComponents) {
+        pathMeta.pathComponents.forEach((componentId: string) => {
+          const component = rootMeta.components?.get(componentId);
+          if (component) {
+            componentsToNotify.add(component);
+          }
+        });
+      }
+
+      if (currentPath.length === 0) break;
+      currentPath.pop(); // Go up one level
     }
+    // --- END FIX ---
   }
 
   // --- PASS 2: Handle 'all' and 'deps' reactivity types ---
   // Iterate over all components for this stateKey that haven't been notified yet.
-  rootMeta.components.forEach((component, componentId) => {
-    // If we've already added this component, skip it.
-    if (componentsToNotify.has(component)) {
-      return;
-    }
-
-    const reactiveTypes = Array.isArray(component.reactiveType)
-      ? component.reactiveType
-      : [component.reactiveType || 'component'];
-
-    if (reactiveTypes.includes('all')) {
-      componentsToNotify.add(component);
-    } else if (reactiveTypes.includes('deps') && component.depsFunction) {
-      const currentState = getShadowValue(stateKey, []);
-      const newDeps = component.depsFunction(currentState);
-
-      if (
-        newDeps === true ||
-        (Array.isArray(newDeps) && !isDeepEqual(component.prevDeps, newDeps))
-      ) {
-        component.prevDeps = newDeps as any; // Update the dependencies for the next check
-        componentsToNotify.add(component);
-      }
-    }
-  });
+  // rootMeta.components.forEach((component, componentId) => {
+  //   // If we've already added this component, skip it.
+  //   if (componentsToNotify.has(component)) {
+  //     return;
+  //   }
+
+  //   const reactiveTypes = Array.isArray(component.reactiveType)
+  //     ? component.reactiveType
+  //     : [component.reactiveType || 'component'];
+
+  //   if (reactiveTypes.includes('all')) {
+  //     componentsToNotify.add(component);
+  //   } else if (reactiveTypes.includes('deps') && component.depsFunction) {
+  //     const currentState = getShadowValue(stateKey, []);
+  //     const newDeps = component.depsFunction(currentState);
+
+  //     if (
+  //       newDeps === true ||
+  //       (Array.isArray(newDeps) && !isDeepEqual(component.prevDeps, newDeps))
+  //     ) {
+  //       component.prevDeps = newDeps as any; // Update the dependencies for the next check
+  //       componentsToNotify.add(component);
+  //     }
+  //   }
+  // });
 
   return componentsToNotify;
 }
 
-function handleInsert(
+function handleUpdate(
   stateKey: string,
   path: string[],
   payload: any
-): { type: 'insert'; newValue: any; shadowMeta: any } {
+): { type: 'update'; oldValue: any; newValue: any; shadowMeta: any } {
+  // ✅ FIX: Get the old value before the update.
+  const oldValue = getGlobalStore.getState().getShadowValue(stateKey, path);
+
+  const newValue = isFunction(payload) ? payload(oldValue) : payload;
+
+  // ✅ FIX: The new `updateShadowAtPath` handles metadata preservation automatically.
+  // The manual loop has been removed.
+  updateShadowAtPath(stateKey, path, newValue);
+
+  markAsDirty(stateKey, path, { bubble: true });
+
+  // Return the metadata of the node *after* the update.
+  const newShadowMeta = getShadowMetadata(stateKey, path);
+
+  return {
+    type: 'update',
+    oldValue: oldValue,
+    newValue,
+    shadowMeta: newShadowMeta,
+  };
+}
+function handleInsertMany(
+  stateKey: string,
+  path: string[],
+  payload: any[]
+): {
+  type: 'insert_many';
+  count: number;
+  shadowMeta: any;
+  path: string[];
+} {
+  // Use the existing, optimized global store function to perform the state update
+  insertManyShadowArrayElements(stateKey, path, payload);
+
+  markAsDirty(stateKey, path, { bubble: true });
+  const updatedMeta = getShadowMetadata(stateKey, path);
+
+  return {
+    type: 'insert_many',
+    count: payload.length,
+    shadowMeta: updatedMeta,
+    path: path,
+  };
+}
+function handleInsert(
+  stateKey: string,
+  path: string[],
+  payload: any,
+  index?: number,
+  itemId?: string
+): {
+  type: 'insert';
+  newValue: any;
+  shadowMeta: any;
+  path: string[];
+  itemId: string;
+  insertAfterId?: string;
+} {
   let newValue;
+
   if (isFunction(payload)) {
     const { value: currentValue } = getScopedData(stateKey, path);
-    newValue = payload({ state: currentValue, uuid: uuidv4() });
+    newValue = payload({ state: currentValue });
   } else {
     newValue = payload;
   }
+  //console.time('insertShadowArrayElement');
+  // Pass itemId to insertShadowArrayElement
+  const actualItemId = insertShadowArrayElement(
+    stateKey,
+    path,
+    newValue,
+    index,
+    itemId
+  );
+  //console.timeEnd('insertShadowArrayElement');
 
-  insertShadowArrayElement(stateKey, path, newValue);
   markAsDirty(stateKey, path, { bubble: true });
 
   const updatedMeta = getShadowMetadata(stateKey, path);
-  if (updatedMeta?.arrayKeys) {
-    const newItemKey = updatedMeta.arrayKeys[updatedMeta.arrayKeys.length - 1];
-    if (newItemKey) {
-      const newItemPath = newItemKey.split('.').slice(1);
-      markAsDirty(stateKey, newItemPath, { bubble: false });
-    }
+
+  let insertAfterId: string | undefined;
+  if (updatedMeta?.arrayKeys && index !== undefined && index > 0) {
+    insertAfterId = updatedMeta.arrayKeys[index - 1];
   }
 
-  return { type: 'insert', newValue, shadowMeta: updatedMeta };
+  return {
+    type: 'insert',
+    newValue,
+    shadowMeta: updatedMeta,
+    path: path,
+    itemId: actualItemId,
+    insertAfterId: insertAfterId,
+  };
 }
 
 function handleCut(
@@ -1231,7 +1360,7 @@ function flushQueue() {
     if (result.shadowMeta?.signals?.length > 0) {
       signalUpdates.push({ shadowMeta: result.shadowMeta, displayValue });
     }
-
+    // console.time('getComponentNotifications');
     const componentNotifications = getComponentNotifications(
       result.stateKey,
       result.path,
@@ -1241,60 +1370,64 @@ function flushQueue() {
     componentNotifications.forEach((component) => {
       allComponentsToNotify.add(component);
     });
+    //  console.timeEnd('getComponentNotifications');
   }
-
+  //console.time('logs');
   if (logsToAdd.length > 0) {
     addStateLog(logsToAdd);
   }
-
+  //console.timeEnd('logs');
   signalUpdates.forEach(({ shadowMeta, displayValue }) => {
     updateSignals(shadowMeta, displayValue);
   });
 
+  // console.time('updateComponents');
   allComponentsToNotify.forEach((component) => {
     component.forceUpdate();
   });
+  //console.timeEnd('updateComponents');
 
   // --- Step 3: CLEANUP ---
   // Clear the queue for the next batch of updates.
   updateBatchQueue = [];
   isFlushScheduled = false;
 }
-
 function createEffectiveSetState<T>(
   thisKey: string,
-  syncApiRef: React.MutableRefObject<any>,
   sessionId: string | undefined,
   latestInitialOptionsRef: React.MutableRefObject<OptionsType<T> | null>
 ): EffectiveSetState<T> {
-  // The returned function is the core setter that gets called by all state operations.
-  // It is now much simpler, delegating all work to the executeUpdate function.
-  return (newStateOrFunction, path, updateObj, validationKey?) => {
+  return (newStateOrFunction, path, updateObj) => {
     executeUpdate(thisKey, path, newStateOrFunction, updateObj);
   };
 
-  // This inner function handles the logic for a single state update.
   function executeUpdate(
     stateKey: string,
     path: string[],
     payload: any,
-    options: UpdateOptions
+    options: UpdateOptions // Now includes itemId
   ) {
-    // --- Step 1: Execute the core state change (Synchronous & Fast) ---
-    // This part modifies the in-memory state representation immediately.
     let result: any;
     switch (options.updateType) {
       case 'update':
         result = handleUpdate(stateKey, path, payload);
         break;
       case 'insert':
-        result = handleInsert(stateKey, path, payload);
+        result = handleInsert(
+          stateKey,
+          path,
+          payload,
+          options.index,
+          options.itemId
+        );
+        break;
+      case 'insert_many':
+        result = handleInsertMany(stateKey, path, payload);
         break;
       case 'cut':
         result = handleCut(stateKey, path);
         break;
     }
-
     result.stateKey = stateKey;
     result.path = path;
     updateBatchQueue.push(result);
@@ -1308,6 +1441,9 @@ function createEffectiveSetState<T>(
       status: 'new',
       oldValue: result.oldValue,
       newValue: result.newValue ?? null,
+      itemId: result.itemId,
+      insertAfterId: result.insertAfterId,
+      metaData: options.metaData,
     };
 
     updateBatchQueue.push(newUpdate);
@@ -1324,10 +1460,8 @@ function createEffectiveSetState<T>(
     if (latestInitialOptionsRef.current?.middleware) {
       latestInitialOptionsRef.current.middleware({ update: newUpdate });
     }
-
-    if (options.sync !== false && syncApiRef.current?.connected) {
-      syncApiRef.current.updateState({ operation: newUpdate });
-    }
+    runValidation(newUpdate, options.validationTrigger || 'programmatic');
+    notifyUpdate(newUpdate);
   }
 }
 
@@ -1335,22 +1469,18 @@ export function useCogsStateFn<TStateObject extends unknown>(
   stateObject: TStateObject,
   {
     stateKey,
-
     localStorage,
     formElements,
     reactiveDeps,
     reactiveType,
     componentId,
     defaultState,
-    syncUpdate,
     dependencies,
     serverState,
-    __useSync,
   }: {
     stateKey?: string;
     componentId?: string;
     defaultState?: TStateObject;
-    __useSync?: UseSyncType<TStateObject>;
     syncOptions?: SyncOptionsType<any>;
   } & OptionsType<TStateObject> = {}
 ) {
@@ -1365,16 +1495,6 @@ export function useCogsStateFn<TStateObject extends unknown>(
   latestInitialOptionsRef.current = (getInitialOptions(thisKey as string) ??
     null) as OptionsType<TStateObject> | null;
 
-  useEffect(() => {
-    if (syncUpdate && syncUpdate.stateKey === thisKey && syncUpdate.path?.[0]) {
-      const syncKey = `${syncUpdate.stateKey}:${syncUpdate.path.join('.')}`;
-      setSyncInfo(syncKey, {
-        timeStamp: syncUpdate.timeStamp!,
-        userId: syncUpdate.userId!,
-      });
-    }
-  }, [syncUpdate]);
-
   const resolveInitialState = useCallback(
     (
       overrideOptions?: OptionsType<TStateObject>
@@ -1438,9 +1558,13 @@ export function useCogsStateFn<TStateObject extends unknown>(
 
   // Effect 1: When this component's serverState prop changes, broadcast it
   useEffect(() => {
-    setServerStateUpdate(thisKey, serverState);
-  }, [serverState, thisKey]);
+    if (!serverState) return;
 
+    // Only broadcast if we have valid server data
+    if (serverState.status === 'success' && serverState.data !== undefined) {
+      setServerStateUpdate(thisKey, serverState);
+    }
+  }, [serverState, thisKey]);
   // Effect 2: Listen for server state updates from ANY component
   useEffect(() => {
     const unsubscribe = getGlobalStore
@@ -1456,13 +1580,14 @@ export function useCogsStateFn<TStateObject extends unknown>(
             return; // Ignore if no valid data
           }
 
+          // Store the server state in options for future reference
           setAndMergeOptions(thisKey, { serverState: serverStateData });
 
           const mergeConfig =
             typeof serverStateData.merge === 'object'
               ? serverStateData.merge
               : serverStateData.merge === true
-                ? { strategy: 'append' }
+                ? { strategy: 'append' as const, key: 'id' }
                 : null;
 
           const currentState = getShadowValue(thisKey, []);
@@ -1471,7 +1596,7 @@ export function useCogsStateFn<TStateObject extends unknown>(
           if (
             mergeConfig &&
             mergeConfig.strategy === 'append' &&
-            'key' in mergeConfig && // Type guard for key
+            'key' in mergeConfig &&
             Array.isArray(currentState) &&
             Array.isArray(incomingData)
           ) {
@@ -1483,88 +1608,93 @@ export function useCogsStateFn<TStateObject extends unknown>(
               return;
             }
 
+            // Get existing IDs to check for duplicates
             const existingIds = new Set(
               currentState.map((item: any) => item[keyField])
             );
 
+            // Filter out duplicates from incoming data
             const newUniqueItems = incomingData.filter(
               (item: any) => !existingIds.has(item[keyField])
             );
 
             if (newUniqueItems.length > 0) {
+              // Insert only the new unique items
               insertManyShadowArrayElements(thisKey, [], newUniqueItems);
             }
 
-            // Mark the entire final state as synced
+            // Mark the entire merged state as synced
             const finalState = getShadowValue(thisKey, []);
             markEntireStateAsServerSynced(
               thisKey,
               [],
               finalState,
-              serverStateData.timestamp
+              serverStateData.timestamp || Date.now()
             );
           } else {
-            // This handles the "replace" strategy (initial load)
+            // Replace strategy (default) - completely replace the state
             initializeShadowState(thisKey, incomingData);
 
+            // Mark as synced from server
             markEntireStateAsServerSynced(
               thisKey,
               [],
               incomingData,
-              serverStateData.timestamp
+              serverStateData.timestamp || Date.now()
             );
           }
+
+          // Notify all components subscribed to this state
+          notifyComponents(thisKey);
         }
       });
 
     return unsubscribe;
-  }, [thisKey, resolveInitialState]);
-
+  }, [thisKey]);
   useEffect(() => {
     const existingMeta = getGlobalStore
       .getState()
       .getShadowMetadata(thisKey, []);
+
+    // Skip if already initialized
     if (existingMeta && existingMeta.stateSource) {
-      return; // Already initialized, bail out.
+      return;
     }
 
     const options = getInitialOptions(thisKey as string);
 
     const features = {
-      syncEnabled: !!cogsSyncFn && !!syncOpt,
-      validationEnabled: !!(
-        options?.validation?.zodSchemaV4 || options?.validation?.zodSchemaV3
-      ),
       localStorageEnabled: !!options?.localStorage?.key,
     };
+
     setShadowMetadata(thisKey, [], {
       ...existingMeta,
       features,
     });
+
     if (options?.defaultState !== undefined || defaultState !== undefined) {
       const finalDefaultState = options?.defaultState || defaultState;
-
-      // Only set defaultState if it's not already set
       if (!options?.defaultState) {
         setAndMergeOptions(thisKey as string, {
           defaultState: finalDefaultState,
         });
       }
+    }
 
-      const { value: resolvedState, source, timestamp } = resolveInitialState();
-
-      initializeShadowState(thisKey, resolvedState);
-
-      // Set shadow metadata with the correct source info
-      setShadowMetadata(thisKey, [], {
-        stateSource: source,
-        lastServerSync: source === 'server' ? timestamp : undefined,
-        isDirty: false,
-        baseServerState: source === 'server' ? resolvedState : undefined,
-      });
+    const { value: resolvedState, source, timestamp } = resolveInitialState();
+    initializeShadowState(thisKey, resolvedState);
+    setShadowMetadata(thisKey, [], {
+      stateSource: source,
+      lastServerSync: source === 'server' ? timestamp : undefined,
+      isDirty: source === 'server' ? false : undefined,
+      baseServerState: source === 'server' ? resolvedState : undefined,
+    });
 
-      notifyComponents(thisKey);
+    if (source === 'server' && serverState) {
+      setServerStateUpdate(thisKey, serverState);
     }
+
+    notifyComponents(thisKey);
   }, [thisKey, ...(dependencies || [])]);
 
   useLayoutEffect(() => {
@@ -1633,10 +1763,9 @@ export function useCogsStateFn<TStateObject extends unknown>(
     };
   }, []);
 
-  const syncApiRef = useRef<SyncApi | null>(null);
   const effectiveSetState = createEffectiveSetState(
     thisKey,
-    syncApiRef,
+
     sessionId,
     latestInitialOptionsRef
   );
@@ -1656,16 +1785,6 @@ export function useCogsStateFn<TStateObject extends unknown>(
     return handler;
   }, [thisKey, sessionId]);
 
-  const cogsSyncFn = __useSync;
-  const syncOpt = latestInitialOptionsRef.current?.syncOptions;
-
-  if (cogsSyncFn) {
-    syncApiRef.current = cogsSyncFn(
-      updaterFinal as any,
-      syncOpt ?? ({} as any)
-    );
-  }
-
   return updaterFinal;
 }
 
@@ -1812,7 +1931,6 @@ function createProxyHandler<T>(
   sessionId?: string
 ): StateObject<T> {
   const proxyCache = new Map<string, any>();
-  let stateVersion = 0;
 
   function rebuildStateShape({
     path = [],
@@ -1826,6 +1944,7 @@ function createProxyHandler<T>(
     const derivationSignature = meta
       ? JSON.stringify(meta.arrayViews || meta.transforms)
       : '';
+
     const cacheKey =
       path.join('.') + ':' + componentId + ':' + derivationSignature;
     if (proxyCache.has(cacheKey)) {
@@ -1838,10 +1957,17 @@ function createProxyHandler<T>(
 
     const handler = {
       get(target: any, prop: string) {
+        if (typeof prop !== 'string') {
+          // This is a Symbol. Let the default "get" behavior happen.
+          // This allows internal JS operations and dev tools to work correctly
+          // without interfering with your state logic.
+          return Reflect.get(target, prop);
+        }
         if (path.length === 0 && prop in rootLevelMethods) {
           return rootLevelMethods[prop as keyof typeof rootLevelMethods];
         }
-        if (!prop.startsWith('$')) {
+
+        if (typeof prop === 'string' && !prop.startsWith('$')) {
           const nextPath = [...path, prop];
           return rebuildStateShape({
             path: nextPath,
@@ -1919,15 +2045,11 @@ function createProxyHandler<T>(
           const getStatusFunc = () => {
             // ✅ Use the optimized helper to get all data in one efficient call
             const { shadowMeta, value } = getScopedData(stateKey, path, meta);
-
-            // Priority 1: Explicitly dirty items. This is the most important status.
+            console.log('getStatusFunc', path, shadowMeta, value);
             if (shadowMeta?.isDirty === true) {
               return 'dirty';
             }
 
-            // ✅ Priority 2: Synced items. This condition is now cleaner.
-            // An item is considered synced if it came from the server OR was explicitly
-            // marked as not dirty (isDirty: false), covering all sync-related cases.
             if (
               shadowMeta?.stateSource === 'server' ||
               shadowMeta?.isDirty === false
@@ -1935,20 +2057,15 @@ function createProxyHandler<T>(
               return 'synced';
             }
 
-            // Priority 3: Items restored from localStorage.
             if (shadowMeta?.stateSource === 'localStorage') {
               return 'restored';
             }
 
-            // Priority 4: Items from default/initial state.
             if (shadowMeta?.stateSource === 'default') {
               return 'fresh';
             }
 
-            // ✅ REMOVED the redundant "root" check. The item's own `stateSource` is sufficient.
-
-            // Priority 5: A value exists but has no metadata. This is a fallback.
-            if (value !== undefined && !shadowMeta) {
+            if (value !== undefined) {
               return 'fresh';
             }
 
@@ -2425,7 +2542,7 @@ function createProxyHandler<T>(
               path,
               meta
             );
-
+            registerComponentDependency(stateKey, componentId, path);
             if (!arrayKeys || !Array.isArray(shadowValue)) {
               return []; // It's valid to map over an empty array.
             }
@@ -2776,8 +2893,6 @@ function createProxyHandler<T>(
 
             if (!Array.isArray(currentState)) return [];
 
-            stateVersion++;
-
             return rebuildStateShape({
               path: [...path, '[*]', fieldName],
               componentId: componentId!,
@@ -2839,7 +2954,18 @@ function createProxyHandler<T>(
             payload: InsertParams<InferArrayElement<T>>,
             index?: number
           ) => {
-            effectiveSetState(payload as any, path, { updateType: 'insert' });
+            effectiveSetState(payload as any, path, {
+              updateType: 'insert',
+              index,
+            });
+          };
+        }
+        if (prop === '$insertMany') {
+          return (payload: InferArrayElement<T>[]) => {
+            // Call the one true path for all state changes.
+            effectiveSetState(payload as any, path, {
+              updateType: 'insert_many',
+            });
           };
         }
         if (prop === '$uniqueInsert') {
@@ -2887,6 +3013,7 @@ function createProxyHandler<T>(
         if (prop === '$cut') {
           return (index?: number, options?: { waitForSync?: boolean }) => {
             const shadowMeta = getShadowMetadata(stateKey, path);
+            console.log('shadowMeta ->>>>>>>>>>>>>>>>', shadowMeta);
             if (!shadowMeta?.arrayKeys || shadowMeta.arrayKeys.length === 0)
               return;
 
@@ -2897,8 +3024,11 @@ function createProxyHandler<T>(
                   ? index
                   : shadowMeta.arrayKeys.length - 1;
 
+            console.log('indexToCut ->>>>>>>>>>>>>>>>', indexToCut);
+
             const idToCut = shadowMeta.arrayKeys[indexToCut];
             if (!idToCut) return;
+            console.log('idToCut ->>>>>>>>>>>>>>>>', idToCut);
 
             effectiveSetState(null, [...path, idToCut], {
               updateType: 'cut',
@@ -3000,11 +3130,7 @@ function createProxyHandler<T>(
               });
             }
 
-            return rebuildStateShape({
-              path: [...path, `not_found_${uuidv4()}`],
-              componentId: componentId!,
-              meta,
-            });
+            return null;
           };
         }
         if (prop === '$cutThis') {
@@ -3034,10 +3160,59 @@ function createProxyHandler<T>(
             });
         }
 
+        // if (prop === '$formInput') {
+        //   const _getFormElement = (path: string[]): HTMLElement | null => {
+        //     const metadata = getShadowMetadata(stateKey, path);
+        //     if (metadata?.formRef?.current) {
+        //       return metadata.formRef.current;
+        //     }
+        //     // This warning is helpful for debugging if a ref is missing.
+        //     console.warn(
+        //       `Form element ref not found for stateKey "${stateKey}" at path "${path.join('.')}"`
+        //     );
+        //     return null;
+        //   };
+        //   return {
+        //     setDisabled: (isDisabled: boolean) => {
+        //       const element = _getFormElement(path) as HTMLInputElement | null;
+        //       if (element) {
+        //         element.disabled = isDisabled;
+        //       }
+        //     },
+        //     focus: () => {
+        //       const element = _getFormElement(path);
+        //       element?.focus();
+        //     },
+        //     blur: () => {
+        //       const element = _getFormElement(path);
+        //       element?.blur();
+        //     },
+        //     scrollIntoView: (options?: ScrollIntoViewOptions) => {
+        //       const element = _getFormElement(path);
+        //       element?.scrollIntoView(
+        //         options ?? { behavior: 'smooth', block: 'center' }
+        //       );
+        //     },
+        //     click: () => {
+        //       const element = _getFormElement(path);
+        //       element?.click();
+        //     },
+        //     selectText: () => {
+        //       const element = _getFormElement(path) as
+        //         | HTMLInputElement
+        //         | HTMLTextAreaElement
+        //         | null;
+        //       if (element && typeof element.select === 'function') {
+        //         element.select();
+        //       }
+        //     },
+        //   };
+        // }
         if (prop === '$$get') {
           return () =>
             $cogsSignal({ _stateKey: stateKey, _path: path, _meta: meta });
         }
+
         if (prop === '$lastSynced') {
           const syncKey = `${stateKey}:${path.join('.')}`;
           return getSyncInfo(syncKey);
@@ -3109,8 +3284,43 @@ function createProxyHandler<T>(
           return componentId;
         }
         if (path.length == 0) {
+          if (prop === '$setOptions') {
+            return (options: OptionsType<T>) => {
+              setOptions({ stateKey, options, initialOptionsPart: {} });
+            };
+          }
+
+          if (prop === '$_applyUpdate') {
+            return (
+              value: any,
+              path: string[],
+              updateType: 'update' | 'insert' | 'cut' = 'update'
+            ) => {
+              effectiveSetState(value, path, { updateType });
+            };
+          }
+
+          if (prop === '$_getEffectiveSetState') {
+            return effectiveSetState;
+          }
+          if (prop === '$getPluginMetaData') {
+            return (pluginName: string) =>
+              getPluginMetaDataMap(stateKey, path)?.get(pluginName);
+          }
+          if (prop === '$addPluginMetaData') {
+            console.log('$addPluginMetaDat');
+            return (pluginName: string, data: Record<string, any>) =>
+              setPluginMetaData(stateKey, path, pluginName, data);
+          }
+          if (prop === '$removePluginMetaData') {
+            return (pluginName: string) =>
+              removePluginMetaData(stateKey, path, pluginName);
+          }
           if (prop === '$addZodValidation') {
-            return (zodErrors: any[]) => {
+            return (
+              zodErrors: any[],
+              source: 'client' | 'sync_engine' | 'api'
+            ) => {
               zodErrors.forEach((error) => {
                 const currentMeta =
                   getGlobalStore
@@ -3125,7 +3335,7 @@ function createProxyHandler<T>(
                       status: 'INVALID',
                       errors: [
                         {
-                          source: 'client',
+                          source: source || 'client',
                           message: error.message,
                           severity: 'error',
                           code: error.code,
@@ -3156,6 +3366,72 @@ function createProxyHandler<T>(
               });
             };
           }
+
+          if (prop === '$applyOperation') {
+            return (
+              operation: UpdateTypeDetail & {
+                validation?: any[];
+                version?: string;
+              },
+              metaData?: Record<string, any>
+            ) => {
+              // const validationErrorsFromServer = operation.validation || [];
+
+              // if (!operation || !operation.path) {
+              //   console.error(
+              //     'Invalid operation received by $applyOperation:',
+              //     operation
+              //   );
+              //   return;
+              // }
+
+              // const newErrors: ValidationError[] =
+              //   validationErrorsFromServer.map((err) => ({
+              //     source: 'sync_engine',
+              //     message: err.message,
+              //     severity: 'warning',
+              //     code: err.code,
+              //   }));
+              // console.log('newErrors', newErrors);
+              // getGlobalStore
+              //   .getState()
+              //   .setShadowMetadata(stateKey, operation.path, {
+              //     validation: {
+              //       status: newErrors.length > 0 ? 'INVALID' : 'VALID',
+              //       errors: newErrors,
+              //       lastValidated: Date.now(),
+              //     },
+              //   });
+              console.log(
+                'getGlobalStore',
+                getGlobalStore
+                  .getState()
+                  .getShadowMetadata(stateKey, operation.path)
+              );
+              let index: number | undefined;
+              if (
+                operation.insertAfterId &&
+                operation.updateType === 'insert'
+              ) {
+                const shadowMeta = getShadowMetadata(stateKey, operation.path);
+                if (shadowMeta?.arrayKeys) {
+                  const afterIndex = shadowMeta.arrayKeys.indexOf(
+                    operation.insertAfterId
+                  );
+                  if (afterIndex !== -1) {
+                    index = afterIndex + 1; // Insert after the found item
+                  }
+                }
+              }
+
+              effectiveSetState(operation.newValue, operation.path, {
+                updateType: operation.updateType,
+                itemId: operation.itemId,
+                index, // Pass the calculated index
+                metaData,
+              });
+            };
+          }
           if (prop === '$applyJsonPatch') {
             return (patches: Operation[]) => {
               const store = getGlobalStore.getState();
@@ -3250,14 +3526,8 @@ function createProxyHandler<T>(
 
           if (prop === '$getComponents')
             return () => getShadowMetadata(stateKey, [])?.components;
-          if (prop === '$getAllFormRefs')
-            return () =>
-              formRefStore.getState().getFormRefsByStateKey(stateKey);
-        }
-        if (prop === '$getFormRef') {
-          return () =>
-            formRefStore.getState().getFormRef(stateKey + '.' + path.join('.'));
         }
+
         if (prop === '$validationWrapper') {
           return ({
             children,
@@ -3277,6 +3547,7 @@ function createProxyHandler<T>(
             </ValidationWrapper>
           );
         }
+
         if (prop === '$_stateKey') return stateKey;
         if (prop === '$_path') return path;
         if (prop === '$update') {
@@ -3289,7 +3560,6 @@ function createProxyHandler<T>(
                   .getState()
                   .getShadowMetadata(stateKey, path);
 
-                // Update the metadata for this specific path
                 setShadowMetadata(stateKey, path, {
                   ...shadowMeta,
                   isDirty: false,
@@ -3297,7 +3567,6 @@ function createProxyHandler<T>(
                   lastServerSync: Date.now(),
                 });
 
-                // Notify any components that might be subscribed to the sync status
                 const fullPath = [stateKey, ...path].join('.');
                 notifyPathSubscribers(fullPath, {
                   type: 'SYNC_STATUS_CHANGE',
@@ -3371,21 +3640,15 @@ function createProxyHandler<T>(
         .getShadowMetadata(stateKey, []);
       let revertState;
 
-      // Determine the correct state to revert to (same logic as before)
       if (shadowMeta?.stateSource === 'server' && shadowMeta.baseServerState) {
         revertState = shadowMeta.baseServerState;
       } else {
         revertState = getGlobalStore.getState().initialStateGlobal[stateKey];
       }
 
-      // Perform necessary cleanup
       clearSelectedIndexesForState(stateKey);
-
-      // FIX 1: Use the IMMEDIATE, SYNCHRONOUS state reset function.
-      // This is what your tests expect for a clean slate.
       initializeShadowState(stateKey, revertState);
 
-      // Rebuild the proxy's internal shape after the reset
       rebuildStateShape({
         path: [],
         componentId: outerComponentId!,
@@ -3401,15 +3664,15 @@ function createProxyHandler<T>(
         localStorage.removeItem(storageKey);
       }
 
-      // FIX 2: Use the library's BATCHED notification system instead of a manual forceUpdate loop.
-      // This fixes the original infinite loop bug safely.
       notifyComponents(stateKey);
 
       return revertState;
     },
+    $initializeAndMergeShadowState: (newState: T) => {
+      initializeAndMergeShadowState(stateKey, newState);
+      notifyComponents(stateKey);
+    },
     $updateInitialState: (newState: T) => {
-      stateVersion++;
-
       const newUpdaterState = createProxyHandler(
         stateKey,
         effectiveSetState,
@@ -3488,7 +3751,6 @@ function SignalRenderer({
 
   const value = getShadowValue(proxy._stateKey, proxy._path, viewIds);
 
-  // Setup effect - runs only once
   useEffect(() => {
     const element = elementRef.current;
     if (!element || isSetupRef.current) return;
@@ -3511,7 +3773,6 @@ function SignalRenderer({
 
       instanceIdRef.current = `instance-${crypto.randomUUID()}`;
 
-      // Store signal info in shadow metadata
       const currentMeta =
         getGlobalStore
           .getState()