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 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