docs: add popup pane usage examples

refs #1125

10 files changed, 134 insertions, 12 deletions

diff --git a/docs/next/website/src/content/docs/configuration.mdx b/docs/next/website/src/content/docs/configuration.mdx
index 0cae754c..6743e3ba 100644
--- a/docs/next/website/src/content/docs/configuration.mdx
+++ b/docs/next/website/src/content/docs/configuration.mdx
@@ -178,6 +178,22 @@ percentage of the terminal area. Dimensions include the popup border, and
 values smaller than the popup minimum are clamped. Popup commands do not receive
 `HERDR_PANE_ID`; use `HERDR_ACTIVE_PANE_ID` for the underlying tiled pane.
 
+On Unix and macOS, a popup command can also provide an ad-hoc terminal without
+adding a split or tab:
+
+```toml
+[[keys.command]]
+key = "prefix+t"
+type = "popup"
+command = "exec \"${SHELL:-sh}\""
+description = "open scratch terminal"
+width = "80%"
+height = "80%"
+```
+
+On Windows, use a shell command such as `command = "powershell.exe -NoLogo"`
+instead. Exit the shell to close the popup and restore the tiled terminal view.
+
 `type = "pane"` opens a temporary zoomed pane and closes it when the command exits.
 
 `type = "shell"` runs detached in the background.
diff --git a/docs/next/website/src/content/docs/ja/cli-reference.mdx b/docs/next/website/src/content/docs/ja/cli-reference.mdx
index 51e8365a..9aa1ebe5 100644
--- a/docs/next/website/src/content/docs/ja/cli-reference.mdx
+++ b/docs/next/website/src/content/docs/ja/cli-reference.mdx
@@ -371,12 +371,12 @@ herdr plugin log list [--plugin ID] [--limit N]
 管理されたターミナルペイン:
 
 ```bash
-herdr plugin pane open --plugin ID --entrypoint ID [--placement overlay|split|tab|zoomed] [--workspace ID] [--target-pane PANE] [--direction right|down] [--cwd PATH] [--env KEY=VALUE] [--focus|--no-focus]
+herdr plugin pane open --plugin ID --entrypoint ID [--placement overlay|popup|split|tab|zoomed] [--width SIZE] [--height SIZE] [--workspace ID] [--target-pane PANE] [--direction right|down] [--cwd PATH] [--env KEY=VALUE] [--focus|--no-focus]
 herdr plugin pane focus <pane_id>
 herdr plugin pane close <pane_id>
 ```
 
-`plugin pane open` は、プラグインがリンクされ、有効で、現在のプラットフォームと互換であることを要求します。マニフェストで宣言された `[[panes]]` コマンドを Herdr 管理のターミナルペインとして起動します。マニフェストのデフォルトは `overlay` で、アクティブなペインの上に一時的なズームオーバーレイを開きます。分割、新しいタブ、ズームされたペインとして開くこともできます。ターミナル以外のネイティブなプラグインペインは今後の対応面です。
+`plugin pane open` は、プラグインがリンクされ、有効で、現在のプラットフォームと互換であることを要求します。マニフェストで宣言された `[[panes]]` コマンドを Herdr 管理のターミナルペインとして起動します。マニフェストのデフォルトは `overlay` で、アクティブなペインの上に一時的なズームオーバーレイを開きます。分割、新しいタブ、ズームされたペイン、またはタブレイアウトを変更しないセッションモーダルな `popup` として開くこともできます。`--width` と `--height` は、外側のポップアップ寸法をターミナルセル数または `80%` のような割合で指定します。省略した寸法はデフォルトでターミナルの半分になり、小さすぎる値はポップアップの最小サイズに制限されます。ポップアップは Herdr ペインではなく、`HERDR_PANE_ID` を受け取らず、pane API やエージェント API に参加しません。ターミナル以外のネイティブなプラグインペインは今後の対応面です。
 
 `--env KEY=VALUE` はプロセスを起動するコマンドで繰り返し指定できます。新しく起動されるプロセスにのみ適用されます。`HERDR_SOCKET_PATH`、`HERDR_BIN_PATH`、`HERDR_ENV`、`HERDR_WORKSPACE_ID`、`HERDR_TAB_ID`、`HERDR_PANE_ID`、`HERDR_PLUGIN_ID`、`HERDR_PLUGIN_ROOT`、`HERDR_PLUGIN_CONFIG_DIR`、`HERDR_PLUGIN_STATE_DIR`、`HERDR_PLUGIN_ENTRYPOINT_ID`、`HERDR_PLUGIN_CONTEXT_JSON` のような Herdr 管理の変数は、呼び出し側が与えた環境変数と衝突した場合も権威を保ちます。
 
diff --git a/docs/next/website/src/content/docs/ja/configuration.mdx b/docs/next/website/src/content/docs/ja/configuration.mdx
index 7105efcd..4a875220 100644
--- a/docs/next/website/src/content/docs/ja/configuration.mdx
+++ b/docs/next/website/src/content/docs/ja/configuration.mdx
@@ -163,11 +163,34 @@ focus_agent = "prefix+alt+1..9"
 ```toml
 [[keys.command]]
 key = "prefix+alt+g"
-type = "pane"
+type = "popup"
 command = "lazygit"
 description = "run lazygit"
+width = "80%"
+height = "80%"
 ```
 
+`type = "popup"` は、タブレイアウトを変更せずにセッションモーダルなポップアップを開きます。
+ポップアップは、コマンドが終了するまで Escape を含むすべてのターミナル入力を受け取ります。
+`width` と `height` は任意です。省略するとデフォルトの半分のサイズになり、数値ならターミナルセル数、`"80%"` のような文字列ならターミナル領域に対する割合を指定できます。
+寸法にはポップアップの枠が含まれ、小さすぎる値は最小サイズに制限されます。
+ポップアップコマンドは `HERDR_PANE_ID` を受け取りません。背後のタイルペインには `HERDR_ACTIVE_PANE_ID` を使ってください。
+
+Unix と macOS では、分割やタブを追加せずに一時的なターミナルを開くこともできます:
+
+```toml
+[[keys.command]]
+key = "prefix+t"
+type = "popup"
+command = "exec \"${SHELL:-sh}\""
+description = "open scratch terminal"
+width = "80%"
+height = "80%"
+```
+
+Windows では、代わりに `command = "powershell.exe -NoLogo"` のようなシェルコマンドを使ってください。
+シェルを終了するとポップアップが閉じ、タイル表示に戻ります。
+
 `type = "pane"` は一時的なペインを開き、コマンドの終了時に閉じます。
 
 `type = "shell"` はバックグラウンドでデタッチ実行します。
diff --git a/docs/next/website/src/content/docs/ja/plugins.mdx b/docs/next/website/src/content/docs/ja/plugins.mdx
index ab9bfec4..426c8e62 100644
--- a/docs/next/website/src/content/docs/ja/plugins.mdx
+++ b/docs/next/website/src/content/docs/ja/plugins.mdx
@@ -264,12 +264,35 @@ Windows クライアントは名前付きパイプに接続します。`HERDR_BI
 マニフェストのペイン `placement` のデフォルトは `overlay` で、アクティブなペインの
 上に一時的なズームオーバーレイを開き、閉じるときに以前のフォーカスとズームを
 復元します。`plugin.pane.open` リクエストは、マニフェストの placement を
-`overlay`、`split`、`tab`、`zoomed` で上書きできます。
+`overlay`、`popup`、`split`、`tab`、`zoomed` で上書きできます。
 
-プラグインペインは、開いた後は通常の Herdr ペインです。プラグインはソケットや CLI を
+`placement = "popup"` は、タイルレイアウトを変更せずにセッションモーダルなターミナルポップアップを開きます。
+マニフェストまたは open リクエストで任意の `width` と `height` を指定できます。
+省略するとデフォルトの半分のサイズになり、数値なら外側のターミナルセル数、`"80%"` のような文字列ならターミナル領域に対する割合になります。
+Escape を含むすべてのターミナル入力を受け取り、コマンドが終了するか `popup.close` リクエストが送られると閉じます。
+最小サイズより小さい寸法は最小値に制限されます。
+
+ペインを常に一時的にしたい場合は、プラグインペインのエントリーポイントに placement を直接宣言します:
+
+```toml
+[[panes]]
+id = "picker"
+title = "Picker"
+platforms = ["linux", "macos"]
+placement = "popup"
+width = "80%"
+height = 20
+command = ["sh", "picker.sh"]
+```
+
+split、tab、zoomed、overlay のプラグインペインは、開いた後は通常の Herdr ペインです。プラグインはソケットや CLI を
 通じて `pane.move`、`pane.swap`、`pane.resize`、`pane.zoom` といった標準のペイン
 API を呼び出せます。ペインがタブやワークスペースをまたいで移動しても、Herdr は
 プラグインペインの所有権を元のペインに結び付けたまま維持します。
+ポップアップは Herdr ペインではなく、セッションに 1 つだけ存在できるリソースです。
+ペイン id を持たず、プラグインのフォーカスコンテキストを変更せず、ペインのライフサイクルイベントを発行せず、pane、layout、永続化、エージェント API に参加しません。
+そのプロセスには `HERDR_PANE_ID` が渡されず、背後のタイルペインは `HERDR_PLUGIN_CONTEXT_JSON` から参照できます。
+Settings、コピーモード、または別の Herdr モーダルが開いている間にポップアップを開くと `ui_busy` が返り、起動後の `plugin.pane.open` は `ok` を返します。
 
 Windows では、ビルドコマンド、アクションコマンド、イベントコマンドは、素の
 コマンドが `PATH` にあれば `npm.cmd`、`bun.cmd`、`pnpm.cmd` のような一般的な
diff --git a/docs/next/website/src/content/docs/ja/socket-api.mdx b/docs/next/website/src/content/docs/ja/socket-api.mdx
index 6e866105..03b98958 100644
--- a/docs/next/website/src/content/docs/ja/socket-api.mdx
+++ b/docs/next/website/src/content/docs/ja/socket-api.mdx
@@ -99,6 +99,7 @@ herdr pane read w1:p2 --source recent --lines 50
 | Worktree | `worktree.list`、`worktree.create`、`worktree.open`、`worktree.remove` |
 | タブ | `tab.create`、`tab.list`、`tab.get`、`tab.focus`、`tab.rename`、`tab.close` |
 | ペイン | `pane.split`、`pane.swap`、`pane.move`、`pane.zoom`、`pane.layout`、`pane.process_info`、`pane.neighbor`、`pane.edges`、`pane.focus_direction`、`pane.resize`、`pane.list`、`pane.current`、`pane.get`、`pane.rename`、`pane.send_text`、`pane.send_keys`、`pane.send_input`、`pane.read`、`pane.report_agent`、`pane.report_agent_session`、`pane.report_metadata`、`pane.clear_agent_authority`、`pane.release_agent`、`pane.close`、`pane.wait_for_output` |
+| ポップアップ | `popup.close` |
 | レイアウト | `layout.export`、`layout.apply` |
 | エージェント | `agent.list`、`agent.get`、`agent.read`、`agent.explain`、`agent.send`、`agent.rename`、`agent.focus`、`agent.start` |
 | イベント | `events.subscribe`、`events.wait` |
@@ -360,7 +361,7 @@ v1 には Herdr が管理するプラグインストレージ API はありま�
 {"id":"req_plugin_pane","method":"plugin.pane.open","params":{"plugin_id":"example.board","entrypoint":"board","placement":"zoomed","target_pane_id":"w1:p1","env":{"HERDR_ROLE":"board"},"focus":true}}
 ```
 
-`plugin.pane.open` は、インストール済みで有効かつプラットフォーム互換のプラグインを要求し、要求されたマニフェストの `[[panes]]` エントリーポイントを argv ベースのターミナルペインとして起動します。マニフェストのペイン `placement` のデフォルトは `overlay` です。リクエストの `placement` は `overlay`、`split`、`tab`、`zoomed` でマニフェストを上書きできます。オーバーレイのペインはアクティブなペインを対象とします。分割とズームのペインは既存のペインを対象とし、タブのペインはワークスペースを対象にできます。ペインは開いた後は通常の Herdr ペインとして振る舞いますが、`plugin.pane.focus` と `plugin.pane.close` はプラグイン API 経由で開かれたペインにのみ作用します。focus は `plugin_pane_focused` を、close は `plugin_pane_closed` を返します。
+`plugin.pane.open` は、インストール済みで有効かつプラットフォーム互換のプラグインを要求し、要求されたマニフェストの `[[panes]]` エントリーポイントを argv ベースのターミナルペインとして起動します。マニフェストのペイン `placement` のデフォルトは `overlay` です。リクエストの `placement` は `overlay`、`popup`、`split`、`tab`、`zoomed` でマニフェストを上書きできます。overlay と popup はアクティブなタイルペインを起動コンテキストとして使います。ポップアップターミナルはセッションモーダルで、タブレイアウトを変更しません。任意の `width` と `height` は、外側のサイズをターミナルセル数または `"80%"` のような割合で指定します。省略した寸法はデフォルトでターミナルの半分になり、小さすぎる値は最小サイズに制限されます。ポップアップはペイン id を持たず、`pane.*` とエージェント API の対象外で、ペインのライフサイクルイベントを発行せず、プラグインのフォーカスコンテキストを背後のタイルペインに維持し、そのプロセスへ `HERDR_PANE_ID` を渡しません。起動は `ok` を返し、`popup.close` はアクティブなポップアップを閉じ、ポップアップがない場合は `popup_not_open` を返します。split と zoomed は既存のペインを対象とし、tab はワークスペースを対象にできます。split、tab、zoomed、overlay は通常の Herdr ペインとして振る舞い、`plugin.pane.focus` と `plugin.pane.close` は引き続きそれらのペインに作用します。
 
 ## ソケットトランスポート
 
diff --git a/docs/next/website/src/content/docs/plugins.mdx b/docs/next/website/src/content/docs/plugins.mdx
index e572ef10..500ae5a3 100644
--- a/docs/next/website/src/content/docs/plugins.mdx
+++ b/docs/next/website/src/content/docs/plugins.mdx
@@ -269,6 +269,20 @@ terminal area. It receives all terminal input, including Escape, and closes
 when the command exits or a `popup.close` request is sent. Dimensions smaller
 than the popup minimum are clamped.
 
+Declare the placement directly on a plugin pane entrypoint when the pane should
+always be transient:
+
+```toml
+[[panes]]
+id = "picker"
+title = "Picker"
+platforms = ["linux", "macos"]
+placement = "popup"
+width = "80%"
+height = 20
+command = ["sh", "picker.sh"]
+```
+
 Split, tab, zoomed, and overlay plugin panes are normal Herdr panes after they
 open. Plugins can call standard pane APIs such as `pane.move`, `pane.swap`,
 `pane.resize`, and `pane.zoom` through the socket or CLI; Herdr keeps plugin
diff --git a/docs/next/website/src/content/docs/zh-cn/cli-reference.mdx b/docs/next/website/src/content/docs/zh-cn/cli-reference.mdx
index 6f1e88a3..6275adb7 100644
--- a/docs/next/website/src/content/docs/zh-cn/cli-reference.mdx
+++ b/docs/next/website/src/content/docs/zh-cn/cli-reference.mdx
@@ -371,12 +371,12 @@ herdr plugin log list [--plugin ID] [--limit N]
 托管终端窗格:
 
 ```bash
-herdr plugin pane open --plugin ID --entrypoint ID [--placement overlay|split|tab|zoomed] [--workspace ID] [--target-pane PANE] [--direction right|down] [--cwd PATH] [--env KEY=VALUE] [--focus|--no-focus]
+herdr plugin pane open --plugin ID --entrypoint ID [--placement overlay|popup|split|tab|zoomed] [--width SIZE] [--height SIZE] [--workspace ID] [--target-pane PANE] [--direction right|down] [--cwd PATH] [--env KEY=VALUE] [--focus|--no-focus]
 herdr plugin pane focus <pane_id>
 herdr plugin pane close <pane_id>
 ```
 
-`plugin pane open` 要求插件已链接、已启用并与当前平台兼容。它把清单声明的 `[[panes]]` 命令作为 Herdr 管理的终端窗格启动。清单的默认值是 `overlay`,在活动窗格上方打开一个临时的缩放覆盖层。它也可以作为分割、新标签页或缩放窗格打开。非终端的原生插件窗格是之后的能力面。
+`plugin pane open` 要求插件已链接、已启用并与当前平台兼容。它把清单声明的 `[[panes]]` 命令作为 Herdr 管理的终端窗格启动。清单的默认值是 `overlay`,在活动窗格上方打开一个临时的缩放覆盖层。它也可以作为分割、新标签页、缩放窗格,或不改变标签页布局的会话级模态 `popup` 打开。`--width` 和 `--height` 以终端单元格数或 `80%` 这样的百分比设置弹窗外层尺寸;省略时默认为终端大小的一半,过小的值会限制为弹窗最小尺寸。弹窗不是 Herdr 窗格,不会收到 `HERDR_PANE_ID`,也不参与 pane 或智能体 API。非终端的原生插件窗格是之后的能力面。
 
 `--env KEY=VALUE` 可以在启动进程的命令上重复使用,只作用于新启动的进程。当与调用方提供的环境变量冲突时,`HERDR_SOCKET_PATH`、`HERDR_BIN_PATH`、`HERDR_ENV`、`HERDR_WORKSPACE_ID`、`HERDR_TAB_ID`、`HERDR_PANE_ID`、`HERDR_PLUGIN_ID`、`HERDR_PLUGIN_ROOT`、`HERDR_PLUGIN_CONFIG_DIR`、`HERDR_PLUGIN_STATE_DIR`、`HERDR_PLUGIN_ENTRYPOINT_ID` 和 `HERDR_PLUGIN_CONTEXT_JSON` 等 Herdr 管理的变量保持权威。
 
diff --git a/docs/next/website/src/content/docs/zh-cn/configuration.mdx b/docs/next/website/src/content/docs/zh-cn/configuration.mdx
index 8a232cc7..055ca3ad 100644
--- a/docs/next/website/src/content/docs/zh-cn/configuration.mdx
+++ b/docs/next/website/src/content/docs/zh-cn/configuration.mdx
@@ -163,11 +163,34 @@ focus_agent = "prefix+alt+1..9"
 ```toml
 [[keys.command]]
 key = "prefix+alt+g"
-type = "pane"
+type = "popup"
 command = "lazygit"
 description = "run lazygit"
+width = "80%"
+height = "80%"
 ```
 
+`type = "popup"` 会打开一个会话级模态弹窗,而不改变标签页布局。
+弹窗会接收包括 Escape 在内的所有终端输入,直到命令退出。
+`width` 和 `height` 是可选的;省略时默认为终端大小的一半,数字表示终端单元格数,`"80%"` 这样的字符串表示终端区域的百分比。
+尺寸包含弹窗边框,过小的值会限制为弹窗最小尺寸。
+弹窗命令不会收到 `HERDR_PANE_ID`;可使用 `HERDR_ACTIVE_PANE_ID` 引用底层平铺窗格。
+
+在 Unix 和 macOS 上,还可以打开一个临时终端,而无需添加分割或标签页:
+
+```toml
+[[keys.command]]
+key = "prefix+t"
+type = "popup"
+command = "exec \"${SHELL:-sh}\""
+description = "open scratch terminal"
+width = "80%"
+height = "80%"
+```
+
+在 Windows 上,请改用 `command = "powershell.exe -NoLogo"` 之类的 shell 命令。
+退出 shell 即可关闭弹窗并恢复平铺终端视图。
+
 `type = "pane"` 会打开一个临时窗格，并在命令退出时关闭它。
 
 `type = "shell"` 会在后台分离运行。
diff --git a/docs/next/website/src/content/docs/zh-cn/plugins.mdx b/docs/next/website/src/content/docs/zh-cn/plugins.mdx
index 8d3ba6fc..a22e56b8 100644
--- a/docs/next/website/src/content/docs/zh-cn/plugins.mdx
+++ b/docs/next/website/src/content/docs/zh-cn/plugins.mdx
@@ -235,11 +235,32 @@ shell 插件可以从各个环境变量读取常用 id,或解析上下文 JSON �
 
 清单中窗格的 `placement` 默认为 `overlay`,它在活动窗格上方打开一个
 临时的缩放覆盖层,关闭时恢复之前的焦点和缩放。`plugin.pane.open` 请求
-可以用 `overlay`、`split`、`tab` 或 `zoomed` 覆盖清单的 placement。
+可以用 `overlay`、`popup`、`split`、`tab` 或 `zoomed` 覆盖清单的 placement。
 
-插件窗格打开后就是普通的 Herdr 窗格。插件可以通过 socket 或 CLI 调用
+`placement = "popup"` 会打开一个会话级模态终端弹窗,而不改变平铺布局。
+可以在清单或 open 请求中指定可选的 `width` 和 `height`;省略时默认为终端大小的一半,数字表示外层终端单元格数,`"80%"` 这样的字符串表示终端区域的百分比。
+弹窗会接收包括 Escape 在内的所有终端输入,并在命令退出或发送 `popup.close` 请求时关闭。
+小于弹窗最小尺寸的值会限制为最小值。
+
+如果某个插件窗格应始终是临时的,可直接在入口点上声明 placement:
+
+```toml
+[[panes]]
+id = "picker"
+title = "Picker"
+platforms = ["linux", "macos"]
+placement = "popup"
+width = "80%"
+height = 20
+command = ["sh", "picker.sh"]
+```
+
+split、tab、zoomed 和 overlay 插件窗格打开后就是普通的 Herdr 窗格。插件可以通过 socket 或 CLI 调用
 `pane.move`、`pane.swap`、`pane.resize`、`pane.zoom` 等标准窗格 API;
 窗格跨标签页或工作区移动时,Herdr 会让插件窗格的所有权跟随底层窗格。
+弹窗不是 Herdr 窗格,而是会话级单例资源:它没有窗格 id,不会改变插件焦点上下文,不会发出窗格生命周期事件,也不参与 pane、layout、持久化或智能体 API。
+其进程不会收到 `HERDR_PANE_ID`;底层平铺窗格仍可通过 `HERDR_PLUGIN_CONTEXT_JSON` 获取。
+在 Settings、复制模式或其他 Herdr 模态界面打开时尝试打开弹窗会返回 `ui_busy`;启动成功后,`plugin.pane.open` 返回 `ok`。
 
 在 Windows 上,构建命令、动作命令和事件命令会在裸命令位于 `PATH` 上时
 解析常见的 `PATHEXT` shim,比如 `npm.cmd`、`bun.cmd` 和 `pnpm.cmd`。
diff --git a/docs/next/website/src/content/docs/zh-cn/socket-api.mdx b/docs/next/website/src/content/docs/zh-cn/socket-api.mdx
index 553ce363..33190f1f 100644
--- a/docs/next/website/src/content/docs/zh-cn/socket-api.mdx
+++ b/docs/next/website/src/content/docs/zh-cn/socket-api.mdx
@@ -99,6 +99,7 @@ herdr pane read w1:p2 --source recent --lines 50
 | Worktree | `worktree.list`、`worktree.create`、`worktree.open`、`worktree.remove` |
 | 标签页 | `tab.create`、`tab.list`、`tab.get`、`tab.focus`、`tab.rename`、`tab.close` |
 | 窗格 | `pane.split`、`pane.swap`、`pane.move`、`pane.zoom`、`pane.layout`、`pane.process_info`、`pane.neighbor`、`pane.edges`、`pane.focus_direction`、`pane.resize`、`pane.list`、`pane.current`、`pane.get`、`pane.rename`、`pane.send_text`、`pane.send_keys`、`pane.send_input`、`pane.read`、`pane.report_agent`、`pane.report_agent_session`、`pane.report_metadata`、`pane.clear_agent_authority`、`pane.release_agent`、`pane.close`、`pane.wait_for_output` |
+| 弹窗 | `popup.close` |
 | 布局 | `layout.export`、`layout.apply` |
 | 智能体 | `agent.list`、`agent.get`、`agent.read`、`agent.explain`、`agent.send`、`agent.rename`、`agent.focus`、`agent.start` |
 | 事件 | `events.subscribe`、`events.wait` |
@@ -360,7 +361,7 @@ v1 没有 Herdr 管理的插件存储 API。`HERDR_PLUGIN_CONFIG_DIR` 和 `HERDR
 {"id":"req_plugin_pane","method":"plugin.pane.open","params":{"plugin_id":"example.board","entrypoint":"board","placement":"zoomed","target_pane_id":"w1:p1","env":{"HERDR_ROLE":"board"},"focus":true}}
 ```
 
-`plugin.pane.open` 要求已安装、已启用、平台兼容的插件,然后把请求的清单 `[[panes]]` 入口点作为 argv 支撑的终端窗格启动。清单窗格的 `placement` 默认为 `overlay`;请求的 `placement` 可以用 `overlay`、`split`、`tab` 或 `zoomed` 覆盖清单。覆盖层窗格针对活动窗格。分割和缩放窗格针对已有窗格;标签页窗格可以针对工作区。窗格打开后表现得像普通 Herdr 窗格,但 `plugin.pane.focus` 和 `plugin.pane.close` 只作用于通过插件 API 打开的窗格。focus 返回 `plugin_pane_focused`;close 返回 `plugin_pane_closed`。
+`plugin.pane.open` 要求已安装、已启用、平台兼容的插件,然后把请求的清单 `[[panes]]` 入口点作为 argv 支撑的终端窗格启动。清单窗格的 `placement` 默认为 `overlay`;请求的 `placement` 可以用 `overlay`、`popup`、`split`、`tab` 或 `zoomed` 覆盖清单。overlay 和 popup 使用活动平铺窗格作为启动上下文。弹窗终端是会话级模态界面,不会改变标签页布局;可选的 `width` 和 `height` 以终端单元格数或 `"80%"` 这样的百分比设置外层尺寸。省略时默认为终端大小的一半,过小的值会限制为弹窗最小尺寸。弹窗没有窗格 id,不属于任何 `pane.*` 或智能体 API,不会发出窗格生命周期事件,会把插件焦点上下文保留在底层平铺窗格上,也不会向其进程导出 `HERDR_PANE_ID`。弹窗启动返回 `ok`;`popup.close` 关闭活动弹窗,没有弹窗时返回 `popup_not_open`。split 和 zoomed 针对已有窗格,tab 可以针对工作区。split、tab、zoomed 和 overlay 打开后表现得像普通 Herdr 窗格,`plugin.pane.focus` 和 `plugin.pane.close` 仍可操作这些窗格。
 
 ## Socket 传输