# Pane Ratio

[English](README.md) | [简体中文](README.zh-CN.md) | 日本語

Pane Ratio は、ワークスペースごとに Dwindle または Scrolling を選択し、左右のペイン比率を記憶して、Dwindle を安全に調整できるときにその比率を適用する Omarchy バープラグインです。

![空の Omarchy ワークスペースで表示した Pane Ratio](assets/pane-ratio-empty-workspace.webp)

## 機能

- コンパクトなバーパネルから `1:3`、`1:2`、`1:1`、`2:1`、`3:1` のプリセットを選べます。
- 現在のワークスペースを Dwindle または Scrolling に明示的に切り替え、Omarchy 標準のワークスペースレイアウト状態として保存します。
- タイル化されたウィンドウが 0 枚または 1 枚でも、選択した比率を保存します。
- 2 枚目のタイル化されたウィンドウが現れると、保存済みの比率を自動的に適用します。
- タイル化されたウィンドウが 3 枚以上になると、配置・サイズを変更せずに一時停止し、2 枚に戻ると再開します。
- 安全な 2 ペインの Dwindle 分割を左右と上下の間で切り替え、より大きなツリーは並べ替えません。
- 現在のプリセットを検出して強調表示し、手動でプリセット外のサイズに変更した場合は `Custom` と表示します。
- フローティングウィンドウを無視します。
- 曖昧なレイアウトを推測せず、操作を拒否します。
- ワークスペースごとの比率の意図は `~/.local/state/omarchy-pane-ratio/` に保存します。Hyprland の設定は変更しません。

自動適用は意図的に、Dwindle ワークスペース上の「横並び・グループ化なし・フルスクリーンではない、ちょうど 2 枚のウィンドウ」に限定しています。Scrolling や多階層の Dwindle ツリーには別の意味付けが必要なため、暗黙の近似処理は行いません。

正の ID を持つワークスペースは、表示名が変わっても数値 ID で追跡します。Hyprland の名前付きワークスペースは完全一致する名前で追跡します。名前を変更すると旧ルールは休止し、後で同じ名前を明示的に再利用すると比率とレイアウトのルールが一緒に再有効化されます。special または安全に分類できないワークスペースでは、パネルは読み取り専用です。

## インストール

```bash
omarchy plugin add https://github.com/r404r/omarchy-pane-ratio.git --enable
```

setup スクリプトや Hyprland の再読み込みは不要です。バックエンドはインストール済みのプラグインディレクトリから直接実行されます。

## 動作要件

- Omarchy Quattro のプラグインランタイム。
- Lua API と `hyprctl` を備えた Hyprland。
- Python 3。バックエンドは標準ライブラリだけを使用します。

追加の Python パッケージ、特権コマンド、バックグラウンドサービス、ネットワークアクセスは不要です。

## アンインストール

```bash
omarchy plugin remove io.github.r404r.pane-ratio
```

アンインストールに `sudo` は不要で、Hyprland のキーバインドや setup の設定ブロックも残りません。保存済みの比率指定と Omarchy のワークスペースレイアウト選択は、ユーザー状態として保持されます。保存済み比率も破棄したい場合に限り、`~/.local/state/omarchy-pane-ratio/` を手動で削除してください。

## 使い方

Pane Ratio アイコンをクリックし、プリセットを選択します。ルールは現在のワークスペースに属し、2 枚目のウィンドウが現れる前でも選択できます。

パネル内のキーボード操作：

- `1`–`9`：その位置のプリセットを選択（既定の一覧では `1`–`5` を使用）
- `D`：現在のワークスペースルールを削除
- `S`：2 ペインの左右分割と上下分割を切り替え
- `L`：ワークスペースを Dwindle と Scrolling の間で切り替え
- `R`：更新
- 矢印キーと Enter：移動して適用
- Escape：閉じる

`Waiting` は、比率の指定が保存され、2 枚目のタイル化されたウィンドウを待っている状態です。`Paused` は、ルール自体は保持されているものの、現在のペイン構成では安全に適用できない状態です。3 ウィンドウのツリーを近似的に変更することはありません。

0.4 からアップグレードすると、最初の使用時に比率状態を schema 2 へ移行します。正規の正整数キーは数値ワークスペース ID として引き続き有効です。従来の非数値キーは、対象の名前付きワークスペースで比率を明示的に保存し直すまで休止します。パネルは対応を推測せず `migration_required` を表示します。0.4 は schema 2 を読めないため、0.4 へ戻す場合はアップグレード前に保存した `intents.json` を復元してください。

Dwindle と Scrolling のボタンは Omarchy の `Super+L` によるワークスペースレイアウト選択に対応しますが、単純な反転ではなく、切り替え先を明示します。選択結果は `~/.local/state/omarchy/workspace-layouts/` に書き込まれ、Omarchy も起動時に同じ場所から復元します。Scrolling では保存済みの比率を一時停止し、Dwindle に戻って安全な 2 ペイン構成になると再開します。

分割ボタンは Omarchy の `Super+J`「Toggle window split」に対応しますが、プラグインでは意図的に安全な 2 ペインの場合だけに限定しています。上下分割にすると保存済みの左右比率は一時停止し、左右分割に戻すと自動的に再適用します。ワークスペースレイアウトと Dwindle の分割方向は別々の操作です。

## カスタムプリセット

プラグインを編集せずに、既定の 5 つの比率を置き換えられます。
`~/.config/omarchy-pane-ratio/presets.json` を作成します：

```json
{
  "schemaVersion": 1,
  "presets": ["1:3", "1:2", "1:1", "5:3", "2:1", "3:1"]
}
```

比率は 1 個から 9 個まで指定でき、左右それぞれの値は 1 から 20 の整数である必要があります。比率は正規形に約分されるため、同じ比率がすでに保存されている場合は `2:2` ではなく `1:1` と記述してください。ファイルを変更したら、パネルを閉じて開き直します。イベントサービスが次回の調整時に設定を読み直します。プリセットファイルから削除された保存済み比率は保持されますが、プリセットを復元するかルールを削除するまで一時停止します。

## セキュリティモデル

- 比率の引数は固定の許可リストから選ばれ、任意のコマンドや任意の Lua は拒否します。
- 比率状態と Omarchy 互換のワークスペースレイアウトルールにはサイズ上限と許可リストがあり、シンボリックリンクを介したすり替えに耐性があり、アトミックに置き換えます。比率状態ディレクトリは `0700`、状態ファイルとルールファイルは `0600` とし、Omarchy の共有レイアウトディレクトリの権限は変更しません。
- `hyprctl` の出力は、タイムアウトとスキーマ検証を伴うサイズ制限付き JSON として解析します。
- 適用前にワークスペース、ウィンドウアドレス、フォーカス、レイアウトを 2 回確認します。
- dispatch の直前に、原子的な Lua guard がウィンドウ集合、フォーカス、Dwindle レイアウト、split bias、グループ、フルスクリーン状態、横方向のジオメトリを再確認します。Hyprland の Lua ウィンドウ API は Pseudotile を公開していないため、独立したポリシーフラグとしては扱わず、同じジオメトリ条件を適用します。
- 操作後のジオメトリを読み戻して検証します。
- 軽量な Omarchy QML サービスが、関連する Hyprland イベントに `140 ms` のデバウンスで反応し、同時に実行する要求は 1 つだけです。一時的な失敗は `250`、`500`、`1000 ms` 後に再試行して停止します。ポーリング、特権コマンド、ネットワークアクセス、ユーザー設定への書き込みはありません。

## 開発

```bash
python -m unittest discover -s tests -v
omarchy plugin validate .
qmllint -I "$OMARCHY_PATH/shell" BarWidget.qml Panel.qml PaneRatioProtocol.qml ReconcileScheduler.qml PaneRatioService.qml
```

## ライセンス

MIT