deprecate: move treeland-dde-shell-v1 to deprecated/

[wineee]

1. Add treeland-active-notify-unstable-v1: manager + per-seat notifier
   (get_active_notify), with activity_enter/activity_leave events carrying a
   reason enum (mouse/wheel) and start_drag/drop events
2. Mark the dde-shell treeland_dde_active_v1 interface and its
   get_treeland_dde_active manager request deprecated and non-functional
3. Register the protocol in CMakeLists and update dde/public READMEs with a
   0.7.0 breaking change entry

Log: New active-notify protocol replaces the dde-shell treeland_dde_active_v1
interface; events renamed from active_in/active_out to activity_enter/leave

Influence:

1. Install the package and verify the new XML file lands in the treeland-protocols data dir
2. Run wayland-scanner client-header and private-code on the new XML file to confirm parsing
3. Check the READMEs list the new protocol and the dde-shell deprecation note
4. Reconfigure cmake and confirm the build succeeds with the updated DDE file list

Summary by Sourcery

Replace the non-functional dde-shell activity and overlap APIs with dedicated experimental DDE protocols and document the migration.

New Features:

• Add the experimental treeland-active-notify-unstable-v1 protocol for per-seat pointer activity and drag-and-drop notifications.
• Add the experimental treeland-window-overlap-checker-unstable-v1 protocol for monitoring edge-anchored regions against toplevel windows.

Enhancements:

• Deprecate and disable the legacy DDE active and window-overlap interfaces in favor of the new standalone protocols.

Build:

• Register the new DDE protocol definitions for installation and build generation.

Documentation:

• Document the new protocols and the breaking migration from the legacy dde-shell interfaces in English and Chinese READMEs.

[sourcery-ai]

Reviewer's Guide

The PR moves XWayland positioning and seat activity functionality into two independently installed unstable-v1 DDE protocols, preserving positioning wire semantics while making the legacy dde-shell functionality non-functional and documenting the 0.7.0 migration.

Sequence diagram for XWayland positioning with callback feedback

sequenceDiagram
    participant Client as Privileged DDE Client
    participant Control as treeland_xwindow_control_v1
    participant Compositor
    participant Callback as wl_callback
    Client->>Control: set_xwindow_position_relative(callback, wid, anchor, dx, dy)
    Control->>Compositor: Process XWayland window placement
    alt move succeeds
        Compositor-->>Callback: done(0)
    else move fails
        Compositor-->>Callback: done(1)
    end
    Compositor-->>Control: Destroy callback

Loading

File-Level Changes

Change	Details	Files
Introduces new unstable DDE protocols for XWayland placement and seat activity, and installs them as DDE protocol XML files.	Defines XWayland relative-positioning with per-request wl_callback success/failure feedback. Defines per-seat activity notification with pointer/wheel transition and drag/drop events. Adds both XML files to the DDE installation list and documents their interfaces in English and Chinese READMEs.	CMakeLists.txt dde/treeland-xwindow-control-unstable-v1.xml dde/treeland-active-notify-unstable-v1.xml dde/README.md dde/README.zh_CN.md
Deprecates the legacy dde-shell window-positioning and activity interfaces while preserving their wire definitions.	Marks the legacy positioning request and activity creation request as non-functional. Directs consumers to the corresponding new independent protocol globals. Adds a 0.7.0 breaking-change migration entry and updates public protocol listings in both languages.	public/treeland-dde-shell-v1.xml public/README.md public/README.zh_CN.md

---

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.

[sourcery-ai]

Hey - I've found 2 issues

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="dde/README.md" line_range="18" />
<code_context>
+| `treeland-active-notify-unstable-v1.xml` | `treeland_active_notify_unstable_v1` | `treeland_active_notify_manager_v1`, `treeland_active_notify_v1` | Seat activity notification: observe pointer button/wheel enter/leave activity and drag/drop lifecycle events scoped to a seat |
</code_context>
<issue_to_address>
**nitpick:** The DDE README lists both new protocols but does not add the promised 0.7.0 breaking-change entry; its breaking-change section still jumps from the introduction directly to 0.6.0. DDE consumers consulting this README are not told that the old dde-shell APIs were deprecated or what replaces them.

**Triggers:** When consumers use `dde/README.md` as the migration guide.

**Suggested fix:** Add a `### 0.7.0` section describing the deprecated dde-shell request/interface and the two replacement protocols.
</issue_to_address>

### Comment 2
<location path="public/README.zh_CN.md" line_range="25" />
<code_context>
+- `treeland-xwindow-control-unstable-v1.xml`（`treeland_xwindow_control_v1`）：XWayland 窗口定位——`set_xwindow_position_relative` 请求，结果经 `wl_callback` 回报，线缆语义不变。
+- `treeland-active-notify-unstable-v1.xml`（`treeland_active_notify_manager_v1`、`treeland_active_notify_v1`）：座席活跃通知——`get_active_notify` 请求创建按座席的通知对象，其 `activity_enter`/`activity_leave` 事件携带 `reason` 枚举（由 `active_in`/`active_out` 更名），并新增 `start_drag`/`drop` 事件。
+
+消费者应改绑新的全局对象，不得在新闻码中使用已废弃的请求与接口。
+
 ### 0.6.0
</code_context>
<issue_to_address>
**nitpick:** The Chinese migration guidance says `不得在新闻码中使用`, where `新闻码` is a typo for `新代码`. The instruction is misleading and is not a meaningful translation of “new code.”

**Triggers:** When Chinese-speaking consumers read the 0.7.0 migration guidance.

**Suggested fix:** Replace `新闻码` with `新代码`.

```suggestion
消费者应改绑新的全局对象，不得在新代码中使用已废弃的请求与接口。
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

[Copilot]

🟡 Changes recommended

Unresolved authorization, protocol semantics, versioning, and migration-documentation issues remain.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds experimental protocols for seat activity and window-overlap monitoring, replacing deprecated DDE shell interfaces.

Changes:

• Adds and registers two unstable protocol XML files.
• Documents legacy API deprecations and migration guidance.
• Updates English and Chinese protocol listings.

File summaries

File	Reviewed change
public/treeland-dde-shell-v1.xml	Deprecates legacy activity and overlap interfaces.
public/README.zh_CN.md	Updates Chinese public documentation.
public/README.md	Updates English public documentation.
dde/treeland-window-overlap-checker-unstable-v1.xml	Defines window-overlap monitoring.
dde/treeland-active-notify-unstable-v1.xml	Defines seat activity notifications.
dde/README.zh_CN.md	Lists new protocols in Chinese.
dde/README.md	Lists new DDE protocols.
CMakeLists.txt	Registers the new protocols.

Review details

Suppressed comments (9)

CMakeLists.txt:35

• The updated READMEs introduce a 0.7.0 breaking-change section, but project(TreelandProtocols VERSION ...) remains 0.6.0; CMake uses PROJECT_VERSION to generate the installed package version at lines 87-90. A build with these protocol additions would therefore still advertise version 0.6.0. Bump the project version to 0.7.0 or keep the documented release version consistent.

  dde/treeland-active-notify-unstable-v1.xml
  dde/treeland-window-overlap-checker-unstable-v1.xml

dde/README.zh_CN.md:19

• The PR description calls for a 0.7.0 breaking-change entry in the DDE and public README files, but this Chinese DDE README only adds the protocol rows and still starts its breaking-change section at 0.6.0. DDE consumers therefore get no migration/deprecation guidance for these replacements; add the matching 0.7.0 section here and in the English DDE README.

| `treeland-active-notify-unstable-v1.xml` | `treeland_active_notify_unstable_v1` | `treeland_active_notify_manager_v1`、`treeland_active_notify_v1` | 座席活跃通知：订阅按座席限定的指针按键/滚轮进入/离开活跃状态及拖拽/放下的生命周期事件 |
| `treeland-window-overlap-checker-unstable-v1.xml` | `treeland_window_overlap_checker_unstable_v1` | `treeland_window_overlap_checker_manager_v1`、`treeland_window_overlap_checker_v1` | 窗口重叠监测：注册沿输出边缘的区域并订阅与 xdg-shell 顶层窗口重叠/解除重叠的 enter/leave 事件 |

dde/treeland-active-notify-unstable-v1.xml:69

• A wheel has no persistent active/inactive state, so consecutive positive (or negative) scrolls do not form enter/leave transitions. The “only on transitions” rule therefore suppresses repeated wheel activity, while no event carries each scroll. Define wheel notifications as per-scroll direction events or specify a real latched state before clients depend on this API.

            button was pressed or a wheel was scrolled in the positive
            direction); leave means the source became inactive (the
            button was released or the wheel was scrolled in the negative
            direction). The compositor sends these events only on the
            transitions, not repeatedly while a state persists.

dde/treeland-active-notify-unstable-v1.xml:52

• The notifier retains the wl_seat for ongoing reports, but this request does not define the required lifetime ordering when that seat is destroyed. Existing seat-bound DDE objects require clients to destroy them before the associated seat; add the same constraint here.

                Create a new treeland_active_notify_v1 object that
                reports activity for the given seat. The seat must be a
                valid, current wl_seat.
            </description>

dde/treeland-active-notify-unstable-v1.xml:67

• The new interface's description uses the generic words enter and leave, while the actual events introduced below are named activity_enter and activity_leave. Since this protocol explicitly replaces active_in/active_out, name the events exactly in the workflow description so clients do not look for nonexistent enter/leave events.

            enter means the source became active (for example a pointer
            button was pressed or a wheel was scrolled in the positive
            direction); leave means the source became inactive (the
            button was released or the wheel was scrolled in the negative

dde/treeland-window-overlap-checker-unstable-v1.xml:123

• With this geometry definition, width is ignored for top/bottom anchors and height is ignored for left/right anchors, yet invalid_size requires both values to be positive. The request therefore requires a value that does not affect the monitored region, leaving clients unsure what geometry they are registering. Define a width-by-height region or remove/clarify the unused dimension before publishing this v1 API.

            <arg name="width" type="int" summary="width of the registered region" />
            <arg name="height" type="int" summary="height of the registered region" />
            <arg name="anchor" type="uint" enum="anchor" summary="output edge the region is anchored to" />
            <arg name="output" type="object" interface="wl_output" summary="the output whose edge anchors the region" />

dde/treeland-window-overlap-checker-unstable-v1.xml:68

• A checker retains the wl_output supplied to set_region, but this description does not state the required lifetime relationship. Without that contract, a client can leave a checker registered against a destroyed output; document that the checker must be destroyed before any output passed to set_region is destroyed, matching the lifetime rule used by the DDE wallpaper protocol.

            leave events. The recorded region only changes when
            set_region is called; the client must call set_region again
            whenever the monitored panel moves or resizes.

public/treeland-dde-shell-v1.xml:107

• The interface contains a functional destroy request at line 157, so saying that all requests have no effect makes the lifecycle contract incorrect and can cause clients to leak the deprecated object. Exclude the destructor from the non-functional behavior and state that it remains usable for cleanup.

            Deprecated: this interface is non-functional. All requests
            have no effect and no events are ever emitted. New code must
            not use it.

public/treeland-dde-shell-v1.xml:55

• The request is documented as superseded, but treeland_dde_active_v1 itself (lines 266-300) still only says it monitors special events and continues to advertise active_in/active_out; unlike the overlap interface, it is not marked deprecated or non-functional in the XML. Add matching interface-level deprecation and replacement text so the wire documentation does not tell clients to keep using the old events.

                Superseded by the treeland_active_notify_manager_v1
                global of the treeland-active-notify-unstable-v1
                protocol.

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

---

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

[Copilot]

🟡 Changes recommended

Protocol semantics and lifetime rules remain underspecified, and the DDE README breaking-change entries are incomplete.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (6)

dde/README.md:19

• The PR description calls for a 0.7.0 breaking-change entry in the DDE/public READMEs, but this DDE README only adds the protocol table rows; its Breaking changes section still stops at 0.6.0. Add the corresponding migration/deprecation entry here and keep the Chinese README synchronized.

| `treeland-active-notify-unstable-v1.xml` | `treeland_active_notify_unstable_v1` | `treeland_active_notify_manager_v1`, `treeland_active_notify_v1` | Seat activity notification: observe pointer button/wheel enter/leave activity and drag/drop lifecycle events scoped to a seat |
| `treeland-window-overlap-checker-unstable-v1.xml` | `treeland_window_overlap_checker_unstable_v1` | `treeland_window_overlap_checker_manager_v1`, `treeland_window_overlap_checker_v1` | Window overlap monitoring: register an edge-anchored region on an output and observe enter/leave overlap events with xdg-shell toplevels |

dde/README.zh_CN.md:19

• The PR description calls for a 0.7.0 breaking-change entry in the DDE/public READMEs, but this DDE README only adds the protocol table rows; its Breaking changes section still stops at 0.6.0. Add the corresponding migration/deprecation entry here and keep the English README synchronized.

| `treeland-active-notify-unstable-v1.xml` | `treeland_active_notify_unstable_v1` | `treeland_active_notify_manager_v1`、`treeland_active_notify_v1` | Seat 活跃通知：订阅按 Seat 限定的指针按键/滚轮进入/离开活跃状态及拖拽/放下的生命周期事件 |
| `treeland-window-overlap-checker-unstable-v1.xml` | `treeland_window_overlap_checker_unstable_v1` | `treeland_window_overlap_checker_manager_v1`、`treeland_window_overlap_checker_v1` | 窗口重叠监测：注册沿输出边缘的区域并订阅与 xdg-shell 顶层窗口重叠/解除重叠的 enter/leave 事件 |

dde/treeland-active-notify-unstable-v1.xml:52

• get_active_notify retains a seat association for the notifier's lifetime, but the protocol never states what clients must do when that wl_seat is removed. Seat-bound objects elsewhere in this tree explicitly require destruction before seat destruction; add the same ordering rule here so compositor and client lifetime handling is unambiguous.

                Create a new treeland_active_notify_v1 object that
                reports activity for the given seat. The seat must be a
                valid, current wl_seat.
            </description>

dde/treeland-window-overlap-checker-unstable-v1.xml:82

• The anchor description defines a full-width/full-height strip, but set_region still accepts both dimensions and only says that both must be positive. The contract does not say whether the non-thickness dimension is ignored, must equal the output size, or actually bounds the region, so clients can send the same edge with different geometries and get undefined monitoring behavior. Define this explicitly before exposing the wire API.

                The registered region is a strip along the anchored edge
                of the output: for top and bottom the strip spans the
                full output width and is height units thick; for left and
                right it spans the full output height and is width units
                thick.

dde/treeland-window-overlap-checker-unstable-v1.xml:118

• Because set_region is the registration point, clients need the resulting overlap state to initialize their UI. With the RFC 2119 paragraph above, “should” makes sending the initial enter/leave optional, so a conforming compositor could send nothing after registration. Make this a mandatory guarantee (and update the identical “should” wording in the interface description) or explicitly define that no initial state is provided.

                After this request the compositor should evaluate the
                current overlap state and send the matching enter or
                leave event.

public/README.zh_CN.md:21

• 前文列出的废弃项包括 set_xwindow_position_relative 请求和两个接口，共三项；这里的“二者”与后面列出的三个替代协议不一致，应改为“三者”。

二者由 `dde/` 下三个新的独立协议取代：

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

[Copilot]

🟡 Changes recommended

Unresolved protocol lifecycle and contract issues, plus a project-version mismatch, need resolution before approval.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (3)

CMakeLists.txt:16

• The changelog now documents a 0.7.0 breaking release, but project(TreelandProtocols VERSION 0.6.0 ...) remains unchanged. CMake uses PROJECT_VERSION for both the generated package version (CMakeLists.txt:89-92) and treeland-protocols.pc, so installations from this change will still advertise 0.6.0; please bump the project version or align the changelog with the intended package release.

  public/treeland-dde-shell-unstable-v2.xml

dde/treeland-window-overlap-checker-unstable-v1.xml:134

• This repeated should has the same contract ambiguity: the request description says the compositor should send the current-state event, while the event descriptions describe it as sent after every set_region. Use must here as well, otherwise clients still cannot rely on the initial state notification.

                After this request the compositor should evaluate the
                current overlap state and send the matching enter or
                leave event.

dde/treeland-window-overlap-checker-unstable-v1.xml:79

• The checker retains the wl_output passed to set_region, but the protocol only describes compositor-side output removal. It does not define whether a client may release the wl_output proxy while the checker remains live, so the output_removed/rebind lifecycle is ambiguous and can leave the server holding a dead object. Add an explicit client-side lifetime rule, including when the old output may be released after output_removed or a successful rebind.

            The checker is associated with the wl_output passed to the
            last set_region request. When that output is destroyed the
            compositor sends the output_removed event; the checker then
            becomes inert: it has no monitored region and sends no
            further enter or leave events. The checker object itself is

• Files reviewed: 10/11 changed files
• Comments generated: 4
• Review effort level: Lite

[deepin-ci-robot]

deepin pr auto review

🤖 AI 代码审查报告

总体评分： 100 分 (通过阈值: 70分)

---

📊 总体评价

项目	结果
审查结论	代码审查通过
评分详情	总体评分 100 分，大于 70 分通过阈值，代码质量符合要求。本次变更为 Wayland 协议定义文件的重构和拆分，新增 4 个独立协议文件，将旧协议移至 deprecated/ 目录并添加废弃标注，同时更新构建配置和文档。所有新增协议均要求特权客户端绑定，遵循最小权限原则，无安全漏洞。

---

🔍 详细分析

1. 语法逻辑 ✅

评价： 优秀 ✅ 通过

潜在问题：
✅ 未发现明显问题

建议： 所有 XML 协议文件格式正确，符合 Wayland 协议 XML Schema 规范。CMakeLists.txt 构建配置变更语法正确，set() 列表更新合理。协议接口版本一致，枚举值定义规范。

---

2. 代码质量 ✅

评价： 优秀 ✅ 通过

潜在问题：
✅ 未发现明显问题

建议： 所有新增协议均包含详尽的接口描述、RFC 2119 合规声明和 per-source/per-action 语义说明。废弃标注清晰，引用了替代协议。中英文 README 文档同步更新，包含详细的线缆级差异和迁移指南。代码结构清晰，职责分离良好。

---

3. 代码性能 ✅

评价： 优秀 ✅ 通过

潜在问题：
✅ 未发现明显问题

建议： compositor-action 协议采用无状态一次性触发设计，开销最小。active-notify 协议对鼠标使用配对事件、对滚轮使用离散脉冲，语义合理。region-watch 协议使用 enter/leave 事件通知，高效。dde-shell-v2 使用位置提示（compositor 决定最终位置），避免不必要的往返通信。

---

4. 代码安全 🔒

评价： 优秀 ✅ 通过

🔐 发现 0 个安全漏洞

安全漏洞详情：
✅ 未发现安全漏洞

建议： 所有 4 个新增协议均明确要求特权客户端绑定（The compositor must reject bind attempts from non-privileged clients）。错误处理完善（already_shell_surface、invalid_anchor、invalid_size）。compositor-action 协议明确文档化客户端不应假设动作已生效。region-watch 协议正确处理输出生命周期（output_removed 事件）。遵循最小权限原则，无注入向量，无硬编码凭据。

---

💡 改进建议代码示例

// 本次变更为协议定义文件和文档更新，无需代码修复示例
// 所有新增协议文件均遵循 Wayland 协议 XML 规范
// 废弃协议已正确标注替代方案

---

本报告由 AI 代码审查工具自动生成

[deepin-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: Groveer, wineee, zccrs

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