[deepin-wm]

解决什么问题

Dock（任务栏）的整体显隐动画、边缘唤出、智能隐藏重叠判断与预留区域目前由 dde-shell 自己完成，与合成器负责的窗口最大化/还原、全屏退出、多任务视图、输出配置变化等动画互相竞争，容易出现空缺、跳变和双方重复控制。

本 PR 只新增协议定义，把上述整体行为交给合成器统一决策与执行；dde-shell 继续绘制 Dock 内容，并通过协议上报合成器无法自行获知的信息。

改了哪些地方

• 新增 dde/treeland-dock-unstable-v1.xml
  • treeland_dock_manager_v1：get_dock(id, surface, mode, policy) 把一个已有的 wlr-layer-shell surface 转为受管 Dock，already_dock_surface / invalid_surface / invalid_mode / invalid_output_policy 为创建期错误
  • treeland_dock_v1
    • 上报侧：set_visibility_mode（always_visible / smart_hide / always_hidden）、set_output_policy（primary_only / any_output，只决定哪些输出装边缘唤出条带）、get_hold（每个交互一个 hold 对象，拒绝自动隐藏但不主动显示）、set_forced_visibility（按 reason 逐个设置/清除，如启动器）
    • 事件侧：visibility(visible, reason) 只在目标可见状态变化时下发并说明原因；edge_wake(output) 每次指针触边都下发，与目标状态是否变化无关，客户端据此决定是否迁屏
    • output_conflict：同一输出上出现第二个受管 Dock 时按协议错误处理
  • treeland_dock_hold_v1：hold 的生命周期对象
  • 协议明确决策口径：模式给出基线，fullscreen 与顶层窗口压住条带是唯一的隐藏来源，hold 只取消隐藏触发，forced 与多任务视图覆盖为显示；多任务视图退出后按原规则重判而不是恢复打开前状态
  • 跨输出唤出：触碰的条带不在 Dock 所在输出时，合成器等客户端把 surface 迁过来再播唤出（或超时后在原输出唤出），避免在旧输出闪一下
  • 预留区域与重叠监控条带统一为"整条输出边 × Dock 厚度"，合成器忽略客户端在此 surface 上设置的 layer-shell exclusive zone 并只预留一次
• CMakeLists.txt：在 TREELAND_PROTOCOL_DDE_XML_FILES 末尾追加该 XML
• dde/README.md / dde/README.zh_CN.md：各追加一行接口表

为什么这么改

• 隐藏采用"合成器把 surface 移出输出"而不是取消映射，唤出时不需要重新映射与重绘，动画不会等待 buffer。
• 厚度、时长、曲线不进协议：厚度沿用 layer-shell surface 状态与既有的交互式缩放，产品行为（含触发时机与优先级）沿原实现，不借迁移重新设计。
• 唯一新增行为是进入多任务视图强制显示 Dock；退出后按原规则重判，不改用户设置。
• Dock 迁移到哪个输出仍由客户端决定，edge_wake 只报告指针触了哪个输出；output_policy 是保住 Show_In_Primary 现有语义的最小手段。
• 本 PR 只含协议，treeland 合成器实现与 dde-shell 迁移是后续独立 PR，协议里已给双方留出迁移点（surface 保持 layer-shell 角色、客户端不再自建唤出条带与显隐动画）。

验证

• ./check-protocol-xml.sh 全仓通过（唯一告警是既有文件 deprecated/treeland-shortcut-manager-v2.xml:291 的历史问题）
• wayland-scanner 的 client-header / server-header / private-code / public-code 均可生成
• 协议内容经多轮评审确认一致（决策优先级、hold 与 forced 边界、跨输出唤出、销毁顺序、未知枚举值处理）

issue: WM-934

Summary by Sourcery

Introduce an experimental protocol that lets the compositor centrally coordinate dock visibility and reserved space while the client continues to render dock content and report client-only state.

New Features:

• Add the experimental treeland-dock-unstable-v1 protocol for compositor-managed dock visibility, edge wake-up, smart-hide behavior, forced visibility, interaction holds, and reserved output areas.

Enhancements:

• Define compositor and client responsibilities for dock visibility decisions, cross-output wake-up, multitask-view overrides, output conflicts, and lifecycle handling.

Build:

• Register the new dock protocol XML in the CMake protocol file list.

Documentation:

• Document the new dock protocol in the English and Chinese DDE protocol indexes.

[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: deepin-wm

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

This protocol-only PR adds an experimental treeland-dock-unstable-v1 interface that lets the compositor centrally manage Dock visibility, animation, edge wake-up, overlap behavior, multitask overrides, and reserved space while the shell continues to own Dock content and reports client-observable state such as modes, holds, forced visibility, and output policy.

Sequence diagram for Dock edge wake-up across outputs

sequenceDiagram
    actor User
    participant Compositor
    participant Shell
    participant DockSurface

    User->>Compositor: Pointer touches armed edge
    Compositor-->>Shell: edge_wake(output)
    Shell->>DockSurface: Move surface to touched output
    Compositor->>DockSurface: Start compositor-managed reveal animation
    Compositor-->>Shell: visibility(visible, edge_wake)

Loading

State diagram for compositor Dock visibility decisions

stateDiagram-v2
    [*] --> ModeBaseline
    ModeBaseline --> Visible: forced visibility or multitask view
    ModeBaseline --> Visible: edge wake
    ModeBaseline --> Hidden: always_hidden
    ModeBaseline --> Hidden: fullscreen or window overlap
    Hidden --> Visible: edge wake
    Hidden --> Visible: forced visibility or multitask view
    Hidden --> Visible: hold cancels hide trigger
    Visible --> Hidden: fullscreen or window overlap
    Visible --> ModeBaseline: hold released
    Visible --> ModeBaseline: forced visibility cleared
    Visible --> ModeBaseline: multitask view exits
    Hidden --> ModeBaseline: forced visibility cleared
    Hidden --> ModeBaseline: multitask view exits

Loading

File-Level Changes

Change	Details	Files
Adds the experimental compositor-managed Dock protocol and defines the compositor/client responsibility boundary for visibility, wake-up, animation, overlap handling, and reserved space.	Introduces manager, dock, and per-interaction hold interfaces. Converts an existing layer-shell surface into a managed Dock with creation-time validation and per-output conflict errors. Defines visibility modes, output wake policies, forced-visibility reasons, and informational visibility reasons. Specifies compositor-owned visibility decisions, animation, multitask/fullscreen/overlap behavior, edge wake events, cross-output migration coordination, and reserved-area derivation. Defines unknown-value handling and object/surface destruction ordering.	dde/treeland-dock-unstable-v1.xml
Registers the new protocol for build-time generation and documents its public DDE protocol interfaces.	Adds the Dock XML to the DDE protocol file list. Adds English and Chinese interface catalog entries.	CMakeLists.txt dde/README.md dde/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.