vscode/.github/instructions/interactive.instructions.md

description

description
Architecture documentation for VS Code interactive window component. Use when working in `src/vs/workbench/contrib/interactive`

Interactive Window

The interactive window component enables extensions to offer REPL like experience to its users. VS Code provides the user interface and extensions provide the execution environment, code completions, execution results rendering and so on.

The interactive window consists of notebook editor at the top and regular monaco editor at the bottom of the viewport. Extensions can extend the interactive window by leveraging the notebook editor API and text editor/document APIs:

• Extensions register notebook controllers for the notebook document in the interactive window through vscode.notebooks.createNotebookController. The notebook document has a special notebook view type interactive, which is contributed by the core instead of extensions. The registered notebook controller is responsible for execution.
• Extensions register auto complete provider for the bottom text editor through vscode.languages.registerCompletionItemProvider. The resource scheme for the text editor is interactive-input and the language used in the editor is determined by the notebook controller contributed by extensions.

Users can type in code in the text editor and after users pressing Shift+Enter, we will insert a new code cell into the notebook document with the content from the text editor. Then we will request execution for the newly inserted cell. The notebook controller will handle the execution just like it's in a normal notebook editor.

Interactive Window Registration

Registering a new editor type in the workbench consists of two steps:

• Register an editor input factory which is responsible for resolving resources with given glob patterns. Here we register an InteractiveEditorInput for all resources with vscode-interactive scheme.
• Register an editor pane factory for the given editor input type. Here we register InteractiveEditor for our own editor input InteractiveEditorInput.

The workbench editor service is not aware of how models are resolved in EditorInput, neither how EditorPanes are rendered. It only cares about the common states and events on EditorInput or EditorPane, i.e., display name, capabilities (editable), content change, dirty state change. It's EditorInput/EditorPane's responsibility to provide the right info and updates to the editor service. One major difference between Interactive Editor and other editor panes is Interactive Window is never dirty so users never see a dot on the editor title bar.

Interactive Window Editor Model Resolution

The Interactive.open command will manually create an InteractiveEditorInput specific for the Interactive Window and resolving that Input will go through the following workflow:

The INotebookEditorModelResolverService is used to resolve the notebook model. The InteractiveEditorInput wraps a NotebookEditorInput for the notebook document and manages a separate text model for the input editor.

When the notebook model is resolved, the INotebookEditorModelResolverService uses the working copy infrastructure to create a IResolvedNotebookEditorModel. The content is passed through a NotebookSerializer from the INotebookService to construct a NotebookTextModel.

The FileSystem provider that is registered for vscode-interactive schema will always return an empty buffer for any read, and will drop all write requests as nothing is stored on disk for Interactive Window resources. The NotebookSerializer that is registered for the interactive viewtype knows to return an empty notebook data model when it deserializes an empty buffer when the model is being resolved.

Restoring the interactive window happens through the editor serializer (InteractiveEditorSerializer), where the notebook data is stored, and can be used to repopulate the InteractiveEditorInput without needing to go through the full editor model resolution flow.

UI/EH Editor/Document Syncing

EditorInput is responsible for resolving models for the given resources but in Interactive Window it's much simpler as we are not resolving models ourselves but delegating to Notebook and TextEditor. InteractiveEditorInput does the coordination job:

• It wraps a NotebookEditorInput via _notebookEditorInput for the notebook document (history cells)
• It manages a separate text model via ITextModelService for the input editor at the bottom
• The IInteractiveDocumentService coordinates between these two parts
• The IInteractiveHistoryService manages command history for the input editor