What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

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

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Frontmatter

id	14970
title	DockRevealOverlay hidden-cls delta intermittently unapplied on a live surface — worker truth correct, DOM stale
state	Open
labels	bugai
assignees	[]
createdAt	4:44 PM
updatedAt	4:44 PM
githubUrl	https://github.com/neomjs/neo/issues/14970
author	neo-fable-clio
commentsCount	0
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]

DockRevealOverlay hidden-cls delta intermittently unapplied on a live surface — worker truth correct, DOM stale

Open Backlog/active-chunk-5 bugai

neo-fable-clio commented on 4:44 PM

Context

Found by the PR #14966 pixel gate (2026-07-10) while visually verifying the reveal choreography on examples/dashboard/dock (dev server, dev mode). Filed as an investigation defect with a clean reproducer — root cause deliberately not asserted (V-B-A: the falsifying instrumentation for the delta pipeline hasn't run yet).

The Problem

The reveal overlay's visibility class stops syncing to the DOM. After a dismiss, the worker holds the correct truth while the rendered element keeps the stale state indefinitely:

Worker (via Neural Link, find_instances on the live overlay):

revealState: 'idle', visible: false,
cls: [..., 'neo-dashboard-dock-reveal-overlay-hidden'],  ← hidden present
revealMotionActive: false                                 ← signal settled correctly

DOM (same instant, sampled at 30ms across 1.5s): display: flex, -hidden class absent, overlay fully visible. No flip ever arrives.

Reproduced clean twice (samplers armed BEFORE any manual DOM interaction in the session): one dismiss (revealed-focused → idle) and one full dismiss+re-reveal cycle each produced zero DOM class/display transitions on the overlay element (element identity verified stable — no remount). Intermittency: one earlier reveal transition DID apply its delta (the -hidden removal landed and the overlay appeared); the subsequent dismisses did not. The machine/rail/overlay worker tier behaved correctly throughout — DockMotionSignal counted enter/leave cleanly (revealMotionActive settles), which is why the #14966 unit tier is green and right to be.

Reproducer (live, dev server)

examples/dashboard/dock in dev mode; Neural Link connected.
execute_dock_operation → {operation: 'setItemAutoHidden', itemId: 'inspector', autoHidden: true} on the workspace (neo-viewport-1) — the right rail appears.
call_method on the rail (neo-dashboard-dock-rail-1): onTabClick({component: {dockItemId: 'inspector'}}) — reveal opens (this delta usually applies).
Same call again — machine returns {state: 'idle'} (dismiss executed).
Observe the overlay element: -hidden never returns; getComputedStyle(el).display stays flex. Worker cls (Neural Link) contains -hidden.

The Architectural Reality

The dismiss path: DockRevealStateMachine → DockRail.onRevealStateChange → syncRevealOverlay() → one batched overlay.set({edge, revealExtent, revealState, revealedItem, ...}) → afterSetRevealState → syncSnapshot() → cls/style vdom update → delta → main thread. Somewhere past the worker-side cls truth (which is CORRECT), the delta fails to reach the DOM — candidates include update batching/merging across the rail's and overlay's same-tick set() sequences, and the known stale-DOM-on-retired-components family noted in the dockdemo workspace JSDoc. Instrumenting Neo.applyDeltas traffic for the overlay id during the reproducer is the first falsifier.

The Fix

Investigation first: capture the delta stream for the overlay across steps 3–5, determine whether the update is (a) never generated worker-side despite the cls config change, (b) generated but merged/dropped, or (c) applied to a different node. Then fix at the owning tier. No prescription until (a)/(b)/(c) is settled.

Acceptance Criteria

Root cause identified with delta-stream evidence (a/b/c above).
The reproducer sequence syncs -hidden to the DOM on every dismiss (manual + scripted repeats, ≥5 cycles).
A regression spec at the owning tier (unit if worker-side, e2e if delta-pipeline).
The #14966 reveal-slide animation restarts on every re-reveal on a token-scoped surface (#14969 provides the scope) — the visible consequence of the fix.

Out of Scope

The missing token scope / CSS loading on dock surfaces (#14969).
Any change to the choreography classes or DockMotionSignal — both verified correct at their tiers.

Decision Record impact

none — defect investigation; no ADR authority touched.

Related: #14966 (the gate that found it) · #14949 · #14969 (sibling finding, same gate) · #14923 (the destroy-wedge family — possibly related DOM-corpse lineage).

Live latest-open sweep: latest 20 open checked at 2026-07-10T14:30Z; no equivalent. A2A herd window checked (30 msgs): no competing claim.

Origin Session ID: 183ac080-2f24-4837-8f63-69bfc536af0d Retrieval Hint: "reveal overlay hidden cls delta not applied worker truth DOM stale dismiss"