GPUI 1.27.0 integration and API review
Integrated on codex/sync-gpui-1.27.0 from local commit 8ed97a3, using upstream
f98d4e26ca850515c1682ae4cd6e2b8277dae6e7. Implementation is prepared for review;
public API approval remains pending; the selected crate versions and exact pins
are applied in this branch. No release or merge has been performed.
Breaking changes to XGPUI API
This migration changes the API exposed by XGPUI's core and Apple backend crates. Applications upgrading from the current XGPUI packages should review the changes below even if they do not use an optional extension. The table distinguishes upstream changes carried into XGPUI from adaptations to our GPUI interfaces.
| Origin | Breaking change in XGPUI | Application migration |
|---|---|---|
| Upstream GPUI | Keystroke parsing, display, formatting and secondary modifiers use the runtime host OS. Static constructors require static strings; direct keystroke Display implementations are removed. | Use KeyBinding::load or Keystroke::parse_with_os for dynamic input; pass the host OS or App context when formatting and resolving modifiers. |
| Upstream GPUI | Window::text_system() returns an Rc handle; hash-based layout methods are removed. | Keep window text caches local to their window thread and use ordinary shape_line and layout_line calls. |
| Upstream GPUI | External Platform implementations must provide platform_info. | Return the host OS and native/web delivery target. |
| Upstream Apple changes adapted to XGPUI | Renderer constructors now return Result; our renderer factory drops its unused native window, view and bounds arguments. | Propagate initialization errors and remove the unused arguments. XGPUI retains its existing color-mode negotiation and typed resource interfaces. |
| Upstream Apple changes | The public thermal module is replaced by process_info; macOS 12.0 is the minimum. | Update observer imports and retain the returned observer owner; update deployment requirements. |
XGPUI's own GPUI changes provide the core integration points used by our font, color, drawing, media and paragraph extensions. Those maintained differences, including earlier breaking changes to font and style structs, are described in GPUI API changes. The detailed review below records each API change in this sync, its origin, compatibility impact and application migration. Final API approval remains pending.
Upstream release reference
The upstream GPUI release tracker for 1.27.0 records the Zed GPUI changes from 1.26.2 to 1.27.0, with links to the original commits and pull requests. XGPUI's integration notes below describe how those changes are combined with our maintained GPUI modifications.
Implementation
- Adopted typed upstream AppKit application, window, event, menu, keyboard,
display, clipboard and appearance bindings; removed private
native_appkit. - Retained XGPUI Metal resources, custom draw, wide SDR, media surfaces, caches, headless capture, and validation interfaces. Ported fallible device, library, pipeline, buffer, command queue and CoreVideo-cache initialization. Adopted validated atlas uploads while preserving our scoped texture ownership wrapper and eviction/lifetime regression tests.
- Preserved local Services submenu registration, nullable pasteboard handling, Objective-C protocol/signature audits, optional text-range output handling, and attributed-string autorelease behavior. These fixes still apply to the upstream typed implementation.
- Adopted power/platform introspection, host-aware key semantics, macOS atomic credential insertion, deferred native-close handling, list scroll anchoring, subscription activation changes, fallback caching and OHOS target exclusion.
- Replaced window text locks with RefCell state and Rc ownership. Adapted our paragraph cache, retained-element reuse and generation invalidation; retained font axes/features/fallback controls and missing-glyph reporting.
- Fixed scramble typography to re-shape its source font request when CoreText returns a size-specific face absent from reverse lookup. Replacements still require an exact native face match, preserving fallback and emoji behavior.
- Supporting crates and provenance now reference 1.27.0. Existing XGPUI package versions follow the selected release table below. Final API review remains pending. macOS now requires 12.0; Metal shader compilation uses the same minimum.
Selected crate versions
Baseline: release-2026-11-04-b35309ab9316. The published column comes from that release’s verified crate table and matches crates.io version metadata checked on November 6, 2026. Before review is the version already prepared in this development cycle before the version review. The 15 selected new versions remain unpublished; color and macros retain their published versions. The selected versions are applied to manifests, exact dependency requirements and release metadata.
Version decisions are measured from the last published API. Multiple breaking changes in an unpublished major can ship together: core stays at 3.0.0 rather than advancing to 4.0.0 merely because another change landed during development. The existing repository policy does not automatically propagate dependency major bumps; dependent crates with retained public signatures use their already prepared patch/minor versions, and consumers upgrade the exact-pinned stack together.
| Crate | November 4 published | Before review | Selected release | Review and rationale |
|---|---|---|---|---|
xgpui | 2.0.1 | 3.0.0 | 3.0.0 | Keep the prepared major: font/style fields plus this sync’s keystroke, text-cache and platform contract breaks fit the same unpublished 3.0.0 release. |
xgpui-apple | 3.0.1 | 3.1.0 | 4.0.0 | Raise the prepared minor to a major: renderer constructors return Result, the factory drops arguments, and thermal moves to process_info. Includes the prepared font capabilities. |
xgpui-macos | 3.0.1 | 3.0.2 | 4.0.0 | Raise the prepared patch to a major: its public test/bench-support MetalHeadlessRenderer re-export now has a fallible constructor. Also adopts typed AppKit and macOS 12 minimum. |
xgpui-wgpu | 2.0.1 | 2.1.0 | 2.1.0 | Keep the prepared minor: Cosmic font inspection, Linux DMA-BUF completion guards, and upstream text/layout compatibility fixes. |
xgpui-windows | 2.0.1 | 2.1.0 | 2.1.0 | Keep the prepared minor: font axes/introspection, corrected fallback fixture, and upstream DirectWrite/input/power integration; no further changed public constructor signature identified. |
xgpui-parley | 0.3.1 | 0.4.0 | 0.4.0 | Keep the prepared pre-1.0 minor: font axes/introspection and VariationPreview. Existing paragraph APIs are retained through the window-cache migration. |
xgpui-linux | 2.0.1 | 2.0.2 | 2.0.2 | Keep the prepared patch: matching core/WGPU pins, platform identity and power-mode backend implementation. No new standalone Linux public API identified. |
xgpui-platform | 2.0.1 | 2.0.2 | 2.0.2 | Keep the prepared patch: matching backend pins, propagate fallible headless creation through the existing Result API, and OHOS selection guards. |
xgpui-web | 2.0.1 | 2.0.2 | 2.0.2 | Keep the prepared patch: matching core/WGPU pins, runtime host identity for correct key semantics, and existing unsupported-axis handling. |
xgpui-ios | 1.26.3 | 1.26.4 | 1.26.4 | Keep the prepared patch: matching core/Apple pins and upstream UIKit initialization changes. Its downstream version need not match upstream 1.27.0. |
xgpui-shader | 0.4.1 | 0.4.2 | 0.4.2 | Keep the prepared patch: matching core/Apple pins, fallible headless call sites and scramble-font recovery; the shader extension’s own public signatures are retained. |
xgpui-media | 0.5.1 | 0.5.2 | 0.5.2 | Keep the prepared patch: matching core/backend/shader/helper pins and headless initialization call sites; media public signatures are retained. |
xgpui-gamut | 0.3.1 | 0.3.2 | 0.3.2 | Keep the prepared patch: matching dependency pins and fallible test-renderer construction; gamut public signatures are retained. |
xgpui-canvas | 0.3.1 | 0.3.2 | 0.3.2 | Keep the prepared patch: matching core/shader pins and packaged beta documentation; CPU-only canvas APIs are retained. |
xgpui-svg | 0.3.1 | 0.3.2 | 0.3.2 | Keep the prepared patch: matching core dependency requirement; SVG public signatures are retained. |
xgpui-color | 0.3.0 | 0.3.0 | 0.3.0 | Unchanged packaged source and dependency requirements since the release; reuse published 0.3.0. |
xgpui-macros | 1.0.1 | 1.0.1 | 1.0.1 | Unchanged package since the release; reuse published 1.0.1. |
The version review revised two prepared version numbers: xgpui-apple 3.1.0 → 4.0.0
and xgpui-macos 3.0.2 → 4.0.0. Their exact requirements are updated in normal,
optional, target-specific and development dependencies, including the registry
consumer fixture. Release metadata, tracked lockfiles and version documentation
are refreshed.
Version selection does not approve the pending public API changes or authorize
publication.
xgpui-shell is a separate development-cycle addition at 0.1.0 with
publish = false, intentionally outside the 17-crate release map. Keep it
unpublished until its public interface is separately reviewed. The lab package
also remains unpublished.
Concrete public API changes
Each row is an individual review item. Origin identifies upstream GPUI changes,
upstream Apple changes, and adaptations to XGPUI’s existing backend API.
No serialized struct shape changes were
identified. Keystroke serialization here means emitted keystroke strings; host
OS changes their modifier spelling and alias interpretation. Platform identity
and PowerMode types do not add serde implementations. Existing package exports,
including ctor, spring types, benchmark macros and typed Metal resource aliases,
are retained. MetalRenderer::layer already used our CAMetalLayer alias and has
no new source signature change.
| Implemented API change | Purpose and compatibility impact | Migration | Origin |
|---|---|---|---|
PlatformInfo { os, target } | Add runtime host identity independent of delivery target; additive type and fields. | Read App::platform_info(). | Upstream GPUI |
OperatingSystem | Add host OS enum, including unknown hosts. | Match with appropriate handling of all variants. | Upstream GPUI |
PlatformTarget | Distinguish native and web delivery. | Avoid inferring host OS from build target. | Upstream GPUI |
PlatformInfo::is_mac | Add convenience predicate. | Optional use. | Upstream GPUI |
Platform::platform_info | Required trait method; breaks external platform implementers. | Implement host and delivery identity in every platform. | Upstream GPUI |
App::platform_info | Expose platform identity to clients. | Replace compile-time assumptions where host semantics matter. | Upstream GPUI |
PowerMode | Add Unknown, LowPower, Balanced, HighPower. | Handle Unknown; macOS reports LowPower or Unknown. | Upstream GPUI |
Platform::power_mode | Defaulted trait method; additive. | Override when supported. | Upstream GPUI |
Platform::on_power_mode_change | Defaulted callback registration; additive. | Notify through safe deferred delivery. | Upstream GPUI |
App::power_mode | Read active energy preference. | Optional use. | Upstream GPUI |
App::write_credentials_if_not_exists | macOS-only atomic write, returns Task<Result<bool>>. | Handle false as existing server/account; do not emulate with read then write. | Upstream GPUI |
Platform::write_credentials_if_not_exists | macOS-only defaulted hook; unsupported platforms return an error. | Override with atomic insertion. | Upstream GPUI |
KeyBinding::new | Keystroke argument becomes &'static str; source breaking. | Use KeyBinding::load for dynamic input or secondary-; static bindings use explicit modifier literals. | Upstream GPUI |
Keystroke::parse | Static input only; secondary- needs OS-aware parsing. | Use literals or parse_with_os for dynamic input. | Upstream GPUI |
Keystroke::parse_with_os | Add dynamic parsing with explicit host OS. | Pass cx.platform_info().os. | Upstream GPUI |
Keystroke::unparse | Require OS argument; emitted aliases depend on host conventions. | Pass intended target OS when persisting strings. | Upstream GPUI |
KeybindingKeystroke::unparse | Same OS-aware string change. | Pass intended target OS. | Upstream GPUI |
Keystroke::display | New explicit OS-aware display adapter. | Format the returned adapter. | Upstream GPUI |
KeybindingKeystroke::display | Same display adapter for bindings. | Format the returned adapter. | Upstream GPUI |
KeystrokeDisplay | New public Display wrapper. | Use instead of direct keystroke formatting. | Upstream GPUI |
Display for Keystroke removed | Direct formatting and to_string() stop compiling. | Use .display(os) or .unparse(os). | Upstream GPUI |
Display for KeybindingKeystroke removed | Same source break. | Use .display(os) or .unparse(os). | Upstream GPUI |
Modifiers::secondary | Add &App argument for host semantics. | Supply App context. | Upstream GPUI |
Modifiers::secondary_key | Add &App argument. | Supply App context. | Upstream GPUI |
KeyContext::new_with_defaults | Add OperatingSystem argument. | Supply runtime host OS. | Upstream GPUI |
Window::keystroke_text_for | Add &App argument. | Supply App context. | Upstream GPUI |
TestAppContext::set_platform_info | Add host-identity test override. | Test native and browser host semantics. | Upstream GPUI |
TestWindow::simulate_close | Add native-close simulation. | Use for reentrancy regression tests. | Upstream GPUI |
Window::text_system | Return &Rc<WindowTextSystem>; loses Arc ownership and thread sharing. | Change explicit Arc annotations/clones; keep window-local access on its thread. | Upstream GPUI |
WindowTextSystem::shape_line_by_hash removed | Remove unused hash cache API; source breaking. | Use shape_line. | Upstream GPUI |
WindowTextSystem::layout_line_by_hash removed | Same cache removal. | Use layout_line. | Upstream GPUI |
WindowTextSystem::try_layout_line_by_hash removed | Remove lookup-only hash API. | Request layout through the regular API. | Upstream GPUI |
ListState::set_item_measurement_readiness | Add callback controlling when measurements become final. | Optional callback; validate scroll anchoring behavior. | Upstream GPUI |
gpui_apple::main_thread_marker | Add cached main-thread identity helper. | Use typed marker where native APIs require it. | Upstream Apple |
gpui_apple::keychain::write_credentials_if_not_exists | Add atomic insertion returning Result<bool, KeychainError>. | Handle duplicate result and errors separately. | Upstream Apple |
gpui_apple::thermal removed | Replace public thermal module. | Move callers to process_info. | Upstream Apple |
thermal::ThermalObserver removed | Replace observer type and its constructor. | Use observe_thermal_state and retain returned owner. | Upstream Apple |
process_info::thermal_state | Move thermal query into new public module. | Update module path. | Upstream Apple |
process_info::power_mode | Add power query. | Handle Unknown. | Upstream Apple |
process_info::observe_thermal_state | Add deferred thermal observation factory. | Retain observer; drop cancels delivery. | Upstream Apple |
process_info::observe_power_mode | Add deferred power observation factory. | Retain observer. | Upstream Apple |
process_info::ProcessInfoObserver | New shared observer owner. | Replace ThermalObserver ownership. | Upstream Apple |
metal_renderer::new_renderer | Factory becomes safe, returns Result<Renderer>, and drops unused native window, view, and bounds arguments. | Remove unused arguments and the unsafe wrapper; propagate errors. The existing Display P3 preference still uses XGPUI color negotiation with SDR fallback. | Upstream Apple, adapted to XGPUI |
MetalRenderer::new | Constructor returns Result<Self>; XGPUI retains its existing two arguments and separate color-mode negotiation. | Use ? or explicit error handling; existing color-mode calls remain valid. | Upstream Apple, adapted to XGPUI |
MetalRenderer::new_headless | Return Result<Self>. | Propagate initialization failures. | Upstream Apple |
MetalHeadlessRenderer::new | Return Result<Self>; test-support re-exports also affected. | Update tests and extension callers. | Upstream Apple |
MetalRenderer::from_layer | Return Result<Self> for platform-owned layer initialization. | Propagate errors; the iOS window constructor now does so. | Upstream Apple |
KeyBinding::load behavior | Existing signature now resolves secondary- against runtime host OS. | Use for dynamic keymaps; serialized alias interpretation follows the intended host. | Upstream GPUI |
WindowTextSystem auto traits | Window-local interior mutability removes Sync; Rc handles are neither Send nor Sync. Shared TextSystem remains Arc-based. | Do not send window text caches across threads. | Upstream GPUI |
The removed hash methods on the crate-private LineLayoutCache, private pasteboard UTType changes, and private subscriber-set changes are not downstream public APIs. Benchmark macros moved into a private module while retaining their exported names and availability. The shared Apple source mirror repeats core changes and is not a separate public API family.
XGPUI backend adaptations
The renderer factory drops its unused native window, view and bounds arguments,
while MetalRenderer::new keeps XGPUI's existing two arguments and separate color
negotiation. Both adopt upstream's fallible initialization. These changes adapt
existing Apple backend entry points used to create platform windows; an extension
cannot change their signatures or initialization error handling.
XGPUI's existing font, color, drawing, media and paragraph integration points are preserved. Their core-versus-extension design belongs in the maintained GPUI API changes guide. The upstream APIs in this migration retain their upstream role and are reviewed for compatibility.
Verification
All 16 suites in the macOS scripts/test_all.sh matrix passed across the full
run and targeted reruns of release-sync, shader and labs after fixes. This
includes the 426-test core suite, extension rendering tests, benchmark checks,
native lab tests, CoreText tests, and iOS simulator test compilation.
Additional checks passed:
- All shared Apple backend tests: 66 passed, one ignored GPU diagnostic.
- macOS native backend tests: 16 passed, including protocol encoding audits, nullable pasteboard handling, optional text-range outputs and layer cleanup.
- Native root
cargo check --locked --offline --config .cargo/validation.toml. - Windows backend test compilation for
x86_64-pc-windows-msvc, using the installed Homebrew LLVM resource compiler. This does not execute Windows tests. - Browser application compilation for
wasm32-unknown-unknown, using the lab'sextensions-webbinary with featureweband its explicit single-threaded wgpu contract. The bare web crate without that application contract is not a supported single-threaded build configuration. - Selected-version audit: all 90 internal dependency requirements match the release map; all 200 selected-version entries across tracked lockfiles match.
- Native workspace and every lab target compile with Apple/macOS 4.0.0.
- The updated native consumer fixture compiles with explicit local overrides for the unpublished release family. Registry-only verification requires publication.
- Release normalization, generated build-manifest consistency and all ten release-sync tests pass.
- Regenerated documentation inventory and its JavaScript verifier.
Linux and OHOS native execution, browser interaction, iOS interactive execution, and physical-display color acceptance were not run in this macOS session. Existing ignored GPU diagnostics remain ignored; test success does not claim these additional platform acceptance results.
Approval required
The repository's AGENTS.md requires: “Complete authorized implementation and verification, then present the concrete API changes individually for user review before finalizing or releasing them.” The items above are implemented for that review; implementation authorization does not approve their final public API.
Labs most affected by this sync
For manual regression testing on macOS, use the following order. This ranks exposure to the changed code; automated rendering tests already pass.
| Order | Lab | Why it is affected and what to check |
|---|---|---|
| 1 | just lab-text | Most direct exposure: layout caches, font fallback, paragraph reuse, native text input and shortcuts. Compare native and Parley; test scrolling, axes, selection, copy/paste and IME. |
| 2 | just lab-shader --example typography | Text shaping alongside custom Metal drawing. The sync exposed a scramble-text regression here, now fixed. Check selection, scramble, shadows and wide output. |
| 3 | just lab-gamut | Our color negotiation against the replaced AppKit window/display bindings. Check SDR/P3 switching, resize and moving between displays. |
| 4 | just lab-media | Renderer initialization, atlas uploads, texture ownership and CoreVideo surfaces. Try tiled images, float images and --video. |
| 5 | just lab-color | Wide-color presentation, compositing and headless capture. Check the photo and chromaticity views. |
| 6 | just lab-paint | Broad coverage of retained Metal rendering: gradients, paths, masks and layers. |
| 7 | just lab-canvas | Mostly shared-backend exposure. Check pan/zoom, clipping, resize and sustained interaction. |
| 8 | just lab-svg | Mostly shared atlas and renderer exposure. Check progressive loading, scaling and eviction/reloading. |
Across every lab, test window closing, fullscreen, display changes, and animation with Low Power Mode enabled. These exercise the backend changes regardless of the lab's content.