cogsbox-state 0.5.471 → 0.5.473

package/src/store.ts

@@ -7,8 +7,6 @@ import type {
   UpdateTypeDetail,
 } from './CogsState.js';
 
-import { type ReactNode } from 'react';
-
 export type FreshValuesObject = {
   pathsToValues?: string[];
   prevValue?: any;
@@ -17,55 +15,16 @@ export type FreshValuesObject = {
 };
 
 type StateValue = any;
-
+export type FormEventType = {
+  type: 'focus' | 'blur' | 'input';
+  value?: any;
+  path: string[];
+};
 export type TrieNode = {
   subscribers: Set<string>;
   children: Map<string, TrieNode>;
 };
 
-export type FormRefStoreState = {
-  formRefs: Map<string, React.RefObject<any>>;
-  registerFormRef: (id: string, ref: React.RefObject<any>) => void;
-  getFormRef: (id: string) => React.RefObject<any> | undefined;
-  removeFormRef: (id: string) => void;
-  getFormRefsByStateKey: (
-    stateKey: string
-  ) => Map<string, React.RefObject<any>>;
-};
-
-export const formRefStore = create<FormRefStoreState>((set, get) => ({
-  formRefs: new Map(),
-
-  registerFormRef: (id, ref) =>
-    set((state) => {
-      const newRefs = new Map(state.formRefs);
-      newRefs.set(id, ref);
-      return { formRefs: newRefs };
-    }),
-
-  getFormRef: (id) => get().formRefs.get(id),
-
-  removeFormRef: (id) =>
-    set((state) => {
-      const newRefs = new Map(state.formRefs);
-      newRefs.delete(id);
-      return { formRefs: newRefs };
-    }),
-
-  getFormRefsByStateKey: (stateKey) => {
-    const allRefs = get().formRefs;
-    const stateKeyPrefix = stateKey + '.';
-    const filteredRefs = new Map();
-
-    allRefs.forEach((ref, id) => {
-      if (id.startsWith(stateKeyPrefix) || id === stateKey) {
-        filteredRefs.set(id, ref);
-      }
-    });
-
-    return filteredRefs;
-  },
-}));
 export type ComponentsType = {
   components?: Map<
     string,
@@ -99,9 +58,81 @@ export type ValidationState = {
   lastValidated?: number;
   validatedValue?: any;
 };
-
+export type SchemaTypeInfo = {
+  type:
+    | 'string'
+    | 'number'
+    | 'boolean'
+    | 'array'
+    | 'object'
+    | 'date'
+    | 'unknown';
+  schema: any; // Store the actual Zod schema object
+  source: 'sync' | 'zod4' | 'zod3' | 'runtime' | 'default';
+  default: any;
+  nullable?: boolean;
+  optional?: boolean;
+};
+export type ClientActivityState = {
+  // ALL elements currently mounted for this path
+  elements: Map<
+    string,
+    {
+      // componentId -> element info
+      domRef: React.RefObject<HTMLElement>;
+      elementType:
+        | 'input'
+        | 'textarea'
+        | 'select'
+        | 'checkbox'
+        | 'radio'
+        | 'range'
+        | 'file'
+        | 'custom';
+      inputType?: string; // For input elements: 'text', 'number', 'date', etc.
+      mountedAt: number;
+
+      // Current activity for THIS specific element
+      currentActivity?: {
+        type:
+          | 'focus'
+          | 'blur'
+          | 'input'
+          | 'select'
+          | 'hover'
+          | 'scroll'
+          | 'cursor';
+        startTime: number;
+        details?: {
+          value?: any;
+          previousValue?: any;
+          inputLength?: number;
+          changeType?: 'keyboard' | 'paste' | 'drop' | 'select' | 'clear';
+          selectionStart?: number;
+          selectionEnd?: number;
+          selectedText?: string;
+          cursorPosition?: number;
+          scrollTop?: number;
+          scrollLeft?: number;
+          isComposing?: boolean;
+          keystrokeCount?: number;
+          key?: string;
+          optionCount?: number;
+          selectedIndex?: number;
+          checked?: boolean;
+          arrayOperation?: 'insert' | 'remove' | 'reorder';
+          arrayIndex?: number;
+          arrayLength?: number;
+        };
+      };
+    }
+  >;
+};
+// Update ShadowMetadata to include typeInfo
 export type ShadowMetadata = {
+  value?: any;
   id?: string;
+  typeInfo?: SchemaTypeInfo;
   stateSource?: 'default' | 'server' | 'localStorage';
   lastServerSync?: number;
   isDirty?: boolean;
@@ -115,26 +146,14 @@ export type ShadowMetadata = {
   syncInfo?: { status: string };
   validation?: ValidationState;
   features?: {
-    syncEnabled: boolean;
-    validationEnabled: boolean;
     localStorageEnabled: boolean;
   };
-  lastUpdated?: number;
   signals?: Array<{
     instanceId: string;
     parentId: string;
     position: number;
     effect?: string;
   }>;
-  mapWrappers?: Array<{
-    instanceId: string;
-    path: string[];
-    componentId: string;
-    meta?: any;
-    mapFn: (setter: any, index: number, arraySetter: any) => ReactNode;
-    containerRef: HTMLDivElement | null;
-    rebuildStateShape: any;
-  }>;
   transformCaches?: Map<
     string,
     {
@@ -144,6 +163,7 @@ export type ShadowMetadata = {
     }
   >;
   pathComponents?: Set<string>;
+
   streams?: Map<
     string,
     {
@@ -151,21 +171,40 @@ export type ShadowMetadata = {
       flushTimer: NodeJS.Timeout | null;
     }
   >;
+  pluginMetaData?: Map<string, Record<string, any>>;
+  // formRef?: React.RefObject<any>;
+  // focusedElement?: { path: string[]; ref: React.RefObject<any> } | null;
+  clientActivityState?: ClientActivityState;
 } & ComponentsType;
 
 type ShadowNode = {
-  value?: any;
   _meta?: ShadowMetadata;
   [key: string]: any;
 };
 
 export type CogsGlobalState = {
+  getPluginMetaDataMap: (
+    key: string,
+    path: string[]
+  ) => Map<string, Record<string, any>> | undefined;
+  setPluginMetaData: (
+    key: string,
+    path: string[],
+    pluginName: string,
+    data: Record<string, any>
+  ) => void;
+  removePluginMetaData: (
+    key: string,
+    path: string[],
+    pluginName: string
+  ) => void;
   setTransformCache: (
     key: string,
     path: string[],
     cacheKey: string,
     cacheData: any
   ) => void;
+  initializeAndMergeShadowState: (key: string, initialState: any) => void;
   initializeShadowState: (key: string, initialState: any) => void;
   getShadowNode: (key: string, path: string[]) => ShadowNode | undefined;
   getShadowMetadata: (
@@ -190,15 +229,15 @@ export type CogsGlobalState = {
   addItemsToArrayNode: (
     key: string,
     arrayPath: string[],
-    newItems: any,
-    newKeys: string[]
+    newItems: any
   ) => void;
   insertShadowArrayElement: (
     key: string,
     arrayPath: string[],
     newItem: any,
-    index?: number
-  ) => void;
+    index?: number,
+    itemId?: string
+  ) => string;
   removeShadowArrayElement: (key: string, itemPath: string[]) => void;
   registerComponent: (
     stateKey: string,
@@ -255,51 +294,452 @@ export type CogsGlobalState = {
   setSyncInfo: (key: string, syncInfo: SyncInfo) => void;
   getSyncInfo: (key: string) => SyncInfo | null;
 };
+function getTypeFromZodSchema(
+  schema: any,
+  source: 'zod4' | 'zod3' | 'sync' = 'zod4'
+): SchemaTypeInfo | null {
+  if (!schema) return null;
+
+  let current = schema;
+  let isNullable = false;
+  let isOptional = false;
+  let defaultValue: any = undefined;
+  let hasDefault = false;
+
+  // This loop will now correctly navigate through any wrappers AND unions.
+  for (let i = 0; i < 20; i++) {
+    // Added a safety break for complex schemas
+    const def = current?.def || current?._def;
+    if (!def) break;
+
+    const typeIdentifier = def.typeName || def.type || current._type;
+
+    // --- START: THE CRITICAL FIX FOR ZodUnion ---
+    if (typeIdentifier === 'ZodUnion' || typeIdentifier === 'union') {
+      if (def.options && def.options.length > 0) {
+        current = def.options[0]; // Proceed by analyzing the FIRST option of the union
+        continue; // Restart the loop with the new schema
+      } else {
+        break; // Union with no options, cannot determine type
+      }
+    }
+    // --- END: THE CRITICAL FIX ---
+
+    if (typeIdentifier === 'ZodOptional' || typeIdentifier === 'optional') {
+      isOptional = true;
+    } else if (
+      typeIdentifier === 'ZodNullable' ||
+      typeIdentifier === 'nullable'
+    ) {
+      isNullable = true;
+    } else if (
+      typeIdentifier === 'ZodDefault' ||
+      typeIdentifier === 'default'
+    ) {
+      hasDefault = true;
+      defaultValue =
+        typeof def.defaultValue === 'function'
+          ? def.defaultValue()
+          : def.defaultValue;
+    } else if (
+      typeIdentifier !== 'ZodEffects' &&
+      typeIdentifier !== 'effects'
+    ) {
+      // This is not a wrapper we need to unwrap further, so we can exit the loop.
+      break;
+    }
 
-export function buildShadowNode(value: any): ShadowNode {
-  if (value === null || typeof value !== 'object') {
-    return { value };
+    const nextSchema = def.innerType || def.schema || current._inner;
+    if (!nextSchema || nextSchema === current) {
+      break; // Reached the end or a recursive schema
+    }
+    current = nextSchema;
   }
 
-  if (Array.isArray(value)) {
-    const arrayNode: ShadowNode = { _meta: { arrayKeys: [] } };
-    const idKeys: string[] = [];
+  const baseSchema = current;
+  const baseDef = baseSchema?.def || baseSchema?._def;
+  const baseType = baseDef?.typeName || baseDef?.type || baseSchema?._type;
+
+  if (baseType === 'ZodNumber' || baseType === 'number') {
+    return {
+      type: 'number',
+      schema: schema,
+      source,
+      default: hasDefault ? defaultValue : 0,
+      nullable: isNullable,
+      optional: isOptional,
+    };
+  }
+  if (baseType === 'ZodString' || baseType === 'string') {
+    return {
+      type: 'string',
+      schema: schema,
+      source,
+      default: hasDefault ? defaultValue : '',
+      nullable: isNullable,
+      optional: isOptional,
+    };
+  }
+  if (baseType === 'ZodBoolean' || baseType === 'boolean') {
+    return {
+      type: 'boolean',
+      schema: schema,
+      source,
+      default: hasDefault ? defaultValue : false,
+      nullable: isNullable,
+      optional: isOptional,
+    };
+  }
+  if (baseType === 'ZodArray' || baseType === 'array') {
+    return {
+      type: 'array',
+      schema: schema,
+      source,
+      default: hasDefault ? defaultValue : [],
+      nullable: isNullable,
+      optional: isOptional,
+    };
+  }
+  if (baseType === 'ZodObject' || baseType === 'object') {
+    return {
+      type: 'object',
+      schema: schema,
+      source,
+      default: hasDefault ? defaultValue : {},
+      nullable: isNullable,
+      optional: isOptional,
+    };
+  }
+  if (baseType === 'ZodDate' || baseType === 'date') {
+    return {
+      type: 'date',
+      schema: schema,
+      source,
+      default: hasDefault ? defaultValue : new Date(),
+      nullable: isNullable,
+      optional: isOptional,
+    };
+  }
+
+  return null;
+}
+
+// Helper to get type info from runtime value
+function getTypeFromValue(value: any): SchemaTypeInfo {
+  if (value === null) {
+    return {
+      type: 'unknown',
+      schema: null,
+      source: 'default',
+      default: null,
+      nullable: true,
+    };
+  }
+
+  if (value === undefined) {
+    return {
+      type: 'unknown',
+      schema: null,
+      source: 'default',
+      default: undefined,
+      optional: true,
+    };
+  }
+
+  const valueType = typeof value;
+
+  if (valueType === 'number') {
+    return { type: 'number', schema: null, source: 'runtime', default: value };
+  } else if (valueType === 'string') {
+    return { type: 'string', schema: null, source: 'runtime', default: value };
+  } else if (valueType === 'boolean') {
+    return { type: 'boolean', schema: null, source: 'runtime', default: value };
+  } else if (Array.isArray(value)) {
+    return { type: 'array', schema: null, source: 'runtime', default: [] };
+  } else if (value instanceof Date) {
+    return { type: 'date', schema: null, source: 'runtime', default: value };
+  } else if (valueType === 'object') {
+    return { type: 'object', schema: null, source: 'runtime', default: {} };
+  }
+
+  return { type: 'unknown', schema: null, source: 'runtime', default: value };
+}
+type BuildContext = {
+  stateKey: string;
+  path: string[];
+  schemas: {
+    sync?: any;
+    zodV4?: any;
+    zodV3?: any;
+  };
+};
 
-    value.forEach((item) => {
-      const itemId = `id:${generateId()}`;
-      arrayNode[itemId] = buildShadowNode(item);
-      idKeys.push(itemId);
+export function buildShadowNode(
+  stateKey: string,
+  value: any,
+  context?: BuildContext
+): ShadowNode {
+  // Handle null/undefined/primitives (This part is already correct)
+  if (value === null || value === undefined || typeof value !== 'object') {
+    const node: ShadowNode = { _meta: { value } };
+    node._meta!.typeInfo = getTypeInfoForPath(value, context);
+    return node;
+  }
+
+  // Handle arrays
+  if (Array.isArray(value)) {
+    // 1. Create the node for the array.
+    const node: ShadowNode = { _meta: { arrayKeys: [] } };
+
+    // 2. Get the type info for the array itself ONCE, right at the start.
+    node._meta!.typeInfo = getTypeInfoForPath(value, context);
+
+    // 3. THEN, recursively process the children.
+    value.forEach((item, index) => {
+      const itemId = generateId(stateKey);
+      const itemContext = context
+        ? {
+            ...context,
+            path: [...context.path, index.toString()],
+          }
+        : undefined;
+
+      node[itemId] = buildShadowNode(stateKey, item, itemContext);
+      node._meta!.arrayKeys!.push(itemId);
     });
 
-    arrayNode._meta!.arrayKeys = idKeys;
-    return arrayNode;
+    return node;
   }
 
+  // Handle objects
   if (value.constructor === Object) {
-    const objectNode: ShadowNode = { _meta: {} };
+    // 1. Create the node for the object.
+    const node: ShadowNode = { _meta: {} };
+
+    // 2. Get the type info for the object itself ONCE, right at the start.
+    node._meta!.typeInfo = getTypeInfoForPath(value, context);
+
+    // 3. THEN, recursively process the children.
     for (const key in value) {
       if (Object.prototype.hasOwnProperty.call(value, key)) {
-        objectNode[key] = buildShadowNode(value[key]);
+        const propContext = context
+          ? {
+              ...context,
+              path: [...context.path, key],
+            }
+          : undefined;
+
+        node[key] = buildShadowNode(stateKey, value[key], propContext);
       }
     }
-    return objectNode;
+
+    return node;
   }
 
-  return { value };
+  // Fallback for other object types (Date, class instances, etc.)
+  return {
+    _meta: {
+      value: value,
+      typeInfo: getTypeFromValue(value),
+    },
+  };
 }
-// store.ts - Replace the shadow store methods with mutable versions
-// store.ts - Replace the shadow store methods with mutable versions
 
-// Module-level mutable store
-const shadowStateStore = new Map<string, ShadowNode>();
-let globalCounter = 0;
+// Helper function to get type info (extracted for clarity)
+function getTypeInfoForPath(
+  value: any,
+  context?: BuildContext
+): SchemaTypeInfo {
+  if (context) {
+    // Try to get schema-based type info
+    let typeInfo: SchemaTypeInfo | null = null;
+
+    if (context.schemas.zodV4) {
+      const schema =
+        context.path.length === 0
+          ? context.schemas.zodV4
+          : getSchemaAtPath(context.schemas.zodV4, context.path);
+      if (schema) {
+        typeInfo = getTypeFromZodSchema(schema, 'zod4');
+      }
+    }
+
+    if (!typeInfo && context.schemas.zodV3) {
+      const schema =
+        context.path.length === 0
+          ? context.schemas.zodV3
+          : getSchemaAtPath(context.schemas.zodV3, context.path);
+      if (schema) {
+        typeInfo = getTypeFromZodSchema(schema, 'zod3');
+      }
+    }
+
+    if (!typeInfo && context.schemas.sync?.[context.stateKey]) {
+      typeInfo = getTypeFromValue(value);
+      typeInfo.source = 'sync';
+    }
 
-export function generateId(prefix = 'id'): string {
-  return `${prefix}:${(globalCounter++).toString(36)}`;
+    if (typeInfo) return typeInfo;
+  }
+
+  return getTypeFromValue(value);
+}
+
+export function updateShadowTypeInfo(
+  stateKey: string,
+  rootSchema: any,
+  source: 'zod4' | 'zod3'
+) {
+  const rootNode =
+    shadowStateStore.get(stateKey) || shadowStateStore.get(`[${stateKey}`);
+  if (!rootNode) return;
+
+  function updateNodeTypeInfo(node: any, path: string[]) {
+    if (!node || typeof node !== 'object') return;
+    const fieldSchema = getSchemaAtPath(rootSchema, path);
+
+    if (fieldSchema) {
+      const typeInfo = getTypeFromZodSchema(fieldSchema, source);
+      if (typeInfo) {
+        if (!node._meta) node._meta = {};
+        node._meta.typeInfo = {
+          ...typeInfo,
+          schema: fieldSchema,
+        };
+      }
+    }
+
+    // Recursively update children
+    if (node._meta?.arrayKeys) {
+      node._meta.arrayKeys.forEach((itemKey: string) => {
+        if (node[itemKey]) {
+          updateNodeTypeInfo(node[itemKey], [...path, '0']); // Use index 0 for array item schema
+        }
+      });
+    } else if (!node._meta?.hasOwnProperty('value')) {
+      // It's an object - update each property
+      Object.keys(node).forEach((key) => {
+        if (key !== '_meta') {
+          updateNodeTypeInfo(node[key], [...path, key]);
+        }
+      });
+    }
+  }
+
+  updateNodeTypeInfo(rootNode, []);
+}
+
+/**
+ * Reliably unwraps a Zod schema to its core type, handling modifiers
+ * from both Zod v3 and modern Zod.
+ */
+function unwrapSchema(schema: any): any {
+  let current = schema;
+  while (current) {
+    // Version-agnostic way to get the definition object
+    const def = current.def || current._def;
+
+    // VITAL FIX: Check for `def.type` (like in your log), `def.typeName` (modern Zod), and `_type` (zod v3)
+    const typeIdentifier = def?.typeName || def?.type || current._type;
+
+    if (
+      typeIdentifier === 'ZodOptional' ||
+      typeIdentifier === 'optional' ||
+      typeIdentifier === 'ZodNullable' ||
+      typeIdentifier === 'nullable' ||
+      typeIdentifier === 'ZodDefault' ||
+      typeIdentifier === 'default' ||
+      typeIdentifier === 'ZodEffects' ||
+      typeIdentifier === 'effects'
+    ) {
+      // Get the inner schema, supporting multiple internal structures
+      current =
+        def.innerType || def.schema || current._inner || current.unwrap?.();
+    } else {
+      break; // Reached the base schema
+    }
+  }
+  return current;
 }
 
+/**
+ * Helper function to get a nested schema at a specific path,
+ * correctly handling both Zod v3 and modern Zod internals.
+ */
+function getSchemaAtPath(schema: any, path: string[]): any {
+  if (!schema) return null;
+  if (path.length === 0) return schema;
+
+  let currentSchema = schema;
+
+  for (const segment of path) {
+    const containerSchema = unwrapSchema(currentSchema);
+    if (!containerSchema) return null;
+
+    const def = containerSchema.def || containerSchema._def;
+
+    // VITAL FIX: Check for `def.type` as you discovered.
+    const typeIdentifier = def?.typeName || def?.type || containerSchema._type;
+
+    if (typeIdentifier === 'ZodObject' || typeIdentifier === 'object') {
+      // VITAL FIX: Check for `shape` inside `def` first, then on the schema itself.
+      const shape =
+        def?.shape || containerSchema.shape || containerSchema._shape;
+      currentSchema = shape?.[segment];
+    } else if (typeIdentifier === 'ZodArray' || typeIdentifier === 'array') {
+      // For arrays, the next schema is always the element's schema.
+      currentSchema = containerSchema.element || def?.type;
+    } else {
+      return null; // Not a container, cannot traverse deeper.
+    }
+
+    if (!currentSchema) {
+      return null; // Path segment does not exist in the schema.
+    }
+  }
+
+  return currentSchema;
+}
+export const shadowStateStore = new Map<string, ShadowNode>();
+let globalCounter = 0;
+const instanceId = Date.now().toString(36);
+
+export function generateId(stateKey: string): string {
+  const prefix = 'local';
+
+  return `id:${prefix}_${instanceId}_${(globalCounter++).toString(36)}`;
+}
 export const getGlobalStore = create<CogsGlobalState>((set, get) => ({
-  // Remove shadowStateStore from Zustand state
+  getPluginMetaDataMap: (
+    key: string,
+    path: string[]
+  ): Map<string, Record<string, any>> | undefined => {
+    const metadata = get().getShadowMetadata(key, path);
+    return metadata?.pluginMetaData;
+  },
+
+  setPluginMetaData: (
+    key: string,
+    path: string[], // ADD THIS PARAMETER
+    pluginName: string,
+    data: Record<string, any>
+  ) => {
+    const metadata = get().getShadowMetadata(key, path) || {}; // Use the path!
+    const pluginMetaData = new Map(metadata.pluginMetaData || []);
+    const existingData = pluginMetaData.get(pluginName) || {};
+    pluginMetaData.set(pluginName, { ...existingData, ...data });
+    get().setShadowMetadata(key, path, { ...metadata, pluginMetaData });
+    get().notifyPathSubscribers([key, ...path].join('.'), {
+      type: 'METADATA_UPDATE',
+    });
+  },
+  removePluginMetaData: (key: string, path: string[], pluginName: string) => {
+    const metadata = get().getShadowMetadata(key, path);
+    if (!metadata?.pluginMetaData) return;
+    const pluginMetaData = new Map(metadata.pluginMetaData);
+    pluginMetaData.delete(pluginName);
+    get().setShadowMetadata(key, path, { ...metadata, pluginMetaData });
+  },
 
   setTransformCache: (
     key: string,
@@ -316,7 +756,151 @@ export const getGlobalStore = create<CogsGlobalState>((set, get) => ({
       transformCaches: metadata.transformCaches,
     });
   },
+  // Replace your entire `initializeAndMergeShadowState` function with this one.
+
+  initializeAndMergeShadowState: (key: string, shadowState: any) => {
+    const isArrayState = shadowState?._meta?.arrayKeys !== undefined;
+    const storageKey = isArrayState ? `[${key}` : key;
+
+    const existingRoot =
+      shadowStateStore.get(storageKey) ||
+      shadowStateStore.get(key) ||
+      shadowStateStore.get(`[${key}`);
+
+    // --- THIS LOGIC IS RESTORED ---
+    // This is vital for preserving component registrations and other top-level
+    // metadata across a full merge/replace, which is why removing it was a mistake.
+    let preservedMetadata: Partial<ShadowMetadata> = {};
+    if (existingRoot?._meta) {
+      const {
+        components,
+        features,
+        lastServerSync,
+        stateSource,
+        baseServerState,
+        pathComponents,
+        signals,
+        validation,
+      } = existingRoot._meta;
+
+      if (components) preservedMetadata.components = components;
+      if (features) preservedMetadata.features = features;
+      if (lastServerSync) preservedMetadata.lastServerSync = lastServerSync;
+      if (stateSource) preservedMetadata.stateSource = stateSource;
+      if (baseServerState) preservedMetadata.baseServerState = baseServerState;
+      if (pathComponents) preservedMetadata.pathComponents = pathComponents;
+      if (signals) preservedMetadata.signals = signals;
+      if (validation) preservedMetadata.validation = validation;
+    }
+    function deepMergeShadowNodes(target: ShadowNode, source: ShadowNode) {
+      // --- START: CORRECTED, MORE ROBUST METADATA MERGE ---
+      if (source._meta || target._meta) {
+        const existingMeta = target._meta || {};
+        const sourceMeta = source._meta || {};
+
+        // Combine metadata, letting the source overwrite simple, top-level properties.
+        const newMeta = { ...existingMeta, ...sourceMeta };
+
+        // CRITICAL FIX: Now, explicitly check and preserve the complex, valuable
+        // objects from the existing state if the incoming source state doesn't have
+        // an equally good or better version.
+
+        // 1. Preserve rich TypeInfo (with a schema) over a simple runtime one.
+        if (existingMeta.typeInfo?.schema && !sourceMeta.typeInfo?.schema) {
+          newMeta.typeInfo = existingMeta.typeInfo;
+        }
+
+        // 2. Preserve the existing validation state, which is computed and stored on the target.
+        // A source built from a plain object will never have this.
+        if (existingMeta.validation && !sourceMeta.validation) {
+          newMeta.validation = existingMeta.validation;
+        }
+
+        // 3. Preserve component registrations, which only exist on the live target state.
+        if (existingMeta.components) {
+          newMeta.components = existingMeta.components;
+        }
+
+        target._meta = newMeta;
+      }
+      // --- END: CORRECTED METADATA MERGE ---
+
+      // 2. Handle the node's data (primitive, array, or object).
+      if (source._meta?.hasOwnProperty('value')) {
+        // Source is a primitive. Clear any old child properties from target.
+        for (const key in target) {
+          if (key !== '_meta') delete target[key];
+        }
+        return; // Done with this branch
+      }
+
+      // Synchronize the data structure based on the source.
+      const sourceKeys = new Set(
+        Object.keys(source).filter((k) => k !== '_meta')
+      );
+      const targetKeys = new Set(
+        Object.keys(target).filter((k) => k !== '_meta')
+      );
+
+      // Delete keys that are in the target but no longer in the source.
+      for (const key of targetKeys) {
+        if (!sourceKeys.has(key)) {
+          delete target[key];
+        }
+      }
 
+      // Recursively merge or add keys from the source.
+      for (const key of sourceKeys) {
+        const sourceValue = source[key];
+        const targetValue = target[key];
+        if (
+          targetValue &&
+          typeof targetValue === 'object' &&
+          sourceValue &&
+          typeof sourceValue === 'object'
+        ) {
+          deepMergeShadowNodes(targetValue, sourceValue); // Recurse for objects
+        } else {
+          target[key] = sourceValue; // Add new or replace primitive/node
+        }
+      }
+    }
+    // --- THIS IS YOUR ORIGINAL, CORRECT MAIN LOGIC ---
+    if (existingRoot) {
+      // Merge the new shadow state into the existing one
+      deepMergeShadowNodes(existingRoot, shadowState);
+      // Restore preserved metadata
+      if (!existingRoot._meta) existingRoot._meta = {};
+      Object.assign(existingRoot._meta, preservedMetadata);
+      shadowStateStore.set(storageKey, existingRoot);
+    } else {
+      // The logic for when no state exists yet
+      if (preservedMetadata && Object.keys(preservedMetadata).length > 0) {
+        if (!shadowState._meta) shadowState._meta = {};
+        Object.assign(shadowState._meta, preservedMetadata);
+      }
+      shadowStateStore.set(storageKey, shadowState);
+    }
+
+    // As your logs show, this part works. It runs AFTER the merge to apply schemas.
+    const options = get().getInitialOptions(key);
+    const hasSchema =
+      options?.validation?.zodSchemaV4 || options?.validation?.zodSchemaV3;
+    if (hasSchema) {
+      if (options.validation?.zodSchemaV4) {
+        updateShadowTypeInfo(key, options.validation.zodSchemaV4, 'zod4');
+      } else if (options.validation?.zodSchemaV3) {
+        updateShadowTypeInfo(key, options.validation.zodSchemaV3, 'zod3');
+      }
+    }
+
+    // Cleanup logic is restored
+    if (storageKey === key) {
+      shadowStateStore.delete(`[${key}`);
+    } else {
+      shadowStateStore.delete(key);
+    }
+  },
   initializeShadowState: (key: string, initialState: any) => {
     const existingRoot =
       shadowStateStore.get(key) || shadowStateStore.get(`[${key}`);
@@ -340,14 +924,29 @@ export const getGlobalStore = create<CogsGlobalState>((set, get) => ({
     shadowStateStore.delete(key);
     shadowStateStore.delete(`[${key}`);
 
-    const newRoot = buildShadowNode(initialState);
+    // Get all available schemas for this state
+    const options = get().getInitialOptions(key);
+    const syncSchemas = get().getInitialOptions('__syncSchemas');
+
+    const context: BuildContext = {
+      stateKey: key,
+      path: [],
+      schemas: {
+        sync: syncSchemas,
+        zodV4: options?.validation?.zodSchemaV4,
+        zodV3: options?.validation?.zodSchemaV3,
+      },
+    };
+
+    // Build with context so type info is stored
+    const newRoot = buildShadowNode(key, initialState, context);
+
     if (!newRoot._meta) newRoot._meta = {};
     Object.assign(newRoot._meta, preservedMetadata);
 
     const storageKey = Array.isArray(initialState) ? `[${key}` : key;
     shadowStateStore.set(storageKey, newRoot);
   },
-
   getShadowNode: (key: string, path: string[]): ShadowNode | undefined => {
     let current: any =
       shadowStateStore.get(key) || shadowStateStore.get(`[${key}`);
@@ -398,59 +997,75 @@ export const getGlobalStore = create<CogsGlobalState>((set, get) => ({
     if (!current._meta) {
       current._meta = {};
     }
+
     Object.assign(current._meta, newMetadata);
   },
+  getShadowValue: (key: string, path: string[], validArrayIds?: string[]) => {
+    const startNode = get().getShadowNode(key, path);
 
-  getShadowValue: (
-    key: string,
-    path: string[],
-    validArrayIds?: string[],
-    log?: boolean
-  ) => {
-    const node = get().getShadowNode(key, path);
+    // If the path is invalid or leads nowhere, return undefined immediately.
+    if (!startNode) {
+      return undefined;
+    }
 
-    if (node === null || node === undefined) return undefined;
+    // --- High-Performance Iterative Materializer ---
 
-    const nodeKeys = Object.keys(node);
+    // A single root object to hold the final, materialized result.
+    const rootResult: any = {};
 
-    const isPrimitiveWrapper =
-      Object.prototype.hasOwnProperty.call(node, 'value') &&
-      nodeKeys.every((k) => k === 'value' || k === '_meta');
+    // Stack to manage the traversal without recursion.
+    // Each item is [shadowNode, parentObjectInResult, keyToSetOnParent]
+    const stack: [ShadowNode, any, string | number][] = [
+      [startNode, rootResult, 'final'],
+    ];
 
-    if (isPrimitiveWrapper) {
-      return node.value;
-    }
+    while (stack.length > 0) {
+      const [currentNode, parentResult, resultKey] = stack.pop()!;
 
-    const isArrayNode =
-      node._meta &&
-      Object.prototype.hasOwnProperty.call(node._meta, 'arrayKeys');
-    if (isArrayNode) {
-      const keysToIterate =
-        validArrayIds !== undefined && validArrayIds.length > 0
-          ? validArrayIds
-          : node._meta!.arrayKeys!;
+      // 1. Handle primitive values
+      if (currentNode._meta?.hasOwnProperty('value')) {
+        parentResult[resultKey] = currentNode._meta.value;
+        continue; // Done with this branch
+      }
 
-      return keysToIterate.map((itemKey: string) =>
-        get().getShadowValue(key, [...path, itemKey])
-      );
-    }
+      // 2. Handle arrays
+      if (currentNode._meta?.arrayKeys) {
+        const keysToIterate = validArrayIds || currentNode._meta.arrayKeys;
+        const newArray: any[] = [];
+        parentResult[resultKey] = newArray;
+
+        // Push children onto the stack in reverse order to process them from 0 to N
+        for (let i = keysToIterate.length - 1; i >= 0; i--) {
+          const itemKey = keysToIterate[i]!;
+          if (currentNode[itemKey]) {
+            // The child's result will be placed at index `i` in `newArray`
+            stack.push([currentNode[itemKey], newArray, i]);
+          }
+        }
+        continue; // Done with this branch
+      }
+
+      // 3. Handle objects
+      const newObject: any = {};
+      parentResult[resultKey] = newObject;
 
-    const result: any = {};
-    for (const propKey of nodeKeys) {
-      if (propKey !== '_meta' && !propKey.startsWith('id:')) {
-        result[propKey] = get().getShadowValue(key, [...path, propKey]);
+      const objectKeys = Object.keys(currentNode);
+      // Push children onto the stack (order doesn't matter for objects)
+      for (const propKey of objectKeys) {
+        if (propKey !== '_meta') {
+          // The child's result will be set as a property on `newObject`
+          stack.push([currentNode[propKey], newObject, propKey]);
+        }
       }
     }
-    return result;
-  },
 
+    return rootResult.final;
+  },
   updateShadowAtPath: (key, path, newValue) => {
-    // NO MORE set() wrapper - direct mutation!
     const rootKey = shadowStateStore.has(`[${key}`) ? `[${key}` : key;
     let root = shadowStateStore.get(rootKey);
     if (!root) return;
 
-    // Navigate to parent without cloning
     let parentNode = root;
     for (let i = 0; i < path.length - 1; i++) {
       if (!parentNode[path[i]!]) {
@@ -458,72 +1073,141 @@ export const getGlobalStore = create<CogsGlobalState>((set, get) => ({
       }
       parentNode = parentNode[path[i]!];
     }
-
     const targetNode =
       path.length === 0 ? parentNode : parentNode[path[path.length - 1]!];
 
-    if (!targetNode) {
-      parentNode[path[path.length - 1]!] = buildShadowNode(newValue);
-      get().notifyPathSubscribers([key, ...path].join('.'), {
-        type: 'UPDATE',
-        newValue,
-      });
-      return;
-    }
-
-    function intelligentMerge(nodeToUpdate: any, plainValue: any) {
+    // This function is now defined inside to close over 'key' and 'path' for context
+    function intelligentMerge(
+      nodeToUpdate: any,
+      plainValue: any,
+      currentPath: string[]
+    ) {
+      // 1. Handle primitives (but NOT arrays)
       if (
         typeof plainValue !== 'object' ||
         plainValue === null ||
-        Array.isArray(plainValue)
+        plainValue instanceof Date
       ) {
-        const oldMeta = nodeToUpdate._meta;
-        // Clear existing properties
-        for (const key in nodeToUpdate) {
-          if (key !== '_meta') delete nodeToUpdate[key];
+        const oldMeta = nodeToUpdate._meta || {};
+        // Clear all child properties
+        for (const prop in nodeToUpdate) {
+          if (prop !== '_meta') delete nodeToUpdate[prop];
         }
-        const newNode = buildShadowNode(plainValue);
-        Object.assign(nodeToUpdate, newNode);
-        if (oldMeta) {
-          nodeToUpdate._meta = { ...oldMeta, ...(nodeToUpdate._meta || {}) };
+        // Set the new primitive value, preserving metadata
+        nodeToUpdate._meta = { ...oldMeta, value: plainValue };
+        return;
+      }
+
+      // 2. Handle Arrays INTELLIGENTLY
+      if (Array.isArray(plainValue)) {
+        // Ensure the target is a shadow array node
+        if (!nodeToUpdate._meta) nodeToUpdate._meta = {};
+        if (!nodeToUpdate._meta.arrayKeys) nodeToUpdate._meta.arrayKeys = [];
+
+        const existingKeys = nodeToUpdate._meta.arrayKeys;
+        const newValues = plainValue;
+
+        const updatedKeys: string[] = [];
+
+        // Merge existing items and add new items
+        for (let i = 0; i < newValues.length; i++) {
+          const newItemValue = newValues[i]!;
+          if (i < existingKeys.length) {
+            // Merge into existing item, preserving its key and metadata
+            const existingKey = existingKeys[i]!;
+            intelligentMerge(nodeToUpdate[existingKey], newItemValue, [
+              ...currentPath,
+              existingKey,
+            ]);
+            updatedKeys.push(existingKey);
+          } else {
+            // Add a new item
+            const newItemId = generateId(key);
+            const options = get().getInitialOptions(key);
+            // Build the new node WITH proper context to get schema info
+            const itemContext: BuildContext = {
+              stateKey: key,
+              path: [...currentPath, '0'], // Use '0' for array element schema lookup
+              schemas: {
+                zodV4: options?.validation?.zodSchemaV4,
+                zodV3: options?.validation?.zodSchemaV3,
+              },
+            };
+            nodeToUpdate[newItemId] = buildShadowNode(
+              key,
+              newItemValue,
+              itemContext
+            );
+            updatedKeys.push(newItemId);
+          }
+        }
+
+        // Remove deleted items
+        if (existingKeys.length > newValues.length) {
+          const keysToDelete = existingKeys.slice(newValues.length);
+          keysToDelete.forEach((keyToDelete: string) => {
+            delete nodeToUpdate[keyToDelete];
+          });
         }
+
+        // Update the keys array to reflect the new state
+        nodeToUpdate._meta.arrayKeys = updatedKeys;
         return;
       }
 
+      // 3. Handle Objects
       const plainValueKeys = new Set(Object.keys(plainValue));
+      if (nodeToUpdate._meta?.hasOwnProperty('value')) {
+        // transitioning from primitive to object, clear the value
+        delete nodeToUpdate._meta.value;
+      }
 
       for (const propKey of plainValueKeys) {
         const childValue = plainValue[propKey];
         if (nodeToUpdate[propKey]) {
-          intelligentMerge(nodeToUpdate[propKey], childValue);
+          intelligentMerge(nodeToUpdate[propKey], childValue, [
+            ...currentPath,
+            propKey,
+          ]);
         } else {
-          nodeToUpdate[propKey] = buildShadowNode(childValue);
+          const options = get().getInitialOptions(key);
+          const itemContext: BuildContext = {
+            stateKey: key,
+            path: [...currentPath, propKey],
+            schemas: {
+              zodV4: options?.validation?.zodSchemaV4,
+              zodV3: options?.validation?.zodSchemaV3,
+            },
+          };
+          nodeToUpdate[propKey] = buildShadowNode(key, childValue, itemContext);
         }
       }
 
+      // Delete keys that no longer exist
       for (const nodeKey in nodeToUpdate) {
         if (
           nodeKey === '_meta' ||
           !Object.prototype.hasOwnProperty.call(nodeToUpdate, nodeKey)
         )
           continue;
-
         if (!plainValueKeys.has(nodeKey)) {
           delete nodeToUpdate[nodeKey];
         }
       }
     }
 
-    intelligentMerge(targetNode, newValue);
+    if (!targetNode) {
+      parentNode[path[path.length - 1]!] = buildShadowNode(key, newValue); // Build fresh if no target
+    } else {
+      intelligentMerge(targetNode, newValue, path); // Use the new intelligent merge
+    }
 
     get().notifyPathSubscribers([key, ...path].join('.'), {
       type: 'UPDATE',
       newValue,
     });
   },
-
-  addItemsToArrayNode: (key, arrayPath, newItems, newKeys) => {
-    // Direct mutation - no cloning!
+  addItemsToArrayNode: (key, arrayPath, newItems) => {
     const rootKey = shadowStateStore.has(`[${key}`) ? `[${key}` : key;
     let root = shadowStateStore.get(rootKey);
     if (!root) {
@@ -531,7 +1215,6 @@ export const getGlobalStore = create<CogsGlobalState>((set, get) => ({
       return;
     }
 
-    // Navigate without cloning
     let current = root;
     for (const segment of arrayPath) {
       if (!current[segment]) {
@@ -540,23 +1223,20 @@ export const getGlobalStore = create<CogsGlobalState>((set, get) => ({
       current = current[segment];
     }
 
-    // Mutate directly
     Object.assign(current, newItems);
-    if (!current._meta) current._meta = {};
-    current._meta.arrayKeys = newKeys; // Direct assignment!
   },
-
-  insertShadowArrayElement: (key, arrayPath, newItem, index) => {
+  insertShadowArrayElement: (key, arrayPath, newItem, index, itemId) => {
     const arrayNode = get().getShadowNode(key, arrayPath);
     if (!arrayNode?._meta?.arrayKeys) {
-      console.error(
+      throw new Error(
         `Array not found at path: ${[key, ...arrayPath].join('.')}`
       );
-      return;
     }
+    console.log('OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO');
+    const newItemId = itemId || `${generateId(key)}`;
 
-    const newItemId = `id:${generateId()}`;
-    const itemsToAdd = { [newItemId]: buildShadowNode(newItem) };
+    // BUILD AND ADD the node directly - no need for addItemsToArrayNode
+    arrayNode[newItemId] = buildShadowNode(key, newItem);
 
     // Mutate the array directly
     const currentKeys = arrayNode._meta.arrayKeys;
@@ -566,13 +1246,12 @@ export const getGlobalStore = create<CogsGlobalState>((set, get) => ({
         : currentKeys.length;
 
     if (insertionPoint >= currentKeys.length) {
-      currentKeys.push(newItemId); // O(1)
+      currentKeys.push(newItemId);
     } else {
-      currentKeys.splice(insertionPoint, 0, newItemId); // O(n) only for middle
+      currentKeys.splice(insertionPoint, 0, newItemId);
     }
 
-    // Pass the mutated array
-    get().addItemsToArrayNode(key, arrayPath, itemsToAdd, currentKeys);
+    // Skip addItemsToArrayNode entirely - we already did everything it does!
 
     const arrayKey = [key, ...arrayPath].join('.');
     get().notifyPathSubscribers(arrayKey, {
@@ -581,6 +1260,8 @@ export const getGlobalStore = create<CogsGlobalState>((set, get) => ({
       itemKey: `${arrayKey}.${newItemId}`,
       index: insertionPoint,
     });
+
+    return newItemId;
   },
 
   insertManyShadowArrayElements: (key, arrayPath, newItems, index) => {
@@ -596,16 +1277,16 @@ export const getGlobalStore = create<CogsGlobalState>((set, get) => ({
       return;
     }
 
-    const itemsToAdd: Record<string, any> = {};
     const newIds: string[] = [];
 
+    // Build and add items directly
     newItems.forEach((item) => {
-      const newItemId = `id:${generateId()}`;
+      const newItemId = `${generateId(key)}`;
       newIds.push(newItemId);
-      itemsToAdd[newItemId] = buildShadowNode(item);
+      arrayNode[newItemId] = buildShadowNode(key, item); // ADD DIRECTLY!
     });
 
-    // Mutate directly
+    // Mutate the keys array
     const currentKeys = arrayNode._meta.arrayKeys;
     const insertionPoint =
       index !== undefined && index >= 0 && index <= currentKeys.length
@@ -613,12 +1294,12 @@ export const getGlobalStore = create<CogsGlobalState>((set, get) => ({
         : currentKeys.length;
 
     if (insertionPoint >= currentKeys.length) {
-      currentKeys.push(...newIds); // O(k) where k is items being added
+      currentKeys.push(...newIds);
     } else {
-      currentKeys.splice(insertionPoint, 0, ...newIds); // O(n + k)
+      currentKeys.splice(insertionPoint, 0, ...newIds);
     }
 
-    get().addItemsToArrayNode(key, arrayPath, itemsToAdd, currentKeys);
+    // NO addItemsToArrayNode call needed!
 
     const arrayKey = [key, ...arrayPath].join('.');
     get().notifyPathSubscribers(arrayKey, {
@@ -709,25 +1390,36 @@ export const getGlobalStore = create<CogsGlobalState>((set, get) => ({
   },
 
   markAsDirty: (key, path, options = { bubble: true }) => {
-    const setDirtyOnPath = (pathToMark: string[]) => {
-      const node = get().getShadowNode(key, pathToMark);
-      if (node?._meta?.isDirty) {
-        return true;
-      }
-      get().setShadowMetadata(key, pathToMark, { isDirty: true });
-      return false;
-    };
+    // Start at the root node once.
+    let rootNode = get().getShadowNode(key, []);
+    if (!rootNode) return;
 
-    setDirtyOnPath(path);
+    // Navigate to the target node once.
+    let currentNode = rootNode;
+    for (const segment of path) {
+      currentNode = currentNode[segment];
+      if (!currentNode) return; // Path doesn't exist, nothing to mark.
+    }
 
-    if (options.bubble) {
-      let parentPath = [...path];
-      while (parentPath.length > 0) {
-        parentPath.pop();
-        if (setDirtyOnPath(parentPath)) {
-          break;
-        }
+    // Mark the target node as dirty.
+    if (!currentNode._meta) currentNode._meta = {};
+    currentNode._meta.isDirty = true;
+
+    // If bubbling is disabled, we are done.
+    if (!options.bubble) return;
+
+    // Efficiently bubble up using the path segments.
+    let parentNode = rootNode;
+    for (let i = 0; i < path.length; i++) {
+      // The current node in the loop is the parent of the next one.
+      if (parentNode._meta?.isDirty) {
+        // Optimization: If a parent is already dirty, all of its ancestors are too.
+        // We can stop bubbling immediately.
+        return;
       }
+      if (!parentNode._meta) parentNode._meta = {};
+      parentNode._meta.isDirty = true;
+      parentNode = parentNode[path[i]!];
     }
   },