Grid workspace for the COSMIC compositor

COSMIC 合成器的工作区网格

How I patched the COSMIC compositor: a 5×5 workspace grid for Pop!_OS. Context: My workspaces are a map, not a scroll. One 4-finger swipe moves me north, south, east, or west across a 5×5 grid that wraps at the edges, and login drops me on the center cell — so no workspace is ever more than two gestures away, and my hands navigate it without looking. COSMIC, the desktop this runs on, is System76’s Rust/Wayland desktop environment for Pop!_OS, built on the Smithay compositor library and led by Victoria Brekenfeld (Drakulix). In stock COSMIC 1.0.0, workspaces live on a linear strip: a flat Vec that only supports vertical or horizontal movement. I wanted the bounded 5×5 grid with edge-wrapping that starts on the center cell.

我是如何为 COSMIC 合成器打补丁的：为 Pop!_OS 实现 5×5 工作区网格。背景：我的工作区是一张地图，而不是一个滚动条。四指滑动即可在 5×5 的网格中向北、南、东或西移动，且边缘支持循环；登录后我直接位于中心单元格——因此任何工作区距离我都不超过两次手势，我的双手无需注视即可完成导航。COSMIC 是 System76 为 Pop!_OS 开发的 Rust/Wayland 桌面环境，基于 Smithay 合成器库，由 Victoria Brekenfeld (Drakulix) 领导。在原版 COSMIC 1.0.0 中，工作区位于一个线性条上：一个仅支持垂直或水平移动的扁平 Vec<Workspace>。我想要的是一个带有边缘循环、从中心单元格开始的 5×5 有界网格。

Approach: I patched two crates: cosmic-comp, the compositor itself, and cosmic-workspaces, the overview app. Both are pinned to the exact versions installed on my machine (cosmic-comp at commit bb584aa, cosmic-workspaces at 1.0.12), and both carry a branch named cosmic-grid. The feature turns on with one line in the user RON config: workspace_grid: Some((5, 5)). The intellectual core of the patch is that a grid is a row-major mapping, not a workspace-model rewrite. idx = row * cols + col over the existing flat Vec. cosmic-comp already exposes 2D workspace coordinates end-to-end: set_workspace_coordinates emits the ext-workspace protocol Coordinates event, which cctk surfaces as WorkspaceInfo.coordinates, which cosmic-workspaces renders. The grid only changes how those coordinates are computed and rendered. Everything upstream of that pipeline stays stock.

方法：我为两个 crate 打了补丁：合成器本身 cosmic-comp 和概览应用 cosmic-workspaces。两者都锁定在我机器上安装的确切版本（cosmic-comp 为提交 bb584aa，cosmic-workspaces 为 1.0.12），并且都包含一个名为 cosmic-grid 的分支。该功能只需在用户 RON 配置文件中添加一行即可开启：workspace_grid: Some((5, 5))。该补丁的核心逻辑在于，网格是一种行优先映射，而非对工作区模型的重写。即在现有的扁平 Vec 上使用 idx = row * cols + col。cosmic-comp 已经实现了端到端的二维工作区坐标暴露：set_workspace_coordinates 会发出 ext-workspace 协议的 Coordinates 事件，cctk 将其呈现为 WorkspaceInfo.coordinates，并由 cosmic-workspaces 进行渲染。网格补丁仅改变了这些坐标的计算和渲染方式，该流水线的所有上游部分均保持原样。

The config decision was to add workspace_grid: Option<(u32, u32)> with #[serde(default)] to cosmic-comp-config/src/workspace.rs. An optional field, not a new WorkspaceLayout enum variant, so stock readers like cosmic-settings and the applets ignore it. No other package needed rebuilding or pinning. Gesture semantics preserve the existing natural-scroll convention exactly. Up/Down swipe means ±cols, Left/Right means ±1 over the flat Vec. Up/down muscle memory is unchanged; left/right is additive. Each axis wraps around independently. Login starts at the center cell (rows/2, cols/2). Workspaces are still created on demand and removed when empty, so RAM behavior matches stock.

配置决策是在 cosmic-comp-config/src/workspace.rs 中添加带有 #[serde(default)] 的 workspace_grid: Option<(u32, u32)>。这是一个可选字段，而不是新的 WorkspaceLayout 枚举变体，因此像 cosmic-settings 和小程序这样的原版读取器会忽略它。无需重新构建或锁定其他任何包。手势语义完全保留了现有的自然滚动惯例。向上/向下轻扫意味着 ±列数，向左/向右意味着在扁平 Vec 上 ±1。向上/向下的肌肉记忆保持不变；向左/向右是累加的。每个轴独立循环。登录时从中心单元格（行/2，列/2）开始。工作区仍然按需创建并在清空时移除，因此内存行为与原版一致。

The build and rollback story was designed for safety from day one. scripts/build.sh does cargo release builds. scripts/install.sh backs up the stock binaries to stock/, installs the patched binaries to /usr/bin/, and runs apt-mark hold on both packages so a system update can’t silently overwrite the patch. scripts/rollback.sh restores the archived originals and releases the holds. Reverting is one command. The archive is real: stock/cosmic-comp.orig at 27.3 MB and stock/cosmic-workspaces.orig at 30.2 MB.

构建和回滚方案从第一天起就考虑了安全性。scripts/build.sh 执行 cargo release 构建。scripts/install.sh 将原版二进制文件备份到 stock/，将打过补丁的二进制文件安装到 /usr/bin/，并对这两个包运行 apt-mark hold，以防止系统更新静默覆盖补丁。scripts/rollback.sh 负责恢复存档的原始文件并解除锁定。还原只需一条命令。存档是真实的：stock/cosmic-comp.orig 为 27.3 MB，stock/cosmic-workspaces.orig 为 30.2 MB。

(Architecture and Evidence sections omitted for brevity, focusing on the core implementation details provided above.)

(为简洁起见，省略了架构和证据部分，重点关注上述核心实现细节。)