What is the 'Neural Link'?

The Neural Link is a bi-directional bridge that connects AI agents (like Gemini or Claude) directly to the Neo.mjs runtime. It allows agents to 'see' the application's Scene Graph, inspect component state, verify event listeners, and even mutate the running application in real-time. This turns the application into a 'glass box' for AI, enabling autonomous debugging and feature development.

Why is Neo.mjs called an 'Application Engine' instead of a framework?

Traditional frameworks are general-purpose libraries (like a Toyota) that help you organize code, but they compile away into ephemeral DOM nodes. Neo.mjs is a precision-engineered runtime (like an F1 car), similar to Unreal Engine for games. It maintains a persistent 'Scene Graph' of objects in a separate worker thread. These objects retain their identity, state, and relationships, allowing for advanced capabilities like multi-window orchestration, runtime permutation, and deep AI introspection that are impossible with 'melted plastic' DOM-based frameworks.

What is 'Context Engineering'?

Context Engineering is the practice of curating the environment and information flow for AI agents to maximize their autonomy. In Neo.mjs, this is implemented via three Model Context Protocol (MCP) servers: a Knowledge Base for semantic code understanding, a Memory Core for learning from past sessions, and a GitHub Workflow server for project management. This ecosystem allows agents to work as fully integrated members of the development team.

What is 'Object Permanence' in the context of Neo.mjs?

In Neo.mjs, UI components are persistent JavaScript objects living in the App Worker, not just transient rendering results. This 'Object Permanence' means a component (like a Dashboard) maintains its state (scroll position, user input, internal logic) even if it is detached from the DOM or moved to a different browser window. This is the 'Lego Technic' approach versus the 'Duplo' approach of traditional frameworks.

What is an 'Agent Operating System'?

Neo.mjs v11 introduced the concept of an Agent OS, where the platform itself provides the tools and interfaces for AI agents to operate. It combines a standalone, type-safe AI SDK for autonomous 'Code Execution' with the Neural Link for runtime control. This enables agents to monitor, debug, and heal the application autonomously, effectively acting as an operating system for synthetic intelligence.

How does Neo.mjs handle multi-window applications?

Neo.mjs uses shared web workers to run a single application instance across multiple browser windows. All windows share the same application state and data in real-time. Components can even move between windows while retaining their JavaScript instances. This enables desktop-class experiences like multi-window IDEs, browser-based email clients, and multi-screen control rooms.

What makes Neo.mjs different from React, Angular, or Vue?

Neo.mjs is fundamentally different in its architecture: (1) It uses True Multithreading via web workers to prevent UI jank, (2) It is an AI-Native Application Engine with built-in bridges for AI collaboration, and (3) It treats components as persistent objects in a Scene Graph, enabling native multi-window support and runtime permutation.

Backlog
v12.1.0

9586 Analysis: Robust Multi-Window LivePreview Routing & Base Path Resolution
9585 Bug: LivePreview popout windowUrl generates incorrectly in dist environments
9584 Bug: Data worker broadly bundles non-data framework classes (Main.mjs) causing Webpack build failure
9582 Bug: Webpack fails due to unanchored `webpackInclude` picking up Node modules
9581 Bug: Webpack fails to resolve Task, Canvas, and Data worker dynamic chunks due to strict magic comments
9583 Bug: Webpack matches absolute paths, invalidating the ^\.\/ magic comment anchor
9580 Bug: Webpack fails to resolve internal app.mjs chunks due to strict magic comment regex
9579 Fix ChromaDB defrag crash on ghost entries
9578 Portal: Add TreeGrid Big Data Example
9577 Draft Release Notes: Storytelling & Narrative Arc
9575 Draft Release Notes: Gather Visual Assets
9576 Draft Release Notes: MCP Infrastructure & Security
9569 Epic: Neo.mjs v12.1 Release Notes
9574 Draft Release Notes: Generate Full Changelog
9573 Draft Release Notes: Learning Guides & Minor Features
9572 Draft Release Notes: ScrollSync & Performance
9571 Draft Release Notes: Locked Columns & Value Banding
9570 Draft Release Notes: TreeGrid & Data Pipeline Architecture
9568 Fix code examples in DataPipelines.md guide
9567 Update AI_QUICK_START.md to include Antigravity configuration
9539 Add TreeStore override for updateKey()
9566 Enhance `agent` parameter formatting in GitHub Workflow MCP Server
9538 Enhance Collection.updateKey() to support filtered collections (allItems map)
9565 Regression: Store.load({url}) fails when Store has no initial URL config
9552 Docs: Create Learning Guide for the Unified Data Pipeline Architecture
9564 Finalize Data Pipeline Push Integration & UI Reactivity
9563 Modularize MCP Server Architecture and Extract Shared Services
9562 Implement Generic OIDC Discovery and Google OAuth Hands-on Guide
9561 Add Functional Tests for MCP Authorization and Refine Error Handling
9560 Create Comprehensive Guide for MCP Server Authorization
9558 Implement OIDC/OAuth Authorization for KB and Memory MCP Servers
9551 Examples: Implement unified Data Pipeline showcases
9550 Refactor(data): Implement Store-to-Pipeline Legacy Bridge
9502 Migrate existing Stores to the new Pipeline architecture
9549 Remove `console.log` statements causing noise in unit tests
9548 `calcValueBands` broken state initialization on `splice` (StoreValueBanding test failure)
9454 Implement Push-Based WebSocket Integration in Data Pipeline
9455 Integrate RPC API into Pipeline Architecture (Connection.Rpc)
9547 Fix RemoteMethodAccess for Main Thread Addons and Instance-to-Instance ID collision
9546 Refactor Pipeline IPC to use Declarative Remote Configs (Instance Proxies)
9453 Implement Pipeline IPC and Remote Execution Routing
9545 Fix Knowledge Base Tool Argument Routing (x-pass-as-object)
9544 Enhance RemoteMethodAccess to Support Instance-to-Instance Routing
9543 Store Pipeline Instantiation and Legacy Parser Compatibility
9452 Connection Foundation and Parser Refactoring
9456 Epic: Buffered Grid - High-Performance Locked Columns (`locked: 'start' | 'end'`)
9542 Update Code of Conduct to include AI Entities & Autonomous Agents
9541 Remove outdated and redundant .github/CONCEPT.md
9540 Update CONTRIBUTING.md to include AI Agents & Autonomous Entities
9196 Feature: Add Collection.updateKey() method
9534 Rename mcp-stdio.mjs to mcp-server.mjs
9533 Migrate MCP servers from SSEServerTransport to StreamableHTTPServerTransport
9532 Support SSE transport for knowledge-base and memory-core MCP servers
9531 Grid SortZone incorrectly intercepts column resize drag events, causing VDOM corruption and layout thrash
9530 Grid cells vanish during column resize after a drag-and-drop column reorder
9529 Add lightweight cell resizing method to grid.Body
9528 Real-time cell resizing during grid column drag:move
9527 Grid cells do not shrink on column resize drop due to minWidth constraint
9526 Add visual focus styling during grid column resizing
9525 Fix header resize proxy visibility and prevent unwanted absolute styles on drop
9524 Prevent column sort toggle when clicking/dragging resize handles
9523 Resolve drag&drop collision between grid column resorting and resizing
9522 Grid Column Resizing: Header Logic and Update on Drop
9521 Tree Grid: Optional Helper Lines for Tree Structures
9520 LivePreview: Propagate active theme to popout child window
9519 SharedWorker: Fix theme resolution for child windows
9518 Fix LivePreview incorrect popout URL for subsequent windows (SharedWorkers)
9517 Workers: Standardize and optimize dynamic imports
7918 Epic: Neo Command Center (Agent OS UI)
8022 Refactor AgentOS Viewport: Modularize Components
8025 Create Custom Theme: Neo Cyberpunk
9516 Portal HomeCanvas: Enhance spark contrast in dark theme
9515 [Epic Sub] Value Banding styling conflicts with row selection
9514 [Epic Sub] TreeStore Value Banding Support
9513 Optimize Grid Value Banding (startIndex Support)
9512 Dynamic Value Banding Updates
9511 [Epic] Grid Value Banding
9510 Tooltip regression: dynamic domListeners bypassed reactivity and bubbling fixes
9509 Docs: Align core engine guides to use "engine" terminology instead of "framework"
9508 Docs: Explain Main Thread Addons and Lazy Loading in Lifecycle guide
9507 Docs: Clarify Two-Tier Reactivity Architecture and core.Config role
9506 Improve inline code styling within h1 tags in Markdown component
9505 Portal: Missing scrollbar contrast in learning section markdown component
9504 List: Fix vertical scrollbar visibility and contrast
9451 Create Pipeline Cornerstone and Refactor Store Implementation
8019 Bug: isWindowDragging flag stuck after external drop
9503 TimelineCanvas regression: Canvas not showing due to SharedCanvas getCanvasId() mismatch with componentId
9500 Epic: The Core Engine Learning Guides & Workshop
9485 Grid: Horizontal Scroll Performance & Jitter for Locked Columns
9484 Grid: Add Unit Tests for Locked Columns Feature
9460 Grid: Column Drag & Drop Integration & State Transitions
9459 Grid: Implement Reactive locked Config and Cell Pooling Bypass
9458 Grid: Create Main Thread Addon for Column Pinning (CSS Variables)
9483 Grid: Implement Reactive locked Config and Run-Time Column Reordering
9457 Grid: Implement Mathematical Column Layout Engine
9356 Chrome Windows: Multi Window Drag & Drop
9359 Google Windows Covid 19 Helix
9365 Chrome Window Neo mjs home
9482 Firefox Nightly: Scroll wheel stuck on Portal home page due to scroll-snap-type mandatory
9481 Auto-detect `isTreeGrid` config based on the Store instance
9479 Firefox Nightly R&D: OffscreenCanvas Worker-to-Worker Transfer Failure
9478 Grid ScrollManager: Support dynamic windowId changes for Main Thread Addon registration
9363 Chrome Window Learn funktionale Komponenten
9364 Chrome Window Calendar Basic
7957 Epic: WebSocket RMA Infrastructure
7958 Epic: Telemetry & Observability
7959 Epic: Agent Security & Capabilities
9476 DevIndex: Add Contextual Rank Column to Grid
9475 Grid: Remove `#initialChunkSize` DOM pooling bypass & fix pool shrink bug
9474 Grid: Optimize row pooling for small datasets
9473 Add File Editing Tool Protocol to AGENTS.md
9472 Add Testing Protocol to AGENTS.md
9471 Add Anti-Corruption Protocol to AGENTS.md
9470 Fix Grid Drag Scrolling Regression
7914 Epic: Foundation for Ticket-Driven Agent Orchestration
7919 Epic: Decouple AI Tooling for Public Ecosystem
7922 Feat: 'Derailment' Intervention Interface
7923 Refactor: Extract Memory Core to @neomjs/ai-memory-server
7924 Refactor: Extract GitHub Workflow to @neomjs/ai-github-server
7925 Feat: Create VisualService (Sighted Agent SDK)
7926 Feat: Add Cross-Repo Capabilities to GitHub Workflow MCP
9461 Epic: TreeGrid Big Data Demo
9469 TreeStore: internalIdMap desyncs after bulk operations (expandAll), breaking selection
9468 Fix memory leak in TreeStore.#rebuildKeysAndCount()
9466 TreeGrid Big Data Demo: Create E2E Tests
9467 Fix TreeStore.collapse() failing after expandAll() due to out-of-sync Collection map
9465 TreeGrid Big Data Demo: Styling, Logging, and Final Integration
9464 TreeGrid Big Data Demo: Implement Controls and Grid Wiring
9463 TreeGrid Big Data Demo: Implement Organic Data Generation Algorithm
9462 TreeGrid Big Data Demo: Scaffold Base Directory and Files
9420 Migrate Data Pipeline to Connection -> Parser -> Normalizer flow
9450 Enhance Data Worker to Instantiate Dynamically Loaded Modules
9419 Implement Dynamic Module Loading in `Neo.worker.Data`
9418 Create Data Normalizer Architecture (`Neo.data.normalizer.Base` & `Tree`)
9412 TreeGrid Component Tests (UI & Interactions)
9448 TreeGrid Component pooling accumulates `is-leaf` class leading to visual bugs
9447 TreeGrid: Fix 7-click expand/collapse bug and redundant change events
9446 Fix ComboBox test failure due to internalId changes
9445 TreeGrid Documentation: Create high-level architectural guide for TreeStore
9444 Clean up redundant `Neo.isDestroyed` catch blocks
9443 Stabilize Playwright Unit Tests by Centralizing Global Mocks
9442 Fix Grid Pooling DOM thrashing and Collection internalId lookup
9440 AI Workflow: Integrate Anchor & Echo strategy into Pre-Flight Commit check
9439 TreeStore: Apply "Anchor & Echo" JSDoc strategy for AI discoverability
9438 TreeStore: Reduce GC pressure and redundant iterations
9437 TreeStore: Optimize #allRecordsMap iteration loops
9433 TreeStore: Implement bulk expandAll() and collapseAll() methods
9435 TreeStore: Fix visible projection for dynamic child additions to expanded parents
9434 TreeStore: Decouple clearFilters() from legacy allItems pattern
9432 TreeStore: Override clear() to prevent memory leaks and split-brain states
9431 TreeStore: Fix ARIA desync (siblingIndex and siblingCount) after sort and filter
9429 TreeStore: Implement ancestor-aware filtering for filter override
9428 TreeStore: Implement hierarchical sorting for doSort override
9430 TreeModel: Introduce childCount to decouple isLeaf state from emptiness
9411 TreeGrid Unit Tests (Data & Logic)
9427 Fix TreeStore projection mutations and Row VDOM recycling
9426 Refactor Tree column and component reactivity
9425 Refactor Tree cell component architecture for performance
9424 Optimize `cellPoolSize` calculation in `grid.Body` to prevent DOM waste
9410 TreeGrid Documentation & Examples
9423 TreeStore Full CRUD Support & Structural Mutations
9422 Update TreeStore to manage ARIA sibling fields on mutations
9408 Grid Core Integration & TreeGrid Accessibility
9407 Create `Neo.grid.column.Tree` & Cell Component
9417 Optimize `TreeStore` Hot Paths (Performance)
9416 Add Error State & Events for Async Tree Loading
9413 Create Async Subtree Loading for `Neo.data.TreeStore`
9415 Support "Turbo Mode" in `Neo.data.TreeStore`
9414 Refactor `Neo.data.Store` to unify Record Hydration
9406 Create `Neo.data.TreeStore`
9405 Create `Neo.data.TreeModel`
9403 Performance: Eliminate Path scrollTop Layout Thrashing in getTargetData
9402 Performance: Eliminate Main Thread Layout Thrashing in getTargetData
9401 Performance: Proxy Getter Hoisting in Grid Row & Array Slice Optimization
9400 Performance: O(1) Fast Paths for onScrollCapture getById Traversal
9398 Performance: Eliminate O(N²) App Worker VDOM Traversal (syncVnodeTree)
9396 E2E: Implement Synthetic Thumb Drag Profiles for Optical Pinning Validation
9395 E2E: Refine GridRowScrollPinning to Target Explicit Thumb Drags
9394 E2E: Validate GridRowScrollPinning against DevIndex Canvas Worker Latency
9393 E2E: Implement GridRowScrollPinning via CSS Variables
9392 E2E: Implement GridRowScrollPinning Automated Test and Sync Refinement
9391 E2E: Refactor GridRowScrollPinning to Hybrid rAF Engine
9390 E2E: Fix GridRowScrollPinning Registration and DOM Lookup Flaws
9389 E2E: Remove Legacy Scroll Prediction Heuristics from Grid ScrollManager
9387 E2E: Implement Main Thread Optical Pinning for Grid Scrolling
9388 E2E: Enhance VDOM Update Pipeline with Meta Payload Support
7834 [Test] Button click event not firing on mobile
9386 E2E: Add min velocity threshold to Grid Predictive Scrolling
9385 E2E: Expose Performance tracker metrics via Remote Methods
9383 E2E: Implement Predictive Delta Injection (Velocity & Acceleration)
9382 E2E: Implement Dynamic RTT Measurement for VDOM Updates
9384 Implement generic Neo.util.Performance tracker
9381 E2E: Create Deterministic Grid Thumb Drag Benchmark
9379 Mobile Scrollbar UX: Increase touch width to 40px and theme thumb colors
9378 Extract desktop grid scrollbar width into a CSS variable
9377 Define `--grid-scrollbar-touch-width` variable across all themes
9369 [Epic] Upgrade ScrollSync for Loop-Free Two-Way Binding (Mobile & Desktop)
9376 Add .neo-has-touch capability class and enhance Mobile Grid Scrollbar
9374 Mobile UX Enhancements for Grid VerticalScrollbar (SCSS)
9373 Enable Mobile Two-Way ScrollSync for Grid VerticalScrollbar
9372 Refactor GridDragScroll to use ScrollSync API
9375 Improve ScrollSync Lock Release Mechanism (rAF vs setTimeout)
9371 API for Programmatic Scrolling in ScrollSync
9370 Upgrade ScrollSync Locking Mechanism
9361 Chrome Windows Johannes DevIndex
9362 Chrome Windows DevIndex
9360 scroll to bottom bug on main page
9368 Enhance Helix to rotate to initial selection on mount
9367 Fix Helix & Gallery selection models keynav and record resolution
9357 Chrome Windows Covid App
9358 Google Windows Covid 19 Helix
7847 Enhance WindowPosition Addon with Adaptive Tracking
9349 build: Fix dirent.path resolution and OS-agnostic pathing in esmodules.mjs
7756 Enhance `create_comment` tool to enforce reading related tickets

v12.0.0
v11.24.0
v11.23.1
v11.23.0
v11.22.0
v11.21.0
v11.20.0
v11.19.1
v11.19.0
v11.18.0
v11.17.1
v11.17.0
v11.16.0
v11.15.0
v11.14.0
v11.13.0
v11.12.0
v11.11.0
v11.10.0
v11.9.0
v11.8.0
v11.7.0
v11.6.1
v11.6.0
v11.5.0
v11.4.0
v11.3.0
v11.2.0
v11.1.0
v11.0.1
v11.0.0
v10.9.0
v10.8.0
v10.7.0
v10.6.0
v10.5.4
v10.5.3
v10.5.2
v10.5.1
v10.5.0
v10.4.1
v10.4.0
v10.3.5
v10.3.4
v10.3.3
v10.3.2
v10.3.1
v10.3.0
v10.2.1
v10.2.0
v10.1.1
v10.1.0
v10.0.2
v10.0.1
v10.0.0
v10.0.0-beta.6
v10.0.0-beta.5
v10.0.0-beta.4
v10.0.0-beta.3
v10.0.0-beta.2
v10.0.0-beta.1
v10.0.0-alpha.5
v10.0.0-alpha.4
v10.0.0-alpha.3
v10.0.0-alpha.2

6832 README.md: content refinement
6836 vdom.Helper: compareAttributes() => refactoring
6835 vdom.Helper: findMovedNodes() => refactoring
6834 vdom.Helper: createVnodeMap() => refactoring
6833 vdom.Helper: getPhysicalIndex()
6831 main.DeltaUpdates: move relevant DomAccess configs over
6830 package.json: description & keywords enhancement

v10.0.0-alpha.1
v9.16.0
v9.15.0
v9.14.0
v9.13.1
v9.13.0
v9.12.0
v9.11.1
v9.11.0
v9.10.5
v9.10.4
v9.10.2
v9.10.1
v9.10.0
v9.9.0
v9.8.0
v9.7.1
v9.7.0
v9.6.1
v9.6.0
v9.5.0
v9.3.0
v9.2.0
v9.1.0
v9.0.2
v9.0.1
v9.0.0
v8.43.1
v8.43.0
v8.42.0
v8.41.2
v8.41.1
v8.41.0
v8.40.0
v8.39.1
v8.39.0
v8.38.0
v8.37.0
v8.36.0
v8.35.1
v8.35.0
v8.34.0
v8.33.0
v8.32.0
v8.31.1
v8.31.0
v8.30.0
v8.29.0
v8.28.1
v8.28.0
v8.27.1
v8.27.0
v8.26.1
v8.26.0
v8.25.0
v8.24.0
v8.23.0
v8.22.0
v8.21.2
v8.21.1
v8.21.0
v8.20.2
v8.20.1
v8.20.0
v8.19.1
v8.19.0
v8.18.1
v8.18.0
v8.17.1
v8.17.0
v8.16.0
v8.15.0
v8.14.3
v8.14.2
v8.14.1
v8.14.0
v8.13.0
v8.12.0
v8.11.0
v8.10.1
v8.10.0
v8.9.1
v8.9.0
v8.8.0
v8.7.1
v8.7.0
v8.6.2
v8.6.1
v8.6.0
v8.5.0
v8.4.2
v8.4.1
v8.4.0
v8.3.0
v8.2.0
v8.1.3
v8.1.2
v8.1.1
v8.1.0

Frontmatter

id	6833
title	vdom.Helper: getPhysicalIndex()
state	Closed
labels	enhancement
assignees	tobiu
createdAt	Jun 18, 2025, 6:25 PM
updatedAt	Jun 18, 2025, 6:28 PM
githubUrl	https://github.com/neomjs/neo/issues/6833
author	tobiu
commentsCount	0
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
blockedBy	[]
blocking	[]
closedAt	Jun 18, 2025, 6:28 PM

vdom.Helper: getPhysicalIndex()

Name: Neo.mjs Application Engine
Author: Neo.mjs

Closed v10.0.0-alpha.2 enhancement

tobiu commented on Jun 18, 2025, 6:25 PM

We are using the same logic within insertNode() and moveNode()
Time to give it a new home

tobiu assigned to @tobiu on Jun 18, 2025, 6:25 PM

tobiu added the enhancement label on Jun 18, 2025, 6:25 PM

tobiu referenced in commit 8a6c8a7 - "vdom.Helper: getPhysicalIndex() #6833" on Jun 18, 2025, 6:26 PM

tobiu closed this issue on Jun 18, 2025, 6:28 PM