neo.mjs 10.1.1 → 10.2.0

package/learn/blog/v10-deep-dive-vdom-revolution.md

@@ -1,18 +1,17 @@
-# Deep Dive: The VDOM Revolution - JSON Blueprints & Asymmetric Rendering
+# The VDOM Revolution: How We Render UIs from a Web Worker
 
-In our previous deep dives, we've established the "why" and the "what" of Neo.mjs v10. We've seen how the
-**Two-Tier Reactivity System** creates a new reality for state management and how our new **Functional Components**
-provide a developer experience free from the "React tax."
+The Virtual DOM is a cornerstone of modern frontend development. But what happens when you take this concept and move it
+off the main thread entirely, into a Web Worker? It's a compelling idea—it promises a world where even the most complex
+UI rendering and diffing can never block user interactions.
 
-Now, we arrive at the final piece of the puzzle: how do we get this hyper-efficient, off-thread application onto the screen?
-This is where we introduce **Act II: The VDOM Revolution**, an architectural leap that rethinks the very nature of
-rendering in a multi-threaded world.
-
-This revolution is built on two pillars:
-1.  **JSON Blueprints:** A more intelligent, efficient language for describing UIs.
-2.  **Asymmetric Rendering:** Using the right tool for the right job—a specialized renderer for initial insertions and a
-    classic diffing engine for updates.
+But this architectural shift introduces a new set of fascinating engineering challenges. How do you efficiently
+communicate UI changes from a worker to the main thread? And what's the best language to describe a UI when it's being
+built by a machine, for a machine?
 
+This article explores the solutions to those problems, focusing on two key concepts:
+1.  **JSON Blueprints:** Why using structured data is a more powerful way to define complex UIs than traditional HTML.
+2.  **Asymmetric Rendering:** How using different, specialized strategies for creating new UI vs. updating existing UI
+3. leads to a more performant and secure system.
 
 *(Part 4 of 5 in the v10 blog series. Details at the bottom.)*
 
@@ -27,7 +26,7 @@ and enterprise dashboards—is sending pre-rendered HTML the ultimate endgame?
 We've seen this movie before. In the world of APIs, the verbose, heavyweight XML standard was supplanted by the lighter,
 simpler, and more machine-friendly JSON. We believe the same evolution is inevitable for defining complex UIs.
 
-Instead of the server laboring to render and stream HTML, Neo.mjs is built on the principle of **JSON Blueprints**.
+Instead of the server laboring to render and stream HTML, Neo.mjs is built on the principle of **JSON Blueprints**. 
 The server's job is to provide a compact, structured description of the component tree—its configuration, state, and
 relationships. Think of it as sending the architectural plans, not pre-fabricated walls.
 
@@ -35,14 +34,22 @@ This approach has profound advantages, especially for the AI-driven applications
 
 *   **Extreme Data Efficiency:** A JSON blueprint is drastically smaller than its equivalent rendered HTML, minimizing data transfer.
 *   **Server De-Loading:** This offloads rendering stress from the server, freeing it for core application logic and intensive AI computations.
-*   **AI's Native Language:** This is the most critical advantage for the next generation of applications. An LLM's
-    natural output is structured text. Asking it to generate a valid JSON object that conforms to a component's
+*   **AI's Native Language:** This is the most critical advantage for the next generation of applications.
+    An LLM's natural output is structured text. Asking it to generate a valid JSON object that conforms to a component's
     configuration is a far more reliable and constrained task than asking it to generate nuanced HTML with embedded logic
     and styles. The component's config becomes a clean, well-defined API for the AI to target, making UI generation less
     error-prone and more predictable.
 *   **True Separation of Concerns:** The server provides the "what" (the UI blueprint); the client's worker-based engine
     expertly handles the "how" (rendering, interactivity, and state management).
 
+This philosophy—that structured JSON is the future of UI definition—is not just a theoretical concept for us. It
+is the core engine behind a new tool we are developing: **Neo Studio**. It's a multi-window, browser-based IDE
+where we're integrating AI to generate component blueprints from natural language. The AI doesn't write JSX; it
+generates the clean, efficient JSON that the framework then renders into a live UI. It's the first step towards
+the vision of scaffolding entire applications this way.
+
+`[Screenshot of the Neo Studio UI, showcasing a generated component from a prompt]`
+
 JSON blueprints are the language. Now let's look at the engine that translates them into a live application.
 
 ---
@@ -65,11 +72,9 @@ from the VDOM worker and uses the right tool for every job.
 
 #### For Creating New DOM: The `DomApiRenderer`
 
-Whenever a new piece of UI needs to be created, the VDOM worker sends an `insertNode` command.
-This isn't just for the initial page load. It applies any time you:
--   Dynamically add a new component to a container.
--   Or, in a capability that showcases the power of the multi-threaded architecture,
-    move an entire component tree into a **new browser window**.
+Whenever a new piece of UI needs to be created, the VDOM worker sends an `insertNode` command. This isn't just for the
+initial page load. It applies any time you dynamically add a new component to a container or, in a capability that
+showcases the power of the multi-threaded architecture, move an entire component tree into a **new browser window**.
 
 For all these creation tasks, our pipeline uses the `DomApiRenderer`. This renderer is not only fast but also
 **secure by default**. It never parses HTML strings, instead building the DOM programmatically with safe APIs like
@@ -106,9 +111,9 @@ performance, security, and flexibility.
 The other half of the revolution happens before an update is even sent. It’s about creating the smartest, most minimal
 blueprint possible.
 
-In v9, Neo.mjs already had a powerful solution for this: **Scoped VDOM Updates**. Using an `updateDepth` config, a parent
-container could intelligently send its own VDOM changes to the worker while treating its children as simple placeholders.
-This prevented wasteful VDOM diffing on child components that weren't part of the update.
+In v9, Neo.mjs already had a powerful solution for this: **Scoped VDOM Updates**. Using an `updateDepth` config, a
+parent container could intelligently send its own VDOM changes to the worker while treating its children as simple
+placeholders. This prevented wasteful VDOM diffing on child components that weren't part of the update.
 
 However, this had a limitation. The `updateDepth` was an "all or nothing" switch for any given level of the component tree.
 Consider a toolbar with ten buttons. If the toolbar's own structure needed to change *and* just one of those ten buttons
@@ -117,14 +122,14 @@ also needed to update, the v9 model wasn't ideal.
 This is the exact challenge that **v10's Asymmetric Blueprints** were designed to solve.
 
 The new `VDomUpdate` manager and `TreeBuilder` utility work together to create a far more intelligent update payload.
-When the toolbar and one button need to change, the manager calculates the precise scope. The `TreeBuilder` then generates
-a partial VDOM blueprint that includes:
+When the toolbar and one button need to change, the manager calculates the precise scope. The `TreeBuilder` then
+generates a partial VDOM blueprint that includes:
 1.  The full VDOM for the toolbar itself.
 2.  The full VDOM for the *one* button that is changing.
 3.  Lightweight `{componentId: 'neo-ignore'}` placeholders for the other nine buttons.
 
-The VDOM worker receives this highly optimized, asymmetric blueprint. When it sees a `neo-ignore` node, it completely
-skips diffing that entire branch of the UI.
+The VDOM worker receives this highly optimized, asymmetric blueprint. When it sees a `neo-ignore` node,
+it completely skips diffing that entire branch of the UI.
 
 It’s the ultimate optimization: instead of sending the entire blueprint for a skyscraper just to fix a window,
 we now send the floor plan for the lobby *and* the specific blueprint for that one window on the 50th floor,
@@ -133,37 +138,6 @@ and the framework automatically creates the most efficient update possible.
 
 ---
 
-#### 2. For Updates: From Scoped to Truly Asymmetric Blueprints
-
-Once a component is on the screen, we need to handle state changes with surgical precision. In v9, Neo.mjs already had
-a powerful solution for this: **Scoped VDOM Updates**. Using an `updateDepth` config, a parent container could
-intelligently send its own VDOM changes to the worker while treating its children as simple placeholders. This prevented
-wasteful VDOM diffing on child components that weren't part of the update.
-
-However, this had a limitation. The `updateDepth` was an "all or nothing" switch for any given level of the component tree.
-Consider a toolbar with ten buttons. If the toolbar's own structure needed to change *and* just one of those ten buttons
-also needed to update, the v9 model forced a choice: either send two separate, parallel updates (one for the toolbar,
-one for the button), or have the toolbar update its entire level, including the nine buttons that hadn't changed.
-
-This is the exact challenge that **v10's Asymmetric Blueprints** were designed to solve.
-
-The new `VDomUpdate` manager and `TreeBuilder` utility work together to create a far more intelligent update payload.
-When the toolbar and one button need to change, the manager calculates the precise scope. The `TreeBuilder` then generates
-a partial VDOM blueprint that includes:
-1.  The full VDOM for the toolbar itself.
-2.  The full VDOM for the *one* button that is changing.
-3.  Lightweight `{componentId: 'neo-ignore'}` placeholders for the other nine buttons.
-
-The VDOM worker receives this highly optimized, asymmetric blueprint. When it sees a `neo-ignore` node, it completely
-skips diffing that entire branch of the UI.
-
-It’s the ultimate optimization: instead of sending the entire blueprint for a skyscraper just to fix a window, we now
-send the floor plan for the lobby *and* the specific blueprint for that one window on the 50th floor, ignoring everything
-else in between. The worker focuses only on what matters, resulting in faster diffs and minimal data transfer between
-threads.
-
----
-
 ## Conclusion: An Engine Built for Tomorrow
 
 The VDOM Revolution in Neo.mjs isn't just a performance enhancement; it's a paradigm shift.
@@ -189,6 +163,6 @@ invite you to fall in love with frontend development all over again.
 
 1. [A Frontend Love Story: Why the Strategies of Today Won't Build the Apps of Tomorrow](./v10-post1-love-story.md)
 2. [Deep Dive: Named vs. Anonymous State - A New Era of Component Reactivity](./v10-deep-dive-reactivity.md)
-3. [Beyond Hooks: A New Breed of Functional Components for a Multi-Threaded World](./v10-deep-dive-functional-components.md)
-4. Deep Dive: The VDOM Revolution - JSON Blueprints & Asymmetric Rendering
-5. [Deep Dive: The State Provider Revolution](./v10-deep-dive-state-provider.md)
+3. [Designing Functional Components for a Multi-Threaded World](./v10-deep-dive-functional-components.md)
+4. The VDOM Revolution: How We Render UIs from a Web Worker
+5. [Designing a State Manager for Performance: A Deep Dive into Hierarchical Reactivity](./v10-deep-dive-state-provider.md)

package/learn/blog/v10-post1-love-story.md

@@ -322,9 +322,9 @@ It's time to fall in love with frontend again.
 
 1. A Frontend Love Story: Why the Strategies of Today Won't Build the Apps of Tomorrow
 2. [Deep Dive: Named vs. Anonymous State - A New Era of Component Reactivity](./v10-deep-dive-reactivity.md)
-3. [Beyond Hooks: A New Breed of Functional Components for a Multi-Threaded World](./v10-deep-dive-functional-components.md)
-4. [Deep Dive: The VDOM Revolution - JSON Blueprints & Asymmetric Rendering](./v10-deep-dive-vdom-revolution.md)
-5. [Deep Dive: The State Provider Revolution](./v10-deep-dive-state-provider.md)
+3. [Designing Functional Components for a Multi-Threaded World](./v10-deep-dive-functional-components.md)
+4. [The VDOM Revolution: How We Render UIs from a Web Worker](./v10-deep-dive-vdom-revolution.md)
+5. [Designing a State Manager for Performance: A Deep Dive into Hierarchical Reactivity](./v10-deep-dive-state-provider.md)
 
 ---
 

package/learn/gettingstarted/DescribingTheUI.md

@@ -1,16 +1,54 @@
 # Describing a View
 
 A Neo.mjs view is comprised of components and containers. A component is a visual widget, like a button,
-and a container is a visual collection of components. 
+and a container is a visual collection of components.
 
-Neo.mjs is declarative, where your code _describes_ or _configures_ the things its creating. 
+Neo.mjs is declarative, where your code _describes_ or _configures_ the things it's creating.
 
-For example, if you wanted to create a button, you'd look in the API docs and see that buttons
-have a few key configs, including `text` and `iconCls`. The configs are properties you can 
-use to describe the component you're creating> You can also access or set the properties dynamically.
+There are two primary ways to describe a view: using modern **functional components** or classic **class-based components**.
+Crucially, these two approaches are fully interoperable, allowing you to mix and match them to fit your needs.
 
+## The Modern Approach: Functional Components
 
-## A view with one component
+For most new views, especially those that are primarily presentational (like a button or a hero section), the recommended approach is to use functional components. This method is concise, highly performant, and aligns with modern reactive programming patterns.
+
+Functional components are defined using the `defineComponent` helper. You provide a configuration object that includes a `createVdom` method. This method is a reactive function that returns the Virtual DOM (VDOM) for your component.
+
+### A simple functional view
+
+Here is a simple view that displays a single button. The `createVdom` function returns a VDOM object that describes the button.
+
+```javascript live-preview
+import {defineComponent} from '../functional/_export.mjs';
+
+const MainView = defineComponent({
+    className: 'GS.describing.functional.MainView',
+
+    createVdom(config) {
+        return {
+            ntype: 'container',
+            layout: {ntype: 'vbox', align: 'start'},
+            items: [{
+                ntype: 'button',
+                iconCls: 'fa fa-home',
+                text: 'Home'
+            }]
+        }
+    }
+});
+
+export default MainView;
+```
+
+## The Classic Approach: Class-Based Components
+
+For more complex, high-order components that require surgical precision and powerful state management (like a buffered grid, a calendar, or an image gallery), the classic class-based approach is more suitable.
+
+This approach involves extending a framework class (like `Neo.container.Base`) and defining your view within the `static config` block. It gives you access to a rich set of lifecycle methods (`beforeSet...`, `afterSet...`, etc.) for fine-grained control.
+
+### A simple class-based view
+
+Here is the same view, but built with the class-based approach.
 
 ```javascript live-preview
 import Button    from '../button/Base.mjs';
@@ -18,7 +56,7 @@ import Container from '../container/Base.mjs';
 
 class MainView extends Container {
     static config = {
-        className: 'GS.describing1.MainView',
+        className: 'GS.describing.class.MainView',
         layout   : {ntype:'vbox', align:'start'},
         items    : [{
             module : Button,
@@ -31,39 +69,71 @@ class MainView extends Container {
 MainView = Neo.setupClass(MainView);
 ```
 
+## Interoperability: The Best of Both Worlds
 
-The button config is just an object describing the button being created. In the example, it has three
-properties:
+The power of Neo.mjs lies in its interoperability layer. You can seamlessly mix both component models.
 
-- `module` is the type of thing being created; it's the imported module name.
-- `text` is the button's text
-- `iconCls` is the css class used for the button's icon. Neo.mjs automatically includes Font Awesome, 
-and `fa fa-home` matches a Font Awesome css class.
+### Using a Class-Based Component in a Functional View
 
-Components are almost always placed within a container. A container is a component that visually holds other 
-components. Containers have an `items:[]` config, which is an array of the components within the container. 
-Containers also have a `layout` property, which describes how the items are arranged. 
+You can easily instantiate a classic component within the `createVdom` method of a functional component. This is useful when you need to embed a complex, stateful widget inside a simpler, functional layout.
 
-Let's put a second button in the container.
+```javascript live-preview
+import {defineComponent} from '../functional/_export.mjs';
+import Calendar from '../calendar/Component.mjs'; // A complex, class-based component
+
+const MainView = defineComponent({
+    className: 'GS.describing.interop.MainView1',
+
+    createVdom(config) {
+        return {
+            ntype: 'container',
+            layout: {ntype: 'vbox', align: 'start'},
+            items: [{
+                ntype: 'component',
+                vdom: {tag: 'h1', html: 'My Functional View'}
+            }, {
+                // Drop the class-based Calendar into our functional view
+                module: Calendar,
+                height: 300,
+                width: 300
+            }]
+        }
+    }
+});
+
+export default MainView;
+```
+
+### Using a Functional Component in a Class-Based View
 
-## A view with two components
+Conversely, you can drop a functional component into the `items` array of a classic container. This allows you to compose your complex views from smaller, more manageable functional pieces.
 
 ```javascript live-preview
-import Button    from '../button/Base.mjs';
+import {defineComponent} from '../functional/_export.mjs';
 import Container from '../container/Base.mjs';
 
+// 1. Define a simple functional component
+const MyFunctionalButton = defineComponent({
+    className: 'GS.describing.interop.FuncButton',
+    createVdom(config) {
+        return {
+            ntype: 'button',
+            iconCls: config.iconCls,
+            text: config.text
+        }
+    }
+});
+
+// 2. Create a class-based MainView
 class MainView extends Container {
     static config = {
-        className: 'GS.describing2.MainView',
-        layout   : {ntype:'vbox', align:'start'}, // Change the ntype to 'hbox'
+        className: 'GS.describing.interop.MainView2',
+        layout   : {ntype:'vbox', align:'start'},
         items    : [{
-            module : Button,
-            iconCls: 'fa fa-home',
-            text   : 'Home'
-        }, {
-            module : Button,
-            iconCls: 'fa fa-star',
-            text   : 'Star'
+            // 3. Use the functional component in the items array
+            module: MyFunctionalButton,
+            iconCls: 'fa fa-rocket',
+            text   : 'Launch'
         }]
     }
 }
@@ -71,9 +141,14 @@ class MainView extends Container {
 MainView = Neo.setupClass(MainView);
 ```
 
-If you run the example you'll see two buttons, arranged according to the `layout`. If you'd like, 
-modify the code to specify `ntype:'hbox'` and run it again. 
+## Choosing Your Approach
+
+*   **Use Functional Components (`defineComponent`) for:**
+    *   Simple, reusable components (e.g., buttons, chips, hero sections).
+    *   Most of your application's views that are primarily presentational.
+    *   When you want a concise, declarative, and highly performant component.
 
-Note that the layout specifies `ntype` rather than `module`. An `ntype` is an alias for a class
-that has already been imported. Containers import all the layout types, so since we've already
-imported container we can simply use `ntype` to specify which layout we want.
+*   **Use Class-Based Components (`class ... extends ...`) for:**
+    *   Complex, high-order components requiring surgical precision (e.g., buffered grids, calendars, charts, galleries).
+    *   Creating new reusable components that extend the functionality of existing framework classes.
+    *   Components with intricate internal logic that benefits from the full range of class lifecycle methods.

package/learn/guides/fundamentals/ConfigSystemDeepDive.md

@@ -4,13 +4,22 @@
 first to understand the foundational concepts and benefits.
 
 The Neo.mjs class configuration system is a cornerstone of the framework, providing a powerful, declarative, and
-reactive way to manage the state of your components and classes. Its internal mechanics are deeply intertwined with
-the instance lifecycle, ensuring predictable and consistent behavior. This guide will take you on a deep dive into
-how it achieves its remarkable consistency and power.
+reactive way to manage the state of your components and classes. With the introduction of functional components in v10,
+this system has evolved into a sophisticated, two-tier reactivity model that combines the robustness of a classic
+"push" system with the fine-grained efficiency of a modern "pull" system.
 
-## 1. Core Concepts Recap
+This guide will take you on a deep dive into how this hybrid system works, giving you the knowledge to build highly
+performant and maintainable applications.
 
-At its heart, the config system is built on a few key principles:
+## Tier 1: The Classic "Push" System
+
+The original reactivity model in Neo.mjs is a "push" system. It's imperative, meaning that when you change a value,
+the system actively "pushes" that change through a series of predefined lifecycle hooks. This system remains a core
+part of v10 and is the foundation for class-based components.
+
+### 1. Core Concepts Recap
+
+At its heart, the push system is built on a few key principles:
 
 *   **`static config` Block:** All configurable properties of a class are declared in a `static config = {}` block.
     This provides a single, clear source of truth for a class's API.
@@ -26,13 +35,13 @@ At its heart, the config system is built on a few key principles:
     automatically runs whenever a specific config property changes, ensuring your UI and application state are always
     in sync.
 
-## 2. The Internal Mechanics: `set()`, `processConfigs()`, and `configSymbol`
+### 2. The Internal Mechanics: `set()`, `processConfigs()`, and `configSymbol`
 
 To truly understand how Neo.mjs handles complex scenarios like simultaneous updates and inter-dependencies, we must
 look at the internal machinery: the `set()` and `processConfigs()` methods in `Neo.core.Base`, and the special
 `configSymbol` object.
 
-### The `set()` Method: Your Gateway to Updates
+#### The `set()` Method: Your Gateway to Updates
 
 The `set()` method is the public interface for changing one or more config properties at once. When you call
 `this.set({a: 1, b: 2})`, you kick off a carefully orchestrated sequence.
@@ -68,7 +77,7 @@ Here’s the breakdown:
     from `configSymbol` to the actual instance properties. The `true` argument (`forceAssign`) is crucial, as we'll
     see next.
 
-### The `processConfigs()` Method: The Heart of the Operation
+#### The `processConfigs()` Method: The Heart of the Operation
 
 This internal method iteratively processes the configs stored in `configSymbol`. It's designed as a recursive
 function to handle the dynamic nature of config processing, where one `afterSet` might trigger another `set()`.
@@ -108,7 +117,7 @@ processConfigs(forceAssign=false) {
     has been invoked. This is vital to prevent reprocessing and to mark the config as handled.
 *   **Recursion (E):** The method calls itself to process the next item in `configSymbol` until it's empty.
 
-## 3. Solving the "Circular Reference" Problem
+### 3. Solving the "Circular Reference" Problem
 
 What happens when two `afterSet` methods depend on each other's properties?
 
@@ -174,10 +183,98 @@ Here's the sequence:
 operation. This guarantees that all `afterSet` handlers, regardless of their execution order, operate on the most
 current and consistent state of all config properties involved in that operation.
 
-## 4. In-depth Example: A Reactive `MainContainer`
+## Tier 2: The Declarative "Pull" System (v10+)
+
+With the introduction of functional components, Neo.mjs now includes a "pull" reactivity system. This system is
+declarative and optimized for fine-grained updates, making it ideal for modern, state-driven UI development. Instead
+of "pushing" changes through hooks, the system "pulls" data as needed, automatically tracking dependencies and
+re-running computations only when necessary.
+
+This tier is powered by three key classes: `Neo.core.Config`, `Neo.core.Effect`, and `EffectManager`.
+
+### 1. `Neo.core.Config`: The Atomic Unit of State
+
+A `Neo.core.Config` instance is a lightweight wrapper around a single, reactive piece of data. Think of it as an
+"atom" of state.
+
+*   **Value Storage:** It holds the current value of a config property.
+*   **Subscription Management:** It maintains a list of subscribers (effects or other logic) that depend on its value.
+*   **Dependency Tracking:** When its `get()` method is called within a reactive context (an "effect"), it registers
+    itself as a dependency of that effect.
+*   **Notification:** When its `set()` method is called and the value changes, it notifies all its subscribers,
+    triggering them to re-run.
+
+### 2. `Neo.core.Effect`: The Reactive Computation
+
+An `Neo.core.Effect` represents a reactive computation—a function that depends on one or more `Config` atoms.
+
+*   **Wrapping a Function:** It wraps a function (e.g., a component's rendering logic).
+*   **Automatic Dependency Tracking:** When the effect runs, it automatically detects which `Config` atoms are `get()`
+    inside its function. It then subscribes to them.
+*   **Automatic Re-execution:** If any of its dependencies change (i.e., their `set()` method is called), the effect's
+    function is automatically re-executed, ensuring the computation is always up-to-date.
+
+### 3. `EffectManager`: The Global Coordinator
+
+The `EffectManager` is a singleton that orchestrates the entire pull system.
+
+*   **Effect Stack:** It maintains a stack of currently running effects. This is how a `Config` atom knows which effect
+    to register itself with when its `get()` method is called.
+*   **Batching:** It provides `Neo.batch()`, a crucial optimization function. It allows the system to pause effect
+    re-runs, perform multiple state changes, and then resume, running all affected effects only once at the end. This
+    prevents "glitches" and unnecessary intermediate computations.
+
+### 4. `createVdom` as a Master Effect
+
+In a functional component, the `createVdom()` method is the perfect example of an effect in action.
+
+*   **The `vdomEffect`:** When a functional component is constructed, the framework automatically wraps its `createVdom()`
+    method in a `Neo.core.Effect`.
+*   **Reading is Subscribing:** When your `createVdom()` function runs, every component config you access (e.g.,
+    `config.text`, `config.items`) is a call to that config's underlying `Neo.core.Config` atom's `get()` method.
+    This automatically subscribes the `vdomEffect` to those configs.
+*   **Automatic UI Updates:** If any of those configs change later, they notify the `vdomEffect`. The effect then
+    re-runs your `createVdom()` function, generating a new virtual DOM based on the new state. The framework then
+    efficiently diffs this new VDOM with the old one and applies the minimal necessary changes to the actual DOM.
+
+This is the essence of declarative, state-driven UI. You declare what the UI should look like for a given state, and
+the framework handles the "how" and "when" of updating it.
+
+## The Bridge: How "Push" and "Pull" Work Together
+
+The true power of the v10 config system is how these two tiers are seamlessly integrated. This bridge is forged in
+the auto-generated setters of reactive configs and the `set()` method of `Neo.core.Base`.
+
+When you change a config on any component (class-based or functional):
+
+```javascript readonly
+myComponent.myConfig = 'new value';
+// or
+myComponent.set({myConfig: 'new value'});
+```
+
+Here's what happens under the hood:
+
+1.  **Batching Begins:** The `set()` method in `Neo.core.Base` immediately calls `EffectManager.pause()`. This tells
+    the "pull" system to queue up any effects that get triggered but not to run them yet.
+2.  **The Setter is Called:** The auto-generated setter for `myConfig` is invoked. This setter is the heart of the
+    bridge. It performs two critical actions:
+    *   **Pull System Update:** It retrieves the `Neo.core.Config` instance for `myConfig` (using `this.getConfig('myConfig')`)
+      and calls its `set()` method with the new value. This updates the reactive atom and queues any dependent effects
+      (like a functional component's `vdomEffect`).
+    *   **Push System Update:** It proceeds with the classic "push" system logic, adding the new value to the
+      `configSymbol` staging area and eventually calling the `afterSetMyConfig()` hook.
+3.  **Batching Ends:** After the `set()` method in `core.Base` has finished processing all configs in the batch, its
+    `finally` block calls `EffectManager.resume()`. This tells the `EffectManager` to run all the unique effects that
+    were queued during the operation, ensuring that the UI and other reactive computations update exactly once.
+
+This elegant integration means you get the best of both worlds: the predictable, hook-based logic of the push system
+and the automatic, fine-grained reactivity of the pull system, all working in harmony.
+
+## In-depth Example: A Reactive `MainContainer`
 
 Let's analyze a practical example to see these concepts in action. The `Neo.examples.core.config.MainContainer`
-demonstrates how to build a reactive UI declaratively.
+demonstrates how to build a reactive UI declaratively using the classic "push" system.
 
 **The Goal:** Create a container with two labels. The text of each label is calculated based on the values of two
 config properties, `a` and `b`. A button allows the user to change `a` and `b` simultaneously.
@@ -259,23 +356,26 @@ class MainContainer extends Viewport {
     *   `afterSetB` runs. It calculates `label2.text` as `value (10) + this.a (reads 10 from _a) = 20`.
     *   **New State:** `label1` shows "20", `label2` shows "20".
 
-This example vividly demonstrates the dynamic and reactive nature of the system, where a single declarative state
-change automatically propagates through the component logic.
+This example vividly demonstrates the dynamic and reactive nature of the "push" system, where a single declarative state
+change automatically propagates through the component logic via `afterSet` hooks.
 
-## 5. Best Practices
+## Best Practices for the Hybrid System
 
-*   **Embrace Declarativity:** Define your entire UI structure inside `static config` whenever possible. This improves
-    readability and maintainability.
+*   **Embrace Declarativity:** For functional components, define your UI structure inside `createVdom`. Trust the
+    reactive system to handle updates. For class-based components, define your entire UI structure inside `static config`
+    whenever possible. This improves readability and maintainability.
 *   **Use the `_` Suffix Wisely:** Only add the trailing underscore to configs that need `afterSet`, `beforeSet` or
   `beforeGet` based logic. For simple value properties, omit it to avoid unnecessary overhead.
 *   **Keep `afterSet` Handlers Pure:** An `afterSet` handler should ideally only react to the change of its own
     property and update other parts of the application. Avoid triggering complex chains of `set()` calls from within
     an `afterSet` if possible.
 *   **Batch Updates with `set()`:** When you need to change multiple properties at once, always use a single
-    `set({a: 1, b: 2})` call. This is more efficient and ensures consistency, as demonstrated above.
+    `set({a: 1, b: 2})` call. This is more efficient and ensures consistency across both reactivity systems.
 *   **Use `onConstructed` for Post-Construction Logic:** Use the `onConstructed` lifecycle method to perform any setup
     that depends on the instance's initial configuration being fully processed. This is the ideal place for logic that
     requires all configs to be set and potentially other instances to be created (if set-driven).
+*   **Understand Your Dependencies:** Be mindful of which configs you access inside `createVdom` and other effects, as
+    this determines when they will re-run.
 
 By understanding these internal mechanics and following best practices, you can leverage the full power of Neo.mjs's
-class config system to build highly complex, reactive, and maintainable applications with confidence.
+hybrid config system to build highly complex, reactive, and maintainable applications with confidence.