Represents a seamless pane navigation request.
This is a custom OSC not yet implemented in any other terminal emulator. Its purpose is to allow for pane navigation between multiplexer panes and application panes seamless (possible using the same key bindings). For tmux, this is accomplshed via a plugin (vim-tmux-navigator) which must be installed in both tmux and vim. I believe this works by having the tmux plugin forward requests to vim when vim is active and then if necessary invoking tmux back to do navigation. But this is vendor specific.
This protocol works similarly but all comunication is done via the escape sequence.
Querying for support of this protocol is done via: OSC 8671 ; t=supported ST If the terminal supports the protocl, it responds with the string. OSC 8671 ; t=supported ST
An application can mark the current terminal as supporting nested navigation using the following sequence: OSC 8671 ; t=register:h=false ST
The parameter 'h' indicates the terminal can hide the cursor automatically when an enter event is sent. This is useful to prevent stale cursor positions from showing when the enter event occurs (which causes flickering), since the enter event may cause the cursor to immediately move.
Once registered, the application will receive events from the terminal when the user attempts to navigate panes while the application is focused. OSC 8671 ; t=navigate:w=false|true:id=xxx ; left|right|down|up ST
If the application w (wrap) is false the application must response to the message either by acknowledging it completed the request or by telling the controlling terminal to perform navigation. When responding the id must be preserved. Additionally, the application should provide a range of cells represneting the bounding edge of its currently active pane when telling the terminal to perform navigation. This ensures the outer terminal switches to the correct pane. The range is 1 indexed and inclusive. If no range is specified it is assumed the edge is the entire application.
To indicate no navigation was performed (because we're moving down and there is no pane below), use: OSC 8671 ; t=navigate:id=xxx:r=1,100 ; left|right|down|up ST
To indicate navigation was successful, use: OSC 8671 ; t=acknowledge:id=xxx ; left|right|down|up ST
Responses are required in both cases because the outer terminal needs to know when the request completes to ensure processing input in the correct order. If the user navigates then types "A", its unclear which pane to send "A" to unless we know the request is completed. Its recommended terminals implementing this protocol buffer input events while navigation is pending up to a certain timeout. When the timeout is reached, navigation should complete assuming the application responsed with the "navigate" message.
When w (wrap) is true, the application should wrap around (essentially the application should assume it's the only application currently displayed in the window). In this case no response is necessary.
Additionally, when an application is navigated to via pane navigation, an "enter" event is emitted. This can be used to navigate to (for example) the bottom pane in the app when navigating upwards. This notification requires no response and application are not required to even process it. This is solely to enable application developers to create the smoothest experience possible when navigation occurs.
The direction is still the navigation direction, meaning if the direction is "up" the application may choose to focus its botton pane. To perform accurate hit testing when there are multiple potential panes to navigate to, a coordinate range is provided. This range is inclusive and 1 indexed. If no range is provided it should be assumed any possible pane is valid. If there is a range, only a pane which intersects the coordinate range (which is relative to the direction's axis (rows or cols)) should be navigated to. OSC 8671 ; t=enter:r=1,100 ; left|right|down|up ST
On application exit, the application should unregister itself via: OSC 8671 ; t=unregister ST
Unregistration happens automatically when hard or soft resetting the terminal. And the registration status should be stored separately between the primary and alternate screen buffers.
1.15.0