cogsbox-state 0.5.472 → 0.5.474

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;
@@ -101,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;
@@ -162,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;
@@ -247,12 +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> = {
+  $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) => void;
+  $applyOperation: (
+    operation: UpdateTypeDetail,
+    metaData?: Record<string, any>
+  ) => void;
   $applyJsonPatch: (patches: any[]) => void;
   $update: UpdateType<T>;
   $_path: string[];
@@ -273,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: ({
@@ -295,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;
 
@@ -303,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;
@@ -329,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:
@@ -340,21 +334,23 @@ 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; // For insert: the new item's ID
-  insertAfterId?: string; // For insert: ID to insert after (null = beginning)
+
+  itemId?: string;
+  insertAfterId?: string;
+  metaData?: Record<string, any>;
 };
 export type ReactivityUnion = 'none' | 'component' | 'deps' | 'all';
 export type ReactivityType =
@@ -365,12 +361,7 @@ 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>;
@@ -379,7 +370,7 @@ type ValidationOptionsType = {
   onChange?: 'error' | 'warning';
   blockSync?: boolean;
 };
-type UseSyncType<T> = (state: T, a: SyncOptionsType<any>) => SyncApi;
+
 type SyncOptionsType<TApiParams> = {
   apiParams: TApiParams;
   stateKey?: string;
@@ -390,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;
@@ -424,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;
@@ -440,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;
@@ -455,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];
@@ -489,6 +490,7 @@ const {
   setShadowMetadata,
   getShadowValue,
   initializeShadowState,
+  initializeAndMergeShadowState,
   updateShadowAtPath,
   insertShadowArrayElement,
   insertManyShadowArrayElements,
@@ -503,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;
@@ -547,10 +555,21 @@ 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>({
@@ -565,28 +584,23 @@ function setOptions<StateKey, Opt>({
   const initialOptions = getInitialOptions(stateKey as string) || {};
   const initialOptionsPartState = initialOptionsPart[stateKey as string] || {};
 
-  // Start with the base options
   let mergedOptions = { ...initialOptionsPartState, ...initialOptions };
   let needToAdd = false;
 
   if (options) {
-    // A function to recursively merge properties
     const deepMerge = (target: any, source: any) => {
       for (const key in source) {
         if (source.hasOwnProperty(key)) {
-          // If the property is an object (and not an array), recurse
           if (
             source[key] instanceof Object &&
             !Array.isArray(source[key]) &&
             target[key] instanceof Object
           ) {
-            // Check for changes before merging to set `needToAdd`
             if (!isDeepEqual(target[key], source[key])) {
               deepMerge(target[key], source[key]);
               needToAdd = true;
             }
           } else {
-            // Overwrite if the value is different
             if (target[key] !== source[key]) {
               target[key] = source[key];
               needToAdd = true;
@@ -597,78 +611,107 @@ function setOptions<StateKey, Opt>({
       return target;
     };
 
-    // Perform a deep merge
     mergedOptions = deepMerge(mergedOptions, options);
   }
 
-  // Your existing logic for defaults and preservation can follow
-  if (
-    mergedOptions.syncOptions &&
-    (!options || !options.hasOwnProperty('syncOptions'))
-  ) {
-    needToAdd = true;
-  }
-  if (
-    (mergedOptions.validation && mergedOptions?.validation?.zodSchemaV4) ||
-    mergedOptions?.validation?.zodSchemaV3
-  ) {
-    // Only set default if onBlur wasn't explicitly provided
-    const wasOnBlurProvided =
+  // Set default onBlur
+  if (mergedOptions.validation) {
+    const onBlurProvided =
       options?.validation?.hasOwnProperty('onBlur') ||
-      initialOptions?.validation?.hasOwnProperty('onBlur');
+      initialOptions?.validation?.hasOwnProperty('onBlur') ||
+      initialOptionsPartState?.validation?.hasOwnProperty('onBlur');
 
-    if (!wasOnBlurProvided) {
-      mergedOptions.validation.onBlur = 'error'; // Default to error on blur
+    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] || {};
 
@@ -683,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,
@@ -748,14 +807,29 @@ 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(() => {
+      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]>
   ) {
@@ -768,109 +842,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: { defaults: any };
-        relations?: 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]['relations'] extends object
-      ? TSyncSchema['schemas'][K] extends {
-          schemas: { defaults: infer D };
-        }
-        ? D
-        : TSyncSchema['schemas'][K]['schemas']['defaults']
-      : TSyncSchema['schemas'][K]['schemas']['defaults'];
-  },
-  {
-    [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];
-
-    // Check if we have relations and thus view defaults
-    if (entry?.relations && entry?.schemas?.defaults) {
-      // Use the view defaults when relations are present
-      initialState[key] = entry.schemas.defaults;
-    } else {
-      // Fall back to regular defaultValues
-      initialState[key] = entry?.schemas?.defaults || {};
-    }
-    console.log('initialState', initialState);
+      // If there's no new wrapper for this plugin, return the original object.
+      return plugin;
+    });
 
-    // Extract apiParams from the api.queryData._paramType
-    if (entry?.api?.queryData?._paramType) {
-      apiParamsMap[key] = entry.api.queryData._paramType;
-    }
+    // 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 createCogsState(initialState, {
-    __fromSyncSchema: true,
-    __syncNotifications: syncSchema.notifications,
-    __apiParamsMap: apiParamsMap,
-    __useSync: useSync,
-    __syncSchemas: schemas,
-  }) as any;
-}
+  return {
+    useCogsState,
+    setCogsOptionsByKey,
+    setCogsFormElements,
+  };
+};
 
 const saveToLocalStorage = <T,>(
   state: T,
@@ -1042,35 +1060,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;
@@ -1114,72 +1111,179 @@ function getComponentNotifications(
 
   const componentsToNotify = new Set<any>();
 
-  // For insert operations, use the array path not the item path
-  let notificationPath = path;
-  if (result.type === 'insert' && result.itemId) {
-    // We have the new structure with itemId separate
-    notificationPath = path; // Already the array path
-  }
-
-  // BUBBLE UP: Notify components at this path and all parent paths
-  let currentPath = [...notificationPath];
-  while (true) {
-    const pathMeta = getShadowMetadata(stateKey, currentPath);
-
-    if (pathMeta?.pathComponents) {
-      pathMeta.pathComponents.forEach((componentId: string) => {
-        const component = rootMeta.components?.get(componentId);
-        if (component) {
-          const reactiveTypes = Array.isArray(component.reactiveType)
-            ? component.reactiveType
-            : [component.reactiveType || 'component'];
-          if (!reactiveTypes.includes('none')) {
-            componentsToNotify.add(component);
+  // --- PASS 1: Notify specific subscribers based on update type ---
+
+  if (result.type === 'update') {
+    // --- Bubble-up Notification ---
+    // An update to `user.address.street` notifies listeners of `street`, `address`, and `user`.
+    let currentPath = [...path];
+    while (true) {
+      const pathMeta = getShadowMetadata(stateKey, currentPath);
+
+      if (pathMeta?.pathComponents) {
+        pathMeta.pathComponents.forEach((componentId: string) => {
+          const component = rootMeta.components?.get(componentId);
+          // NEW: Add component to the set instead of calling forceUpdate()
+          if (component) {
+            const reactiveTypes = Array.isArray(component.reactiveType)
+              ? component.reactiveType
+              : [component.reactiveType || 'component'];
+            if (!reactiveTypes.includes('none')) {
+              componentsToNotify.add(component);
+            }
           }
+        });
+      }
+
+      if (currentPath.length === 0) break;
+      currentPath.pop(); // Go up one level
+    }
+
+    // --- Deep Object Change Notification ---
+    // If the new value is an object, notify components subscribed to sub-paths that changed.
+    if (
+      result.newValue &&
+      typeof result.newValue === 'object' &&
+      !isArray(result.newValue)
+    ) {
+      const changedSubPaths = getDifferences(result.newValue, result.oldValue);
+
+      changedSubPaths.forEach((subPathString: string) => {
+        const subPath = subPathString.split('.');
+        const fullSubPath = [...path, ...subPath];
+        const subPathMeta = getShadowMetadata(stateKey, fullSubPath);
+
+        if (subPathMeta?.pathComponents) {
+          subPathMeta.pathComponents.forEach((componentId: string) => {
+            const component = rootMeta.components?.get(componentId);
+            // NEW: Add component to the set
+            if (component) {
+              const reactiveTypes = Array.isArray(component.reactiveType)
+                ? component.reactiveType
+                : [component.reactiveType || 'component'];
+              if (!reactiveTypes.includes('none')) {
+                componentsToNotify.add(component);
+              }
+            }
+          });
         }
       });
     }
+  } 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);
+
+    // --- 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
+      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 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,
+  };
+}
+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
+  index?: number,
+  itemId?: string
 ): {
   type: 'insert';
   newValue: any;
@@ -1189,19 +1293,28 @@ function handleInsert(
   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');
 
-  const itemId = insertShadowArrayElement(stateKey, path, newValue, index);
   markAsDirty(stateKey, path, { bubble: true });
 
   const updatedMeta = getShadowMetadata(stateKey, path);
 
-  // Find the ID that comes before this insertion point
   let insertAfterId: string | undefined;
   if (updatedMeta?.arrayKeys && index !== undefined && index > 0) {
     insertAfterId = updatedMeta.arrayKeys[index - 1];
@@ -1211,11 +1324,12 @@ function handleInsert(
     type: 'insert',
     newValue,
     shadowMeta: updatedMeta,
-    path: path, // Just the array path now
-    itemId: itemId,
+    path: path,
+    itemId: actualItemId,
     insertAfterId: insertAfterId,
   };
 }
+
 function handleCut(
   stateKey: string,
   path: string[]
@@ -1245,7 +1359,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,
@@ -1255,63 +1369,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);
@@ -1327,6 +1442,7 @@ function createEffectiveSetState<T>(
       newValue: result.newValue ?? null,
       itemId: result.itemId,
       insertAfterId: result.insertAfterId,
+      metaData: options.metaData,
     };
 
     updateBatchQueue.push(newUpdate);
@@ -1343,10 +1459,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);
   }
 }
 
@@ -1354,22 +1468,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> = {}
 ) {
@@ -1384,16 +1494,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>
@@ -1563,10 +1663,6 @@ export function useCogsStateFn<TStateObject extends unknown>(
     const options = getInitialOptions(thisKey as string);
 
     const features = {
-      syncEnabled: !!cogsSyncFn && !!syncOpt,
-      validationEnabled: !!(
-        options?.validation?.zodSchemaV4 || options?.validation?.zodSchemaV3
-      ),
       localStorageEnabled: !!options?.localStorage?.key,
     };
 
@@ -1666,10 +1762,9 @@ export function useCogsStateFn<TStateObject extends unknown>(
     };
   }, []);
 
-  const syncApiRef = useRef<SyncApi | null>(null);
   const effectiveSetState = createEffectiveSetState(
     thisKey,
-    syncApiRef,
+
     sessionId,
     latestInitialOptionsRef
   );
@@ -1689,16 +1784,6 @@ export function useCogsStateFn<TStateObject extends unknown>(
     return handler;
   }, [thisKey, sessionId]);
 
-  const cogsSyncFn = __useSync;
-  const syncOpt = latestInitialOptionsRef.current?.syncOptions;
-  console.log('syncOpt', syncOpt);
-  if (cogsSyncFn) {
-    syncApiRef.current = cogsSyncFn(
-      updaterFinal as any,
-      syncOpt ?? ({} as any)
-    );
-  }
-
   return updaterFinal;
 }
 
@@ -1845,7 +1930,6 @@ function createProxyHandler<T>(
   sessionId?: string
 ): StateObject<T> {
   const proxyCache = new Map<string, any>();
-  let stateVersion = 0;
 
   function rebuildStateShape({
     path = [],
@@ -1859,6 +1943,7 @@ function createProxyHandler<T>(
     const derivationSignature = meta
       ? JSON.stringify(meta.arrayViews || meta.transforms)
       : '';
+
     const cacheKey =
       path.join('.') + ':' + componentId + ':' + derivationSignature;
     if (proxyCache.has(cacheKey)) {
@@ -1871,10 +1956,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,
@@ -2800,8 +2892,6 @@ function createProxyHandler<T>(
 
             if (!Array.isArray(currentState)) return [];
 
-            stateVersion++;
-
             return rebuildStateShape({
               path: [...path, '[*]', fieldName],
               componentId: componentId!,
@@ -2863,7 +2953,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') {
@@ -2911,6 +3012,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;
 
@@ -2921,8 +3023,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',
@@ -3024,11 +3129,7 @@ function createProxyHandler<T>(
               });
             }
 
-            return rebuildStateShape({
-              path: [...path, `not_found_${uuidv4()}`],
-              componentId: componentId!,
-              meta,
-            });
+            return null;
           };
         }
         if (prop === '$cutThis') {
@@ -3058,10 +3159,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);
@@ -3133,6 +3283,38 @@ 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[],
@@ -3185,46 +3367,67 @@ function createProxyHandler<T>(
           }
 
           if (prop === '$applyOperation') {
-            return (operation: UpdateTypeDetail & { validation?: any[] }) => {
-              const validationErrorsFromServer = operation.validation || [];
-
-              if (!operation || !operation.path) {
-                console.error(
-                  'Invalid operation received by $applyOperation:',
-                  operation
-                );
-                return;
-              }
-
-              const updatePath = operation.path;
-
-              const currentMeta =
+            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, updatePath) || {};
-
-              const newErrors: ValidationError[] =
-                validationErrorsFromServer.map((err) => ({
-                  source: 'sync_engine',
-                  message: err.message,
-                  severity: 'warning',
-                  code: err.code,
-                }));
+                  .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
+                  }
+                }
+              }
 
-              console.log('updatePath', updatePath);
-              getGlobalStore
-                .getState()
-                .setShadowMetadata(stateKey, updatePath, {
-                  ...currentMeta,
-                  validation: {
-                    status: newErrors.length > 0 ? 'INVALID' : 'VALID',
-                    errors: newErrors,
-                    lastValidated: Date.now(),
-                  },
-                });
-              effectiveSetState(operation.newValue, updatePath, {
+              effectiveSetState(operation.newValue, operation.path, {
                 updateType: operation.updateType,
-                sync: false,
+                itemId: operation.itemId,
+                index, // Pass the calculated index
+                metaData,
               });
             };
           }
@@ -3322,14 +3525,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,
@@ -3349,6 +3546,7 @@ function createProxyHandler<T>(
             </ValidationWrapper>
           );
         }
+
         if (prop === '$_stateKey') return stateKey;
         if (prop === '$_path') return path;
         if (prop === '$update') {
@@ -3469,9 +3667,11 @@ function createProxyHandler<T>(
 
       return revertState;
     },
+    $initializeAndMergeShadowState: (newState: T) => {
+      initializeAndMergeShadowState(stateKey, newState);
+      notifyComponents(stateKey);
+    },
     $updateInitialState: (newState: T) => {
-      stateVersion++;
-
       const newUpdaterState = createProxyHandler(
         stateKey,
         effectiveSetState,