feat: add output-mirror protocol, deprecate virtual-output-v1

CMakeLists.txt

@@ -29,7 +29,9 @@ set(TREELAND_PROTOCOL_DDE_XML_FILES
   dde/treeland-shortcut-manager-unstable-v3.xml
   dde/treeland-compositor-action-unstable-v1.xml
   dde/treeland-appearance-manager-unstable-v1.xml
-  dde/treeland-virtual-output-manager-v1.xml
+  dde/treeland-output-group-manager-unstable-v1.xml
+  dde/treeland-output-uuid-unstable-v1.xml
+  dde/treeland-output-uuid-head-unstable-v1.xml
   dde/treeland-wallpaper-manager-unstable-v1.xml
   dde/treeland-layer-shell-extension-unstable-v1.xml
   dde/treeland-xwindow-control-unstable-v1.xml
@@ -68,6 +70,7 @@ set(TREELAND_PROTOCOL_DEPRECATED_XML_FILES
   deprecated/treeland-wallpaper-color-v1.xml
   deprecated/treeland-window-management-v1.xml
   deprecated/treeland-foreign-toplevel-manager-v1.xml
+  deprecated/treeland-virtual-output-manager-v1.xml
 )
 
 option(TREELAND_PROTOCOLS_INSTALL_DEPRECATED "Install deprecated protocol files" ON)

dde/README.md

@@ -7,11 +7,13 @@ For DDE desktop components. Installed via `TREELAND_PROTOCOL_DDE_XML_FILES`.
 | `treeland-foreign-toplevel-manager-unstable-v2.xml` | `treeland_foreign_toplevel_manager_unstable_v2` | `treeland_foreign_toplevel_manager_v2`, `treeland_foreign_toplevel_handle_v2`, `treeland_dock_preview_context_v2` | Redesigned toplevel observation and dock preview; fixes naming, member ordering, destroy placement, and description quality relative to v1 |
 | `treeland-input-manager-unstable-v1.xml` | `treeland_input_manager_unstable_v1` | `treeland_input_manager_v1`, `treeland_pointer_device_configuration_v1`, `treeland_mouse_settings_v1`, `treeland_touchpad_settings_v1`, `treeland_keyboard_settings_v1` | Per-device input configuration: pointer acceleration, send-events mode, keyboard toggle state, and XKB keymap settings |
 | `treeland-keyboard-state-notify-unstable-v1.xml` | `treeland_keyboard_state_notify_unstable_v1` | `treeland_keyboard_state_notify_manager_v1`, `treeland_keyboard_state_watcher_v1` | Watch keyboard modifier (caps/num lock) state changes |
-| `treeland-output-manager-unstable-v2.xml` | `treeland_output_manager_unstable_v2` | `treeland_output_manager_v2`, `treeland_output_picture_control_v2` | Primary output designation, per-output color temperature and brightness control |
+| `treeland-output-manager-unstable-v2.xml` | `treeland_output_manager_unstable_v2` | `treeland_output_manager_v2`, `treeland_output_picture_control_v2` | Primary output designation, per-output color temperature and brightness control; outputs addressed by uuid |
 | `treeland-shortcut-manager-unstable-v3.xml` | `treeland_shortcut_manager_unstable_v3` | `treeland_shortcut_manager_v3`, `treeland_shortcut_capture_v3` | Global keyboard shortcut binding with key/touch/multi-touch gesture support and one-shot shortcut capture |
 | `treeland-compositor-action-unstable-v1.xml` | `treeland_compositor_action_unstable_v1` | `treeland_compositor_action_v1` | One-shot privileged triggering of window-independent compositor actions: workspace switching, show-desktop, multitask overview, screen zoom, FPS overlay, lockscreen, shutdown menu, user switch; window-level and task-switch actions are intentionally excluded and remain only as shortcuts in `treeland_shortcut_manager_v3` |
 | `treeland-appearance-manager-unstable-v1.xml` | `treeland_appearance_manager_unstable_v1` | `treeland_appearance_manager_v1` | Privileged user-level appearance configuration: cursor theme/size, global font, icon theme, accent color, window opacity, color scheme, titlebar height, global corner radius |
-| `treeland-virtual-output-manager-v1.xml` | `treeland_virtual_output_manager_v1` | `treeland_virtual_output_manager_v1`, `treeland_virtual_output_v1` | Virtual (mirrored) output creation and management |
+| `treeland-output-uuid-unstable-v1.xml` | `treeland_output_uuid_unstable_v1` | `treeland_output_uuid_manager_v1`, `treeland_output_uuid_v1` (frozen) | Stable opaque uuid identity for `wl_output` objects; the uuid is shared with the head variant and consumed by other output protocols |
+| `treeland-output-uuid-head-unstable-v1.xml` | `treeland_output_uuid_head_unstable_v1` | `treeland_output_uuid_head_manager_v1` | Companion to `treeland-output-uuid-unstable-v1`: obtain the same `treeland_output_uuid_v1` object from a `zwlr_output_head_v1` (wlr-output-management), including disabled outputs with no live `wl_output` |
+| `treeland-output-group-manager-unstable-v1.xml` | `treeland_output_group_manager_unstable_v1` | `treeland_output_group_manager_v1`, `treeland_output_group_v1` | Output mirroring (copy mode) groups: designate a source output mirrored to one or more mirror outputs, addressed by uuid, with registry-pattern enumeration |
 | `treeland-wallpaper-manager-unstable-v1.xml` | `treeland_wallpaper_manager_unstable_v1` | `treeland_wallpaper_manager_v1`, `treeland_wallpaper_v1` | Per-output wallpaper configuration with image/video sources |
 | `treeland-layer-shell-extension-unstable-v1.xml` | `treeland_layer_shell_extension_unstable_v1` | `treeland_layer_shell_extension_manager_v1`, `treeland_layer_shell_extension_object_v1` | Compositor-driven interactive resize for layer-shell surfaces (dock / side bar / status bar): begin_resize with seat+serial, per-resize size limits, and rejection reasons |
 | `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 |
@@ -48,20 +50,34 @@ The DDE-shell protocol interfaces consumed by DDE components are split into dedi
 - `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 `role` enum that adds `normal` (0) while keeping `overlay` (1), and a merged `set_skip_flags` bitfield.
 
-### 0.6.0
-
 #### `treeland-output-manager-v1.xml`
 
-Superseded by `treeland-output-manager-unstable-v2.xml`; the old v1 file moved to `deprecated/` unchanged. The v2 protocol renames both interfaces, normalizes member ordering, and switches primary-output identification from output names to `wl_output` objects. Wire-level differences:
+Superseded by `treeland-output-manager-unstable-v2.xml`; the old v1 file moved to `deprecated/` unchanged. The v2 protocol renames both interfaces, normalizes member ordering, and addresses outputs by opaque uuid strings from the new `treeland-output-uuid-unstable-v1` protocol instead of output names or `wl_output` objects. Wire-level differences:
 
-1. Interfaces renamed: `treeland_output_manager_v1` → `treeland_output_manager_v2` and `treeland_output_color_control_v1` → `treeland_output_picture_control_v2`; interface versions reset to 1 and the `since="2"` markers were removed.
+1. Interfaces renamed: `treeland_output_manager_v1` → `treeland_output_manager_v2` and `treeland_output_color_control_v1` → `treeland_output_picture_control_v2`; interface versions reset to 1.
 2. `destroy` moved to the first request on both interfaces, shifting the opcodes of all other requests by one.
-3. `set_primary_output` now takes a non-null, enabled `wl_output` object instead of an output name `string`; passing a disabled or destroyed output is rejected via a `primary_output_failed` event rather than a protocol error. The compositor no longer supports clearing the primary designation via a null argument.
-4. The `primary_output` event now carries a `wl_output` object (null only when no output is available) instead of an output name `string`, is emitted once immediately after bind, and confirms every `set_primary_output` request. When the designated primary output is disconnected or disabled, the compositor automatically selects another available output as the new primary and emits this event.
-5. The `result` event argument changed from a plain `uint` flag (1 = success, 0 = failure) to the new `commit_result` enum (`success = 0`, `failed = 1`, `unsupported = 2`, `invalid_output = 3`), so the wire values are inverted.
-6. The picture control `error` enum is retained on the renamed `treeland_output_picture_control_v2` interface; its `invalid_color_temperature`/`invalid_brightness` entries keep the same names but their values reset from 1/2 to 0/1 following the interface version reset, and the fatal-protocol-error behavior on out-of-range `set_*` values is unchanged. `commit_result` therefore carries only success and output-related failure causes (no range entries); enums moved before requests, and a `primary_output_failed_reason` enum backs the new `primary_output_failed` event. `get_picture_control` accepts any valid `wl_output` regardless of state — invalid object ids remain a core protocol error; output validity is reported at commit time through the `result` event.
+3. `set_primary_output` takes a `string uuid` instead of an output name or `wl_output` object; an empty uuid is a fatal `error.invalid_uuid`, and a uuid with no connected enabled output is rejected via the `primary_output_failed` event (reason `invalid_output`).
+4. The `primary_output` event carries a `string uuid` (empty when no primary output is designated) instead of an output name or `wl_output` object, is emitted once on bind, and confirms every `set_primary_output` request.
+5. `get_picture_control` takes a `string uuid`; an empty uuid, or a uuid with no recognized connected output, is a fatal `error.invalid_uuid` (the object is not created, so the initial-state contract holds).
+6. The `result` event argument changed from a plain `uint` flag (1 = success, 0 = failure) to the `commit_result` enum (`success = 0`, `failed = 1`, `unsupported = 2`, `invalid_output = 3`), so the wire values are inverted.
+
+Consumers should rebind the global as `treeland_output_manager_v2`, obtain output uuids from `treeland_output_uuid_manager_v1.get_uuid`, pass uuid strings instead of output names or `wl_output` objects, and interpret `result` values via the `commit_result` enum.
+
+#### `treeland-virtual-output-manager-v1.xml`
 
-Consumers should rebind the global as `treeland_output_manager_v2`, pass `wl_output` objects instead of output names, and interpret `result` values via the `commit_result` enum; the old v1 XML is kept installed during migration but must not be used in new code.
+Superseded by `treeland-output-group-manager-unstable-v1.xml`; the old v1 file moved to `deprecated/` unchanged. The protocol was redesigned around uuid-based output identity instead of output-name strings, with explicit source/mirror separation, a registry-pattern enumeration model, and fully specified object lifecycles. Wire-level differences:
+
+1. Protocol and interfaces renamed: `treeland_virtual_output_manager_v1` → `treeland_output_group_manager_unstable_v1`, with interfaces `treeland_virtual_output_manager_v1` → `treeland_output_group_manager_v1` and `treeland_virtual_output_v1` → `treeland_output_group_v1`; interface versions reset to 1.
+2. Output identity switched from name strings to uuids: the `name`/`outputs` `string`/`array` arguments of `create_virtual_output`, the `names` `array` argument of the `virtual_output_list` event, and the `outputs` `array` argument of the `outputs` event are all removed. The new `create_group` request takes a group `name` `string` and an initial `source` uuid `string` (empty for no source), so a group is created with its source already set and observers never see an empty-source group; mirrors are added with `add_output` and the source changed with `set_source`. Outputs are referenced by uuid strings on the group's `set_source`, `add_output`, and `remove_output` requests and on its `source`, `output_added`, and `output_removed` events. The old `outputs[0] = source, outputs[1..] = mirrors` positional convention is replaced by an explicit `set_source` request and an ordered `add_output`/`remove_output` mirror list, with the `source` event reporting the current source uuid (empty when the group has no source). A non-empty source that does not identify a connected enabled output is rejected with the new fatal manager error `invalid_source`.
+3. Enumeration replaced by a registry push model: the `get_virtual_output_list` request and the `virtual_output_list` snapshot event are removed. On binding the manager the compositor emits one `group_added` event (carrying a fresh group object) per existing group, and again whenever a group is created; `group_removed` is emitted when a group is dissolved. This removes the list-then-lookup TOCTOU window.
+4. The `get_virtual_output` request is removed; clients obtain handles to existing groups from the bind-time `group_added` dump or from later `group_added` events, so the unknown-name fatal-error path no longer exists.
+5. The per-group `error` event is removed. Failures are split by severity: manager errors `invalid_name` (empty, non-UTF-8, or NUL-containing name) and `name_exists` (duplicate) are fatal protocol errors; group business failures — `invalid_output`, `duplicate_output`, `output_in_use`, `not_in_group` — are non-fatal and reported via the new `operation_failed` event (code + uuid), so transient output state like an unplug between `get_uuid` and the request does not terminate the connection. Only `already_dissolved` (any request other than `destroy` on a dissolved group) remains a fatal group protocol error. The old codes `invalid_group_name` (0), `invalid_screen_number` (1), and `invalid_output` (2) no longer exist.
+6. Object lifecycle redefined: destroying a group object (`destroy`) now only releases that client's handle and does not dissolve the group or affect other clients; a separate `dissolve` request tears down the group, emitting `removed` to all bound group objects and `group_removed` on the manager. The old behavior, where any client destroying its `treeland_virtual_output_v1` object (including one obtained via `get_virtual_output`) dissolved the group, is removed. Initial state is now pushed: a `source` event (empty uuid when no source) followed by one `output_added` per mirror is emitted immediately on every group object's creation, so clients no longer start with unknown state.
+7. Source-successor behavior on hardware removal is retained and made explicit: when the source output is unplugged or disabled and mirrors remain, the first remaining mirror becomes the new source (the compositor emits `output_removed` then `source` for it); client-driven `remove_output` of the source instead clears it (emits `source` with an empty uuid) and does not auto-select a successor.
+
+Consumers should rebind the global as `treeland_output_group_manager_v1`, obtain `treeland_output_group_v1` objects from the `group_added` event (or as the return value of `create_group`), reference outputs by uuid via `set_source`/`add_output`/`remove_output`, and dissolve groups with `dissolve` rather than by destroying a group object; the old v1 XML is kept installed during migration but must not be used in new code.
+
+### 0.6.0
 
 #### `treeland-personalization-manager-v1.xml`