# GPUI concept compatibility matrix

Status: M1 evidence ledger, pinned to upstream `zed-industries/zed@d9afb21688e04f89d9e94d96d33eb530aef90886`.

Compatibility means useful behavioral and conceptual correspondence. It does not mean Rust source or binary compatibility. A row may be marked `compatible` only after conformance evidence exists for its stated behavior. `compatible with documented deviation` requires both passing evidence and a linked deviation. `planned` means the contract exists or is scheduled but implementation/conformance evidence is incomplete. `intentionally unsupported` requires a deliberate scope decision and explanation.

The contract links below state gpui.mbt behavior. Some M1 concepts now have a MoonBit implementation and headless tests; those links establish behavior against this project’s contract only. Every concept remains `planned` until an explicit comparison to the pinned upstream revision supports a compatibility claim. Hosted checks now cover initial Ubuntu/Wayland and experimental Windows slices; broader native behavior and production evidence remain incomplete (see [project status](status.md) and the [Windows guide](windows-native.md)).

| Concept | Status | Contract | Upstream reference | Deviation | Evidence |
|---|---|---|---|---|---|
| Application / `App` lifecycle | planned | [App lifecycle](product.md#app-lifecycle) | [GPUI `app.rs` at pinned revision](https://github.com/zed-industries/zed/blob/d9afb21688e04f89d9e94d96d33eb530aef90886/crates/gpui/src/app.rs) | Lifecycle mapping not measured; lifecycle states and failure behavior are gpui.mbt's explicit M1 contract. | Implementation: [core/app.mbt](../core/app.mbt); tests: [core/core_test.mbt](../core/core_test.mbt), [core_model](../testing/core_model/model_test.mbt). Upstream semantic comparison pending. |
| `Entity[T]` identity and state ownership | planned | [Entity identity and lifetime](product.md#entity-identity-and-lifetime) | [GPUI source at pinned revision](https://github.com/zed-industries/zed/tree/d9afb21688e04f89d9e94d96d33eb530aef90886/crates/gpui/src) | Handle representation and stale-handle errors are MoonBit-native; equivalence not measured. | Implementation: [core/entity.mbt](../core/entity.mbt), [core/identity.mbt](../core/identity.mbt); tests: [core_model](../testing/core_model/model_test.mbt). Generic mutable aliases are a documented M1 deviation; upstream comparison pending. |
| `Context[T]` update scope and authority | planned | [Context lifetime and authority](product.md#context-lifetime-and-authority) | [GPUI `app.rs` at pinned revision](https://github.com/zed-industries/zed/blob/d9afb21688e04f89d9e94d96d33eb530aef90886/crates/gpui/src/app.rs) | Runtime token enforces callback extent; API and failure semantics are gpui.mbt-defined. | Implementation: [core/entity.mbt](../core/entity.mbt); tests: [core/core_test.mbt](../core/core_test.mbt), [core_model](../testing/core_model/model_test.mbt). Generic mutable aliases remain caller-managed; upstream comparison pending. |
| Notifications and revisions | planned | [Update, revision, and notification](product.md#update-revision-and-notification) | [GPUI source at pinned revision](https://github.com/zed-industries/zed/tree/d9afb21688e04f89d9e94d96d33eb530aef90886/crates/gpui/src) | Explicit `notify`, one revision per entered callback, and coalesced delivery are the gpui.mbt baseline; upstream equivalence not measured. | Implementation: [core/entity.mbt](../core/entity.mbt); tests: [core/core_test.mbt](../core/core_test.mbt), [core_model](../testing/core_model/model_test.mbt). Upstream notification parity pending. |
| Observation, subscriptions, release | planned | [Observation, subscriptions, and release](product.md#observation-subscriptions-and-release) | [GPUI source at pinned revision](https://github.com/zed-industries/zed/tree/d9afb21688e04f89d9e94d96d33eb530aef90886/crates/gpui/src) | Drop, release, and queued-callback semantics are explicitly fixed here; upstream equivalence not measured. | Implementation: [core/entity.mbt](../core/entity.mbt); tests: [core/core_test.mbt](../core/core_test.mbt), [core_model](../testing/core_model/model_test.mbt). MoonBit uses explicit `unsubscribe` rather than deterministic drop; upstream comparison pending. |
| `Render` and `IntoElement` | planned | [GPUI-facing surface](product.md#gpui-facing-surface-and-current-boundaries); [element layer](architecture.md#layer-responsibilities-and-allowed-edges) | [GPUI source at pinned revision](https://github.com/zed-industries/zed/tree/d9afb21688e04f89d9e94d96d33eb530aef90886/crates/gpui/src) | MoonBit's open traits return the framework's declarative `Element`; this is not Rust source compatibility. The API currently uses an explicit `Element::root` and flex-item children. | Implementation: [element/lifecycle.mbt](../element/lifecycle.mbt); a custom `Render` implementation and `Element`'s `IntoElement` identity conversion compile/run in [element/lifecycle_test.mbt](../element/lifecycle_test.mbt). Upstream API comparison remains pending. |
| Element request-layout / prepaint / paint lifecycle | planned | [Scene and renderer boundary](architecture.md#scene-and-renderer-boundary); [initial layout boundary](architecture.md#initial-layout-boundary) | [GPUI source at pinned revision](https://github.com/zed-industries/zed/tree/d9afb21688e04f89d9e94d96d33eb530aef90886/crates/gpui/src) | The headless lifecycle is typed as `request_layout → prepaint → paint`: a definite viewport resolves recursive flex boxes, prepaint builds a hit-test-ready tree, and paint emits background quads into a portable scene. `paint_snapshot` freezes those quads into the current SceneSnapshot v1 subset. Bounded text items can be constructed separately in a snapshot; this does not add an element text widget. Nesting is limited to 64; invalidation, general text/path/image painting, and renderer submission remain pending. | Implementation: [element/lifecycle.mbt](../element/lifecycle.mbt), [element/element.mbt](../element/element.mbt), [scene/scene.mbt](../scene/scene.mbt), [scene/snapshot.mbt](../scene/snapshot.mbt); lifecycle and depth-bound cases: [element/lifecycle_test.mbt](../element/lifecycle_test.mbt). Upstream lifecycle comparison remains pending. |
| Window lifecycle and focus | planned | [Platform API layer](architecture.md#layer-responsibilities-and-allowed-edges); [platform tiers](../README.md#platform-support) | [GPUI `window.rs` at pinned revision](https://github.com/zed-industries/zed/blob/d9afb21688e04f89d9e94d96d33eb530aef90886/crates/gpui/src/window.rs) | Element-local focusability and focus state are defined headlessly; window focus transfer and platform behavior await M4. No platform is currently supported. | Headless element focus tests: [element/element_test.mbt](../element/element_test.mbt). Window lifecycle/native focus E2E remains pending. |
| Input/event dispatch and propagation | planned | [Element layer](architecture.md#layer-responsibilities-and-allowed-edges); [platform API layer](architecture.md#layer-responsibilities-and-allowed-edges) | [GPUI source at pinned revision](https://github.com/zed-industries/zed/tree/d9afb21688e04f89d9e94d96d33eb530aef90886/crates/gpui/src) | Event values are MoonBit-native. M2 now defines deterministic reverse-paint hit testing and root-to-target capture / target-to-root bubble route metadata; callback dispatch and stop-propagation remain pending. | Foundation: [element/element.mbt](../element/element.mbt); ordering/hit-test tests: [element/element_test.mbt](../element/element_test.mbt). Upstream and stop-propagation conformance remain pending. |
| Actions and key bindings | planned | [Platform API layer](architecture.md#layer-responsibilities-and-allowed-edges) | [GPUI source at pinned revision](https://github.com/zed-industries/zed/tree/d9afb21688e04f89d9e94d96d33eb530aef90886/crates/gpui/src) | Serialization and keymap semantics await M2/M4; no Rust macro compatibility promised. | Pending dispatch model and native keyboard tests. |
| Scroll state and drag gestures | planned | [Weekboard interaction scope](browser-demo.md#weekboard-increment--2026-10-05) | [GPUI source at pinned revision](https://github.com/zed-industries/zed/tree/d9afb21688e04f89d9e94d96d33eb530aef90886/crates/gpui/src) | Immutable clamped scroll geometry and pointer drag threshold/commit/cancel transitions are gpui.mbt contracts. Weekboard combines them with clipped card hit testing and keyboard reveal. Inertia, general drag/drop payloads, within-lane reorder, and pinned-upstream equivalence are not claimed. | Implementation/tests: [scroll](../element/scroll.mbt), [scroll tests](../element/scroll_test.mbt), [drag](../element/drag.mbt), [drag tests](../element/drag_test.mbt), [task-board tests](../examples/task_board/task_board_wbtest.mbt), [Chromium smoke](../tests/browser/board.mjs). |
| Styling and layout | planned | [Initial layout boundary](architecture.md#initial-layout-boundary) | [GPUI source at pinned revision](https://github.com/zed-industries/zed/tree/d9afb21688e04f89d9e94d96d33eb530aef90886/crates/gpui/src) | First layout contract is the bounded flex subset; unsupported style features are named in the contract. Recursive layout uses a definite root viewport and parent-assigned child bounds. Auto container dimensions measure descendant bases along the flow axis and maximum child size along the cross axis, then add gaps/insets; percentages on a measured auto axis fail as indefinite. Nesting is limited to 64. Flat-tree scans and repeated nested intrinsic measurement have quadratic worst-case cost in node count; the depth bound protects stack usage only. | Foundation: [layout/layout.mbt](../layout/layout.mbt), [layout/tree.mbt](../layout/tree.mbt), [element/lifecycle.mbt](../element/lifecycle.mbt); deterministic cases: [layout/layout_test.mbt](../layout/layout_test.mbt), [layout/tree_test.mbt](../layout/tree_test.mbt), [element/lifecycle_test.mbt](../element/lifecycle_test.mbt); seeded properties: [layout/layout_pbt_test.mbt](../layout/layout_pbt_test.mbt), [layout/tree_pbt_test.mbt](../layout/tree_pbt_test.mbt). Broader style coverage and pinned-upstream compatibility fixtures remain pending. |
| Scene primitives | planned | [Scene and renderer boundary](architecture.md#scene-and-renderer-boundary) | [GPUI source at pinned revision](https://github.com/zed-industries/zed/tree/d9afb21688e04f89d9e94d96d33eb530aef90886/crates/gpui/src) | Ordered commands still cover background quads and rectangle clip push/pop only. SceneSnapshot v1 carries transforms, opacity, resource/clip-chain/item tables, canonical serialization, and bounded plain-text items. Existing quad JSON is unchanged; Canvas 2D presents text, while Ubuntu and Windows draw bounded grayscale subsets through PangoFT2/GLES and copied DirectWrite/D3D11 masks. macOS measures and draws a bounded single-line grayscale subset through CoreText. Paths, images, border/corner data, path clips, and broader renderer resources remain pending. | Foundation: [scene/scene.mbt](../scene/scene.mbt), [scene/snapshot.mbt](../scene/snapshot.mbt), [scene tests](../scene/scene_test.mbt), [snapshot tests](../scene/snapshot_test.mbt), [text tests](../scene/snapshot_text_test.mbt), [Canvas tests](../tests/browser/canvas-renderer.test.mjs), [macOS native guide](macos-native.md), [Linux text guide](linux-text.md#ubuntu-grayscale-scene-text), [Windows guide](windows-native.md), and deterministic element-to-scene tests in [element/element_test.mbt](../element/element_test.mbt). Upstream comparison and full-schema snapshots remain pending. |
| Text shaping and text-system contracts | planned | [Text and IME design](platform.md#text-and-ime); [bounded browser text](browser-demo.md#bounded-text-and-visible-card-semantics) | [GPUI source at pinned revision](https://github.com/zed-industries/zed/tree/d9afb21688e04f89d9e94d96d33eb530aef90886/crates/gpui/src) | Merged PR27 adds copied measurement/caret/hit geometry and Ubuntu PangoFT2; Ubuntu and Windows additionally draw bounded grayscale masks for existing text items, and macOS measures/draws a bounded CoreText system-sans subset. Windows' copied DirectWrite geometry supports a focused experimental single-line field. Its private default-off IMM32 session ingress remains experimental, and real Japanese IME behavior is unqualified. Color glyphs reject the frame; Canvas uses system sans. No cross-platform editor contract or support-tier promotion is claimed. | Foundation and boundaries: [text_layout model](../text_layout/model.mbt), [macOS native guide](macos-native.md), [Linux text guide](linux-text.md), [Ubuntu guide](ubuntu.md), [Windows guide](windows-native.md), [text tests](../scene/snapshot_text_test.mbt), [Canvas tests](../tests/browser/canvas-renderer.test.mjs). Upstream semantic comparison and real-IME qualification remain pending. |
| Async tasks and App lifecycle | planned | [Async and application scheduling](architecture.md#async-and-application-scheduling); [App lifecycle](product.md#app-lifecycle) | [GPUI `app.rs` at pinned revision](https://github.com/zed-industries/zed/blob/d9afb21688e04f89d9e94d96d33eb530aef90886/crates/gpui/src/app.rs) | Scheduler semantics are defined independently; no Rust async runtime or API compatibility. | Implementation: [core/scheduler.mbt](../core/scheduler.mbt); tests: [core/core_test.mbt](../core/core_test.mbt), [core_model](../testing/core_model/model_test.mbt). Synchronous foreground tasks and manual time are a MoonBit-native subset; upstream async parity pending. |
| Clipboard and cursor | planned | [Platform API layer](architecture.md#layer-responsibilities-and-allowed-edges) | [GPUI source at pinned revision](https://github.com/zed-industries/zed/tree/d9afb21688e04f89d9e94d96d33eb530aef90886/crates/gpui/src) | Backend-specific behavior and error mapping await platform conformance. | Pending headless contract and per-platform tests. |
| Menus and display information | planned | [Platform API layer](architecture.md#layer-responsibilities-and-allowed-edges) | [GPUI source at pinned revision](https://github.com/zed-industries/zed/tree/d9afb21688e04f89d9e94d96d33eb530aef90886/crates/gpui/src) | Native capability differences will be documented per backend. | Pending backend contract and native tests. |
| Accessibility | planned | [Accessibility design](platform.md#accessibility); [browser projection](browser-demo.md#bounded-text-and-visible-card-semantics) | [GPUI source at pinned revision](https://github.com/zed-industries/zed/tree/d9afb21688e04f89d9e94d96d33eb530aef90886/crates/gpui/src) | Weekboard dynamically projects visible, clipped cards into DOM buttons keyed by stable task IDs, with focus/action reconciliation. This is an application DTO adapter; the shared generational semantic tree, native adapters, and screen-reader qualification remain pending. | [Projection](../examples/browser/site/canvas-accessibility.js), [DOM contract tests](../tests/browser/canvas-accessibility.test.mjs), [Weekboard smoke](../tests/browser/board.mjs). Shared semantic-tree and native accessibility checks remain pending. |
| IME and text input | planned | [Text and IME design](platform.md#text-and-ime); [committed-text ingress](browser-demo.md#committed-text-ingress) | [GPUI `window.rs` at pinned revision](https://github.com/zed-industries/zed/blob/d9afb21688e04f89d9e94d96d33eb530aef90886/crates/gpui/src/window.rs) | The interaction lab has opt-in committed inserts with composition deduplication/cancellation; Windows adds a private, default-off bounded IMM32 text-session ingress for its experimental single-line field. Full cross-platform `textInputIme` remains unavailable; Weekboard's HTML fields do not implement framework selection or composition. The Windows path does not promote a support tier, and Japanese IME qualification remains open. | [Text bridge tests](../tests/browser/text-input.test.mjs), [Chromium committed-input cases](../tests/browser/text-input.mjs), [Windows session and field tests](windows-native.md). Real Japanese IME and full editor E2E remain pending. |

## Update rule

When behavior or implementation changes, update the affected row in the same change as its contract and evidence links. Evidence should link to the relevant implementation and named test/CI job, and identify the tested upstream revision. A row stays `planned` if any required platform or lifecycle evidence is missing. The overall project must not claim global GPUI compatibility while any required production concept remains unclassified.