LearnNewsExamplesServices
Frontmatter
tagName11.19.0
nameNeo.mjs v11.19.0 Release Notes
publishedAt1/9/2026, 1:06:42 AM
isPrerelease
isDraft

Neo.mjs v11.19.0 Release Notes

Release Type: Strategic Pivot & Platform Maturity
Stability: Production-ready
Upgrade Path: Drop-in replacement for v11.18.0

TL;DR: v11.19.0 corrects the project's identity. For 6 years, Neo.mjs has been an "Application Engine" disguised as a framework. We finally fixed that branding failure. In parallel, we executed a massive Infrastructure Upgrade: we intentionally broke the AI Knowledge Base to upgrade it from JSDoc indexing to AST Source Parsing, solving the "Re-embedding Hell" (where index-based IDs caused entire collections to shift on every update). 110 tickets resolved in 3 days.

The Identity Correction

v11.18 gave us the Neural Link (Vision). v11.19 gives us the Truth (Self).

We realized that calling Neo.mjs a "Framework" (like React or Vue) was a fundamental branding failure. Frameworks are libraries you import to organize code. Neo.mjs is, and always has been, a multi-threaded runtime that runs your code. It has a Scene Graph, Object Permanence, and Subsystems. It is closer to Unreal Engine than it is to Angular.

This release executes the strategic pivot to align our identity with our reality:

  1. Identity: Comprehensive rebranding of 250+ documentation files to correct the "Application Engine" narrative.
  2. Capability: A new Content Engine that proves the "Engine" thesis by powering our own Portal 2.0.
  3. Intelligence: A Knowledge Base V2 that indexes source code and inheritance hierarchies, allowing the AI to understand the engine's DNA.

⚙️ The Engine Room: Heavy Engineering

While the rebranding changes the narrative, the engineering changes in this release fundamentally upgrade the runtime capabilities.

💤 Generic Lazy-Loading Protocol

We didn't just add a "Mermaid wrapper". We implemented a Generic Lazy-Loading Architecture for all Main Thread Addons.

  • The Nuance: Standard import() handles code splitting, but orchestrating it across the Worker barrier requires a dedicated protocol.
  • The Solution: We introduced a centralized Addon Loader (Neo.currentWorker.getAddon).
    • Worker-Side Control: Components (like Neo.component.wrapper.Mermaid) simply await getAddon('Mermaid') in their initAsync phase.
    • Transparent Orchestration: The App Worker checks if the addon proxy exists. If not, it instructs the Main Thread to dynamically import and instantiate the service, then caches the proxy for future use.
    • Deep Array Merging: We implemented merge: 'deepArrays' in the core config system to allow Addons to inherit and extend the remote method definitions seamlessly.
    • Extensible Singleton Pattern: Addons are singletons within each Main thread context (one instance per window), but architected as extensible classes. This allows developers to extend them (e.g., custom Mermaid themes, additional GoogleMaps features) in their own workspaces while maintaining the singleton lifecycle.

🕸️ Multi-Window SharedWorker Hardening

We fixed a critical race condition in the SharedWorker architecture that affects multi-window applications (and Playwright tests).

  • The Issue: Secondary windows connecting to an existing App Worker (SharedWorker) were missing remote method definitions. The worker's initialization logic (where remotes are registered) runs only once, so subsequent window connections received nothing.
  • The Fix: We introduced a remotesToRegister state queue in src/worker/Base.mjs. The onConnected handler (triggered for every new window connection) now deterministically replays this registration queue to the new MessagePort, ensuring every window receives the full API surface.

🚀 Portal 2.0 Performance: Dynamic Imports

The new News Section isn't just a UI change; it's a performance blueprint.

  • The Pattern: We refactored NewsTabContainer to use Dynamic Imports (Arrow Function Syntax) for its children: module: () => import(...).
  • The Impact: This prevents the heavy "Blog" and "Releases" chunks from loading during the initial application boot. They are fetched only when the user clicks the tab, keeping the initial bundle size minimal.
Screenshot 2026-01-08 at 20 56 03

🕷️ Hierarchical SEO Traversal

The new Content Engine introduces Smart Traversal Logic for metadata.

  • The Logic: If a specific deep route (e.g., /news/releases/v11.19.0) lacks specific SEO tags, the engine now recursively traverses the route path upwards (/news/releases -> /news) until it finds a valid metadata definition.
  • The Result: We can now launch hundreds of nested views without manually defining SEO tags for every leaf node, inheriting "Section Level" metadata automatically.

🌳 Build-Time Tree Indexing

For the new Releases section, we moved data processing from runtime to build-time.

  • The Indexer: A new build script (createReleaseIndex.mjs) scans the markdown archive, parses YAML frontmatter, and constructs a highly optimized Hierarchical Tree (Major Version -> Release).
  • Optimization: The script strips redundant fields (version, name) and flattens the tree into a list structure optimized for the TreeList component, reducing the payload size significantly while enabling instant navigation.

🧠 Knowledge Base V2: The Strategic Upgrade

We intentionally broke the Knowledge Base to make it smarter. This wasn't a "bug fix" - it was a fundamental architectural shift.

  • From JSDoc to AST: Previously, we indexed JSDoc JSON output, which gave the AI a shallow view of the API. Now, we use a custom AST Source Parser to analyze raw .mjs files. The AI sees the implementation (logic patterns, config blocks, full method bodies), not just the signatures.
  • The Challenge: This upgrade broke everything. The old scoring algorithm assumed JSDoc structure. The old ID generation was index-based, meaning adding one file shifted every ID, causing total corruption during updates.
  • The Fix: We spent 3 days hardening the pipeline:
    • Hash-Based IDs: We switched to content-addressable hashing. IDs are now stable across builds.
    • Delta Updates: Because IDs are stable, we can now perform precise delta updates. The system only re-embeds files that have physically changed, reducing update time from 10 minutes to 3 seconds.
    • Static Class Hierarchy: We implemented a build-time analyzer that generates a deterministic map of the entire class tree. Agents can now answer questions like "Find all components that extend Neo.component.Base" with 100% accuracy.
  • RAG (Ask the Engine): The new SearchService leverages this V2 architecture to enable Retrieval-Augmented Generation, synthesizing answers from the deep implementation details we now expose.

🛠️ Engineering Case Study: The 10k Vector Migration

To enable "Context Engineering", we had to move from indexing what code does (JSDoc) to how it does it (Source AST). This wasn't just a parser swap; it was a scale challenge.

  • The Scale: The index jumped from ~7k fragmented properties to 10,231 semantic source chunks.
  • The Performance: collection.get() failed at this scale. We implemented batched fetching (2k limit) and hash-based ID deduplication to handle the load.
  • The Parser: We built a custom SourceParser using acorn to decompose ES Modules into 4 semantic layers:
    1. Module Context: Imports & top-level scope.
    2. Class Properties: Static fields & non-reactive state.
    3. Config Block: The declarative heart of Neo.mjs components.
    4. Methods: Full implementation logic.
// ai/mcp/server/knowledge-base/parser/SourceParser.mjs
parse(content, filePath, defaultType='src', hierarchy={}) {
    // ...
    // 1. Traverse AST to categorize nodes
    ast.body.forEach(node => {
        if (node.type === 'ImportDeclaration') {
            contextNodes.push(node);
        } else if (node.type === 'ClassDeclaration') {
            // ... capture class definition ...
            classDecl.body.body.forEach(member => {
                if (member.key.name === 'config' && member.static) {
                    configNode = member; // Isolate the Config System
                } else if (member.type === 'MethodDefinition') {
                    methodNodes.push(member); // Isolate Logic
                }
            });
        }
    });
    // ...
}

🔄 Process Evolution: Programming the Programmer

This release cycle demonstrated a meta-evolution in how we work. The AI didn't just build the code; it updated its own Operating System.

  • Self-Legislating Agents: In the middle of the release, the AI realized it was missing a rigorous protocol for closing tickets. It autonomously updated AGENTS.md to enforce a "Push -> Assign -> Comment -> Close" protocol, effectively programming its own future behavior.
  • Velocity Deconstructed: The "110 tickets in 3 days" metric isn't random. It breaks down into:
    • ~30 tickets for the Knowledge Base V2 upgrade.
    • ~20 tickets for cascading infrastructure fixes (query scoring, IDs, deduplication).
    • ~40 tickets for the Portal 2.0 Content Engine.
    • ~20 tickets for Branding/Docs. This velocity was powered by Context Continuity (reading past session summaries) and the GitHub Workflow Server (browsing ticket history). We also saw an emergent behavior: AI agents using the Neural Link for static code analysis (e.g., extracting single methods like insertThemeFiles via get_method_source to save tokens), a use case we never explicitly designed for.
  • The "Obsolete" DevTools: The Neural Link has proven so effective for runtime inspection that we officially removed the Chrome DevTools MCP Server from our default configuration. For our Human-Agent team, the native engine introspection (scene graph awareness) rendered the generic browser tools obsolete, freeing up 26 tool slots for higher-level reasoning capabilities.

⏱️ Velocity Case Study: The 12-Minute Refactor

To prove this isn't theoretical, let's look at Ticket #8413 (commit 2a4421e).

  • The Mission: Structural refactoring of the Portal. Moving the entire Blog and Releases view hierarchies under a new News namespace, including updating all classNames, imports, and SCSS file paths.
  • The Stats:
    • 09:40 - User Input & Ticket Creation
    • 09:41 - Plan Approval
    • 09:52 - Ticket Closed (Files moved, SCSS updated, Build Verified)
    • Impact: 16 changed files, +154 -37 lines of touched code
    • Duration: 12 Minutes
  • The Reality: A human developer would spend 30+ minutes manually moving files, grepping for broken imports, and fixing SCSS paths—likely missing one. The Agent executed the file moves and updated the AST references in near real-time.
// Before: apps/portal/view/blog/Container.mjs
class Container extends BaseContainer {
    static config = {
        className: 'Portal.view.blog.Container', // <--- Old Namespace
        ...
    }
}

// After: apps/portal/view/news/blog/Container.mjs
class Container extends BaseContainer {
    static config = {
        className: 'Portal.view.news.blog.Container', // <--- Automatically Refactored
        ...
    }
}

✨ Highlights

📝 The Content Engine: A Production-Ready CMS

We didn't just redesign the Portal; we engineered a reusable Content Management Architecture.

  • Shared Content Viewer: We extracted the "Tree Nav + Content + Sidebar" layout into a generic Portal.view.shared.content.Container. This now powers both the Learning section and the new Releases section, proving the reusability of the pattern.
  • News Center Architecture: We refactored the Blog into a unified News Section (Portal.view.news.TabContainer). While the Blog retains its specialized list-based architecture, it now lives alongside the tree-based Releases view under a cohesive tabbed interface with Dynamic Imports for optimal performance.
  • Markdown Engine: The Neo.component.Markdown component received a massive overhaul. It now natively parses YAML frontmatter, supports implicit readonly code blocks, automatically links GitHub issues (e.g., #8392), and supports Mermaid Diagrams via the new Lazy-Loading protocol.

📦 Full Changelog

🚀 Identity & Portal 2.0

  • 'Docs: Rebrand Neo.mjs as an Application Engine in README' (#8350)
  • 'Docs: Replace Framework Comparison with Engine Architecture in README' (#8351)
  • 'Docs: Refine README Vocabulary to 'Engine Subsystems' & 'Scene Graph'' (#8352)
  • 'Finalize README.md Rebrand: Polish and Engine Terminology' (#8353)
  • Finalize README Application Engine Rebrand and Terminology (#8354)
  • Refine README 'F1 vs Toyota' Phrasing (#8355)
  • Add Maturity Statement to README Qualification Section (#8356)
  • Update package.json branding and keywords (#8357)
  • Update Portal index.html to reflect Application Engine branding (#8358)
  • Refine Portal FAQ Schema metaphors for SEO (#8359)
  • Update Portal Landing Page Content (MainNeo) for Application Engine Branding (#8360)
  • Refine Portal Landing Page cycleTexts for Precision and Web Standards (#8361)
  • Redesign Portal Hero (MainNeo) Layout & Styling (#8367)
  • Replace "AfterMath" with "AI-Native Toolchain" Section (#8368)
  • 'Refactor Features & ContentBox: Modernize Design and Content' (#8369)
  • Unify Portal Home with Global "Engine Environment" Background (#8370)
  • Modernize learn/benefits/Introduction.md to reflect "Application Engine" identity (#8371)
  • Refactor Portal Blog to News Section with Tabbed Interface (#8386)
  • Refactor Portal TabContainers to use Shared Base Class and Styling (#8387)
  • Refactor Portal Learning Views to Shared Content Viewer (#8388)
  • Implement Releases Section using Shared Content View (#8389)
  • Implement Tree-Structured Release Index and Portal Integration (#8390)
  • Update generateSeoFiles.mjs to handle tree-structured release data (#8391)
  • Refactor Portal View Structure: Move Blog and Release under News (#8413)
  • Update Portal Services Page to match Home Page Styling (#8429)
  • Refactor Portal About Page to use Shared Styling (#8430)
  • Apply Shared Background to Portal News and Remove Default Backgrounds (#8431)
  • 'Update Portal shared background color to #fcfcfc' (#8432)
  • Fix route regression in Home Features and enhance AiToolchain (#8433)
  • Use dynamic imports in Portal News TabContainer (#8434)
  • Fix Release News Default Route Index (#8435)
  • Fix missing titles for non-leaf Release tree nodes (#8436)
  • Remove redundant version field from Release Index and Model (#8437)
  • Remove redundant name field from Release Index and Model (#8438)
  • Update SEO Service for Nested Routes and News Section (#8439)
  • Fix Mobile Layout Overlay in Portal News TabContainer (#8440)
  • Rebrand Neo.mjs to "Application Engine" in Documentation (#8445)
  • Comprehensive Rebranding to "Application Engine" (Phase 2) (#8446)
  • Comprehensive Rebranding to "Application Engine" (Phase 3) (#8447)
  • Refactor Portal 'Blog' to 'News' with Left-Tab Architecture for Releases & Posts (#8362)
  • Polish Terminology in NeoVsAngular.md (#8448)
  • 'Update CodebaseOverview.md with Jan 8, 2026 Metrics' (#8449)

🧠 AI & Knowledge Base

  • Robust Knowledge Base Delta Updates (Hash-based IDs + Deterministic Sorting) (#8341)
  • Switch Knowledge Base to Source Code Indexing (SourceParser) (#8342)
  • 'Expand Source Indexing Coverage (Apps, Examples, AI)' (#8343)
  • Fix Duplicate ID Error in VectorService (#8344)
  • Fix Shebang Parsing in SourceParser (#8345)
  • Refactor DatabaseService to Config-based Opt-Out Auto-Sync (#8346)
  • Refactor Memory & GitHub Services to Config-based Opt-Out Auto-Sync (#8347)
  • Move sync_knowledge_base.mjs to buildScripts/syncKnowledgeBase.mjs (#8349)
  • Force full knowledge base sync on startup (#8414)
  • Prototype Search & Summarize (RAG) Tool (#8415)
  • Update SDK and add RAG verification script (#8416)
  • Refine RAG System Prompt for Identity & Accuracy (#8417)
  • Refactor and Document SearchService (#8418)
  • Update /knowledge/ask tool description in openapi.yaml (#8419)
  • Fix Knowledge Base Indexing and Scoring for Source Code (#8420)
  • Implement Static Class Hierarchy in Knowledge Base (#8421)
  • Update Knowledge Base Documentation (#8422)
  • Fix SourceParser to prioritize fully qualified className from config (#8423)
  • Fix SourceParser to resolve fully qualified superclass names (#8424)
  • Switch Class Hierarchy to JSON (#8425)
  • Clean up SourceParser and use Class Hierarchy (#8426)
  • Improve SourceParser Documentation and Context Extraction logic (#8427)
  • Enforce root parameter for getClassHierarchy (#8428)
  • Fix getClassHierarchy schema mismatch and JSDoc (#8442)
  • Fix OpenAPI Validator to support additionalProperties (#8443)

📝 Content Engine (Markdown)

  • Create Neural Link Documentation (#8372)
  • Update Introduction.md to highlight Neural Link capabilities (#8373)
  • Update MCP Introduction Guide to Include Neural Link (#8374)
  • Update Code Execution Guide for Application Engine Branding and Neural Link (#8375)
  • Add Mermaid Diagram Support to Markdown Component (#8376)
  • Create Mermaid Component Wrapper (#8377)
  • Add intent-driven comments to Mermaid Addon (#8378)
  • Implement Lazy Loading Support for Main Thread Addons (#8379)
  • Fix json5 rendering in NeuralLink guide (#8380)
  • Fix json code block highlighting in MainThreadAddons guide (#8381)
  • Fix Markdown code block styling to apply universally (#8382)
  • Add styling for tables in Markdown component (#8383)
  • Add rounded corners to Markdown tables (#8384)
  • Add support for 'text' language in Markdown code blocks (#8385)
  • Implement Frontmatter Parsing and Rendering in Markdown Component (#8393)
  • Enhance Markdown Frontmatter Rendering (#8394)
  • Enhance Markdown parser to enforce newlines after headlines (#8395)
  • Enhance Markdown parser to support implicit readonly code blocks (#8396)
  • Add support for automatic GitHub issue linking in Markdown component (#8397)
  • Fix Deep Linking Routing in News TabContainer (#8399)
  • Fix Markdown code block trimming destroying indentation (#8400)
  • Refine Markdown inline code styling in light theme (#8401)
  • Enhance Release tree titles with dates (#8402)
  • Add styling for Markdown hr tags (#8404)
  • Reduce sidebar width for Release view (#8405)
  • Fix Release navigation button titles showing HTML and Date (#8411)

🛠️ Infrastructure & Core

  • Update npm-publish workflow to support Node.js 22.x (#8340)
  • Fix logic mismatch in debug_session_state.mjs (#8348)
  • Create Build Script for Release Notes JSON Index (#8363)
  • Update generateSeoFiles.mjs for Portal News & Application Engine Branding (#8364)
  • Integrate Release Index Generation into Release Workflow and Fix SEO Script (#8365)
  • Fix deprecated destination warning for registerRemote messages (#8366)
  • Mandate Ticket IDs in Commit Messages via AGENTS.md (#8392)
  • Pass record instance to Model field convert method (#8403)
  • 'Optimize MCP Tool Allocation: Remove Chrome DevTools from Default Config' (#8406)
  • 'Update AGENTS.md: Enforce 'Git Push' before closing tickets' (#8407)
  • Optimize 'sync_all' tool description to reduce redundant calls (#8408)
  • 'Update AGENTS.md: Enforce 'Ownership-on-Completion' (Assign before Close)' (#8409)
  • Refactor AGENTS.md to explicitly define Ticket Closure Protocol (#8412)
  • Safe check for DragZone handlers in DomEvent manager (#8441)
  • Automate .npmignore synchronization with .gitignore in prepareRelease script (#8444)

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