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.
• Multiphase shrink steps should not normally need to reduce a tiled window far below roughly one quarter of the relevant full size. The implementation may enforce a conservative sanity minimum, and pathological cases may fall back.
• If the no-overlap planner cannot produce a legal sequence, only the affected group should fall back to linear animation. This is expected to be rare for valid tiling layouts.
• When entering mono mode, the active child should animate to the mono geometry. Inactive siblings may snap invisible. Floats may overlap normally and do not need the no-overlap planner.

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.
• Build the planner as pure geometry first. Live integration should collect eligible leaf (old, new) rects across a command-driven layout pass, then submit planner-produced phases as a batch. Per-node tl_change_extents calls are too incremental to plan safely by themselves.
• 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.
• When entering mono, the active child animates to the full mono area and inactive siblings snap invisible. When exiting mono, ordinary tiled geometry may animate from the mono child where that produces a clear hierarchy transition.
• If a legal no-overlap sequence cannot be found for a group, fall back to the linear animator for that group only. Float windows are outside this invariant.

Current pure planner status:

• Two-window same-axis swaps use shrink lanes, move, then grow.
• Swap lane choice follows motion direction, not node identity: right/down moving windows take the first lane, and left/up moving windows take the second lane.
• Stack extraction/return patterns are covered in both horizontal and vertical orientations: peer/container space scales first, the extracted child moves only after space exists, and orthogonal growth happens in the final phase.
• Same-axis size redistribution is handled as a single scale phase when the exact validator proves adjacent windows stay non-overlapping.
• Nested size redistribution can use hierarchy metadata to decompose two-axis resizing into parent-axis then child-axis scale phases, but only when the source/target ancestor split depths give a deterministic order.
• Every produced plan is checked analytically for overlap over the full duration of each phase before it is accepted. This solves the linear edge inequalities for each pair of moving rectangles instead of relying on sampled frames.
• Live layout batches are partitioned by overlapping motion bounds, so unrelated groups can still use multiphase animation when another group falls back to linear motion.
• Planner requests now carry per-window hierarchy metadata for source/target parent, depth, sibling index, split axis, nearest ancestor split depth per axis, mono state, and transition kind. The current planner uses this for parent-before-child scale ordering, but not yet for full nested move planning.
• Multiphase planning has a diagnostic entry point used by live fallback logs. It distinguishes request validation errors, missing patterns, shrink-bound rejections, invalid phase steps, and exact validation failures such as stale starts or phase overlap.
• Planner tests now include a deterministic split-tree generator. It builds valid weighted tiling layouts, derives leaf hierarchy metadata, mutates them through supported transitions, and runs the real planner plus exact validator.

Tests:

• horizontal swaps shrink, move, then grow without overlap
• extraction from a stack creates space before moving the extracted window
• nested size redistribution scales the parent axis before the child axis
• 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.