Layer surfaces

gnoblin.layers.list() returns LayerSurface objects from the native layer-surface snapshot. Each includes its state revision. Layer surfaces have no mutating methods; shell clients continue to own their surfaces.

Like window objects, every read of one surface returns the same object, updated with each change:

• layer.alive turns false when the surface goes away.
• layer:on(signal, fn) takes "changed" or "closed".
• layer:watch(field, fn) calls fn(layer, value, old) when a declared field changes.

gnoblin.layers.list() takes no filter. Select surfaces with gnoblin.find("LayerSurface", filter). A table filter matches declared scalar fields, such as id, namespace, layer and monitor_id. A predicate function also works. See find.

The read is available only in the native Mutter runtime and raises a Lua error while its snapshot is unavailable.

local panels = gnoblin.find("LayerSurface", {layer = "top"})

Shells that also use the control socket can find its request format in the compositor bridge.

Layer records expose these fields:

Mutter omits app_id because layer-shell does not provide one.

The layer field controls stacking order:

• background sits behind desktop content.
• bottom sits above background surfaces.
• top sits above normal windows.
• overlay sits above the other layer levels.

keyboard_interactive controls keyboard focus:

• none does not request keyboard focus.
• on_demand requests focus when the surface needs keyboard input.
• exclusive keeps keyboard focus while the surface is mapped.

Pointer input follows the surface's wl_surface input region independently of keyboard focus. A surface with keyboard_interactive = "none" can still accept clicks. Retained panels can expand or clear their input regions when opening or closing; they do not need to request keyboard focus to receive clicks.

Pointer movement alone leaves layer ordering unchanged. Pointer clicks can raise a layer surface within its layer. Exclusive keyboard focus also raises a popup when it opens. A shell can keep companion surfaces above or below an overlay using UI-session state. Those constraints apply to pointer raises too.

gnoblin.layers.animation_policy(layer) returns the effective enter and exit phases and window_shadow for a layer surface. Pass a LayerSurface, or a namespace of 1 to 128 UTF-8 bytes. Without an animation override, each phase uses its first enabled event registration, or none if no event is registered.

window_shadow defaults to false unless a matching default-window rule supplies a shadow value. The method raises a Lua error if the committed policy cannot be read.

layer:inspect_animation(name, event?) resolves an animation against the surface without starting it. layer:preview_animation(name, event?, autoplay?) starts a controllable preview.

gnoblin.capabilities.list() returns read-only native compositor and protocol capability records. It takes no arguments and has no filters or mutators. The read raises a Lua error if its snapshot is unavailable.

Capability records expose these fields:

• id: the capability name.
• description: what the capability provides.
• available: whether its current requirements are met.
• revision: the compositor state revision.
• reason: the cause when the capability is unavailable; omitted otherwise.

The standalone runtime advertises these optional capabilities:

• window-thumbnails: bounded window previews.
• session-activity: native idle-monitor state.
• microphone-monitor: PipeWire microphone activity monitoring.
• camera-monitor: PipeWire camera activity monitoring.

microphone-monitor and camera-monitor are available only when this Mutter build includes remote-desktop support and the PipeWire monitor is connected. When unavailable, reason is one of:

• remote_desktop_disabled: the Mutter build lacks remote-desktop support.
• pipewire_unavailable: the monitor cannot connect.

Camera activity follows running PipeWire nodes whose media role is Camera. The activity remains available for 500 ms after the last camera node stops to avoid flickering.

Subscribe to gnoblin.capability.changed to receive the updated record when availability changes. Check the capability snapshot before using an optional capability.