Positioned elements paint in tree order; no CSS stacking order or zIndex

[Ernxst]

Problem

Found in the consuming app on 0.16.0-fork.1. Positioned elements paint in tree order, and zIndex is not supported, so a positioned element can't be placed early in the tree without the content after it painting over it. Browsers apply CSS stacking order instead: positioned descendants paint above in-flow, non-positioned content regardless of source order, and z-index orders positioned elements among themselves.

In the app this blocks an accessibility fix. The dock is an absolutely positioned layer at the bottom of the window. To make it the first thing Tab reaches, it has to come before <main> in the tree. On the web that changes nothing visually. In GPU-IX the opaque <main> then paints over the dock and it disappears.

Minimal repro, a 200×100 root with position: relative, captured with renderer.captureScreenshot():

const overlay = <div style={{ position: "absolute", left: 20, top: 20, width: 100, height: 50, background: "#ff0000" }} />;
const page = <div style={{ width: 200, height: 100, background: "#0000ff" }} />;
// overlay first: [overlay, page]   overlay last: [page, overlay]

Tree order	GPU-IX	Chromium
overlay, then page	all blue: overlay hidden	red overlay over blue
page, then overlay	red overlay over blue	red overlay over blue

zIndex is not a StyleDesc key, and at runtime it is rejected: property "zIndex" rejected value 1: unsupported style property, with the rest of the style applied.

Fix

1. Paint in CSS stacking order: within a stacking context, in-flow non-positioned content first, then positioned descendants with z-index: auto / 0 in tree order, then positive z-index in ascending order; negative z-index below in-flow content.
2. Support zIndex on positioned elements, creating a stacking context as CSS does. opacity < 1 and transform should create stacking contexts too, if they don't already.
3. Hit-testing and pointer delivery follow the same order as painting, so a positioned overlay that paints on top also receives the click.

Done means

• In the repro, "overlay, then page" shows the red overlay, matching Chromium.
• zIndex is typed on StyleDesc, accepted without a diagnostic, and orders sibling positioned elements, including a negative value painting below in-flow content.
• Pointer events reach the topmost painted element in both orders.

🤖 Generated with Claude Code

[Ernxst]

Parking this with the design worked out, so it can be picked up without redoing the investigation.

Rejected: reorder a parent's children for paint

Sorting a Div's children into stacking order for prepaint and paint (and repairing Tab order afterwards) breaks GPUI's assumption that traversal order is document order:

• The AccessKit tree is built in prepaint encounter order (zed/crates/gpui/src/window/a11y.rs, element.rs), so accessibility siblings would follow paint order.
• Cached views replay exact tab_stops.insertion_history slices (view.rs, window.rs reuse_paint), so a post-paint tab-order repair points cached ranges at the wrong siblings. Deferred popovers insert their tab stops outside the originating child's range.
• Text selection and copy index a registry that relies on paint order being document order (packages/native/src/text/selection.rs, text/paint.rs).
• Capture and bubble listeners dispatch in paint-registration order, including the outside-click handling used for closing menus.
• It cannot let a positioned element escape a non-positioned parent, which popovers and cards inside a <main> need.

Invariant

zIndex never changes traversal. Request-layout, prepaint and paint callbacks, AccessKit children, listener registration, tab-stop history, selectable-text registration and copy order all stay in tree order. Only two things follow CSS stacking order: the order the scene draws primitives in, and hit testing (the same order reversed, keeping clip masks and BlockMouse). Ties break by source order, then insertion order. The first-in-tree absolute dock stays first for Tab, accessibility and selection, but paints and receives clicks above a later in-flow <main>.

Model: stacking keys on primitives and hitboxes

Feasible in this GPUI with a CPU-side ordering pass and no renderer or shader changes. Metal, WGPU, DirectX and the Wasm build all draw scene.batches() in order.

• Scene: keep paint_operations in traversal order, because cached ranges index it. Record a stacking-key handle and an insertion ordinal per operation. When any key is active, Scene::finish sorts paint units by key, reruns them through a fresh BoundsTree and writes back DrawOrder. Batching is unchanged.
• Hit testing: each hitbox carries a key and ordinal. A separate index sorted by (key, insertion) is walked backwards, finalized after prepaint and before the first hit test. Frame::cursor_style and window-control hit testing use the same rank.
• Caches: keys in cached ranges are relative to the cached subtree and are rebased onto the current context in reuse_prepaint and Scene::replay.
• Presentation planes: document < inspector/deferred < prompt, drag, tooltip < diagnostic overlays. Document zIndex never crosses a plane. Within a deferred root CSS stacking applies; deferred priority orders the roots.

Corrections found by the investigation, all required:

1. Containers vs contexts. position: relative|absolute with zIndex: auto is a stacking container, not an atomic context. Its positioned descendants still take part in the nearest real context: an early auto-positioned A containing z=100 paints above a later z=1 sibling.
2. Paint phases. A context's own background, content and border/outline are separate paint units with a phase in the key. Style::paint enters explicit decoration, content and outline phases.
3. Source order comes from an explicit retained-tree token supplied by GPU-IX, never from prepaint encounter order. Div::prepaint_order_fn has an upstream user.
4. Selection overlap. Text registries stay in tree order. Each entry carries a stacking rank used only to decide which overlapping text wins a point.

Applicability, following CSS Positioned Layout §4.2, Flexbox §4.3 and Grid §6.5:

• authored relative/absolute with zIndex auto: container;
• numeric zIndex, including 0, on a positioned element or a flex/grid item: atomic context;
• position: fixed: atomic context;
• opacity < 1: atomic context for ordering only, since GPU-IX multiplies opacity per primitive rather than compositing a group;
• numeric zIndex on an ordinary block: accepted, no effect;
• zIndex inside hover/active/focus styles: rejected.

"Positioned" must come from authored GPU-IX metadata: GPUI defaults Style.position to Relative, and GPU-IX calls .relative() when nothing is authored.

Where it lands

File	Change
zed/crates/gpui/src/scene.rs	Key metadata on operations; clear, push_layer/pop_layer, insert_primitive, replay, finish.
zed/crates/gpui/src/window.rs	Stacking scopes; Hitbox, DeferredDraw, Frame::{hit_test, cursor_style}; hit-order finalization; deferred planes; cache rebasing in reuse_prepaint/reuse_paint.
zed/crates/gpui/src/style.rs	Decoration, content and outline phase scopes in Style::paint.
zed/crates/gpui/src/elements/stacking.rs (new)	Transparent wrapper carrying the stacking descriptor without reordering children.
packages/native/src/renderer.rs	Descriptor (source token, authored position, zIndex, flex/grid-item flag, opacity, plane), wrapping every result of build_element_with_parent_layout, so host containers, custom elements and virtual-list rows are covered.
packages/native/src/style.rs, packages/react/src/types/host.ts	zIndex as an integer, rejected in state styles.
packages/native/src/text/paint.rs	Stacking rank for overlap resolution only.
README.md	zIndex applicability and stacking behaviour.

Cost: trees with no authored positioned, zIndex or opacity context pay one branch. Trees with some pay a key handle and ordinal per primitive and hitbox, a sort of paint units and hitboxes, one extra BoundsTree pass, and possibly smaller GPU batches where CSS order prevents merging.

Size: large. It changes the core of GPUI's scene, window and style paint, plus cache replay, which is the riskiest part. Tests need to cover negative, zero and positive ordering, container escape, the dock case with Tab and accessibility unchanged, cached views, deferred planes, flex and grid items, custom-element children and virtual-list rows.