fpasoterm 1.6.0

package/docs/config.ja.md

@@ -0,0 +1,544 @@
+# fpasoterm 設定
+
+fpasoterm はユーザー編集用の設定を以下から読み込みます。
+
+```text
+~/.config/fpasoterm/User/config.toml
+```
+
+Windows の `~` は現在の user profile を表すため、既定 path は
+`%USERPROFILE%\.config\fpasoterm\User\config.toml` です。
+
+起動時に、全デフォルト項目を含む example を以下へ書き出し、古い場合は更新します。
+
+```text
+~/.config/fpasoterm/User/config.toml.example
+```
+
+`config.toml.example` を `config.toml` にコピーし、変更したい値だけ編集してください。既存の `config.toml` は上書きしません。`config.toml.example` が無い場合や古い場合は、次回起動時に再生成されます。
+
+別の設定ファイルを一度だけ使う場合:
+
+```sh
+fpasoterm --config ~/.config/fpasoterm/User/work.toml
+fpasoterm -c ~/.config/fpasoterm/User/work.toml
+```
+
+window menu の `Help` には、そのwindowが現在使用している設定ファイルの絶対pathを表示します。
+`OSC 777;config=...` で runtime config file を適用した場合も、適用後のpathを表示します。
+
+## 変更の反映タイミング
+
+fpasoterm は各 window process の起動時に `config.toml` を読みます。launcher は解決済み設定を
+in-memory JSON snapshot として native process へ渡します。これは file cache ではなく、起動済み
+window は TOML file の変更を監視しません。編集後は対象 window を閉じて再度起動してください。
+`[keybindings]` も同じです。shortcut label と binding は起動時に解決されるため、TOML を編集した
+だけでは既存 window に反映されません。
+
+```mermaid
+flowchart TD
+  U["User TOML<br/>~/.config/fpasoterm/User/config.toml"]
+  X["自動生成 example<br/>config.toml.example"]
+  S["保存済み bounds<br/>window-state.json"]
+  N["Node launcher<br/>bin/fpasoterm"]
+  E["embedded default<br/>src-tauri/default-config.toml"]
+  D["配布済み direct binary<br/>fpasoterm.exe / fpasoterm"]
+  J["FPASOTERM_RUNTIME_CONFIG_JSON<br/>一つの process 用 snapshot"]
+  W["native window と renderer"]
+  T["terminal shell から fpasoterm を実行"]
+
+  U --> N
+  N --> X
+  S -. 保存済み width height .-> N
+  N --> J --> W
+  U --> D
+  E --> D
+  S -. 保存済み width height .-> D
+  D --> W
+  W --> T --> D
+  J -. 子 process は継承した native snapshot を無視 .-> D
+```
+
+`FPASOTERM_RUNTIME_CONFIG_JSON` はdiskへ保存されず、古いTOML fileのcacheでもありません。
+新しい起動ごとに、Node launcherは選択された`config.toml`を読み直して新しいJSON snapshotを作り、
+配布済みdirect binaryは選択されたTOMLを自身で読みます。fileが無い場合や古いpartial TOMLの場合も、
+current defaultとmergeして読み込みます。`config.toml.example`の更新は別処理であり、既存userの
+`config.toml`を変更しません。
+
+設定の読込処理が`config.toml`または`window-state.json`を書き換えることはありません。保存済み
+boundsは`window.rememberBounds = true`の場合だけTOMLのwidth/heightより優先され続けます。保存sizeを
+削除する操作は明示的な`--reset-window-state`だけです。
+
+window を閉じずに現在の terminal session へ適用する場合は、terminal から次の OSC sequence を
+出力します。不明な場合は `Help` に表示される絶対pathを使用してください。
+
+```sh
+config_path="$HOME/.config/fpasoterm/User/config.toml"
+printf '\033]777;config=%s\a\r\n' "$config_path"
+```
+
+PowerShell の場合:
+
+```powershell
+$configPath = Join-Path $HOME '.config\fpasoterm\User\config.toml'
+[Console]::Write("$([char]27)]777;config=$configPath$([char]7)`r`n")
+```
+
+`window.rememberBounds = true` の場合、`window.width` と `window.height` は保存済み
+`window-state.json` により追加で上書きされます。`config.toml` で size を試す場合は、
+`fpasoterm --reset-window-state` を実行してから新しい window を開いてください。
+
+設定済みウィンドウサイズを一時的に上書きする場合:
+
+```sh
+fpasoterm --size 1200x760
+fpasoterm -z 1200x760
+```
+
+titlebar の表示名や色を一時的に上書きする場合。複数ウィンドウを開いた時の識別に使えます。
+
+```sh
+fpasoterm --title work --titlebar-color '#2e7d32'
+fpasoterm -t logs -b '#6a1b9a'
+```
+
+`--title` を使った場合、shell が送る title change は無視されるため、
+ウィンドウ識別用の表示名が維持されます。起動中 terminal から意図して
+変更したい場合は `OSC 777;title=...` を使ってください。
+
+起動後に shell でコマンドを実行する場合:
+
+```sh
+fpasoterm --command "tmux attach -t work"
+fpasoterm -e "tmux attach -t work"
+```
+
+一度だけ別の shell を使う場合:
+
+```sh
+fpasoterm --shell pwsh.exe
+fpasoterm --shell cmd.exe
+fpasoterm -s /usr/bin/fish
+```
+
+保存済みウィンドウサイズを削除する場合:
+
+```sh
+fpasoterm --reset-window-state
+```
+
+全設定をOSごとのデフォルトへ戻す場合:
+
+```sh
+fpasoterm --reset-config
+# 短縮形: fpasoterm -R
+```
+
+既存ファイルは同じ場所の `config.toml.backup-<timestamp>` へrenameして残し、
+完全な新しい`config.toml`を生成します。保存済み`window-state.json`も削除するため、
+次回起動時はデフォルトの幅1000、高さ680が使われます。このコマンドはwindowを
+開かず終了します。`--config <path>`と併用した場合は選択したconfigだけをrenameして
+resetし、標準のローカルwindow stateも削除します。
+
+既存の値を置き換えず、新しい fpasoterm version で追加された設定項目だけを追加する場合:
+
+```sh
+fpasoterm --update-config
+```
+
+このcommandは既存の対応済みvalueを維持した完全な正規化済み`config.toml`を書き出し、
+書換前に`config.toml.backup-<timestamp>`を作成します。`window-state.json`は変更しません。
+`--config <path>`で別fileも更新できます。Node launcherと配布済みdirect binaryの両方で
+使用できます。
+
+現在の対応設定schemaに含まれない項目を削除する場合:
+
+```sh
+fpasoterm --prune-config
+```
+
+こちらもbackupを作成し、対応済みvalueは維持します。ただしthird-party plugin用のcustom key
+を含め、unknownな設定を全て削除します。backupを確認できる状態でだけ実行してください。
+新しい既定値の追加と削除済み項目の除去の両方が必要な場合は、先に`--prune-config`、次に
+`--update-config`を実行します。
+
+解決済み設定と plugin 状態を表示する場合:
+
+```sh
+fpasoterm --show-config
+```
+
+選択中TOMLを変更せず検証する場合、選択中pathを確認する場合、現在の完全な既定exampleを
+標準出力へ出す場合:
+
+```sh
+fpasoterm --config-check
+fpasoterm --config-path
+fpasoterm --config-example > config.toml
+```
+
+warning、exit status、GitHub Issue向けの`--diagnostics` reportは
+[設定と診断](diagnostics.ja.md)を参照してください。
+
+## Profile
+
+profileは一回の起動にだけ適用する名前付きoverlayです。通常設定を先にmergeし、
+次に`[profiles.<name>]`、最後に`--title`、`--shell`、`--size`などのCLI引数を
+適用します。このためprofileを選んでも`config.toml`や保存済みwindow boundsは
+書き換わりません。
+
+```toml
+[terminal]
+fontSize = 14
+
+[profiles.large-font.terminal]
+fontSize = 18
+
+[profiles.transparent.window]
+titlebarColor = "#00695c"
+
+[profiles.transparent.terminal]
+backgroundOpacity = 0.65
+```
+
+```sh
+fpasoterm --profile-list
+fpasoterm --profile large-font
+fpasoterm --config examples/config/profiles.toml --profile transparent
+```
+
+profile名はcase-sensitiveなTOML table名です。存在しない名前、またはtableではない
+profileを指定すると、通常設定へ黙ってfallbackせずerrorで終了します。
+`--show-config`と`--diagnostics`には選択中profileを表示します。
+`--config`を指定せず`fpasoterm --profile large-font`を使う場合は、
+`fpasoterm --config-path`で表示されるfileへ`[profiles.large-font.terminal]`tableを
+copyします。[`examples/config/profiles.toml`](../examples/config/profiles.toml)も参照してください。
+
+コマンドラインから plugin を有効化・無効化する場合:
+
+```sh
+fpasoterm --enable-plugin hello,theme
+fpasoterm --disable-plugin hello,theme
+```
+
+plugin 操作は `User/plugins` 配下のファイル名で選択します。複数指定はカンマ区切り、
+または同じオプションの繰り返しが使用できます。同名ファイルが複数のサブディレクトリに
+ある場合は `group/hello.ts` のように plugins directory からの相対 path を指定します。
+
+## 全デフォルト
+
+```toml
+[window]
+title = "fpasoterm"
+width = 1000
+height = 680
+minWidth = 420
+minHeight = 260
+backgroundColor = "rgba(0, 0, 0, 0)"
+titlebarColor = "#1565c0"
+titleLocked = true
+themeSource = "system"
+rememberBounds = true
+frame = false
+[terminal]
+allowTransparency = true
+cursorBlink = true
+cursorStyle = "block"
+fontFamily = "\"DejaVu Sans Mono\", \"Noto Sans Mono\", \"Noto Sans Mono CJK JP\", \"Noto Sans Mono CJK KR\", \"Noto Sans Mono CJK SC\", \"NanumGothicCoding\", \"BIZ UDGothic\", \"Symbols Nerd Font Mono\", \"Symbols Nerd Font\", \"JetBrainsMono Nerd Font\", \"Noto Sans CJK JP\", \"Noto Sans CJK KR\", \"Noto Sans CJK SC\", \"Noto Sans CJK TC\", \"Hiragino Kaku Gothic ProN\", \"Apple SD Gothic Neo\", \"Malgun Gothic\", Meiryo, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
+fontSize = 14
+# 省略時の既定値はmacOS Intelで12、その他のOSで14です。
+lineHeight = 1
+minimumContrastRatio = 1
+rescaleOverlappingGlyphs = false
+backgroundOpacity = 0.65
+scrollback = 1000
+termName = "xterm-256color"
+encoding = "utf-8"
+shell = ""
+
+# enhanced Kitty keyboard inputを明示的に必要とするTUIだけで有効化します。
+# 現在無効なgraphics addonとは別の設定です。
+kittyKeyboard = false
+
+# [terminal.images] は将来の安定した renderer 用に予約されています。
+# 現在の build はこの section を無視します。config.toml へ追加しないでください。
+
+[terminal.theme]
+background = "rgba(16, 19, 23, 0.65)"
+foreground = "#e8edf2"
+cursor = "#f5d76e"
+selectionBackground = "#35506b"
+black = "#11151a"
+red = "#ff6b6b"
+green = "#8bd17c"
+yellow = "#f5d76e"
+blue = "#7bb7ff"
+magenta = "#d7a8ff"
+cyan = "#63d4d5"
+white = "#e8edf2"
+brightBlack = "#5d6978"
+brightRed = "#ff8f8f"
+brightGreen = "#ade89f"
+brightYellow = "#ffe08a"
+brightBlue = "#a4ceff"
+brightMagenta = "#e3c3ff"
+brightCyan = "#9de9ea"
+brightWhite = "#ffffff"
+
+[keybindings]
+# Mod は Windows/Linux の Ctrl、macOS の Cmd を表します。
+prefix = "Mod+Shift"
+# 一文字の value は prefix を継承します。full shortcut はその操作だけ上書きします。
+# physical key の例: newWindow = "Ctrl+Alt+KeyN"
+logMenu = "L"
+logToggle = "S"
+logShow = "P"
+copy = "C"
+paste = "V"
+menu = "M"
+help = "H"
+newWindow = "N"
+openCwd = "o"
+broadcast = "B"
+kill = "K"
+tile = "T"
+closeAll = "X"
+
+### キー名
+
+`prefix` には `+` 区切りで modifier だけを指定できます。値は `Ctrl` または `Control`、`Alt`
+または `Option`、`Shift`、`Meta` または `Cmd` または `Command`、`Mod` です。`Mod` は
+Windows/Linux の `Ctrl`、macOS の `Cmd` を表します。modifier の大文字小文字は区別しません。
+`Escape` など action key を `prefix` の一部にはできません。
+
+各 action には、`prefix` を継承する action key 一つ、または `Ctrl+Shift+KeyN` のような full
+shortcut 一つを指定できます。以下の名前を使用できます。
+
+| 種類 | 名前 | 照合 |
+| --- | --- | --- |
+| 文字 | `A`-`Z`、`0`-`9`、`-` | browser の key value。keyboard layout 依存 |
+| 名前付きキー | `Tab`、`Enter`、`Escape`、`Space`、`Backspace`、`Delete`、`Insert`、`Home`、`End`、`PageUp`、`PageDown` | `Space` と physical form は keyboard code、それ以外は key value |
+| function/cursor | `F1`-`F24`、`ArrowUp`、`ArrowDown`、`ArrowLeft`、`ArrowRight` | physical keyboard code |
+| physical key | `KeyA`-`KeyZ`、`Digit0`-`Digit9`、`Space`、`Numpad0`-`Numpad9`、`NumpadEnter`、`NumpadAdd`、`NumpadSubtract`、`NumpadMultiply`、`NumpadDivide`、`NumpadDecimal` | physical keyboard code |
+| 日本語 IME key | `ZenkakuHankaku`、`KanaMode`、`KanjiMode` | browser の key value。keyboard/OS 依存 |
+
+`Tab`、`Escape`、`Delete`、`Backspace` は使用可能です。例えば `kill = "Escape"` は設定済み
+prefix を継承し、`help = "Ctrl+Shift+F1"` は Help だけ full shortcut になります。`Space` は
+literal の `Space` で指定できます。例: `broadcast = "Space"`。通常のキーは keyboard layout
+に依存しない `KeyN`、`Digit1` を推奨します。
+
+`Fn` は action / modifier として使用できません。通常は keyboard firmware が処理し、browser に
+独立した key event が届かないためです。`Fn+F1` は OS が F1 event として渡す場合だけ `F1` として
+指定できます。日本語 IME key は IME または OS が先に捕捉する場合があるため、application action
+には推奨しません。同様に `Alt+Tab`、`Ctrl+Alt+Tab`、一部の function key のような OS 予約済み
+shortcut は fpasoterm に届かないことがあります。同じ full shortcut を複数の fpasoterm action へ
+割り当てないでください。
+
+`Ctrl+X` 単体は、例えば `closeAll = "Ctrl+X"` として指定できる有効な full shortcut です。
+`Ctrl+X` を押してから `N` を押す形式は、一つのshortcutではなく順序付きkey chordです。現行の
+config formatではkey chordには対応していません。
+
+Windows では `Ctrl+N` や `Ctrl+Shift+N` を fpasoterm の確認に使わないでください。WebView または
+IME が renderer より先に捕捉する場合があります。代わりに、OS予約と競合しにくい明示的なbindingを
+指定します。
+
+```toml
+[keybindings]
+newWindow = "Ctrl+F2"
+```
+
+`--debug-keys --console-diagnostics` で起動すると、動作するshortcutではF2 eventに`ctrl=true`と
+`shortcut matched action=newWindow spec=Ctrl+F2`の両方が出ます。`ctrl=false`の場合はOSがmodifierを
+渡していないため、renderer側では修正できません。
+
+[plugins]
+enabled = []
+
+[sync]
+enabled = false
+provider = "folder"
+path = ""
+channel = "default"
+diagnostics = true
+maxBytes = 1048576
+commands = false
+commandSecret = ""
+commandTtlSeconds = 60
+
+[logging]
+enabled = true
+directory = ""
+autoStart = false
+maxBytes = 10485760
+```
+
+`lineHeight` の既定値はmacOSを含む全OSで`1`です。TUI logo行の連続性より`g`/`q`/`y`などdescenderの判別を優先します。fpasoterm同梱のxterm.jsは`0.5`以上を受け付けます。macOSの以前のcompact既定値`0.8`、`0.81`、`0.82`、`0.85`、`0.9`、`0.92`と一致する既存設定はruntimeで移行します。明示したcustom値は保持します。
+
+macOSではbox/block glyphのmetricsがmacOS Terminalに近い`Menlo`を既定fontの先頭にします。`SF Mono`はfallbackとして維持します。
+
+### 文字コード
+
+`terminal.encoding` の既定値は `utf-8` です。Unixでは、親processからUTF-8ではないlocaleを
+継承した場合にも、UTF-8 PTYへUTF-8 localeを設定します。これによりmacOSの`ls`などが
+日本語pathを`?`へ置換することを防ぎます。legacy programが出力するbyte列を使用する場合だけ、
+`shift-jis` または `euc-jp` を設定してください。文字コードの自動判定は曖昧で誤表示を起こすため
+実装しません。**Diagnostics > Capability Test** のselectorで保存でき、decoderとshell localeを
+適用するにはwindowを再起動します。
+
+```toml
+[terminal]
+encoding = "utf-8"
+```
+
+## セクション
+
+- `window`: titlebar の表示名、初期ウィンドウサイズ、最小サイズ、背景色、custom titlebar 色、native theme source、frame/titlebar 表示、最後の window bounds を local に記憶するかどうか。`themeSource` は `system`、`light`、`dark` を指定できます。`titleLocked` は既定で `true` で、shell が送る title sequence で fpasoterm の titlebar が上書きされないようにします。`--title` / `-t` と `--titlebar-color` / `-b` は一度だけ titlebar 表示を上書きします。
+- `terminal`: terminal 作成時に渡す xterm.js options。既定の `fontFamily` は罫線・block文字のcell計測を安定させるため、Noto/DejaVu等幅font候補を先頭にします。Nerd Font候補はprivate-use glyph用のfallbackです。macOSでは`SF Mono`、`Menlo`、Hiragino、`Apple SD Gothic Neo`を含みます。ASCII文字のcell計測を等幅に保つため、可変幅の`Hiragino Sans`を等幅fontより前へ置かないでください。他OSでは半角カタカナやCJK文字を優先して描画するため、日本語・韓国語・中国語向けのNoto CJK候補とOSごとの一般的なfallbackを含めます。ただし、installされていないfontのglyphはfont stackだけでは表示できません。韓国語がtofu boxになる、またはNerd Fontのprivate-use glyphが別記号になる場合は、Font / Glyph Testで確認し、OS側でCJK fontまたはNerd Fontをinstallしてください。`lineHeight` の既定値はterminal artやTUI logoの隣接行がつながるように `1` です。`minimumContrastRatio` の既定値は `1` で、terminal applicationが指定したANSI/RGB色を維持します。`rescaleOverlappingGlyphs` の既定値は `false` で、block artやPowerline形式の装飾などapplication側のglyphを保ちます。CJK fontが隣接cellへ重なる場合だけ有効化してください。`terminal.termName` は既定で `xterm-256color` です。backend PTY は `TERM=xterm-256color` と `COLORTERM=truecolor` を設定するため、tmuxなどのterminal multiplexerがterminfoを使え、TUI applicationもtruecolor経路を選択できます。`terminal.shell` は空でなければ platform default shell を上書きします。Windows では `powershell.exe`、`pwsh.exe`、`cmd.exe` などを指定できます。`--shell <command>` / `-s <command>` は一度だけこの設定を上書きします。`terminal.kittyKeyboard` は既定で `false` です。enhanced Kitty keyboard inputを明示的に必要とするTUIだけで有効化してください。WebViewごとにIME動作が異なるためです。graphicsを有効化する設定ではありません。`[terminal.images]` は予約済みで、現在の build は値を無視します。追加・有効化しないでください。
+
+Windowsで非標準の場所にPowerShellをinstallしている場合は、`C:\Program Files\PowerShell\7\pwsh.exe` のようにshellのフルパスを指定できます。
+
+PowerShell 7 (`pwsh.exe`) が利用可能な場合に既定 shell として選択します。見つからない場合は一般的なPowerShell 7のinstall pathを確認します。
+
+### TUI互換性の確認
+
+block glyphを詰めて使うterminal applicationや、意図して低contrastなRGB色を使うapplicationでは、
+contrastまたはglyph rescalingの上書きにより表示が崩れることがあります。既定値はこれらの
+applicationをそのまま表示する値です。既存設定と比較する場合は、`[terminal]`へ次を設定して
+再起動するか、一度だけ`examples/config/tui-compatibility.toml`を指定して起動してください。
+
+```toml
+[terminal]
+minimumContrastRatio = 1
+rescaleOverlappingGlyphs = false
+```
+- `keybindings`: application shortcut の設定。`prefix = "Mod+Shift"` はWindows/Linuxでは`Ctrl+Shift`、macOSでは`Cmd+Shift`を表します。Windowsでkeyboard layoutまたは他applicationが`Ctrl+Shift`を捕捉する場合は、`prefix = "Ctrl+Alt"`へ変更してください。この変更は共通modifierを置換するため、従来の`Ctrl+Shift` application shortcutは実行されなくなります。prefix tokenは大文字小文字を区別しませんが、`Ctrl`/`Control`、`Alt`/`Option`、`Shift`、`Meta`/`Cmd`/`Command`、`Mod`だけが使用できます。`Ctrl+Esc`は`Esc`がmodifierではなくaction keyのため無効です。無効なprefixは`Mod+Shift`へfallbackし、menuのtooltipで確認できます。一文字のaction valueは`prefix`を継承し、full shortcut はそのactionだけを上書きします。action keyには`Escape`、`F1`、`ArrowUp`、`KeyN`/`Digit1`などを使用できます。例: `newWindow = "Ctrl+Alt+KeyN"`、`kill = "Ctrl+Alt+Escape"`。`KeyN`のような値はphysical keyboard keyで照合するため、keyboard layoutによる`event.key`の違いを避けられます。window menuの先頭には有効なprefixを表示し、各actionはキーだけを表示します。menuを開くと最初のitemへfocusし、`Tab`/`Shift+Tab`と矢印キーで移動、`Escape`で閉じてterminalへfocusを戻します。再起動またはruntime config fileの適用でmenu labelとbindingを更新します。
+fpasoterm は IME composition event を仮入力表示のためだけに監視します。xterm.js と WebView のnativeな入力配送をそのまま使い、fpasoterm が IME text を抑止・再送・置換・直接確定することはありません。ChromeOS/Linuxでは、新しいcompositionの開始時にまだ新しい仮入力textが入っていないため、hidden helper textareaに過去の確定textが残っている場合だけclearします。後続変換が過去の確定textを継承することを防ぎ、terminal textとPTY payloadは変更しません。Windows/LinuxではWebViewがxtermのhelper textareaを描画しない場合にだけ、表示専用の`IME` fallbackを使います。macOSはWebKit nativeのmarked text描画を使い、このfallbackを追加しないため、確定後にIME overlayが残りません。
+- `plugins.enabled`: `~/.config/fpasoterm/User/` からの相対 plugin path。
+- `sync`: diagnostics と明示的に送信した broadcast command を同期フォルダで共有する設定。`provider = "folder"` は Google Drive for desktop などで同期済みのローカルフォルダを使います。`commands` は短寿命の共有 command を許可し、`commandTtlSeconds` は実行可能な時間を制限します。詳細は [Sync Folder](sync.ja.md) を参照してください。
+- `logging`: terminal output logging 設定。hamburger menu に `Log Start (^S)` / `Log Stop (^S)` と `Log Show (^P)` を表示します。`Ctrl+Shift+L` はlog操作にfocusした状態でmenuを開き、`Ctrl+Shift+S` は記録を直接切り替え、`Ctrl+Shift+P` はcaptured `terminal-*.log` の一覧から表示対象を選択する画面を開きます。制御シーケンスを除去した readable terminal output を local file に記録します。自動生成されるlog名には titlebar の title と timestamp が入り、例は `terminal-work-<timestamp>.log` です。log panel では選択した停止済み log の削除ができ、`Delete All` は log panel 内の確認で承認された場合だけ active log を空にして、設定済み log directory の停止済み `terminal-*.log` を全て削除します。`directory` が空の場合は `~/.config/fpasoterm/User/logs` が使われ、必要に応じて同期フォルダを指定できます。path には `~`、`%USERPROFILE%`、`$HOME` などを使えます。OS 間で共有する設定では `~` が最も扱いやすい指定です。
+
+`window.rememberBounds` が有効な場合、最後の window size は `~/.config/fpasoterm/User/window-state.json` に保存され、次回起動時に復元されます。
+
+window 表示と size は、デフォルト設定、`config.toml` に明示した値、size については保存済み `window-state.json`、最後に `--title`、`--titlebar-color`、`--size` などの一時 CLI 指定、の順に解決されます。size 設定変更を保存済み状態より優先したい場合は、`fpasoterm --reset-window-state` を実行してください。
+
+Windowsでは、起動したterminal processの`Path`先頭にfpasoterm executable directoryを追加します。macOSでは、以前のreleaseでも使用していた標準的な`~/.local/bin/fpasoterm`を現在起動中のapp bundle向けに毎回生成し、`~/.local/bin`を`PATH`先頭に置いて全引数を変更せず転送します。互換性のため`~/.config/fpasoterm/bin/fpasoterm`も更新します。これにより従来のcommand pathを維持したまま、fpasoterm内で`fpasoterm --help`、`--list`、`--close`など直接binaryのcommandを実行できます。macOSで新しいGUIを起動する場合は既定でprocessを切り離して現在のpromptを解放します。終了まで待つ場合は`--foreground`を使います。Node launcher専用option、`--hoge`や`-?`などの未知option、値不足のoptionを配布binaryへ指定した場合は、無関係なGUIを開かず一行のerrorだけを表示します。全option一覧が必要な場合だけ`--help`を実行してください。`--version` と app内の `Help (^H)` panelにはpackage versionとbuild commitを表示するため、同じversionのcontributor buildやPR buildも識別できます。
+
+macOSは最後のwindowを閉じてもapplicationをactiveのまま維持するのが通常動作です。CLIの`--close` / `-q`とapp内のClose Allでは一致する各fpasoterm processを明示終了するため、`fpasoterm -q all`後はmacOSのメニューバーにもfpasotermを残しません。
+
+起動中の titlebar は terminal 内の command からも変更できます。標準の OSC title sequence は window title を変更し、fpasoterm 独自の OSC 777 は titlebar 表示を変更します。
+
+## Terminal Graphics
+
+Kitty Graphics Protocol、SIXEL、iTerm inline imageは、現在のbuildでは未対応です。xterm.js image addonはChromeOSの現行Tauri/WebKitGTKでWebViewを無反応にすることがあるため、`config.toml`に`[terminal.images]`があっても意図的にloadしません。
+
+graphicsの検証目的でも、fpasoterm内で`kitten icat`、`chafa --format kitty`、`chafa --format sixels`を実行しないでください。fpasotermは`TERM=xterm-256color`を維持し、Kitty graphics capability queryへ応答しないため、`kitten icat`はgraphics非対応のerrorを表示します。これは想定どおりであり、以前再現したrenderer freezeを避けるためです。
+
+## Broadcast Input
+
+hamburger menu の `Broadcast (^B)`、または `Ctrl+Shift+B` を押します。title と PID ごとに一つ以上の local window を選択し、command を入力して `Shift+Enter` または `Send` を実行します。複数行 command の改行は通常の `Enter` で入力します。fpasotermは末尾の改行を除去して改行コードを正規化し、選択したlocal fpasoterm windowだけへtextを配信します。command送信時は常に本文の後にtarget terminalの実際のEnter key eventを送り、target TUIが有効なkeyboard protocolに従ってencodeできます。通常のshellでは従来と同じCR byteになります。pickerが挿入する`Ctrl+C`などcontrol byteだけの入力は、追加のEnterを送らずに配信します。
+
+全 local window を選択し、sync が有効な場合、dialog に `Include synced channel` が表示されます。これを選ぶと、同じ sync path と channel を使う、すでに起動している全ての fpasoterm instance にも同じ短寿命 command を送ります。remote window の identity は共有していないため、local の一部だけを選択している場合は sync delivery を無効にします。command file は `sync.commandTtlSeconds`（既定 60 秒）で期限切れとなり、instance は自分の起動前に作成された command を実行しません。
+
+この機能は remote server、OAuth token、後から起動した instance での command 自動実行を使用しません。この機能を使う場合、shared sync folder は command channel になります。参加する全 machine で信頼できる folder と channel だけを使用してください。
+
+Broadcast dialogを開いている間は、`Tab` と `Shift+Tab` がterminalへ移動せず、dialog内のcontrolを循環します。focusしたcontrolはscrollして表示され、黄色の枠と`Keyboard focus:`行で現在位置を確認できます。terminalが意図せずfocusを取り戻した場合も`Shift+Enter`は送信として処理します。送信時は常に本文の後にtarget terminalの実際のEnter key eventを送り、dialog shortcutとは別にenhanced keyboard protocolを維持します。IME変換中のkeyはdialog操作として扱わずbrowserへ渡します。dialogの **Control byte** pickerでは、textareaのcursor位置へ表示可能な
+表記を挿入します。明示的な`Enter / CR`は`\x0D`、`Tab`は`\x09`、`Ctrl+C`は`\x03`、`Ctrl+D`は`\x04`、`Ctrl+X`は`\x18`、`Ctrl+Z`は
+`\x1A`です。fpasotermはpickerが挿入したこれらの表記だけを、送信時にterminal byteへ変換します。末尾に明示した`\x0D`へは追加のsemantic Enterを送信しません。単独の`Esc`は
+**Alt prefix / Esc**と同じ`\x1B`になるため、選択肢から除外しています。`Ctrl`と`Alt`はbyteではなくmodifierです。
+慣例上の`Alt+x`を送る場合は **Alt prefix / Esc** を挿入してから`x`を入力します。Escapeはclose、Tabはfocus移動に
+予約されているため、pickerを使うことでkey eventへの依存を避けます。
+
+Broadcastで危険性の高いpatternに一致するcommandを送る前には、追加確認を表示します。現在の対象は`rm`、
+`find -delete`、`git reset --hard`、force付き`git clean`、filesystem format、`dd of=`、`truncate`、
+`shred`、shutdown commandです。確認画面には一致したpattern、選択target、sync delivery、command textを
+表示します。これは利便性のための警告でありshell parserやsecurity boundaryではありません。**Send Anyway** を
+選ぶ前に、すべてのBroadcast commandを確認してください。
+
+BroadcastとDiagnostics panelは同じ右下位置に表示します。panelの見出しをdragするとwindow内で移動できます。
+この位置は一時的で、保存されずterminal windowの位置やsizeも変更しません。
+
+次の `printf` 例は POSIX shell (`bash`、`dash`、`fish` など) 向けです。Windows の PowerShell や cmd.exe ではそのまま使えません。
+
+```sh
+printf '\033]0;work\a\r\n'
+printf '\033]777;titlebarColor=#2e7d32\a\r\n'
+printf '\033]777;opacity=0.65\a\r\n'
+printf '\033]777;title=work;titlebarColor=#2e7d32\a\r\n'
+printf '\033]777;log=start\a\r\n'
+printf '\033]777;log=stop\a\r\n'
+```
+
+PowerShell で直接送る場合:
+
+```powershell
+[Console]::Write("$([char]27)]777;title=work;titlebarColor=#2e7d32$([char]7)`r`n")
+```
+
+runtime config sample は次で適用できます。
+
+```sh
+./examples/apply-runtime-appearance.sh
+```
+
+Windows PowerShell または cmd.exe では次を使えます。
+
+```powershell
+.\examples\apply-runtime-appearance.ps1
+.\examples\apply-runtime-appearance.bat
+```
+
+この sample は title を `RUNTIME SAMPLE ACTIVE` にし、titlebar をピンク、terminal 背景と文字色を分かりやすく変更します。
+
+起動中の window を標準の見た目へ戻す場合:
+
+```sh
+./examples/apply-default-appearance.sh
+```
+
+Windows PowerShell または cmd.exe では次を使えます。
+
+```powershell
+.\examples\apply-default-appearance.ps1
+.\examples\apply-default-appearance.bat
+```
+
+path を手動指定する場合:
+
+```sh
+config_path="$(pwd)/examples/config/runtime-appearance.toml"
+printf '\033]777;config=%s\a\r\n' "$config_path"
+```
+
+Windows PowerShell で path を手動指定する場合:
+
+```powershell
+$configPath = Resolve-Path .\examples\config\runtime-appearance.toml
+[Console]::Write("$([char]27)]777;config=$configPath$([char]7)`r`n")
+```
+
+runtime config 適用では、現在の shell session は維持されます。`window.title`、`window.titlebarColor`、`window.width`、`window.height`、`terminal.fontSize`、`terminal.lineHeight`、`terminal.minimumContrastRatio`、`terminal.fontFamily`、`terminal.backgroundOpacity`、`terminal.theme` など、起動中に反映可能な表示設定を適用します。`terminal.shell` のように新しい PTY が必要な設定は次回起動時に反映されます。
+
+TOML では同じ table を複数回定義できません。`frame = true` などを試す場合は、既存の `[window]` section 内の値を編集してください。ファイル末尾へ新しく `[window]` を追加すると config parse error になります。
+
+## Plugins
+
+Plugin は以下に配置します。
+
+```text
+~/.config/fpasoterm/User/plugins/
+```
+
+`config.toml` で有効化します。
+
+```toml
+[plugins]
+enabled = ["plugins/example.ts"]
+```
+
+TypeScript plugin は以下へ変換されます。
+
+```text
+~/.config/fpasoterm/User/cache/plugins/
+```
+
+設定サンプルは `examples/config/`、plugin sample は `examples/plugins/` を参照してください。

package/docs/debugging.en.md

@@ -0,0 +1,72 @@
+# Debugging Guide
+
+Use this guide when a platform-specific problem needs an event trace, such as
+IME composition, clipboard handling, terminal rendering, or a window lifecycle
+problem.
+
+## Start From Current Source
+
+Close every existing fpasoterm window, then force a local debug-binary rebuild.
+This avoids testing an older packaged or cached binary.
+
+```sh
+mise exec node -- ./bin/fpasoterm --dev --foreground --debug-keys --console-diagnostics \
+  2>&1 | tee ~/temp/fpasoterm-debug.log
+```
+
+`--dev` rebuilds the local debug binary from the current source. `--foreground`
+keeps the launcher attached to the console. `--debug-keys` enables renderer key
+and composition diagnostics, and `--console-diagnostics` mirrors them to stderr.
+
+For a normal attached launch without forcing a rebuild:
+
+```sh
+fpasoterm --foreground --debug-keys --console-diagnostics
+```
+
+The persistent debug log is
+`~/.config/fpasoterm/User/logs/fpasoterm-debug.log` unless the platform uses a
+different configured user directory.
+
+## IME Composition Trace
+
+Reproduce the issue with at least two conversions. For example, convert and
+confirm `日本語は`, then convert and confirm another phrase or enter punctuation.
+After closing the app, extract only the IME and PTY-input lines:
+
+```sh
+grep -E 'renderer ime (compositionstart|compositionupdate|compositionend|beforeinput|input|keydown|cleared)|renderer terminal input' \
+  ~/temp/fpasoterm-debug.log
+```
+
+Expected behavior is that each `renderer terminal input` payload contains the
+newly committed text only. When investigating ChromeOS, compare the helper
+textarea `value=` at `compositionstart` with the following
+`compositionupdate`: a stale prior value must not be inherited by the new
+composition.
+
+Share the smallest contiguous trace that includes one successful conversion
+and one failing conversion. Do not edit or normalize the event payloads: their
+ordering is the evidence needed to diagnose the platform webview and xterm.js
+interaction.
+
+## Rendering And Window Diagnostics
+
+Use this command for WebKitGTK rendering symptoms on ChromeOS/Baguette:
+
+```sh
+fpasoterm --disable-dmabuf --foreground --console-diagnostics
+```
+
+Use the titlebar menu's **Diagnostics > Font / Glyph Test** and
+**Diagnostics > Capability Test** before reporting glyph, terminfo, truecolor,
+OSC, bracketed-paste, or bell issues. See [Configuration and Diagnostics](diagnostics.en.md),
+[Font and Glyph Diagnostics](font-diagnostics.en.md), and
+[Terminal Capability Diagnostics](capability-diagnostics.en.md).
+
+## Reporting Safely
+
+Include the result of `fpasoterm --diagnostics` when useful, but review it
+first. It can contain local paths, plugin names, shell output, and sync-folder
+details. Never publish credentials, tokens, private commands, or terminal
+output containing secrets.