wry/docs/window-animations-plan.md

Window Animations Plan

This document is the working plan for Wry's window animation system. It records the decisions already made, the implementation phases, and the risks that must be handled deliberately.

Accepted Decisions

• The first landed slice is linear interpolation only, disabled by default.
• Animation is presentation-only. Logical layout, input hit testing, focus, and Wayland configure state use final geometry immediately.
• Pointer drag and resize initiated by the mouse or tablet do not animate.
• Linear animations restart only for windows whose destination changes. Other in-flight windows keep their existing timelines.
• Spawn-in uses scale and position for newly mapped tiled and floating app windows. Layer-shell, overlay, override-redirect, and fullscreen surfaces do not use this path. Spawn-out uses retained visual content after the live node is gone, when a stable retained surface tree can be captured before unmap or destroy.
• Command-driven tile-to-float and float-to-tile transitions may animate. Protocol drag/drop paths do not.
• The no-overlap multiphase system is a separate phase after the linear path is working and testable.
• Content freezing will use retained per-surface texture references, not a full offscreen snapshot as the default design.
• Retained records should keep using the existing renderer behavior for now, including clipping and edge stretch/clamp behavior for undersized contents. A dedicated retained-tree scaling path is deferred to a later polish phase.
• The multiphase animation concept is original to Wry. Hy3 is relevant only as partial inspiration for tiling style and titlebar/grouping behavior.
• Mono mode should mostly avoid animations. Exceptions are windows entering or exiting mono mode, where a visual transition can clarify the hierarchy change.

Texture Freezing Decision

The approved freezing design is to capture a renderable surface tree at animation start:

• texture references
• source sample rects
• target sizes
• alpha and color metadata
• subsurface offsets and stacking order
• enough synchronization/release state to keep referenced buffers alive safely

This is lighter than rendering every toplevel into a compositor-owned offscreen texture, and it should handle normal GPU-backed windows without an extra full window copy. It also gives spawn-out a path: capture the surface tree before the toplevel is logically destroyed, then animate the retained records after the live node is gone.

Tradeoffs:

• Retained references can delay buffer release. For dmabuf clients this can increase memory pressure or throttle clients if many large windows animate.
• SHM buffers still matter for simple clients, fallback paths, some utilities, and cursor-like surfaces. They are probably not the common case for large app windows, but the implementation must still treat SHM texture flipping as a correctness issue.
• The release/sync contract must be explicit. A retained texture must not be released back to the client while the compositor may still render it.
• True offscreen snapshots remain a possible fallback for cases where retained references cannot safely preserve the rendered content.

Phase 1: Linear Presentation Animations

Goal: add the smallest correct animation layer without changing layout semantics.

Implementation shape:

• Add animation state owned by State.
• Track per-toplevel animation entries keyed by NodeId.
• Store logical target rect, current presentation rect, previous damaged rect, start time, duration, and curve.
• On command-driven tiled layout geometry changes, animate from current presentation rect to new final rect.
• On interruption, restart only the affected window from its current presentation rect.
• Drive frames from the existing output latch/presentation event flow.
• Damage the union of previous presentation rect, current presentation rect, and final logical rect.

Initial scope:

• Tiled reflow animation.
• Floating command-driven moves and resizes are animated. Pointer and tablet drag/resize paths still snap directly to the live cursor position.
• Cross-output and cross-scale movements snap for now.
• Linear mode may overlap windows during swaps. That is expected for the classic interpolation mode; no-overlap is Phase 3.
• Live client buffers are rendered in Phase 1. Retained content freezing is deferred, but animated windows must still be clipped to their presentation bounds and must preserve the existing stretch behavior for undersized contents.
• Spawn-out is retained-content-only. If the surface cannot be retained safely the window snaps out instead of animating an empty frame.
• No multiphase no-overlap planner.

Tests:

• rect interpolation is direction-independent
• interruption restarts only changed windows
• unchanged in-flight windows keep their original timeline
• drag-driven floating movement bypasses animation
• damage includes old, current, and final rects
• command-driven tile-to-float and float-to-tile transitions use linear motion
• command-driven floating moves and resizes animate without affecting pointer drag/resize behavior
• pointer/header double-click unfloat bypasses the command-animation gate

Phase 2: Retained Texture Freezing

Goal: freeze visual contents during movement and enable spawn-out.

Initial retained-record implementation status:

• Tiled animation can retain GPU/dmabuf-backed XDG and Xwayland surface trees.
• Spawn-in animation can retain GPU/dmabuf-backed XDG and Xwayland surface trees for both tiled windows and floating child contents.
• Tile-to-float and float-to-tile transitions retain GPU/dmabuf-backed child contents while the presentation geometry changes.
• Spawn-out captures retained app-window contents before XDG/Xwayland unmap or destroy, then renders a detached shrinking presentation record until the animation completes.
• Retained records hold both GfxTexture and SurfaceBuffer references so the existing buffer release/sync path remains authoritative.
• Single-pixel buffers can be retained as color records.
• Retained records render through the same texture and stretch/clamp paths used by live surfaces. This is the expected Phase 2 behavior.
• Async SHM textures are not retained yet because Wry's per-surface SHM front/back textures can be reused by later commits while an animation is still running. Those surfaces fall back to live rendering until an explicit offscreen copy fallback exists.

Implementation shape:

• Add a retained render-record tree for toplevel surfaces.
• Capture records before movement animations that require freezing.
• Capture records before destroy/unmap for spawn-out.
• Render retained records through the normal renderer primitives where possible.
• Extend event/sync handling so retained buffers remain valid until the animation is complete.

Deferred/future polish:

• Whether retained records participate in frame callbacks or presentation feedback. Default assumption: no, because they are compositor animation frames, not client commits.
• How to fall back when a buffer cannot be safely retained.
• A distinct retained-tree scaling render path for true spawn-in/spawn-out content scaling. If added, start with retained GPU-backed records only, keep the animated frame as the clip boundary, and avoid live SHM scaling until there is an explicit snapshot/copy fallback.

Phase 3: Multiphase No-Overlap Animations

Goal: implement Wry's staged no-overlap planner while preserving the rule that windows never overlap.

Core rules:

• Each phase is a discrete animation using the full curve.
• A phase performs only one action kind per window: move or scale.
• Movement and scaling are split by axis.
• No diagonal motion.
• A window or synchronized group owns its own timeline.
• New layout changes interrupt only windows/groups with changed destinations.
• Current hierarchy and target hierarchy both matter. The planner must know whether a window is ascending toward a higher-level/toplevel position, descending into a container, or moving between containers at the same depth.
• If some child windows require fewer phases than their parent/container context, parent/container-space changes generally happen first so space exists before the child moves into it. This rule can be overridden only when the non-overlap invariant still clearly holds.
• Windows that become peers in the target hierarchy may synchronize later phases even if they were not peers in the source hierarchy.

Important parent/child synchronization issue:

The planner must not let a parent container and child window animate independent axes at the same time in a way that violates the visual rules. For example, a parent scaling horizontally while a child scales vertically can accidentally produce a diagonal or multi-axis motion in screen space.

Preferred approach:

• Plan in terms of leaf toplevel visual rectangles first.
• Treat containers as constraints and grouping boundaries, not as independently animated visual actors.
• Derive every leaf's per-phase rect from one phase schedule so parent and child effects cannot compose into forbidden motion.
• Add container-level grouping only after the leaf planner proves correct.
• Include hierarchy-transition metadata in the planner input: source parent, target parent, source depth, target depth, and whether the window is ascending, descending, or staying at the same hierarchy level.
• For mono containers, suppress ordinary in-mono focus/tab changes. Animate only transitions into mono, out of mono, or across the mono boundary.

Tests:

• horizontal swaps shrink, move, then grow without overlap
• extraction from a stack creates space before moving the extracted window
• nested containers do not produce simultaneous cross-axis motion
• interruption restarts only affected phase groups
• reversing direction produces equivalent motion in reverse
• child waits for parent/container-space phases when moving upward into a toplevel peer position
• mono-mode tab switches do not animate, while entering/exiting mono can animate

Configuration

Phase 1 should expose a disabled-by-default setting for:

• enabled/disabled
• duration
• curve preset or cubic bezier

Initial TOML shape:

[animations]
enabled = false
duration-ms = 160
curve = "ease-out"
# or:
curve = [0.25, 0.1, 0.25, 1.0]

Bezier curves are analyzed when configuration is applied and stored as a piecewise curve that is cheap to evaluate during rendering. Custom curves use CSS cubic-bezier semantics: (0, 0) and (1, 1) are implicit, while the four configured numbers are x1, y1, x2, and y2. The x control points must be between 0 and 1.

Existing Note

docs/animation-integration.md appears to document a prior animation attempt whose src/animation/ implementation is not present in this checkout. Treat this plan as the current source of truth until implementation docs are updated.