feat(protocol): add treeland-window-animation-v1 protocol

[glyvut]

Persistent, updatable rect object for window open/close animation:

• Renamed from treeland-launch-animation-v1 to treeland-window-animation-v1
• Rect object survives commit; client may call set_geometry + commit repeatedly
• Close animation transitions back to the rect
• Destroying the rect falls back to default close animation
• Removed already_committed error; commit is repeatable

Summary by Sourcery

Add a persistent, updatable window animation protocol for activation-driven open and close transitions.

New Features:

• Add the experimental treeland window animation protocol for rectangle-based window open and close animations, with optional source images.

Enhancements:

• Support persistent animation rectangles whose geometry and source image can be updated across repeated commits, including latest-geometry close animations and default fallback when the rectangle is destroyed.

Build:

• Install and package the new public window animation protocol XML.

Documentation:

• Document the new public protocol, interfaces, and intended window animation behavior.

[deepin-ci-robot]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[deepin-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: glyvut

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• debian/deepin/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[sourcery-ai]

Reviewer's Guide

Introduces the experimental treeland-window-animation-v1 Wayland protocol, replacing the one-shot launch-animation model with a persistent, repeatedly updatable rectangle associated with an activation token; the protocol defines geometry validation, close-event lifecycle, and default-animation fallback when the rectangle is destroyed.

Sequence diagram for persistent window animation rectangle lifecycle

sequenceDiagram
    participant A as AppA
    participant M as AnimationManager
    participant R as AnimationRect
    participant T as ActivationToken
    participant B as AppB
    participant C as Compositor

    A->>M: get_window_animation_rect(R, T)
    A->>R: set_geometry(x, y, width, height)
    A->>R: commit()
    A->>T: commit()
    A->>B: Pass activation token
    B->>C: activate(token, surface)
    C->>C: Play open animation from latest rectangle
    A->>R: set_geometry(new_x, new_y, new_width, new_height)
    A->>R: commit()
    B->>C: Close target window
    C->>C: Play close animation to latest rectangle
    C-->>R: closed
    A->>R: destroy()

Loading

State diagram for window animation rectangle lifecycle

stateDiagram-v2
    [*] --> Uncommitted
    Uncommitted --> Committed: set_geometry() + commit()
    Committed --> Committed: set_geometry() + commit()
    Committed --> Closed: target window destroyed
    Closed --> [*]: destroy()
    Committed --> DefaultClose: destroy() / client disconnect / origin surface destroyed
    DefaultClose --> [*]
    Uncommitted --> Uncommitted: commit() / no_geometry error

Loading

File-Level Changes

Change	Details	Files
Add the experimental window-animation protocol definition and register it for generated/build outputs.	Define manager and persistent rectangle interfaces tied to xdg activation tokens. Specify geometry commit/update semantics, open/close animation behavior, lifecycle fallback, and protocol errors. Add the XML protocol to the CMake protocol input list.	public/treeland-window-animation-v1.xml CMakeLists.txt

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[Copilot]

🟡 Changes recommended

The new protocol spec needs adjustments to match established repo protocol naming/structure conventions and to resolve clarity/consistency issues in the XML text.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a new public Wayland protocol XML specifying a rectangle-driven open/close window animation workflow tied to xdg-activation-v1, including a persistent rect object with repeatable commits and an optional source image buffer.

Changes:

• Introduces treeland-window-animation-v1 protocol with manager + rect interfaces, geometry/commit workflow, optional wl_buffer source image, and a closed event.
• Registers the new protocol in the public protocols README table.
• Adds the protocol XML to TREELAND_PROTOCOL_XML_FILES for installation/packaging.

File summaries

File	Description
public/treeland-window-animation-v1.xml	New protocol specification for rectangle-based window open/close animations with optional source buffer and persistent updates.
public/README.md	Documents the newly added public protocol in the protocol table.
CMakeLists.txt	Installs/packages the new public protocol XML by adding it to the public list.

Review details

Suppressed comments (3)

public/treeland-window-animation-v1.xml:156

• The protocol rules for this repo recommend keeping enums before requests and keeping all requests before any events. In treeland_window_animation_rect_v1, the closed event appears before set_geometry/commit/set_source_buffer, and the error enum is last; please reorder the members to match the recommended layout (description -> enums -> destroy -> requests -> events) for consistency and easier diff review in future versions.

        <event name="closed">
            <description summary="the target window has been destroyed">
                Sent once the target window associated with this rectangle has

public/treeland-window-animation-v1.xml:77

• This protocol text uses RFC 2119-style normative keywords (e.g. “MUST”, “SHOULD”) but does not include the RFC 2119 interpretation paragraph. Per the repo protocol rules, either add the RFC 2119 paragraph to the top-level <description> and use lowercase keywords consistently, or avoid normative keywording entirely to prevent ambiguous conformance requirements.

        The client MUST call xdg_activation_v1.activate on the target
        surface before that surface is first mapped (i.e. before the
        wl_surface.commit that causes the compositor to map it). This
        ensures the compositor has the animation rectangle available when
        the surface appears.

public/treeland-window-animation-v1.xml:169

• The closed event description is internally contradictory (“creates a rectangle per long-lived target window” vs “reuse the rectangle for further target windows”), which makes the intended lifetime guidance unclear. Please reword this section to clearly separate the “reuse one rectangle” vs “create one rectangle per target window” patterns.

                long-lived target window can reuse the rectangle for further
                target windows; a client that creates a new rectangle for each
                target window SHOULD destroy the rectangle upon receiving this
                event so it does not accumulate rectangles for windows that are
                already gone.

• Files reviewed: 3/3 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.