neo.mjs 10.0.0-beta.4 → 10.0.0-beta.6

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

@@ -0,0 +1,122 @@
+# 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.

package/README.md

@@ -84,9 +84,6 @@ That’s Neo.mjs in action — solving problems others can’t touch.
 * **Persistent Component Instances**: Components maintain their state and logic even when their DOM is removed or moved.
   No more wasteful re-creations – just surgical, efficient updates.
 
-* **Reactive State Management**: Built-in reactivity ensures dynamic, efficient updates between components and state providers,
-  all handled off the main thread.
-
 * **Reactive State Management**: Leveraging `Neo.state.Provider`, Neo.mjs offers natively integrated, hierarchical state management.
   Components declare their data needs via a concise `bind` config. These `bind` functions act as powerful inline formulas, allowing
   Components to automatically react to changes and combine data from multiple state providers within the component hierarchy.

package/ServiceWorker.mjs

@@ -20,9 +20,9 @@ class ServiceWorker extends ServiceBase {
          */
         singleton: true,
         /**
-         * @member {String} version='10.0.0-beta.4'
+         * @member {String} version='10.0.0-beta.6'
          */
-        version: '10.0.0-beta.4'
+        version: '10.0.0-beta.6'
     }
 
     /**

package/apps/colors/store/Colors.mjs

@@ -14,6 +14,7 @@ class Colors extends Store {
         className: 'Colors.store.Colors',
         /**
          * @member {Neo.data.Model} model=ColorModel
+         * @reactive
          */
         model: ColorModel
     }

package/apps/colors/view/GridContainer.mjs

@@ -13,10 +13,12 @@ class GridContainer extends BaseGridContainer {
         className: 'Colors.view.GridContainer',
         /**
          * @member {Number|null} amountColumns_=null
+         * @reactive
          */
         amountColumns_: null,
         /**
          * @member {Number|null} amountRows_=null
+         * @reactive
          */
         amountRows_: null,
         /**
@@ -29,6 +31,7 @@ class GridContainer extends BaseGridContainer {
         },
         /**
          * @member {String[]} cls=['colors-grid-container']
+         * @reactive
          */
         cls: ['colors-grid-container']
     }

package/apps/colors/view/HeaderToolbar.mjs

@@ -16,10 +16,12 @@ class HeaderToolbar extends Toolbar {
         className: 'Colors.view.HeaderToolbar',
         /**
          * @member {String[]} cls=['colors-header-toolbar']
+         * @reactive
          */
         cls: ['colors-header-toolbar'],
         /**
          * @member {Object} layout={ntype:'hbox',align:'stretch',wrap:'wrap'}
+         * @reactive
          */
         layout: {ntype: 'hbox', align: 'center', pack: 'start', wrap: 'wrap'},
         /**

package/apps/colors/view/Viewport.mjs

@@ -19,10 +19,12 @@ class Viewport extends BaseViewport {
         className: 'Colors.view.Viewport',
         /**
          * @member {String[]} cls=['colors-viewport']
+         * @reactive
          */
         cls: ['colors-viewport'],
         /**
          * @member {Neo.controller.Component} controller=ViewportController
+         * @reactive
          */
         controller: ViewportController,
         /**
@@ -49,6 +51,7 @@ class Viewport extends BaseViewport {
         }],
         /**
          * @member {Neo.state.Provider} stateProvider=ViewportStateProvider
+         * @reactive
          */
         stateProvider: ViewportStateProvider
     }

package/apps/covid/view/FooterContainer.mjs

@@ -13,14 +13,17 @@ class FooterContainer extends Container {
         className: 'Covid.view.FooterContainer',
         /**
          * @member {Number} height=20
+         * @reactive
          */
         height: 25,
         /**
          * @member {Object} layout={ntype: 'hbox'}
+         * @reactive
          */
         layout: {ntype: 'hbox'},
         /**
          * @member {String} reference='footer'
+         * @reactive
          */
         reference: 'footer',
         /**

package/apps/covid/view/GalleryContainer.mjs

@@ -22,6 +22,7 @@ class GalleryContainer extends Container {
         baseCls: ['neo-gallery-maincontainer', 'neo-viewport'],
         /**
          * @member {Neo.controller.Component|null} controller=GalleryContainerController
+         * @reactive
          */
         controller: GalleryContainerController,
         /**
@@ -34,6 +35,7 @@ class GalleryContainer extends Container {
         galleryConfig: null,
         /**
          * @member {Object|null} layout={ntype: 'hbox', align: 'stretch'}
+         * @reactive
          */
         layout: {ntype: 'hbox', align: 'stretch'},
         /**

package/apps/covid/view/GalleryContainerController.mjs

@@ -14,6 +14,7 @@ class GalleryContainerController extends ComponentController {
         /**
          * @member {Neo.component.Gallery|null} gallery_=null
          * @protected
+         * @reactive
          */
         gallery_: null
     }

package/apps/covid/view/HeaderContainer.mjs

@@ -19,10 +19,12 @@ class HeaderContainer extends Container {
         baseCls: ['covid-header-container'],
         /**
          * @member {Number} height=70
+         * @reactive
          */
         height: 120,
         /**
          * @member {Object} layout={ntype: 'hbox', align: 'stretch'}
+         * @reactive
          */
         layout: {ntype: 'hbox', align: 'stretch'},
         /**

package/apps/covid/view/HelixContainer.mjs

@@ -22,6 +22,7 @@ class HelixContainer extends Container {
         baseCls: ['neo-helix-maincontainer', 'neo-viewport'],
         /**
          * @member {Neo.controller.Component|null} controller=HelixContainerController
+         * @reactive
          */
         controller: HelixContainerController,
         /**
@@ -34,6 +35,7 @@ class HelixContainer extends Container {
         helixConfig: null,
         /**
          * @member {Object|null} layout={ntype: 'hbox', align: 'stretch'}
+         * @reactive
          */
         layout: {ntype: 'hbox', align: 'stretch'},
         /**

package/apps/covid/view/HelixContainerController.mjs

@@ -14,6 +14,7 @@ class HelixContainerController extends ComponentController {
         /**
          * @member {Neo.component.Helix|null} helix_=null
          * @protected
+         * @reactive
          */
         helix_: null
     }

package/apps/covid/view/MainContainer.mjs

@@ -22,6 +22,7 @@ class MainContainer extends Viewport {
         baseCls: ['covid-viewport', 'neo-viewport'],
         /**
          * @member {Neo.controller.Component} controller=MainContainerController
+         * @reactive
          */
         controller: MainContainerController,
         /**
@@ -83,10 +84,12 @@ class MainContainer extends Viewport {
         }, FooterContainer],
         /**
          * @member {Object} layout={ntype: 'vbox', align: 'stretch'}
+         * @reactive
          */
         layout: {ntype: 'vbox', align: 'stretch'},
         /**
          * @member {Neo.state.Provider} stateProvider=MainContainerStateProvider
+         * @reactive
          */
         stateProvider: MainContainerStateProvider
     }

package/apps/covid/view/TableContainer.mjs

@@ -27,10 +27,12 @@ class TableContainer extends Container {
         },
         /**
          * @member {Neo.controller.Component|null} controller=TableContainerController
+         * @reactive
          */
         controller: TableContainerController,
         /**
          * @member {Object} countryRecord_=null
+         * @reactive
          */
         countryRecord_: null,
         /**
@@ -48,6 +50,7 @@ class TableContainer extends Container {
         tableConfig: null,
         /**
          * @member {Object|null} layout={ntype: 'hbox', align: 'stretch'}
+         * @reactive
          */
         layout: {ntype: 'hbox', align: 'stretch'},
         /**

package/apps/covid/view/TableContainerController.mjs

@@ -45,6 +45,7 @@ class TableContainerController extends ComponentController {
         /**
          * @member {Neo.table.Container|null} table_=null
          * @protected
+         * @reactive
          */
         table_: null
     }

package/apps/covid/view/WorldMapContainer.mjs

@@ -17,10 +17,12 @@ class WorldMapContainer extends Container {
         className: 'Covid.view.WorldMapContainer',
         /**
          * @member {Neo.controller.Component} controller=WorldMapContainerController
+         * @reactive
          */
         controller: WorldMapContainerController,
         /**
          * @member {Object} layout={ntype: 'vbox', align: 'stretch'}
+         * @reactive
          */
         layout: {ntype: 'vbox', align: 'stretch'},
         /**

package/apps/covid/view/country/Gallery.mjs

@@ -25,6 +25,7 @@ class CountryGallery extends Gallery {
         },
         /**
          * @member {String|null} country_=null
+         * @reactive
          */
         country_: null,
         /**
@@ -34,6 +35,7 @@ class CountryGallery extends Gallery {
         itemHeight: 280,
         /**
          * @member {Object} itemTpl_
+         * @reactive
          */
         itemTpl:
         {cls: ['neo-gallery-item', 'image-wrap', 'view', 'neo-transition-1000'], tabIndex: '-1', cn: [
@@ -86,6 +88,7 @@ class CountryGallery extends Gallery {
         selectOnMount: false,
         /**
          * @member {Neo.data.Store} store=CountryStore
+         * @reactive
          */
         store: CountryStore
     }

package/apps/covid/view/country/Helix.mjs

@@ -25,15 +25,18 @@ class CountryHelix extends Helix {
         },
         /**
          * @member {String|null} country_=null
+         * @reactive
          */
         country_: null,
         /**
          * The vertical delta between each helix item (increasing this value will create a spiral)
          * @member {Number} deltaY=1.2
+         * @reactive
          */
         deltaY: 1.2,
         /**
          * @member {Object} itemTpl_
+         * @reactive
          */
         itemTpl:
         {cls: ['surface', 'neo-helix-item'], style: {}, tabIndex: '-1', cn: [
@@ -77,11 +80,13 @@ class CountryHelix extends Helix {
         /**
          * The radius of the Helix in px
          * @member {Number} radius=2500
+         * @reactive
          */
         radius: 2500,
         /**
          * The rotationAngle of the Helix in degrees
          * @member {Number} rotationAngle=720
+         * @reactive
          */
         rotationAngle: 720,
         /**
@@ -91,16 +96,19 @@ class CountryHelix extends Helix {
         showCloneInfo: false,
         /**
          * @member {Neo.data.Store} store=CountryStore
+         * @reactive
          */
         store: CountryStore,
         /**
          * The translateX value gets included into each helix item
          * @member {Number} translateY=500
+         * @reactive
          */
         translateY: 500,
         /**
          * The translateX value gets included into each helix item
          * @member {Number} translateZ_=-2300
+         * @reactive
          */
         translateZ: -2300
     }

package/apps/covid/view/country/HistoricalDataTable.mjs

@@ -80,6 +80,7 @@ class HistoricalDataTable extends Container {
         }],
         /**
          * @member {Neo.data.Store} store=HistoricalData
+         * @reactive
          */
         store: HistoricalData
     }

package/apps/covid/view/country/Table.mjs

@@ -104,10 +104,12 @@ class Table extends Container {
         }],
         /**
          * @member {String|null} country_=null
+         * @reactive
          */
         country_: null,
         /**
          * @member {Neo.data.Store} store=CountryStore
+         * @reactive
          */
         store: CountryStore
     }

package/apps/covid/view/mapboxGl/Component.mjs

@@ -17,6 +17,7 @@ class Component extends BaseComponent {
         accessToken: 'pk.eyJ1IjoidG9iaXUiLCJhIjoiY2s4dTlsdHA5MDRmYzNtcGxlczFpcGVncyJ9.qcmzDjpdyQeLtz9z7d7CkA',
         /**
          * @member {Object} center={lat: 40, lng: 20}
+         * @reactive
          */
         center: {lat: 40, lng: 20},
         /**

package/apps/covid/view/mapboxGl/Container.mjs

@@ -22,6 +22,7 @@ class Container extends BaseContainer {
         ntype: 'covid-mapboxgl-container',
         /**
          * @member {Neo.controller.Component} controller=ContainerController
+         * @reactive
          */
         controller: ContainerController,
         /**
@@ -88,6 +89,7 @@ class Container extends BaseContainer {
         }],
         /**
          * @member {Object} layout={ntype: 'fit'}
+         * @reactive
          */
         layout: {ntype: 'fit'},
 

package/apps/email/EPIC_PLAN.md

@@ -0,0 +1,58 @@
+# EPIC: Refactor and Enhance the Email App
+
+This document outlines the plan for refactoring the `apps/email` application into a showcase for the Neo.mjs functional component architecture and multi-window capabilities.
+
+## Architectural Milestones & Key Learnings
+
+This epic has driven significant architectural improvements to the functional component system. For a full understanding of the current state, review this ticket:
+
+-   **[#ticket-functional-recursive-config-diffing.md](/.github/ticket-functional-recursive-config-diffing.md):** A plan for a future enhancement to make the diffing logic recursive, allowing for deep, declarative control over nested component configurations.
+
+---
+
+## Phase 1: Foundation and Basic Layout (Completed)
+
+**Goal:** Implement the main 3-pane layout as a functional `MainView` component and set it as the content of the existing classic `Viewport`.
+
+**Learnings & Decisions:**
+-   **Interoperability:** Kept the classic `Viewport` and embedded the new functional `MainView` component, showcasing seamless integration.
+-   **Naming:** Renamed `Main.mjs` to `MainView.mjs` for clarity.
+
+---
+
+## Phase 2: Email List View (Completed)
+
+**Goal:** Implement the email list pane using a `Neo.grid.Container`.
+
+**Learnings & Decisions:**
+-   **Complex Component Integration:** Discovered that complex classic components require specific configs (e.g., `wrapperStyle`) to manage their own layout when nested inside functional components.
+-   **Stateful Child Problem:** Uncovered the core issue of stateful children (stores, columns) being re-created on every parent render. This led directly to the architectural work on VDOM diffing.
+
+---
+
+## Phase 3: Email Detail View (Completed)
+
+**Goal:** Display the content of a selected email from the grid.
+-   Implemented a `selection.RowModel` on the grid and used a `useConfig` state variable (`selectedEmail`) to drive a conditional render of the detail pane.
+
+---
+
+## Phase 4: Compose Email Functionality (Next)
+
+**Goal:** Implement the ability to compose a new email, initially within the main window.
+
+**Proposed Plan:**
+1.  **Compose Button:** Add a `Neo.button.Base` to the "Folders" pane.
+2.  **State Management:** Use `useConfig` in `MainView` to manage an `isComposing` boolean state.
+3.  **Compose View:** Create a new functional component, `view/ComposeView.mjs`, containing the form for the new email.
+4.  **Conditional Rendering:** Use the `isComposing` flag to conditionally render the `ComposeView` as an overlay on top of the main view.
+5.  **Event Handling:** The "Compose" button will set `isComposing` to `true`. The `ComposeView` will have a "Close" button that sets it back to `false`.
+6.  **Overlay Implementation:** We will build a custom functional overlay for this, as it's a good exercise and provides maximum flexibility.
+
+---
+
+## Phase 5: Multi-Window Detach
+
+**Goal:** Implement the "detach" functionality to move the compose view into a separate browser window.
+**Sub-Tasks:** *(To be defined)*
+

package/apps/email/neo-config.json

@@ -4,6 +4,6 @@
     "environment": "development",
     "mainPath": "./Main.mjs",
     "themes": [
-        "neo-theme-light"
+        "neo-theme-dark"
     ]
-}
+}

package/apps/email/store/Emails.mjs

@@ -15,7 +15,17 @@ class Emails extends Store {
         /**
          * @member {Neo.data.Model} model=Email
          */
-        model: EmailModel
+        model: EmailModel,
+        /**
+         * @member {Object[]} data
+         */
+        data: [
+            {id: 1, sender: 'John Doe', title: 'Hello World!', content: 'This is the first email.', dateSent: '2025-07-15T10:00:00Z'},
+            {id: 2, sender: 'Jane Smith', title: 'Re: Project Update', content: 'Here is the project update you requested.', dateSent: '2025-07-15T11:30:00Z'},
+            {id: 3, sender: 'Peter Jones', title: 'Lunch tomorrow?', content: 'Are we still on for lunch tomorrow at 12:30?', dateSent: '2025-07-15T12:15:00Z'},
+            {id: 4, sender: 'Mary Williams', title: 'Your order has shipped', content: 'Your order #12345 has shipped and will arrive in 3-5 business days.', dateSent: '2025-07-14T15:45:00Z'},
+            {id: 5, sender: 'David Brown', title: 'Quick question', content: 'I have a quick question about the new feature.', dateSent: '2025-07-14T09:20:00Z'}
+        ]
     }
 }
 

package/apps/email/view/ComposeView.mjs

@@ -0,0 +1,44 @@
+import Button            from '../../../src/button/Base.mjs';
+import TextField         from '../../../src/form/field/Text.mjs';
+import TextAreaField     from '../../../src/form/field/TextArea.mjs';
+import {defineComponent} from '../../../src/functional/_export.mjs';
+
+export default defineComponent({
+    config: {
+        className: 'Email.view.ComposeView',
+        cls      : ['email-compose-view']
+    },
+    createVdom({onClose}) {
+        const fieldStyle = {
+            marginBottom: '10px'
+        };
+
+        return {
+            cn: [{
+                module    : TextField,
+                id        : 'compose-to',
+                labelText : 'To:',
+                labelWidth: 80,
+                style     : fieldStyle
+            }, {
+                module    : TextField,
+                id        : 'compose-subject',
+                labelText : 'Subject:',
+                labelWidth: 80,
+                style     : fieldStyle
+            }, {
+                module   : TextAreaField,
+                id       : 'compose-body',
+                labelText: 'Body:',
+                height   : 200,
+                style    : fieldStyle
+            }, {
+                module : Button,
+                handler: onClose,
+                id     : 'compose-close-button',
+                style  : {alignSelf: 'flex-end'},
+                text   : 'Close'
+            }]
+        }
+    }
+});