docs: Enhance VDOM architecture documentation (#8841)

Author: tobiu

src/manager/VDomUpdate.mjs

@@ -15,6 +15,11 @@ import Collection from '../collection/Base.mjs';
  *    more focused data for the VDOM worker to process. While the amount of final DOM
  *    modifications remains the same, this aggregation is key to performance.
  *
+ *    **Teleportation (Disjoint Updates):** The manager now supports processing multiple
+ *    disjoint components in a single "Teleportation" batch. This allows deep descendants
+ *    to update in parallel with their ancestors without requiring the ancestor to "bridge"
+ *    the gap, eliminating O(N) overhead for deep updates.
+ *
  * 2. **Asynchronous Flow Control:** Manages the asynchronous nature of VDOM updates, which
  *    are often processed in a worker thread. It ensures that code awaiting an update
  *    (e.g., via a returned Promise) is correctly notified upon completion.
@@ -151,6 +156,13 @@ class VDomUpdate extends Collection {
      * Executes all callbacks associated with a completed VDOM update for a given `ownerId`.
      * This method first processes callbacks for any children that were merged into this
      * update cycle, then executes the callbacks for the `ownerId` itself.
+     *
+     * **Teleportation / Batch Support:**
+     * The `processedChildIds` argument is crucial for Disjoint Updates. It ensures we only
+     * execute callbacks for children that were *actually* included in the VDOM payload.
+     * Children that were filtered out (e.g. due to collisions with a parent update) will
+     * NOT have their callbacks executed here; they will be handled by the covering parent's callback.
+     *
      * @param {String} ownerId The `id` of the component whose update has just completed.
      * @param {Object} [data]  Optional data to pass to the callbacks.
      * @param {Set<String>|null} [processedChildIds] IDs of children actually included in this update.

src/mixin/VdomLifecycle.mjs

@@ -190,7 +190,21 @@ class VdomLifecycle extends Base {
     }
 
     /**
-     * Internal method to send update requests to the vdom worker
+     * Internal method to send update requests to the vdom worker.
+     *
+     * **Teleportation / Batched Disjoint Updates:**
+     * This method implements the core logic for "Teleportation". Instead of merging child updates
+     * into the parent's VDOM tree (which requires expanding the parent's tree to reach the child),
+     * we collect all merged child updates and send them as a **batch of disjoint payloads**.
+     *
+     * 1. **Recursive Collection:** We recursively collect all `mergedChildIds` from the component
+     *    and its descendants.
+     * 2. **Disjoint Payloads:** For each component in the batch, we generate a "self-only" VDOM
+     *    payload (`updateDepth: 1`). This allows the VDOM engine to update the child directly
+     *    without needing the parent to "bridge" to it.
+     * 3. **Collision Filtering:** We filter out child updates that are already covered by a
+     *    parent update in the same batch (e.g., if the parent is doing a full tree update).
+     *
      * @param {function} [resolve] used by promiseUpdate()
      * @param {function} [reject] used by promiseUpdate()
      * @private
@@ -218,7 +232,7 @@ class VdomLifecycle extends Base {
                 const component = Neo.getComponent(componentId);
                 if (!component || component.isDestroyed) return;
 
-                // Skip unmounted components. They will be expanded by the Parent's TreeBuilder (Hybrid/Leapfrog)
+                // Skip unmounted components. They will be expanded by the Parent's TreeBuilder
                 // and handled via the Parent's resolveVdomUpdate -> syncVnodeTree.
                 if (!component.vnode) return;
 
@@ -599,8 +613,8 @@ class VdomLifecycle extends Base {
      *
      * **Recursive Traversal:**
      * This method recursively walks up the component tree (`distance + 1`). This enables
-     * transitive merging (Grandchild -> Child -> Parent) and leapfrog merging (skipping
-     * clean parents).
+     * transitive merging (Grandchild -> Child -> Parent) and merging into ancestors even
+     * if intermediate parents are not updating.
      *
      * @param {String} parentId=this.parentId
      * @param {Function} [resolve] gets passed by updateVdom()
@@ -820,7 +834,7 @@ class VdomLifecycle extends Base {
         // The manager will ensure it's called when the appropriate update cycle completes.
         resolve && VDomUpdate.addPromiseCallback(me.id, resolve);
 
-        // Attempt to merge into a parent's update cycle (Teleportation/Leapfrog).
+        // Attempt to merge into a parent's update cycle.
         // We do this even if silent, to ensure we catch the bus if a parent is departing.
         if (me.mergeIntoParentUpdate(parentId)) {
             me.needsVdomUpdate = true;

src/vdom/Helper.mjs

@@ -779,6 +779,10 @@ class Helper extends Base {
 
     /**
      * Processes a map of updates sequentially and aggregates the results.
+     * This method is the core of the "Teleportation" / Disjoint Updates architecture.
+     * Instead of building a single bridged VDOM tree, we process multiple components
+     * as separate, disjoint updates in a single batch.
+     *
      * @param {Object} data
      * @param {Object} data.updates A map of update config objects: {componentId: updateOpts}
      * @returns {Object} { deltas: Object[], vnodes: Object }

test/playwright/unit/vdom/RealWorldUpdates.spec.mjs

@@ -89,6 +89,18 @@ class TestChildContainer extends Container {
 }
 TestChildContainer = Neo.setupClass(TestChildContainer);
 
+/**
+ * @summary Verification tests for Batched Disjoint VDOM Updates ("Teleportation").
+ *
+ * These tests cover complex, real-world update scenarios to ensure the VDOM engine
+ * correctly handles:
+ * 1. **Disjoint Updates:** Parent and Child updating in parallel without "Bridge Path" interference.
+ * 2. **Recursive Merging:** Grandchild merging into Parent's batch (skipping Child).
+ * 3. **Ghost Updates:** Updates triggered by components that are being removed/detached in the same tick.
+ * 4. **Structural Changes:** Inserts and removes within batched updates.
+ *
+ * This suite is the primary regression guard for the Teleportation architecture.
+ */
 test.describe('Neo.vdom.VdomRealWorldUpdates', () => {
     let parent, child, grandchild, testRun = 0;