cogsbox-state 0.5.463 → 0.5.465

package/src/store.ts

@@ -3,17 +3,12 @@ import { ulid } from 'ulid';
 import type {
   OptionsType,
   ReactivityType,
-  StateKeys,
   SyncInfo,
   UpdateTypeDetail,
 } from './CogsState.js';
 
 import { startTransition, type ReactNode } from 'react';
 
-type StateUpdater<StateValue> =
-  | StateValue
-  | ((prevValue: StateValue) => StateValue);
-
 export type FreshValuesObject = {
   pathsToValues?: string[];
   prevValue?: any;
@@ -21,9 +16,6 @@ export type FreshValuesObject = {
   timeStamp: number;
 };
 
-type SyncLogType = {
-  timeStamp: number;
-};
 type StateValue = any;
 
 export type TrieNode = {
@@ -89,16 +81,35 @@ export type ComponentsType = {
     }
   >;
 };
+
+export type ValidationStatus =
+  | 'NOT_VALIDATED' // Never run
+  | 'VALIDATING' // Currently running
+  | 'VALID' // Passed
+  | 'INVALID'; // Failed
+
+export type ValidationError = {
+  source: 'client' | 'sync_engine' | 'api';
+  message: string;
+  severity: 'warning' | 'error'; // warning = gentle, error = blocking
+  code?: string; // Optional error code
+};
+
+export type ValidationState = {
+  status: ValidationStatus;
+  errors: ValidationError[];
+  lastValidated?: number;
+  validatedValue?: any; // Value when last validated
+};
+
+// This is the new definition for the metadata object
 export type ShadowMetadata = {
   id?: string;
-
   stateSource?: 'default' | 'server' | 'localStorage';
   lastServerSync?: number;
   isDirty?: boolean;
   baseServerState?: any;
-
   arrayKeys?: string[];
-
   fields?: Record<string, any>;
   virtualizer?: {
     itemHeight?: number;
@@ -106,14 +117,12 @@ export type ShadowMetadata = {
   };
   syncInfo?: { status: string };
   validation?: ValidationState;
+  features?: {
+    syncEnabled: boolean;
+    validationEnabled: boolean;
+    localStorageEnabled: boolean;
+  };
   lastUpdated?: number;
-  value?: any;
-  classSignals?: Array<{
-    id: string;
-    effect: string;
-    lastClasses: string;
-    deps: any[];
-  }>;
   signals?: Array<{
     instanceId: string;
     parentId: string;
@@ -125,12 +134,7 @@ export type ShadowMetadata = {
     path: string[];
     componentId: string;
     meta?: any;
-    mapFn: (
-      setter: any,
-      index: number,
-
-      arraySetter: any
-    ) => ReactNode;
+    mapFn: (setter: any, index: number, arraySetter: any) => ReactNode;
     containerRef: HTMLDivElement | null;
     rebuildStateShape: any;
   }>;
@@ -152,36 +156,48 @@ export type ShadowMetadata = {
   >;
 } & ComponentsType;
 
-export type ValidationStatus =
-  | 'PRISTINE' // Untouched, matches initial state.
-  | 'DIRTY' // Changed, but no validation run yet.
-  | 'VALID_LIVE' // Valid while typing.
-  | 'INVALID_LIVE' // Gentle error during typing.
-  | 'VALIDATION_FAILED' // Hard error on blur/submit.
-  | 'VALID_PENDING_SYNC' // Passed validation, ready for sync.
-  | 'SYNCING' // Actively being sent to the server.
-  | 'SYNCED' // Server confirmed success.
-  | 'SYNC_FAILED'; // Server rejected the data.
-
-export type ValidationState = {
-  status: ValidationStatus;
-  message?: string;
-  lastValidated?: number;
-  validatedValue?: any;
+// The shadow node itself can have a value and the metadata object.
+type ShadowNode = {
+  value?: any;
+  _meta?: ShadowMetadata;
+  [key: string]: any; // For nested data properties
 };
-export type CogsEvent =
-  | { type: 'INSERT'; path: string; itemKey: string; index: number }
-  | { type: 'REMOVE'; path: string; itemKey: string }
-  | { type: 'UPDATE'; path: string; newValue: any }
-  | { type: 'ITEMHEIGHT'; itemKey: string; height: number }
-  | { type: 'RELOAD'; path: string };
+
 export type CogsGlobalState = {
-  updateQueue: Set<() => void>;
-  isFlushScheduled: boolean;
+  // NEW shadow store
+  shadowStateStore: Map<string, ShadowNode>; // Changed ShadowMetadata to ShadowNode
+  setTransformCache: (
+    key: string,
+    path: string[],
+    cacheKey: string,
+    cacheData: any
+  ) => void;
+  // NEW functions
+  initializeShadowState: (key: string, initialState: any) => void;
 
-  flushUpdates: () => void;
+  // REFACTORED: getShadowNode gets the whole object (data + _meta)
+  getShadowNode: (key: string, path: string[]) => ShadowNode | undefined;
+  // REFACTORED: getShadowMetadata now returns just the _meta field
+  getShadowMetadata: (
+    key: string,
+    path: string[]
+  ) => ShadowMetadata | undefined;
 
-  // --- Shadow State and Subscription System ---
+  setShadowMetadata: (key: string, path: string[], metadata: any) => void;
+  getShadowValue: (
+    key: string,
+    path: string[],
+    validArrayIds?: string[],
+    log?: boolean
+  ) => any;
+  updateShadowAtPath: (key: string, path: string[], newValue: any) => void;
+  insertShadowArrayElement: (
+    key: string,
+    arrayPath: string[],
+    newItem: any,
+    index?: number
+  ) => void;
+  removeShadowArrayElement: (key: string, itemPath: string[]) => void;
   registerComponent: (
     stateKey: string,
     componentId: string,
@@ -193,7 +209,6 @@ export type CogsGlobalState = {
     dependencyPath: string[],
     fullComponentId: string
   ) => void;
-  shadowStateStore: Map<string, ShadowMetadata>;
 
   markAsDirty: (
     key: string,
@@ -201,35 +216,6 @@ export type CogsGlobalState = {
     options: { bubble: boolean }
   ) => void;
   // These method signatures stay the same
-  initializeShadowState: (key: string, initialState: any) => void;
-  updateShadowAtPath: (key: string, path: string[], newValue: any) => void;
-  insertShadowArrayElement: (
-    key: string,
-    arrayPath: string[],
-    newItem: any
-  ) => void;
-  removeShadowArrayElement: (key: string, arrayPath: string[]) => void;
-  getShadowValue: (
-    key: string,
-
-    validArrayIds?: string[]
-  ) => any;
-
-  getShadowMetadata: (
-    key: string,
-    path: string[]
-  ) => ShadowMetadata | undefined;
-  setShadowMetadata: (
-    key: string,
-    path: string[],
-    metadata: Omit<ShadowMetadata, 'id'>
-  ) => void;
-  setTransformCache: (
-    key: string,
-    path: string[],
-    cacheKey: string,
-    cacheData: any
-  ) => void;
 
   pathSubscribers: Map<string, Set<(newValue: any) => void>>;
   subscribeToPath: (
@@ -268,655 +254,565 @@ export type CogsGlobalState = {
 
   stateLog: Map<string, Map<string, UpdateTypeDetail>>;
   syncInfoStore: Map<string, SyncInfo>;
-  addStateLog: (key: string, update: UpdateTypeDetail) => void;
+  addStateLog: (updates: UpdateTypeDetail[]) => void;
 
   setSyncInfo: (key: string, syncInfo: SyncInfo) => void;
   getSyncInfo: (key: string) => SyncInfo | null;
 };
-const isSimpleObject = (value: any): boolean => {
-  // Most common cases first
-  if (value === null || typeof value !== 'object') return false;
 
-  // Arrays are simple objects
-  if (Array.isArray(value)) return true;
+// ✅ CHANGE 1: `METADATA_KEYS` now only contains `_meta` and `value`.
+// The other keys are now properties of the `ShadowMetadata` type.
+export const METADATA_KEYS = new Set(['_meta', 'value']);
+
+/**
+ * The single source of truth for converting a regular JS value/object
+ * into the shadow state tree format with the new `_meta` structure.
+ */
+// ✅ CHANGE 2: `buildShadowNode` now creates the `_meta` field.
+export function buildShadowNode(value: any): ShadowNode {
+  // Primitives and null are wrapped.
+  if (value === null || typeof value !== 'object') {
+    return { value };
+  }
+
+  // Arrays are converted to an object with id-keyed children and metadata in `_meta`.
+  if (Array.isArray(value)) {
+    const arrayNode: ShadowNode = { _meta: { arrayKeys: [] } }; // Initialize with _meta and arrayKeys
+    const idKeys: string[] = [];
+    value.forEach((item) => {
+      const itemId = `id:${ulid()}`;
+      arrayNode[itemId] = buildShadowNode(item); // Recurse for each item
+      idKeys.push(itemId);
+    });
+    arrayNode._meta!.arrayKeys = idKeys; // Set the final ordered keys
+    return arrayNode;
+  }
+
+  // Plain objects are recursively processed.
+  if (value.constructor === Object) {
+    const objectNode: ShadowNode = { _meta: {} }; // Initialize with an empty meta object
+    for (const key in value) {
+      if (Object.prototype.hasOwnProperty.call(value, key)) {
+        objectNode[key] = buildShadowNode(value[key]); // Recurse for each property
+      }
+    }
+    return objectNode;
+  }
 
-  // Plain objects second most common
-  if (value.constructor === Object) return true;
+  // Fallback for other object types (Date, etc.) - treat them as primitives.
+  return { value };
+}
 
-  // Everything else is not simple
-  return false;
-};
 export const getGlobalStore = create<CogsGlobalState>((set, get) => ({
-  updateQueue: new Set<() => void>(),
-  // A flag to ensure we only schedule the flush once per event-loop tick.
-  isFlushScheduled: false,
+  shadowStateStore: new Map<string, ShadowNode>(),
 
-  // This function is called by queueMicrotask to execute all queued updates.
-  flushUpdates: () => {
-    const { updateQueue } = get();
-
-    if (updateQueue.size > 0) {
-      startTransition(() => {
-        updateQueue.forEach((updateFn) => updateFn());
-      });
+  setTransformCache: (
+    key: string,
+    path: string[],
+    cacheKey: string,
+    cacheData: any
+  ) => {
+    // This function now uses setShadowMetadata which correctly places the data.
+    const metadata = get().getShadowMetadata(key, path) || {};
+    if (!metadata.transformCaches) {
+      metadata.transformCaches = new Map();
     }
-
-    // Clear the queue and reset the flag for the next event loop tick.
-    set({ updateQueue: new Set(), isFlushScheduled: false });
+    metadata.transformCaches.set(cacheKey, cacheData);
+    get().setShadowMetadata(key, path, {
+      transformCaches: metadata.transformCaches,
+    });
   },
-  addPathComponent: (stateKey, dependencyPath, fullComponentId) => {
+
+  initializeShadowState: (key: string, initialState: any) => {
     set((state) => {
       const newShadowStore = new Map(state.shadowStateStore);
-      const dependencyKey = [stateKey, ...dependencyPath].join('.');
-
-      // --- Part 1: Update the path's own metadata ---
-      const pathMeta = newShadowStore.get(dependencyKey) || {};
-      // Create a *new* Set to ensure immutability
-      const pathComponents = new Set(pathMeta.pathComponents);
-      pathComponents.add(fullComponentId);
-      // Update the metadata for the specific path
-      newShadowStore.set(dependencyKey, { ...pathMeta, pathComponents });
+      const existingRoot =
+        newShadowStore.get(key) || newShadowStore.get(`[${key}`);
+      let preservedMetadata: Partial<ShadowMetadata> = {};
+
+      if (existingRoot?._meta) {
+        const {
+          components,
+          features,
+          lastServerSync,
+          stateSource,
+          baseServerState,
+        } = 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;
+      }
 
-      // --- Part 2: Update the component's own list of paths ---
-      const rootMeta = newShadowStore.get(stateKey) || {};
-      const component = rootMeta.components?.get(fullComponentId);
+      newShadowStore.delete(key);
+      newShadowStore.delete(`[${key}`);
 
-      // If the component exists, update its `paths` set immutably
-      if (component) {
-        const newPaths = new Set(component.paths);
-        newPaths.add(dependencyKey);
-
-        const newComponentRegistration = { ...component, paths: newPaths };
-        const newComponentsMap = new Map(rootMeta.components);
-        newComponentsMap.set(fullComponentId, newComponentRegistration);
+      const newRoot = buildShadowNode(initialState);
+      // Ensure _meta exists before assigning to it
+      if (!newRoot._meta) newRoot._meta = {};
+      Object.assign(newRoot._meta, preservedMetadata);
 
-        // Update the root metadata with the new components map
-        newShadowStore.set(stateKey, {
-          ...rootMeta,
-          components: newComponentsMap,
-        });
-      }
+      const storageKey = Array.isArray(initialState) ? `[${key}` : key;
+      newShadowStore.set(storageKey, newRoot);
 
-      // Return the final, updated state
-      return { shadowStateStore: newShadowStore };
-    });
-  },
-  registerComponent: (stateKey, fullComponentId, registration) => {
-    set((state) => {
-      const newShadowStore = new Map(state.shadowStateStore);
-      const rootMeta = newShadowStore.get(stateKey) || {};
-      const components = new Map(rootMeta.components);
-      components.set(fullComponentId, registration);
-      newShadowStore.set(stateKey, { ...rootMeta, components });
       return { shadowStateStore: newShadowStore };
     });
   },
 
-  unregisterComponent: (stateKey, fullComponentId) => {
-    set((state) => {
-      const newShadowStore = new Map(state.shadowStateStore);
-      const rootMeta = newShadowStore.get(stateKey);
-      if (!rootMeta?.components) {
-        return state; // Return original state, no change needed
-      }
+  // ✅ NEW HELPER: Gets the entire node (data and metadata).
+  getShadowNode: (key: string, path: string[]): ShadowNode | undefined => {
+    const store = get().shadowStateStore;
+    let current: any = store.get(key) || store.get(`[${key}`);
 
-      const components = new Map(rootMeta.components);
-      const wasDeleted = components.delete(fullComponentId);
+    if (!current) return undefined;
+    if (path.length === 0) return current;
 
-      // Only update state if something was actually deleted
-      if (wasDeleted) {
-        newShadowStore.set(stateKey, { ...rootMeta, components });
-        return { shadowStateStore: newShadowStore };
-      }
+    for (const segment of path) {
+      if (typeof current !== 'object' || current === null) return undefined;
+      current = current[segment];
+      if (current === undefined) return undefined;
+    }
+    return current;
+  },
 
-      return state; // Nothing changed
-    });
+  // ✅ REFACTORED: Returns only the `_meta` part of a node.
+  getShadowMetadata: (
+    key: string,
+    path: string[]
+  ): ShadowMetadata | undefined => {
+    const node = get().getShadowNode(key, path);
+    return node?._meta;
   },
-  markAsDirty: (key: string, path: string[], options = { bubble: true }) => {
-    const { shadowStateStore } = get();
-    const updates = new Map<string, ShadowMetadata>();
 
-    const setDirty = (currentPath: string[]) => {
-      const fullKey = [key, ...currentPath].join('.');
-      const meta = shadowStateStore.get(fullKey) || {};
+  // ✅ REFACTORED: Sets data within the `_meta` object.
+  setShadowMetadata: (
+    key: string,
+    path: string[],
+    newMetadata: Partial<ShadowMetadata>
+  ) => {
+    set((state) => {
+      const newStore = new Map(state.shadowStateStore);
+      const rootKey = newStore.has(`[${key}`) ? `[${key}` : key;
+      let root = newStore.get(rootKey);
 
-      // If already dirty, no need to update
-      if (meta.isDirty === true) {
-        return true; // Return true to indicate parent is dirty
+      if (!root) {
+        root = {};
+        newStore.set(rootKey, root);
       }
 
-      updates.set(fullKey, { ...meta, isDirty: true });
-      return false; // Not previously dirty
-    };
-
-    // Mark the target path
-    setDirty(path);
+      const clonedRoot: any = { ...root };
+      newStore.set(rootKey, clonedRoot);
 
-    // Bubble up if requested
-    if (options.bubble) {
-      let parentPath = [...path];
-      while (parentPath.length > 0) {
-        parentPath.pop();
-        const wasDirty = setDirty(parentPath);
-        if (wasDirty) {
-          break; // Stop bubbling if parent was already dirty
-        }
+      let current = clonedRoot;
+      for (const segment of path) {
+        const nextNode = current[segment] || {};
+        current[segment] = { ...nextNode }; // Clone for immutability
+        current = current[segment];
       }
-    }
 
-    // Apply all updates at once
-    if (updates.size > 0) {
-      set((state) => {
-        updates.forEach((meta, key) => {
-          state.shadowStateStore.set(key, meta);
-        });
-        return state;
-      });
-    }
-  },
-  serverStateUpdates: new Map(),
-  setServerStateUpdate: (key, serverState) => {
-    set((state) => {
-      const newMap = new Map(state.serverStateUpdates);
-      newMap.set(key, serverState);
-      return { serverStateUpdates: newMap };
-    });
+      // Ensure _meta object exists and merge the new metadata into it
+      current._meta = { ...(current._meta || {}), ...newMetadata };
 
-    // Notify all subscribers for this key
-    get().notifyPathSubscribers(key, {
-      type: 'SERVER_STATE_UPDATE',
-      serverState,
+      return { shadowStateStore: newStore };
     });
   },
-  shadowStateStore: new Map(),
-  getShadowNode: (key: string) => get().shadowStateStore.get(key),
-  pathSubscribers: new Map<string, Set<(newValue: any) => void>>(),
+  getShadowValue: (
+    key: string,
+    path: string[],
+    validArrayIds?: string[],
+    log?: boolean
+  ) => {
+    const node = get().getShadowNode(key, path);
 
-  subscribeToPath: (path, callback) => {
-    const subscribers = get().pathSubscribers;
-    const subsForPath = subscribers.get(path) || new Set();
-    subsForPath.add(callback);
-    subscribers.set(path, subsForPath);
+    if (node === null || node === undefined) return undefined;
 
-    return () => {
-      const currentSubs = get().pathSubscribers.get(path);
-      if (currentSubs) {
-        currentSubs.delete(callback);
-        if (currentSubs.size === 0) {
-          get().pathSubscribers.delete(path);
-        }
-      }
-    };
-  },
+    const nodeKeys = Object.keys(node);
 
-  notifyPathSubscribers: (updatedPath, newValue) => {
-    const subscribers = get().pathSubscribers;
-    const subs = subscribers.get(updatedPath);
+    // ✅ FIX: A node is a primitive wrapper ONLY if its keys are 'value' and/or '_meta'.
+    // This prevents objects in your data that happen to have a "value" property from being
+    // incorrectly treated as wrappers.
+    const isPrimitiveWrapper =
+      Object.prototype.hasOwnProperty.call(node, 'value') &&
+      nodeKeys.every((k) => k === 'value' || k === '_meta');
 
-    if (subs) {
-      subs.forEach((callback) => callback(newValue));
+    if (isPrimitiveWrapper) {
+      return node.value;
     }
-  },
 
-  initializeShadowState: (key: string, initialState: any) => {
-    set((state) => {
-      // 1. Make a copy of the current store to modify it
-      const newShadowStore = new Map(state.shadowStateStore);
-      console.log('initializeShadowState');
-      // 2. PRESERVE the existing components map before doing anything else
-      const existingRootMeta = newShadowStore.get(key);
-      const preservedComponents = existingRootMeta?.components;
-
-      // 3. Wipe all old shadow entries for this state key
-      const prefixToDelete = key + '.';
-      for (const k of Array.from(newShadowStore.keys())) {
-        if (k === key || k.startsWith(prefixToDelete)) {
-          newShadowStore.delete(k);
-        }
-      }
+    // Array Check (This part is correct)
+    const isArrayNode =
+      node._meta &&
+      Object.prototype.hasOwnProperty.call(node._meta, 'arrayKeys');
+    if (isArrayNode) {
+      const keysToIterate =
+        validArrayIds !== undefined && validArrayIds.length > 0
+          ? validArrayIds
+          : node._meta!.arrayKeys!;
+
+      return keysToIterate.map((itemKey: string) =>
+        get().getShadowValue(key, [...path, itemKey])
+      );
+    }
 
-      // 4. Run your original logic to rebuild the state tree from scratch
-      const processValue = (value: any, path: string[]) => {
-        const nodeKey = [key, ...path].join('.');
-
-        if (Array.isArray(value)) {
-          const childIds: string[] = [];
-          value.forEach(() => {
-            const itemId = `id:${ulid()}`;
-            childIds.push(nodeKey + '.' + itemId);
-          });
-          newShadowStore.set(nodeKey, { arrayKeys: childIds });
-          value.forEach((item, index) => {
-            const itemId = childIds[index]!.split('.').pop();
-            processValue(item, [...path!, itemId!]);
-          });
-        } else if (isSimpleObject(value)) {
-          const fields = Object.fromEntries(
-            Object.keys(value).map((k) => [k, nodeKey + '.' + k])
-          );
-          newShadowStore.set(nodeKey, { fields });
-          Object.keys(value).forEach((k) => {
-            processValue(value[k], [...path, k]);
-          });
-        } else {
-          newShadowStore.set(nodeKey, { value });
-        }
-      };
-      processValue(initialState, []);
-
-      // 5. RESTORE the preserved components map onto the new root metadata
-      if (preservedComponents) {
-        const newRootMeta = newShadowStore.get(key) || {};
-        newShadowStore.set(key, {
-          ...newRootMeta,
-          components: preservedComponents,
-        });
+    // Object Reconstruction (This part is also correct)
+    const result: any = {};
+    for (const propKey of nodeKeys) {
+      // We correctly ignore metadata and array item keys here.
+      if (propKey !== '_meta' && !propKey.startsWith('id:')) {
+        result[propKey] = get().getShadowValue(key, [...path, propKey]);
       }
-
-      // 6. Return the completely updated state
-      return { shadowStateStore: newShadowStore };
-    });
+    }
+    return result;
   },
 
-  getShadowValue: (fullKey: string, validArrayIds?: string[]) => {
-    const memo = new Map<string, any>();
-    const reconstruct = (keyToBuild: string, ids?: string[]): any => {
-      if (memo.has(keyToBuild)) {
-        return memo.get(keyToBuild);
-      }
-
-      const shadowMeta = get().shadowStateStore.get(keyToBuild);
-      if (!shadowMeta) {
-        return undefined;
-      }
-
-      if (shadowMeta.value !== undefined) {
-        return shadowMeta.value;
-      }
-
-      let result: any; // The value we are about to build.
-
-      if (shadowMeta.arrayKeys) {
-        const keys = ids ?? shadowMeta.arrayKeys;
-        result = [];
-        memo.set(keyToBuild, result);
-        keys.forEach((itemKey) => {
-          result.push(reconstruct(itemKey));
-        });
-      } else if (shadowMeta.fields) {
-        result = {};
-        memo.set(keyToBuild, result);
-        Object.entries(shadowMeta.fields).forEach(([key, fieldPath]) => {
-          result[key] = reconstruct(fieldPath as string);
-        });
+  // ✅ REFACTORED: Correctly preserves `_meta` on updates.
+  updateShadowAtPath: (key, path, newValue) => {
+    set((state) => {
+      const newStore = new Map(state.shadowStateStore);
+      const rootKey = newStore.has(`[${key}`) ? `[${key}` : key;
+      let root = newStore.get(rootKey);
+
+      if (!root) return state;
+
+      const clonedRoot: any = { ...root };
+      newStore.set(rootKey, clonedRoot);
+
+      if (path.length === 0) {
+        const newRootStructure = buildShadowNode(newValue);
+        // Preserve the top-level metadata
+        if (clonedRoot._meta) {
+          newRootStructure._meta = {
+            ...(newRootStructure._meta || {}),
+            ...clonedRoot._meta,
+          };
+        }
+        newStore.set(rootKey, newRootStructure);
       } else {
-        result = undefined;
-      }
+        let current = clonedRoot;
+        const parentPath = path.slice(0, -1);
+        for (const segment of parentPath) {
+          current[segment] = { ...current[segment] };
+          current = current[segment];
+        }
 
-      // Return the final, fully populated result.
-      return result;
-    };
+        const lastSegment = path[path.length - 1]!;
+        const existingNode = current[lastSegment] || {};
+        const newNodeStructure = buildShadowNode(newValue);
 
-    // Start the process by calling the inner function on the root key.
-    return reconstruct(fullKey, validArrayIds);
-  },
-  getShadowMetadata: (key: string, path: string[]) => {
-    const fullKey = [key, ...path].join('.');
+        // This merge is critical: it preserves existing metadata during an update.
+        if (existingNode._meta) {
+          newNodeStructure._meta = {
+            ...(newNodeStructure._meta || {}),
+            ...existingNode._meta,
+          };
+        }
+        current[lastSegment] = newNodeStructure;
+      }
 
-    return get().shadowStateStore.get(fullKey);
+      get().notifyPathSubscribers([key, ...path].join('.'), {
+        type: 'UPDATE',
+        newValue,
+      });
+      return { shadowStateStore: newStore };
+    });
   },
 
-  setShadowMetadata: (key, path, metadata) => {
-    const fullKey = [key, ...path].join('.');
-    const existingMeta = get().shadowStateStore.get(fullKey);
-
-    // --- THIS IS THE TRAP ---
-    // If the existing metadata HAS a components map, but the NEW metadata DOES NOT,
-    // it means we are about to wipe it out. This is the bug.
-    if (existingMeta?.components && !metadata.components) {
-      console.group(
-        '%c🚨 RACE CONDITION DETECTED! 🚨',
-        'color: red; font-size: 18px; font-weight: bold;'
-      );
+  // ✅ REFACTORED: Works with `_meta.arrayKeys`.
+  insertShadowArrayElement: (key, arrayPath, newItem, index) => {
+    const arrayNode = get().getShadowNode(key, arrayPath);
+    if (!arrayNode?._meta?.arrayKeys) {
       console.error(
-        `An overwrite is about to happen on stateKey: "${key}" at path: [${path.join(', ')}]`
-      );
-      console.log(
-        'The EXISTING metadata had a components map:',
-        existingMeta.components
-      );
-      console.log(
-        'The NEW metadata is trying to save WITHOUT a components map:',
-        metadata
+        `Array not found at path: ${[key, ...arrayPath].join('.')}`
       );
-      console.log(
-        '%cStack trace to the function that caused this overwrite:',
-        'font-weight: bold;'
-      );
-      console.trace(); // This prints the call stack, leading you to the bad code.
-      console.groupEnd();
+      return;
     }
-    // --- END OF TRAP ---
 
-    const newShadowStore = new Map(get().shadowStateStore);
-    const finalMeta = { ...(existingMeta || {}), ...metadata };
-    newShadowStore.set(fullKey, finalMeta);
-    set({ shadowStateStore: newShadowStore });
-  },
-  setTransformCache: (
-    key: string,
-    path: string[],
-    cacheKey: string,
-    cacheData: any
-  ) => {
-    const fullKey = [key, ...path].join('.');
-    const newShadowStore = new Map(get().shadowStateStore);
-    const existing = newShadowStore.get(fullKey) || {};
+    const newItemId = `id:${ulid()}`;
+    const newItemNode = buildShadowNode(newItem);
+
+    // Update the `arrayKeys` in the metadata
+    const currentKeys = arrayNode._meta.arrayKeys;
+    const newKeys = [...currentKeys];
+    if (index !== undefined && index >= 0 && index <= newKeys.length) {
+      newKeys.splice(index, 0, newItemId);
+    } else {
+      newKeys.push(newItemId);
+    }
 
-    // Initialize transformCaches if it doesn't exist
-    if (!existing.transformCaches) {
-      existing.transformCaches = new Map();
+    // Update transform caches if they exist
+    if (arrayNode._meta.transformCaches) {
+      arrayNode._meta.transformCaches.forEach((cache) => {
+        if (cache.validIds && Array.isArray(cache.validIds)) {
+          const matchesFilters = cache.transforms.every((transform) =>
+            transform.type === 'filter' ? transform.fn(newItem) : true
+          );
+          if (matchesFilters) {
+            cache.validIds = [...cache.validIds];
+            if (index !== undefined) {
+              cache.validIds.splice(index, 0, newItemId);
+            } else {
+              cache.validIds.push(newItemId);
+            }
+          }
+        }
+      });
     }
 
-    // Update just the specific cache entry
-    existing.transformCaches.set(cacheKey, cacheData);
+    // Directly set the new item and updated metadata on the node before setting state
+    arrayNode[newItemId] = newItemNode;
+    arrayNode._meta.arrayKeys = newKeys;
 
-    // Update shadow store WITHOUT notifying path subscribers
-    newShadowStore.set(fullKey, existing);
-    set({ shadowStateStore: newShadowStore });
+    get().setShadowMetadata(key, arrayPath, { arrayKeys: newKeys });
 
-    // Don't call notifyPathSubscribers here - cache updates shouldn't trigger renders
-  },
-  insertShadowArrayElement: (
-    key: string,
-    arrayPath: string[],
-    newItem: any
-  ) => {
-    const newShadowStore = new Map(get().shadowStateStore);
+    // Trigger notifications
     const arrayKey = [key, ...arrayPath].join('.');
-    const parentMeta = newShadowStore.get(arrayKey);
-
-    if (!parentMeta || !parentMeta.arrayKeys) return;
-
-    const newItemId = `id:${ulid()}`;
-    const fullItemKey = arrayKey + '.' + newItemId;
-
-    // Just add to the end (or at a specific index if provided)
-    const newArrayKeys = [...parentMeta.arrayKeys];
-    newArrayKeys.push(fullItemKey); // Or use splice if you have an index
-    newShadowStore.set(arrayKey, { ...parentMeta, arrayKeys: newArrayKeys });
-
-    // Process the new item - but use the correct logic
-    const processNewItem = (value: any, path: string[]) => {
-      const nodeKey = [key, ...path].join('.');
-
-      if (Array.isArray(value)) {
-        // Handle arrays...
-      } else if (typeof value === 'object' && value !== null) {
-        // Create fields mapping
-        const fields = Object.fromEntries(
-          Object.keys(value).map((k) => [k, nodeKey + '.' + k])
-        );
-        newShadowStore.set(nodeKey, { fields });
-
-        // Process each field
-        Object.entries(value).forEach(([k, v]) => {
-          processNewItem(v, [...path, k]);
-        });
-      } else {
-        // Primitive value
-        newShadowStore.set(nodeKey, { value });
-      }
-    };
-
-    processNewItem(newItem, [...arrayPath, newItemId]);
-    set({ shadowStateStore: newShadowStore });
-
     get().notifyPathSubscribers(arrayKey, {
       type: 'INSERT',
       path: arrayKey,
-      itemKey: fullItemKey,
+      itemKey: `${arrayKey}.${newItemId}`,
+      index: index ?? newKeys.length - 1,
     });
   },
-  removeShadowArrayElement: (key: string, itemPath: string[]) => {
-    const newShadowStore = new Map(get().shadowStateStore);
 
-    // Get the full item key (e.g., "stateKey.products.id:xxx")
-    const itemKey = [key, ...itemPath].join('.');
+  // ✅ REFACTORED: Works with `_meta.arrayKeys`.
+  removeShadowArrayElement: (key, itemPath) => {
+    if (itemPath.length === 0) return;
 
-    // Extract parent path and item ID
-    const parentPath = itemPath.slice(0, -1);
-    const parentKey = [key, ...parentPath].join('.');
+    const arrayPath = itemPath.slice(0, -1);
+    const itemId = itemPath[itemPath.length - 1];
+    if (!itemId?.startsWith('id:')) return;
 
-    // Get parent metadata
-    const parentMeta = newShadowStore.get(parentKey);
+    const arrayNode = get().getShadowNode(key, arrayPath);
+    if (!arrayNode?._meta?.arrayKeys) return;
 
-    if (parentMeta && parentMeta.arrayKeys) {
-      // Find the index of the item to remove
-      const indexToRemove = parentMeta.arrayKeys.findIndex(
-        (arrayItemKey) => arrayItemKey === itemKey
-      );
+    // Filter the item's ID from the `arrayKeys` metadata
+    const newKeys = arrayNode._meta.arrayKeys.filter((k) => k !== itemId);
 
-      if (indexToRemove !== -1) {
-        // Create new array keys with the item removed
-        const newArrayKeys = parentMeta.arrayKeys.filter(
-          (arrayItemKey) => arrayItemKey !== itemKey
-        );
-
-        // Update parent with new array keys
-        newShadowStore.set(parentKey, {
-          ...parentMeta,
-          arrayKeys: newArrayKeys,
-        });
-
-        // Delete all data associated with the removed item
-        const prefixToDelete = itemKey + '.';
-        for (const k of Array.from(newShadowStore.keys())) {
-          if (k === itemKey || k.startsWith(prefixToDelete)) {
-            newShadowStore.delete(k);
-          }
-        }
-      }
-    }
+    // Delete the item's data from the node
+    delete arrayNode[itemId];
 
-    set({ shadowStateStore: newShadowStore });
+    // Persist the modified array node back to the store
+    get().setShadowMetadata(key, arrayPath, { arrayKeys: newKeys });
 
-    get().notifyPathSubscribers(parentKey, {
+    const arrayKey = [key, ...arrayPath].join('.');
+    get().notifyPathSubscribers(arrayKey, {
       type: 'REMOVE',
-      path: parentKey,
-      itemKey: itemKey, // The exact ID of the removed item
+      path: arrayKey,
+      itemKey: `${arrayKey}.${itemId}`,
     });
   },
 
-  updateShadowAtPath: (key, path, newValue) => {
-    const fullKey = [key, ...path].join('.');
+  // The rest of the functions are updated to use the new helpers (`getShadowMetadata`, `setShadowMetadata`)
+  // which abstracts away the `_meta` implementation detail.
 
-    // Optimization: Only update if value actually changed
-    const existingMeta = get().shadowStateStore.get(fullKey);
-    if (existingMeta?.value === newValue && !isSimpleObject(newValue)) {
-      return; // Skip update for unchanged primitives
+  addPathComponent: (stateKey, dependencyPath, fullComponentId) => {
+    const metadata = get().getShadowMetadata(stateKey, dependencyPath) || {};
+    const newPathComponents = new Set(metadata.pathComponents);
+    newPathComponents.add(fullComponentId);
+    get().setShadowMetadata(stateKey, dependencyPath, {
+      pathComponents: newPathComponents,
+    });
+
+    const rootMeta = get().getShadowMetadata(stateKey, []);
+    if (rootMeta?.components) {
+      const component = rootMeta.components.get(fullComponentId);
+      if (component) {
+        const fullPathKey = [stateKey, ...dependencyPath].join('.');
+        const newPaths = new Set(component.paths);
+        newPaths.add(fullPathKey);
+        const newComponentRegistration = { ...component, paths: newPaths };
+        const newComponentsMap = new Map(rootMeta.components);
+        newComponentsMap.set(fullComponentId, newComponentRegistration);
+        get().setShadowMetadata(stateKey, [], { components: newComponentsMap });
+      }
     }
+  },
 
-    // CHANGE: Don't clone the entire Map, just update in place
-    set((state) => {
-      const store = state.shadowStateStore;
+  registerComponent: (stateKey, fullComponentId, registration) => {
+    const rootMeta = get().getShadowMetadata(stateKey, []) || {};
+    const components = new Map(rootMeta.components);
+    components.set(fullComponentId, registration);
+    get().setShadowMetadata(stateKey, [], { components });
+  },
 
-      if (!isSimpleObject(newValue)) {
-        const meta = store.get(fullKey) || {};
-        store.set(fullKey, { ...meta, value: newValue });
-      } else {
-        // Handle objects by iterating
-        const processObject = (currentPath: string[], objectToSet: any) => {
-          const currentFullKey = [key, ...currentPath].join('.');
-          const meta = store.get(currentFullKey);
-
-          if (meta && meta.fields) {
-            for (const fieldKey in objectToSet) {
-              if (Object.prototype.hasOwnProperty.call(objectToSet, fieldKey)) {
-                const childValue = objectToSet[fieldKey];
-                const childFullPath = meta.fields[fieldKey];
-
-                if (childFullPath) {
-                  if (isSimpleObject(childValue)) {
-                    processObject(
-                      childFullPath.split('.').slice(1),
-                      childValue
-                    );
-                  } else {
-                    const existingChildMeta = store.get(childFullPath) || {};
-                    store.set(childFullPath, {
-                      ...existingChildMeta,
-                      value: childValue,
-                    });
-                  }
-                }
-              }
-            }
-          }
-        };
+  unregisterComponent: (stateKey, fullComponentId) => {
+    const rootMeta = get().getShadowMetadata(stateKey, []);
+    if (!rootMeta?.components) return;
+    const components = new Map(rootMeta.components);
+    if (components.delete(fullComponentId)) {
+      get().setShadowMetadata(stateKey, [], { components });
+    }
+  },
 
-        processObject(path, newValue);
+  // ✅ REFACTORED: `markAsDirty` now correctly writes to `_meta.isDirty`.
+  markAsDirty: (key, path, options = { bubble: true }) => {
+    const setDirtyOnPath = (pathToMark: string[]) => {
+      const node = get().getShadowNode(key, pathToMark);
+      if (node?._meta?.isDirty) {
+        return true; // Already dirty, stop bubbling
       }
+      get().setShadowMetadata(key, pathToMark, { isDirty: true });
+      return false; // Was not dirty before
+    };
 
-      // Only notify after all changes are made
-      get().notifyPathSubscribers(fullKey, { type: 'UPDATE', newValue });
+    setDirtyOnPath(path);
 
-      // Return same reference if using Zustand's immer middleware
-      return state;
+    if (options.bubble) {
+      let parentPath = [...path];
+      while (parentPath.length > 0) {
+        parentPath.pop();
+        if (setDirtyOnPath(parentPath)) {
+          break; // Stop if parent was already dirty
+        }
+      }
+    }
+  },
+
+  serverStateUpdates: new Map(),
+  setServerStateUpdate: (key, serverState) => {
+    set((state) => ({
+      serverStateUpdates: new Map(state.serverStateUpdates).set(
+        key,
+        serverState
+      ),
+    }));
+    get().notifyPathSubscribers(key, {
+      type: 'SERVER_STATE_UPDATE',
+      serverState,
     });
   },
+
+  pathSubscribers: new Map<string, Set<(newValue: any) => void>>(),
+  subscribeToPath: (path, callback) => {
+    const subscribers = get().pathSubscribers;
+    const subsForPath = subscribers.get(path) || new Set();
+    subsForPath.add(callback);
+    subscribers.set(path, subsForPath);
+
+    return () => {
+      const currentSubs = get().pathSubscribers.get(path);
+      if (currentSubs) {
+        currentSubs.delete(callback);
+        if (currentSubs.size === 0) {
+          get().pathSubscribers.delete(path);
+        }
+      }
+    };
+  },
+  notifyPathSubscribers: (updatedPath, newValue) => {
+    const subscribers = get().pathSubscribers;
+    const subs = subscribers.get(updatedPath);
+    if (subs) {
+      subs.forEach((callback) => callback(newValue));
+    }
+  },
+
   selectedIndicesMap: new Map<string, string>(),
-  getSelectedIndex: (arrayKey: string, validIds?: string[]): number => {
+  getSelectedIndex: (arrayKey, validIds) => {
     const itemKey = get().selectedIndicesMap.get(arrayKey);
-
     if (!itemKey) return -1;
 
-    // Use validIds if provided (for filtered views), otherwise use all arrayKeys
-    const arrayKeys =
-      validIds ||
-      getGlobalStore.getState().getShadowMetadata(arrayKey, [])?.arrayKeys;
-
-    if (!arrayKeys) return -1;
+    const arrayMeta = get().getShadowMetadata(
+      arrayKey.split('.')[0]!,
+      arrayKey.split('.').slice(1)
+    );
+    const arrayKeys = validIds || arrayMeta?.arrayKeys;
 
-    return arrayKeys.indexOf(itemKey);
+    return arrayKeys ? arrayKeys.indexOf(itemKey) : -1;
   },
 
-  setSelectedIndex: (arrayKey: string, itemKey: string | undefined) => {
+  setSelectedIndex: (arrayKey, itemKey) => {
     set((state) => {
-      const newMap = state.selectedIndicesMap;
+      const newMap = new Map(state.selectedIndicesMap);
+      const oldSelection = newMap.get(arrayKey);
+      if (oldSelection) {
+        get().notifyPathSubscribers(oldSelection, { type: 'THIS_UNSELECTED' });
+      }
 
       if (itemKey === undefined) {
         newMap.delete(arrayKey);
       } else {
-        if (newMap.has(arrayKey)) {
-          get().notifyPathSubscribers(newMap.get(arrayKey)!, {
-            type: 'THIS_UNSELECTED',
-          });
-        }
         newMap.set(arrayKey, itemKey);
-
-        get().notifyPathSubscribers(itemKey, {
-          type: 'THIS_SELECTED',
-        });
+        get().notifyPathSubscribers(itemKey, { type: 'THIS_SELECTED' });
       }
-      get().notifyPathSubscribers(arrayKey, {
-        type: 'GET_SELECTED',
-      });
-      return {
-        ...state,
-        selectedIndicesMap: newMap,
-      };
+
+      get().notifyPathSubscribers(arrayKey, { type: 'GET_SELECTED' });
+      return { selectedIndicesMap: newMap };
     });
   },
-  clearSelectedIndex: ({ arrayKey }: { arrayKey: string }): void => {
+
+  clearSelectedIndex: ({ arrayKey }) => {
     set((state) => {
-      const newMap = state.selectedIndicesMap;
-      const acutalKey = newMap.get(arrayKey);
-      if (acutalKey) {
-        get().notifyPathSubscribers(acutalKey, {
-          type: 'CLEAR_SELECTION',
-        });
+      const newMap = new Map(state.selectedIndicesMap);
+      const actualKey = newMap.get(arrayKey);
+      if (actualKey) {
+        get().notifyPathSubscribers(actualKey, { type: 'CLEAR_SELECTION' });
       }
-
       newMap.delete(arrayKey);
-      get().notifyPathSubscribers(arrayKey, {
-        type: 'CLEAR_SELECTION',
-      });
-      return {
-        ...state,
-        selectedIndicesMap: newMap,
-      };
+      get().notifyPathSubscribers(arrayKey, { type: 'CLEAR_SELECTION' });
+      return { selectedIndicesMap: newMap };
     });
   },
-  clearSelectedIndexesForState: (stateKey: string) => {
+
+  clearSelectedIndexesForState: (stateKey) => {
     set((state) => {
-      const newOuterMap = new Map(state.selectedIndicesMap);
-      const changed = newOuterMap.delete(stateKey);
-      if (changed) {
-        return { selectedIndicesMap: newOuterMap };
-      } else {
-        return {};
+      const newMap = new Map(state.selectedIndicesMap);
+      let changed = false;
+      for (const key of newMap.keys()) {
+        if (key === stateKey || key.startsWith(stateKey + '.')) {
+          newMap.delete(key);
+          changed = true;
+        }
       }
+      return changed ? { selectedIndicesMap: newMap } : {};
     });
   },
 
   initialStateOptions: {},
-
-  stateTimeline: {},
-  cogsStateStore: {},
   stateLog: new Map(),
-
   initialStateGlobal: {},
 
-  validationErrors: new Map(),
-  addStateLog: (key, update) => {
+  addStateLog: (updates) => {
+    if (!updates || updates.length === 0) return;
     set((state) => {
       const newLog = new Map(state.stateLog);
-      const stateLogForKey = new Map(newLog.get(key));
-      const uniquePathKey = JSON.stringify(update.path);
-
-      const existing = stateLogForKey.get(uniquePathKey);
-      if (existing) {
-        // If an update for this path already exists, just modify it. (Fast)
-        existing.newValue = update.newValue;
-        existing.timeStamp = update.timeStamp;
-      } else {
-        // Otherwise, add the new update. (Fast)
-        stateLogForKey.set(uniquePathKey, { ...update });
+      const logsGroupedByKey = new Map<string, UpdateTypeDetail[]>();
+      for (const update of updates) {
+        const group = logsGroupedByKey.get(update.stateKey) || [];
+        group.push(update);
+        logsGroupedByKey.set(update.stateKey, group);
+      }
+      for (const [key, batchOfUpdates] of logsGroupedByKey.entries()) {
+        const newStateLogForKey = new Map(newLog.get(key));
+        for (const update of batchOfUpdates) {
+          newStateLogForKey.set(JSON.stringify(update.path), { ...update });
+        }
+        newLog.set(key, newStateLogForKey);
       }
-
-      newLog.set(key, stateLogForKey);
       return { stateLog: newLog };
     });
   },
 
-  getInitialOptions: (key) => {
-    return get().initialStateOptions[key];
-  },
-
+  getInitialOptions: (key) => get().initialStateOptions[key],
   setInitialStateOptions: (key, value) => {
     set((prev) => ({
-      initialStateOptions: {
-        ...prev.initialStateOptions,
-        [key]: value,
-      },
+      initialStateOptions: { ...prev.initialStateOptions, [key]: value },
     }));
   },
   updateInitialStateGlobal: (key, newState) => {
     set((prev) => ({
-      initialStateGlobal: {
-        ...prev.initialStateGlobal,
-        [key]: newState,
-      },
+      initialStateGlobal: { ...prev.initialStateGlobal, [key]: newState },
     }));
   },
 
   syncInfoStore: new Map<string, SyncInfo>(),
-  setSyncInfo: (key: string, syncInfo: SyncInfo) =>
+  setSyncInfo: (key, syncInfo) =>
     set((state) => {
       const newMap = new Map(state.syncInfoStore);
       newMap.set(key, syncInfo);
-      return { ...state, syncInfoStore: newMap };
+      return { syncInfoStore: newMap };
     }),
-  getSyncInfo: (key: string) => get().syncInfoStore.get(key) || null,
+  getSyncInfo: (key) => get().syncInfoStore.get(key) || null,
 }));