GPUI
Build native desktop surfaces with GPUI's views, entities, elements, and platform crates. GPUI is pre-1.0; APIs and platform support can change between revisions.
For product and visual design decisions, read ui-craftsmanship and keep shared UX guidance
there. Treat Sjel's Mac and iPhone surfaces as one product with platform-specific interaction
patterns. GPUI draws only the Mac: the iPhone is drawn by NSH. Read "Native chrome and iOS" in
references/platform-and-build.md before any iOS work.
Workflow
- Locate the app and pin. Read its
Cargo.tomland lockfile. For Sjel, the desktop app isapps/gpui; it has its own Cargo workspace and lockfile. Runpython3 scripts/show_revision.py <Cargo.toml>from this skill's directory to report direct Zed pins or the locked GPUI Kit release and its cached publication revision. The helper requires Python 3.11+; do not assumemainmatches the app's API. - Load only the relevant reference. Read kit-components.md for GPUI Kit controls, ownership and recipes; kit-testing.md for headless UI interaction coverage; views-and-events.md for GPUI structure and input; async-and-data.md for state updates and I/O; or platform-and-build.md for OS features and verification.
- Follow the resolved source. For GPUI Kit, use the helper's release-specific source and documentation links. Inspect the selected renderer and component re-exports before borrowing lower-level GPUI examples. For direct Zed dependencies, use that revision's
crates/gpuiandcrates/gpui_platform. Upstreammainand website docs are navigation only. Do not update dependency pins as part of an unrelated UI change. - Keep the app boundary clear. In Sjel, use existing capability APIs or reviewed local interfaces. Do not give the desktop UI direct access to capability databases or copy private overlay values into source.
- Verify the smallest affected target, and do not take the user's focus. Before building in Sjel, run
tools/toolchain-check --workflow build. Then runcargo check --manifest-path .... Do not test by launching the app in the foreground, by opening asjel://link, or by sending keys to its window: the user is working on the same Mac. Use the focus-free checks inreferences/platform-and-build.md(Local verification).
Error handling
- If the pinned source link is unavailable locally, inspect the Git revision from
Cargo.lock; do not silently substitute upstreammain. - If a GPUI async callback fails to compile, inspect the executor and context APIs at the pinned revision before changing ownership or adding another runtime.
- If a network client panics about a missing Tokio runtime, keep that I/O on an executor/runtime that owns its timers. GPUI's integrated executor does not automatically provide Tokio's runtime context.
- If a platform build fails, check the matching
gpui_platformfeature and OS toolchain inreferences/platform-and-build.md.
Change scope
Keep rendering pure and fast. Move blocking I/O off the UI thread, return results into GPUI state, and notify the entity so the view renders again. Preserve the current dependency pin until a deliberate upgrade is reviewed against the local app.