---
tagName: 11.17.0
name: Neo.mjs v11.17.0 Release Notes
publishedAt: '2025-12-21T19:28:51Z'
isPrerelease: false
isDraft: false
---
# Neo.mjs v11.17.0 Release Notes

**Release Type:** Feature Release
**Stability:** Production-ready
**Breaking Changes:** API Standardization (Remote Methods & Addons)
**Upgrade Path:** Drop-in replacement for v11.16.0 (Refactor required for direct addon usage)

---

**Core Architecture & Multi-Window Precision**

This release is a powerhouse, resolving **107 tickets** in just over two weeks. From a sheer scope perspective—introducing a new flagship app, overhauling the core rendering engine, and redefining multi-window architecture—this could easily justify a major version bump.

However, we are sticking to **v11.17.0**. Why? Because we have even bigger plans for v12. This release creates a highly polished, performant foundation that sets the stage for the next evolutionary leap.

This update focuses on deep architectural precision. We have **consolidated the Main thread's queue system**, moving from a triple Read-Write-Update model to a streamlined Read-Write model for better batching efficiency.

Crucially, we have enhanced the **VDOM & VNode architecture** to treat scroll state (`scrollTop`, `scrollLeft`) as first-class properties. This allows us to capture and restore scroll positions seamlessly across all rendering modes—**DomApiRenderer**, **StringBasedRenderer**, and even **SSR** scenarios via new post-update queues.

These capabilities necessitated a fundamental shift in our multi-window architecture. We have deprecated the ambiguous `'main'` destination for worker messages, **enforcing explicit `windowId` routing** to ensure precision in multi-window applications. Consequently, **all remote methods** have been refactored to explicitly pass `windowId`, eliminating ambiguity when communicating through the main thread.

Furthermore, we are solidifying the **AgentOS** ecosystem by adding legitfs as a versioned filesystem with full branching support running in the browser [This allows agents to operate fully sandboxed] and significant upgrades to the Dashboard.

---

https://github.com/user-attachments/assets/aad19eb3-6345-4e30-ab3d-0514f06ce37c

---

## ✨ Highlights

### ⚡ Engineering Velocity: The "Force Multiplier" Effect
This release serves as a powerful case study for the **AI-Native** nature of Neo.mjs. The massive scope of this update—**349 files changed, +15,517 lines of code, and 107 tickets resolved**—was achieved in just **16 days** by a "2-person" team: **1 Human Architect + 1 AI Agent** (powered by the Neo.mjs Memory Core MCP Server).

This velocity validates our vision: Neo.mjs isn't just a framework for building apps; it's an operating system for AI-assisted development. By leveraging the framework's own AI infrastructure (Memory Core, Knowledge Base), a single developer can operate with the output of a full engineering team.

### 🧠 Meta: The Self-Correcting Release Note
How do you accurately document 107 tickets and 15,000 lines of code without missing the architectural nuance? You ask the AI to QA itself.

For this release, we utilized the **Neo.mjs Memory Core MCP Server** to validate these notes. The agent queried its own vector database for semantic concepts like "store optimization" and "multi-window routing"—not just keywords. The system successfully retrieved the deep contextual *reasons* behind the changes (e.g., linking "lazy instantiation" to the "Turbo Mode" store refactor), allowing the agent to cross-reference the ticket list against its own institutional memory.

This closed loop—AI generating code, storing context, and then validating the release story—transforms the AI from a stateless task-runner into a **stateful project maintainer**. It is the operational model that ensures architectural integrity is preserved across sessions, making our high velocity possible.

### 🚀 Legit: A Neo.mjs Implementation
We are excited to showcase a new demo application developed in cooperation with **Martin**, founder of the [Legit](https://www.legitcontrol.com/) open-source project.

*   **The Project:** Legit — a development platform focused on versioning, collaboration, and reliability for modern applications. At its core, Legit provides a Git-backed filesystem API that automatically tracks all changes, commits history, enables branching and rollback, and supports syncing across environments. It’s designed to make versioning and control first-class features for apps, especially those involving AI-driven workflows and collaborative editing.
*   **Architecture:**
    *   **Service Layer (`Legit.service.Legit`):** A robust singleton service that abstracts a **virtual file system** (using `memfs`) and **Git operations** (using `@legit-sdk/core`). It handles file seeding, hashing (SHA-1), and tree traversal entirely within the App Worker, ensuring heavy I/O and cryptographic operations never block the UI.
    *   **Reactive Polling:** The `ViewportController` implements a smart polling mechanism that monitors the virtual Git `HEAD`. When changes are detected, it calculates a **Tree Delta** (added, modified, deleted files) and efficiently updates the `FileStore` and `CommitStore` in real-time.
*   **Features:**
    *   **Live Preview Editor:** Integrated **Monaco Editor** (via `LivePreview`) that supports both Markdown and Neo.mjs code editing with instant visual feedback.
    *   **Commit History Grid:** A virtualized `Neo.grid.Container` visualizing the repository history, bound directly to the `CommitStore`.
    *   **Virtual File Tree:** A `TreeList` navigation component that dynamically reflects the state of the in-memory Git repository.

### ⚛️ Core Refactoring: Architectural Precision
We executed a massive, deep-dive refactoring of the core rendering pipeline and worker architecture. These changes eliminate race conditions, reduce memory overhead, and ensure deterministic state synchronization.

*   **Rendering Pipeline Unification:**
    *   **Unified Update Strategy:** Previously, manual DOM updates (`App.applyDeltas`) and VDOM updates used separate communication channels (`updateDom` vs `updateVdom`). We have merged them into a single `updateVdom` pipeline. Now, every DOM change—whether from a VDOM diff or a direct delta—benefits from the same `requestAnimationFrame` synchronization and Promise-based reply mechanism.
    *   **Read/Write Queue Model:** We overhauled the Main thread's task management (`Neo.Main`). The legacy triple-queue system (`read`, `update`, `write`) has been consolidated into a strict **Read/Write** model. This aligns with modern DOM batching best practices (preventing layout thrashing) and simplifies the execution flow.
    *   **Zero-Delta Optimization:** The `WorkerManager` (Main Thread) now intelligently inspects VDOM diffs received from the VDOM worker. "Empty" updates (zero deltas) are intercepted and dropped immediately, preventing them from entering the rendering queue.

*   **Mounting & Lifecycle:**
    *   **AutoMount as Delta:** The `autoMount` process, which previously used a special "magic placeholder" logic, has been transformed into a standard `insertNode` delta operation. This unifies the mounting logic with the rest of the delta update system.
    *   **Mount Refactor:** `mount()` is now a direct, lightweight alias for `initVnode(true)`. We removed the `hasUnmountedVdomChanges` mechanism from `VdomLifecycle`, eliminating the overhead of tracking state changes for unmounted components.

*   **State & Scroll Management:**
    *   **Bidirectional Scroll Sync:** To support first-class scroll state, we implemented a robust **bidirectional synchronization** model. This ensures that the VDOM worker respects the *live* scroll position captured by the Main thread, preventing state conflicts during rapid scrolling.
        1.  **Preservation:** When the VDOM worker calculates a patch, it now respects the *live* scroll position captured by the Main thread (`onScrollCapture`), preventing stale VDOM state from resetting the browser's scroll position.
        2.  **First-Class State:** `scrollTop` and `scrollLeft` are now first-class properties in the VNode structure, ensuring they are preserved during component moves (e.g., drag-and-drop).

*   **Architecture & Memory:**
    *   **Explicit Window IDs:** We are migrating away from the ambiguous `'main'` destination string. Cross-worker communication now prioritizes explicit `windowId` routing, essential for robust Multi-Window applications.
    *   **Async Remote Registration:** Remote method registration (`promiseRemotes`) is now fully asynchronous and deterministic, eliminating race conditions during application startup.
    *   **Symbol-Based Store Sorting:** Refactored `Neo.data.Store` to use a lightweight `initialIndexSymbol` for tracking insertion order. This removes the need to duplicate the entire dataset for state restoration, significantly reducing memory usage for large stores.
    *   **Store Turbo Mode (`autoInitRecords`):** We introduced the `autoInitRecords` config, giving developers declarative control over record instantiation. This makes it easier to enable "Turbo Mode" (lazy loading) for high-performance scenarios without needing to manually pass flags to every `add()` call.

### 🧩 SortZone & Dashboard Polish: Advanced "Drag-to-Popup"
The multi-window drag-and-drop experience has evolved from a basic functional capability into a sophisticated, native-grade interaction model. This release solves several hard technical problems to ensure that dragging complex, stateful components (like 3D Canvases or Iframes) feels seamless.

*   **Live Component Dragging (Manual DOM Strategy):**
    *   Previously, dragging a component involved moving it in the VDOM, which triggered a destroy/re-create cycle for the underlying DOM node. This would reset stateful elements (e.g., reloading an iframe or killing a canvas context).
    *   **The Fix:** We implemented a **Manual DOM Delta** strategy. The framework now surgically moves the *actual* DOM node into the Drag Proxy without disturbing the VDOM structure until the drop is finalized. This allows `OffscreenCanvas` and `Iframe` components to remain "live" and interactive even while being dragged.

*   **Intelligent Layout Transitions ("Fill the Gap"):**
    *   **Window Detachment:** When a widget is dragged outside the dashboard boundary, `SortZone` now calculates a "Target Layout" for the remaining items. It mathematically infers gaps and padding from the DOM snapshot and smoothly animates the siblings to fill the void left by the detached component.
    *   **Seamless Re-entry:** Dragging the window back over the dashboard instantly snaps the layout back to its "sortable" state, restoring the gap and showing the drag placeholder exactly where the item would land.

*   **Robust Window Management:**
    *   **Exact Sizing:** We resolved a complex race condition where browser chrome (headers/toolbars) caused popup windows to resize unpredictably. The new logic enforces "Outer Height" locking, ensuring the popup window appears with the exact same dimensions as the dragged item.
    *   **Auto-Stealing:** Components robustly "steal" ownership of themselves when moving between contexts (Dashboard -> Drag Proxy -> Window -> Dashboard), preventing state corruption.

    *   **Logical Component Bubbling:**
        *   We refactored the Event Manager (`Neo.manager.DomEvent.verifyDelegationPath`) to support **Logical Ancestry**. Even when a component is physically detached from the DOM (e.g., inside a floating Drag Proxy or a different Window), events still bubble up to its *logical* parent container using `Neo.manager.Component.getParentPath`.
        *   **Multi-Window Impact:** This ensures that Controllers listening on the Dashboard continue to receive events from items dragged into popups or other windows, maintaining a cohesive event model across the entire distributed application.
*   **Refactoring:** Renamed `container.sortable` to `container.dragResortable` to unambiguously distinguish item reordering from data sorting (e.g., in Grids).

### 🖥️ Multi-Window Architecture: Explicit Window IDs
We have deprecated the generic `'main'` destination for cross-window messaging.
*   **Explicit Addressing:** The architecture now enforces explicit Window IDs for all remote method calls and state propagation. This eliminates ambiguity in multi-window apps where "main" could refer to the opener or the current context.
*   **Canvas Migration:** `OffscreenCanvas` nodes can now be transferred between windows (SharedWorkers) without losing their state or context, enabling seamless 3D/2D visualization portability.

### 📝 LivePreview: The "Inception" Architecture
The `code.LivePreview` component—the heart of our docs and interactive examples—has been reimagined from a simple code runner into a **recursive development environment**.

*   **Polymorphic Rendering:** The component now seamlessly switches between `neomjs` (code execution) and `markdown` (rich text) modes. It uses a new pluggable executor system (`src/code/executor/Neo.mjs`) to handle the specifics of each language.
*   **The "Inception" Capability:** This is the game-changer. `Neo.component.Markdown` doesn't just parse text; it **hydrates applications**.
    *   A Markdown file can contain a ````javascript live-preview```` block.
    *   The renderer detects this and instantiates a *real* `Neo.code.LivePreview` component inside the document flow.
    *   **Recursion:** That nested LivePreview can, in turn, load another Markdown file, which contains more LivePreviews.
    *   This allows for incredibly rich, interactive documentation where examples are fully functional applications running inside the document flow.
*   **Self-Sufficient Window Management:**
    *   `LivePreview` now manages its own "pop-out" lifecycle using the new **Explicit Window ID** architecture.
    *   **Recursive Popping:** You can pop a preview out to a new window. Inside that new window, you can interact with a nested example and pop *that* out to a *third* window. The component propagates its environment (`windowUrl`, `windowId`) down the tree, ensuring every child app behaves correctly regardless of its nesting level.
*   **Neo.component.Markdown:** A new first-class component that encapsulates `marked.js` parsing, `HighlightJS` syntax highlighting, and the component hydration logic. It replaces the ad-hoc HTML injection used previously, providing a stable foundation for content-driven apps.

## ⚠️ Breaking Changes: Addon API Standardization

To support the new **Explicit Window ID** architecture, we have standardized the method signatures for all Main Thread Addons (Singletons). Previously, many methods accepted positional arguments. Now, **all remote methods must accept a single configuration object** as their first parameter.

This is a mandatory change to allow the injection of `windowId` into the method call payload, ensuring correct routing in multi-window environments.

**Impacted APIs include (but are not limited to):**

*   **`Neo.main.addon.Cookie`**
    *   `getCookie(name)` ➞ `getCookie({name})`
    *   `setCookie(value)` ➞ `setCookie({value})`
*   **`Neo.main.addon.Navigator`**
    *   `navigateTo(id, data)` ➞ `navigateTo({target: id, data, windowId})`
*   **`Neo.main.addon.Stylesheet`**
    *   `createStyleSheet(name, id, href)` ➞ `createStyleSheet({name, id, href})`
*   **`Neo.main.addon.HighlightJS`**
    *   `switchTheme(theme)` ➞ `switchTheme({theme, windowId})`

If your application uses these addons directly, you will need to update your method calls to use the new object-based signature.

---

## 📦 Full Changelog

### 🚀 New Features & Apps
*   **Legit App:** Initial release of the Git client with Service architecture (#8108, #8110, #8133)
*   **Legit Viewport:** Enhanced UX, file writing, and footer toolbar (#8109, #8060, #8061)
*   **AgentOSStrategy:** New child app for isolated strategy views (#8111)
*   **StrategyPanel:** Modular AgentOS strategy view with horizontal DnD (#8038, #8039)
*   **Neo.component.Markdown:** Dedicated, optimized Markdown renderer (#8067, #8068, #8075)
*   **Container Enhancements:** Added `silent` parameter to `add()` (#8047) and `removeFromPreviousParent` support (#8113)
*   **Theming:** Support for `additionalThemeFiles` to load external styles (#8117)
*   **AgentOS UI:** Adjusted Viewport flex ratios (#8042) and logo (#8105)

### ⚡ Performance & Core
*   **Zero-Delta Updates:** Manager optimization to skip empty VDOM diffs (#8125)
*   **Mount Refactor:** Removed VdomLifecycle overhead (#8132, #8134)
*   **Unified Delays:** Centralized DOM update strategy to fix race conditions (#8124)
*   **Read/Write Queues:** Consolidated main thread task management (#8131)
*   **Store Optimization:** Eager record initialization (#8085, #8097, #8077, #8078) and redundant check avoidance (#8095)
*   **Symbol-Based Sorting:** Refactored Store sorting for memory efficiency (#8094)
*   **VDOM State:** Bidirectional scroll sync (#8151) and `VDom.getById` implementation (#8140)
*   **LivePreview:** Optimized `doRunSource` (#8083) and container updates (#8084)
*   **Worker Manager:** Refactored `onWorkerMessage` redundancy (#8126) and optimized autoMount (#8129, #8130)

### 🖱️ UX & Interactions
*   **DragProxyContainer:** Live component dragging with auto-stealing (#8044, #8045, #8112)
*   **Dashboard Animations:** Smooth layout transitions during window drag (#8141)
*   **Drag-to-Popup:** Standardized logic in ViewportControllers (#8115) and fixed event routing (#8114)
*   **SortZone:** Renamed to `dragResortable` (#8092), fixed gap handling (#8043), and unified creation logic (#8087, #8090, #8091, #8093)
*   **Manual DOM Delta:** Implemented strategy for live component dragging (#8053)
*   **Event Delegation:** Implemented Logical Ancestry (#8051, #8056, #8057) and Physical Anchor verification (#8058)
*   **Flexbox:** Fixed shorthand parsing for numeric flex values (#8041)

### 🛠️ Infrastructure & Refactoring
*   **Window IDs:** Migration to explicit window addressing (#8149, #8153)
*   **Canvas:** Support for moving OffscreenCanvas between windows (#8118, #8119)
*   **LivePreview Architecture:** Pluggable renderers (#8063, #8069), internal multi-window logic (#8071), and nested window support (#8074)
*   **LivePreview Lifecycle:** Standardized component management (#8066) and optimized loading (#8064)
*   **Remote Methods:** Async registration with robust worker checking (#8147) and multi-window fix (#8148)
*   **Documentation:** Massive overhaul of `src/worker/mixin/RemoteMethodAccess.mjs` to explain cross-thread messaging architecture.
*   **Memory Core:** Request deduplication for HealthServices (#8104)
*   **GitHub Workflow:** Added `syncOnStartup` config (#8103)
*   **Agent Protocol:** Mandated sub-agent context injection (#8102)

### 🛡️ Quality Assurance & Hardening
Given the massive scope of the core refactorings in this release, we maintained a rigorous testing standard. This list highlights specific regressions and edge cases that were identified and resolved during the development cycle to ensure v11.17.0 retains the rock-solid stability of its predecessor.

*   **VDOM Race Condition:** Fixed initialization collision for child updates (#8123)
*   **Popup Sizing:** Fixed rounding errors, caching, and race conditions (#8121)
*   **Re-integration:** Fixed DOM updates when dragging back from popup (#8143, #8144, #8145)
*   **SortZone:** Fixed sorting corruption after multiple drags (#8054) and layout calculation regression (#8120)
*   **Drag Proxy:** Fixed cleanup failure on window drop (#8116)
*   **Monaco Editor:** Fixed double-initialization regression (#8150) and validation (#8070)
*   **Store:** Fixed `isLoaded` regression (#8100) and `initialIndexSymbol` assignment (#8099)
*   **Calendar:** Fixed Week View DnD state regression (#8076) and YearComponent state (#8098)
*   **DOM Events:** Fixed mapping for wrapper nodes (#8088) and logical bubbling (#8050)
*   **ResizeObserver:** Enabled for Canvas auto-resize (#8146)
*   **WebPack:** Fixed dynamic import errors in Legit service (#8133)
*   **ApplyDeltas:** Hardened against single delta objects (#8135)
*   **Worker Manager:** Fixed deadlock in silent VNode creation (#8055) and autoMount regression (#8128)

### 📚 Documentation & Tests
*   **Guides:** Created "Worker Architecture & Messaging" guide (#8136)
*   **Source Docs:** Enhanced SortZone (#8142) and Renderer (#8065) JSDoc
*   **Tests:** Added unit tests for SortZone (#8086), DomEvent fire (#8059), Custom VDOM Root (#8089), and Store (#8096)
*   **Testbed:** Duplicated childapps/preview for Legit testing (#8073)

All changes delivered in 1 atomic commit: https://github.com/neomjs/neo/commit/ca697682fcc9a1064a9ef53d5c51ee483d65c929
