docs: Draft v12.1.0 core sections (#9570) (#9571) (#9572) (#9573)

Author: tobiu

resources/content/release-notes/v12.1.0.md

@@ -0,0 +1,113 @@
+---
+tagName: 12.1.0
+name: Neo.mjs v12.1.0 Release Notes
+publishedAt: ''
+isPrerelease: false
+isDraft: true
+---
+# Neo.mjs v12.1.0 Release Notes
+
+**Release Type:** Grid Flexibility & Architecture Extensions  
+**Stability:** Production-Ready  
+**Upgrade Path:** Drop-in replacement for v12.0.0  
+
+> **TL;DR:** **v12.1.0** expands upon the massive foundation laid in 12.0. We introduce a complete hierarchical data layer with **TreeStore** and **TreeGrid**, bringing O(1) rendering performance to deeply nested organizational structures. We also implemented high-performance **Locked Columns**, a loop-free **ScrollSync** architecture, and modernized the entire Data Pipeline towards a modular Parser/Normalizer flow. Continuing our rapid AI-assisted velocity, we resolved **178 tickets in just 22 active development days** (27 days since v12.0, minus a 5-day external workshop), averaging ~8.1 tickets per day.
+
+---
+
+## 🌲 Velocity Case Study 1: The TreeGrid & Data Pipeline Evolution
+
+> **"Hierarchical data without the DOM overhead."**
+
+v12.1 introduces a massive expansion to the data layer: native, high-performance hierarchical data management and representation. Rendering a Flat Grid with 50,000 records was solved in v12.0; the challenge for v12.1 was achieving that same O(1) rendering performance for massively nested organizational structures.
+
+**The Challenge:** Managing deep trees of data (like file systems, organizational charts, or threaded discussions) traditionally crushes UI performance. Filtering a tree requires ancestor-aware logic. Sorting a tree requires preserving parent-child boundaries. Expanding a deeply nested node can suddenly unhide thousands of descendant records, triggering massive VDOM rebuilds.
+
+**The Solution: `Neo.data.TreeStore` and the Multi-Stage Pipeline**
+
+We engineered a completely new hierarchical data foundation that fully supports the v12.0 "Turbo Mode" (bypassing model instantiation for raw JSON speed) while introducing real-time asynchronous subtree loading.
+
+### 1. The TreeStore & TreeModel Architecture
+*   **Hierarchical Foundation:** We introduced `Neo.data.TreeModel` and `Neo.data.TreeStore`. Unlike a flat collection, the `TreeStore` manages deep structural relationships using strict O(1) lookup maps (`#allRecordsMap` and `#childrenMap`).
+*   **Ancestor-Aware Overrides:**
+    *   **Filtering:** When you filter a `TreeStore`, it employs "Ancestor-Aware Filtering". If a deeply nested child matches the search query, the engine automatically ensures that all of its parent nodes remain visible in the projection, preserving the structural path without duplicating data.
+    *   **Sorting (`doSort`):** Sorting is now perfectly hierarchical. The Store sorts siblings within their local parent boundary, recursively maintaining the integrity of the tree shape while reordering nodes based on user intent.
+*   **Structural Integrity:** Complex operations like `updateKey` have been overridden to automatically migrate descendant `parentId` references, ensuring the "split-brain" State (where lookup maps get out of sync with record data) is impossible. Full CRUD support is built-in.
+*   **Async Subtree Loading:** For massive datasets that cannot be sent to the client at once, the `TreeStore` supports asynchronous, on-demand loading of child nodes when a user expands a parent branch. We also implemented explicit Error States and dedicated events to handle network failures gracefully within the UI.
+
+### 2. The Data Pipeline Modernization
+To feed the newly minted `TreeStore`, we completely overhauled the Data Worker's ingestion pipeline.
+*   **The Parser-Normalizer Split:** Previously, data came through a single pipeline. We refactored this into a strict, modular flow: `Connection -> Parser -> Normalizer`. The new `Neo.data.normalizer.Base` (and its hierarchical sibling, `Tree`) acts as the final transformation layer, normalizing complex nested payloads from external APIs before handing pure JSON to the App Worker.
+*   **Push-Based WebSocket IPC & RPC:** We integrated persistent WebSocket connections and RPC APIs directly into the `Connection` architecture, enabling real-time streaming of hierarchical mutations from the server directly to the VDOM without polling.
+*   **Dynamic Module Loading:** `Neo.worker.Data` can now dynamically request and instantiate parser/normalizer modules at runtime, deeply minimizing the initial Data Worker bundle size.
+
+### 3. `Neo.grid.column.Tree` & The Big Data Demo
+The visual counterpart to the `TreeStore` is the new `TreeGrid` column component. 
+*   **O(1) Rendering Hierarchy:** It utilizes semantic indentation (`padding-left` derived from node depth) and interactive expand/collapse toggles natively rendered inside the pooled Grid Cells. 
+*   **Accessibility First:** ARIA sibling and level fields are dynamically calculated and applied to the VDOM nodes on every structural mutation, guaranteeing screen-reader compatibility for nested data out of the box.
+*   **The Killer Demo:** To prove the architecture, we built the **TreeGrid Big Data Demo**. It features an organic data generation algorithm that artificially constructs thousands of infinitely deep, nested records in the worker thread. Thanks to "Turbo Mode" and the fixed-DOM row pooling of the v12 Grid, sorting or expanding 10,000 nested items renders instantly at native speeds.
+
+---
+
+## 🧱 Velocity Case Study 2: Value Banding & Locked Columns
+
+> **"Data visualization at the cellular level."**
+
+### 1. Grid Value Banding
+To enhance high-density data visualization, we introduced **Grid Value Banding**. This allows developers to apply dynamic visual rules to cells or rows based on their underlying record data. Whether visualizing financial thresholds, status indicators, or heatmap intensities, value banding provides immediate, semantic visual feedback without requiring heavy custom column renderers.
+
+### 2. High-Performance Locked Columns
+A long-awaited feature for enterprise grids is the ability to pin columns to the left or right of the viewport (`locked: 'start' | 'end'`) while horizontally scrolling massive datasets.
+
+We implemented this by completely redesigning how cells are laid out.
+*   **The Mathematical Layout Engine:** Instead of relying on rigid DOM structures, columns are now positioned using a purely mathematical placement engine.
+*   **Cell Pooling Bypass:** To support locked columns without sacrificing the O(1) performance of our cell pooling engine, we implemented intelligent bypass logic. Locked cells are excluded from the horizontal recycling pool but remain fully integrated into the vertical Virtual DOM pipeline.
+*   **Optical Pinning via Addon:** We utilize a Main Thread Addon to synchronously inject CSS variables (`--grid-locked-start-offset`) that counteract the scrolling `transform: translateX()`, creating the pinning effect.
+*   **Drag & Drop Alignment:** Column Reordering (`SortZone`) seamlessly supports dragging unlocked columns across the viewport, as well as dragging locked columns to reorder within their respective pinned zones.
+
+> [!WARNING]
+> ### 🚧 Known Limitation: The Compositor Challenge
+> While our initial approach to `locked` columns is fully functional, our extreme horizontal scrolling tests revealed a limitation in browser architecture: **Main Thread vs. Compositor Thread synchronization**.
+>
+> When a user scrolls horizontally, the browser's GPU compositor instantly shifts the container. However, JavaScript `scroll` events fire *after* this native paint. Therefore, our Main Thread counter-translation arrives exactly one frame late, causing an inescapable "elastic lag" or visual jitter during fast horizontal scrolling.
+> 
+> **The Future (Post-v12.1):** To achieve truly zero-jitter locked columns, we are currently planning a massive fundamental pivot to a **Grid Multi-Body Architecture** (Epic #9486). This will decouple horizontal and vertical scrolling physics, split the Virtual DOM into physically distinct container bodies, and guarantee flawless native scrolling sync.
+
+---
+
+## ⚖️ Velocity Case Study 3: Overhauling ScrollSync & Performance Engineering
+
+> **"Physics-based UIs require loop-free architecture."**
+
+### 1. The ScrollSync Upgrade (Mobile & Desktop 2-Way Binding)
+Synchronizing scroll positions between disparate elements—like a main grid body and a custom scrollbar component—has historically been prone to endless feedback loops. If Component A scrolls Component B, B fires a scroll event back to A, resulting in infinite loops or stuttering.
+
+v12.1 introduces a complete overhaul to `Neo.plugin.ScrollSync`.
+*   **Loop-Free Architecture:** We implemented a bulletproof locking mechanism. When a programmatic scroll is initiated (e.g., via the new API), `ScrollSync` establishes a lock, applies the scroll, and ignores the echo events using a highly tuned `requestAnimationFrame` release timer.
+*   **Mobile vs. Desktop Unity:** We unified the two-way binding physics. `GridDragScroll` (the kinetic drag-to-scroll addon) now flawlessly routes through the `ScrollSync` API. This means dragging the grid on a touch screen perfectly accelerates the custom scrollbar thumb, and vice versa, without dropping a single frame or triggering a feedback loop.
+
+### 2. Optical Pinning via Hybrid rAF Engine
+To handle row-level pinning (like summary rows or group headers) during high-velocity scrolling, we engineered `GridRowScrollPinning`.
+*   **The Hybrid Engine:** Relying solely on App Worker logic for sticky headers causes latency. We moved the pinning engine to a Main Thread Addon using a hybrid `requestAnimationFrame` structure. It injects hardware-accelerated CSS Variables to optically pin rows, matching the zero-latency responsiveness of native OS views.
+
+### 3. Performance Engineering (The O(1) Mandate)
+We scoured the codebase with extreme profiling tools to eliminate any operation that scaled exponentially with DOM size.
+*   **Eradicating O(N²) Traversals:** We completely rewrote the core `syncVnodeTree` tracking. Previously, reconciling nodes required traversing the entire App Worker VDOM array. It now utilizes O(1) direct dictionary lookups.
+*   **Path Traversals:** The `onScrollCapture` and `getTargetData` event paths were optimized heavily. By providing O(1) fast paths for specific event targets, we decoupled the engine from Main Thread DOM layout thrashing during continuous kinetic scrolling.
+*   **Proxy Getter Hoisting:** To alleviate V8 Garbage Collection pressure during high-frequency VDOM generation, we hoisted getter proxies within the Grid Row internals, preventing duplicate function instantiations across the cell pool.
+
+---
+
+## 🎓 The Core Engine Learning Guides & Workshop
+
+We believe that the best framework is one you deeply understand, not just one you use blindly. To that end, v12.1 officially launches the **Core Engine Learning Guides & Workshop**.
+
+*   **Deep Dives:** New comprehensive guides have been added to the Neo Portal, covering everything from the underlying worker architecture to the advanced routing and state management patterns.
+*   **The Workshop:** A structured set of exercises designed to take developers from basic Neo.mjs concepts to building complex, highly performant, multi-threaded applications. This is the fastest track to mastering the "Fat Client" paradigm.
+*   **Documentation Enhancements:** Alongside the major features, we resolved numerous documentation gaps, improved inline styling within our Markdown components, and enhanced the knowledge base structure for AI agents and human developers alike.
+
+---
+
+## 📦 Full Changelog
+
+*(Note: The full list of 178 resolved tickets will be generated and appended here prior to final publication).*