Add the mutable vdom & state concept to all 3 guides #7034

Author: tobiu

learn/comparisons/NeoVsAngular.md

@@ -36,9 +36,11 @@ This is where the two frameworks diverge significantly, each offering unique tra
     *   **VDOM:** Angular does not use a traditional Virtual DOM in the same way React does. Its Ivy renderer directly updates the DOM based on detected changes.
     *   **Performance Consideration (Two-Way Binding & Direct DOM Access):** Angular's two-way data binding, while convenient, inherently ties the application's data model directly to the DOM. This often leads to frequent DOM read/write operations. Since **DOM read/write access is significantly slower (often 20x or more) compared to pure JavaScript logic**, this can cause performance bottlenecks and UI jank in complex applications with many bindings, as each change detection cycle can trigger a cascade of expensive DOM manipulations on the Main Thread.
     *   **DOM Pollution:** Angular often adds numerous internal `data-set` attributes to the real DOM for its own tracking and debugging purposes. While functional, this can lead to a less clean and more verbose DOM structure.
+    *   **Immutability Considerations:** While Angular doesn't enforce immutability, performance optimizations like `OnPush` change detection often benefit significantly from immutable data patterns. This can introduce a cognitive burden for developers to manage data immutably for optimal performance.
 
 *   **Neo.mjs: Virtual DOM (Off-Main-Thread Diffing & Fine-Grained Reactivity)**
-    *   Neo.mjs uses a Virtual DOM. Your `createVdom()` method (within functional components) returns a plain JavaScript object representing the desired UI structure. **This VDOM is defined using simple nested JavaScript objects and arrays, akin to a JSON-like description of the DOM.**
+    *   Neo.mjs uses a Virtual DOM. Your `createVdom()` method (within functional components) returns a plain JavaScript object representing the desired UI structure. **This VDOM is defined using simple nested JavaScript objects and arrays, akin to a JSON-like description of the DOM. Crucially, Neo.mjs's VDOM objects are mutable.**
+    *   **Mutable VDOM & State (By Design):** Unlike Angular, Neo.mjs embraces mutability for both its VDOM and its reactive state (configs and state provider data). Developers can directly modify properties of VDOM objects or state data. This is a deliberate design choice enabled by Neo.mjs's worker architecture. The App Worker sends a *snapshot* (a serialized copy) of the VDOM (or relevant parts of state) to the VDom Worker or Main Thread for diffing or rendering. This allows developers the convenience of direct mutation without sacrificing performance, as the framework handles the efficient snapshotting and communication across workers.
     *   **Off-Main-Thread Diffing:** The VDOM diffing process occurs in a dedicated **VDom Worker**, offloading this computational work from the Main Thread.
     *   **Surgical Direct DOM API Updates (`Neo.main.DeltaUpdates` & `DomApiRenderer`):** The VDom Worker sends "deltas" (minimal change instructions) to the Main Thread. `Neo.main.DeltaUpdates` then applies these changes using direct DOM APIs.
     *   **Fine-Grained Reactivity & Decoupled DOM:** Neo.mjs's `Neo.core.Effect` system precisely tracks dependencies. When a reactive config or state changes, only the specific `createVdom()` effect that depends on it re-executes, leading to highly targeted VDOM updates. Crucially, Neo.mjs components are **completely decoupled from the real DOM**; they reside in the App Worker and never directly read from or write to the DOM. This fundamental architectural choice eliminates the performance bottleneck associated with frequent DOM access, ensuring Main Thread responsiveness and predictable performance. Neo.mjs also strives to keep the real DOM as clean as possible, avoiding the addition of numerous internal framework-specific attributes.

learn/comparisons/NeoVsReact.md

@@ -33,9 +33,11 @@ This is where the two frameworks diverge significantly, each offering unique tra
 *   **React: Virtual DOM (Reconciliation & Diffing on Main Thread)**
     *   React uses a Virtual DOM. When state or props change, React builds a new VDOM tree, compares it with the previous one (reconciliation), and calculates the minimal set of changes (diffing). These changes are then applied to the real DOM.
     *   **VDOM Definition:** Primarily uses JSX, which is a syntax extension for JavaScript that allows you to write HTML-like structures directly within your JavaScript code. JSX requires a build step (e.g., Babel) to transpile it into `React.createElement` calls.
+    *   **Immutability:** React's VDOM is treated as immutable. When state or props change, a *new* VDOM tree is created, and React's reconciler determines the differences. Developers are encouraged to treat state as immutable, often using spread operators or `Object.assign` to create new object references when updating state.
 
 *   **Neo.mjs: Virtual DOM (Off-Main-Thread Diffing & Optimized Direct DOM API Updates)**
-    *   Neo.mjs also uses a Virtual DOM. Your `createVdom()` method (within functional components) returns a plain JavaScript object representing the desired UI structure. **This VDOM is defined using simple nested JavaScript objects and arrays, akin to a JSON-like description of the DOM.**
+    *   Neo.mjs also uses a Virtual DOM. Your `createVdom()` method (within functional components) returns a plain JavaScript object representing the desired UI structure. **This VDOM is defined using simple nested JavaScript objects and arrays, akin to a JSON-like description of the DOM. Crucially, Neo.mjs's VDOM objects are mutable.**
+    *   **Mutable VDOM & State (By Design):** Unlike React, Neo.mjs embraces mutability for both its VDOM and its reactive state (configs and state provider data). Developers can directly modify properties of VDOM objects or state data. This is a deliberate design choice enabled by Neo.mjs's worker architecture. The App Worker sends a *snapshot* (a serialized copy) of the VDOM (or relevant parts of state) to the VDom Worker or Main Thread for diffing or rendering. This allows developers the convenience of direct mutation without sacrificing performance, as the framework handles the efficient snapshotting and communication across workers.
     *   **Off-Main-Thread Diffing:** The VDOM diffing process (calculating the minimal changes between the old and new VDOM) occurs in a dedicated **VDom Worker**, offloading this computational work from the Main Thread.
     *   **Surgical Direct DOM API Updates (`Neo.main.DeltaUpdates` & `DomApiRenderer`):** The VDom Worker sends "deltas" (minimal change instructions) to the Main Thread. `Neo.main.DeltaUpdates` then applies these changes using direct DOM APIs. For inserting new subtrees, `DomApiRenderer` builds detached `DocumentFragments` and inserts them in a single, atomic operation. For updates to existing nodes, `DeltaUpdates` directly manipulates attributes, classes, styles, and content using native DOM methods.
     *   **Benefit:** This approach minimizes costly browser reflows/repaints and enhances security (e.g., against XSS) by avoiding `innerHTML` for updates.

learn/comparisons/NeoVsSolid.md

@@ -22,12 +22,13 @@ This is where the two frameworks diverge significantly, each offering unique tra
     *   Solid.js compiles its JSX (or tagged template literals) into highly optimized, imperative JavaScript instructions. These instructions directly create and manipulate the real browser DOM.
     *   When a signal updates, Solid knows precisely which DOM nodes need to change and updates them surgically, without any intermediate Virtual DOM diffing step.
     *   **Benefit:** This "no VDOM" approach often leads to industry-leading performance benchmarks for UI updates, as it eliminates the overhead of VDOM reconciliation.
+    *   **Immutability:** Solid's signals represent immutable values. When a signal is updated, a new value is set, and the reactive graph propagates this new value to dependent computations and DOM updates.
 
 *   **Neo.mjs: Virtual DOM (with Optimized Direct DOM API Updates)**
-    *   Neo.mjs utilizes a Virtual DOM. Your `createVdom()` method (within functional components) returns a plain JavaScript object representing the desired UI structure. **This VDOM is defined using simple nested JavaScript objects and arrays, akin to a JSON-like description of the DOM.**
-    *   **Stable VDOM Object:** Neo.mjs's approach is unique: the component's `vdom` property is a **stable object** that gets mutated. When `createVdom()` re-runs, the new VDOM structure is intelligently merged into this existing `vdom` object.
+    *   Neo.mjs utilizes a Virtual DOM. Your `createVdom()` method (within functional components) returns a plain JavaScript object representing the desired UI structure. **This VDOM is defined using simple nested JavaScript objects and arrays, akin to a JSON-like description of the DOM. Crucially, Neo.mjs's VDOM objects are mutable.**
+    *   **Mutable VDOM & State (By Design):** Unlike Solid.js's immutable signals, Neo.mjs embraces mutability for both its VDOM and its reactive state (configs and state provider data). Developers can directly modify properties of VDOM objects or state data. This is a deliberate design choice enabled by Neo.mjs's worker architecture. The App Worker sends a *snapshot* (a serialized copy) of the VDOM (or relevant parts of state) to the VDom Worker or Main Thread for diffing or rendering. This allows developers the convenience of direct mutation without sacrificing performance, as the framework handles the efficient snapshotting and communication across workers.
     *   **Off-Main-Thread Diffing:** The VDOM diffing process (calculating the minimal changes between the old and new VDOM) occurs in a dedicated **VDom Worker**, offloading this computational work from the Main Thread.
-    *   **Surgical Direct DOM API Updates (`Neo.main.DeltaUpdates` & `DomApiRenderer`):** The VDom Worker sends "deltas" (minimal change instructions) to the Main Thread. `Neo.main.DeltaUpdates` then applies these changes using direct DOM APIs. For inserting new subtrees, `DomApiRenderer` builds detached `DocumentFragments` and inserts them in a single, atomic operation. For updates to existing nodes, `DeltaUpdates` directly manipulates attributes, classes, styles, and content using native DOM methods (`setAttribute`, `classList.add/remove`, `node.style.setProperty`, `node.textContent`, etc.).
+    *   **Surgical Direct DOM API Updates (`Neo.main.DeltaUpdates` & `DomApiRenderer`):** The VDom Worker sends "deltas" (minimal change instructions) to the Main Thread. `Neo.main.DeltaUpdates` then applies these changes using direct DOM APIs. For inserting new subtrees, `DomApiRenderer` builds detached `DocumentFragments` and inserts them in a single, atomic operation. For updates to existing nodes, `DeltaUpdates` directly manipulates attributes, classes, styles, and content using native DOM methods.
     *   **Benefit:** While it still has VDOM diffing overhead (unlike Solid), this overhead is offloaded. The Main Thread receives highly optimized, surgical instructions for direct DOM manipulation, minimizing costly browser reflows/repaints and enhancing security (e.g., against XSS).
 
 ### 2. Component Execution Model