neo.mjs 10.2.1 → 10.3.1

package/.github/epic-functional-components.md

@@ -1,498 +0,0 @@
-# Epic: Functional Components
-
-## Motivation
-
-This initiative will establish a new, lightweight base class for components. This class will bypass the traditional `items` array and `layout` system. Instead, it will be driven by a central `Effect` that calls a VDOM-generating method (e.g., `createVdom()`) to declaratively build the component's UI based on its current state. This aligns with the reactive patterns of other popular frameworks and provides a more intuitive and familiar entry point for those developers.
-
-This epic will be broken down into several sub-tickets to implement this new component architecture in an iterative and isolated manner.
-
-Functional Components are an addition to, and not a replacement for declarative component trees based on `container.Base`: `items`.
-
----
-
-## Two Modes of Functional Component Definition
-
-Neo.mjs will offer two distinct ways to define functional components, catering to different developer preferences and needs. Both modes leverage the underlying `Neo.functional.component.Base` class and the `Neo.core.Effect` system for reactive rendering, but they provide different levels of abstraction and access to the framework's full power.
-
-### 1. Beginner Mode: Pure Function with Hooks (e.g., `Neo.functional.defineComponent`)
-
-This mode is designed for developers seeking a highly concise and familiar syntax, especially those coming from frameworks like React. Components are defined as plain JavaScript functions that return VDOM. State management is handled via dedicated hooks (e.g., `useConfig`).
-
-**Characteristics:**
--   **Concise Syntax:** Focus on the VDOM rendering logic.
--   **Hook-based State:** State and side effects are managed through `use` hooks.
--   **Simplified API:** Abstracts away class boilerplate.
--   **Tier 1 Reactivity:** Primarily leverages `Neo.core.Config` for reactive values and `Neo.core.Effect` for re-rendering.
--   **No Lifecycle Hooks:** Does not expose `beforeGet`, `beforeSet`, or `afterSet` lifecycle hooks directly on the component definition, as these are tied to the class-based `static config` system.
-
-### 2. Medium Mode: Class-based Functional Component (Extending `Neo.functional.component.Base`)
-
-This mode provides direct access to the underlying `Neo.functional.component.Base` class, allowing developers to define components using `static config` properties. This offers a more explicit and powerful way to define reactive components within the Neo.mjs class system.
-
-**Characteristics:**
--   **Explicit Configs:** State is defined via `static config` properties.
--   **Full Two-Tier Reactivity:** Access to both `Neo.core.Config` (Tier 1) and the `autoGenerateGetSet` mechanism (Tier 2), including `afterSet` lifecycle hooks for imperative side effects.
--   **Class-based Structure:** Familiar to developers comfortable with class-based component patterns.
-
----
-
-## Sub-Ticket: Create `Neo.component.mixin.VdomLifecycle`
-
-**Status:** Done
-
-### 1. Summary
-
-Create a new mixin named `Neo.component.mixin.VdomLifecycle`. This mixin will encapsulate the core VDOM rendering engine logic currently located in `Neo.component.Base`. This is the foundational step for enabling the new functional component base class and for cleaning up the existing component architecture.
-
-### 2. Rationale
-
-The new reactivity layer introduced in v10, centered around `Neo.core.Config` and `Neo.core.Effect`, allows for a highly efficient and declarative component model. The `src/button/Effect.mjs` class serves as a proof-of-concept for this pattern, where a single `Effect` replaces dozens of imperative `afterSet` hooks.
-
-This new, simpler component architecture relies on the ability to compose features using Mixins. With the recent enhancement enabling mixins to merge their `static config` into a consuming class, we can now create self-contained "feature mixins" (e.g., for VDOM management).
-
-Extracting the VDOM logic from `component.Base` into `Neo.component.mixin.VdomLifecycle` is the foundational step. It will:
-- Improve code modularity and separation of concerns.
-- Slim down `component.Base`, making it easier to understand and maintain.
-- Provide a reusable piece of core machinery that can be used by the new `FunctionalComponentBase` without inheriting all of `component.Base`.
-
-### 3. Scope & Implementation Plan
-
-1.  **Create File:** Create a new file at `src/mixin/VdomLifecycle.mjs`.
-2.  **Identify & Move Logic:** Move the properties and methods related to the VDOM rendering engine from `src/component/Base.mjs` into `Neo.component.mixin.VdomLifecycle`. The list of candidates we previously identified will be used as the basis for this refactoring.
-3.  **Refactor `component.Base`:** Modify `src/component/Base.mjs` to use the new `VdomLifecycle` mixin, ensuring all existing functionality remains intact.
-
-### 4. Definition of Done
-
--   `Neo.component.mixin.VdomLifecycle` is created and contains the extracted VDOM logic.
--   `Neo.component.Base` uses the new mixin.
--   All existing component-related tests pass without regression, confirming the refactoring is successful.
-
----
-
-## Sub-Ticket: Create `Neo.functional.component.Base`
-
-**Status:** Done
-
-### 1. Summary
-
-Create a new base class, `Neo.functional.component.Base`, which will serve as the foundational class for all functional components. This class provides the core reactive rendering mechanism and acts as the underlying base for both class-based functional components and the simpler, function-based "beginner mode" components.
-
-### 2. Rationale
-
-The primary goal of the Functional Components epic is to provide a simpler entry point into the Neo.mjs ecosystem while also offering the full power of its reactivity. This base class achieves this by providing a minimal, modern API for creating components, directly appealing to developers familiar with frameworks like React and Vue, and serving as the common foundation for different component definition styles.
-
-### 3. Scope & Implementation Plan
-
-1.  **Create File:** Create a new file at `src/functional/component/Base.mjs`.
-2.  **Class Definition:**
-    *   The class will extend `Neo.core.Base`.
-    *   It will use the `Neo.component.mixin.VdomLifecycle` (created in the prerequisite ticket).
-    *   It will **not** extend `Neo.component.Base` or `Neo.container.Base`.
-3.  **Core API:**
-    *   It will introduce a new method for developers to implement: `createVdom()`. This method is responsible for returning the component's VDOM structure based on its current configs (state).
-    *   In its `construct()` method, it will create a `Neo.core.Effect`. This effect will wrap a call to `this.createVdom()` and assign the result to `this.vdom`. This ensures that any time a config used within `createVdom()` is changed, the component automatically re-renders.
-
-### 4. Example Usage (Class-based Functional Component)
-
-```javascript
-import FunctionalBase from 'neo/functional/component/Base.mjs';
-
-class MyFunctionalButton extends FunctionalBase {
-    static config = {
-        className: 'MyApp.MyFunctionalButton',
-        text_    : 'Click Me'
-    }
-
-    createVdom() {
-        return {
-            tag : 'button',
-            text: this.text
-        };
-    }
-}
-
-// An instance of this component would render a button and
-// automatically update its text whenever `myButton.text = 'new text'` is called.
-```
-
-### 5. Definition of Done
-
--   `src/functional/component/Base.mjs` is created.
--   The class works as described, using `VdomLifecycle` and a central `Effect`.
--   A basic test case is created to verify that a simple `FunctionalBase` component can be rendered and updates when its configs change.
-
----
-
-## Sub-Ticket: Create `Neo.functional.useConfig` Hook
-
-**Status:** In Progress
-
-### 1. Summary
-
-Implement a `useConfig` hook for functional components, allowing developers to manage reactive state within their "render" functions in a React-like fashion.
-
-### 2. Rationale
-
-This hook provides a simplified entry point for developers familiar with `useState` from other frameworks. It leverages Neo.mjs's Tier 1 reactivity (`Neo.core.Config`) for state management without requiring class-based config definitions, making it ideal for the "beginner mode" functional component experience.
-
-### 3. Scope & Implementation Plan
-
-1.  **Create File:** Create `src/functional/useConfig.mjs`.
-2.  **Implement `useConfig`:** The hook will return a `[value, setter]` tuple. The `setter` will update an internal `Neo.core.Config` instance.
-3.  **Lifecycle Management:** Ensure the `Neo.core.Config` instance is properly managed (created, updated, destroyed) in relation to the functional component's lifecycle. This will likely involve associating the `core.Config` instance with the `Neo.functional.component.Base` instance that is executing the "render" function.
-
-### 4. Example Usage
-
-```javascript
-import { useConfig } from 'neo/functional/useConfig.mjs';
-import { defineComponent } from 'neo/functional/defineComponent.mjs'; // Assuming this exists
-
-const MyCounter = defineComponent({
-    className: 'MyApp.MyCounter',
-    createVdom: () => {
-        const [count, setCount] = useConfig(0);
-
-        return {
-            tag: 'button',
-            text: `Count: ${count}`,
-            listeners: {
-                click: () => setCount(count + 1)
-            }
-        };
-    }
-});
-```
-
-### 5. Definition of Done
-
--   `Neo.functional.useConfig` hook is implemented and tested.
--   It correctly creates and manages reactive state via `Neo.core.Config`.
--   Changes to the state trigger re-execution of the component's render function (via `Effect`).
-
----
-
-## Sub-Ticket: Create `Neo.functional.defineComponent` Factory
-
-**Status:** Done
-
-### 1. Summary
-
-Implement a factory function that allows developers to define functional components using a plain JavaScript function, abstracting away the underlying class creation.
-
-### 2. Rationale
-
-This factory further simplifies the developer experience for "beginner mode" functional components, making the syntax more concise and familiar to developers accustomed to functional component patterns in other frameworks. It acts as the bridge between a pure function definition and the underlying `Neo.functional.component.Base` class.
-
-### 3. Scope & Implementation Plan
-
-1.  **Create File:** Create `src/functional/defineComponent.mjs`.
-2.  **Implement `defineComponent`:** The factory will accept a configuration object (including `className`, optional `ntype`, and the `createVdom` function).
-3.  **Internal Class Generation:** Internally, `defineComponent` will create a new class that extends `Neo.functional.component.Base`. It will apply the provided `className` and `ntype` to this new class.
-4.  **`createVdom` Method Assignment:** The developer's `createVdom` function will be assigned as the `createVdom` method of the generated class's prototype.
-5.  **Integration with `useConfig`:** Ensure that the context (`this`) within the developer's `createVdom` function (when executed by the generated component instance) allows `useConfig` to correctly associate state with that instance.
-
-### 4. Example Usage
-
-```javascript
-import { defineComponent } from 'neo/functional/defineComponent.mjs';
-import { useConfig }       from 'neo/functional/useConfig.mjs';
-
-const MyGreeting = defineComponent({
-    className: 'MyApp.MyGreeting',
-    createVdom: (config) => {
-        const [name, setName] = useConfig('World');
-
-        return {
-            tag: 'div',
-            text: `Hello, ${name}!`,
-            listeners: {
-                click: () => setName(name === 'World' ? 'Neo.mjs' : 'World')
-            }
-        };
-    }
-});
-```
-
-### 5. Definition of Done
-
--   `Neo.functional.defineComponent` factory is implemented and tested.
--   It successfully generates functional component classes from plain functions.
--   Generated components correctly utilize `useConfig` for state management.
-
----
-
-# Sub-Ticket: Enhance `Neo.functional.component.Base` for Hook Support
-
-**Status:** Done
-
-## 1. Summary
-
-This ticket covers the foundational work on `Neo.functional.component.Base` to enable the hook system (`useConfig`, `useEvent`, etc.) for beginner-mode functional components. The key challenge was to allow external hook functions to manage state on a component instance without exposing that state through the public API.
-
-## 2. Rationale
-
-The initial implementation of `functional.component.Base` was a minimal class with a `createVdom` method driven by an `Effect`. To support hooks like React's `useState`, we needed a mechanism to:
-1.  Associate state (like `Config` instances) with a specific component instance.
-2.  Track the order of hook calls within a single `createVdom` execution.
-3.  Provide a way for external hook functions to access this internal state securely.
-
-Using protected properties (e.g., `_hooks`) was considered but deemed insufficient for true encapsulation. The chosen solution provides a robust, framework-private way to manage hook state.
-
-## 3. Scope & Implementation Plan
-
-1.  **Introduce Symbols for State:**
-    *   Create two `Symbol.for()` symbols: `hookIndexSymbol` and `hooksSymbol`.
-    *   These symbols act as unique keys for properties on the component instance, making them accessible to any module that knows the symbol, but keeping them off the public API.
-
-2.  **Initialize State in `FunctionalBase`:**
-    *   In the `construct()` method of `functional.component.Base`, use `Object.defineProperties` to add the symbol-keyed properties (`[hookIndexSymbol]` and `[hooksSymbol]`) to the component instance.
-    *   These properties are configured to be non-enumerable (`enumerable: false`) to further hide them from standard object iteration.
-    *   The `hookIndex` is reset to `0` at the beginning of every `vdomEffect` execution, ensuring a clean slate for each render.
-
-3.  **Component Registration:**
-    *   Implement the `afterSetId()` and `destroy()` methods to correctly register and unregister the functional component instance with `Neo.manager.Component`. This makes functional components discoverable via `Neo.getComponent()`, integrating them fully into the framework's component model.
-
-4.  **Link Effect to Component:**
-    *   Modify the `vdomEffect` creation to pass the component's ID (`this.id`) to the `Effect` constructor. This allows the `useConfig` hook to retrieve the currently rendering component instance by getting the active effect from `EffectManager` and looking up the component by its ID.
-
-## 4. Definition of Done
-
--   `functional.component.Base` is updated to use `Symbol.for()` to manage internal hook state.
--   The component correctly registers and unregisters itself with `ComponentManager`.
--   The `vdomEffect` is correctly associated with the component's ID.
--   The implementation provides the necessary foundation for the `useConfig` hook to function correctly.
-
-# Sub-Ticket: Enhance `Neo.core.Effect` Constructor
-
-**Status:** Done
-
-## 1. Summary
-
-This ticket covers a minor but important enhancement to the `Neo.core.Effect` class to support the functional component hook system.
-
-## 2. Rationale
-
-To allow hooks like `useConfig` to identify which component is currently rendering, we needed a way to link an active `Effect` back to its owner component. The cleanest, most decoupled way to achieve this was to add an optional `componentId` to the `Effect`'s constructor.
-
-Since `core.Effect` is a new class introduced in the v10 beta series, adding an optional parameter is a safe, non-breaking change.
-
-## 3. Scope & Implementation Plan
-
-1.  **Update `Effect` Constructor:**
-    *   Modify the `constructor` of `Neo.core.Effect` to accept an optional second parameter, `componentId`.
-    *   If `componentId` is provided, store it on a public `this.componentId` property on the effect instance.
-
-2.  **Update `FunctionalBase`:**
-    *   In `Neo.functional.component.Base`, update the creation of the `vdomEffect` to pass `this.id` as the second argument to the `Effect` constructor.
-
-## 4. Definition of Done
-
--   The `Neo.core.Effect` constructor is updated to accept an optional `componentId`.
--   `functional.component.Base` correctly passes its ID when creating its `vdomEffect`.
--   This change enables the `useConfig` hook to reliably get the current component instance.
-
-## Sub-Ticket: Create Interoperability Layer
-
-**Status:** To Do
-
-### 1. Summary
-
-Design and implement the mechanism that allows functional components to seamlessly host classic components (e.g., `Neo.grid.Container`) and vice-versa. This is critical for ensuring that developers can adopt the new functional paradigm without losing access to the existing library of powerful, classic components.
-
-### 2. Rationale
-
-A developer will inevitably need to mix and match component paradigms. For example, they might build the main structure of their application using new functional components but need to include a complex, data-driven component like the grid. Without a robust interoperability layer, this would be impossible, creating a fractured ecosystem.
-
-The core challenge is that functional components define children declaratively as part of a VDOM tree, while classic components are instantiated via `Neo.create()` and managed within an `items` array. We need to bridge this gap.
-
-### 3. Technical Challenges & Example
-
-Consider a `FunctionalBase` component trying to render a classic grid:
-
-```javascript
-// Inside a FunctionalBase component...
-createVdom() {
-    return {
-        tag: 'div',
-        cn: [
-            {tag: 'h1', text: 'My Classic Grid'},
-            {
-                // This is just a VDOM node, not an instance yet
-                module: Neo.grid.Container,
-                store: this.myStore,
-                columns: [...]
-            }
-        ]
-    };
-}
-```
-
-To make this work, the system (likely the `VdomLifecycle` mixin) must solve these problems when it processes the VDOM from `createVdom()`:
-
-1.  **Instantiation:** It must detect VDOM nodes that represent component definitions (e.g., via a `module` or `ntype` key) and automatically call `Neo.create()` to turn them into component instances. The logic inside `container.Base#createItem` is a good reference for this.
-2.  **Parent/Child Linking:** Once the classic component instance (the grid) is created, its `parentId` must be set to the `id` of the functional component that is rendering it. The `parent` property should also be correctly linked.
-3.  **Context Propagation:** This parent/child link is essential for context-aware features. The grid instance must be able to find its parent's controller or state provider via `getController()` and `getStateProvider()`.
-
-### 4. Scope & Implementation Plan
-
--   Enhance the `VdomLifecycle` mixin (or create a new helper) to traverse VDOM trees before they are sent to the renderer.
--   This traversal logic will identify and instantiate component definitions.
--   It will be responsible for setting `parentId` on the new child instances.
--   Create test cases that verify a functional component can successfully render a classic `container.Base` and that the classic container can find its functional parent's controller.
-
-### 5. Definition of Done
-
--   A functional component can successfully render a classic component defined within its `createVdom` method.
--   The classic component is correctly mounted in the DOM.
--   The classic component can access its functional parent via `this.parent`.
--   Context-aware features work across the boundary.
-
----
-
-## Sub-Ticket: Encourage Pure VDOM Effects
-
-**Status:** To Do
-
-### 1. Summary
-
-Define and promote best practices for writing "pure" VDOM-generating methods (e.g., `createVdom()`) within functional components. This ensures that the output of these methods is solely determined by their inputs (component configs) and that they produce no side effects, which is crucial for predictability and enabling future optimizations like memoization.
-
-### 2. Rationale
-
-The `Neo.core.Effect` system automatically re-executes VDOM-generating methods when their dependencies changes. For this system to be truly robust and performant, these methods should ideally be pure functions. Purity makes components easier to reason about, test, and debug. It also unlocks significant performance gains through memoization, as the output can be safely cached if inputs remain unchanged.
-
-### 3. Scope & Implementation Plan
-
-1.  **Define Purity Guidelines:** Clearly document what constitutes a "pure" VDOM-generating method in the context of Neo.mjs functional components. This includes avoiding direct DOM manipulation, external state modification, or reliance on non-reactive global state within `createVdom()`.
-2.  **Documentation:** Add a section to the functional component documentation explaining the concept of pure effects and why it's important.
-3.  **Linting/Static Analysis (Optional, Future):** Explore the possibility of adding linting rules or static analysis checks to identify potential impurities in `createVdom()` methods.
-
-### 4. Definition of Done
-
--   Clear guidelines for writing pure VDOM-generating methods are documented.
--   The documentation explains the benefits of purity and provides examples.
-
----
-
-## Sub-Ticket: Implement Effect Memoization
-
-**Status:** To Do
-
-### 1. Summary
-
-Enhance the `Neo.core.Effect` system (or provide a utility around it) to support memoization for VDOM-generating methods. This will significantly improve rendering performance by caching the VDOM output and preventing unnecessary re-executions when component configs (inputs) have not changed.
-
-### 2. Rationale
-
-Functional components, driven by `Neo.core.Effect`, re-generate their VDOM whenever a tracked config changes. While efficient, re-generating complex VDOM trees can still be computationally intensive. By memoizing the output of pure VDOM-generating methods, we can avoid redundant work. If the inputs to `createVdom()` are the same as the last execution, the cached VDOM can be returned directly, bypassing the VDOM generation and worker communication steps.
-
-### 3. Scope & Implementation Plan
-
-1.  **Memoization Mechanism:** Design and implement a caching layer for `Neo.core.Effect` instances (or a new `MemoizedEffect` class). This mechanism will:
-    *   Store the last computed VDOM output.
-    *   Efficiently compare current inputs (tracked configs) with previous inputs to determine if re-execution is necessary.
-    *   Invalidate the cache when inputs change.
-2.  **Integration:** Determine how developers will opt-in to memoization (e.g., a config on `FunctionalBase`, a decorator, or a utility function).
-3.  **Performance Testing:** Create benchmarks to measure the performance gains achieved through memoization, especially for components with complex VDOM structures or frequently updated but unchanged inputs.
-
-### 4. Definition of Done
-
--   A memoization mechanism for `Neo.core.Effect` is implemented.
--   Functional components can leverage memoization to improve rendering performance.
--   Performance benchmarks demonstrate measurable gains.
-
-## Sub-Ticket: Proof of Concept: Beginner Mode Functional Component
-
-**Status:** To Do
-
-### 1. Summary
-
-Create a simple, working example of a "Beginner Mode" functional component using `Neo.functional.defineComponent` and `Neo.functional.useConfig`.
-
-### 2. Rationale
-
-This PoC is crucial to validate the end-to-end developer experience for the simplified functional component definition. It will demonstrate that a developer can define a reactive component as a plain function, leveraging hooks for state, and that it renders correctly and updates reactively.
-
-### 3. Scope & Implementation Plan
-
-1.  **Create a Simple Component:** Define a basic functional component (e.g., a counter or a text display) using the `defineComponent` factory and `useConfig` hook.
-2.  **Render the Component:** Instantiate and render this component within a test environment or a minimal application.
-3.  **Verify Reactivity:** Ensure that changes to the state managed by `useConfig` correctly trigger re-renders of the component.
-
-### 4. Example Usage
-
-```javascript
-// In a component file (e.g., MyCounter.mjs)
-import { defineComponent } from 'neo/functional/defineComponent.mjs';
-import { useConfig }       from 'neo/functional/useConfig.mjs';
-
-export default defineComponent(function MyCounter(config) { // The functional component is now the function itself
-    const [count, setCount] = useConfig(0);
-
-    return {
-        tag: 'button',
-        text: `Count: ${count}`,
-        // No listeners property directly in VDOM for beginner mode
-    };
-});
-
-// In your app's MainView or a test file
-// Neo.create(MyCounter, { id: 'my-counter-instance' });
-```
-
-### 5. Definition of Done
-
--   A functional component defined as a plain function using `defineComponent` and `useConfig` is successfully rendered.
--   The component's state updates reactively, and these updates are reflected in the DOM.
-
----
-
-## Sub-Ticket: DOM Event Handling for Beginner Mode Functional Components
-
-**Status:** To Do
-
-### 1. Summary
-
-Explore and define the idiomatic way for developers to handle DOM events within "Beginner Mode" functional components, ensuring integration with Neo.mjs's powerful, separate DOM event engine.
-
-### 2. Rationale
-
-Unlike some other frameworks, Neo.mjs has a dedicated and highly optimized DOM event management system that operates separately from the VDOM. Directly embedding `listeners` within the VDOM (as is common in React) is not the Neo.mjs way and can lead to confusion and suboptimal performance. This ticket aims to define a clear, intuitive, and performant pattern for event handling in the simplified functional component mode.
-
-### 3. Scope & Implementation Plan
-
-1.  **Research Existing Patterns:** Analyze how Neo.mjs's DOM event engine (`Neo.manager.DomEvent`) is currently used and how it can be exposed in a functional, hook-like manner.
-2.  **Propose API:** Brainstorm and propose a `useEvent` hook or similar API that allows developers to attach event listeners to VDOM nodes declaratively within their `createVdom` function, without directly embedding `listeners` in the VDOM object.
-3.  **Integration:** Ensure the proposed API seamlessly integrates with the underlying `Neo.functional.component.Base` instance and the `Neo.manager.DomEvent`.
-4.  **Documentation:** Provide clear examples and guidelines for using the new event handling mechanism.
-
-### 4. Example Usage (Conceptual)
-
-```javascript
-import { defineComponent } from 'neo/functional/defineComponent.mjs';
-import { useConfig }       from 'neo/functional/useConfig.mjs';
-import { useEvent }        from 'neo/functional/useEvent.mjs'; // New hook
-
-export default defineComponent(function MyClickableDiv(config) {
-    const [count, setCount] = useConfig(0);
-
-    // Attach a click listener using the new hook
-    useEvent('click', (event) => {
-        setCount(count + 1);
-        console.log('Div clicked!', event);
-    });
-
-    return {
-        tag: 'div',
-        html: `Clicked ${count} times`,
-        // No listeners property directly in VDOM
-    };
-});
-```
-
-### 5. Definition of Done
-
--   A clear and idiomatic pattern for DOM event handling in "Beginner Mode" functional components is defined.
--   Necessary hooks/utilities (e.g., `useEvent`) are designed.
--   Documentation and examples are provided.
-

package/.github/ticket-asymmetric-vdom-updates.md

@@ -1,122 +0,0 @@
-# Epic: Optimized VDOM Update Strategies
-
-This epic outlines a series of surgical enhancements to the framework's VDOM update lifecycle. The goal is to improve the robustness and maintainability of the update mechanism by centralizing complex state for all collision scenarios, without altering the existing high-performance, real-time messaging architecture.
-
-## Core Problem: Distributed State
-The current VDOM update logic is extremely fast, but the state management for aggregated updates is complex and distributed across component instances. This is true for two scenarios:
-1.  **Pre-Flight Merges:** Multiple updates are queued in the same event loop tick and merged before a worker message is sent.
-2.  **In-Flight Collisions:** A child requests an update while its parent's update is already in-flight to the worker.
-
-In both cases, callbacks and post-update triggers are stored in scattered instance-level caches (`resolveUpdateCache`, `childUpdateCache`), making the lifecycle hard to debug and maintain.
-
-## Solution: Centralized Orchestration Manager
-
-We will introduce a new manager to act as a central orchestrator for all collision-related state. This approach preserves the existing high-performance update engine while drastically simplifying the `VdomLifecycle` mixin.
-
-### 1. New Class: `Neo.manager.VDomUpdate` (Orchestrator)
--   This new singleton manager will **not** schedule or delay updates.
--   It will contain two maps to manage all collision scenarios:
-    -   `mergedCallbackMap`: Stores callbacks and relevant update depth information for **pre-flight merges**.
-    -   `postUpdateQueueMap`: Stores child components that need updating after an **in-flight collision**.
--   It will expose methods to be called by the `VdomLifecycle` mixin:
-    -   `registerMerged(ownerId, childId, callbacks, childUpdateDepth, distance)`: Stores the child's callbacks, its `updateDepth`, and its `distance` from the owner.
-    -   `registerPostUpdate(ownerId, childId, resolve)`
-    -   `executeCallbacks(ownerId)`: This method will also be responsible for calculating the maximum required `updateDepth` for the `ownerId` (parent) based on the `childUpdateDepth` and `distance` of all merged children. It will then set the `ownerId` component's `updateDepth` to this calculated maximum *before* the parent's `update()` method is called (if `needsVdomUpdate` is true).
-    -   `triggerPostUpdates(ownerId)`
-
-### 2. `VdomLifecycle.mjs` Refactoring
--   The core, high-performance update logic (`updateVdom`, collision detection) will remain.
--   **Pre-Flight Merge:** When an update is merged (e.g., in `mergeIntoParentUpdate()`), it will now call `Neo.manager.VDomUpdate.registerMerged(parent.id, me.id, me.resolveUpdateCache, me.updateDepth, distance)` instead of manipulating local caches.
--   **In-Flight Collision:** When an update collides with an in-flight parent (in `isParentUpdating()`), it will call `Neo.manager.VDomUpdate.registerPostUpdate(...)`. The child component will still set its own `needsVdomUpdate = true` and hold its own callback in its `resolveUpdateCache` for the update it will eventually run.
--   **On Update Completion:** When a root update cycle finishes, its `then()` block will call both `manager.executeCallbacks(this.id)` and `manager.triggerPostUpdates(this.id)`.
--   This change allows for the complete removal of the complex `childUpdateCache` property and simplifies the logic around `resolveUpdateCache`.
-
-### 3. Asymmetric VDOM Serialization (`ComponentManager.mjs`)
--   This part of the plan remains crucial and unchanged.
--   `getVdomTree()` and `getVnodeTree()` will be refactored to honor the `updateDepth` of each individual component.
--   If a child component is excluded from an update, a lightweight placeholder object `{componentId: 'neo-ignore'}` will be inserted into the tree to preserve its structural integrity.
-
-### 4. VDOM Worker Enhancement (`vdom/Helper.mjs`)
--   The VDOM worker's `createDeltas()` method will be enhanced to recognize the `neo-ignore` placeholder. When it encounters this node, it will skip the diffing process, leaving the corresponding DOM element untouched.
-
-### 5. Testing Strategy
-Given the architectural significance of these changes, a comprehensive testing strategy is required. Since the test environment runs in a single thread (main), the strategy will be:
-
-1.  **Unit Test Environment Setup:**
-    -   The test suite will import all necessary classes directly into the main thread: `vdom.Helper`, `manager.VDomUpdate`, and all relevant components and containers.
-    -   Components will be instantiated in a non-rendering mode (`preventDOM: true` or a similar mechanism) to avoid any interaction with the actual DOM.
-
-2.  **Validation Points:**
-    -   **Aggregation Logic:** Create complex scenarios with nested components triggering updates simultaneously to verify that the new `VDomUpdate` manager correctly handles both pre-flight and in-flight collisions.
-    -   **Delta Correctness:** After a test update cycle, inspect the generated `deltas` array to ensure it is correct and that the `neo-ignore` placeholder is working as expected.
-    -   **VNode Redistribution:** Verify that after an update, the new `vnode` is correctly passed down and synchronized to all relevant child components.
-    -   **Callback Execution:** Ensure that all `resolve` callbacks from merged and queued updates are executed correctly and exactly once.
-
-3.  **Benchmarking:**
-    -   A dedicated feature branch will be used for this epic.
-    -   Create a suite of performance tests that simulate high-frequency updates on complex component trees.
-    -   Run these benchmarks on both the `main` branch (old implementation) and the feature branch (new implementation) to rigorously compare performance and ensure there are no regressions.
-
-This final, refined approach provides the best of all worlds: it fixes the code complexity and maintainability issues by centralizing all collision-related state, while fully preserving the framework's proven, real-time performance characteristics.
-
-## Implementation Progress
-
-**Status:** Foundational work complete. Documentation and a regression test suite are in place, and key framework APIs have been enhanced.
-
-### 1. Documentation & Test Suite
-
-Two crucial files have been created to guide and validate this epic:
-
--   **Epic Ticket (`.github/ticket-asymmetric-vdom-updates.md`):** This central document outlines the problem, defines the solution, and tracks our progress.
--   **`VdomAsymmetricUpdates.mjs`:** A low-level unit test that directly validates the core logic of the new `VDomUpdate` manager and `TreeBuilder`. It simulates asymmetric updates with mock components to ensure the delta generation is correct.
--   **`VdomRealWorldUpdates.mjs`:** A high-level integration test using real components to create a regression suite. It verifies that the framework's *existing* ability to merge updates from multiple component levels into a single, efficient cycle remains intact.
-
-Key achievements of these tests:
--   **Validates Current Logic:** It successfully tests the *existing* logic where updates from multiple component levels (e.g., a parent and a grandchild) within the same event loop tick are correctly merged into a single, efficient VDOM update cycle.
--   **Pure VDOM Testing:** The test runs without a real DOM. It creates component instances, generates their initial `vnode` structure, and then programmatically triggers updates.
--   **Asserts on Deltas:** Instead of inspecting the DOM, the test awaits the `promiseUpdate()` method (which was enhanced to resolve with the update data) and directly inspects the raw `deltas` array. This provides a precise and reliable way to verify that the update-merging logic is working as expected.
-
-This test now serves as a critical regression suite, ensuring that the planned refactoring of the update mechanism will not alter this core, high-performance behavior.
-
-### 2. Framework API Enhancements
-
-The process of building the test suite revealed opportunities to improve the core framework. The following enhancements have been implemented:
-
--   **`Component.mountedPromise`:** A new, robust `mountedPromise` getter has been added to `component.Base`. This provides a clean, reusable, promise-based API for awaiting a component's mounted state. The implementation is resilient to the framework's full lifecycle, correctly handling unmounting and remounting, making it a valuable tool for both testing and application-level code.
--   **`VdomLifecycle.promiseUpdate()` Enhancement:** The `promiseUpdate()` method was refactored to resolve with the full data object from `vdom.Helper.update()`, giving developers and tests access to the generated `deltas` and the new `vnode`.
--   **Environment Robustness:** Several fixes were made to the `VdomLifecycle` mixin to ensure it works reliably in both multi-threaded (worker) and single-threaded (test) environments, particularly around `vdom.Helper` calls and `Neo.currentWorker` access.
-
--   **`VdomLifecycle.promiseUpdate()` Enhancement:** The `promiseUpdate()` method was refactored to resolve with the full data object from `vdom.Helper.update()`, giving developers and tests access to the generated `deltas` and the new `vnode`.
--   **Environment Robustness:** Several fixes were made to the `VdomLifecycle` mixin to ensure it works reliably in both multi-threaded (worker) and single-threaded (test) environments, particularly around `vdom.Helper` calls and `Neo.currentWorker` access.
-
-## Comparison with `dev` Branch (based on PR #7077)
-
-This feature branch represents a major architectural enhancement to the VDOM update lifecycle. Here is a summary of the key changes compared to the `dev` branch:
-
--   **New Update Orchestration Core:**
-    -   `manager.VDomUpdate`: A new singleton manager has been introduced to centralize the state for both pre-flight update merges and in-flight update collisions.
-    -   `util.vdom.TreeBuilder`: A new utility class for recursively building VDOM and VNode trees. It is the engine behind creating the *asymmetric* trees needed for optimized updates, correctly expanding component references based on a calculated `updateDepth`.
-
--   **Core Framework Refactoring:**
-    -   `mixin/VdomLifecycle.mjs`: This critical mixin has been significantly refactored. The complex, distributed state management (`childUpdateCache`) has been removed, and it now delegates all collision and merge logic to the new `VDomUpdate` manager.
-    The `executeVdomUpdate()` method has been modernized to use `async/await`, making the control flow more robust and readable, and ensuring deltas are correctly applied in non-worker environments.
-    -   `vdom/Helper.mjs`: The diffing engine has been enhanced to support the new asymmetric update strategy.
-    -   `component/Base.mjs`: The base component has been improved with a robust `mountedPromise` for easier async handling and other lifecycle enhancements to support the new update model.
-    -   `manager/Component.mjs`: Has undergone significant refactoring to align with the new VDOM strategies.
-    -   `functional/component/Base.mjs`: The base for functional components has been updated to align with the lifecycle changes in `component.Base`.
-
--   **New Testing Infrastructure:**
-    -   `test/siesta/tests/vdom/VdomAsymmetricUpdates.mjs`: A new low-level test suite that directly validates the logic of `VDomUpdate` and `TreeBuilder` using mock components.
-    -   `test/siesta/tests/vdom/VdomRealWorldUpdates.mjs`: A new high-level integration test suite using real, nested components to serve as a regression test.
-    -   `src/DefaultConfig.mjs`: The new `allowVdomUpdatesInTests: true` flag has been added to facilitate running VDOM-related tests in a unit test environment.
-    -   `test/siesta/siesta.js`: The test runner has been updated to include these new test suites.
-
-### Remaining Work to Complete the Epic (as of this PR)
-
-While the core architectural shift is complete, the following tasks remain to finalize the epic:
-
--   **Finalize Cleanup:**
-    -   The `childUpdateCache` property inside `src/component/Base.mjs` is now obsolete. It can be safely removed, as `VDomUpdate` has taken over its responsibilities.
-    -   The `updateVdom()` method in `VdomLifecycle.mjs` still uses a `timeout` to handle updates on unmounted components. This can be refactored to use the new `mountedPromise`, creating a cleaner and more robust implementation.
--   **Complete Asymmetric Logic:** The `TreeBuilder` and `vdom.Helper` still need the final logic to handle the `neo-ignore` placeholder. This will enable truly asymmetric updates where non-participating component sub-trees are completely skipped during the diffing process.
--   **Performance Benchmarking:** Conduct rigorous performance tests to compare this branch against `dev` and ensure no regressions.