ricing

Apply the project's high-priority motion contract and Glass Liquid visual language for QML/Quickshell UI. Use when designing or modifying QML visual components, PanelWindow surfaces, popups, islands, overlays, layout transitions, animations, states, or interaction feedback.

Keep dockzone-hosted hover details from changing host body or ear geometry. Use when a bar widget detail popup shifts a dockzone, pushes an attached ear offscreen, is clipped after decoupling, or needs a non-layout overlay viewport.

Use when an expand/collapse/grow/shrink animation stutters or drops frames even though per-frame CPU/GPU work looks cheap. Applies when the animated size is driven into a costly-to-commit boundary every frame — a top-level/layer-shell/OS window, a compositor input/blur/visible region, a cross-process or protocol-committed surface, or a per-frame rebuild of a large model/object graph. Covers the fix (fixed outer container, animate inner content) and a frame-delta bisection method to locate the offending per-frame commit.

Use when content inside an expanding/contracting surface (dockzone, island, drawer, menu) overflows or reads as harshly cut during the host's grow/shrink. Drive content reveal (opacity, slide, anchor edge) from the host's reveal progress before relying on a clip mask.

Use when a search, picker, launcher, clipboard, or results list only stutters on the first large match/open, then becomes smooth on subsequent runs. Applies when the dominant cost is cold delegate/icon/text/layout initialization rather than steady-state filtering or GPU work. Fix by prewarming a small representative first batch without changing search semantics or list structure.

Use when diagnosing or fixing UI layout bugs where measured, preferred, target, actual, animated, or clipped sizes diverge. Applies to QML, React, native UI, and other reactive layout systems, especially when content is clipped even though the theoretical max size is large enough.

Load when adjusting QML visual styles, colors, radii, opacity, blur, shadows, spacing, scale, or related presentation variables. Enforces project-wide transition rules for perceptible style changes.

Use when a text field, search box, or editable control works the first time but stops accepting input on reopen, page switch, or second mount because multiple live instances, wrappers, or lifecycle hooks compete for focus. Applies when hover and pointer are fine but keyboard input goes to the wrong instance or nowhere. Not for pointer starvation from overlapping layers; use `overlay-pointer-event-starvation`. Not for visible-owner migrations that break rendering/editing/geometry together; use `surface-owner-split-debugging`.

Stabilize media UI when browser MPRIS metadata is incomplete, delayed, or inconsistent. Use when lyrics or artwork disappear, flicker, or fail to update for web players like Firefox/Chrome, especially when MPRIS omits trackArtUrl, artist fields churn, temporary file artwork expires, or webpage metadata is richer than the exported media session.

Use when a secondary render layer that updates on an asynchronous or coalesced/throttled commit path (compositor blur/mask region, low-frequency mirror/shadow copy, polish-cycle-driven geometry) visibly lags, stutters, overflows, or pops relative to a main layer that renders synchronously every frame, especially during fast size/shape animations.

Use when an inner or lower element stops receiving hover/pointer events (no hover highlight, hover-driven popup never opens, or a popup flickers open/closed) because an overlapping element above it silently consumes those events. Applies to QML, web (CSS/DOM), and native UI. Trigger signs include a full-area transparent catcher, a hoverEnabled/pointer-capturing layer drawn on top, or a fullscreen overlay window that covers the very element that triggered it.

Use when a UI surface's visible owner has been moved or split away from its prior state, layout, or editing owner, and behavior regresses in ways such as hover animations disappearing, real content not rendering, right-click or drag editing breaking, or container width/height no longer tracking content.

Require a brief descriptive comment immediately before major QML element declarations. Use when editing QML modules that should stay self-documenting and easy to scan.