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

package/learn/comparisons/NeoVsReact.md

@@ -0,0 +1,95 @@
+# Neo.mjs vs React.js
+
+Neo.mjs is a comprehensive JavaScript ecosystem for building high-performance, multi-threaded web applications. Unlike libraries such as React that form only one part of a complex, manually assembled toolchain, Neo.mjs is a self-contained system with **zero runtime dependencies**. It provides a complete, out-of-the-box solution that includes four distinct development and deployment environments, from a revolutionary zero-builds development mode to thread-optimized production bundles.
+
+This article provides a focused comparison between the Neo.mjs ecosystem and React. React, now over a decade old, has become an industry standard, but its foundational architecture is rooted in the single-threaded limitations of its time. We will explore their fundamentally different approaches to **architecture, rendering, and reactivity**, highlighting the trade-offs between React's library-focused, Main-Thread-bound model and Neo.mjs's holistic, worker-based paradigm.
+
+## Foundational Concepts: A Shared Heritage
+
+Despite their architectural differences, both frameworks build upon foundational concepts that have shaped UI development:
+
+*   **Component-Based Architecture (with a distinction):** Both frameworks promote building UIs as a composition of reusable components. However, Neo.mjs extends this concept with `Neo.core.Base`, allowing any class-based entity (like controllers, models, or routers) to leverage the framework's powerful class system, even if they don't directly render UI. This contrasts with frameworks where non-visual logic might often be shoehorned into component structures.
+*   **Declarative UI:** Developers describe *what* the UI should look like for a given state, and the framework handles *how* to update the DOM.
+*   **Reactive Paradigm:** Both leverage reactive programming principles where UI updates are driven by changes in state.
+*   **Functional Components & Hooks:** Both support defining components as functions and provide hooks for managing state and side effects, though their implementation and performance characteristics differ significantly.
+
+## Key Differences: Architectural & Rendering Strategies
+
+This is where the two frameworks diverge significantly, each offering unique trade-offs and advantages.
+
+### 1. Overall Architecture: Main Thread vs. Worker-Based
+
+*   **React: Main Thread Focused**
+    *   React applications run predominantly on the Main JavaScript Thread of the browser. All component logic, state management, VDOM reconciliation, and direct DOM manipulation occur on this single thread.
+    *   **Implication:** While React is highly optimized, complex computations, large state updates, or extensive component trees can potentially block the Main Thread, leading to UI jank, unresponsiveness, and a poor user experience. React relies on techniques like Fiber reconciliation and `requestIdleCallback` (via `Scheduler`) to yield to the browser, but it's still fundamentally bound by the Main Thread's limitations.
+
+*   **Neo.mjs: Worker-Based (Main Thread + App Worker + VDom Worker)**
+    *   Neo.mjs's defining feature is its multi-threaded architecture. Application logic (component instances, state, business logic, `vdomEffect`s) runs in a dedicated **App Worker**, separate from the Main Thread. The VDOM diffing occurs in a **VDom Worker**.
+    *   Communication between workers and the Main Thread happens via asynchronous message passing.
+    *   **Benefit:** This architecture keeps the Main Thread almost entirely free and responsive, preventing UI freezes even during heavy computations or complex application logic. It inherently leverages multi-core CPUs for parallel processing, leading to superior UI responsiveness and performance under heavy load.
+
+### 2. Rendering Mechanism
+
+*   **React: Main-Thread VDOM & Enforced Immutability**
+    *   React uses a Virtual DOM. When state or props change, React builds a new VDOM tree on the Main Thread, compares it with the previous one (reconciliation), and calculates the minimal set of changes (diffing). These changes are then applied to the real DOM, all on the same thread responsible for user interactions.
+    *   **VDOM Definition:** Primarily uses JSX, a syntax extension requiring a build step (e.g., Babel) to transpile HTML-like structures into `React.createElement` calls.
+    *   **The Burden of Immutability:** React's reconciliation algorithm relies on developers treating state as immutable. To change state, you must create a *new* object or array reference instead of modifying the existing one. This forces developers into patterns using spread syntax (`...`) or libraries like Immer to manage state changes. While this simplifies React's diffing logic, it offloads significant cognitive and boilerplate burden onto the developer and can be a frequent source of bugs when not handled correctly.
+
+*   **Neo.mjs: Off-Thread VDOM & Developer-Friendly Mutability**
+    *   Neo.mjs also uses a Virtual DOM, but its philosophy and implementation are fundamentally different. The VDOM is defined using plain JavaScript objects and arrays—no JSX or build step is required for UI definition.
+    *   **Mutability by Design, Immutability in Process:** Neo.mjs embraces developer convenience by allowing **direct, mutable manipulation** of component state (configs) and the VDOM structure within the App Worker. This eliminates the boilerplate and cognitive load of managing immutable updates. The architectural brilliance lies in how it achieves the benefits of immutability: when an update is triggered, Neo.mjs creates a **JSON snapshot** of the relevant VDOM tree. This snapshot is sent to the VDom Worker, making the *update process itself* immutable and predictable for diffing. This provides the best of both worlds: simple, direct mutation for the developer and a safe, immutable structure for the high-performance diffing algorithm in another thread.
+    *   **Off-Main-Thread Diffing:** The entire VDOM diffing process occurs in the dedicated **VDom Worker**, completely freeing the Main Thread from this heavy computation.
+    *   **Scoped VDOM (Encapsulation & Performance):** The VDom Worker sends only the "deltas" (a minimal set of change instructions) back to the Main Thread. For insertions, `DomApiRenderer` **builds the entire new DOM subtree in memory**, completely detached from the live document, and inserts it in a **single, atomic operation**. Furthermore, Neo.mjs's VDOM is **scoped by default**. When a parent component renders, its children are represented by simple `{componentId: '...'}` placeholders. This provides two key advantages:
+        1.  **Performance:** A parent's update never processes the complex VDOM of its children, keeping update payloads extremely small and efficient.
+        2.  **Encapsulation:** It is architecturally impossible for a parent to accidentally reach into and manipulate a child's internal VDOM structure. This enforces clear ownership and prevents a wide class of bugs.
+
+### 3. Component Execution Model: Precision vs. Brute Force
+
+*   **React: Cascading Re-Renders & The `memo` Tax**
+    *   When a component's state changes, React re-executes the entire component function. This is just the beginning. By default, it then triggers a cascading re-render of **all its child components**, regardless of whether their own props have changed.
+    *   This brute-force approach creates a significant performance problem known as "unnecessary re-renders." To fight this, developers are forced to pay the `memo` tax: wrapping components in `React.memo()`, manually memoizing functions with `useCallback()`, and objects with `useMemo()`. This adds significant boilerplate, increases complexity, and is a notorious source of bugs, including stale closures and incorrect dependency arrays. This manual optimization becomes a core, and often frustrating, part of the development process.
+
+*   **Neo.mjs: Surgical Effects & Automatic Efficiency**
+    *   Neo.mjs's model is fundamentally more efficient and intelligent. A component's `createVdom` method is wrapped in a `Neo.core.Effect`. This effect automatically and dynamically tracks its dependencies—the specific `config` values it reads.
+    *   When a config value changes, only the specific `createVdom` effects that depend on that *exact* piece of state are queued for re-execution. There are no cascading re-renders. If a parent's `createVdom` re-runs, but the configs passed to a child have not changed, the child component's `createVdom` function is **never executed**.
+    *   **Benefit (Zero Manual Optimization):** This fine-grained reactivity completely eliminates the need for manual memoization (`memo`, `useCallback`, `useMemo`). The framework handles dependency tracking automatically and precisely, delivering optimal performance out-of-the-box without the boilerplate and complexity inherent in React. This also sidesteps entire classes of bugs like stale closures, as dependencies are discovered fresh on every run, without requiring manual dependency arrays.
+
+*   **State Management & The End of Props Drilling:** React often relies on its Context API or third-party state management libraries to avoid "props drilling." However, this often introduces performance issues, as any change to a context value re-renders all consuming components by default. Neo.mjs's architecture makes props drilling an obsolete anti-pattern. A deeply nested component can subscribe directly to the precise piece of state it needs from a `StateProvider` via an `Effect`. This creates a direct, performant link between the state and the component that needs it, completely bypassing all intermediate components. This results in a cleaner, more decoupled, and more performant architecture by default.
+
+### 4. Scaling Complexity: Linear Effort vs. Exponential Overhead
+
+A key differentiator between the frameworks is how they handle growing application complexity.
+
+*   **React: Exponential Complexity in Large Applications**
+    *   Consider a complex dashboard with a global state (e.g., a user profile in a Context). When a single value in that state changes (e.g., the user's name), React's default behavior is to re-render **every single component** that consumes that context.
+    *   To prevent the entire UI from lagging, developers must manually optimize each consuming component. This involves wrapping components in `React.memo` and using selector-like functions with `useMemo` to extract only the needed data. As the application grows, the number of these manual optimizations grows, leading to an exponential increase in boilerplate and performance-tuning effort. The burden is on the developer to constantly fight the framework's default behavior.
+
+*   **Neo.mjs: Built-in Efficiency and Linear Effort**
+    *   Neo.mjs's architecture is designed to handle this scenario effortlessly. Multiple state changes are automatically batched into a single, de-duplicated update cycle via the `EffectBatchManager`.
+    *   In the same complex dashboard scenario, if a value in a global `StateProvider` changes, only the `createVdom` effects in components that *directly depend on that specific value* will re-run. All other components remain untouched, with **zero manual optimization required from the developer**.
+    *   This leads to a **linear relationship between complexity and effort**. As you add more components, you don't need to add more performance optimizations. The framework's core design ensures that updates are always surgical and efficient, allowing developers to focus on features instead of fighting the rendering engine. This is a direct result of the sophisticated, multi-layered batching and aggregation built into the framework's core.
+
+### Other Considerations:
+
+*   **Development & Deployment Environments:** Neo.mjs offers four distinct environments, providing unparalleled flexibility:
+    *   **Zero Builds Development Mode:** The primary development workflow, leveraging native ES Modules for instant code reflection and debugging without a build step. This contrasts sharply with React's typical development setup which always involves a build process.
+    *   **`dist/esm`:** Deploys as native ES Modules, preserving the dev mode's file structure for efficient modular loading in modern browsers.
+    *   **`dist/production`:** Generates highly optimized, thread-specific bundles using Webpack for maximum compatibility and minification.
+    *   **`dist/development`:** A bundled but unminified environment for debugging production-specific issues or for TypeScript preference, serving as a bridge to traditional build-based workflows.
+    *   **Dynamic Module Loading:** Neo.mjs uniquely supports dynamically loading code-based modules (even with arbitrary `import` statements) from different environments at runtime, a powerful feature for plugin architectures or user-generated code that most other frameworks struggle with.
+
+*   **JSX vs. Plain Objects:** React uses JSX (requiring a build step for UI definition). Neo.mjs uses plain JavaScript objects for VDOM (no JSX compilation needed for VDOM definition).
+*   **Side Effects:** Both frameworks advocate for managing side effects outside the pure render function. React uses `useEffect`. Neo.mjs uses separate `Neo.core.Effect` instances or dedicated hooks for side effects.
+*   **Ecosystem & Maturity:** React has a massive, mature ecosystem with abundant libraries, tools, and community support. Neo.mjs has a smaller but dedicated community, with a focus on framework-level solutions and integrated features.
+*   **Learning Curve:** React's initial learning curve can be gentle, but mastering its performance optimizations (memoization, context, custom hooks) can be complex. Neo.mjs has a steeper initial learning curve due to its worker-based architecture, but once understood, it offers inherent performance benefits.
+*   **Dependency Management (Batteries Included):** React projects often involve a large `node_modules` directory and can lead to complex dependency trees and version conflicts, a common pain point often referred to as "dependency hell." Neo.mjs, in contrast, is a "batteries included" framework. It literally has zero real runtime dependencies outside of its own core. This native ES Module approach and integrated framework significantly reduces this complexity, offering a much leaner and more controlled dependency management experience.
+
+## Conclusion: Why Neo.mjs Offers Significant Technical Advantages Over React
+
+For applications where guaranteed Main Thread responsiveness, high performance under load, leveraging multi-core processing, and long-term maintainability are paramount, Neo.mjs presents a compelling and technically superior alternative.
+
+*   **Unblocked Main Thread & Inherent Performance:** Neo.mjs's unique worker-based architecture fundamentally shifts application logic off the Main Thread. This ensures the UI remains fluid and responsive even during heavy computations, leading to inherently higher performance ceilings without the need for extensive manual optimizations common in React.
+*   **Optimized & Precise DOM Updates:** Through off-Main-Thread VDOM diffing, sophisticated batching, and surgical direct DOM API updates, Neo.mjs achieves highly efficient and smooth visual updates, precisely targeting changes and avoiding unnecessary re-renders.
+*   **Linear Effort for Complexity:** Unlike frameworks where effort can grow exponentially with application complexity, Neo.mjs's unified config system, predictable component lifecycle, and modular design enable a more linear relationship between complexity and development effort, leading to faster development cycles and lower maintenance costs in the long run.
+
+The choice between them depends on the specific application's needs. For applications where guaranteed Main Thread responsiveness, high performance under load, leveraging multi-core processing, and long-term maintainability are paramount, Neo.mjs presents a compelling and technically superior alternative.

package/learn/comparisons/NeoVsSolid.md

@@ -0,0 +1,78 @@
+# Neo.mjs vs Solid.js
+
+Neo.mjs is a comprehensive JavaScript ecosystem for building high-performance, multi-threaded web applications. Unlike libraries such as Solid.js that focus purely on rendering and are typically part of a manually assembled toolchain, Neo.mjs is a self-contained system with **zero runtime dependencies**. It provides a complete, out-of-the-box solution that includes four distinct development and deployment environments, from a revolutionary zero-builds development mode to thread-optimized production bundles.
+
+This article provides a focused comparison between the Neo.mjs ecosystem and Solid.js. While both frameworks leverage fine-grained reactivity for high performance, they employ fundamentally different architectural and rendering strategies to achieve their goals. We will explore their approaches to **rendering, reactivity, and DOM updates**, highlighting the trade-offs between Solid's "no-VDOM," Main-Thread-bound model and Neo.mjs's holistic, worker-based paradigm.
+
+## Core Similarities: Fine-Grained Reactivity
+
+At their heart, both frameworks share the philosophy of **fine-grained reactivity**:
+
+*   **Direct Updates:** When a piece of reactive state changes, only the specific parts of the UI that directly depend on that state are updated. This minimizes unnecessary re-renders of entire component trees, a common performance bottleneck in traditional Virtual DOM frameworks.
+*   **Reactive Primitives:**
+    *   **Solid.js:** Utilizes "signals" (`createSignal`) as its primary reactive primitive.
+    *   **Neo.mjs:** Employs `Neo.core.Config` instances as its core reactive primitive.
+*   **Automatic Dependency Tracking:** Both frameworks automatically detect dependencies. When code executes within a reactive context (e.g., an effect, a memo, or a component's render logic), any reactive primitive accessed during that execution is automatically subscribed to. This eliminates the need for manual dependency declarations in many cases.
+
+## Key Differences: Architectural & Rendering Strategies
+
+This is where the two frameworks diverge significantly, each offering unique trade-offs.
+
+### 1. Rendering Mechanism: A Tale of Two Architectures
+
+*   **Solid.js: No VDOM—A Consequence of Single-Threaded Design**
+    *   Because it operates entirely on the Main Thread, Solid.js can forgo a Virtual DOM. It compiles JSX directly into highly optimized, imperative JavaScript instructions that create and surgically manipulate the real DOM.
+    *   When a signal (which holds an immutable value) updates, Solid's reactive graph knows precisely which DOM node to change and updates it directly, without any VDOM diffing overhead.
+    *   **Benefit:** This "no VDOM" approach is extremely fast for DOM updates, as it eliminates the overhead of VDOM reconciliation. This is the peak of Main-Thread rendering performance.
+
+*   **Neo.mjs: VDOM as a Necessity for Multi-Threading**
+    *   For Neo.mjs, a Virtual DOM is not an optional design choice—it is a **necessary and powerful consequence** of its multi-threaded architecture. Since components and application logic live in the App Worker, they have **no access to the DOM**.
+    *   The VDOM serves as the essential, serializable blueprint of the UI. It's a lightweight description defined using plain JavaScript objects (no JSX).
+    *   **Mutability by Design, Immutability in Process:** Neo.mjs allows for convenient, direct mutation of state and VDOM in the App Worker. When an update is triggered, it sends an immutable JSON snapshot of the VDOM to a dedicated VDom Worker for diffing. This provides developer convenience without sacrificing performance.
+    *   **Benefit:** This architecture makes off-thread VDOM diffing possible, which in turn guarantees Main Thread responsiveness. The overhead of the VDOM is the price for keeping the UI from ever freezing. The process is further optimized via atomic DOM insertions, where entire subtrees are built in a detached state and inserted into the live DOM in a single operation.
+
+### 2. Component Execution Model
+
+*   **Solid.js: Components Run Once**
+    *   Solid's functional components execute only *once* during their initial render. Their primary role is to set up the reactive graph (signals, effects, memos) and create the real DOM nodes. They do not re-run when state changes. Updates are handled by the fine-grained reactivity system directly updating the DOM.
+    *   **Benefit:** Extremely efficient, as component functions are not re-executed.
+
+*   **Neo.mjs: `createVdom` Re-runs Inside an Effect**
+    *   In Neo.mjs, the `createVdom` method of a functional component is wrapped in a `Neo.core.Effect`. This effect automatically tracks which `config` values it reads.
+    *   When a dependency changes, the `Effect` re-executes the `createVdom()` function to get a new VDOM description. This is fundamentally different from a React re-render, as it's a targeted re-execution of only the VDOM generation logic, not the entire component setup, and it doesn't cascade to children whose configs haven't changed.
+    *   **Benefit:** This model is highly intuitive (the VDOM function re-runs when its inputs change) and provides automatic, surgical updates without the developer needing to worry about manual dependency tracking or memoization.
+
+### 3. Overall Architecture
+
+*   **Solid.js: Single-Threaded (Main Thread Focused)**
+    *   Solid.js operates entirely on the main JavaScript thread. Its optimizations are focused on making the Main Thread's work as fast and efficient as possible.
+    *   **Benefit:** Simpler deployment and debugging model, as all JavaScript runs in one context.
+
+*   **Neo.mjs: Worker-Based (Main Thread + App Worker + VDom Worker)**
+    *   This is Neo.mjs's most distinctive feature. Application logic (including component instances, state, and `vdomEffect`s) runs in a dedicated **App Worker**, separate from the Main Thread. The VDOM diffing occurs in a **VDom Worker**.
+    *   Communication between workers and the Main Thread happens via message passing.
+    *   **Benefit:** Keeps the Main Thread free and responsive, preventing UI freezes even during heavy computations or complex application logic. It inherently leverages multi-core CPUs for parallel processing.
+
+### 4. Update Aggregation & Batching
+
+*   **Solid.js:** Relies on its fine-grained reactivity and direct DOM manipulation for efficient updates. While it has its own batching mechanisms for signal updates, it doesn't have a VDOM reconciliation phase to aggregate changes.
+*   **Neo.mjs:** Employs sophisticated batching and aggregation:
+    *   **Roundtrip-Based Batching:** Multiple reactive changes within a single tick can be batched into one VDom worker request.
+    *   **VDom Tree Aggregation (`VdomLifecycle`):** Changes in child components can be aggregated into a parent's update. If a parent is updating, a child's update is deferred and its changes are included in the parent's VDOM diff, minimizing redundant VDom worker roundtrips.
+    *   **`requestAnimationFrame` Aggregation:** The final application of deltas on the Main Thread (via `DeltaUpdates`) is implicitly batched by the browser's `requestAnimationFrame` cycle, ensuring all DOM changes for a frame are applied efficiently.
+    *   **Benefit:** This multi-layered batching and aggregation strategy leads to significantly fewer real DOM changes and smoother visual updates, especially in complex applications.
+
+### Other Considerations:
+
+*   **JSX vs. Plain Objects:** Solid uses JSX (requiring a build step), while Neo.mjs uses plain JavaScript objects for VDOM (no JSX compilation needed). **This means Neo.mjs's VDOM is defined using simple nested JavaScript objects and arrays, akin to a JSON-like description of the DOM.**
+*   **Side Effects:** Solid has explicit `createEffect` and `createRenderEffect` hooks for managing side effects. In Neo.mjs, `createVdom` is the primary effect for rendering, and other side effects would typically be managed by separate `Neo.core.Effect` instances or dedicated hooks.
+*   **Ecosystem & Maturity:** Solid.js has a growing community and ecosystem. Neo.mjs has a smaller but dedicated community, with a focus on framework-level solutions.
+
+## Conclusion
+
+Both Neo.mjs and Solid.js are highly performant, modern reactive frameworks.
+
+*   **Solid.js** excels by completely sidestepping the Virtual DOM, compiling directly to efficient DOM operations, and running components only once. It's a lean, fast choice for Main Thread-bound applications.
+*   **Neo.mjs** offers a unique value proposition with its worker-based architecture, offloading heavy computation from the Main Thread to ensure UI responsiveness. It combines this with a sophisticated VDOM pipeline that includes off-Main-Thread diffing, intelligent batching/aggregation, and surgical direct DOM API updates.
+
+The choice between them depends on the specific application's needs: Solid.js for ultimate Main Thread rendering speed, and Neo.mjs for guaranteed Main Thread responsiveness and leveraging multi-core processing, especially in complex, data-intensive applications.

package/learn/comparisons/NeoVsVue.md

@@ -0,0 +1,92 @@
+# Neo.mjs vs Vue.js
+
+Neo.mjs is a comprehensive JavaScript ecosystem for building high-performance, multi-threaded web applications. Unlike frameworks like Vue.js, which operate within a single-threaded browser environment, Neo.mjs is a self-contained system with **zero runtime dependencies**. It provides a complete, out-of-the-box solution that includes four distinct development and deployment environments, from a revolutionary zero-builds development mode to thread-optimized production bundles.
+
+This article provides a focused comparison between the Neo.mjs ecosystem and Vue.js. While both frameworks share a commitment to reactivity and component-based architecture, their underlying philosophies on how to achieve performance and scalability are fundamentally different. We will explore their approaches to **architecture, rendering, and reactivity**, highlighting the trade-offs between Vue's highly optimized, single-threaded model and Neo.mjs's holistic, worker-based paradigm.
+
+## Foundational Concepts: A Shared Heritage
+
+Despite their architectural differences, both frameworks build upon foundational concepts that have shaped modern UI development:
+
+*   **Component-Based Architecture:** Both frameworks champion building UIs as a composition of reusable components. Neo.mjs extends this with `Neo.core.Base`, allowing any class-based entity (controllers, models, etc.) to leverage the framework's powerful class system, even without a UI.
+*   **Declarative UI:** Developers describe *what* the UI should look like for a given state, and the framework handles *how* to update the DOM.
+*   **Reactive Paradigm:** Both are built on reactive principles where UI updates are driven by changes in state. Vue's reactivity system is renowned for its efficiency and ease of use.
+*   **Functional Components & Modern APIs:** Both support defining components as functions (or with script setup in Vue) and provide APIs (Hooks in Neo.mjs, Composition API in Vue) for managing state and side effects.
+
+## Key Differences: Architectural & Rendering Strategies
+
+This is where the two frameworks diverge significantly, each offering unique trade-offs and advantages.
+
+### 1. Overall Architecture: Main Thread vs. Worker-Based
+
+*   **Vue.js: Main Thread Focused**
+    *   Vue applications run entirely on the Main JavaScript Thread. All component logic, state management (e.g., Pinia), VDOM reconciliation, and direct DOM manipulation occur on this single thread.
+    *   **Implication:** Vue is exceptionally well-optimized for the Main Thread. Its reactivity system is designed to minimize unnecessary work. However, it is still fundamentally bound by the single-threaded nature of JavaScript. Very complex computations or large, synchronous state updates can still potentially block the Main Thread, impacting the user experience in data-heavy, high-frequency update scenarios.
+
+*   **Neo.mjs: Worker-Based (Main Thread + App Worker + VDom Worker)**
+    *   Neo.mjs's defining feature is its multi-threaded architecture. Application logic (component instances, state, business logic, `vdomEffect`s) runs in a dedicated **App Worker**, separate from the Main Thread. The VDOM diffing occurs in a **VDom Worker**.
+    *   Communication between workers and the Main Thread happens via asynchronous message passing.
+    *   **Benefit:** This architecture keeps the Main Thread almost entirely free and responsive, preventing UI freezes even during heavy computations or complex application logic. It inherently leverages multi-core CPUs for parallel processing, leading to superior UI responsiveness and performance under heavy load.
+
+### 2. Rendering Mechanism
+
+*   **Vue.js: Main-Thread VDOM & Compiler-Optimized Updates**
+    *   Vue uses a Virtual DOM and a sophisticated compiler. During the build process, Vue's template compiler analyzes templates and converts them into highly optimized render functions.
+    *   **VDOM Definition:** Primarily uses Single-File Components (SFCs) with HTML-like templates, which are compiled into JavaScript render functions. It also supports JSX.
+    *   **Compiler Intelligence:** The compiler can detect static parts of a template and hoist them out of the render function, so they are created only once. It also applies other optimizations, such as patching flags, to help the runtime VDOM diffing algorithm take fast paths and skip unnecessary checks. This makes Vue's rendering extremely efficient on the Main Thread.
+
+*   **Neo.mjs: Off-Thread VDOM & Developer-Friendly Mutability**
+    *   Neo.mjs also uses a Virtual DOM, but its philosophy and implementation are fundamentally different. The VDOM is defined using plain JavaScript objects and arrays—no special template syntax or build step is required for UI definition.
+    *   **Mutability by Design, Immutability in Process:** Neo.mjs embraces developer convenience by allowing **direct, mutable manipulation** of component state (configs) and the VDOM structure within the App Worker. This eliminates the boilerplate and cognitive load of managing immutable updates. The architectural brilliance lies in how it achieves the benefits of immutability: when an update is triggered, Neo.mjs creates a **JSON snapshot** of the relevant VDOM tree. This snapshot is sent to the VDom Worker, making the *update process itself* immutable and predictable for diffing. This provides the best of both worlds: simple, direct mutation for the developer and a safe, immutable structure for the high-performance diffing algorithm in another thread.
+    *   **Off-Main-Thread Diffing:** The entire VDOM diffing process occurs in the dedicated **VDom Worker**, completely freeing the Main Thread from this heavy computation.
+    *   **Scoped VDOM (Encapsulation & Performance):** The VDom Worker sends only the "deltas" (a minimal set of change instructions) back to the Main Thread. For insertions, `DomApiRenderer` **builds the entire new DOM subtree in memory**, completely detached from the live document, and inserts it in a **single, atomic operation**. Furthermore, Neo.mjs's VDOM is **scoped by default**. When a parent component renders, its children are represented by simple `{componentId: '...'}` placeholders. This provides two key advantages:
+        1.  **Performance:** A parent's update never processes the complex VDOM of its children, keeping update payloads extremely small and efficient.
+        2.  **Encapsulation:** It is architecturally impossible for a parent to accidentally reach into and manipulate a child's internal VDOM structure. This enforces clear ownership and prevents a wide class of bugs.
+
+### 3. Component Execution Model: Precision vs. Optimization
+
+*   **Vue.js: Fine-Grained Reactivity & Optimized Re-Renders**
+    *   Vue's reactivity system is one of its most celebrated features. When a piece of reactive state (e.g., from `ref` or `reactive`) changes, Vue automatically tracks which components depend on it and triggers updates only for those specific components.
+    *   It avoids the "cascading re-render" problem of React by default. If a parent component re-renders, it will not unnecessarily re-render child components whose props have not changed. This is a significant performance advantage and a core part of Vue's design.
+
+*   **Neo.mjs: Surgical Effects & Automatic Efficiency**
+    *   Neo.mjs's model achieves a similar outcome through a different mechanism. A component's `createVdom` method is wrapped in a `Neo.core.Effect`. This effect automatically and dynamically tracks its dependencies—the specific `config` values it reads.
+    *   When a config value changes, only the specific `createVdom` effects that depend on that *exact* piece of state are queued for re-execution. There are no cascading re-renders. If a parent's `createVdom` re-runs, but the configs passed to a child have not changed, the child component's `createVdom` function is **never executed**.
+    *   **Benefit (Zero Manual Optimization):** Like Vue, this fine-grained reactivity eliminates the need for manual memoization (`memo`, `useCallback`, `useMemo`) that plagues React development. The framework handles dependency tracking automatically and precisely, delivering optimal performance out-of-the-box.
+
+### 4. Scaling Complexity: Linear Effort vs. Main-Thread Limits
+
+A key differentiator between the frameworks is how they handle growing application complexity.
+
+*   **Vue.js: Optimized for Main-Thread Scalability**
+    *   Vue is designed to scale gracefully on the Main Thread. Its reactivity system and compiler optimizations ensure that as an application grows, performance remains high. State management with Pinia is also highly optimized.
+    *   However, the fundamental limitation remains: all work competes for the same single thread. For extremely data-intensive applications, like real-time financial dashboards or complex graphical editors, the Main Thread can still become a bottleneck, no matter how optimized the framework is.
+
+*   **Neo.mjs: Built-in Efficiency and Linear Effort**
+    *   Neo.mjs's architecture is designed to handle this scenario effortlessly. Multiple state changes are automatically batched into a single, de-duplicated update cycle via the `EffectBatchManager`.
+    *   In a complex dashboard scenario, if a value in a global `StateProvider` changes, only the `createVdom` effects in components that *directly depend on that specific value* will re-run. All other components remain untouched. The crucial difference is that this logic runs in the **App Worker**, and the VDOM diffing runs in the **VDom Worker**, leaving the Main Thread free.
+    *   This leads to a **linear relationship between complexity and effort**. As you add more components, you don't need to add more performance optimizations. The framework's core design ensures that updates are always surgical and efficient, allowing developers to focus on features instead of fighting the rendering engine. This is a direct result of the sophisticated, multi-layered batching and aggregation built into the framework's core.
+
+### Other Considerations:
+
+*   **Development & Deployment Environments:** Neo.mjs offers four distinct environments, providing unparalleled flexibility:
+    *   **Zero Builds Development Mode:** The primary development workflow, leveraging native ES Modules for instant code reflection and debugging without a build step. This contrasts with Vue's typical SFC-based development which always requires a build process (e.g., Vite).
+    *   **`dist/esm`:** Deploys as native ES Modules, preserving the dev mode's file structure.
+    *   **`dist/production`:** Generates highly optimized, thread-specific bundles using Webpack.
+    *   **`dist/development`:** A bundled but unminified environment for debugging production-specific issues.
+    *   **Dynamic Module Loading:** Neo.mjs uniquely supports dynamically loading code-based modules (even with arbitrary `import` statements) from different environments at runtime, a powerful feature for plugin architectures.
+
+*   **Templates vs. Plain Objects:** Vue primarily uses HTML-like templates in SFCs (requiring a build step). Neo.mjs uses plain JavaScript objects for VDOM (no compilation needed for VDOM definition).
+*   **Ecosystem & Maturity:** Vue has a massive, mature ecosystem with a rich collection of libraries, tools (like Vite and Vue Devtools), and extensive community support. Neo.mjs has a smaller but dedicated community, with a focus on framework-level solutions and integrated features.
+*   **Learning Curve:** Vue is famous for its gentle learning curve and excellent documentation. Neo.mjs has a steeper initial learning curve due to its worker-based architecture, but once understood, it offers inherent performance benefits that don't require manual tuning.
+*   **Dependency Management (Batteries Included):** Vue projects, while often leaner than React, still rely on `node_modules` and a build toolchain. Neo.mjs is a "batteries included" framework with zero real runtime dependencies outside of its own core. This native ES Module approach significantly reduces complexity and dependency management overhead.
+
+## Conclusion: Why Neo.mjs Offers Significant Technical Advantages Over Vue.js
+
+For applications where guaranteed Main Thread responsiveness, high performance under load, leveraging multi-core processing, and long-term maintainability are paramount, Neo.mjs presents a compelling and technically superior alternative.
+
+*   **Unblocked Main Thread & Inherent Performance:** While Vue is highly optimized for the Main Thread, Neo.mjs's unique worker-based architecture fundamentally removes application logic from the Main Thread entirely. This is not an optimization strategy but a core architectural principle, ensuring the UI remains fluid and responsive even during heavy computations that would challenge any single-threaded framework.
+*   **True Parallelism:** Neo.mjs doesn't just optimize tasks on the Main Thread; it runs them in parallel on separate threads. This provides a higher performance ceiling for complex, data-intensive applications.
+*   **Linear Effort for Complexity:** Like Vue, Neo.mjs avoids unnecessary re-renders. However, by offloading this work to workers, it ensures that even complex update cycles have zero impact on the Main Thread's availability, allowing for more scalable and maintainable applications in the long run.
+
+The choice between them depends on the specific application's needs. For many content-driven sites and standard business applications, Vue's performance and developer experience are excellent. For applications pushing the boundaries of complexity and performance, where guaranteed UI fluidity is a critical requirement, Neo.mjs offers a fundamentally more robust and scalable architecture.

package/learn/comparisons/Overview.md

@@ -0,0 +1,46 @@
+# Overview
+
+## Framework Comparisons
+
+This section provides detailed comparisons between Neo.mjs and other popular JavaScript frameworks. Our goal is to help
+you understand the key similarities, differences, and unique advantages of Neo.mjs in relation to technologies you might
+already be familiar with.
+
+We aim to compare these frameworks from a **technical, objective, and constructive perspective**, focusing on how
+different architectural choices and design philosophies address common web development challenges. Please note that
+these comparison documents were generated with the assistance of a large language model (Gemini).
+
+Each comparison article will focus on:
+
+*   **Bridging Knowledge Gaps:** Mapping concepts you know to Neo.mjs.
+*   **Highlighting Differentiators:** What makes Neo.mjs unique.
+*   **Side-by-Side Analysis:** Feature-by-feature comparisons.
+*   **Trade-offs and Use Cases:** When Neo.mjs might be the optimal choice.
+
+### Architectural Snapshot
+
+The table below offers a high-level architectural comparison of the frameworks discussed in this section. It is designed
+to provide a quick snapshot of their core differences. For a deeper understanding, please refer to the detailed comparison
+articles.
+
+| Feature                 | Neo.mjs                                | React                                   | Vue.js                               | Solid.js                                | Angular                                 |
+| ----------------------- |----------------------------------------| --------------------------------------- | ------------------------------------ | --------------------------------------- | --------------------------------------- |
+| **Core Architecture**   | Multi-Threaded (Worker-Based)          | Single-Threaded (Main-Thread Bound)     | Single-Threaded (Main-Thread Bound)  | Single-Threaded (Main-Thread Bound)     | Single-Threaded (Main-Thread Bound)     |
+| **VDOM Location**       | App Worker                             | Main Thread                             | Main Thread                          | No VDOM (Direct DOM Updates)            | Main Thread                             |
+| **Reactivity Model**    | Fine-Grained (Surgical Atomic Updates) | Cascading Re-Renders (Manual Memo)      | Fine-Grained (Compiler-Assisted)     | Fine-Grained (Non-Destructive)          | Zone.js (Automatic Change Detection)    |
+| **Manual Optimizations**| Not Required                           | Required (`memo`, `useCallback`, `useMemo`) | Not Required                         | Not Required                            | Not Required                            |
+| **State Mutability**    | Directly Mutable                       | Immutable (Enforced)                    | Mutable (Proxied)                    | Mutable (Proxied)                       | Mutable (Observable-based)              |
+| **Dev Environment**     | Zero-Builds (Instant)                  | Build-Based (Vite, etc.)                | Build-Based (Vite)                   | Build-Based (Vite)                      | Build-Based (Angular CLI)               |
+| **Multi-Window Support**| Native (Shared Data/Components)        | Limited/Requires Custom Logic           | Limited/Requires Custom Logic        | Limited/Requires Custom Logic           | Limited/Requires Custom Logic           |
+
+### Available Comparisons
+
+*   [Neo.mjs vs. React](/learn/comparisons/NeoVsReact.md)
+*   [Neo.mjs vs. Angular](/learn/comparisons/NeoVsAngular.md)
+*   [Neo.mjs vs. Vue.js](/learn/comparisons/NeoVsVue.md)
+*   [Neo.mjs vs. Solid.js](/learn/comparisons/NeoVsSolid.md)
+*   [Neo.mjs vs. Next.js](/learn/comparisons/NeoVsNextJs.md)
+*   [Neo.mjs vs. Ext.js](/learn/comparisons/NeoVsExtJs.md)
+
+If you have feedback on any of our comparisons or would like to see a new one, please feel free to open an issue on our
+[GitHub repository](https://github.com/neomjs/neo/issues).

package/learn/gettingstarted/ComponentModels.md

@@ -1,3 +1,5 @@
+# Shared Bindable Data
+
 Neo has a feature that allows shared, bindable, data.
 
 A _state provider_ — `Neo.state.Provider` — instance holds properties that 

package/learn/gettingstarted/Config.md

@@ -1,3 +1,5 @@
+# Config
+
 As you've probably noticed, Neo.mjs classes have a `static config` property. 
 
 The config describes properties you can specify as you create an instance of the class.

package/learn/gettingstarted/DescribingTheUI.md

@@ -1,3 +1,5 @@
+# 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. 
 

package/learn/gettingstarted/Events.md

@@ -1,3 +1,5 @@
+# Events
+
 All components fire events. For example, form fields fire a `change` event, various 
 focus events, and others. Some other types fire events too, such as `Neo.data.Store`, 
 which fires a `load` event after the store is loaded with data.

package/learn/gettingstarted/Extending.md

@@ -1,3 +1,5 @@
+# Extending Classes
+
 In theory, a Neo.mjs app could be defined in a single `.mjs` source file. But that would be very hard to 
 maintain, and any reusable configs would have to be duplicated. Instead, each of your views and reusable 
 widgets will be defined as its own class. The result is simpler views which are inherently reusable and easier 

package/learn/gettingstarted/References.md

@@ -1,3 +1,5 @@
+# Component References
+
 Controllers often need to get references to components in order to update 
 the UI or access component properties. 
 There are two common ways of doing that:

package/learn/gettingstarted/Setup.md

@@ -1,3 +1,5 @@
+# Setup
+
 Setting up Neo.mjs is pretty easy — all you have to do is confirm that you have some required
 software then follow a single npx script.
 
@@ -5,9 +7,8 @@ software then follow a single npx script.
 
 Before you get started, Neo.mjs requires that you have a few of things installed: 
 
-- npm (see <a href="https://docs.npmjs.com/downloading-and-installing-node-js-and-npm" target="_blank">https://docs.npmjs.com/downloading-and-installing-node-js-and-npm</a>)
+- npm & nodejs (see <a href="https://docs.npmjs.com/downloading-and-installing-node-js-and-npm" target="_blank">https://docs.npmjs.com/downloading-and-installing-node-js-and-npm</a>)
 - npx (see <a href="https://www.npmjs.com/package/npx" target="_blank">https://www.npmjs.com/package/npx</a>)
-- node (see <a href="https://nodejs.org/en/download" target="_blank">https://nodejs.org/en/download</a>)
 
 ## Installation
 

package/learn/gettingstarted/Workspaces.md

@@ -1,3 +1,5 @@
+# Workspaces and Applications
+
 The purpose of this tutorial is to let you see the structure of a Neo.mjs workspace,
 and the structure of an application.
 

package/learn/guides/datahandling/Collections.md

@@ -1,3 +1,4 @@
+# Collections
 
 Neo.mjs provides a powerful and flexible `Neo.collection.Base` class for managing data. This guide will explore its
 features, including:

package/learn/guides/datahandling/Records.md

@@ -1,3 +1,4 @@
+# Records
 
 In Neo.mjs, a **Record** is a super lightweight, reactive JavaScript object, dynamically created and structured
 according to a `Neo.data.Model`. Records provide a powerful way to manage application data with built-in features like