mobx-vue-bridge 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+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.0.0] - 2025-09-29
+
+### Added
+- Initial release of mobx-vue-bridge
+- Two-way data binding between MobX observables and Vue 3 reactivity
+- Support for properties, getters, setters, and methods
+- Deep object/array observation with proper reactivity
+- Configurable mutation behavior via `allowDirectMutation` option
+- TypeScript definitions for better developer experience
+- Comprehensive test suite covering various scenarios
+- Error handling for edge cases and circular references
+- Performance optimizations with intelligent change detection
+
+### Features
+- `useMobxBridge()` - Main bridge function
+- `usePresenterState()` - Alias for presenter pattern usage
+- Automatic property type detection (observable, computed, methods)
+- Intelligent synchronization preventing infinite loops
+- Support for nested objects and arrays
+- Graceful handling of uninitialized computed properties

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Visar Uruqi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,289 @@
+# 🌉 MobX-Vue Bridge
+
+A seamless bridge between MobX observables and Vue 3's reactivity system, enabling effortless two-way data binding and state synchronization.
+
+[![npm version](https://badge.fury.io/js/mobx-vue-bridge.svg)](https://www.npmjs.com/package/mobx-vue-bridge)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## ✨ Features
+
+- 🔄 **Two-way data binding** between MobX observables and Vue reactive state
+- 🎯 **Automatic property detection** (properties, getters, setters, methods)
+- 🏗️ **Deep object/array observation** with proper reactivity
+- ⚙️ **Configurable mutation behavior** 
+- 🔒 **Type-safe bridging** between reactive systems
+- 🚀 **Optimized performance** with intelligent change detection
+- 🛡️ **Error handling** for edge cases and circular references
+
+## 📦 Installation
+
+```bash
+npm install mobx-vue-bridge
+```
+
+**Peer Dependencies:**
+- Vue 3.x
+- MobX 6.x
+
+```bash
+npm install vue mobx
+```
+
+## 🚀 Quick Start
+
+```javascript
+import { useMobxBridge } from 'mobx-vue-bridge'
+import { makeAutoObservable } from 'mobx'
+
+// Your MobX store/presenter
+class UserPresenter {
+  constructor() {
+    this.name = 'John'
+    this.age = 25
+    this.emails = []
+    
+    makeAutoObservable(this)
+  }
+  
+  get displayName() {
+    return `${this.name} (${this.age})`
+  }
+  
+  addEmail(email) {
+    this.emails.push(email)
+  }
+}
+
+// In your Vue component
+
+// Option 1: Modern <script setup> syntax (recommended)
+<script setup>
+import { useMobxBridge } from 'mobx-vue-bridge'
+import { makeAutoObservable } from 'mobx'
+
+// Your MobX presenter
+class UserPresenter {
+  constructor() {
+    this.name = 'John'
+    this.age = 25
+    this.emails = []
+    
+    makeAutoObservable(this)
+  }
+  
+  get displayName() {
+    return `${this.name} (${this.age})`
+  }
+  
+  addEmail(email) {
+    this.emails.push(email)
+  }
+}
+
+const userPresenter = new UserPresenter()
+
+// Bridge MobX observable to Vue reactive state
+const state = useMobxBridge(userPresenter)
+</script>
+
+// Option 2: Traditional Composition API
+<script>
+import { useMobxBridge } from 'mobx-vue-bridge'
+import { makeAutoObservable } from 'mobx'
+
+class UserPresenter {
+  constructor() {
+    this.name = 'John'
+    this.age = 25
+    this.emails = []
+    
+    makeAutoObservable(this)
+  }
+  
+  get displayName() {
+    return `${this.name} (${this.age})`
+  }
+  
+  addEmail(email) {
+    this.emails.push(email)
+  }
+}
+
+export default {
+  setup() {
+    const userPresenter = new UserPresenter()
+    
+    // Bridge MobX observable to Vue reactive state
+    const state = useMobxBridge(userPresenter)
+    
+    return {
+      state
+    }
+  }
+}
+</script>
+```
+
+```vue
+<template>
+  <div>
+    <!-- Two-way binding works seamlessly -->
+    <input v-model="state.name" />
+    <input v-model.number="state.age" />
+    
+    <!-- Computed properties are reactive -->
+    <p>{{ state.displayName }}</p>
+    
+    <!-- Methods are properly bound -->
+    <button @click="state.addEmail('new@email.com')">
+      Add Email
+    </button>
+    
+    <!-- Arrays/objects are deeply reactive -->
+    <ul>
+      <li v-for="email in state.emails" :key="email">
+        {{ email }}
+      </li>
+    </ul>
+  </div>
+</template>
+```
+
+## 📚 API Reference
+
+### `useMobxBridge(mobxObject, options?)`
+
+Bridges a MobX observable object with Vue's reactivity system.
+
+**Parameters:**
+- `mobxObject` - The MobX observable object to bridge
+- `options` - Configuration options (optional)
+
+**Options:**
+- `allowDirectMutation` (boolean, default: `true`) - Whether to allow direct mutation of properties
+
+**Returns:** Vue reactive state object
+
+```javascript
+// With configuration
+const state = useMobxBridge(store, {
+  allowDirectMutation: false // Prevents direct mutations
+})
+```
+
+### `usePresenterState(presenter, options?)`
+
+Alias for `useMobxBridge` - commonly used with presenter pattern.
+
+```javascript
+const state = usePresenterState(presenter, options)
+```
+
+## 🎯 Use Cases
+
+### Presenter Pattern
+```javascript
+class TodoPresenter {
+  constructor(todoService) {
+    this.todoService = todoService
+    this.todos = []
+    this.filter = 'all'
+    this.loading = false
+    
+    makeAutoObservable(this)
+  }
+  
+  get filteredTodos() {
+    switch (this.filter) {
+      case 'active': return this.todos.filter(t => !t.completed)
+      case 'completed': return this.todos.filter(t => t.completed)
+      default: return this.todos
+    }
+  }
+  
+  async loadTodos() {
+    this.loading = true
+    try {
+      this.todos = await this.todoService.fetchTodos()
+    } finally {
+      this.loading = false
+    }
+  }
+}
+
+// In component
+const presenter = new TodoPresenter(todoService)
+const state = usePresenterState(presenter)
+```
+
+### Store Integration
+```javascript
+// MobX store
+class AppStore {
+  constructor() {
+    this.user = null
+    this.theme = 'light'
+    this.notifications = []
+    
+    makeAutoObservable(this)
+  }
+  
+  get isAuthenticated() {
+    return !!this.user
+  }
+  
+  setTheme(theme) {
+    this.theme = theme
+  }
+}
+
+// Bridge in component
+const state = useMobxBridge(appStore)
+```
+
+## 🔧 Advanced Features
+
+### Deep Reactivity
+The bridge automatically handles deep changes in objects and arrays:
+
+```javascript
+// These mutations are automatically synced
+state.user.profile.name = 'New Name'  // Object mutation
+state.todos.push(newTodo)             // Array mutation
+state.settings.colors[0] = '#FF0000'  // Nested array mutation
+```
+
+### Error Handling
+The bridge gracefully handles edge cases:
+
+- Uninitialized computed properties
+- Circular references
+- Failed setter operations
+- Missing dependencies
+
+### Performance Optimization
+- Intelligent change detection prevents unnecessary updates
+- Efficient shallow/deep equality checks
+- Minimal overhead for large object graphs
+
+## 🧪 Testing
+
+```bash
+npm test                 # Run tests
+npm run test:watch      # Watch mode
+npm run test:coverage   # Coverage report
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📄 License
+
+MIT © [Visar Uruqi](https://github.com/visaruruqi)
+
+## 🔗 Links
+
+- [GitHub Repository](https://github.com/visaruruqi/mobx-vue-bridge)
+- [NPM Package](https://www.npmjs.com/package/mobx-vue-bridge)
+- [Issues](https://github.com/visaruruqi/mobx-vue-bridge/issues)

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "mobx-vue-bridge",
+  "version": "1.0.0",
+  "description": "A bridge between MobX observables and Vue 3 reactivity system, enabling seamless two-way data binding and state synchronization.",
+  "main": "src/mobxVueBridge.js",
+  "module": "src/mobxVueBridge.js",
+  "types": "src/mobxVueBridge.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/mobxVueBridge.js",
+      "require": "./src/mobxVueBridge.js"
+    }
+  },
+  "files": [
+    "src/",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:coverage": "vitest --coverage",
+    "prepublishOnly": "npm test && node scripts/pre-publish.js",
+    "publish:dry": "npm publish --dry-run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/visaruruqi/mobx-vue-bridge.git"
+  },
+  "keywords": [
+    "mobx",
+    "vue",
+    "vue3",
+    "reactivity",
+    "state-management",
+    "bridge",
+    "observable",
+    "reactive",
+    "two-way-binding",
+    "composition-api"
+  ],
+  "author": "Visar Uruqi",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/visaruruqi/mobx-vue-bridge/issues"
+  },
+  "homepage": "https://github.com/visaruruqi/mobx-vue-bridge#readme",
+  "peerDependencies": {
+    "vue": "^3.0.0",
+    "mobx": "^6.0.0"
+  },
+  "dependencies": {
+    "mobx-utils": "^6.0.0",
+    "clone": "^2.1.2"
+  },
+  "devDependencies": {
+    "vitest": "^1.0.0",
+    "@vitest/coverage-v8": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/src/mobxVueBridge.d.ts

@@ -0,0 +1,33 @@
+import { Ref, UnwrapRef } from 'vue'
+
+export interface MobxBridgeOptions {
+  /**
+   * Whether to allow direct mutation of properties
+   * @default true
+   */
+  allowDirectMutation?: boolean
+}
+
+/**
+ * Bridge between MobX observables and Vue 3 reactivity system
+ * 
+ * @param mobxObject - The MobX observable object to bridge
+ * @param options - Configuration options
+ * @returns Vue reactive state object
+ */
+export function useMobxBridge<T extends object>(
+  mobxObject: T,
+  options?: MobxBridgeOptions
+): UnwrapRef<T>
+
+/**
+ * Helper alias for useMobxBridge - commonly used with presenter objects
+ * 
+ * @param presenter - The MobX presenter object to bridge
+ * @param options - Configuration options
+ * @returns Vue reactive state object
+ */
+export function usePresenterState<T extends object>(
+  presenter: T,
+  options?: MobxBridgeOptions
+): UnwrapRef<T>

package/src/mobxVueBridge.js

@@ -0,0 +1,432 @@
+import { reactive, onUnmounted, ref } from 'vue';
+import { toJS, reaction, observe, isComputedProp, isObservableProp } from 'mobx';
+import { deepObserve } from 'mobx-utils';
+import clone from 'clone';
+
+/**
+ * 🌉 MobX-Vue Bridge
+ * 
+ * @param {object} mobxObject - The MobX observable object to bridge
+ * @param {object} options - Configuration options
+ * @param {boolean} options.allowDirectMutation - Whether to allow direct mutation of properties
+ * @returns {object} Vue reactive state object
+ */
+export function useMobxBridge(mobxObject, options = {}) {
+  const safeOptions = options || {};
+  // Use explicit boolean conversion to handle truthy/falsy values properly
+  const allowDirectMutation = safeOptions.allowDirectMutation !== undefined 
+    ? Boolean(safeOptions.allowDirectMutation) 
+    : true; // Keep the original default of true
+  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('_'));
+
+  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 --------------------------------------------
+  const updatingFromMobx = new Set();
+  const updatingFromVue = new Set();
+
+  const isEqual = (a, b) => {
+    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;
+    
+    // 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]));
+    }
+    
+    // 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]));
+  };
+
+  // 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}'`);
+
+  // Helper to create deep proxies for nested objects and arrays
+  const createDeepProxy = (value, prop) => {
+    // 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;
+    }
+    
+    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);
+        }
+        return result;
+      },
+      set: (target, key, val) => {
+        target[key] = val;
+        // Update the Vue ref to trigger reactivity
+        propertyRefs[prop].value = clone(propertyRefs[prop].value);
+        // Update MobX immediately
+        mobxObject[prop] = clone(propertyRefs[prop].value);
+        return true;
+      }
+    });
+  };
+
+  // ---- properties (two-way) -------------------------------------------------
+  const propertyRefs = {};
+  
+  members.properties.forEach(prop => {
+    propertyRefs[prop] = ref(toJS(mobxObject[prop]));
+
+    Object.defineProperty(vueState, prop, {
+      get: () => {
+        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 value;
+      },
+      set: allowDirectMutation
+        ? (value) => {
+            // Update Vue ref
+            const cloned = clone(value);
+            if (!isEqual(propertyRefs[prop].value, cloned)) {
+              propertyRefs[prop].value = cloned;
+            }
+            // ALSO update MobX immediately (synchronous)
+            if (!isEqual(mobxObject[prop], cloned)) {
+              mobxObject[prop] = cloned;
+            }
+          }
+        : () => warnDirectMutation(prop),
+      enumerable: true,
+      configurable: true,
+    });
+
+  });
+
+  // ---- getters and setters (handle both computed and two-way binding) ------
+  const getterRefs = {};
+  const setterRefs = {};
+
+  // 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
+  getterSetterPairs.forEach(prop => {
+    // Get initial value from getter
+    let initialValue;
+    try {
+      initialValue = toJS(mobxObject[prop]);
+    } catch (error) {
+      initialValue = undefined;
+    }
+    getterRefs[prop] = ref(initialValue);
+    setterRefs[prop] = ref(initialValue);
+
+    Object.defineProperty(vueState, prop, {
+      get: () => getterRefs[prop].value,
+      set: allowDirectMutation
+        ? (value) => {
+            // Update both refs
+            setterRefs[prop].value = value;
+            // Call the MobX setter immediately
+            try {
+              mobxObject[prop] = value;
+              // The getter ref will be updated by the reaction
+            } catch (error) {
+              console.warn(`Failed to set property '${prop}':`, error);
+            }
+          }
+        : () => warnDirectMutation(prop),
+      enumerable: true,
+      configurable: true,
+    });
+  });
+
+  // Getter-only properties: read-only computed
+  gettersOnly.forEach(prop => {
+    // Safely get initial value of computed property, handle errors gracefully
+    let initialValue;
+    try {
+      initialValue = toJS(mobxObject[prop]);
+    } catch (error) {
+      // If computed property throws during initialization (e.g., accessing null.property),
+      // set initial value to undefined and let the reaction handle updates later
+      initialValue = undefined;
+    }
+    getterRefs[prop] = ref(initialValue);
+
+    Object.defineProperty(vueState, prop, {
+      get: () => getterRefs[prop].value,
+      set: () => {
+        throw new Error(`Cannot assign to computed property '${prop}'`)
+      },
+      enumerable: true,
+      configurable: true,
+    });
+  });
+
+  // Setter-only properties: write-only
+  settersOnly.forEach(prop => {
+    // For setter-only properties, track the last set value
+    setterRefs[prop] = ref(undefined);
+
+    Object.defineProperty(vueState, prop, {
+      get: () => setterRefs[prop].value,
+      set: allowDirectMutation
+        ? (value) => {
+            // Update the setter ref
+            setterRefs[prop].value = value;
+            
+            // Call the MobX setter immediately
+            try {
+              mobxObject[prop] = value;
+            } catch (error) {
+              console.warn(`Failed to set property '${prop}':`, error);
+            }
+          }
+        : () => warnSetterMutation(prop),
+      enumerable: true,
+      configurable: true,
+    });
+  });
+
+  // ---- methods (bound) ------------------------------------------------------
+  members.methods.forEach(prop => {
+    // Cache the bound method to avoid creating new functions on every access
+    const boundMethod = mobxObject[prop].bind(mobxObject);
+    Object.defineProperty(vueState, prop, {
+      get: () => boundMethod,
+      set: () => warnMethodAssignment(prop),
+      enumerable: true,
+      configurable: true,
+    });
+  });
+
+  // ---- MobX → Vue: property observation ----------------------------------------
+  const subscriptions = [];
+
+  setupStandardPropertyObservers();
+
+  // Standard property observation implementation
+  function setupStandardPropertyObservers() {
+    // Use individual observe for each property to avoid circular reference issues
+    members.properties.forEach(prop => {
+      try {
+        const sub = observe(mobxObject, prop, (change) => {
+          if (!propertyRefs[prop]) return;
+          if (updatingFromVue.has(prop)) return; // avoid echo
+          updatingFromMobx.add(prop);
+          try {
+            const next = toJS(mobxObject[prop]);
+            if (!isEqual(propertyRefs[prop].value, next)) {
+              propertyRefs[prop].value = next;
+            }
+          } finally {
+            updatingFromMobx.delete(prop);
+          }
+        });
+        subscriptions.push(sub);
+      } catch (error) {
+        // Silently ignore non-observable properties
+      }
+    });
+
+    // For nested objects and arrays, use deepObserve to handle deep changes
+    // This handles both object properties and array mutations
+    members.properties.forEach(prop => {
+      const value = mobxObject[prop];
+      if (value && typeof value === 'object') { // Include both objects AND arrays
+        try {
+          const sub = deepObserve(value, (change, path) => {
+            if (!propertyRefs[prop]) return;
+            if (updatingFromVue.has(prop)) return; // avoid echo
+            updatingFromMobx.add(prop);
+            try {
+              const next = toJS(mobxObject[prop]);
+              if (!isEqual(propertyRefs[prop].value, next)) {
+                propertyRefs[prop].value = next;
+              }
+            } finally {
+              updatingFromMobx.delete(prop);
+            }
+          });
+          subscriptions.push(sub);
+        } catch (error) {
+          // Silently ignore if deepObserve fails (e.g., circular references in nested objects)
+        }
+      }
+    });
+  }
+
+  // Getters: keep them in sync via reaction (both getter-only and getter/setter pairs)
+  [...gettersOnly, ...getterSetterPairs].forEach(prop => {
+    const sub = reaction(
+      () => {
+        try {
+          return toJS(mobxObject[prop]);
+        } catch (error) {
+          // If computed property throws (e.g., accessing null.property), return undefined
+          return undefined;
+        }
+      },
+      (next) => {
+        if (!getterRefs[prop]) return;
+        if (!isEqual(getterRefs[prop].value, next)) {
+          getterRefs[prop].value = next;
+        }
+      }
+    );
+    subscriptions.push(sub);
+  });
+
+  // Cleanup
+  onUnmounted(() => {
+    subscriptions.forEach(unsub => {
+      try {
+        if (typeof unsub === 'function') {
+          unsub();
+        }
+      } catch {
+        // Silently ignore cleanup errors
+      }
+    });
+  });
+
+  return vueState;
+}
+
+/**
+ * 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
+ */
+export function usePresenterState(presenter, options = {}) {
+  return useMobxBridge(presenter, options);
+}