mobx-vue-bridge 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -5,6 +5,52 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.0] - 2025-11-25
+
+### 🎯 Major Improvements
+
+#### Zero-side-effect initialization with lazy detection
+- **Feature**: Bridge no longer calls any setters during initialization, eliminating all side effects
+- **Benefit**: Fixes production bugs where setter side effects (like `refreshDataOnTabChange()`) were triggered during bridge setup
+- **Mechanism**: Lazy detection pattern - properties are optimistically marked as writable during init, tested on first actual write attempt
+- **Caching**: `readOnlyDetected` Set caches detection results for O(1) lookups on subsequent writes
+- **Impact**: User's `currentRoom` setter with side effects now works correctly - side effects only occur during actual user interactions
+
+#### Modular architecture refactoring
+- **Feature**: Core logic separated into focused utility modules
+- **Structure**: 
+  - `src/utils/memberDetection.js` (210 lines) - MobX member categorization without side effects
+  - `src/utils/equality.js` (47 lines) - Deep equality with circular reference protection
+  - `src/utils/deepProxy.js` (109 lines) - Nested reactivity with microtask batching
+- **Main bridge**: Reduced from 523 lines → 321 lines (39% reduction)
+- **Benefit**: Better maintainability, testability, and code organization
+
+### 🐛 Bug Fixes
+
+#### Fixed computed property detection with MobX synthetic setters
+- **Issue**: MobX adds synthetic setters to computed-only properties that throw "not possible to assign" errors
+- **Previous approach**: Tested setters during initialization (caused side effects)
+- **New approach**: Check descriptor existence only (`descriptor.get && descriptor.set`), test lazily on first write
+- **Detection**: Catch MobX error message during first write attempt, cache as read-only
+- **Result**: Accurate detection without initialization side effects
+
+#### Fixed test equality assertions
+- **Issue**: One test expected reference equality for cloned objects
+- **Fix**: Changed `.toBe()` to `.toStrictEqual()` for deep equality comparison
+- **Context**: Bridge clones objects to prevent reference sharing between Vue and MobX
+
+### ✅ Testing
+
+- **Total tests**: 170 passing (was 168 + 2 skipped)
+- **New active tests**: Unskipped and fixed 2 comprehensive two-way binding demo tests
+- **Coverage**: All patterns verified including lazy detection, nested mutations, and error handling
+
+### 📚 Documentation
+
+- **Architecture notes**: Added inline documentation explaining lazy detection pattern
+- **Comments**: Clear explanation of why setters aren't called during init
+- **Examples**: Test files demonstrate proper usage patterns
+
 ## [1.2.0] - 2025-10-01
 
 ### ✨ New Features

package/README.md

@@ -14,6 +14,8 @@ A seamless bridge between MobX observables and Vue 3's reactivity system, enabli
 - 🔒 **Type-safe bridging** between reactive systems
 - 🚀 **Optimized performance** with intelligent change detection
 - 🛡️ **Error handling** for edge cases and circular references
+- ⚡ **Zero-side-effect initialization** with lazy detection (v1.4.0+)
+- 📦 **Modular architecture** for better maintainability
 
 ## 📦 Installation
 
@@ -296,6 +298,51 @@ presenter.items.push(newItem)
 console.log(presenter.items)  // Immediately updated!
 ```
 
+## 🏗️ Architecture & Implementation
+
+### Modular Design (v1.4.0+)
+
+The bridge uses a clean, modular architecture for better maintainability:
+
+```
+src/
+├── mobxVueBridge.js           # Main bridge (321 lines)
+└── utils/
+    ├── memberDetection.js     # MobX property categorization (210 lines)
+    ├── equality.js            # Deep equality with circular protection (47 lines)
+    └── deepProxy.js           # Nested reactivity with batching (109 lines)
+```
+
+### Zero-Side-Effect Initialization
+
+The bridge uses **lazy detection** to avoid calling setters during initialization:
+
+```javascript
+class GuestPresenter {
+  get currentRoom() {
+    return this.repository.currentRoomId
+  }
+  
+  set currentRoom(val) {
+    this.repository.currentRoomId = val
+    this.refreshDataOnTabChange()  // Side effect!
+  }
+}
+
+// ✅ v1.4.0+: No side effects during bridge creation
+const state = useMobxBridge(presenter)  // refreshDataOnTabChange() NOT called
+
+// ✅ Side effects only happen during actual mutations
+state.currentRoom = 'room-123'  // refreshDataOnTabChange() called here
+```
+
+**How it works:**
+1. **Detection phase**: Checks descriptor existence only (`descriptor.get && descriptor.set`)
+2. **First write**: Tests if setter actually works by attempting the write
+3. **Caching**: Results stored in `readOnlyDetected` Set for O(1) future lookups
+
+This prevents bugs where setter side effects were triggered during bridge setup, while maintaining accurate runtime behavior.
+
 ### Error Handling
 The bridge gracefully handles edge cases:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobx-vue-bridge",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "A lightweight bridge for seamless two-way data binding between MobX observables and Vue 3 reactivity",
   "main": "src/mobxVueBridge.js",
   "module": "src/mobxVueBridge.js",

package/src/mobxVueBridge.js

@@ -1,7 +1,10 @@
 import { reactive, onUnmounted, ref } from 'vue';
-import { toJS, reaction, observe, isComputedProp, isObservableProp } from 'mobx';
+import { toJS, reaction, observe } from 'mobx';
 import { deepObserve } from 'mobx-utils';
 import clone from 'clone';
+import { categorizeMobxMembers } from './utils/memberDetection.js';
+import { isEqual } from './utils/equality.js';
+import { createDeepProxy } from './utils/deepProxy.js';
 
 /**
  * 🌉 MobX-Vue Bridge
@@ -49,248 +52,18 @@ export function useMobxBridge(mobxObject, options = {}) {
   
   const vueState = reactive({});
 
-  // Discover props/methods via MobX introspection (don’t rely on raw descriptors)
-  const props = Object.getOwnPropertyNames(mobxObject)
-    .concat(Object.getOwnPropertyNames(Object.getPrototypeOf(mobxObject)))
-    .filter(p => p !== 'constructor' && !p.startsWith('_'));
+  // Use the imported categorization function
+  const members = categorizeMobxMembers(mobxObject);
 
-  const members = {
-    getters: props.filter(p => {
-      try {
-        // First try to check if it's a computed property via MobX introspection
-        try {
-          return isComputedProp(mobxObject, p);
-        } catch (computedError) {
-          // If isComputedProp fails (e.g., due to uninitialized nested objects),
-          // fall back to checking if it has a getter descriptor
-          const descriptor = Object.getOwnPropertyDescriptor(mobxObject, p) || 
-                            Object.getOwnPropertyDescriptor(Object.getPrototypeOf(mobxObject), p);
-          
-          // If it has a getter but no corresponding property, it's likely a computed getter
-          return descriptor && typeof descriptor.get === 'function' && 
-                 !isObservableProp(mobxObject, p);
-        }
-      } catch (error) {
-        return false;
-      }
-    }),
-    setters: props.filter(p => {
-      try {
-        // Check if it has a setter descriptor
-        const descriptor = Object.getOwnPropertyDescriptor(mobxObject, p) || 
-                          Object.getOwnPropertyDescriptor(Object.getPrototypeOf(mobxObject), p);
-        
-        // Must have a setter
-        if (!descriptor || typeof descriptor.set !== 'function') return false;
-        
-        // Exclude methods
-        if (typeof mobxObject[p] === 'function') return false;
-        
-        // For MobX objects with makeAutoObservable, we need to distinguish:
-        // 1. Regular observable properties (handled separately) 
-        // 2. Computed properties with setters (getter/setter pairs)
-        // 3. Setter-only properties
-        
-        // Include if it's a computed property with a WORKING setter (getter/setter pair)
-        try {
-          if (isComputedProp(mobxObject, p)) {
-            // For computed properties, test if the setter actually works
-            try {
-              const originalValue = mobxObject[p];
-              descriptor.set.call(mobxObject, originalValue); // Try to set to same value
-              return true; // Setter works, it's a getter/setter pair
-            } catch (setterError) {
-              return false; // Setter throws error, it's a computed-only property
-            }
-          }
-        } catch (error) {
-          // If isComputedProp fails, check if it has a getter and test the setter
-          if (descriptor.get) {
-            try {
-              // Try to get the current value and set it back
-              const currentValue = mobxObject[p];
-              descriptor.set.call(mobxObject, currentValue);
-              return true; // Setter works
-            } catch (setterError) {
-              return false; // Setter throws error
-            }
-          }
-        }
-        
-        // Include if it's NOT an observable property (setter-only or other cases)
-        if (!isObservableProp(mobxObject, p)) return true;
-        
-        // Exclude regular observable properties (they're handled separately)
-        return false;
-      } catch (error) {
-        return false;
-      }
-    }),
-    properties: props.filter(p => {
-      try {
-        // Check if it's an observable property
-        if (!isObservableProp(mobxObject, p)) return false;
-        
-        // Check if it's a function (method)
-        if (typeof mobxObject[p] === 'function') return false;
-        
-        // Check if it's a computed property - if so, it's a getter, not a property
-        const isComputed = isComputedProp(mobxObject, p);
-        if (isComputed) return false;
-        
-        return true; // Regular observable property
-      } catch (error) {
-        return false;
-      }
-    }),
-    methods: props.filter(p => {
-      try {
-        return typeof mobxObject[p] === 'function';
-      } catch (error) {
-        return false;
-      }
-    }),
-  };
-  
-
-  // ---- utils: guards + equality --------------------------------------------
+  // ---- utils: guards -------------------------------------------------------
   const updatingFromMobx = new Set();
   const updatingFromVue = new Set();
 
-  /**
-   * Deep equality comparison with circular reference protection.
-   * Uses WeakSet to track visited objects and prevent infinite recursion.
-   * 
-   * @param {any} a - First value to compare
-   * @param {any} b - Second value to compare  
-   * @param {WeakSet} visited - Set of visited objects to prevent circular references
-   * @returns {boolean} True if values are deeply equal
-   */
-  const isEqual = (a, b, visited = new WeakSet()) => {
-    if (Object.is(a, b)) return true;
-    
-    // Handle null/undefined cases
-    if (a == null || b == null) return a === b;
-    
-    // Different types are not equal
-    if (typeof a !== typeof b) return false;
-    
-    // For primitives, Object.is should have caught them
-    if (typeof a !== 'object') return false;
-    
-    // Check for circular references
-    if (visited.has(a)) return true;
-    visited.add(a);
-    
-    // Fast array comparison
-    if (Array.isArray(a) && Array.isArray(b)) {
-      if (a.length !== b.length) return false;
-      return a.every((val, i) => isEqual(val, b[i], visited));
-    }
-    
-    // Fast object comparison - check keys first
-    const aKeys = Object.keys(a);
-    const bKeys = Object.keys(b);
-    if (aKeys.length !== bKeys.length) return false;
-    
-    // Check if all keys match
-    if (!aKeys.every(key => bKeys.includes(key))) return false;
-    
-    // Check values (recursive)
-    return aKeys.every(key => isEqual(a[key], b[key], visited));
-  };
-
   // Warning helpers to reduce duplication
   const warnDirectMutation = (prop) => console.warn(`Direct mutation of '${prop}' is disabled`);
   const warnSetterMutation = (prop) => console.warn(`Direct mutation of setter '${prop}' is disabled`);
   const warnMethodAssignment = (prop) => console.warn(`Cannot assign to method '${prop}'`);
 
-  /**
-   * Creates a deep proxy for nested objects/arrays to handle mutations at any level.
-   * This enables mutations like state.items.push(item) to work correctly.
-   * Respects the allowDirectMutation configuration for all nesting levels.
-   * 
-   * Note: Mutations are batched via queueMicrotask to prevent corruption during 
-   * array operations like shift(), unshift(), splice() which modify multiple indices.
-   * This ensures data correctness at the cost of a microtask delay.
-   * 
-   * IMPORTANT: The proxy wraps the value stored in propertyRefs[prop].value, which is
-   * a clone. When nested mutations occur, we update the clone in-place, then trigger
-   * a sync back to MobX by re-assigning the entire cloned structure.
-   * 
-   * @param {object|array} value - The nested value to wrap in a proxy
-   * @param {string} prop - The parent property name for error messages and sync
-   * @param {function} getRoot - Function that returns the current root value from propertyRef
-   * @returns {Proxy} Proxied object/array with reactive mutation handling
-   */
-  const createDeepProxy = (value, prop, getRoot = null) => {
-    // Don't proxy built-in objects that should remain unchanged
-    if (value instanceof Date || value instanceof RegExp || value instanceof Map || 
-        value instanceof Set || value instanceof WeakMap || value instanceof WeakSet) {
-      return value;
-    }
-
-    // If no getRoot provided, use the default which gets from propertyRefs
-    if (!getRoot) {
-      getRoot = () => propertyRefs[prop].value;
-    }
-
-    // Track pending updates to batch array mutations
-    let updatePending = false;
-    
-    return new Proxy(value, {
-      get: (target, key) => {
-        const result = target[key];
-        // If the result is an object/array, wrap it in a proxy too (but not built-ins)
-        if (result && typeof result === 'object' && 
-            !(result instanceof Date || result instanceof RegExp || result instanceof Map || 
-              result instanceof Set || result instanceof WeakMap || result instanceof WeakSet)) {
-          return createDeepProxy(result, prop, getRoot);
-        }
-        return result;
-      },
-      set: (target, key, val) => {
-        // Check if direct mutation is allowed
-        if (!allowDirectMutation) {
-          warnDirectMutation(`${prop}.${String(key)}`);
-          return true; // Must return true to avoid TypeError in strict mode
-        }
-        
-        // Update the target in-place (this modifies the clone in propertyRefs[prop].value)
-        target[key] = val;
-        
-        // Batch updates to avoid corrupting in-progress array operations
-        // like shift(), unshift(), splice() which modify multiple indices synchronously
-        if (!updatePending) {
-          updatePending = true;
-          queueMicrotask(() => {
-            updatePending = false;
-            // The root value has already been modified in-place above (target[key] = val)
-            // Now we need to trigger Vue reactivity and sync to MobX
-            
-            // Clone the root to create a new reference for Vue reactivity
-            // This ensures Vue detects the change
-            const rootValue = getRoot();
-            const cloned = clone(rootValue);
-            
-            // Update the Vue ref to trigger reactivity
-            propertyRefs[prop].value = cloned;
-            
-            // Update MobX immediately with the cloned value
-            updatingFromVue.add(prop);
-            try {
-              mobxObject[prop] = cloned;
-            } finally {
-              updatingFromVue.delete(prop);
-            }
-          });
-        }
-        
-        return true;
-      }
-    });
-  };
-
   // ---- properties (two-way) -------------------------------------------------
   const propertyRefs = {};
   
@@ -302,7 +75,15 @@ export function useMobxBridge(mobxObject, options = {}) {
         const value = propertyRefs[prop].value;
         // For objects/arrays, return a deep proxy that syncs mutations back
         if (value && typeof value === 'object') {
-          return createDeepProxy(value, prop);
+          return createDeepProxy(
+            value, 
+            prop, 
+            () => propertyRefs[prop].value,
+            allowDirectMutation,
+            updatingFromVue,
+            mobxObject,
+            propertyRefs
+          );
         }
         return value;
       },
@@ -333,13 +114,15 @@ export function useMobxBridge(mobxObject, options = {}) {
   // ---- getters and setters (handle both computed and two-way binding) ------
   const getterRefs = {};
   const setterRefs = {};
+  const readOnlyDetected = new Set(); // Track properties detected as read-only on first write
 
   // First, handle properties that have BOTH getters and setters (getter/setter pairs)
   const getterSetterPairs = members.getters.filter(prop => members.setters.includes(prop));
   const gettersOnly = members.getters.filter(prop => !members.setters.includes(prop));
   const settersOnly = members.setters.filter(prop => !members.getters.includes(prop));
 
-  // Getter/setter pairs: writable with reactive updates
+  // Getter/setter pairs: potentially writable with reactive updates
+  // Note: Some may have MobX synthetic setters that throw - we detect this lazily on first write
   getterSetterPairs.forEach(prop => {
     // Get initial value from getter
     let initialValue;
@@ -349,20 +132,31 @@ export function useMobxBridge(mobxObject, options = {}) {
       initialValue = undefined;
     }
     getterRefs[prop] = ref(initialValue);
-    setterRefs[prop] = ref(initialValue);
 
     Object.defineProperty(vueState, prop, {
+      // ALWAYS read from MobX so computed properties work correctly
       get: () => getterRefs[prop].value,
       set: allowDirectMutation
         ? (value) => {
-            // Update both refs
-            setterRefs[prop].value = value;
-            // Call the MobX setter immediately
+            // Check if we've already detected this as read-only
+            if (readOnlyDetected.has(prop)) {
+              throw new Error(`Cannot assign to computed property '${prop}'`);
+            }
+            
+            // Try to call the MobX setter (first write test)
             updatingFromVue.add(prop);
             try {
               mobxObject[prop] = value;
               // The getter ref will be updated by the reaction
             } catch (error) {
+              // Check if it's a MobX "not possible to assign" error (synthetic setter)
+              if (error.message && error.message.includes('not possible to assign')) {
+                // Mark as read-only so we don't try again
+                readOnlyDetected.add(prop);
+                // This is actually a read-only computed property
+                throw new Error(`Cannot assign to computed property '${prop}'`);
+              }
+              // For other errors (validation, side effects), just warn
               console.warn(`Failed to set property '${prop}':`, error);
             } finally {
               updatingFromVue.delete(prop);
@@ -520,9 +314,11 @@ export function useMobxBridge(mobxObject, options = {}) {
       try {
         if (typeof unsub === 'function') {
           unsub();
+        } else if (typeof unsub?.dispose === 'function') {
+          unsub.dispose();
         }
-      } catch {
-        // Silently ignore cleanup errors
+      } catch (error) {
+        // Silently handle cleanup errors
       }
     });
   });
@@ -531,12 +327,7 @@ export function useMobxBridge(mobxObject, options = {}) {
 }
 
 /**
- * Helper alias for useMobxBridge - commonly used with presenter objects
- * 
- * @param {object} presenter - The MobX presenter object to bridge
- * @param {object} options - Configuration options
- * @returns {object} Vue reactive state object
+ * Alias for useMobxBridge - for users who prefer "presenter" terminology
+ * @alias useMobxBridge
  */
-export function usePresenterState(presenter, options = {}) {
-  return useMobxBridge(presenter, options);
-}
+export const usePresenterState = useMobxBridge;

package/src/utils/deepProxy.js

@@ -0,0 +1,109 @@
+import clone from 'clone';
+
+/**
+ * Creates a deep proxy for nested objects/arrays to handle mutations at any level.
+ * 
+ * This enables mutations like `state.items.push(item)` to work correctly by:
+ * 1. Intercepting nested property access and wrapping in proxies
+ * 2. Batching mutations via queueMicrotask to prevent array corruption
+ * 3. Syncing changes back to MobX and triggering Vue reactivity
+ * 
+ * Key Design Decisions:
+ * - Mutations are batched via queueMicrotask to prevent corruption during
+ *   array operations like shift(), unshift(), splice() which modify multiple
+ *   indices synchronously.
+ * - The proxy wraps a CLONE stored in propertyRefs[prop].value
+ * - When nested mutations occur, we update the clone in-place, then sync back
+ * 
+ * @param {object|array} value - The nested value to wrap in a proxy
+ * @param {string} prop - The parent property name for error messages and sync
+ * @param {function} getRoot - Function that returns the current root value from propertyRef
+ * @param {boolean} allowDirectMutation - Whether mutations are allowed
+ * @param {Set} updatingFromVue - Guard set to prevent infinite loops
+ * @param {object} mobxObject - The MobX object to sync changes back to
+ * @param {object} propertyRefs - Vue refs storage for syncing
+ * @returns {Proxy} Proxied object/array with reactive mutation handling
+ */
+export function createDeepProxy(
+  value, 
+  prop, 
+  getRoot,
+  allowDirectMutation,
+  updatingFromVue,
+  mobxObject,
+  propertyRefs
+) {
+  // Don't proxy built-in objects that should remain unchanged
+  if (value instanceof Date || value instanceof RegExp || value instanceof Map || 
+      value instanceof Set || value instanceof WeakMap || value instanceof WeakSet) {
+    return value;
+  }
+
+  // If no getRoot provided, use the default which gets from propertyRefs
+  if (!getRoot) {
+    getRoot = () => propertyRefs[prop].value;
+  }
+
+  // Track pending updates to batch array mutations
+  let updatePending = false;
+  
+  return new Proxy(value, {
+    get: (target, key) => {
+      const result = target[key];
+      // If the result is an object/array, wrap it in a proxy too (but not built-ins)
+      if (result && typeof result === 'object' && 
+          !(result instanceof Date || result instanceof RegExp || result instanceof Map || 
+            result instanceof Set || result instanceof WeakMap || result instanceof WeakSet)) {
+        return createDeepProxy(
+          result, 
+          prop, 
+          getRoot,
+          allowDirectMutation,
+          updatingFromVue,
+          mobxObject,
+          propertyRefs
+        );
+      }
+      return result;
+    },
+    set: (target, key, val) => {
+      // Check if direct mutation is allowed
+      if (!allowDirectMutation) {
+        console.warn(`Direct mutation of '${prop}.${String(key)}' is disabled`);
+        return true; // Must return true to avoid TypeError in strict mode
+      }
+      
+      // Update the target in-place (this modifies the clone in propertyRefs[prop].value)
+      target[key] = val;
+      
+      // Batch updates to avoid corrupting in-progress array operations
+      // like shift(), unshift(), splice() which modify multiple indices synchronously
+      if (!updatePending) {
+        updatePending = true;
+        queueMicrotask(() => {
+          updatePending = false;
+          // The root value has already been modified in-place above (target[key] = val)
+          // Now we need to trigger Vue reactivity and sync to MobX
+          
+          // Clone the root to create a new reference for Vue reactivity
+          // This ensures Vue detects the change
+          const rootValue = getRoot();
+          const cloned = clone(rootValue);
+          
+          // Update the Vue ref to trigger reactivity
+          propertyRefs[prop].value = cloned;
+          
+          // Update MobX immediately with the cloned value
+          updatingFromVue.add(prop);
+          try {
+            mobxObject[prop] = cloned;
+          } finally {
+            updatingFromVue.delete(prop);
+          }
+        });
+      }
+      
+      return true;
+    }
+  });
+}

package/src/utils/equality.js

@@ -0,0 +1,45 @@
+/**
+ * Deep equality comparison with circular reference protection.
+ * 
+ * Uses WeakSet to track visited objects and prevent infinite recursion.
+ * This is used to prevent unnecessary updates when values haven't actually changed.
+ * 
+ * @param {any} a - First value to compare
+ * @param {any} b - Second value to compare  
+ * @param {WeakSet} visited - Set of visited objects to prevent circular references
+ * @returns {boolean} True if values are deeply equal
+ */
+export function isEqual(a, b, visited = new WeakSet()) {
+  // Same reference or primitive equality
+  if (Object.is(a, b)) return true;
+  
+  // Handle null/undefined cases
+  if (a == null || b == null) return a === b;
+  
+  // Different types are not equal
+  if (typeof a !== typeof b) return false;
+  
+  // For primitives, Object.is should have caught them
+  if (typeof a !== 'object') return false;
+  
+  // Check for circular references
+  if (visited.has(a)) return true;
+  visited.add(a);
+  
+  // Fast array comparison
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((val, i) => isEqual(val, b[i], visited));
+  }
+  
+  // Fast object comparison - check keys first
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  
+  // Check if all keys match
+  if (!aKeys.every(key => bKeys.includes(key))) return false;
+  
+  // Check values (recursive)
+  return aKeys.every(key => isEqual(a[key], b[key], visited));
+}

package/src/utils/memberDetection.js

@@ -0,0 +1,195 @@
+import { isComputedProp, isObservableProp } from 'mobx';
+
+/**
+ * Categorizes members of a MobX object into getters, setters, properties, and methods.
+ * 
+ * This is the core classification logic that determines how each member should be
+ * bridged to Vue. The categorization affects:
+ * - Getters: Read-only computed properties
+ * - Setters: Writable computed properties (getter/setter pairs)
+ * - Properties: Two-way bindable observable properties
+ * - Methods: Bound functions
+ * 
+ * @param {object} mobxObject - The MobX observable object to analyze
+ * @returns {object} Object with arrays: { getters, setters, properties, methods }
+ */
+export function categorizeMobxMembers(mobxObject) {
+  // Discover all properties and methods (own + prototype)
+  const props = Object.getOwnPropertyNames(mobxObject)
+    .concat(Object.getOwnPropertyNames(Object.getPrototypeOf(mobxObject)))
+    .filter(p => p !== 'constructor' && !p.startsWith('_'));
+
+  return {
+    getters: detectGetters(mobxObject, props),
+    setters: detectSetters(mobxObject, props),
+    properties: detectProperties(mobxObject, props),
+    methods: detectMethods(mobxObject, props),
+  };
+}
+
+/**
+ * Detects computed properties (getters) in a MobX object.
+ * 
+ * A property is considered a getter if:
+ * - MobX identifies it as a computed property via isComputedProp, OR
+ * - It has a getter descriptor but is not an observable property
+ * 
+ * @param {object} mobxObject - The MobX object
+ * @param {string[]} props - Array of property names to check
+ * @returns {string[]} Array of getter property names
+ */
+function detectGetters(mobxObject, props) {
+  return props.filter(p => {
+    try {
+      // First try MobX introspection
+      try {
+        return isComputedProp(mobxObject, p);
+      } catch (computedError) {
+        // If isComputedProp fails (e.g., uninitialized nested objects),
+        // fall back to descriptor checking
+        const descriptor = getDescriptor(mobxObject, p);
+        
+        // Has getter but not an observable property = computed getter
+        return descriptor && 
+               typeof descriptor.get === 'function' && 
+               !isObservableProp(mobxObject, p);
+      }
+    } catch (error) {
+      return false;
+    }
+  });
+}
+
+/**
+ * Detects writable computed properties (getter/setter pairs) in a MobX object.
+ * 
+ * A property is considered a setter if:
+ * - It has a setter descriptor, AND
+ * - It's either a computed property with a working setter OR a setter-only property
+ * 
+ * Key Challenge: Testing if a setter "works" can have side effects.
+ * Current approach: Try to set the property to its current value.
+ * TODO: Consider safer detection methods or document limitations.
+ * 
+ * @param {object} mobxObject - The MobX object
+ * @param {string[]} props - Array of property names to check
+ * @returns {string[]} Array of setter property names
+ */
+function detectSetters(mobxObject, props) {
+  return props.filter(p => {
+    try {
+      const descriptor = getDescriptor(mobxObject, p);
+      
+      // Must have a setter
+      if (!descriptor || typeof descriptor.set !== 'function') return false;
+      
+      // Exclude methods (shouldn't happen, but defensive)
+      if (typeof mobxObject[p] === 'function') return false;
+      
+      // For computed properties, include if it has both getter AND setter descriptors
+      // Don't call the setter during initialization - we'll handle errors during actual sync
+      try {
+        if (isComputedProp(mobxObject, p)) {
+          // If both getter and setter exist, assume it's potentially writable
+          // The actual setter behavior will be tested lazily during first sync attempt
+          return descriptor.get && descriptor.set;
+        }
+      } catch (error) {
+        // If isComputedProp fails, check if both descriptors exist
+        if (descriptor.get && descriptor.set) {
+          return true;
+        }
+      }
+      
+      // Include setter-only properties (not observable)
+      if (!isObservableProp(mobxObject, p)) return true;
+      
+      // Exclude regular observable properties (handled separately)
+      return false;
+    } catch (error) {
+      return false;
+    }
+  });
+}
+
+/**
+ * Tests if a setter can be called without throwing.
+ * 
+ * CAUTION: This has side effects if the setter triggers actions or state changes.
+ * The test tries to set the property to its current value to minimize impact.
+ * 
+ * @param {object} mobxObject - The MobX object
+ * @param {PropertyDescriptor} descriptor - The property descriptor
+ * @param {string} prop - Property name (for error context)
+ * @returns {boolean} True if setter works without throwing
+ */
+function testSetter(mobxObject, descriptor, prop) {
+  try {
+    const originalValue = mobxObject[prop];
+    descriptor.set.call(mobxObject, originalValue);
+    return true; // Setter works
+  } catch (setterError) {
+    // Setter throws - treat as read-only computed
+    return false;
+  }
+}
+
+/**
+ * Detects regular observable properties in a MobX object.
+ * 
+ * A property is considered a regular observable if:
+ * - MobX identifies it as observable via isObservableProp, AND
+ * - It's not a function (method), AND
+ * - It's not a computed property
+ * 
+ * @param {object} mobxObject - The MobX object
+ * @param {string[]} props - Array of property names to check
+ * @returns {string[]} Array of observable property names
+ */
+function detectProperties(mobxObject, props) {
+  return props.filter(p => {
+    try {
+      // Must be observable
+      if (!isObservableProp(mobxObject, p)) return false;
+      
+      // Exclude methods
+      if (typeof mobxObject[p] === 'function') return false;
+      
+      // Exclude computed properties (they're getters)
+      if (isComputedProp(mobxObject, p)) return false;
+      
+      return true; // Regular observable property
+    } catch (error) {
+      return false;
+    }
+  });
+}
+
+/**
+ * Detects methods in a MobX object.
+ * 
+ * @param {object} mobxObject - The MobX object
+ * @param {string[]} props - Array of property names to check
+ * @returns {string[]} Array of method names
+ */
+function detectMethods(mobxObject, props) {
+  return props.filter(p => {
+    try {
+      return typeof mobxObject[p] === 'function';
+    } catch (error) {
+      return false;
+    }
+  });
+}
+
+/**
+ * Gets the property descriptor from either the object or its prototype.
+ * 
+ * @param {object} obj - The object to inspect
+ * @param {string} prop - Property name
+ * @returns {PropertyDescriptor|undefined} The descriptor or undefined
+ */
+function getDescriptor(obj, prop) {
+  return Object.getOwnPropertyDescriptor(obj, prop) || 
+         Object.getOwnPropertyDescriptor(Object.getPrototypeOf(obj), prop);
+}