1---
2title: Zed Development: Glossary
3description: "Guide to zed development: glossary for Zed development."
4---
5
6# Zed Development: Glossary
7
8This page defines terms and structures used throughout the Zed codebase.
9
10It is a best-effort list and a work in progress.
11
12<!--
13TBD: Glossary Improvement
14
15Questions:
16
17- Can we generate this list from doc comments throughout zed?
18- We should have a section that shows the various UI parts and their names. (Can't do that in the channel.)
19-->
20
21## Naming conventions
22
23These are common naming patterns across the codebase. `Name` is a placeholder
24for any type name, such as `AnyElement` or `LspStore`.
25
26- `AnyName`: A type-erased version of _name_. Think `Box<dyn NameTrait>`.
27- `NameStore`: A wrapper type which abstracts over whether operations are running locally or on a remote.
28
29## GPUI
30
31### State management
32
33- `App`: A singleton that holds full application state, including all entities. `App` is not `Send`, so it exists only on the thread that created it (usually the main/UI thread). If you see `&mut App`, you are on the UI thread.
34- `Context`: A wrapper around `App` with specialized behavior for a specific `Entity`. You can think of it as `(&mut App, Entity<V>)`. For example, `App::spawn` takes `AsyncFnOnce(AsyncApp) -> Ret`, while `Context::spawn` takes `AsyncFnOnce(WeakEntity<V>, AsyncApp) -> Ret`.
35- `AsyncApp`: An owned version of `App` for async contexts. It is still not `Send`, so it still runs on the main thread, and operations may fail if the `App` has already terminated.
36 `AsyncApp` exists because `App` is usually accessed as `&mut App`, which is awkward to hold across async boundaries.
37- `AppContext`: A trait that abstracts over `App`, `AsyncApp`, `Context`, and their test variants.
38- `Task`: A future running (or scheduled to run) on a background or foreground executor. Unlike regular futures, tasks do not need `.await` to start. You still need to await them to read their result.
39- `Executor`: Used to spawn tasks that run either on the foreground or background thread. Try to run the tasks on the background thread.
40 - `BackgroundExecutor`: A threadpool running `Task`s.
41 - `ForegroundExecutor`: The main thread running `Task`s.
42- `Entity`: A strong, well-typed reference to a struct which is managed by gpui. Effectively a pointer/map key into the `App::EntityMap`.
43- `WeakEntity`: A runtime checked reference to an `Entity` which may no longer exist. Similar to [`std::rc::Weak`](https://doc.rust-lang.org/std/rc/struct.Weak.html).
44- `Global`: A singleton type which has only one value, that is stored in the `App`.
45- `Event`: A data type that can be sent by an `Entity` to subscribers.
46- `Action`: An event that represents a user's keyboard input that can be handled by listeners
47 Example: `file finder: toggle`
48- `Observing`: Reacting to notifications that entities have changed.
49- `Subscription`: An event handler that is used to react to the changes of state in the application.
50 1. Emitted event handling
51 2. Observing `{new,release,on notify}` of an entity
52
53### UI
54
55- `View`: An `Entity` which can produce an `Element` through its implementation of `Render`.
56- `Element`: A type that can be laid out and painted to the screen.
57- `element expression`: An expression that builds an element tree, example:
58
59```rust
60h_flex()
61 .id(text[i])
62 .relative()
63 .when(selected, |this| {
64 this.child(
65 div()
66 .h_4()
67 .absolute()
68 etc etc
69```
70
71- `Component`: A builder which can be rendered turning it into an `Element`.
72- `Dispatch tree`: TODO
73- `Focus`: The place where keystrokes are handled first
74- `Focus tree`: Path from the place that has the current focus to the UI Root. Example <img> TODO
75
76## Zed UI
77
78- `Window`: A struct representing a Zed window in your desktop environment (see image below). You can have multiple windows open. This is mostly passed around for rendering.
79- `Modal`: A UI element that floats on top of the rest of the UI
80- `Picker`: A struct representing a list of items floating on top of the UI (Modal). You can select an item and confirm. What happens on select or confirm is determined by the picker's delegate. (The 'Modal' in the image below is a picker.)
81- `PickerDelegate`: A trait used to specialize behavior for a `Picker`. The `Picker` stores the `PickerDelegate` in the field delegate.
82- `Center`: The middle of the zed window, the center is split into multiple `Pane`s. In the codebase this is a field on the `Workspace` struct. (see image below).
83- `Pane`: An area in the `Center` where we can place items, such as an editor, multi-buffer or terminal (see image below).
84- `Panel`: An `Entity` implementing the `Panel` trait. Panels can be placed in a `Dock`. In the image below: `ProjectPanel` is in the left dock, `DebugPanel` is in the bottom dock, and `AgentPanel` is in the right dock. `Editor` does not implement `Panel`.
85- `Dock`: A UI element similar to a `Pane` that can be opened and hidden. Up to three docks can be open at once: left, right, and bottom. A dock contains one or more `Panel`s, not `Pane`s.
86
87<img width="1921" height="1080" alt="Screenshot for the Pane and Dock features" src="https://github.com/user-attachments/assets/2cb1170e-2850-450d-89bb-73622b5d07b2" />
88
89- `Project`: One or more `Worktree`s
90- `Worktree`: Represents either local or remote files.
91
92<img width="552" height="1118" alt="Screenshot for the Worktree feature" src="https://github.com/user-attachments/assets/da5c58e4-b02e-4038-9736-27e3509fdbfa" />
93
94- [Multibuffer](https://zed.dev/docs/multibuffers): A list of Editors, a multi-buffer allows editing multiple files simultaneously. A multi-buffer opens when an operation in Zed returns multiple locations, examples: _search_ or _go to definition_. See project search in the image below.
95
96<img width="800" height="886" alt="Screenshot for the MultiBuffer feature" src="https://github.com/user-attachments/assets/d59dcecd-8ab6-4172-8fb6-b1fc3c3eaf9d" />
97
98## Editor
99
100- `Editor`: The text editor type. Most editable surfaces in Zed are an `Editor`, including single-line inputs. Each pane in the image above contains one or more `Editor` instances.
101- `Workspace`: The root of the window
102- `Entry`: A file, dir, pending dir or unloaded dir.
103- `Buffer`: The in-memory representation of a 'file' together with relevant data such as syntax trees, git status and diagnostics.
104- `pending selection`: You have mouse down and you're dragging but you have not yet released.
105
106## Collab
107
108- `Collab session`: Multiple users working in a shared `Project`
109- `Upstream client`: The zed client which has shared their workspace
110- `Downstream client`: The zed client joining a shared workspace
111
112## Debugger
113
114- `DapStore`: Is an entity that manages debugger sessions
115- `debugger::Session`: An entity that manages the lifecycle of a debug session and communication with DAPs.
116- `BreakpointStore`: Is an entity that manages breakpoints states in local and remote instances of Zed
117- `DebugSession`: Manages a debug session's UI and running state
118- `RunningState`: Directly manages all the views of a debug session
119- `VariableList`: The variable and watch list view of a debug session
120- `Console`: TODO
121- `Terminal`: TODO
122- `BreakpointList`: TODO