Copilot instructions

1---
2description: Architecture documentation for VS Code notebook and interactive window components. Use when working in `src/vs/workbench/contrib/notebook/`
3---
4 
5# Notebook Architecture
6 
7This document describes the internal architecture of VS Code's notebook implementation.
8 
9## Model resolution
10 
11Notebook 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.
12 
13## Viewport rendering (virtualization)
14 
15The 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>`.
16 
17![Viewport Rendering](./resources/notebook/viewport-rendering.drawio.svg)
18 
19The rendering has the following steps:
20 
211. **Render Viewport** - Layout/render only the cells that are in the visible viewport
222. **Render Template** - Each cell type has a template (code cell, markdown cell) that is instantiated via `CodeCellRenderer` or `MarkupCellRenderer`
233. **Render Element** - The cell content is rendered into the template
244. **Get Dynamic Height** - Cell height is computed dynamically based on content (editor lines, outputs, etc.)
255. **Cell Parts Lifecycle** - Each cell has lifecycle parts that manage focus, selection, and other state
26 
27### Cell resize above viewport
28 
29When 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.
30 
31![Cell Resize Above Viewport](./resources/notebook/cell-resize-above-viewport.drawio.svg)
32 
33## Cell Rendering
34 
35The notebook editor renders cells through a contribution system. Cell parts are organized into two categories via `CellPartsCollection`:
36 
37- **CellContentPart** - Non-floating elements rendered inside a cell synchronously to avoid flickering
38  - `prepareRenderCell()` - Prepare model (no DOM operations)
39  - `renderCell()` / `didRenderCell()` - Update DOM for the cell
40  - `unrenderCell()` - Cleanup when cell leaves viewport
41  - `updateInternalLayoutNow()` - Update layout per cell layout changes
42  - `updateState()` - Update per cell state change
43  - `updateForExecutionState()` - Update per execution state change
44 
45- **CellOverlayPart** - Floating elements rendered on top, may be deferred to next animation frame
46 
47Cell parts are located in `view/cellParts/` and contribute to different aspects:
48- **Editor** - The Monaco editor for code cells
49- **Outputs** - Rendered outputs from code execution
50- **Toolbar** - Cell toolbar with actions
51- **Status Bar** - Execution status, language info
52- **Decorations** - Fold regions, diagnostics, etc.
53- **Context Keys** - Cell-specific context key management
54- **Drag and Drop** - Cell reordering via `CellDragAndDropController`
55 
56## Focus Tracking
57 
58Focus in the notebook editor is complex because there are multiple focusable elements:
59 
601. The notebook list itself (`NotebookCellList`)
612. Individual cell containers
623. Monaco editors within cells
634. Output elements (webviews via `BackLayerWebView`)
64 
65The `NotebookEditorWidget` tracks focus state and provides APIs to manage focus across these components. Context keys like `NOTEBOOK_EDITOR_FOCUSED`, `NOTEBOOK_OUTPUT_FOCUSED`, and `NOTEBOOK_OUTPUT_INPUT_FOCUSED` are used to track focus state.
66 
67## Optimizations
68 
69### Output virtualization
70 
71Large outputs are virtualized similar to cells. Only visible portions of outputs are rendered.
72 
73### Cell DOM recycling
74 
75Cell DOM elements are pooled and recycled to reduce DOM operations. When scrolling, cells that move out of the viewport have their templates returned to the pool. Editor instances are managed via `NotebookCellEditorPool`.
76 
77### Webview reuse
78 
79Output webviews are reused across cells when possible to reduce the overhead of creating new webview contexts. The `BackLayerWebView` manages the webview lifecycle.
80 
81---
82 
83# Find in Notebook Outputs
84 
85The notebook find feature supports searching in both text models and rendered outputs. The find functionality is implemented via `FindModel` and `CellFindMatchModel` classes.
86 
87## Hybrid Find
88 
89For rendered outputs (HTML, images with alt text, etc.), the find uses a hybrid approach:
90 
911. **Text model search** - Searches cell source code using standard text search via `FindMatch`
922. **DOM search in webview** - Uses `window.find()` to search rendered output content via `CellWebviewFindMatch`
93 
94![Hybrid Find](./resources/notebook/hybrid-find.drawio.svg)
95 
96The hybrid find works by:
97 
981. First finding matches in text models (cell inputs) - stored in `contentMatches`
992. Then finding matches in rendered outputs via webview - stored in `webviewMatches`
1003. Mixing both match types into a unified result set via `CellFindMatchModel`
1014. Navigating between matches reveals the appropriate editor or output
102 
103### Implementation details
104 
105- Uses `window.find()` for DOM searching in webview
106- Uses `document.execCommand('hiliteColor')` to highlight matches
107- Serializes `document.getSelection()` to get match positions
108- Creates ranges for current match highlighting
109