neo.mjs 10.3.2 → 10.3.3

package/.github/RELEASE_NOTES/v10.3.3.md

@@ -0,0 +1,14 @@
+# Neo.mjs v10.3.3 Release Notes
+
+This patch release introduces a major new deep-dive article on our rendering architecture and enhances our framework comparison documentation.
+
+## New Content & Documentation
+
+- **New Blog Post: The Surgical Update: From JSON Blueprints to Flawless UI**
+  - A comprehensive deep dive into the Neo.mjs off-thread rendering engine.
+  - Explores key concepts like the secure `DomApiRenderer`, asymmetric update batching, and how our architecture preserves DOM state (e.g., for a playing `<video>`).
+  - This is the fourth article in the v10 blog post series.
+
+- **Enhanced Framework Comparisons**
+  - The comparison documents for React, Vue, and Angular have been updated with a new section: **"Component Mobility: Portals vs. True Persistence."**
+  - This section details the architectural advantages of Neo.mjs's persistent component model for moving stateful DOM elements, a common challenge for single-threaded frameworks.

package/README.md

@@ -124,7 +124,8 @@ That’s Neo.mjs in action — solving problems others can’t touch.
 * **Multi-Window & Single-Page Applications (SPAs)***: Beyond traditional SPAs, Neo.mjs excels at complex multi-window applications.
   Its unique architecture, powered by seamless cross-worker communication (enabled by `Neo.worker.mixin.RemoteMethodAccess`) and
   extensible Main Thread addons (`Neo.main.addon.*`), enables truly native-like, persistent experiences across browser windows,
-  all without a native shell.
+  all without a native shell. This is made possible by the same efficient delta-based DOM update engine, which can surgically
+  move and update components across window boundaries with unparalleled performance.
 
 * **No npm Dependency Hell**: Neo.mjs apps run with **zero runtime dependencies**, just a few dev dependencies for tooling.
   This means smaller bundles, fewer conflicts, and a simpler dependency graph.

package/ServiceWorker.mjs

@@ -20,9 +20,9 @@ class ServiceWorker extends ServiceBase {
          */
         singleton: true,
         /**
-         * @member {String} version='10.3.2'
+         * @member {String} version='10.3.3'
          */
-        version: '10.3.2'
+        version: '10.3.3'
     }
 
     /**

package/apps/portal/index.html

@@ -16,7 +16,7 @@
         "@type": "Organization",
         "name": "Neo.mjs"
       },
-      "datePublished": "2025-08-03",
+      "datePublished": "2025-08-04",
       "publisher": {
         "@type": "Organization",
         "name": "Neo.mjs"

package/apps/portal/resources/data/blog.json

@@ -1,4 +1,16 @@
 [{
+    "author"      : "Tobias Uhlig",
+    "authorImage" : "author_TobiasUhlig.jpeg",
+    "date"        : "Aug 04, 2025",
+    "id"          : 68,
+    "image"       : "VdomRevolution.png",
+    "name"        : "The Surgical Update: From JSON Blueprints to Flawless UI",
+    "provider"    : "Medium",
+    "publisher"   : "ITNEXT",
+    "selectedInto": [],
+    "type"        : "Blog Post",
+    "url"         : "https://itnext.io/the-surgical-update-from-json-blueprints-to-flawless-ui-fcba31575f44?source=friends_link&sk=d2084a1ed9d5fc512859320895550080"
+}, {
     "author"      : "Tobias Uhlig",
     "authorImage" : "author_TobiasUhlig.jpeg",
     "date"        : "Jul 28, 2025",

package/apps/portal/view/home/FooterContainer.mjs

@@ -108,7 +108,7 @@ class FooterContainer extends Container {
             }, {
                 module: Component,
                 cls   : ['neo-version'],
-                text  : 'v10.3.2'
+                text  : 'v10.3.3'
             }]
         }],
         /**

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

@@ -1,56 +1,137 @@
-# The VDOM Revolution: How We Render UIs from a Web Worker
+# The Surgical Update: From JSON Blueprints to Flawless UI
 
-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.
+**A deep dive into our off-thread rendering engine, which uses asymmetric batching and a secure `DomApiRenderer` to
+eliminate jank at an architectural level.**
 
-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?
+In a world where some frameworks declare the VDOM "pure overhead," we've made a radical bet: we've doubled down on the
+VDOM and moved it entirely off the main thread. This isn't a defense of the traditional VDOM;
+it's a redefinition of its purpose.
+
+The debate between VDOM-based and "VDOM-less" frameworks misses the point. Both are fundamentally limited by the same
+bottleneck: the single main thread where your application logic, state management, and rendering all compete for resources.
+The result is inevitable—every complex calculation is a potential source of UI jank.
+
+The recent introduction of the React Compiler is a brilliant validation of this very problem. By automating memoization,
+the React team acknowledges that managing performance on the main thread is a major burden. But automated memoization is
+still memoization—an extra layer of overhead added to your application, just hidden by a tool. It’s the most advanced
+solution possible for a single-threaded architecture.
+
+Neo.mjs offers a different path. Our architecture is designed to make the cost of updates so low that performance
+memoization becomes unnecessary. We don't automate the tax; we eliminate it.
+
+Neo.mjs solves this by changing the battlefield. For any true off-main-thread architecture, a VDOM isn't a choice—it's a
+**necessity**. Since a Web Worker cannot directly access the DOM, it needs a serializable, abstract representation of
+the UI to send to the main thread. That representation *is* a Virtual DOM. We treat it not as a rendering engine, but
+as the essential **cross-thread communication protocol**. This same protocol is the foundation for true multi-window
+applications, allowing a single App Worker to seamlessly synchronize the UI across multiple browser windows—a feat
+impossible for single-threaded frameworks.
+
+This architectural shift is the real revolution. It forces us to answer fascinating new questions: How do you best
+communicate UI changes between threads? And, most critically, what is the ideal language for describing a UI when it's
+being built not by a human, but by a machine? The answer is simple, structured data—a language that AI understands natively.
+This is the foundation for the next generation of applications.
 
 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.
+1.  **Three Philosophies of UI Definition:** How Neo.mjs offers multiple layers of abstraction for building UIs, from
+    high-level declarative trees to low-level VDOM blueprints.
 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.
+    leads to a more performant and secure system.
 
 *(Part 4 of 5 in the v10 blog series. Details at the bottom.)*
 
 ---
 
-## Part 1: The Blueprint - Why JSON is the Language of the Future UI
+## Part 1: The Three Philosophies of UI Definition
+
+Before diving into *how* the VDOM works, it's crucial to understand *what* we're building. Neo.mjs offers three distinct
+approaches to defining your UI, each with its own strengths.
+
+### 1. The OOP Way: Abstracting the DOM Away
+
+The most powerful and abstract way to build complex applications in Neo.mjs is the Object-Oriented approach. You compose
+your UI by creating `Container` classes and declaratively defining their child `items` as a configuration object.
+
+```javascript
+// Example of a declarative component tree
+import Container from '../../../../src/container/Base.mjs';
+import Toolbar   from '../../../../src/toolbar/Base.mjs';
+import Button    from '../../../../src/button/Base.mjs';
+
+class MyComponent extends Container {
+    static config = {
+        className: 'MyComponent',
+        layout   : {ntype: 'vbox', align: 'stretch'},
+        items    : [{
+            module: Toolbar,
+            items : [{module: Button, text: 'Button 1'}]
+        }, {
+            ntype: 'component',
+            text : 'Content Area'
+        }]
+    }
+}
+```
+
+With this method, you are not thinking about HTML, divs, or even the VDOM. You are describing your application in terms
+of its logical components and their relationships. This is the classic approach for building robust, enterprise-scale
+applications where separation of concerns and maintainability are paramount.
+
+From a Micro-Frontends perspective: The **named** configs here are the contract (API) available from the outside.
+Any run-time value change is reactive and will update the UI.
+
+### 2. The Functional Way: Direct VDOM Control with JSON Blueprints
+
+For functional components, or when you need to dynamically generate UI structures, you can drop down a level of
+abstraction and work directly with **JSON Blueprints**. This is the "native language" of the Neo.mjs rendering engine.
 
-The web industry has spent years optimizing the delivery of HTML. For content-heavy sites, Server-Side Rendering (SSR)
-and streaming HTML is a brilliant solution. But for complex, stateful applications—the kind needed for AI cockpits, IDEs,
-and enterprise dashboards—is sending pre-rendered HTML the ultimate endgame?
+The component's `render()` method returns a structured JSON object that describes the VDOM tree.
 
-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.
+We've seen this movie before. In the world of APIs, the verbose, heavyweight, and human-readable XML standard was
+inevitably supplanted by the lighter, simpler, and more machine-friendly JSON. We believe the same evolution is happening
+for defining complex UIs. While HTML is the language of the document, structured data is the language of the application.
 
-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.
+This approach has profound advantages:
 
-This approach has profound advantages, especially for the AI-driven applications of tomorrow:
+*   **Extreme Data Efficiency:** A JSON blueprint is drastically smaller than its equivalent rendered HTML.
+*   **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 API is
+    a far more reliable and constrained task than asking it to generate nuanced HTML.
+*   **Ultimate Control:** It gives you precise, programmatic control over the generated VDOM.
 
-*   **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
-    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 is the engine behind our AI-powered **Neo Studio** (super early spoiler),, which generates these JSON
+blueprints from natural language prompts.
 
-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](https://raw.githubusercontent.com/neomjs/pages/main/resources_pub/website/blog/NeoStudio.png "Neo Studio Spoiler")
 
-`[Screenshot of the Neo Studio UI, showcasing a generated component from a prompt]`
+### 3. The Onboarding Ramp: Developer-Friendly HTML Templates
 
-JSON blueprints are the language. Now let's look at the engine that translates them into a live application.
+While JSON is the framework's native tongue, we recognize the universal fluency of HTML. To lower the barrier to entry
+and provide a familiar authoring experience, the recent [v10.3.0 release](../../.github/RELEASE_NOTES/v10.3.0.md)
+introduced an intuitive, HTML-like syntax built on standard JavaScript Tagged Template Literals.
+
+```javascript
+// Inside a component's render() method:
+return html`
+    <div class="my-container">
+        <p>${config.myText}</p>
+        <${Button} text="Click Me" handler="${this.onButtonClick}" />
+    </div>
+`;
+```
+
+This is the **beginner mode**—an easy on-ramp for developers new to the framework. Crucially, this is **not JSX**. It's
+built on our core principle of a **zero-builds development experience**, running directly in the browser.
+
+To achieve this without sacrificing performance, we use a dual-mode architecture:
+1.  **Development:** Templates are parsed live in the browser.
+2.  **Production:** A build-time process transforms the templates directly into the same optimized **JSON VDOM blueprints**
+    used by the functional approach. The parser is completely removed, resulting in zero runtime overhead.
+
+This gives developers a choice: start with the familiar comfort of HTML templates, or use the raw power of JSON
+blueprints. For complex functional components, we still recommend using JSON directly for maximum clarity and performance.
+But for simpler components or for developers who prefer it, the template syntax is a powerful and welcome alternative.
+
+All three philosophies feed into the same revolutionary rendering engine. Now let's look at that engine.
 
 ---
 
@@ -69,6 +150,7 @@ the DOM in the Main Thread.
 
 On the Main Thread, the `Neo.main.DeltaUpdates` manager acts as a central orchestrator. It receives a stream of commands
 from the VDOM worker and uses the right tool for every job.
+Deltas are pushed into `requestAnimationFrame()`.
 
 #### For Creating New DOM: The `DomApiRenderer`
 
@@ -76,12 +158,41 @@ Whenever a new piece of UI needs to be created, the VDOM worker sends an `insert
 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
-`document.createElement()` and `element.textContent`. This completely eradicates the risk of XSS attacks that plague
-`innerHTML`-based rendering, providing a crucial safety net for UIs where an LLM might generate content or even structure.
+For all these creation tasks, our pipeline uses the [DomApiRenderer](../../src/main/render/DomApiRenderer.mjs).
+This renderer is not only fast but also **secure by default**. It achieves this by treating all content as plain text
+unless explicitly told otherwise. When processing a VDOM blueprint, it uses the safe `node.textContent` property for any
+`text` configs. This simple default required a framework-wide effort to ensure our entire component library uses `text`
+instead of `html`, fundamentally eliminating the risk of XSS attacks that plague `innerHTML`-based rendering. While
+developers can still use the `html` property at their own risk for trusted content, the framework's secure-by-default
+posture provides a crucial safety net, especially for UIs where an LLM might generate content or even structure.
+This zero-trust approach to rendering means that even if a malicious or malformed string were to be injected into a
+component's data, it is physically incapable of being executed as code in the browser.
+
+The renderer builds the entire new UI tree on a `DocumentFragment` that is detached from the live DOM, preventing layout
+thrashing. Only when the entire structure is complete is it appended to the document in a single, efficient operation.
+
+```javascript
+// A simplified look at the DomApiRenderer's core logic
+// Note: This runs on the Main Thread
+const createFragment = (vnode) => {
+    const fragment = document.createDocumentFragment();
+
+    // Recursively build the entire tree off-screen
+    vnode.childNodes?.forEach(child => {
+        const el = document.createElement(child.tag);
+        // ... logic for setting attributes, styles, etc.
+        fragment.appendChild(el);
+    });
+
+    return fragment;
+};
+
+// Later, in a single operation:
+parentElement.appendChild(createFragment(vnode));
+```
 
-Enabling this superior rendering engine is as simple as setting a flag in your project's configuration:
+Enabling this superior rendering engine is as simple as setting a flag in your project's configuration
+(Default value in v10):
 
 ```json
 {
@@ -90,6 +201,22 @@ Enabling this superior rendering engine is as simple as setting a flag in your p
 }
 ```
 
+But its real genius lies in how it handles complex insertions. This isn't just about performance; it's about **preserving
+the state of live DOM nodes**.
+
+Consider a `<video>` element that is currently playing. In many frameworks, moving that video component to a different
+part of the UI would destroy the old DOM node and create a new one, causing the video to jarringly restart from the
+beginning. This is because the rendering engine only knows how to create new things, not how to relocate existing ones.
+
+Neo.mjs avoids this entirely. Our architecture understands that the component instance is a persistent entity. When you
+move it, the [DomApiVnodeCreator](../../src/vdom/util/DomApiVnodeCreator.mjs) sees that the video component's DOM
+already exists. Instead of generating a VDOM blueprint to recreate it, it **prunes that entire branch** from the
+`insertNode` delta. The VDOM worker then issues a separate, highly efficient `moveNode` delta.
+
+The result on the main thread is a single, clean DOM operation: the existing `<video>` element is simply moved to its
+new location, **continuing to play without interruption**. This is the power of the pruned graph: it's an optimization
+that not only boosts performance but preserves the integrity and state of your UI.
+
 #### For Modifying Existing DOM: Surgical Updates
 
 When you change a property on an existing component—like its text, style, or attributes—the VDOM worker sends different
@@ -119,17 +246,107 @@ However, this had a limitation. The `updateDepth` was an "all or nothing" switch
 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 wasn't ideal.
 
-This is the exact challenge that **v10's Asymmetric Blueprints** were designed to solve.
+This is the exact challenge that **v10's Asymmetric Blueprints** were designed to solve. The magic lies in a
+sophisticated **pre-processing and negotiation phase** that happens entirely within the App Worker, *before* anything
+is sent to the VDOM worker.
+
+Here's how it works, with a more realistic example. Imagine a dashboard container with four cards. A user action causes
+the container's background to change, and simultaneously, the content of the second and fourth cards needs to update.
+
+**1. Negotiation & Aggregation:**
+The `VDomUpdate` manager is notified of three separate changes: one for the container and one for each of the two cards.
+Instead of sending three separate update requests across the worker boundary (which would be inefficient), it aggregates
+them. It initiates a single update on the top-most component in the hierarchy (the container) and passes the IDs of the
+other changed components (`card-2`, `card-4`) into the `TreeBuilder` via the `mergedChildIds` parameter.
+
+**2. The Asymmetric Build:**
+The [TreeBuilder](../../src/util/vdom/TreeBuilder.mjs) is called on the container. It knows it needs to generate the
+container's own VDOM, but instead of expanding all children, it follows a simple rule: "Expand only the children whose
+IDs are in the `mergedChildIds` set. For all others, create a lightweight placeholder."
+
+Here is the power of this approach in action.
+
+**Before: The Container's Own VDOM Blueprint**
+This is the simple structure the container holds before the update. It just references its children.
+```javascript
+// The container's vdom property just lists its children
+{
+    id: 'dashboard-container-1',
+    tag: 'div',
+    cn: [
+        { componentId: 'card-1' },
+        { componentId: 'card-2' },
+        { componentId: 'card-3' },
+        { componentId: 'card-4' }
+    ]
+}
+```
+
+**After: The Optimized Blueprint Sent to the VDOM Worker**
+The `TreeBuilder` produces a highly specific, asymmetric blueprint. It's a mix of detailed VDOM for the changed items
+and placeholders for the unchanged ones.
 
-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.
+```javascript
+// The TreeBuilder intelligently expands only what's necessary
+{
+    id: 'dashboard-container-1',
+    tag: 'div',
+    style: { background: '#f0f0f0' }, // The container's own change
+    cn: [
+        // Card 1 is untouched, so it becomes a placeholder
+        { componentId: 'card-1', neoIgnore: true },
+
+        // Card 2 changed, so its full VDOM is included
+        {
+            id: 'card-2',
+            tag: 'section',
+            cn: [
+                { tag: 'h2', text: 'Card 2 Header' },
+                { tag: 'p',  text: 'This is the NEW updated content.' }
+            ]
+        },
+
+        // Card 3 is untouched
+        { componentId: 'card-3', neoIgnore: true },
+
+        // Card 4 also changed
+        {
+            id: 'card-4',
+            tag: 'section',
+            cn: [
+                { tag: 'h2', text: 'Card 4 Header' },
+                { tag: 'p',  text: 'Another card with new text.' }
+            ]
+        }
+    ]
+}
+```
+
+**The Result: A Revolution in Efficiency and Correctness**
+
+The VDOM worker receives this pre-optimized blueprint. When it sees a node with `neoIgnore: true`, it **completely skips
+diffing that entire branch of the UI**, saving significant computation time.
 
-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.
+But the placeholders serve a second, equally critical purpose: **they preserve the structural integrity of the child
+list**. By keeping the original order and count of siblings intact, they ensure the diffing engine can correctly
+calculate where to insert a new node or move an existing one. Without them, the engine would see a list of two items
+instead of four and incorrectly create deltas to delete the other two cards. The placeholders allow the engine to
+distinguish between a simple update and a structural change, producing a minimal and—most importantly—*accurate* set of
+deltas to send to the main thread.
+
+This is the essence of the Asymmetric VDOM. It's not just about batching updates; it's about creating the smartest,
+most minimal blueprint possible *before* the expensive diffing process even begins.
+
+#### Inside the VDOM Worker: The Diffing Engine
+Once the optimized blueprint arrives at the VDOM worker, the second half of the revolution begins. Here, the plain JSON
+blueprint is inflated into a tree of `VNode` instances. This is a key architectural point: the `VNode` is a very
+lightweight wrapper class that exists *only* inside the VDOM worker. It performs no complex logic, but normalizes the
+raw JSON blueprint, ensuring every node has a consistent structure (e.g., an `id` and a `childNodes` array) for the
+diffing engine to process reliably.
+
+The `vdom.Helper` singleton then acts as the core diffing engine. It compares the new `VNode` tree to the previous one
+and, instead of generating HTML, produces an array of **deltas**—highly specific, low-level instructions for the main
+thread to execute.
 
 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,
@@ -140,22 +357,30 @@ and the framework automatically creates the most efficient update possible.
 
 ## Conclusion: An Engine Built for Tomorrow
 
-The VDOM Revolution in Neo.mjs isn't just a performance enhancement; it's a paradigm shift.
+The VDOM Revolution in Neo.mjs isn't just a performance enhancement; it's a paradigm shift that fundamentally changes
+what's possible on the web.
 
 By combining the declarative power of **JSON Blueprints** with the intelligent efficiency of **Asymmetric Rendering**,
-we've created an architecture that is:
+we've created an architecture that delivers on the promise of a truly non-blocking UI. For you, the developer,
+this means you can finally build applications that are:
 
--   **Faster:** Blazing-fast initial renders and surgically precise updates keep the UI fluid at all times.
--   **Smarter:** The multi-threaded design allows for intensive AI logic to run in the background without ever freezing
-    the user experience—a critical feature for AI-native apps.
--   **Future-Proof:** An engine where AI is not an afterthought, but a first-class citizen. It provides the perfect,
-    secure, and efficient foundation for building applications *with* AI, where LLMs can generate, manipulate, and render
-    complex UIs by speaking their native language: structured data.
+-   **Fast by Default:** Blazing-fast initial renders and surgically precise updates keep the UI fluid at all times,
+    without you having to think about it.
+-   **Intelligent & Unrestricted:** The multi-threaded design allows for intensive AI logic, complex calculations,
+    or heavy data processing to run in the background without ever freezing the user experience.
+-   **Future-Proof & AI-Native:** An engine where AI is not an afterthought, but a first-class citizen.
+    It provides the perfect, secure, and efficient foundation for building applications *with* AI, where LLMs can generate,
+    manipulate, and render complex UIs by speaking their native language: structured data.
 
 This is what it means to build a framework not just for the web of today, but for the applications of tomorrow.
 
-In our final article, we'll bring all three revolutions—Reactivity, Functional Components, and the VDOM—together and
-invite you to fall in love with frontend development all over again.
+### What's Next?
+
+- **See it in Action:** Explore our [Online Examples](https://neomjs.com/dist/esm/apps/portal/) to experience the fluid UI for yourself.
+- **Dive into the Code:** The entire framework is open source. [Check out the repo on GitHub](https://github.com/neomjs/neo) and see how it works.
+- **Join the Community:** Have questions? Join our [Slack Channel](https://join.slack.com/t/neomjs/shared_invite/zt-6c50ueeu-3E1~M4T9xkNnb~M_prEEOA) and connect with the team and other developers.
+
+In our final article, we'll bring all three revolutions—Reactivity, Functional Components, and the VDOM—together and show you why it's time to fall in love with frontend development all over again.
 
 ---
 

package/learn/comparisons/NeoVsAngular.md

@@ -66,6 +66,21 @@ This is where the two frameworks diverge significantly, each offering unique tra
     *   **Benefit:** This offers unparalleled speed and debugging clarity. Code changes are reflected instantly. Developers work directly with the real code in the browser's dev tools, eliminating the need for source maps and vastly simplifying debugging.
     *   While Neo.mjs provides a robust architecture, it offers significant flexibility within that structure (e.g., plain JS for VDOM, choice of functional or class components), allowing developers more freedom without sacrificing consistency.
 
+### 5. Component Mobility: Portals vs. True Persistence
+
+A critical architectural difference emerges when dealing with moving components around the UI, especially those with internal state (like a playing `<video>` or a complex third-party widget).
+
+*   **Angular: The CDK Portal**
+    *   Angular uses its Component Dev Kit (CDK) `cdkPortal` and `cdkPortalOutlet` to solve a common CSS layout problem: rendering a component's DOM subtree in a different physical location in the DOM (e.g., a modal at the end of `<body>`). This is a **rendering trick**.
+    *   The component's logical position in the Angular tree remains the same, but its DOM is "teleported" elsewhere.
+    *   **The Limitation:** If the component that *defines* the portal is destroyed (e.g., via `*ngIf`), its state is destroyed. The portal's content is completely recreated from scratch. A playing video would jarringly restart.
+
+*   **Neo.mjs: True Mobility by Design**
+    *   This is not a special feature in Neo.mjs; it is a **natural consequence of the architecture**.
+    *   Because component instances are stable and persistent, moving a component is a controlled data operation. A developer programmatically modifies the `items` arrays of the relevant containers, then calls `update()` on the **closest common ancestor**. This signals the framework to perform a single, efficient reconciliation that correctly identifies the component move. While calling `update()` on a higher-level ancestor would also work, targeting the closest one is a best practice that minimizes the scope of the update, showcasing the framework's focus on performance and developer control. This explicit, batch-friendly approach is a core architectural feature, not a hack.
+    *   The framework recognizes that the component's DOM node already exists. It issues a single, efficient `moveNode` command to the Main Thread.
+    *   **The Benefit:** The existing DOM node, with all its internal state, is simply unplugged from its old parent and plugged into the new one. A playing video continues to play, uninterrupted. This enables a level of UI fluidity and state preservation that is architecturally impossible in a single-threaded model where component identity is tied to its place in the template.
+
 ### Other Considerations:
 
 *   **Framework Rigidity vs. Flexible Structure:** Angular is often perceived as a "straightjacket" due to its highly opinionated and prescriptive nature, dictating specific patterns (e.g., NgModules, decorators, strict DI) that can limit flexibility and make it challenging to deviate from "the Angular way." Neo.mjs, while also a comprehensive framework, offers a different kind of opinionation. Its core architectural choices (worker-based, unified config system, `Neo.core.Base` for any class-based entity) provide a robust structure, but within that structure, it offers significant flexibility (e.g., plain JS for VDOM, choice of functional or class components, integrated features reducing external dependencies), allowing developers more freedom without sacrificing consistency.

package/learn/comparisons/NeoVsReact.md

@@ -136,6 +136,21 @@ This is where the two frameworks diverge significantly, each offering unique tra
     *   Neo.mjs's architecture makes props drilling an obsolete anti-pattern. The integrated `state.Provider` allows a deeply nested component to subscribe *only* to the precise slice of state it needs via its `bind` config or a `useConfig` hook.
     *   This creates a direct, performant, and surgical link between the state and the component that needs it, completely bypassing all intermediate components. It is more akin to a selector in a dedicated state management library, but it's a native, architectural feature of the framework.
 
+### 6. Component Mobility: Portals vs. True Persistence
+
+A critical architectural difference emerges when dealing with moving components around the UI, especially those with internal state (like a playing `<video>` or a complex third-party widget).
+
+*   **React: The Portal "Trick"**
+    *   React uses `ReactDOM.createPortal()` to solve a common CSS layout problem: rendering a component's DOM subtree in a different physical location in the DOM (e.g., a modal at the end of `<body>`). This is a **rendering trick**.
+    *   The component's logical position in the React tree remains the same, but its DOM is "teleported" elsewhere.
+    *   **The Limitation:** If the component that *defines* the portal is unmounted and remounted in a new location, its state is destroyed. The portal's content is completely recreated from scratch. A playing video would jarringly restart.
+
+*   **Neo.mjs: True Mobility by Design**
+    *   This is not a special feature in Neo.mjs; it is a **natural consequence of the architecture**.
+    *   Because component instances are stable and persistent, moving a component is a controlled data operation. A developer programmatically modifies the `items` arrays of the relevant containers, then calls `update()` on the **closest common ancestor**. This signals the framework to perform a single, efficient reconciliation that correctly identifies the component move. While calling `update()` on a higher-level ancestor would also work, targeting the closest one is a best practice that minimizes the scope of the update, showcasing the framework's focus on performance and developer control. This explicit, batch-friendly approach is a core architectural feature, not a hack.
+    *   The framework recognizes that the component's DOM node already exists. It issues a single, efficient `moveNode` command to the Main Thread.
+    *   **The Benefit:** The existing DOM node, with all its internal state, is simply unplugged from its old parent and plugged into the new one. A playing video continues to play, uninterrupted. This enables a level of UI fluidity and state preservation that is architecturally impossible in a single-threaded, ephemeral component model.
+
 ### Other Considerations:
 
 *   **Development & Deployment Environments:** Neo.mjs offers four distinct environments, providing unparalleled flexibility:

package/learn/comparisons/NeoVsVue.md

@@ -53,6 +53,21 @@ This is where the two frameworks diverge significantly, each offering unique tra
     *   **`initAsync()`**: This hook runs *after* construction but *before* the component is considered "ready." It allows for asynchronous setup (like data fetching or lazy-loading modules) to complete *before* the first render. This eliminates entire classes of UI flicker and race conditions at an architectural level.
     *   **`afterSetMounted()` & True Persistence**: A Neo.mjs component is a stable, persistent instance. It can be unmounted from the DOM (`mounted: false`) and later remounted without being destroyed. `afterSetMounted` fires reliably for both state changes. This persistence is the key to enabling true multi-window applications, where a component instance can be moved from one browser window to another while retaining its full state and logic.
 
+### 4. Component Mobility: Portals vs. True Persistence
+
+A critical architectural difference emerges when dealing with moving components around the UI, especially those with internal state (like a playing `<video>` or a complex third-party widget).
+
+*   **Vue.js: The `<Teleport>` Component**
+    *   Vue uses its built-in `<Teleport>` component to solve a common CSS layout problem: rendering a component's DOM subtree in a different physical location in the DOM (e.g., a modal at the end of `<body>`). This is a **rendering trick**.
+    *   The component's logical position in the Vue tree remains the same, but its DOM is "teleported" elsewhere.
+    *   **The Limitation:** If the component that *contains* the `<Teleport>` tag is unmounted and remounted in a new location (e.g., via `v-if`), its state is destroyed. The teleported content is completely recreated from scratch. A playing video would jarringly restart.
+
+*   **Neo.mjs: True Mobility by Design**
+    *   This is not a special feature in Neo.mjs; it is a **natural consequence of the architecture**.
+    *   Because component instances are stable and persistent, moving a component is a controlled data operation. A developer programmatically modifies the `items` arrays of the relevant containers, then calls `update()` on the **closest common ancestor**. This signals the framework to perform a single, efficient reconciliation that correctly identifies the component move. While calling `update()` on a higher-level ancestor would also work, targeting the closest one is a best practice that minimizes the scope of the update, showcasing the framework's focus on performance and developer control. This explicit, batch-friendly approach is a core architectural feature, not a hack.
+    *   The framework recognizes that the component's DOM node already exists. It issues a single, efficient `moveNode` command to the Main Thread.
+    *   **The Benefit:** The existing DOM node, with all its internal state, is simply unplugged from its old parent and plugged into the new one. A playing video continues to play, uninterrupted. This enables a level of UI fluidity and state preservation that is architecturally impossible in a single-threaded model where component identity is tied to its place in the template.
+
 ### Other Considerations:
 
 *   **Development & Deployment Environments:** Neo.mjs offers four distinct environments, providing unparalleled flexibility:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "neo.mjs",
-    "version": "10.3.2",
+    "version": "10.3.3",
     "description": "Neo.mjs: The multi-threaded UI framework for building ultra-fast, desktop-like web applications with uncompromised responsiveness, inherent security, and a transpilation-free dev mode.",
     "type": "module",
     "repository": {
@@ -83,7 +83,7 @@
         "acorn": "^8.15.0",
         "astring": "^1.9.0",
         "autoprefixer": "^10.4.21",
-        "chalk": "^5.4.1",
+        "chalk": "^5.5.0",
         "clean-webpack-plugin": "^4.0.0",
         "commander": "^14.0.0",
         "cssnano": "^7.1.0",
@@ -93,7 +93,7 @@
         "highlightjs-line-numbers.js": "^2.9.0",
         "html-minifier-terser": "^7.2.0",
         "inquirer": "^12.9.0",
-        "marked": "^16.1.1",
+        "marked": "^16.1.2",
         "monaco-editor": "0.50.0",
         "neo-jsdoc": "1.0.1",
         "neo-jsdoc-x": "1.0.5",

package/src/DefaultConfig.mjs

@@ -299,12 +299,12 @@ const DefaultConfig = {
     useVdomWorker: true,
     /**
      * buildScripts/injectPackageVersion.mjs will update this value
-     * @default '10.3.2'
+     * @default '10.3.3'
      * @memberOf! module:Neo
      * @name config.version
      * @type String
      */
-    version: '10.3.2'
+    version: '10.3.3'
 };
 
 Object.assign(DefaultConfig, {