feat: add normal role to dde-shell surface role enum

dde/README.md

@@ -17,7 +17,7 @@ For DDE desktop components. Installed via `TREELAND_PROTOCOL_DDE_XML_FILES`.
 | `treeland-xwindow-control-unstable-v1.xml` | `treeland_xwindow_control_unstable_v1` | `treeland_xwindow_control_v1` | XWayland window placement: move an XWayland window (by X11 window ID) to a position relative to another surface, with wl_callback result feedback |
 | `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-region-watch-unstable-v1.xml` | `treeland_region_watch_unstable_v1` | `treeland_region_watch_manager_v1`, `treeland_region_watch_v1` | Edge-anchored region overlap watch: register an edge-anchored region on an output and observe enter/leave overlap events with xdg-shell toplevels |
-| `treeland-dde-shell-unstable-v2.xml` | `treeland_dde_shell_unstable_v2` | `treeland_dde_shell_manager_v2`, `treeland_dde_shell_surface_v2` | DDE shell surface role: turn a wl_surface into a shell surface rendered below the wlr-layer-shell layer stack at the workspace overlay level, suggest an initial position relative to an output or the cursor, and declare switcher/dock-preview/multitask-view listing preferences via a skip bitfield |
+| `treeland-dde-shell-unstable-v2.xml` | `treeland_dde_shell_unstable_v2` | `treeland_dde_shell_manager_v2`, `treeland_dde_shell_surface_v2` | DDE shell surface role: turn a wl_surface into a shell surface rendered at the workspace overlay level (above normal toplevels, below layer-shell surfaces) or at the normal window layer, suggest an initial position relative to an output or the cursor, and declare switcher/dock-preview/multitask-view listing preferences via a skip bitfield |
 
 ## Breaking changes
 
@@ -46,7 +46,7 @@ The DDE-shell protocol interfaces consumed by DDE components are split into dedi
 - `treeland_dde_active_v1` (and its `get_treeland_dde_active` manager request) is non-functional and superseded by `treeland-active-notify-unstable-v1.xml` (`treeland_active_notify_manager_v1` / `treeland_active_notify_v1`): `get_active_notify` creates a per-seat notifier whose `activity_changed` event carries a `reason` enum and an `activity_state` enum (renamed from `active_in`/`active_out`; mouse tracks the left-button state, wheel is a per-event pulse), plus a `drag_changed` event carrying a `drag_state` enum (started/dropped/cancelled).
 - `treeland_window_overlap_checker` (and its `get_window_overlap_checker` manager request) is non-functional and superseded by `treeland-region-watch-unstable-v1.xml` (`treeland_region_watch_manager_v1` / `treeland_region_watch_v1`): the watcher interface gains the `_v1` suffix, the region request is renamed from `update` to `set_region` with an explicit `anchor` enum and `invalid_anchor`/`invalid_size` errors, and `output_removed` covers output lifetime.
 - `treeland_multitaskview_v1` and `treeland_lockscreen_v1` (with their creating requests) are superseded by the corresponding actions (`toggle_multitask_view`/`open_multitask_view`/`close_multitask_view` and `lockscreen`/`shutdown_menu`/`show_user_switch`) of `treeland-compositor-action-unstable-v1.xml` (`treeland_compositor_action_v1`).
-- `treeland_dde_shell_surface_v1` (and its `get_shell_surface` manager request) is superseded by `treeland-dde-shell-unstable-v2.xml` (`treeland_dde_shell_manager_v2` / `treeland_dde_shell_surface_v2`), in `dde/`; the surface role is carried over with a 0-based `role` enum and a merged `set_skip_flags` bitfield.
+- `treeland_dde_shell_surface_v1` (and its `get_shell_surface` manager request) is superseded by `treeland-dde-shell-unstable-v2.xml` (`treeland_dde_shell_manager_v2` / `treeland_dde_shell_surface_v2`), in `dde/`; the surface role is carried over with a `role` enum that adds `normal` (0) while keeping `overlay` (1), and a merged `set_skip_flags` bitfield.
 
 ### 0.6.0
 

dde/README.zh_CN.md

@@ -17,7 +17,7 @@
 | `treeland-xwindow-control-unstable-v1.xml` | `treeland_xwindow_control_unstable_v1` | `treeland_xwindow_control_v1` | XWayland 窗口定位：将 XWayland 窗口（按 X11 窗口 ID）移动到相对另一 surface 的位置，结果经 wl_callback 回报 |
 | `treeland-active-notify-unstable-v1.xml` | `treeland_active_notify_unstable_v1` | `treeland_active_notify_manager_v1`、`treeland_active_notify_v1` | Seat 活跃通知：订阅按 Seat 限定的指针按键/滚轮进入/离开活跃状态及拖拽/放下的生命周期事件 |
 | `treeland-region-watch-unstable-v1.xml` | `treeland_region_watch_unstable_v1` | `treeland_region_watch_manager_v1`、`treeland_region_watch_v1` | 沿输出边缘的区域重叠监控：注册锚定输出边缘的区域并订阅与 xdg-shell 顶层窗口重叠/解除重叠的 enter/leave 事件 |
-| `treeland-dde-shell-unstable-v2.xml` | `treeland_dde_shell_unstable_v2` | `treeland_dde_shell_manager_v2`、`treeland_dde_shell_surface_v2` | DDE Shell surface 角色：将 wl_surface 转为在 wlr-layer-shell 层叠之下、工作区 overlay 层渲染的 shell surface，建议相对输出或光标的初始位置，并通过 skip 位域声明任务切换器/dock 预览/多任务视图的列表偏好 |
+| `treeland-dde-shell-unstable-v2.xml` | `treeland_dde_shell_unstable_v2` | `treeland_dde_shell_manager_v2`、`treeland_dde_shell_surface_v2` | DDE Shell surface 角色：将 wl_surface 转为在工作区 overlay 层（高于普通顶层窗口、低于 layer-shell surface）或普通窗口层渲染的 shell surface，建议相对输出或光标的初始位置，并通过 skip 位域声明任务切换器/dock 预览/多任务视图的列表偏好 |
 
 ## 破坏性变更
 
@@ -46,7 +46,7 @@ DDE-shell 协议中被 DDE 组件消费的接口拆分为 `dde/` 下的专用协
 - `treeland_dde_active_v1`（含其创建请求 `get_treeland_dde_active`）已不可用，由 `treeland-active-notify-unstable-v1.xml`（`treeland_active_notify_manager_v1` / `treeland_active_notify_v1`）取代：`get_active_notify` 创建按 Seat 限定的通知对象，其 `activity_changed` 事件携带 `reason` 与 `activity_state` 枚举（由 `active_in`/`active_out` 更名；鼠标跟踪左键状态，滚轮为逐事件脉冲），并新增携带 `drag_state` 枚举（started/dropped/cancelled）的 `drag_changed` 事件。
 - `treeland_window_overlap_checker`（含其创建请求 `get_window_overlap_checker`）已不可用，由 `treeland-region-watch-unstable-v1.xml`（`treeland_region_watch_manager_v1` / `treeland_region_watch_v1`）取代：watcher 接口补上 `_v1` 后缀，设区域请求由 `update` 更名为 `set_region`，含显式 `anchor` 枚举与 `invalid_anchor`/`invalid_size` 错误，并新增 `output_removed` 覆盖输出生命周期。
 - `treeland_multitaskview_v1` 和 `treeland_lockscreen_v1`（含其创建请求）由 `treeland-compositor-action-unstable-v1.xml`（`treeland_compositor_action_v1`）的对应动作取代（`toggle_multitask_view`/`open_multitask_view`/`close_multitask_view` 与 `lockscreen`/`shutdown_menu`/`show_user_switch`）。
-- `treeland_dde_shell_surface_v1`（含其创建请求 `get_shell_surface`）由 `treeland-dde-shell-unstable-v2.xml`（`treeland_dde_shell_manager_v2` / `treeland_dde_shell_surface_v2`）取代，后者位于 `dde/`；surface 角色得以保留，`role` 枚举改为 0 基编号，skip 请求合并为 `set_skip_flags` 位域。
+- `treeland_dde_shell_surface_v1`（含其创建请求 `get_shell_surface`）由 `treeland-dde-shell-unstable-v2.xml`（`treeland_dde_shell_manager_v2` / `treeland_dde_shell_surface_v2`）取代，后者位于 `dde/`；surface 角色得以保留，`role` 枚举新增 `normal`（0）并保留 `overlay`（1），skip 请求合并为 `set_skip_flags` 位域。
 
 ### 0.6.0
 

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

@@ -71,9 +71,10 @@ SPDX-License-Identifier: MIT
     <interface name="treeland_dde_shell_surface_v2" version="1">
         <description summary="shell surface role">
             A shell surface object assigns the DDE shell surface role to a
-            wl_surface. A shell surface renders below the wlr-layer-shell
-            layer stack, at the overlay level of the workspace: above
-            normal toplevel windows but below layer-shell surfaces.
+            wl_surface. A shell surface renders either at the overlay level
+            of the workspace (above normal toplevel windows but below
+            layer-shell surfaces) or at the normal window layer, as
+            selected by the set_role request. The default role is overlay.
 
             The role carries no requests that map, commit, or configure
             buffer state; the client commits buffers with wl_surface
@@ -102,7 +103,8 @@ SPDX-License-Identifier: MIT
                 z depth. Multiple surfaces can share a single role, and
                 ordering within a single role is undefined.
             </description>
-            <entry name="overlay" value="0" summary="workspace overlay layer, above normal toplevels and below layer-shell surfaces" />
+            <entry name="normal" value="0" summary="normal window layer, below the overlay layer and participating in regular toplevel stacking" />
+            <entry name="overlay" value="1" summary="workspace overlay layer, above normal toplevels and below layer-shell surfaces" />
         </enum>
 
         <enum name="skip_flag" bitfield="true">
@@ -135,6 +137,10 @@ SPDX-License-Identifier: MIT
                 Assign the role identified by the role enum to this shell
                 surface, selecting the layer it renders in. The default
                 role before this request is overlay.
+
+                Assigning the normal role returns the surface to the
+                regular window layer, participating in normal toplevel
+                stacking again.
             </description>
             <arg name="role" type="uint" enum="role" summary="the rendering layer for this surface" />
         </request>

public/README.md

@@ -25,12 +25,12 @@ The whole file is deprecated and moved to `deprecated/`. It is superseded by `tr
 Wire-level differences between v1 and v2:
 
 1. Only the surface role is carried over. The manager exposes just `get_shell_surface` with a new `already_shell_surface` error; the factory requests for the superseded interfaces (`get_window_overlap_checker`, `get_treeland_dde_active`, `get_treeland_multitaskview`, `get_treeland_window_picker`, `get_treeland_lockscreen`) and the `set_xwindow_position_relative` request are not carried over.
-2. The `role` enum is renumbered to 0-based: `overlay` changes from 1 to 0, and its semantics are stated precisely (above normal toplevels, below layer-shell surfaces).
+2. The `role` enum gains a `normal` value at 0 while `overlay` keeps its v1 value of 1; both semantics are stated precisely (`normal` is the regular window layer, `overlay` is above normal toplevels and below layer-shell surfaces).
 3. The three skip requests (`set_skip_switcher`, `set_skip_dock_preview`, `set_skip_muti_task_view`, the latter also fixing the "muti" typo) are merged into a single `set_skip_flags` request taking a `skip_flag` bitfield (`switcher` 0x1, `dock_preview` 0x2, `multitask_view` 0x4).
 4. The placement requests are reworked into two hints whose final position the compositor decides: `set_position_hint` suggests fixed coordinates relative to an output (null for the primary output), and `set_cursor_placement_hint` suggests a position relative to the cursor with an `int` y_offset (v1 used `uint`). The mutual exclusivity of the two requests (most recent wins) is now specified.
 5. The v2 globals must reject binds from non-privileged clients.
 
-Consumers should rebind as `treeland_dde_shell_manager_v2`, recreate shell surfaces through `get_shell_surface`, switch to `set_skip_flags`, and treat `overlay` as 0; window-picker consumers have no replacement and must drop the functionality. The old XML is kept installed during migration but must not be used in new code.
+Consumers should rebind as `treeland_dde_shell_manager_v2`, recreate shell surfaces through `get_shell_surface`, switch to `set_skip_flags`, and treat `overlay` as 1 (unchanged) while `normal` (0) restores the regular window layer; window-picker consumers have no replacement and must drop the functionality. The old XML is kept installed during migration but must not be used in new code.
 
 The manager request `set_xwindow_position_relative` and the `treeland_dde_active_v1` and `treeland_window_overlap_checker` interfaces (with their creating manager requests `get_treeland_dde_active` and `get_window_overlap_checker`) are deprecated and non-functional: they have no effect and no events are ever emitted (their `destroy` requests remain functional so clients can release the objects).
 

public/README.zh_CN.md

@@ -26,12 +26,12 @@
 v1 与 v2 的线缆级差异：
 
 1. 仅 surface 角色得以保留。管理器只暴露 `get_shell_surface` 并新增 `already_shell_surface` 错误；被取代接口的工厂请求（`get_window_overlap_checker`、`get_treeland_dde_active`、`get_treeland_multitaskview`、`get_treeland_window_picker`、`get_treeland_lockscreen`）及 `set_xwindow_position_relative` 请求不再保留。
-2. `role` 枚举改为 0 基编号：`overlay` 由 1 改为 0，且语义明确化（高于普通顶层窗口、低于 layer-shell surface）。
+2. `role` 枚举新增 0 值的 `normal`，`overlay` 保留 v1 的值 1；两者语义明确化（`normal` 为普通窗口层，`overlay` 高于普通顶层窗口、低于 layer-shell surface）。
 3. 三个 skip 请求（`set_skip_switcher`、`set_skip_dock_preview`、`set_skip_muti_task_view`，最后一个同时修正 "muti" 拼写错误）合并为单一的 `set_skip_flags` 请求，携带 `skip_flag` 位域（`switcher` 0x1、`dock_preview` 0x2、`multitask_view` 0x4）。
 4. 放置请求重构为两个提示（最终位置由合成器决定）：`set_position_hint` 建议相对输出（null 为主屏）的固定坐标，`set_cursor_placement_hint` 建议相对光标的位置（y_offset 为 `int`，v1 为 `uint`）。两请求的互斥关系（最近发送者生效）现已明确。
 5. v2 全局对象必须拒绝非特权客户端绑定。
 
-消费者应改绑为 `treeland_dde_shell_manager_v2`，通过 `get_shell_surface` 重建 shell surface，改用 `set_skip_flags`，并将 `overlay` 视为 0；窗口选取消费者无替代，须移除该功能。旧 XML 在迁移期间仍会安装，但不得用于新代码。
+消费者应改绑为 `treeland_dde_shell_manager_v2`，通过 `get_shell_surface` 重建 shell surface，改用 `set_skip_flags`，并将 `overlay` 视为 1（不变），以 `normal`（0）还原普通窗口层；窗口选取消费者无替代，须移除该功能。旧 XML 在迁移期间仍会安装，但不得用于新代码。
 
 管理器的 `set_xwindow_position_relative` 请求及 `treeland_dde_active_v1`、`treeland_window_overlap_checker` 接口（含其创建请求 `get_treeland_dde_active`、`get_window_overlap_checker`）已废弃且不可用：请求无任何效果，也不会发出任何事件（`destroy` 请求仍然可用，客户端可借此释放对象）。