✨ Support Window Swallow

Author: Asthestarsfalll

README.en.md

@@ -14,6 +14,7 @@ Piri is a high-performance [Niri](https://github.com/YaLTeR/niri) extension tool
 - 🔄 **Autofill**: Layout auto-alignment. Automatically aligns remaining windows when a window is closed or layout changes, keeping your interface clean (see [Autofill Docs](docs/en/plugins/autofill.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))
 - 📋 **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))
 
 
 ## Quick Start
@@ -306,6 +307,44 @@ piri window_order toggle
 
 For detailed documentation, please refer to the [Window Order documentation](docs/en/plugins/window_order.md).
 
+### Swallow
+
+![Swallow](./assets/autofill_1.mp4)
+
+Automatically hides parent windows when child windows are opened, allowing child windows to replace parent windows in the layout. This is useful for scenarios like terminals spawning image viewers or media players.
+
+**Configuration Example**:
+```toml
+[piri.plugins]
+swallow = true
+
+[piri.swallow]
+use_pid_matching = true  # Enable PID-based parent-child process matching (default: true)
+
+# Global exclude rule (optional)
+[piri.swallow.exclude]
+app_id = [".*dialog.*"]
+
+# Rules list
+[[swallow]]
+parent_app_id = [".*terminal.*", ".*alacritty.*", ".*foot.*", ".*ghostty.*"]
+child_app_id = [".*mpv.*", ".*imv.*", ".*feh.*"]
+exclude_child_app_id = [".*dialog.*", ".*error.*"]
+
+[[swallow]]
+parent_app_id = ["code", "nvim-qt"]
+child_app_id = [".*preview.*", ".*markdown.*"]
+```
+
+**Features**:
+- Supports PID-based parent-child process matching (enabled by default)
+- Supports rule-based matching (via `app_id`, `title`, or `pid` patterns)
+- Supports global and rule-level exclude rules
+- Intelligent focus window queue for automatic parent window discovery
+- Automatically handles workspace movement and floating window conversion
+
+For detailed documentation, please refer to the [Swallow documentation](docs/en/plugins/swallow.md).
+
 ## Documentation
 
 - [Architecture](docs/en/architecture.md) - Project architecture and how it works

README.md

@@ -14,6 +14,7 @@ Piri 是基于 Rust 的 [Niri](https://github.com/YaLTeR/niri) 高性能功能
 - 🔄 **Autofill**: 布局自动对齐。在窗口关闭或布局变动时自动对齐剩余窗口，时刻保持界面整洁（详见 [Autofill 文档](docs/zh/plugins/autofill.md)）
 - 🔒 **Singleton**: 单实例保障。确保特定应用全局唯一，支持快速聚焦现有实例或自动拉起新进程（详见 [Singleton 文档](docs/zh/plugins/singleton.md)）
 - 📋 **Window Order**: 智能窗口排序。根据配置权重自动重排平铺窗口，相同权重窗口保持相对位置以最小化移动损耗（详见 [Window Order 文档](docs/zh/plugins/window_order.md)）
+- 🍽️ **Swallow**: 窗口吞噬机制。当子窗口打开时自动隐藏父窗口，让子窗口在布局中替换父窗口的位置（详见 [Swallow 文档](docs/zh/plugins/swallow.md)）
 
 ## 窗口匹配机制
 
@@ -316,6 +317,43 @@ piri window_order toggle
 
 详细说明请参考 [Window Order 文档](docs/zh/plugins/window_order.md)。
 
+### Swallow
+
+![Swallow](./assets/autofill_1.mp4)
+
+当子窗口打开时自动隐藏父窗口，让子窗口在布局中替换父窗口的位置。这对于终端启动图片查看器或媒体播放器等场景非常有用。
+
+**配置示例**：
+```toml
+[piri.plugins]
+swallow = true
+
+[piri.swallow]
+use_pid_matching = true  # 启用基于 PID 的父子进程匹配（默认：true）
+
+# 全局排除规则（可选）
+[piri.swallow.exclude]
+app_id = [".*dialog.*"]
+
+# 规则列表
+[[swallow]]
+parent_app_id = [".*terminal.*", ".*alacritty.*", ".*foot.*", ".*ghostty.*"]
+child_app_id = [".*mpv.*", ".*imv.*", ".*feh.*"]
+
+[[swallow]]
+parent_app_id = ["code", "nvim-qt"]
+child_app_id = [".*preview.*", ".*markdown.*"]
+```
+
+**特性**：
+- 支持基于 PID 的父子进程匹配（默认启用）
+- 支持基于规则的匹配（通过 `app_id`、`title` 或 `pid` 模式）
+- 支持全局和规则级别的排除规则
+- 智能聚焦窗口队列，自动查找父窗口
+- 自动处理工作空间移动和浮动窗口转换
+
+详细说明请参考 [Swallow 文档](docs/zh/plugins/swallow.md)。
+
 ## 文档
 
 - [架构设计](docs/zh/architecture.md) - 项目架构和工作原理

assets/swallow_pid.mp4

@@ -15,6 +15,7 @@ window_rule = true
 autofill = true
 singleton = true
 window_order = true
+swallow = true
 
 [piri.scratchpad]
 default_size = "40% 60%"
@@ -117,4 +118,18 @@ default_weight = 0
 # Window-specific weights
 google-chrome = 100
 code = 80
-ghostty = 70
+ghostty = 70
+
+[piri.swallow]
+use_pid_matching=false
+
+[piri.swallow.exclude]
+app_id = ".*mpv*."
+
+[[swallow]]
+child_app_id='.*google-chrome.*'
+parent_app_id='.*ghostty.*'
+
+[[swallow]]
+child_app_id='.*firefox*.'
+parent_app_id='.*ghostty.*'

assets/swallow_rule.mp4

@@ -0,0 +1,233 @@
+# Swallow Plugin
+
+The Swallow plugin automatically hides parent windows when child windows are spawned. This is useful for scenarios like terminals spawning image viewers or media players, where you want the child window to replace the parent window in the layout.
+
+## How It Works
+
+When a child window is opened:
+
+1. **Child Window Matching**: The plugin checks if the new window matches any rule's child window criteria
+2. **Parent Window Discovery**: It finds the parent window using two methods (in priority order):
+   - **PID-based matching** (default): Traces the process tree to find if the child process was spawned from a parent process
+   - **Rule-based matching**: Matches parent windows by `app_id`, `title`, or `pid` patterns
+3. **Swallow Operation**: If a matching parent is found, the child window is "swallowed" into the parent's column position, effectively replacing it
+
+## Configuration
+
+Use the `[[swallow]]` format to configure rules (each rule is a separate configuration block), and use `[piri.swallow]` to configure plugin global settings:
+
+```toml
+[piri.plugins]
+swallow = true
+
+# Plugin global configuration
+[piri.swallow]
+# Enable PID-based parent-child process matching (default: true)
+use_pid_matching = true
+
+# Global exclude rule: windows matching these conditions will never be swallowed
+[piri.swallow.exclude]
+app_id = [".*dialog.*"]
+title = [".*error.*"]
+
+# Rules list (each rule is a separate configuration block)
+# Example 1: Terminal swallows media players
+[[swallow]]
+parent_app_id = [".*terminal.*", ".*alacritty.*", ".*foot.*", ".*ghostty.*"]
+child_app_id = [".*mpv.*", ".*imv.*", ".*feh.*"]
+
+# Example 2: Editor swallows preview windows
+[[swallow]]
+parent_app_id = ["code", "nvim-qt"]
+child_app_id = [".*preview.*", ".*markdown.*"]
+```
+
+### Global Configuration Parameters
+
+The following global parameters can be configured in `[piri.swallow]`:
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `use_pid_matching` | `bool` | Enable PID-based parent-child process matching (default: `true`) |
+| `exclude` | `SwallowExclude` | Global exclude rule, windows matching these conditions will never be swallowed (optional) |
+
+### Rule Configuration Parameters
+
+Each rule supports the following optional parameters:
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `parent_app_id` | `Vec<String>` | Regex patterns to match parent window `app_id` |
+| `parent_title` | `Vec<String>` | Regex patterns to match parent window `title` |
+| `child_app_id` | `Vec<String>` | Regex patterns to match child window `app_id` |
+| `child_title` | `Vec<String>` | Regex patterns to match child window `title` |
+
+### Matching Logic
+
+1. **Global Exclude Check**: First check if the child window matches the global `exclude` rule. If matched, skip immediately without performing any swallow operations.
+
+2. **PID Matching** (when `use_pid_matching = true`, default, highest priority):
+   - Traces the child process's process tree to find ancestor processes
+   - Matches parent windows whose PID is an ancestor of the child process
+   - If parent criteria (`parent_app_id`, `parent_title`) are specified, they are also checked
+   - If no parent criteria are specified, any ancestor window will match
+
+3. **Rule-based Matching** (fallback when PID matching fails or is disabled):
+   - Matches parent windows using `app_id`, `title`, or `pid` patterns
+   - Only used if PID matching fails or `use_pid_matching = false`
+   - **Parent Window Discovery Mechanism**:
+     - If the currently focused window is not the child window, use the currently focused window as the candidate parent window
+     - If the currently focused window is the child window itself, search for a matching parent window from the focus window queue (maintains the last 5 focused windows)
+     - The focus window queue is automatically updated when windows gain focus
+
+4. **Exclude Rules**: Exclude patterns take precedence - if a window matches an exclude pattern, it will not be matched even if it matches include patterns
+
+5. **Pattern Lists**: When multiple patterns are provided (e.g., `parent_app_id = ["pattern1", "pattern2"]`), the rule matches if ANY pattern matches (OR logic)
+
+## Examples
+
+### PID-based Matching Example
+
+![Swallow - PID-based Matching](./assets/swallow_pid.mp4)
+
+Using the default PID matching (`use_pid_matching = true`), the plugin automatically traces the process tree to find parent-child relationships.
+
+```toml
+[piri.swallow]
+use_pid_matching = true
+
+[[swallow]]
+parent_app_id = [".*ghostty.*"]
+child_app_id = [".*mpv.*"]
+```
+
+### Rule-based Matching Example
+
+![Swallow - Rule-based Matching](./assets/swallow_rule.mp4)
+
+Using `app_id` and `title` patterns to match parent windows.
+
+```toml
+[piri.swallow]
+use_pid_matching = true
+
+[[swallow]]
+child_app_id = '.*google-chrome.*'
+parent_app_id = '.*ghostty.*'
+
+[[swallow]]
+child_app_id = '.*firefox*.'
+parent_app_id = '.*ghostty.*'
+```
+
+### Basic Example: Terminal Swallows Media Players
+
+```toml
+[[swallow]]
+parent_app_id = ["ghostty", "alacritty", "foot"]
+child_app_id = ["mpv", "imv", "feh"]
+```
+
+When you launch `mpv` or `imv` from a terminal, the terminal window will be hidden and replaced by the media player.
+
+
+### Global Exclude Example
+
+```toml
+[piri.swallow]
+# Globally exclude all dialog windows
+[piri.swallow.exclude]
+app_id = [".*dialog.*", ".*error.*"]
+
+[[swallow]]
+parent_app_id = [".*terminal.*"]
+child_app_id = [".*mpv.*"]
+```
+
+This way all dialog windows will never be swallowed, even if rules match.
+
+### Disable PID Matching
+
+```toml
+[piri.swallow]
+use_pid_matching = false
+
+[[swallow]]
+parent_app_id = [".*terminal.*"]
+child_app_id = [".*mpv.*"]
+```
+
+This uses rule-based matching only, without checking process relationships.
+
+### Match by Title
+
+```toml
+[[swallow]]
+parent_title = [".*Terminal.*"]
+child_title = [".*Video Player.*"]
+```
+
+### Complex Example: Multiple Patterns
+
+```toml
+[[swallow]]
+parent_app_id = ["ghostty", "alacritty", "foot", "kitty"]
+child_app_id = ["mpv", "imv", "feh", "sxiv"]
+```
+
+## Default Behavior
+
+- If no rules are specified, the plugin is enabled but won't match any windows
+- `use_pid_matching` defaults to `true` if not specified
+- If `exclude` is not specified, no global exclusion is performed
+- If no child conditions are specified, the rule will match any child window and look for parents
+- If no parent conditions are specified (with PID matching enabled), any ancestor window will match
+- The focus window queue maintains at most the last 5 focused windows, used to find parent windows when child windows are focused
+
+## Technical Details
+
+### Process Tree Tracing
+
+When PID matching is enabled, the plugin:
+1. Finds the PID of the child window's process
+2. Traces up the process tree (up to PID 1) to find ancestor PIDs
+3. Matches windows whose process PID is in the ancestor chain
+
+### Focus Window Queue
+
+The plugin maintains a focus queue of at most 5 windows to track recently focused windows:
+- When a window gains focus (`WindowFocusTimestampChanged` event), the window ID is added to the end of the queue
+- When a new window opens (`WindowOpenedOrChanged` event), the window ID is also added to the queue
+- When a child window opens and the currently focused window is the child window itself, the plugin searches for a matching parent window from the queue (newest to oldest)
+- The queue size is limited to 5, removing the oldest window ID when exceeded
+
+### Window Matching
+
+The plugin uses the same window matching mechanism as other plugins. For details, see [Window Matching Mechanism](../window_matching.md).
+
+### IPC Calls
+
+The plugin performs the following operations when swallowing:
+1. Focus the parent window
+2. Ensures child window is not floating (converts to tiling if needed)
+3. Moves child window to parent's workspace (if different)
+4. Executes `ConsumeOrExpelWindowLeft` action to swallow the child into parent's column
+5. Focuses the child window
+
+All operations are performed in a single batch for better performance and atomicity.
+
+## Use Cases
+
+- **Terminals spawning media players**: Hide terminal when launching `mpv`, `imv`, or `feh`
+- **Editors spawning previews**: Hide editor window when preview window opens
+- **Applications with launcher windows**: Hide launcher when main application starts
+- **Nested application workflows**: Automatically manage parent-child window relationships
+
+## Limitations
+
+- Floating windows cannot be swallowed (will be converted to tiling first)
+- Parent and child windows must be in the same workspace (plugin handles this automatically)
+- Process tree tracing goes all the way up to PID 1, which may impact performance if the process tree is very deep
+- PID matching requires processes to have a parent-child relationship
+- The focus window queue maintains at most 5 windows. If the parent window is not among the last 5 focused windows, rule-based matching may not find the parent window
+