vscode notebook.instructions.md

Notebook Architecture

This document describes the internal architecture of VS Code's notebook implementation.

Model resolution

Notebook model resolution is handled by NotebookService. It resolves notebook models from the file system or other sources. The notebook model is a tree of cells, where each cell has a type (code or markdown) and a list of outputs.

Viewport rendering (virtualization)

The notebook viewport is virtualized to improve performance. Only visible cells are rendered, and cells outside the viewport are recycled. The viewport rendering is handled by NotebookCellList which extends WorkbenchList<CellViewModel>.

The rendering has the following steps:

1. Render Viewport - Layout/render only the cells that are in the visible viewport
2. Render Template - Each cell type has a template (code cell, markdown cell) that is instantiated via CodeCellRenderer or MarkupCellRenderer
3. Render Element - The cell content is rendered into the template
4. Get Dynamic Height - Cell height is computed dynamically based on content (editor lines, outputs, etc.)
5. Cell Parts Lifecycle - Each cell has lifecycle parts that manage focus, selection, and other state

Cell resize above viewport

When a cell above the viewport is resized (e.g., output grows), the viewport needs to be updated to maintain scroll position. This is handled by tracking scroll anchors.

Cell Rendering

The notebook editor renders cells through a contribution system. Cell parts are organized into two categories via CellPartsCollection:

• CellContentPart - Non-floating elements rendered inside a cell synchronously to avoid flickering
  • prepareRenderCell() - Prepare model (no DOM operations)
  • renderCell() / didRenderCell() - Update DOM for the cell
  • unrenderCell() - Cleanup when cell leaves viewport
  • updateInternalLayoutNow() - Update layout per cell layout changes
  • updateState() - Update per cell state change
  • updateForExecutionState() - Update per execution state change