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	14969
title	Dock-zone surfaces never load the dashboard token scope — the motion contract is invisible on both
state	Closed
labels	bugai
assignees	neo-fable-clio
createdAt	Jul 10, 2026, 4:43 PM
updatedAt	Jul 10, 2026, 7:12 PM
githubUrl	https://github.com/neomjs/neo/issues/14969
author	neo-fable-clio
commentsCount	0
parentIssue	13158
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]
closedAt	Jul 10, 2026, 7:12 PM

Dock-zone surfaces never load the dashboard token scope — the motion contract is invisible on both

Closed Backlog/active-chunk-5 bugai

neo-fable-clio commented on Jul 10, 2026, 4:43 PM

Context

The PR #14966 pixel gate was the first rendered-pixel verification of the dock motion chain after the shared tokens (#14947), FLIP consumer (#14944), and choreography classes (#14966) converged. Unit and Neural-Link tiers had verified worker truth, but neither watched the rendered surface.

The Problem

The dock motion contract lives in resources/scss/src/dashboard/Container.scss: --dock-transition-*, reduced-motion collapse, reveal/arrival keyframes, splitter cursors, and rail/overlay styling. The css map loads that file with Neo.dashboard.Container instances, but neither dock-zone surface creates one:

examples/dashboard/dock projects ordinary containers through DockLayoutAdapter.
apps/agentos/childapps/dockdemo has the same projection shape.

Both surfaces therefore lacked dashboard/Container.css and a .neo-dashboard scope. Tokens computed unset, DockFlip correctly fell back to instant, and the #14966 choreography classes could not render. The FM cockpit was unaffected because its Viewport mounts a real Neo.dashboard.Container.

Live injection proved the motion CSS itself was correct: loading Container.css and stamping the scope restored 260ms tokens, reveal/arrival motion, splitter cursors, and the 280px edge-band rule.

The Fix

Use the existing, minimal integration shape:

DockLayoutAdapter.project() stamps neo-dashboard on the projection root, so scope survives every re-projection by construction.
The two consuming workspace classes declare additionalThemeFiles: ['Neo.dashboard.Container']; worker/App.insertThemeFiles() reads this contract from the class prototype, not projected instance configs.
Splitter cursor selectors gain enough scope specificity to beat the generic sort affordance without relying on stylesheet load order.

Shape B — a new thin dashboard host class plus theme migration — remains deferred until a third consumer justifies that abstraction.

Contract Ledger

Target Surface	Source of Authority	Behavior	Failure Posture	Evidence
projection root scope	`DockLayoutAdapter.project()` presentation output	every projected dock root carries `neo-dashboard`; no document/persistence field added	Set-based augmentation preserves existing classes and rides every re-projection	adapter unit suite + live root inspection
per-surface theme loading	`worker/App.insertThemeFiles()` prototype contract	the example and dockdemo workspace classes load `Neo.dashboard.Container` via `additionalThemeFiles`	instance-config loading is rejected as ineffective; only the two real consumers declare the dependency	source inspection + stylesheet inventory on both live surfaces
splitter cursor cascade	`Container.scss` dock-scope selectors	horizontal/vertical splitters compute resize cursors	selector specificity beats generic sort affordance independent of load order	computed cursor receipts on both surfaces

Acceptance Criteria

Both dock-zone surfaces compute --dock-transition-duration: 260ms on the native projection scope with zero manual injection.
src/dashboard/Container.css is present in document.styleSheets on both surfaces.
A committed FLIP re-layout takes the animated path (play() === true; 379ms observed) rather than the instant fallback.
Splitter cursors render ew-resize / ns-resize by orientation.
Native exact-head Playwright emulation confirms the scoped token computes 0ms under prefers-reduced-motion: reduce and 260ms with no preference, with no style/DOM injection.
Cross-family review on PR #14971.

Out of Scope

The DockRevealOverlay hidden-cls delta defect (#14970).
Shape B's host-class/theme migration.
Motion token values or choreography classes; this leaf mounts their existing owner scope.

Decision Record impact

aligned-with ADR 0029 — presentation-tier integration only; no persisted dock model shape changes.

Related: #14944 · #14947 · #14959 · #14966 · #14970 · parent #13158

Origin Session ID: 183ac080-2f24-4837-8f63-69bfc536af0d

Retrieval Hint: "dock surface neo-dashboard token scope Container.css additionalThemeFiles motion invisible"

tobiu referenced in commit cfda0d2 - "fix(dashboard): mount the dock token scope on every projection + load its theme file per surface (#14969) (#14971) on Jul 10, 2026, 7:12 PM

tobiu closed this issue on Jul 10, 2026, 7:12 PM