| name | per-frame-surface-resize-jank |
| description | 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. |
Per-Frame Surface-Resize Jank
Diagnose and fix animation stutter caused by pushing a per-frame-changing size/geometry across an expensive commit boundary every frame, instead of keeping that boundary fixed and animating cheap inner content.
The Generic Pattern / Methodology
Core Concept
- A smooth animation must do only cheap work per frame (move/resize/clip/opacity on scene-graph items the renderer already owns).
- Some boundaries are expensive to mutate and must NOT be driven every frame:
- a top-level / OS / layer-shell window size (each resize = a compositor reconfigure roundtrip)
- a compositor input/visible/blur region or mask committed over a protocol/IPC boundary
- a mirror/snapshot/cached layer or any cross-process surface
- a per-frame rebuild of a large model/object graph (fresh allocations → GC pauses)
- The portable shape of the fix: fix the expensive outer boundary at a constant (large-enough) size, and animate cheap inner content inside it — grow/clip the content, not the window/region/model.
- The reference smooth implementation in the same codebase usually already does this (e.g. a popup window pinned to full-screen height with content growing inside). Compare against it.
Universal Checklist (before tuning easing/spring)
| Question | Why it matters |
|---|
Does the animated size feed a top-level window implicitWidth/Height? | Per-frame window resize = per-frame compositor reconfigure → periodic spikes. Pin it. |
| Does it feed a committed region (input/visible/blur/mask) every frame? | Region commits cross a protocol/IPC boundary; coalesce or pin during the animation. |
| Does the per-frame value flow through a JS/model rebuild that allocates objects? | Fresh allocations each frame thrash GC → sporadic long frames. Bypass the rebuild. |
| Is there a sibling feature that animates smoothly? | It almost certainly keeps the expensive boundary fixed; mirror its structure. |
| Can the outer boundary be a fixed, generous size with content clipped inside? | This is the fix; the extra transparent area is masked/click-through. |
The Specific Trap / Symptom (Case Study)
A Wayland (Quickshell) top bar grew a dockzone downward to host a hover popup. The expand animation stuttered (frame deltas 44–88 ms instead of ~16 ms) despite a GPU Shape outline and a spring. Bisection found the dominant cost was the bar PanelWindow.implicitHeight changing every frame as the dockzone grew → each frame forced a layer-shell surface resize + compositor reconfigure roundtrip. A secondary cost was routing the per-frame spring value through a JS contract-model rebuild (buildModel/deriveRendererMetrics) that re-allocated objects each frame and also invalidated unrelated sibling sections. The sibling that was smooth (the center "island") used a fixed full-screen-height window with its body growing inside.
The Anti-Pattern vs. Best Practice
- ❌ Anti-Pattern: bind an animated size to a top-level window dimension (
implicitHeight: content.implicitHeight), or recompute a committed region / rebuild a large model object on every animation frame.
- ✅ Best Practice: pin the window/region/model to a constant (generously sized) value; animate inner item geometry and clip; restrict input with a state-switched mask (resting shape vs full-window-for-click-away); keep the reserved/exclusive zone pinned so layout never reflows.
- ❌ Anti-Pattern: feed the per-frame animated value as an input to a pure function that allocates a fresh nested object graph (model/metrics) each frame.
- ✅ Best Practice: compute the resting model once; apply the animation as a lightweight additive geometry override on the already-exposed properties (QML bindings / direct style props), so the hot path allocates nothing.
Generalizable Rules (Highly Portable)
- Never animate an expensive commit boundary. Top-level window size, compositor regions, cross-process surfaces, and large object rebuilds are not per-frame-safe. Keep them fixed; animate inner content.
- Fixed outer, animated inner. Give the outer surface a constant generous size; grow/clip content within it. Mirrors the proven smooth sibling.
- Pin reservation/exclusion separately from visible size. A fixed tall window must still reserve only its resting footprint (e.g. exclusiveZone = bar height), and mask input to the resting shape until the popup is open.
- Keep the animation hot path allocation-free. Don't rebuild model/metrics objects per frame; apply additive overrides to existing properties.
- For side previews and detail panes, fix the slot before the payload. Keep the preview area at a constant width once that mode is open, and delay image decode / long-text layout / scroll setup until the host geometry has settled.
- Warning signs in other code: an
implicitWidth/Height of a window/top-level bound to animated content; a region/mask whose item geometry is driven by a running animation; a property var/model that re-runs a builder on every frame of a transition; "smooth here but janky there" between two surfaces doing nominally the same thing.
Universal Verification Strategy
- Frame-delta probe + bisection. Log
Date.now() deltas on the animated property's change handler. Even ~16 ms = smooth; sporadic 40–90 ms = real jank. Then bisect by temporarily neutralising one suspect per run and re-measuring:
- freeze the committed region (point blur/mask at a resting size) — spikes gone? region commit was it.
- stop feeding the value through the model rebuild (additive override) — sibling elements stop firing? model rebuild was a cost.
- pin the window size — spikes gone? per-frame window resize was the dominant cost.
- Watch for cross-element contamination. If unrelated siblings' geometry handlers fire every frame during one element's animation, a shared per-frame rebuild or shared committed boundary is the cause.
- Compare to the smooth sibling. Diff the janky surface against an existing smooth one; the difference is almost always "the smooth one keeps the expensive boundary fixed."
- No mouse needed. Drive the state from a temporary
Timer toggling the trigger so the animation can be measured headlessly; remove the probe after.
