### Build Pot Desktop Installation Package

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

Command to build the installation package for Pot Desktop.

```bash
pnpm tauri build # Build into installation package
```

--------------------------------

### Install Pot App via Winget (Windows)

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

Use Winget to install the Pot App on Windows. This is a simple command-line installation method.

```powershell
winget install Pylogmon.pot
```

--------------------------------

### Install Pot App via apt-get (Debian/Ubuntu)

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

Install the Pot App on Debian-based systems using apt-get after downloading the .deb package.

```bash
sudo apt-get install ./pot_{version}_amd64.deb
```

--------------------------------

### Install WebView2 Runtime (Windows)

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

Link to manually install WebView2 Runtime, which is required for the Pot App's interface on Windows. This is a troubleshooting step if the app has no visible interface.

```html
https://learn.microsoft.com/en-us/microsoft-edge/webview2/
```

--------------------------------

### Install Plugin using .potext File

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Install plugins by selecting .potext files (ZIP archives) via a file dialog. The backend unpacks the plugin into the configuration directory. Requires 'info.json' and 'main.js' within the archive.

```typescript
import { invoke } from "@tauri-apps/api/tauri";
import { open } from "@tauri-apps/api/dialog";

// 通过文件选择器安装插件
const paths = await open({
  multiple: true,
  filters: [{ name: "Pot Plugin", extensions: ["potext"] }],
});

if (paths && paths.length > 0) {
  try {
    const count = await invoke<number>("install_plugin", {
      pathList: paths as string[],
    });
    console.log(`成功安装 ${count} 个插件`);
    // 插件解压目录：$CONFIG/com.pot-app.desktop/plugins/{plugin_type}/{plugin_name}/
    // plugin_type 可为：translate / recognize / tts / collection
  } catch (e) {
    // 错误示例：
    // "Invalid Plugin: file name must start with plugin"
    // "Invalid Plugin: miss info.json"
    // "Invalid Plugin: miss main.js"
    console.error("插件安装失败:", e);
  }
}

// info.json 格式示例：
// {
//   "plugin_type": "translate",  // translate | recognize | tts | collection
//   "name": "plugin-my-translator",
//   "version": "1.0.0"
// }
```

--------------------------------

### Install Linux Dependencies

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

Package installation command for Linux systems to satisfy build requirements for Pot Desktop.

```bash
sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.0-dev libayatana-appindicator3-dev librsvg2-dev patchelf libxdo-dev libxcb1 libxrandr2 libdbus-1-3
```

--------------------------------

### Install Pot App via Brew (MacOS)

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

Install the Pot App using Homebrew Cask after adding the tap. This command installs the application.

```bash
brew install --cask pot
```

--------------------------------

### install_plugin - Plugin Installation

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Installs plugins by extracting `.potext` files (ZIP archives) into the appropriate plugin subdirectories within the configuration directory. Requires `info.json` and `main.js` inside the archive.

```APIDOC
## install_plugin

### Description
Installs plugins by extracting `.potext` files (ZIP archives) into the appropriate plugin subdirectories within the configuration directory. Requires `info.json` and `main.js` inside the archive.

### Parameters
- `pathList` (array of strings): A list of paths to the `.potext` plugin files to install.

### Plugin Structure Requirements
- The plugin file must be a ZIP archive named starting with `plugin`.
- Inside the archive, `info.json` and `main.js` are mandatory.
- `info.json` must contain a `plugin_type` field (e.g., `translate`, `recognize`, `tts`, `collection`).

### Installation Directory
Plugins are extracted to: `$CONFIG/com.pot-app.desktop/plugins/{plugin_type}/{plugin_name}/`
```

--------------------------------

### Install Pot App via AUR Helper (Arch/Manjaro)

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

Install the Pot App from the Arch User Repository (AUR) using an AUR helper like yay or paru.

```bash
yay -S pot-translation # 或 pot-translation-bin
```

```bash
# paru -S pot-translation # 或 pot-translation-bin
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

Command to install project dependencies using pnpm after cloning the repository.

```bash
cd pot-desktop
pnpm install
```

--------------------------------

### Install Pot App via pacman (Arch Linux)

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

Install the Pot App directly using pacman if you are using the archlinuxcn repository.

```bash
sudo pacman -S pot-translation
```

--------------------------------

### Hyprland Window Rules for Pot

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

Example window rules for Hyprland to make Pot windows float and follow the mouse cursor.

```conf
windowrulev2 = float, class:(pot), title:(Translator|OCR|PopClip|Screenshot Translate) # Translation window floating
windowrulev2 = move cursor 0 0, class:(pot), title:(Translator|PopClip|Screenshot Translate) # Translation window follows the mouse position.
```

--------------------------------

### Run Pot Desktop in Development Mode

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

Command to start the Pot Desktop application in development mode for debugging.

```bash
pnpm tauri dev # Run the app in development mode
```

--------------------------------

### Hyprland Keybindings for Grim and Slurp

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

Configuration example for Hyprland to bind keys for screenshotting with grim/slurp and triggering Pot's OCR or translate functions.

```conf
bind = ALT, X, exec, grim -g "$(slurp)" ~/.cache/com.pot-app.desktop/pot_screenshot_cut.png && curl "127.0.0.1:60828/ocr_recognize?screenshot=false"
bind = ALT, C, exec, grim -g "$(slurp)" ~/.cache/com.pot-app.desktop/pot_screenshot_cut.png && curl "127.0.0.1:60828/ocr_translate?screenshot=false"
```

--------------------------------

### Read and Write Configuration with tauri-plugin-store

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Demonstrates how to read and write application configuration using the `get` and `set` functions, which interact with a JSON configuration file. Handles default values for missing configurations and automatically persists changes to disk.

```rust
// src-tauri/src/config.rs

// 读取配置（返回 Option<Value>）
let port: i64 = match get("server_port") {
    Some(v) => v.as_i64().unwrap(),
    None => 60828, // 不存在则使用默认值
};

let proxy_enabled: bool = get("proxy_enable")
    .and_then(|v| v.as_bool())
    .unwrap_or(false);

let language: String = get("app_language")
    .and_then(|v| v.as_str().map(String::from))
    .unwrap_or_else(|| "en".to_string());

// 写入配置（自动持久化）
set("server_port", 8080_i64);
set("app_language", "zh_cn");
set("proxy_enable", true);
set("translate_service_list", vec!["openai@uuid1", "deepl@uuid2"]);

// 判断是否首次运行（配置为空）
if is_first_run() {
    config_window(); // 打开偏好设置引导
}
```

```javascript
// 前端读写配置（使用 tauri-plugin-store-api）
import { Store } from "tauri-plugin-store-api";
const store = new Store("config.json");

await store.set("translate_window_width", 400);
await store.save();
const width = await store.get<number>("translate_window_width"); // 400
```

--------------------------------

### Install C++ Redistributable (Windows)

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

Link to download the latest supported Visual C++ Redistributable packages for Visual Studio, necessary for resolving missing module errors on Windows.

```html
https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170#visual-studio-2015-2017-2019-and-2022
```

--------------------------------

### Configuration Management (`get`/`set`)

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Provides functions to read and write key-value configuration settings, persisting them to a JSON file. It leverages `tauri-plugin-store` for efficient storage and retrieval.

```APIDOC
## `get` / `set` — 配置读写

基于 `tauri-plugin-store` 实现的键值配置系统，配置文件存储于 `$CONFIG/com.pot-app.desktop/config.json`。

### `get(key: &str) -> Option<serde_json::Value>`
Reads a configuration value by its key. Returns `Option<serde_json::Value>`.

### `set(key: &str, value: impl Serialize)`
Writes a configuration value by its key. The value is automatically serialized and immediately persisted to disk.

### Example Usage (Rust)
```rust
// Reading configuration
let port: i64 = match get("server_port") {
    Some(v) => v.as_i64().unwrap_or(60828),
    None => 60828, // Default value if not found
};

let proxy_enabled: bool = get("proxy_enable")
    .and_then(|v| v.as_bool())
    .unwrap_or(false);

// Writing configuration
set("server_port", 8080_i64);
set("app_language", "zh_cn");
set("proxy_enable", true);
```

### Example Usage (JavaScript)
```javascript
import { Store } from "tauri-plugin-store-api";
const store = new Store("config.json");

await store.set("translate_window_width", 400);
await store.save();
const width = await store.get<number>("translate_window_width"); // 400
```
```

--------------------------------

### Start HTTP Server in Rust

Source: https://context7.com/pot-app/pot-desktop/llms.txt

This Rust code starts a local HTTP server in a separate thread to handle incoming requests for translation and OCR. It includes error handling for port conflicts.

```rust
// src-tauri/src/server.rs
pub fn start_server() {
    // 从配置读取端口，默认 60828
    let port = match get("server_port") {
        Some(v) => v.as_i64().unwrap(),
        None => { set("server_port", 60828); 60828 }
    };
    thread::spawn(move || {
        let server = match Server::http(format!("127.0.0.1:{port}")) {
            Ok(v) => v,
            Err(e) => {
                // 端口冲突时弹出系统通知
                let _ = notification::Notification::new("com.pot-spp.com")
                    .title("Server start failed")
                    .body("Please Change Server Port and restart the application")
                    .show();
                return;
            }
        };
        for request in server.incoming_requests() {
            http_handle(request); // 路由分发
        }
    });
}

// 路由映射（server.rs 内部）
fn http_handle(request: Request) {
    match request.url() {
        "/" | "/translate"                     => handle_translate(request),
        "/config"                              => handle_config(request),
        "/selection_translate"                 => handle_selection_translate(request),
        "/input_translate"                     => handle_input_translate(request),
        "/ocr_recognize" | "/ocr_recognize?screenshot=true"  => handle_ocr_recognize(request),
        "/ocr_recognize?screenshot=false"      => handle_ocr_recognize(request), // 使用已保存截图
        "/ocr_translate"  | "/ocr_translate?screenshot=true" => handle_ocr_translate(request),
        "/ocr_translate?screenshot=false"      => handle_ocr_translate(request),
        _ => {}
    }
}
```

--------------------------------

### Add Pot App Tap (MacOS)

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

Add the Pot App's Homebrew tap to your system to manage installations via Brew.

```bash
brew tap pot-app/homebrew-tap
```

--------------------------------

### Call Selection Translate with cURL

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

Example of how to trigger the selection translate feature using cURL.

```bash
curl "127.0.0.1:60828/selection_translate"
```

--------------------------------

### local / aliyun - Local and Aliyun OSS Backup

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Handles local file backups and backups to Aliyun Object Storage Service (OSS). Supports 'put' (backup) and 'get' (restore) operations.

```APIDOC
## local / aliyun

### Description
Handles local file backups and backups to Aliyun Object Storage Service (OSS). Supports 'put' (backup) and 'get' (restore) operations.

### Operations
- `put`: Backs up the current configuration.
- `get`: Restores the configuration from a backup.

### Parameters (local)
- `operate` (string): The operation to perform (put, get).
- `path` (string): The local file path for the backup ZIP file.

### Parameters (aliyun)
- `operate` (string): The operation to perform (put, get).
- `path` (string): Not used for 'get' operation. For 'put', it's the local temporary ZIP path.
- `url` (string): The pre-signed URL for Aliyun OSS interaction (PUT or GET).
```

--------------------------------

### Screenshot and Image Manipulation (`screenshot`, `cut_image`, `get_base64`, `copy_img`)

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Provides functionalities to capture screenshots, crop specific regions, get the cropped image as a Base64 string, and copy the cropped image to the system clipboard.

```APIDOC
## `screenshot` — 屏幕捕获（Tauri 命令）

捕获指定显示器的完整截图，保存为 `$CACHE/com.pot-app.desktop/pot_screenshot.png`，供后续 `cut_image` 裁剪使用。

### Description
Captures a screenshot of the specified monitor and saves it to `$CACHE/com.pot-app.desktop/pot_screenshot.png` for subsequent cropping.

### Method
Tauri Command (`invoke`)

### Parameters
#### Command Arguments
- **x** (number) - Required - The physical pixel starting X-coordinate of the target monitor.
- **y** (number) - Required - The physical pixel starting Y-coordinate of the target monitor.

### Request Example (JavaScript)
```javascript
import { invoke } from "@tauri-apps/api/tauri";
import { appWindow } from "@tauri-apps/api/window";

const monitor = await appWindow.currentMonitor();
if (monitor) {
  const { x, y } = monitor.position;
  await invoke("screenshot", { x, y });
  // Screenshot saved as pot_screenshot.png in the cache directory
}
```

---

## `cut_image` — 裁剪图像（Tauri 命令）

### Description
Crops a specified region from the previously captured screenshot (`pot_screenshot.png`) and saves the result as `pot_screenshot_cut.png`.

### Method
Tauri Command (`invoke`)

### Parameters
#### Command Arguments
- **left** (number) - Required - The starting X-coordinate (in physical pixels) of the crop area.
- **top** (number) - Required - The starting Y-coordinate (in physical pixels) of the crop area.
- **width** (number) - Required - The width of the crop area.
- **height** (number) - Required - The height of the crop area.

### Request Example (JavaScript)
```javascript
// Assuming screenshot has already been taken
await invoke("cut_image", {
  left: 100,   // Crop start X (physical pixels)
  top: 200,    // Crop start Y (physical pixels)
  width: 400,  // Width
  height: 300, // Height
});
// Cropped image saved as pot_screenshot_cut.png
```

---

## `get_base64` — 获取 Base64 编码（Tauri 命令）

### Description
Retrieves the Base64 encoded string of the cropped image (`pot_screenshot_cut.png`). This is useful for sending the image data to an OCR API.

### Method
Tauri Command (`invoke`)

### Request Example (JavaScript)
```javascript
const base64: string = await invoke("get_base64");
// → "iVBORw0KGgoAAAANSUhEUgAA..."
```

### Response
#### Success Response
- **string**: The Base64 encoded string of the cropped image.

---

## `copy_img` — 复制图像到剪贴板（Tauri 命令）

### Description
Copies the cropped image (`pot_screenshot_cut.png`) to the system clipboard.

### Method
Tauri Command (`invoke`)

### Parameters
#### Command Arguments
- **width** (number) - Required - The width of the image to copy.
- **height** (number) - Required - The height of the image to copy.

### Request Example (JavaScript)
```javascript
await invoke("copy_img", { width: 400, height: 300 });
```
```

--------------------------------

### check_update

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Asynchronously checks for application updates when the application starts. If a new version is available, it opens the update window. This command utilizes the Tauri built-in `updater` plugin.

```APIDOC
## `check_update` — 自动更新检查

应用启动时异步检查更新端点，若有新版本则打开更新窗口。使用 Tauri 内置的 `updater` 插件，更新端点配置在 `tauri.conf.json` 中。

```rust
// src-tauri/src/updater.rs
// 应用启动时调用（main.rs setup 中）：
check_update(app.handle());

// 内部逻辑等效代码：
async fn check_update_logic(app_handle: AppHandle) {
    // 配置键 "check_update" 为 false 时跳过
    match tauri::updater::builder(app_handle).check().await {
        Ok(update) if update.is_update_available() => {
            // 打开 600x400 更新窗口（updater_window()）
            updater_window();
        }
        Ok(_) => { /* 已是最新版本 */ }
        Err(e) => { /* 网络错误或端点不可达时静默忽略 */ }
    }
}

// 前端禁用自动更新检查：
import { Store } from "tauri-plugin-store-api";
const store = new Store("config.json");
await store.set("check_update", false);
await store.save();

// 更新端点（tauri.conf.json）：
// "https://dl.pot-app.com/https://github.com/pot-app/pot-desktop/releases/download/updater/update.json"
// "https://github.com/pot-app/pot-desktop/releases/download/updater/update.json"
```
```

--------------------------------

### Local and Aliyun OSS Backup Operations

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Perform local backups using Tauri's save dialog or Aliyun OSS backups via pre-signed URLs. Supports 'put' (backup) and 'get' (restore) operations.

```typescript
import { invoke } from "@tauri-apps/api/tauri";
import { save, open } from "@tauri-apps/api/dialog";

// ── 本地备份 ──────────────────────────────────────────
// 选择保存路径并导出备份
const savePath = await save({ filters: [{ name: "Pot Backup", extensions: ["zip"] }] });
if (savePath) {
  await invoke("local", { operate: "put", path: savePath });
  console.log("备份已导出:", savePath);
}

// 选择备份文件并恢复（覆盖当前配置）
const openPath = await open({ filters: [{ name: "Pot Backup", extensions: ["zip"] }] });
if (openPath) {
  await invoke("local", { operate: "get", path: openPath as string });
  // 恢复完成后需重启应用生效
}

// ── 阿里云 OSS 备份 ───────────────────────────────────
// 上传：path 为本地临时 ZIP，url 为 OSS 预签名 PUT URL
await invoke("aliyun", {
  operate: "put",
  path: "/tmp/pot_backup.zip",
  url: "https://bucket.oss-cn-hangzhou.aliyuncs.com/pot/backup.zip?Signature=xxx",
});

// 下载并恢复：url 为 OSS 预签名 GET URL
await invoke("aliyun", {
  operate: "get",
  path: "",  // get 操作 path 参数未使用
  url: "https://bucket.oss-cn-hangzhou.aliyuncs.com/pot/backup.zip?Signature=xxx",
});
```

--------------------------------

### OCR Recognize without Internal Screenshot Tool

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

Example of triggering OCR recognize without using the built-in screenshot tool, useful for custom screenshot workflows.

```bash
rm ~/.cache/com.pot-app.desktop/pot_screenshot_cut.png && flameshot gui -s -p ~/.cache/com.pot-app.desktop/pot_screenshot_cut.png && curl "127.0.0.1:60828/ocr_recognize?screenshot=false"
```

--------------------------------

### WebDAV Cloud Backup Operations

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Invoke Tauri commands for WebDAV operations: list, put (backup), get (restore), and delete. Requires WebDAV server URL, username, and password.

```typescript
import { invoke } from "@tauri-apps/api/tauri";

const webdavConfig = {
  url: "https://dav.example.com",
  username: "alice",
  password: "secret123",
};

// 列出所有备份文件
const list = await invoke<string>("webdav", {
  operate: "list",
  ...webdavConfig,
  name: null,
});
console.log(JSON.parse(list)); // [{ href: "/pot-app/backup-2024.zip", ... }]

// 上传当前配置为备份（打包 config.json + history.db + plugins/）
await invoke("webdav", {
  operate: "put",
  ...webdavConfig,
  name: "backup-2024-01-15.zip",
});

// 从 WebDAV 恢复备份（解压覆盖本地配置目录）
await invoke("webdav", {
  operate: "get",
  ...webdavConfig,
  name: "backup-2024-01-15.zip",
});

// 删除指定备份
await invoke("webdav", {
  operate: "delete",
  ...webdavConfig,
  name: "backup-2024-01-15.zip",
});
```

--------------------------------

### webdav - WebDAV Cloud Backup

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Manages cloud backups using WebDAV. Supports listing, getting, putting, and deleting backup files. The backup is a ZIP archive of config.json, history.db, and the plugins/ directory.

```APIDOC
## webdav

### Description
Manages cloud backups using WebDAV. Supports listing, getting, putting, and deleting backup files. The backup is a ZIP archive of config.json, history.db, and the plugins/ directory.

### Operations
- `list`: Lists all backup files on the WebDAV server.
- `put`: Uploads the current configuration as a backup.
- `get`: Downloads and restores a backup from the WebDAV server.
- `delete`: Deletes a specified backup file from the WebDAV server.

### Parameters
- `operate` (string): The operation to perform (list, get, put, delete).
- `url` (string): The WebDAV server URL.
- `username` (string): The username for WebDAV authentication.
- `password` (string): The password for WebDAV authentication.
- `name` (string | null): The name of the backup file for get, put, and delete operations. Null for list operation.
```

--------------------------------

### Pot App Development and Build Commands

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Provides essential commands for setting up the development environment, running the app in development mode with hot reloading, and performing production builds.

```bash
# 环境要求：Node.js ≥ 18、pnpm ≥ 8.5、Rust ≥ 1.80

# 安装前端依赖
pnpm install

# Linux 额外系统依赖
sudo apt-get install -y \
  libgtk-3-dev libwebkit2gtk-4.0-dev libayatana-appindicator3-dev \
  librsvg2-dev patchelf libxdo-dev libxcb1 libxrandr2 libdbus-1-3

# 开发模式（热重载）
pnpm tauri dev

# 生产构建（输出安装包到 src-tauri/target/release/bundle/）
pnpm tauri build

# 代码格式化
pnpm prettier --write .

# 应用标识符：com.pot-app.desktop
# 配置目录：$CONFIG/com.pot-app.desktop/
# 缓存目录：$CACHE/com.pot-app.desktop/
# 日志目录：$LOGS/com.pot-app.desktop/
```

--------------------------------

### Wayland Environment Configuration (Linux)

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Configuration details for running Pot Desktop in pure Wayland environments on Linux, such as Hyprland. This includes setting up system shortcuts via HTTP API calls and configuring window rules for the translation window.

```APIDOC
## Wayland 环境配置（Linux）

在纯 Wayland 桌面环境（如 Hyprland）下，Tauri 全局快捷键不可用，需使用系统快捷键调用 HTTP API，并配置窗口规则实现翻译窗口跟随鼠标。

```bash
# Hyprland 配置示例（~/.config/hypr/hyprland.conf）

# 全局快捷键替代方案（使用 curl 触发 pot）
bind = ALT, Q, exec, curl "127.0.0.1:60828/selection_translate"
bind = ALT, W, exec, curl "127.0.0.1:60828/input_translate"
bind = ALT, X, exec, grim -g "$(slurp)" ~/.cache/com.pot-app.desktop/pot_screenshot_cut.png && curl "127.0.0.1:60828/ocr_recognize?screenshot=false"
bind = ALT, C, exec, grim -g "$(slurp)" ~/.cache/com.pot-app.desktop/pot_screenshot_cut.png && curl "127.0.0.1:60828/ocr_translate?screenshot=false"

# 窗口规则：翻译窗口浮动并跟随鼠标位置
windowrulev2 = float, class:(pot), title:(Translator|OCR|PopClip|Screenshot Translate)
windowrulev2 = move cursor 0 0, class:(pot), title:(Translator|PopClip|Screenshot Translate)

# NVIDIA 专有驱动崩溃修复（/etc/environment 或 ~/.profile）
WEBKIT_DISABLE_DMABUF_RENDERER=1
```
```

--------------------------------

### Clone Pot Desktop Repository

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

Command to clone the Pot Desktop repository from GitHub.

```bash
git clone https://github.com/pot-app/pot-desktop.git
```

--------------------------------

### Wayland Environment Configuration (Linux)

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Configures global shortcuts using `curl` to trigger Pot's HTTP API and sets window rules for floating and mouse-following behavior in Wayland environments like Hyprland.

```bash
# Hyprland 配置示例（~/.config/hypr/hyprland.conf）

# 全局快捷键替代方案（使用 curl 触发 pot）
bind = ALT, Q, exec, curl "127.0.0.1:60828/selection_translate"
bind = ALT, W, exec, curl "127.0.0.1:60828/input_translate"
bind = ALT, X, exec, grim -g "$(slurp)" ~/.cache/com.pot-app.desktop/pot_screenshot_cut.png && curl "127.0.0.1:60828/ocr_recognize?screenshot=false"
bind = ALT, C, exec, grim -g "$(slurp)" ~/.cache/com.pot-app.desktop/pot_screenshot_cut.png && curl "127.0.0.1:60828/ocr_translate?screenshot=false"

# 窗口规则：翻译窗口浮动并跟随鼠标位置
windowrulev2 = float, class:(pot), title:(Translator|OCR|PopClip|Screenshot Translate)
windowrulev2 = move cursor 0 0, class:(pot), title:(Translator|PopClip|Screenshot Translate)

# NVIDIA 专有驱动崩溃修复（/etc/environment 或 ~/.profile）
WEBKIT_DISABLE_DMABUF_RENDERER=1
```

--------------------------------

### Global Shortcut Registration

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Pot allows for global keyboard shortcuts to be registered and managed. This can be done on application startup for all shortcuts or dynamically via a Tauri command for individual updates.

```APIDOC
## Register All Shortcuts

### Description
Registers all predefined global shortcuts when the application starts.

### Method
Internal Function Call (on startup)

### Function Signature
`register_shortcut("all")`

---

## Register Specific Shortcut (Backend)

### Description
Registers a specific global shortcut, typically called internally by the backend.

### Method
Internal Function Call

### Function Signature
`register_shortcut("shortcut_name")`

### Parameters
#### Path Parameters
- **shortcut_name** (string) - The name of the shortcut to register (e.g., `"hotkey_selection_translate"`).

---

## Register Shortcut by Frontend (Dynamic Update)

### Description
Allows the frontend to dynamically register or update a global shortcut without restarting the application. This is invoked via a Tauri command.

### Method
Tauri Invoke Command

### Function Signature
`invoke("register_shortcut_by_frontend", { name, shortcut })

### Parameters
#### Request Body
- **name** (string) - Required - The internal name of the shortcut (e.g., `"hotkey_selection_translate"`).
- **shortcut** (string) - Required - The desired key combination (e.g., `"Alt+Q"`).

### Supported Shortcut Names
- `"hotkey_selection_translate"`: Selection Translate
- `"hotkey_input_translate"`: Input Translate
- `"hotkey_ocr_recognize"`: Screenshot OCR
- `"hotkey_ocr_translate"`: Screenshot Translate
```

--------------------------------

### Pot Desktop API Endpoints

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

List of available API endpoints for interacting with Pot Desktop functionalities like translation and OCR.

```bash
POST "/" => 翻译指定文本(body为需要翻译的文本),
GET "/config" => 打开设置,
POST "/translate" => 翻译指定文本(同"/"),
GET "/selection_translate" => 划词翻译,
GET "/input_translate" => 输入翻译,
GET "/ocr_recognize" => 截图OCR,
GET "/ocr_translate" => 截图翻译,
GET "/ocr_recognize?screenshot=false" => 截图OCR(不使用软件内截图),
GET "/ocr_translate?screenshot=false" => 截图翻译(不使用软件内截图),
GET "/ocr_recognize?screenshot=true" => 截图OCR,
GET "/ocr_translate?screenshot=true" => 截图翻译
```

--------------------------------

### Configuration Endpoint

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

This endpoint allows you to open the settings or configuration window of the Pot Desktop application.

```APIDOC
## GET "/config"

### Description
Opens the application's settings or configuration window.

### Method
GET

### Endpoint
/config
```

--------------------------------

### run_binary - Plugin Binary Execution

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Executes a specified binary file within a plugin's directory. Captures stdout, stderr, and the exit code, returning them to the frontend as a JSON object.

```APIDOC
## run_binary

### Description
Executes a specified binary file within a plugin's directory. Captures stdout, stderr, and the exit code, returning them to the frontend as a JSON object.

### Parameters
- `pluginType` (string): The type of the plugin (e.g., `recognize`).
- `pluginName` (string): The name of the plugin directory.
- `cmdName` (string): The name of the executable file to run.
- `args` (array of strings): A list of command-line arguments to pass to the executable.

### Returns
An object containing:
- `stdout` (string): The standard output from the executed command.
- `stderr` (string): The standard error from the executed command.
- `status` (number): The exit code of the executed command.
```

--------------------------------

### Execute Plugin Binary

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Run executable files within a plugin's directory using the 'run_binary' Tauri command. Captures stdout, stderr, and exit status, returning them as JSON.

```typescript
import { invoke } from "@tauri-apps/api/tauri";

// 执行插件内的二进制工具（如 Paddle OCR、Rapid OCR 等）
const result = await invoke<{
  stdout: string;
  stderr: string;
  status: number;
}>("run_binary", {
  pluginType: "recognize",         // 插件类型目录
  pluginName: "plugin-paddle-ocr", // 插件目录名
  cmdName: "paddleocr",            // 可执行文件名（Windows 自动包装为 cmd /c）
  args: ["--image", "input.png", "--lang", "ch"],
});

if (result.status === 0) {
  console.log("识别结果:", result.stdout);
  // → '{"words_result": [{"words": "你好世界"}]}'
} else {
  console.error("执行失败:", result.stderr);
}
```

--------------------------------

### Configure and Enable Network Proxy

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Sets process-level environment variables for HTTP proxy based on configuration. Ensure proxy settings are complete before invoking.

```typescript
import { invoke } from "@tauri-apps/api/tauri";
import { Store } from "tauri-plugin-store-api";

const store = new Store("config.json");

// 配置并启用代理
await store.set("proxy_enable", true);
await store.set("proxy_host", "127.0.0.1");
await store.set("proxy_port", 7890);
await store.set("no_proxy", "localhost,127.0.0.1");
await store.save();

try {
  await invoke("set_proxy");
  // 等效于设置环境变量：
  // http_proxy=http://127.0.0.1:7890
  // https_proxy=http://127.0.0.1:7890
  // all_proxy=http://127.0.0.1:7890
  // no_proxy=localhost,127.0.0.1
  console.log("代理已启用");
} catch {
  console.error("代理配置不完整");
}
```

--------------------------------

### Screen Capture and Image Manipulation

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Captures a full screenshot of a specified monitor, saves it to the cache directory, and allows for cropping and conversion to Base64. Also includes functionality to copy the cropped image to the system clipboard.

```javascript
// src-tauri/src/screenshot.rs
// 前端调用（截图选区 UI 中使用）：
import { invoke } from "@tauri-apps/api/tauri";
import { appWindow } from "@tauri-apps/api/window";

// 获取当前窗口所在显示器并截图
const monitor = await appWindow.currentMonitor();
if (monitor) {
  const { x, y } = monitor.position;
  await invoke("screenshot", { x, y });
  // 截图已保存至缓存目录 pot_screenshot.png
}

// 配合 cut_image 裁剪选区
await invoke("cut_image", {
  left: 100,   // 裁剪起点 x（物理像素）
  top: 200,    // 裁剪起点 y（物理像素）
  width: 400,  // 宽度
  height: 300, // 高度
});
// 裁剪结果保存为 pot_screenshot_cut.png

// 获取裁剪图的 Base64 编码（用于发送给 OCR API）
const base64: string = await invoke("get_base64");
// → "iVBORw0KGgoAAAANSUhEUgAA..."

// 将裁剪图复制到系统剪切板
await invoke("copy_img", { width: 400, height: 300 });
```

--------------------------------

### Check for Application Updates

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Asynchronously checks for updates on application startup and opens the update window if a new version is available. Uses Tauri's built-in `updater` plugin.

```rust
// src-tauri/src/updater.rs
// 应用启动时调用（main.rs setup 中）：
check_update(app.handle());

// 内部逻辑等效代码：
async fn check_update_logic(app_handle: AppHandle) {
    // 配置键 "check_update" 为 false 时跳过
    match tauri::updater::builder(app_handle).check().await {
        Ok(update) if update.is_update_available() => {
            // 打开 600x400 更新窗口（updater_window()）
            updater_window();
        }
        Ok(_) => { /* 已是最新版本 */ }
        Err(e) => { /* 网络错误或端点不可达时静默忽略 */ }
    }
}

// 前端禁用自动更新检查：
import { Store } from "tauri-plugin-store-api";
const store = new Store("config.json");
await store.set("check_update", false);
await store.save();

// 更新端点（tauri.conf.json）：
// "https://dl.pot-app.com/https://github.com/pot-app/pot-desktop/releases/download/updater/update.json"
// "https://github.com/pot-app/pot-desktop/releases/download/updater/update.json"
```

--------------------------------

### Register Global Hotkeys in Rust and React

Source: https://context7.com/pot-app/pot-desktop/llms.txt

This snippet shows how to register global hotkeys in the Pot application. The backend registers all hotkeys on startup, while the frontend can dynamically update them via Tauri commands without restarting.

```rust
// src-tauri/src/hotkey.rs

// 应用启动时注册全部快捷键（main.rs 中调用）
match register_shortcut("all") {
    Ok(()) => {} // Do nothing on success
    Err(e) => { /* 弹出系统通知 */ } // Handle error, e.g., show notification
}

// 后端注册示例（注册划词翻译快捷键）
register_shortcut("hotkey_selection_translate")?;
```

```javascript
// src/views/Preference/pages/Hotkey/index.jsx 中类似调用：
import { invoke } from "@tauri-apps/api/tauri";

async function saveHotkey(name: string, shortcut: string) {
  try {
    await invoke("register_shortcut_by_frontend", { name, shortcut });
    // 示例：name = "hotkey_selection_translate", shortcut = "Alt+Q"
    console.log("快捷键注册成功");
  } catch (e) {
    console.error("快捷键注册失败:", e);
    // 常见原因：快捷键已被其他应用占用
  }
}

// 支持的快捷键名称：
// "hotkey_selection_translate" → 划词翻译
// "hotkey_input_translate"     → 输入翻译
// "hotkey_ocr_recognize"       → 截图 OCR
// "hotkey_ocr_translate"       → 截图翻译
```

--------------------------------

### start_clipboard_monitor - Clipboard Monitor

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Monitors the system clipboard for text changes at a 500ms interval and triggers a text translation upon detecting a change. This feature can be enabled or disabled without restarting the application.

```APIDOC
## start_clipboard_monitor

### Description
Monitors the system clipboard for text changes at a 500ms interval and triggers a text translation upon detecting a change. This feature can be enabled or disabled without restarting the application.

### Usage
Control the clipboard monitor by setting the `clipboard_monitor` value in the `config.json` store to `true` (enable) or `false` (disable).

### Internal Mechanism
- The monitor runs in a loop, checking the clipboard every 500ms.
- If the clipboard content changes, it triggers the `text_translate` function.
- The state is managed by a `ClipboardMonitorEnableWrapper`.
```

--------------------------------

### Update Pot App via Brew (MacOS)

Source: https://github.com/pot-app/pot-desktop/blob/master/README.md

Upgrade the Pot App to the latest version using Homebrew Cask.

```bash
brew upgrade --cask pot
```

--------------------------------

### System OCR with Tauri Commands

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Implements cross-platform system OCR using native APIs (Windows Media OCR, Apple Vision Framework, Tesseract CLI). The input is an image file in the cache directory, and the output is the recognized text string. Frontend calls are made using `invoke`.

```javascript
// 前端通过 invoke 调用：
import { invoke } from "@tauri-apps/api/tauri";

async function runSystemOcr(lang: string = "auto"): Promise<string> {
  try {
    // lang 可为 "auto" 或 BCP-47 语言代码，如 "zh_cn"、"en"、"ja"
    const result = await invoke<string>("system_ocr", { lang });
    console.log("OCR 结果:", result);
    return result;
  } catch (e) {
    // 常见错误：
    // Windows: "Language package not installed!"
    // Linux:   "Tesseract not installed!" / "Language data not installed!"
    // macOS:   二进制权限问题
    console.error("OCR 失败:", e);
    throw e;
  }
}

// Windows 示例 —— 指定语言
await runSystemOcr("zh-Hans"); // Windows BCP-47 格式
// macOS 示例
await runSystemOcr("zh_cn");
// Linux 示例（需安装对应语言包）
// sudo apt install tesseract-ocr-chi-sim
await runSystemOcr("chi_sim");
// 自动检测语言
await runSystemOcr("auto");
```

```rust
// src-tauri/src/system_ocr.rs（以 Linux/Tesseract 为例）
```

--------------------------------

### Local Language Detection (`lang_detect`)

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Detects the language of a given text input locally and offline using the `lingua` crate. It supports 22 languages and returns Pot's internal language code.

```APIDOC
## `lang_detect` — 本地语种检测（Tauri 命令）

使用 `lingua` crate 在本地（离线）对输入文本进行语种检测，支持 22 种语言，返回 pot 内部使用的语言代码。

### Description
Detects the language of the input text locally and returns Pot's internal language code (e.g., "zh_cn", "en", "ja"). This is enabled when the `translate_detect_engine` configuration is set to "local".

### Method
Tauri Command (`invoke`)

### Parameters
#### Command Arguments
- **text** (string) - Required - The text to analyze for language detection.

### Request Example (JavaScript)
```javascript
import { invoke } from "@tauri-apps/api/tauri";

async function detectLanguage(text: string): Promise<string> {
  // Returns Pot's internal language code
  const lang = await invoke<string>("lang_detect", { text });
  return lang;
}

// Example usage:
await detectLanguage("Hello world");         // → "en"
await detectLanguage("你好世界");            // → "zh_cn"
await detectLanguage("こんにちは");           // → "ja"
```

### Response
#### Success Response
- **string**: The detected language code (e.g., "zh_cn", "en", "ja"). Defaults to "en" if the language cannot be identified.

### Supported Languages
`zh_cn`, `ja`, `en`, `ko`, `fr`, `es`, `de`, `ru`, `it`, `pt_pt`, `tr`, `ar`, `vi`, `th`, `id`, `ms`, `hi`, `mn_cy`, `nb_no`, `nn_no`, `fa`, `uk`
```

--------------------------------

### Update System Tray Menu

Source: https://context7.com/pot-app/pot-desktop/llms.txt

Rebuilds the system tray menu based on application language and auto-copy mode. Supports 11 languages and synchronizes menu item states.

```typescript
import { invoke } from "@tauri-apps/api/tauri";

// 切换应用语言后刷新托盘菜单
await invoke("update_tray", {
  language: "zh_cn",   // "en"|"zh_cn"|"zh_tw"|"ja"|"ko"|"fr"|"de"|"ru"|"pt_br"|"fa"|"uk"|""
  copyMode: "target",  // "source"|"target"|"source_target"|"disable"|""
});
// 传空字符串 "" 表示从配置文件自动读取

// 仅刷新语言（复制模式保持当前设置）
await invoke("update_tray", { language: "ja", copyMode: "" });

// 完全自动（从配置读取所有值）
await invoke("update_tray", { language: "", copyMode: "" });

// 自动复制模式说明：
// "source"        → 翻译完成后自动复制原文
// "target"        → 翻译完成后自动复制译文
// "source_target" → 翻译完成后同时复制原文+译文
// "disable"       → 不自动复制
```