Pure surface registry: the single source for "what is where on screen".

Given the frame's editor state, placements/1 returns an ordered list of MingaEditor.Layout.SurfaceRegistry.Placement entries, each carrying a surface_id, a rect (terminal cells, the existing Layout.rect/0 convention), a z band, and a hit_kind. The list is ordered back-to-front by z (lowest first), so a stable sort by z reproduces paint order and a reverse walk reproduces hit-test precedence.

This module is a calculation, not a process: state in, placements out. There is no ETS, no GenServer, no cache of its own. It is consumed where MingaEditor.FocusTree/MingaEditor.Layout are consumed today.

The input rule (design of record, epic #2330)

Clients resolve clicks on content they render and send semantic intents (gui_actions); the BEAM owns placement, stacking, and containment for registry-placed surfaces. That is the governing line for all surface input.

A frontend hit-tests its own rendered content (a completion row, a notification action, an observatory node) and emits an intent like "item N clicked", exactly as SwiftUI's native hit-test already does. The BEAM does not re-derive what a click means on rendered content. What it owns is structure: which rect a surface occupies (placements), which surface wins when rects overlap (z-order arbitration, since stacking depends on editor state only the BEAM has), and containment, so a click that misses every interactive element of a registry-placed surface is swallowed instead of falling through to the buffer underneath (MingaEditor.Input.OverlaySink). The picker is the one documented exception: it predates this rule and stays BEAM-resolved as shipped.

One source, derived from the focus tree

The registry is built by flattening the existing MingaEditor.FocusTree. The focus tree is already the BEAM's authority for mouse routing: it carries the per-frame Layout rects plus the single active overlay, with children stored in rendered z-order (back to front). By projecting that same tree into placement entries, the registry rect for every surface is, by construction, the exact rect the focus tree (and therefore every hit-test that routes through it) uses. That is the behaviour-neutrality guarantee the epic asks for: registry rect == the rect each handler previously computed, because both read the same tree.

Scope honesty: single active overlay

FocusTree.add_modal_overlays/3 encodes the same exclusive precedence that Go's overlayLines() chain encodes today: at most one modal overlay (picker OR completion) is live per frame. The registry preserves that decision as data; it emits the single active overlay and nothing else. Multiple simultaneous overlays are newly expressible as a list but are deliberately NOT produced here. Enabling them is out of scope (see #2268, AC-4).

Enumeration history (#2268 -> #2281). The Go compositor's overlayLines() chain once stacked surfaces that were not focus-tree nodes via a hand-ordered rank table. That table is now gone: every overlay surface is a focus-tree node with a BEAM-authoritative rect.

• Cursor-anchored popups: hover popup, signature help. Both are floating popups whose exact on-screen box the BEAM computes for layout (HoverPopup.box/3/SignatureHelp.box/3, driven by FloatingWindow). FocusTree.add_floating_overlays/2 adds them as overlay nodes from shell_state; they occupy the @z_floating_overlay region (hover 290 > signature help 280).

• Footer-band secondary overlays (#2281): float popup, agent context, tool manager, extension panel, observatory, edit timeline, notifications, extension overlay. The owner ruled these mouse-driven (#2330), so the BEAM owning their footer-band geometry is now the designed layout. FocusTree.add_footer_band_overlays/3 adds each visible one (per MingaEditor.Layout.FooterOverlays) as an overlay node with a bottom-anchored full-width rect from MingaEditor.Layout.OverlayBand (porting the Go maxOverlayHeight clamp). They carry the exact historical stacking z (270/260/240/190/180/170/160/150), so Go composites the single highest-z winner by its placement rect instead of footer-appending. The single-active model still holds (#2268 AC-4): the tree may express several placements, but Go renders one. Their click events route to MingaEditor.Input.OverlaySink, which swallows mouse events so a click over a visible overlay never reaches the buffer underneath (AC-2). Per-surface activation semantics land as epic #2330 children.

surface_id namespace and the identity-unification call (#2268)

surface_id/1 maps each focus-tree content_type to a stable atom in the registry's namespace; surface_id_u16/1 maps that atom to its u16 wire value and hit_kind_u8/1 maps a hit_kind atom to its u8 wire value. This module is the single source of both mappings.

Unification decision (#2268 proper): the schema (surface_placement in docs/protocol_schema.toml, generated decoders on every frontend) carries surface_id as a raw u16 and hit_kind as a raw u8. It deliberately does NOT add a surface_id/hit_kind enum: that would be a new schema vocabulary, and the consult's instruction was to keep the schema as the cross-language source of truth without a new vocabulary. The cross-language source of truth is therefore the wire shape plus the generated codec; the numeric identity of each surface stays authoritative here, and the emitter (Minga.Frontend.Adapter.GUI.SurfaceLayoutEncoder) consumes these functions rather than re-deriving numbers. One writer (this module), one reader (the encoder). hit_kind_u8/1 reuses the window-encoder hit-kind numbering (Minga.Frontend.Adapter.GUI.WindowEncoder 1..6) and extends it with :chrome (7) and :overlay (8) so a placement's hit kind and a window hit region speak the same u8.

hit_kind

hit_kind reuses the window-scoped convention already encoded by Minga.RenderModel.Window.HitRegion and Minga.Frontend.Adapter.GUI.WindowEncoder (:text, :gutter, :fold_control, :modeline, :status_bar, :divider). Surface-level entries extend it with :chrome (structural chrome that routes to a handler but is not buffer text) and :overlay (a modal overlay surface). It is a coarse classification of what a click on the surface means, not a precise intra-surface region; intra-window hit regions stay with the window encoder.

What is NOT unified here (documented per the epic)

Several handlers compute a region's interpretation from math that is too entangled to swap behind a rect lookup without rewriting interaction semantics. For those, the registry is the source of the surface RECT, but the handler keeps its own interpretation:

• MingaEditor.Input.AgentMouse splits the agent window content rect into a chat sub-column vs a preview sub-column using chat_width_pct math, and splits the prompt area off the bottom using PromptRenderer height math. The registry emits the agent window/panel rect; the chat/preview/prompt sub-division stays in AgentMouse (it is interaction semantics, not a placed surface). Forcing it into the registry would mean inventing sub-surfaces that nothing else places.
• Tab-bar and modeline segment click regions (tab_bar_click_regions, modeline_click_regions) are authored at render time as text-property spans, not rects. The registry places the tab_bar and status_bar/modeline surfaces; the per-segment command lookup stays where it is.
• Intra-window buffer geometry (gutter width, fold column, scroll position to buffer line) stays in MingaEditor.Mouse.HitTest. The registry places the window content rect; translating a cell to a buffer position is window interpretation, not surface placement.

These are left intentionally. The registry's job in this slice is to be the one authority for surface rects and z-order, not to absorb every handler's interpretation of a click inside its surface.