✨ Add Mark

Author: Asthestarsfalll

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "piri"
-version = "0.1.5"
+version = "0.1.6"
 edition = "2021"
 authors = ["Starfall"]
 description = "Extend niri compositor capabilities with extensible command system and plugins"

README.en.md

@@ -13,9 +13,22 @@ Piri is a high-performance [Niri](https://github.com/YaLTeR/niri) extension tool
 - 🎯 **Window Rule**: Powerful rule engine. Automatically places windows based on regex matching and provides focus-triggered command execution with a built-in de-duplication mechanism (see [Window Rule Docs](docs/en/plugins/window_rule.md))
 - 📐 **Workspace Rule**: Workspace window layout management. Provides automatic width adjustment, automatic tiling, automatic alignment, and automatic maximization. Integrates original Autofill functionality (see [Workspace Rule Docs](docs/en/plugins/workspace_rule.md))
 - 🔒 **Singleton**: Single-instance assurance. Ensures specific applications remain globally unique, supporting quick focus or automatic process launching (see [Singleton Docs](docs/en/plugins/singleton.md))
+- 📌 **Mark**: Named window marks for quick focus. Bind the focused window to a name and jump back later; bindings are in-memory only (see [Mark Docs](docs/en/plugins/mark.md))
 - 📋 **Window Order**: Intelligent reordering. Automatically reorders tiled windows based on configured weights, preserving relative positions for identical weights to minimize movement (see [Window Order Docs](docs/en/plugins/window_order.md))
 - 🍽️ **Swallow**: Window swallowing mechanism. Automatically hides parent windows when child windows are opened, allowing child windows to replace parent windows in the layout (see [Swallow Docs](docs/en/plugins/swallow.md))
 
+## Window Matching
+
+Piri uses a unified window matching mechanism: regex on `app_id` and/or `title`. Plugins such as `window_rule`, `singleton`, and `scratchpads` use it to find windows.
+
+**Supported matching**:
+- Full regular expression syntax
+- Match `app_id` and/or `title`
+- If both are set, **either** match can satisfy the rule (OR)
+
+> **Note**: The Window Rule plugin also supports list matching for `app_id` and `title`; see [Window Rule Docs](docs/en/plugins/window_rule.md).
+
+**Details**: [Window matching](docs/en/window_matching.md)
 
 ## Quick Start
 
@@ -325,6 +338,34 @@ piri singleton {name} toggle
 
 For detailed documentation, please refer to the [Singleton documentation](docs/en/plugins/singleton.md).
 
+### Mark
+
+Assign **named marks** (e.g. letters `a`, `b`) to windows for quick focus. Marks are kept in the daemon’s memory and are **cleared when the daemon restarts**. You only enable the plugin in `piri.toml` and bind `spawn` commands in Niri for marks you use often.
+
+**Configuration example**:
+
+```toml
+[piri.plugins]
+mark = true
+```
+
+**Quick usage**:
+
+```bash
+# No valid binding: bind focused window to name; binding exists and window lives: focus it
+piri mark {name} toggle
+
+# Force-bind focused window to name (overwrites previous binding)
+piri mark {name} add
+
+# Remove this mark
+piri mark {name} delete
+```
+
+**Note**: Piri cannot capture the “next key” globally. To save shortcut slots, you can use a launcher (e.g. `fuzzel`) to pick a letter, then run the commands above. If Niri adds multi-key sequences or binding modes, you can group `piri mark …` calls under one prefix.
+
+For detailed documentation, see the [Mark documentation](docs/en/plugins/mark.md).
+
 ### Window Order
 
 ![Window Order - Manual Trigger](./assets/window_order.mp4)

README.md

@@ -13,6 +13,7 @@ Piri 是基于 Rust 的 [Niri](https://github.com/YaLTeR/niri) 高性能功能
 - 🎯 **Window Rule**: 强大规则引擎。基于正则匹配实现窗口自动归位，并提供带去重机制的焦点触发命令执行（详见 [Window Rule 文档](docs/zh/plugins/window_rule.md)）
 - 📐 **Workspace Rule**: 工作区窗口布局管理。提供自动宽度调整、自动平铺、自动对齐和自动最大化等功能，整合了原 Autofill 功能（详见 [Workspace Rule 文档](docs/zh/plugins/workspace_rule.md)）
 - 🔒 **Singleton**: 单实例保障。确保特定应用全局唯一，支持快速聚焦现有实例或自动拉起新进程（详见 [Singleton 文档](docs/zh/plugins/singleton.md)）
+- 📌 **Mark**: 窗口标记与快速聚焦。用名称绑定当前窗口，再次触发可跳回该窗口；绑定仅存于内存（详见 [Mark 文档](docs/zh/plugins/mark.md)）
 - 📋 **Window Order**: 智能窗口排序。根据配置权重自动重排平铺窗口，相同权重窗口保持相对位置以最小化移动损耗（详见 [Window Order 文档](docs/zh/plugins/window_order.md)）
 - 🍽️ **Swallow**: 窗口吞噬机制。当子窗口打开时自动隐藏父窗口，让子窗口在布局中替换父窗口的位置（详见 [Swallow 文档](docs/zh/plugins/swallow.md)）
 
@@ -345,6 +346,34 @@ piri singleton {name} toggle
 
 详细说明请参考 [Singleton 文档](docs/zh/plugins/singleton.md)。
 
+### Mark
+
+为窗口设置**命名标记**（如字母 `a`、`b`），用于快速聚焦。标记在守护进程内存中维护，**重启 daemon 后会清空**；无需在 `piri.toml` 里为每个标记写配置，只需启用插件并在 Niri 里为常用标记绑定 `spawn` 命令。
+
+**配置示例**：
+
+```toml
+[piri.plugins]
+mark = true
+```
+
+**快速使用**：
+
+```bash
+# 无有效绑定时：把当前焦点窗口绑定到名称；已有且窗口仍在：聚焦该窗口
+piri mark {name} toggle
+
+# 强制把当前窗口绑定到名称（覆盖原绑定）
+piri mark {name} add
+
+# 删除该标记
+piri mark {name} delete
+```
+
+**说明**：Piri 无法全局捕获「下一个按键」；若希望少占快捷键，可配合启动器（如 `fuzzel`）选字母后再调用上述命令。Niri 若支持多键序列或绑定模式，可将多条 `piri mark …` 收拢在同一前缀下。
+
+详细说明请参考 [Mark 文档](docs/zh/plugins/mark.md)。
+
 ### Window Order
 
 ![Window Order - 手动触发](./assets/window_order.mp4)

docs/en/plugins/mark.md

@@ -0,0 +1,67 @@
+# Mark Plugin
+
+The Mark plugin provides **named quick-focus targets**: bind a string (often a single letter, e.g. `a`) to the current window, then jump back to that window using the same name. Bindings live in the daemon’s memory only; **nothing is written to the config file**.
+
+## Configuration
+
+Enable the plugin:
+
+```toml
+[piri.plugins]
+mark = true
+```
+
+No extra `[mark.*]` tables are required; all marks are created or removed at runtime via the CLI.
+
+## Command Line
+
+```bash
+# If the mark points to a window that still exists → focus it; else bind the focused window to this mark
+piri mark {name} toggle
+
+# Remove this mark (success even if it did not exist)
+piri mark {name} delete
+
+# Bind the focused window to this mark (replaces any previous binding)
+piri mark {name} add
+```
+
+Examples:
+
+```bash
+piri mark a toggle   # First time: mark current window as a; later: jump to a
+piri mark a add      # Force re-bind current window to a
+piri mark a delete   # Clear a
+```
+
+## Behavior
+
+1. **`toggle`**: If `name` is bound and the window still exists, **focus** that window; otherwise (unbound or window closed) **bind** the currently focused window to `name`.
+2. **`add`**: Always sets `name` to the current focus, overwriting any previous binding without checking the old window.
+3. **`delete`**: Removes the binding for `name`; idempotent.
+
+To **change** which window a mark points to while the old binding is still valid, use **`add`**, or **`delete`** then **`toggle`**.
+
+## Niri Keybindings
+
+Piri cannot listen for the “next key” by itself. In Niri you typically add one `spawn` per mark you care about, for example:
+
+```kdl
+binds {
+    Mod+Shift+A { spawn "piri" "mark" "a" "toggle"; }
+    Mod+Shift+B { spawn "piri" "mark" "b" "toggle"; }
+}
+```
+
+If Niri gains multi-key sequences or binding modes, you can group these under one prefix. See the main README for context.
+
+## Limitations
+
+- **Not persistent**: All marks are lost when `piri daemon` restarts.
+- **No on-window labels**: Niri IPC does not provide drawing mark letters on window decorations; use a bar, notifications, or an external script if you need a visible list.
+- **Requires focus**: `toggle` / `add` use the **currently focused** window; focus the target before invoking.
+
+## Use Cases
+
+- Short-lived bookmarks for a few windows you switch between often.
+- Pairing with a launcher (e.g. `fuzzel` listing `a`–`z` then calling `piri mark …`) so you do not type the mark name manually every time.

docs/en/plugins/plugins.md

@@ -22,6 +22,14 @@ Executes commands when switching to specific empty workspaces. Useful for automa
 - Workspace-based configuration
 - Similar to Hyprland's `on-created-empty` workspace rule
 
+### [Mark Plugin](mark.md)
+
+Named marks for windows via `piri mark …`: bind the focused window or jump back to a marked window. Bindings are kept in daemon memory only; no per-mark tables in the config.
+
+**Key features**:
+- `toggle`, `add`, and `delete` operations
+- Works well with Niri `spawn` keybindings or a launcher
+
 ### [Window Rule Plugin](window_rule.md)
 
 Automatically moves windows to specified workspaces based on their `app_id` or `title`. Useful for automating window management and organizing applications.
@@ -50,10 +58,14 @@ You can control which plugins are enabled or disabled in the configuration file:
 scratchpads = true
 empty = true
 window_rule = true
-autofill = true
+workspace_rule = true
+singleton = true
+window_order = true
+swallow = true
+mark = true
 ```
 
 **Default Behavior**:
 - If not explicitly specified, plugins are **disabled** by default (`false`)
-- You must explicitly set `scratchpads = true`, `empty = true`, `window_rule = true`, or `autofill = true` to enable plugins
-- Exception: `window_rule` plugin is enabled by default if window rules are configured (unless explicitly set to `false`)
+- Set each plugin to `true` explicitly to enable it
+- Exception: `window_rule` is enabled by default if window rules are configured (unless explicitly set to `false`)

docs/zh/plugins/mark.md

@@ -0,0 +1,67 @@
+# Mark 插件
+
+Mark 插件为窗口提供**可命名的快捷焦点**：把一个字符串（通常是一个字母，如 `a`）绑定到当前窗口，之后用同一名称即可快速切回该窗口。绑定关系保存在守护进程内存中，**不写配置文件**。
+
+## 配置
+
+只需在插件列表中启用：
+
+```toml
+[piri.plugins]
+mark = true
+```
+
+无需额外的 `[mark.*]` 表；所有标记均在运行时通过 CLI 创建或删除。
+
+## 命令行
+
+```bash
+# 若该标记已指向仍存在窗口 → 聚焦该窗口；否则将当前焦点窗口绑定到该标记
+piri mark {name} toggle
+
+# 删除该标记（不存在也视为成功）
+piri mark {name} delete
+
+# 将当前焦点窗口绑定到该标记（若已有绑定则直接覆盖）
+piri mark {name} add
+```
+
+示例：
+
+```bash
+piri mark a toggle   # 第一次：把当前窗口标为 a；之后：跳到 a
+piri mark a add      # 强制把当前窗口重新标为 a
+piri mark a delete   # 取消 a
+```
+
+## 行为说明
+
+1. **`toggle`**：若 `name` 已有绑定且对应窗口仍存在，则**聚焦**该窗口；否则（无绑定或窗口已关闭）将**当前焦点窗口**写入 `name`。
+2. **`add`**：始终用当前焦点窗口覆盖 `name`，不先判断旧窗口是否仍存在。
+3. **`delete`**：移除 `name` 的绑定，幂等。
+
+若要在**已有有效绑定**时改绑到别的窗口，请使用 **`add`**，或先 **`delete`** 再 **`toggle`**。
+
+## 与 Niri 快捷键配合
+
+Piri 无法单独「监听下一个按键」；在 Niri 中一般为每个要用的标记配置一条 `spawn`，例如：
+
+```kdl
+binds {
+    Mod+Shift+A { spawn "piri" "mark" "a" "toggle"; }
+    Mod+Shift+B { spawn "piri" "mark" "b" "toggle"; }
+}
+```
+
+若 Niri 将来支持多键序列或绑定模式，可把多条 `piri mark …` 收拢到同一前缀下，减少与全局快捷键的冲突。详见项目 README 中的相关说明。
+
+## 限制与提示
+
+- **非持久化**：重启 `piri daemon` 后所有标记丢失。
+- **无窗口装饰**：Niri IPC 当前无法在窗口上绘制标记字母；若需可视化，可考虑状态栏、通知或外部脚本自行维护列表。
+- **依赖焦点**：`toggle` / `add` 依赖「当前聚焦窗口」；调用前请确保目标窗口已聚焦。
+
+## 使用场景
+
+- 临时「书签」几个频繁切换的窗口（终端、浏览器、编辑器等）。
+- 与脚本或菜单（如 `fuzzel` 列出 `a`–`z` 后调用 `piri mark …`）组合，减少手写标记名。

docs/zh/plugins/plugins.md

@@ -22,6 +22,14 @@ Piri 支持插件系统，允许你扩展功能。插件在守护进程模式下
 - 基于工作区的配置
 - 类似于 Hyprland 的 `on-created-empty` 工作区规则
 
+### [Mark 插件](mark.md)
+
+为窗口设置命名标记，通过 `piri mark …` 绑定当前焦点窗口或跳回已标记窗口。绑定仅存于守护进程内存，无需在配置中为每个标记单独建表。
+
+**主要特性**：
+- `toggle` / `add` / `delete` 三种操作
+- 适合与 Niri `spawn` 或启动器组合使用
+
 ### [Window Rule 插件](window_rule.md)
 
 根据窗口的 `app_id` 或 `title` 自动将窗口移动到指定的工作区。用于自动化窗口管理和组织应用程序。
@@ -72,10 +80,14 @@ Piri 支持插件系统，允许你扩展功能。插件在守护进程模式下
 scratchpads = true
 empty = true
 window_rule = true
-autofill = true
+workspace_rule = true
+singleton = true
+window_order = true
+swallow = true
+mark = true
 ```
 
 **默认行为**：
 - 如果未明确指定，插件默认**禁用**（`false`）
-- 必须显式设置 `scratchpads = true`、`empty = true`、`window_rule = true` 或 `autofill = true` 来启用插件
+- 必须显式将对应项设为 `true` 来启用插件
 - `window_rule` 插件例外：如果配置了窗口规则，默认启用（除非显式设置为 `false`）

src/config.rs

@@ -182,6 +182,8 @@ pub struct PluginsConfig {
     pub swallow: Option<bool>,
     #[serde(default)]
     pub workspace_rule: Option<bool>,
+    #[serde(default)]
+    pub mark: Option<bool>,
     #[serde(rename = "empty_config", default)]
     pub empty_config: Option<EmptyPluginConfig>,
 }
@@ -197,6 +199,7 @@ impl Default for PluginsConfig {
             window_order: None,
             swallow: None,
             workspace_rule: None,
+            mark: None,
             empty_config: None,
         }
     }
@@ -379,6 +382,7 @@ impl PluginsConfig {
             "window_order" => self.window_order.unwrap_or(false),
             "swallow" => self.swallow.unwrap_or(false),
             "workspace_rule" => self.workspace_rule.unwrap_or(false),
+            "mark" => self.mark.unwrap_or(false),
             _ => false,
         }
     }

src/ipc.rs

@@ -19,6 +19,18 @@ pub enum IpcRequest {
         name: String,
     },
     WindowOrderToggle,
+    /// Mark: focus if bound window exists, else bind current focus to `name`.
+    MarkToggle {
+        name: String,
+    },
+    /// Remove mark `name` (no-op if missing).
+    MarkDelete {
+        name: String,
+    },
+    /// Bind current focus to `name`, replacing any previous binding.
+    MarkAdd {
+        name: String,
+    },
     Ping,
     Shutdown,
 }
@@ -261,6 +273,22 @@ pub async fn handle_request(
                         IpcResponse::Error("WindowOrder plugin is not enabled. Please enable it in the configuration file (piri.plugins.window_order = true).".to_string())
                     }
                 }
+                IpcRequest::MarkToggle { .. }
+                | IpcRequest::MarkDelete { .. }
+                | IpcRequest::MarkAdd { .. } => {
+                    let config = handler.config();
+                    if config.piri.plugins.is_enabled("mark") {
+                        IpcResponse::Error(
+                            "Mark plugin is enabled but not initialized. Please restart the daemon."
+                                .to_string(),
+                        )
+                    } else {
+                        IpcResponse::Error(
+                            "Mark plugin is not enabled. Set piri.plugins.mark = true in the config."
+                                .to_string(),
+                        )
+                    }
+                }
             }
         }
     };