coop/docs/gpui-base-migration.md

Migrating crates/ui to gpui-base

crates/ui is a fork of an early version of gpui-component: 71 files and roughly 21.9k lines that mix behavior, presentation, and application shell. This document is the plan for moving its behavior half onto the upstream gpui-base crate while the application keeps the design system it has today.

The facts below were checked against gpui-base 0.6.1 (crates.io), the gpui-kit repository at main, and this workspace's Cargo.lock (zed at 4b47ceb, 2026-09-17). Line counts come from wc -l under crates/ui/src.

The two facts that shape the work

GPUI still comes from upstream — addressed as the gpui-pre package. gpui-base declares its GPUI dependency as gpui = { package = "gpui-pre", version = "0.3.1" }: the crate in the graph is the published package gpui-pre, and gpui is only the name used in code. That package is upstream zed's gpui (a snapshot of zed@d89e9c2) republished unchanged, so nothing is forked and there is no source to align. Coop currently pins zed's git repository at 4b47ceb (2026-09-17), roughly four days ahead of that snapshot.

The two cannot be mixed. Zed's git gpui and the gpui-pre package are different crates, so App, Window, Entity, and elements from one are not the other's types, and a dependency graph that contains both does not compile. Zed's crates.io gpui (0.2.2, October 2025) is also far behind the APIs coop already uses. The workspace's gpui entry therefore has to resolve to the gpui-pre package; with the package = alias, every use gpui::… site stays as it is.

The fork's external contract is small. Outside crates/ui, the crate is consumed as 38 imported items plus a single ui::init(cx) call, across 13 modules, and never deeper than ui::<module>::<Item>:

Module	Items	Consumer files
crate root (Icon, IconName, h_flex, v_flex, divider, Root, TitleBar, Sizable, Selectable, Disableable, StyledExt, WindowExtension, InteractiveElementExt)	13	17
input (InputState, Input, InputEvent)	3	10
button (Button, ButtonVariants)	2	14
dock (Panel, PanelView, DockArea, DockItem, DockPlacement, PanelEvent, ClosePanel)	7	10
notification, avatar, menu, scroll, group_box, indicator, switch, modal, tooltip	12	16
list, checkbox, popover, resizable, skeleton, tab, divider (module), history, animation, actions	0 references	0

ui::list and ui::checkbox have no consumers at all; the message list in crates/chat_ui uses GPUI's own list::ListState. The modules with zero external references still serve as internal machinery for dock, menu, modal, and input.

The consequence: this is not a rewrite of an app-facing library. Most of the work is deleting internals and re-expressing a few thousand lines of presentation over base primitives.

What must not change

• crates/theme stays the source of truth: ThemeColors, ThemeFamily, the registry, scrollbar mode, platform, font size and radii.
• Behavior comes from gpui-base; presentation comes from theme plus the ui styled layer. Every migrated component keeps reading cx.theme() and keeps its current spacing, radius, and shadow math, so the rendered result does not move.
• Application code keeps importing theme::ActiveTheme and ui::* under its current names. Module paths are part of the contract; internals are not.
• gpui-component is not adopted. It is a complete, styled visual language, and taking it would replace the design system rather than preserve it.

Two Theme types will exist — theme::Theme and gpui_base::Theme — as separate GPUI globals. Coop's stays the application-facing one. Base's is touched in exactly one place: a theme::sync_base(cx) that projects coop's colors into gpui_base::Theme::global_mut(cx).tokens (SemanticThemeTokens: colors, radius, typography, shadow) plus ThemeAppearance, ScrollbarTheme, and ResizableTheme. It runs from ui::init and on every theme change. This is needed because base paints a few things itself — the focus ring from FocusableExt, text selection under glyphs, scrollbars, resize handles, and the dialog backdrop — and those should follow coop's palette rather than base's default.

What each module becomes

ui module	LOC	Plan	gpui-base counterpart
input/ (state, element, display_map, rope_ext, mask_pattern, movement, selection, indent, mode, change, cursor, blink_cursor, clear_button)	6,929	Replace; keep ui::input::{Input, InputEvent, InputState} as the import path	Input/InputState, Textarea/TextareaState, Editor
list/	1,477	Delete	GPUI's own list (already in use)
checkbox.rs	312	Delete	Checkbox
scroll/ (scrollbar, scrollable, scrollable_mask)	1,332	Replace; keep the ScrollableElement and Scrollbar names	Scrollbar, ScrollableMask
resizable/	927	Replace; base exports the same names (h_resizable, v_resizable, resizable_panel, PANEL_MIN_SIZE, resize_handle)	Resizable + ResizeHandleRenderer for the coop hairline
modal.rs	540	Port onto base parts; keep Modal, ModalButtonProps, and window.open_modal	Dialog, AlertDialog
notification.rs	584	Port; keep Notification, NotificationKind, and window.push_notification	Toast, ToastManager, ToastStack
popover.rs	432	Replace with a coop-styled wrapper	Popover, Popup, Positioner
tooltip.rs	36	Replace with a coop-styled wrapper	Tooltip
button.rs	626	Skin: base behavior plus coop's existing variant tables	Button, StateStyle
switch.rs	287	Skin	Switch, SwitchTrack, SwitchThumb
avatar.rs	141	Skin	Avatar, AvatarImage, AvatarFallback
history.rs, index_path.rs, element_ext.rs, event.rs, focusable.rs	340	Delete	History/UndoHistory, IndexPath, ElementExt, InteractiveElementExt, FocusableExt, FocusTrapElement
styled.rs, actions.rs, animation.rs	305	Keep ui::StyledExt, Size, and Sizable as the app's import; base's h_flex/v_flex helpers are identical (flex_row + items_center) and can be delegated to	styled, StateStyle
icon.rs, kbd.rs, divider.rs, skeleton.rs, group_box.rs, indicator.rs	1,023	Keep; no base equivalent, these are the design system	—
menu/	2,208	Keep; base has no menu. Optional later: re-base anchoring and dismissal on Popup/Positioner	Popup (optional)
dock/ + tab/	3,356	Keep for now; see phase 5	base dock (different contract)
root.rs, window_ext.rs, title_bar.rs	965	Keep; app shell. Root continues to host the dialog and toast layers and focused_input	—

Roughly 10k lines are removed, 3k are re-expressed as thin skins, and 8k are kept.

Dependency change

The workspace manifest's GPUI entries become:

[workspace.dependencies]
gpui           = { package = "gpui-pre",              version = "0.3.5" }
gpui_platform  = { package = "gpui-pre-platform",     version = "0.3.5", features = ["font-kit", "x11", "wayland"] }
gpui_linux     = { package = "gpui-pre-linux",        version = "0.3.5" }
gpui_windows   = { package = "gpui-pre-windows",      version = "0.3.5" }
gpui_macos     = { package = "gpui-pre-macos",        version = "0.3.5" }
gpui_web       = { package = "gpui-pre-web",          version = "0.3.5" }
reqwest_client = { package = "gpui-pre-reqwest-client", version = "0.3.5" }
sum_tree       = { package = "gpui-pre-sum-tree",     version = "0.3.5" }
gpui-base      = "0.6.1"

Because of the package = alias, use gpui::… and use gpui_platform::… keep compiling unchanged. gpui_web moves from web/Cargo.toml into the workspace table with the rest.

The only alternative — leaving the workspace on zed's git gpui and redirecting gpui-base's dependency to it — means vendoring gpui-base and owning its source. That is a fork, and this plan deliberately avoids it.

gpui_tokio is the one missing piece: longbridge does not republish it, and crates/state uses it in three places (init, spawn, spawn_result). Either vendor zed's small crate into the workspace, or drop it for cx.background_spawn. Decide in phase 0.

gpui-base and gpui-pre move together on minor versions (0.6.x requires 0.3.x); bump both in the same change.

Phases

Phase 0 — move gpui onto the gpui-pre package (manifest only)

Point the workspace's GPUI entries at the published gpui-pre crates and fix whatever the four days of API drift between 4b47ceb and zed@d89e9c2 broke. There is no GPUI source to align, patch, or vendor. Confirm that the entry points coop calls still exist in 0.3.5: gpui_platform::application(), web_init(), and single_threaded_web().

Exit criteria: cargo check passes for desktop and for cargo check -p coop_web --target wasm32-unknown-unknown, and the drift fixes are listed in the pull request. The change rewrites the dependency graph, so it stays in a pull request of its own.

Phase 1 — Wire base, delete dead weight (no visual change)

Add gpui-base, make ui::init call gpui_base::init(cx) followed by theme::sync_base(cx), and re-export the base utilities the app already imports under their current names (ElementExt, InteractiveElementExt, IndexPath, History, Disableable, Selectable). Delete checkbox.rs and list/, which have no consumers, along with history.rs, index_path.rs, element_ext.rs, and event.rs once base supplies them. Drop the dependencies this leaves unused.

Exit criteria: no diff outside crates/ui and crates/theme, the app launches, and switching the theme still restyles everything.

Phase 2 — input/ (the largest single win, ~6.9k lines)

The mapping is close to 1:1 with what the app actually uses:

Coop today	gpui-base
InputState::new(window, cx).placeholder(..)	same
.auto_grow(1, 20) (chat composer)	TextareaState::auto_grow(2, 8) with Textarea
.masked(true) (nsec, password, key)	InputState::masked(true), unmask_value()
.set_value(value, window, cx)	set_value(value, window, cx)
InputEvent::{Change, PressEnter, Focus, Blur}	identical variants
Input::new(&state).appearance(false)	coop's Input keeps these chrome options

Known gaps to reconcile here, verified against the 0.6.1 source before starting: clean_on_escape(), set_loading() (called from crates/workspace/src/sidebar/mod.rs), and the InputEditorStyle hook that has to be filled from coop tokens. Everything else in input/ — display_map, rope_ext, mask_pattern, movement, selection, indent, mode, element — is deleted. Afterwards, ropey, sum_tree, lsp-types, tree-sitter, regex, unicode-segmentation, and uuid can probably leave crates/ui's manifest.

Surfaces to re-verify: the chat composer (auto-grow, Enter to send, IME), the subject line, the settings dialog, profile, relay and messaging lists, the import/restore/backup dialogs, and sidebar search.

Phase 3 — overlays and feedback

popover becomes a wrapper over base Popover; modal composes base Dialog and AlertDialog while keeping the Modal API and window.open_modal; notification moves onto Toast/ToastManager (base owns the stack, timers, and motion; coop owns the visual and the placement from theme.notification); tooltip becomes a wrapper over base Tooltip. Root and window_ext keep their public API and host the new layers. No call site changes.

Phase 4 — leaf controls, scroll, and resizable (one module per pull request)

Order: tooltip, avatar, switch, button, scroll/, resizable/. button is the largest skin: the ButtonVariants and ButtonCustomVariant tables, the compact, loading, and caret builders, and the variant names stay as they are, with styling supplied through base's semantic-state styles. scroll/ keeps the ScrollableElement trait name so .vertical_scrollbar(..) call sites keep compiling, and resizable/ becomes a thin re-export of base's identically named API plus a ResizeHandleRenderer for the coop hairline.

Each of these is independently shippable. Acceptance for each: no change outside crates/ui, and the surfaces that use the module are pixel-identical before and after.

Phase 5 — dock, tab, and menu (deliberately later)

Base has a full dock, but its contract is "layout is data, and the application implements the renderer traits", while coop's Panel/PanelView/DockArea/DockItem is an app-specific shell already consumed by crates/workspace and crates/chat_ui. Moving it is a project of its own, and it would also retire tab/ and touch menu/. Keep them local until phases 1–4 have landed, then plan dock separately. Re-basing menu positioning and dismissal on base Popup/Positioner is optional and later still.

Verification

There is no UI test suite to lean on, so each phase gets the same treatment:

• cargo check at the workspace root, plus cargo check -p coop_web --target wasm32-unknown-unknown for the web target.
• Launch the app and walk the surfaces the phase touched. The settings dialog is the densest single smoke surface (Button, GroupBox, Switch, Input, DropdownMenu, PopupMenuItem), followed by the chat panel and the sidebar.
• For phase 4, record before/after screenshots per module.
• Keep the call-site diff at zero for phases 1, 3, and 4; if a call site has to change because base has no equivalent (set_loading is the known candidate), list it in the pull request.

Risks and non-goals

• Snapshot lag. The gpui-pre package is a republished snapshot, so it trails zed main by however long it takes longbridge to cut the next release (a few days). A new GPUI API is therefore unavailable until then. That is the price of not maintaining a fork; the escape hatch — vendoring gpui-base and patching it onto zed's git repository — should stay unused.
• The gpui dependency line is load-bearing. Depending on zed's git gpui alongside gpui-base looks harmless and is not: it puts two GPUI crates in the graph and every window, context, and element crossing between them becomes a type error.
• Two Theme globals. Confine gpui_base::Theme to theme::sync_base and crates/ui internals; application code keeps using theme::ActiveTheme. Avoid importing both Theme types into one file.
• gpui_tokio has to be vendored or dropped (phase 0).
• Non-goals: adopting gpui-component, migrating dock/tab/menu, rewriting the self-contained pieces (icon, kbd, divider, skeleton, group_box, indicator), and changing any color, radius, or spacing value.

Pull request sequence

PR	Content	Touches outside crates/ui
1	Phase 0: move gpui to the gpui-pre package, fix drift	Cargo.toml, possibly crates/state
2	Phase 1: base wiring, sync_base, deletions	none
3	Phase 2: input	none, or the named gaps above
4	Phase 3: popover, modal, notification, tooltip	none
5–10	Phase 4: one leaf module each	none
later	Phase 5: dock, as its own plan	crates/workspace, crates/chat_ui

The end state: the application keeps its design system and its call sites, crates/ui shrinks by roughly half, and the parts that are genuinely hard — text editing, focus and IME, drag-resize arithmetic, overlay lifecycle, accessibility semantics — are maintained upstream instead of in a fork.