neo.mjs 10.0.0-beta.5 → 10.0.0

package/learn/benefits/Speed.md

@@ -1,3 +1,5 @@
+# Extreme Speed
+
 The Neo.mjs architecture leverages web workers to run application logic, data processing,
 and even parts of the rendering pipeline in parallel, on separate CPU cores.
 This offloads heavy computations from the main thread, ensuring the UI remains responsive.

package/learn/blog/v10-deep-dive-functional-components.md

@@ -0,0 +1,293 @@
+# Beyond Hooks: A New Breed of Functional Components for a Multi-Threaded World
+
+If you're a seasoned React developer, you've mastered the art of hooks. You know how to build complex, stateful UIs with
+`useState`, `useEffect`, and `useMemo`. You also know the trade-offs—the intricate dependency arrays, the constant battle
+against unnecessary re-renders, and the "memoization tax" you pay to keep your application performant.
+
+We've been taught that these trade-offs are fundamental to the functional component model. But what if they aren't?
+What if they are merely symptoms of a single-threaded architecture?
+
+This article will show you a new breed of functional component, born from a multi-threaded world, that eliminates these
+compromises by design. We didn't build them to copy other frameworks; we built them because our architecture unlocked a
+better way to write UIs.
+
+*(Part 3 of 5 in the v10 blog series. Details at the bottom.)*
+
+### A First Look: The Anatomy of a Neo.mjs Functional Component
+
+Before we dive into the "why," let's look at the "what." Here is a simple, complete, and reactive functional component
+in Neo.mjs. Keep this structure in mind as we explore how it solves the problems you've come to accept as normal.
+
+```javascript
+import {defineComponent, useConfig, useEvent} from 'neo.mjs';
+
+export default defineComponent({
+    // The component's public API (like props)
+    config: {
+        className: 'My.Counter',
+        labelText_: 'Counter:'
+    },
+
+    // The function that creates the VDOM
+    createVdom(config) {
+        // Internal, private state (like useState)
+        const [count, setCount] = useConfig(0);
+
+        // An event listener that updates the private state
+        useEvent('click', () => setCount(prev => prev + 1));
+
+        return {
+            tag: 'button',
+            cn: [
+                {tag: 'span', text: config.labelText},
+                {tag: 'span', cls: ['count-badge'], text: count}
+            ]
+        }
+    }
+});
+```
+
+Notice what's missing: there are no dependency arrays, no `memo` wrappers, and no `useCallback` hooks. Now, let's explore
+the architecture that makes this clean, simple code possible.
+
+---
+
+### The Architectural Divide: Why Your Component's Environment Matters
+
+Before we deconstruct the problems, we have to address the fundamental difference that changes everything. In a
+traditional framework like React, your component function, its state, its reconciliation (diffing), and its DOM
+manipulation all happen on the **same main thread** that is responsible for user interactions.
+
+In Neo.mjs, the architecture is fundamentally different:
+
+1.  **Your Application Logic (including your component's `createVdom` function) runs in a dedicated App Worker.**
+2.  **The VDOM diffing happens in a separate VDom Worker.**
+3.  **The Main Thread is left with one primary job: applying the calculated DOM patches.**
+
+This isn't just a minor difference; it's a paradigm shift. Your component code is decoupled from the rendering engine,
+which allows for a level of performance and predictability that is architecturally impossible on the main thread.
+With this in mind, let's see how this new architecture solves old problems.
+
+---
+
+### Deconstructing the "React Tax": How a New Architecture Solves Old Problems
+
+Let's tackle the compromises you've learned to live with, one by one, and show how a multi-threaded architecture solves
+them at their root.
+
+#### 1. The Problem: Cascading Re-Renders & The `memo` Tax
+
+**The React Way:** You know the drill. A state change in a parent component triggers a re-render. By default, React then
+re-renders **all of its children**, whether their props have changed or not. To prevent this performance drain,
+you are forced to pay the `memo` tax: wrapping components in `React.memo()`, manually memoizing functions with
+`useCallback()`, and objects with `useMemo()`. This manual optimization becomes a core, and often frustrating,
+part of the development process.
+
+```javascript
+// A typical "optimized" React component
+const MyComponent = React.memo(({ onButtonClick, user }) => {
+  console.log('Rendering MyComponent');
+  return <button onClick={onButtonClick}>{user.name}</button>;
+});
+
+const App = () => {
+  const [count, setCount] = useState(0);
+
+  // We must wrap this in useCallback to prevent MyComponent from re-rendering
+  // every time the App component's state changes.
+  const handleClick = useCallback(() => {
+    console.log('Button clicked!');
+  }, []);
+
+  // We must wrap this in useMemo to ensure the object reference is stable.
+  const user = useMemo(() => ({ name: 'John Doe' }), []);
+
+  return (
+    <div>
+      <button onClick={() => setCount(c => c + 1)}>App Clicks: {count}</button>
+      <MyComponent onButtonClick={handleClick} user={user} />
+    </div>
+  );
+};
+```
+
+**The Neo.mjs Solution: Surgical Effects, Not Brute-Force Renders**
+
+Our `createVdom` method is a surgical `Effect`. It automatically and precisely tracks every piece of reactive state it reads.
+When a piece of state 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**. 
+
+This means `memo`, `useCallback`, and `useMemo` are not needed. The architecture is efficient by default, eliminating an
+entire class of performance optimizations and bugs.
+
+#### 2. The Problem: The Boilerplate of Immutability
+
+**The React Way:** To change a nested object in React state, you have to meticulously reconstruct the object path with
+spread syntax (`...`), creating new references for every level. This is required to signal to React's diffing algorithm
+that something has changed.
+
+```javascript
+// The familiar immutable update dance
+setState(prevState => ({
+  ...prevState,
+  deeply: {
+    ...prevState.deeply,
+    nested: {
+      ...prevState.deeply.nested,
+      property: 'new value'
+    }
+  }
+}));
+```
+
+**The Neo.mjs Solution: Mutability for You, Immutability for the Machine**
+
+We believe the developer should not carry this cognitive load. In Neo.mjs, you can just mutate the state directly.
+It's simple and intuitive.
+
+```javascript
+// Just change the value. That's it.
+this.myObject.deeply.nested.property = 'new value';
+```
+
+How does it work? When an update is triggered, the framework handles creating an immutable JSON snapshot of the VDOM for
+the diffing process in the VDom Worker. We provide the best of both worlds: simple, direct mutation for the developer
+and a safe, immutable structure for the high-performance diffing algorithm.
+
+#### 3. The Problem: The "SSR and Hydration is the ONLY way" Mindset
+
+**The React/Next.js Way:** The industry has invested heavily in Server-Side Rendering and hydration to improve perceived
+performance and SEO. For content-heavy sites, this is a valid strategy. But for complex, stateful Single-Page Applications,
+it introduces immense complexity: the "hydration crisis," the difficulty of managing server vs. client components, and
+the fact that after all that work, your application is *still* running on the client's main thread.
+
+**The Neo.mjs Solution: Blueprints, Not Dehydrated HTML**
+
+We offer a more robust and scalable model for SPAs. Instead of sending pre-rendered HTML that needs to be brought back
+to life, we can send a compact **JSON blueprint**. The client-side engine, running in a worker, constructs the live,
+interactive UI from this blueprint. This is a more efficient, more predictable, and architecturally cleaner way to build
+complex applications that are not primarily focused on static content.
+
+---
+
+### The "WOW" Effect: Building a Real Application
+
+The simple counter example is a great start, but the true power of functional components is revealed when you build a
+complete, interactive application. Let's build a slightly more advanced "Task List" application to demonstrate how all
+the pieces come together.
+
+This example will showcase:
+- **Component Composition:** Using a class-based `List` component within our functional view.
+- **State Management:** Tracking the currently selected task.
+- **Conditional Rendering:** Displaying task details only when a task is selected.
+- **Event Handling:** Updating state based on events from a child component.
+
+Here is the complete, interactive example.
+
+```javascript live-preview
+import {defineComponent, useConfig} from 'neo.mjs';
+import List from 'neo.mjs/src/list/Base.mjs';
+import Store from 'neo.mjs/src/data/Store.mjs';
+
+// 1. Define a simple data Store for our list
+const TaskStore = Neo.create(Store, {
+    data: [
+        {id: 1, title: 'Build a better component model', description: 'Re-imagine what a component can be when freed from the main thread.'},
+        {id: 2, title: 'Create a new reactivity system', description: 'Design a two-tier system that is both powerful and intuitive.'},
+        {id: 3, title: 'Revolutionize the VDOM',         description: 'Build an asymmetric, off-thread VDOM engine for maximum performance.'}
+    ]
+});
+
+// 2. Define our main application view
+export default defineComponent({
+    config: {
+        className: 'My.TaskListApp',
+        layout: {ntype: 'hbox', align: 'stretch'}
+    },
+    createVdom() {
+        // 3. Manage the selected task with useConfig
+        const [selectedTask, setSelectedTask] = useConfig(null);
+
+        const onSelectionChange = ({value}) => {
+            // 4. Update our state when the list selection changes
+            setSelectedTask(TaskStore.get(value[0]));
+        };
+
+        const paneStyle = {
+            border : '1px solid #c0c0c0',
+            margin : '10px',
+            padding: '10px'
+        };
+
+        return {
+            cn: [{
+                // 5. The List Component
+                module   : List,
+                store    : TaskStore,
+                width    : 250,
+                style    : paneStyle,
+                listeners: {
+                    selectionChange: onSelectionChange
+                }
+            }, {
+                // 6. The Details Pane (with conditional rendering)
+                flex: 1,
+                style: paneStyle,
+                cn: selectedTask ? [
+                    {tag: 'h2', text: selectedTask.title},
+                    {tag: 'p',  text: selectedTask.description}
+                ] : [{
+                    tag  : 'div',
+                    style: {color: '#888'},
+                    text : 'Please select a task to see the details.'
+                }]
+            }]
+        }
+    }
+});
+```
+
+This single `defineComponent` call creates a fully-featured application. Notice how the `createVdom` function is a pure,
+declarative representation of the UI. When the `selectedTask` state changes, the framework surgically re-renders only
+the details pane. This is the power of the new component model in action: complex, stateful, and performant applications
+with beautifully simple code.
+
+---
+
+### The AI Connection: The Inevitable Next Step
+
+This blueprint-first, surgically reactive, and mutable-by-default model isn't just better for you; it's the architecture
+an AI would choose. An AI can easily generate and manipulate a structured JSON blueprint, but it struggles to generate
+flawless, complex JSX. By building on these principles, you are not just using a new framework; you are future-proofing
+your skills for the AI era.
+
+---
+
+### Conclusion: A Different Philosophy, A Better Component
+
+Neo.mjs functional components are not a "React clone." They are a re-imagining of what a functional component can be
+when freed from the architectural constraints of the main thread. They offer a development experience that is not only
+more performant by default but also simpler, more intuitive, and ready for the AI-driven future of the web.
+
+This is what it feels like to stop paying the performance tax and start building again.
+
+The clean, hook-based API for functional components is possible because it stands on the shoulders of a robust, modular,
+and deeply integrated class system. We've engineered the framework's core to handle the complex machinery of reactivity
+and lifecycle management automatically. To learn more about the powerful engine that makes this all possible, see our
+deep dive on the **Two-Tier Reactivity System**.
+
+Next, we will look at how this architecture revolutionizes the very way we render UIs with the Asymmetric VDOM
+and JSON Blueprints.
+
+---
+
+## The Neo.mjs v10 Blog Post Series
+
+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
+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)