v0.19.0

CuboMX Release 0.19.0: Asynchronous Swaps & Guaranteed Hydration

This release introduces a fundamental improvement to the framework’s core swapping mechanism, making it fully asynchronous. This change enhances reliability and predictability when dynamically updating the DOM.

---

💥 Breaking Changes

CuboMX.swap() is Now Asynchronous

To eliminate race conditions and guarantee that new content is fully hydrated and reactive before your code continues, the CuboMX.swap() function now returns a Promise.

What this means: You must now use await when calling CuboMX.swap(). This ensures that the DOM manipulation is complete and all associated CuboMX components have been initialized.

Why this is better: When the Promise returned by swap() resolves, you are guaranteed that the new HTML is in the DOM and fully reactive. This makes your code more robust and predictable, especially in complex scenarios like SPA-style navigation.

Migration Guide:

Simply add await to your CuboMX.swap() calls.

Old (Synchronous) Code:

// This no longer works as expected
CuboMX.swap(newHtml, [{ target: "#my-div" }]);
// The next line might execute before the new content is hydrated

New (Asynchronous) Code:

// Use await to ensure the operation is complete
await CuboMX.swap(newHtml, [{ target: "#my-div" }]);
// You can now safely interact with the new, fully hydrated content

---

🛠️ Improvements & Bug Fixes

Guaranteed Hydration for ArrayItems

The hydration mechanism for items added to an ArrayItems proxy has been strengthened. It now explicitly requires a valid component proxy to be resolved, throwing an error if hydration fails. This prevents items from being added to the DOM without becoming reactive.

MX-Redirect Stability

Fixed a critical bug where MX-Redirect requests would cause tests to time out.

• CuboMX.request(): Now correctly awaits the swap() operation during a redirect, ensuring the request only completes after the page has been fully updated.
• MutationObserver: The observer is now attached to document.documentElement instead of document.body. This prevents the observer from being detached when the <body> tag is replaced, ensuring that CuboMX continues to detect DOM changes reliably during full-page swaps.

Test Suite Updates

The test suite for CuboMX.swap() has been updated to reflect the new asynchronous behavior, ensuring all tests pass and the feature is well-covered.