Frontmatter
| id | 8825 |
| title | Docs: Document Scoped VDOM Update Rationale in VdomLifecycle |
| state | Closed |
| labels | documentationai |
| assignees | tobiu |
| createdAt | Jan 20, 2026, 10:22 AM |
| updatedAt | Jan 20, 2026, 10:30 AM |
| githubUrl | https://github.com/neomjs/neo/issues/8825 |
| author | tobiu |
| commentsCount | 1 |
| parentIssue | null |
| subIssues | [] |
| subIssuesCompleted | 0 |
| subIssuesTotal | 0 |
| blockedBy | [] |
| blocking | [] |
| closedAt | Jan 20, 2026, 10:30 AM |
Docs: Document Scoped VDOM Update Rationale in VdomLifecycle
tobiu assigned to @tobiu on Jan 20, 2026, 10:30 AM
tobiu
Jan 20, 2026, 10:30 AM
Input from Gemini 3 Pro:
✦ I have enhanced the JSDoc for
hasUpdateCollisioninsrc/mixin/VdomLifecycle.mjs.Documentation Update:
- Explicitly documented the Scoped VDOM Update philosophy.
- Clarified that at
updateDepth: 1, the VDOM naturally contains unexpanded reference nodes for children.- Explained that this state ensures Parent and Child updates operate on disjoint DOM sets, making them collision-free and parallel-safe.
- Confirmed that
distance < updateDepth(e.g.,1 < 1False) is the correct logic to enforcing this separation.This serves as a definitive reference to prevent future regressions where agents might incorrectly assume collision at Depth 1.
tobiu closed this issue on Jan 20, 2026, 10:30 AM
The
VdomLifecyclemethodhasUpdateCollisionuses the<operator (e.g.,distance < updateDepth) to determine if a child update should merge into a parent update. This logic is critical for enabling Scoped VDOM Updates, but its rationale has been a source of confusion for AI agents, leading to regression loops.The Core Concept:
updateDepth: 1produces a VDOM tree that only contains its own structure and reference nodes (placeholders) for its children. It explicitly prunes the child's subtree.The Task: Enhance the JSDoc for
hasUpdateCollision(and potentially the class header ofVdomLifecycle) to explicitly document this "Disjoint/Scoped Update" philosophy. Use the rationale provided above to clearly explain why1 < 1(False) is the correct and intended behavior for preserving parallelism. This will serve as a permanent knowledge anchor for future development.