fpasoterm 1.6.0

package/docs/pr-review.ja.md

@@ -0,0 +1,170 @@
+# Pull Request Review
+
+通常の pull request には、release artifact を標準では添付しません。Release
+artifact は version tag から `Release` workflow で生成し、GitHub Release に
+upload します。
+
+reviewer から「download できる PR artifact が無い場合、何を確認すればよいか」
+と聞かれた場合は、この document を参照します。
+
+## Source Checkout で確認する場合
+
+reviewer が対象 OS 上で build できる場合は、この方法を使います。
+
+```sh
+gh pr checkout <number> --repo oyoguhito/fpasoterm
+npm install
+npm run check
+```
+
+GitHub CLI が無い場合:
+
+```sh
+git fetch origin pull/<number>/head:review-pr-<number>
+git switch review-pr-<number>
+npm install
+npm run check
+```
+
+`git fetch` は remote reference を取得するだけで、現在の working tree は変更しません。
+build前には必ず `git switch` または `git checkout` を実行してください。
+
+Node.js 22+、Rust stable、対象OSのnative build toolが必要です。macOSではXcode
+Command Line Tools、WindowsではVisual Studio Build Toolsの**Desktop development with
+C++**とMicrosoft Edge WebView2 Runtimeを導入してください。local checkoutが無い場合は
+`git clone https://github.com/oyoguhito/fpasoterm.git`後に`cd fpasoterm`を実行します。
+
+## Windows MSI の確認
+
+repository rootでPowerShellから実行します。PRのhead branch名を推測せず、PR numberから
+取得するrefを使います。
+
+```powershell
+git fetch origin pull/<number>/head:review-pr-<number>
+git switch review-pr-<number>
+git status --short
+git log -1 --oneline
+npm ci
+npm run check
+npm run build:bundles
+```
+
+`git status --short` が空であることと、最後の `git log` の出力により、package化する
+revisionを確認できます。`git fetch` だけではcurrent branchは変わらないため、build
+手順としては不十分です。
+
+まずは古いStart menu、pinned shortcut、Path上のexecutableを起動しない、生成済みの
+direct binaryを確認します。CLI出力はPowerShellがGUI-subsystem executableの終了を待つよう、
+生成された`.cmd` wrapperを使用します。
+
+```powershell
+.\src-tauri\target\release\fpasoterm.cmd --version
+.\src-tauri\target\release\fpasoterm.exe
+```
+
+CLI startupを変更するPRでは、実際のNode launcherも確認します。status lineを表示し、
+windowを待たずPowerShell promptが戻ることを確認してください。
+
+```powershell
+node .\bin\fpasoterm
+Get-Content "$env:LOCALAPPDATA\fpasoterm\launcher.log" -Tail 40
+```
+
+local buildが必要な場合だけlogに`cargo-build-start` / `cargo-build-complete`が出て、
+その後に`desktop-spawned`とelapsed timeが記録されます。
+
+application内の `Help` を開き、`Config:` が編集対象のfileを指すことと、PRのUI変更が
+表示されることを確認してください。
+
+未releaseのPRでは、既にinstall済みのbuildと同じversionであることがあります。MSIを
+installする前に全fpasoterm processを閉じ、Windows Installerへsame-version packageの
+再installを明示します。
+
+```powershell
+Get-Process fpasoterm -ErrorAction SilentlyContinue | Stop-Process -Force
+$msi = Get-ChildItem .\artifacts\*.msi | Sort-Object LastWriteTime -Descending | Select-Object -First 1
+& msiexec.exe /i $msi.FullName REINSTALL=ALL REINSTALLMODE=vomus
+if ($LASTEXITCODE -notin 0, 3010) { throw "MSI install failed: $LASTEXITCODE" }
+```
+
+終了code `3010` はWindows再起動が必要であることを表します。この後、更新されたStart
+menu shortcutからinstalled appを起動します。機能確認だけであれば、上記direct binary
+の起動が、PR branchを実行していることを最も確実に確認できます。
+
+## Windows Direct Binary の確認
+
+direct `fpasoterm.exe` の挙動に関係する変更では、PR branch から Windows binary
+を build して確認します。
+
+debug build:
+
+```powershell
+cargo build --manifest-path src-tauri/Cargo.toml
+.\src-tauri\target\debug\fpasoterm.exe --help
+.\src-tauri\target\debug\fpasoterm.exe --size 1200x800 --title "PR test" --titlebar-color "#2e7d32"
+```
+
+release build に近い local build:
+
+```powershell
+npm run build
+.\src-tauri\target\release\fpasoterm.exe --help
+```
+
+期待する挙動:
+
+- `--help` は GUI window を開く前に終了し、usage text を表示する。
+- `--size` は起動時の window size を変更する。
+- `--title` は custom titlebar の文字を変更する。
+- `--titlebar-color` は custom titlebar の色を変更する。
+
+## macOS App Bundle の確認
+
+repository rootのTerminalで実行します。reviewする実機でnative buildします。Apple Silicon
+ではarm64、Intel Macではx64が生成されます。
+
+```sh
+git fetch origin pull/<number>/head:review-pr-<number>
+git switch review-pr-<number>
+git status --short
+git log -1 --oneline
+npm ci
+npm run check
+npm run build:bundles
+./src-tauri/target/release/fpasoterm --version
+node ./bin/fpasoterm
+tail -40 ~/.cache/fpasoterm/launcher.log
+```
+
+CLI launcherの挙動確認には`node ./bin/fpasoterm`を使います。cached runtimeまたはCargo
+buildのstatusを表示し、windowが開く前にTerminal promptが戻ることを確認してください。
+compilerまたはapplication outputを待つ必要がある場合だけ、`--foreground --console-diagnostics`
+を追加します。
+
+iconやFinder/App bundleの確認は、local buildしたapp bundleを別に開きます。
+
+```sh
+open -n ./src-tauri/target/release/bundle/macos/fpasoterm.app
+```
+
+unsigned local buildをmacOSがblockした場合はFinderの**開く**を実行し、Privacy & Security
+で許可します。PR branchの代わりに古いtagのDMGを使わないでください。
+
+## Artifact が無い場合
+
+PR に download できる artifact が無い場合、review 対象は PR branch そのものです。
+reviewer は PR branch を checkout し、依存関係を install し、local check を実行し、
+対象 OS 上で debug build または release build を作成して確認します。
+
+tag release asset は PR artifact の代わりには使いません。tag release asset は
+version tag から build されたものであり、pull request branch から build された
+ものではないためです。
+
+## PR Artifact が必要な場合
+
+reviewer が pull request ごとに `.exe`、`.msi`、`.deb`、`.rpm`、`.dmg`、
+app archive を download して確認する必要がある場合は、別途 `pull_request`
+用の artifact workflow を追加します。この workflow は PR branch から build して
+GitHub Actions artifact として upload しますが、GitHub Release には publish しません。
+
+正式な version release には、tag based の `Release` workflow を使い続けます。

package/docs/release-checklist.en.md

@@ -0,0 +1,72 @@
+# Release Checklist
+
+## Local Checks
+
+```sh
+npm ci
+npm run check
+npm run security
+cargo fmt --check --manifest-path src-tauri/Cargo.toml
+desktop-file-validate extra/linux/io.github.oyoguhito.fpasoterm.desktop
+npm run audit:prod
+npm pack --dry-run
+npm run build:artifacts
+```
+
+## GitHub Release
+
+Create and push a version tag after the release PR is merged:
+
+```sh
+git tag v1.3.0
+git push origin v1.3.0
+```
+
+The `Release` workflow validates that the tag version matches `package.json`, builds `artifacts/`, and attaches the generated files to the GitHub Release.
+
+Before creating the tag, confirm the PR template's verification checklist is
+complete and that the required `Check` and `Security` workflows are green. The
+workflows run `npm run check`, production dependency audit, secret scanning,
+and the release workflow builds source plus Linux, macOS, and Windows artifacts.
+
+To rebuild assets for an existing tag, run the `Release` workflow manually and pass the tag name. The workflow uploads release assets with clobber enabled.
+
+Release assets are built on GitHub-hosted runners for:
+
+- source package and portable source archive
+- Linux x64 packages
+- Linux arm64 packages for ChromeOS/Baguette and other arm64 Linux systems
+- macOS x64 bundle
+- macOS arm64 bundle
+- Windows x64 bundle
+
+## ChromeOS Linux Manual Checks
+
+```sh
+./scripts/run
+fpasoterm
+FPASOTERM_DEBUG_KEYS=1 ./scripts/run
+```
+
+Verify:
+
+- The app starts without Wayland/GPU errors.
+- The terminal shell appears and accepts normal ASCII input.
+- Japanese input works with the configured ChromeOS Linux input method.
+- `かな` / `英数` keys are not intercepted by fpasoterm.
+- If debugging, `diagnostics/fpasoterm-debug.log` is written.
+- `npm install -g fpasoterm` exposes the `fpasoterm` command after the package is published.
+- Artifacts include `fpasoterm-<version>.tgz` and `fpasoterm-<version>-source-portable.tar.gz`.
+- GitHub Release assets include Linux x64, Linux arm64, macOS x64, macOS arm64, and Windows x64 bundles.
+- GitHub Actions `Check` and `Security` workflows pass.
+- Secret scanning reports no potential credentials.
+- Production dependency audit reports no known vulnerabilities.
+
+## Documentation Checks
+
+- README has basic English usage.
+- `docs/spec.en.md` explains architecture and input policy.
+- `docs/spec.ja.md` explains the same policy in Japanese.
+- Release notes should mention the tested ChromeOS Linux condition.
+- The icon asset exists at `extra/logo/fpasoterm.png`.
+- `LICENSE` exists and package metadata says `MIT`.

package/docs/release-checklist.ja.md

@@ -0,0 +1,71 @@
+# リリースチェックリスト
+
+## ローカル確認
+
+```sh
+npm ci
+npm run check
+npm run security
+cargo fmt --check --manifest-path src-tauri/Cargo.toml
+desktop-file-validate extra/linux/io.github.oyoguhito.fpasoterm.desktop
+npm run audit:prod
+npm pack --dry-run
+npm run build:artifacts
+```
+
+## GitHub Release
+
+release PR を merge した後、version tag を作成して push します。
+
+```sh
+git tag v1.3.0
+git push origin v1.3.0
+```
+
+`Release` workflow は tag version と `package.json` の version が一致することを確認し、`artifacts/` を生成して GitHub Release に添付します。
+
+tagを作る前に、PR templateのverification checklistと必須の`Check`、`Security` workflowが
+greenであることを確認します。workflowは`npm run check`、production dependency audit、
+secret scanを実行し、Release workflowはsource、Linux、macOS、Windowsのartifactを生成します。
+
+既存 tag の成果物を再生成する場合は、`Release` workflow を手動実行して tag 名を指定します。Release asset は上書き upload されます。
+
+Release asset は GitHub-hosted runner で次の対象を生成します。
+
+- source package と portable source archive
+- Linux x64 package
+- ChromeOS/Baguette を含む arm64 Linux 向け package
+- macOS x64 bundle
+- macOS arm64 bundle
+- Windows x64 bundle
+
+## ChromeOS Linux 手動確認
+
+```sh
+./scripts/run
+fpasoterm
+FPASOTERM_DEBUG_KEYS=1 ./scripts/run
+```
+
+確認項目:
+
+- Wayland/GPU エラーで起動に失敗しない。
+- Terminal shell が表示され、通常の ASCII 入力を受け付ける。
+- 設定済みの ChromeOS Linux 入力メソッドで日本語入力できる。
+- `かな` / `英数` キーを fpasoterm が横取りしない。
+- debug 時に `diagnostics/fpasoterm-debug.log` が書き出される。
+- package 公開後、`npm install -g fpasoterm` で `fpasoterm` コマンドが使える。
+- artifact に `fpasoterm-<version>.tgz` と `fpasoterm-<version>-source-portable.tar.gz` が含まれる。
+- GitHub Release asset に Linux x64、Linux arm64、macOS x64、macOS arm64、Windows x64 の bundle が含まれる。
+- GitHub Actions の `Check` と `Security` workflow が通る。
+- secret scan で credential 候補が検出されない。
+- production dependency audit で既知の脆弱性が検出されない。
+
+## ドキュメント確認
+
+- README に基本的な英語の利用手順がある。
+- `docs/spec.en.md` に構成と入力方針が英語で書かれている。
+- `docs/spec.ja.md` に同じ方針が日本語で書かれている。
+- リリースノートには検証済みの ChromeOS Linux 条件を明記する。
+- icon asset が `extra/logo/fpasoterm.png` に存在する。
+- `LICENSE` が存在し、package metadata が `MIT` になっている。

package/docs/security.en.md

@@ -0,0 +1,36 @@
+# Security
+
+fpasoterm starts a user-selected shell and has the same authority as that user account. Treat terminal input, plugins, and synced command delivery as security-sensitive.
+
+## Trust Boundaries
+
+### Local plugins
+
+Files enabled from `~/.config/fpasoterm/User/plugins/` run as JavaScript in the terminal renderer. They can read the exposed plugin API and act as the current user. Enable only reviewed local files. Do not enable a plugin merely because it has a familiar file name or came from an unreviewed repository.
+
+### Sync-folder Broadcast
+
+Remote Broadcast is disabled by default. `fpasoterm --setup-sync` generates a 32-character-or-longer `sync.commandSecret`. Configure the same secret only on devices and user accounts that you trust. fpasoterm signs synced command files with HMAC-SHA-256 and ignores unsigned or invalidly signed files.
+
+The secret is stored in each device's local `config.toml`; it is not placed in the shared folder. Do not commit it, put it in screenshots, paste it into an issue, or share the configuration file publicly. Rotate it by running `--setup-sync` again and updating every trusted device before using synced Broadcast again.
+
+HMAC confirms that a command was created by a device holding the secret. It does not make a shared folder private, encrypt diagnostics or logs, or protect a device already compromised by malware. Keep the sync folder private and limit who can write to it.
+
+### Broadcast confirmation
+
+The Broadcast dialog asks for confirmation for a small set of destructive patterns such as `rm` and `git reset --hard`. This is an accidental-operation guard, not command authorization. CLI Broadcast, plugins, shell aliases, and commands that do not match the heuristic remain capable of executing commands. Review the command and targets before sending it.
+
+### Terminal control sequences
+
+Terminal output is not an authorization channel. OSC 8 URLs require an explicit
+confirmation dialog and never open automatically. External opening is off by
+default (`security.osc8Open = false`). OSC 9/99 desktop notifications are also
+off by default (`security.oscNotifications = false`) and are rate-limited when
+enabled. OSC 52 clipboard writes remain configurable through `security.osc52`;
+disable them for untrusted terminal output.
+
+## Reporting and Maintenance
+
+Do not publish secrets, private log contents, sync paths, or command secrets in public issues. Use GitHub private vulnerability reporting when available, or contact the repository owner privately for a security issue.
+
+CI runs a repository secret scan, `npm audit --omit=dev`, CodeQL for JavaScript and Rust, and `cargo audit` for Rust dependencies. These checks reduce known risk; they do not replace keeping fpasoterm, its plugins, and the operating system updated.

package/docs/security.ja.md

@@ -0,0 +1,31 @@
+# セキュリティ
+
+fpasoterm はuserが選択したshellを起動するため、そのuser accountと同じ権限を持ちます。terminal input、plugin、sync command deliveryはsecurity-sensitiveな機能として扱ってください。
+
+## 信頼境界
+
+### Local plugin
+
+`~/.config/fpasoterm/User/plugins/`で有効化したfileはterminal renderer内でJavaScriptとして実行されます。plugin APIを参照し、現在のuserとして操作できます。内容をreviewしたlocal fileだけを有効化してください。見覚えのあるfile名や未reviewのrepositoryだけを理由に有効化してはいけません。
+
+### Sync folder Broadcast
+
+remote Broadcastは既定で無効です。`fpasoterm --setup-sync`は32文字以上の`sync.commandSecret`を生成します。同じsecretは信頼できるdeviceとuser accountだけに設定してください。fpasotermはsync command fileへHMAC-SHA-256署名を付け、署名がない、または一致しないfileを無視します。
+
+secretはdeviceごとのlocal `config.toml`に保存され、shared folderには保存しません。Git commit、screenshot、Issue、公開設定fileへ含めないでください。secretをrotateする場合は`--setup-sync`を再実行し、trusted deviceのすべてを更新してからsync Broadcastを再開してください。
+
+HMACはsecretを持つdeviceがcommandを作成したことを確認します。shared folderの非公開化、diagnostics/logの暗号化、malwareに侵害されたdeviceの保護は行いません。sync folderはprivateにし、writeできるuserを制限してください。
+
+### Broadcast確認
+
+Broadcast dialogは`rm`や`git reset --hard`など一部の破壊的patternで確認を求めます。これは誤操作防止であり、command authorizationではありません。CLI Broadcast、plugin、shell alias、heuristicに一致しないcommandは引き続き実行できます。送信前にcommandとtargetを確認してください。
+
+### Terminal control sequence
+
+terminal outputはauthorization channelではありません。OSC 8 URLは明示的な確認dialogを必ず表示し、自動openしません。外部browserでのopenは既定で無効です（`security.osc8Open = false`）。OSC 9/99 desktop notificationも既定で無効です（`security.oscNotifications = false`）。有効化した場合もrate limitします。OSC 52 clipboard writeは`security.osc52`で設定できるため、trustedではないterminal outputでは無効にしてください。
+
+## 報告と保守
+
+secret、private log内容、sync path、command secretをpublic Issueへ掲載しないでください。GitHubのprivate vulnerability reportingが利用できる場合はそれを使い、利用できない場合はrepository ownerへprivateに連絡してください。
+
+CIではrepository secret scan、`npm audit --omit=dev`、JavaScript/RustのCodeQL、Rust dependency向けの`cargo audit`を実行します。これらは既知riskを減らすものであり、fpasoterm、plugin、OSを最新に保つ代わりにはなりません。

package/docs/spec.en.md

@@ -0,0 +1,106 @@
+# fpasoterm Specification
+
+## Purpose
+
+fpasoterm is a desktop terminal application focused on Japanese input in ChromeOS Linux while keeping the architecture portable to other operating systems. It is intended to be used alongside terminal multiplexers such as screen / tmux / byobu / herdr rather than implementing split panes. Multiple application windows can be tiled from the titlebar. It deliberately avoids reimplementing features supplied by the shell, multiplexer, or TUI editor, including session/pane management, shell commands, job control, multiplexer configuration, and editor features provided by Vim, Emacs, Fresh, Helix, and similar tools. Compatibility with those tools is a maintenance priority.
+
+## Architecture
+
+- Tauri owns the application window and platform webview input method path.
+- xterm.js renders the terminal UI in the renderer process.
+- portable-pty creates the shell-backed pseudoterminal in the Rust backend.
+- The renderer communicates with the backend through narrow Tauri commands and events.
+- Terminal clipboard integration copies selected terminal text, handles OSC 52 copy requests from multiplexers, and sends paste shortcuts through a backend OS clipboard fallback.
+- Terminal output logging records the PTY stream that fpasoterm receives after removing common terminal control sequences for readability. Automatic log names include the titlebar title and timestamp. Pane-specific logging is delegated to multiplexers such as tmux, screen, byobu, or herdr because fpasoterm does not implement split-pane awareness.
+
+## ChromeOS Linux Input Policy
+
+fpasoterm does not intercept Japanese keyboard keys such as `かな` or `英数`. Input method switching and composition are delegated to the platform webview and the operating system.
+
+For terminal copy, selecting terminal text and pressing `Ctrl+Shift+C` writes that selection to the OS clipboard through the WebView clipboard event/API and the backend clipboard path. The hamburger window menu contains `Log Start (^S)` / `Log Stop (^S)`, `Log Show (^P)`, `Broadcast (^B)`, `Kill (^K)`, `Copy (^C)`, and `Paste (^V)`. On Unix, `Kill (^K)` or `Ctrl+Shift+K` sends `SIGKILL` to the foreground PTY process group. On Windows, it force-terminates descendants of the terminal shell, from the deepest child upward. Both paths preserve the interactive shell and its window, and report that no command is running at a shell prompt; use the close button to exit the shell. Kill is separate from normal `Ctrl+C` terminal input. `Ctrl+Shift+B` broadcasts normalized text plus Enter only to selected local PTYs and can explicitly include the configured trusted sync channel when all local windows are selected. Kitty APC graphics are experimental and disabled by default. `Ctrl+Shift+L` opens that menu with the log action focused, while `Ctrl+Shift+S` and `Ctrl+Shift+P` invoke logging and log display directly. Right-click copies when a terminal selection exists; otherwise it pastes. Terminal paste first reads the WebView clipboard API during the user gesture, then falls back to the backend clipboard when the WebView result is empty or unavailable, and sends the text to the PTY. Tools such as herdr, tmux, and screen can copy through OSC 52 when configured to emit clipboard sequences; fpasoterm writes those OSC 52 payloads to the OS clipboard. `Ctrl+Shift+M` opens the window menu, and its `Help (^H)` item or `Ctrl+Shift+H` displays the complete application shortcut list.
+
+The terminal log panel keeps keyboard focus inside the panel while it is open. `Tab` and `Shift+Tab` cycle through the log selector, search field, action buttons, close button, and log text area. The focused control is shown with a high-contrast outline. The `Search` button selects and scrolls to the next matching string in the displayed log and shows the current match count. `N` and `j` move to the next match, while `P` and `k` move to the previous match. Arrow keys remain reserved for normal text area scrolling.
+
+The npm binary name is `fpasoterm`. On Linux, `--disable-dmabuf` sets `WEBKIT_DISABLE_DMABUF_RENDERER=1` for WebKitGTK rendering diagnostics.
+By default, the launcher detaches from the console. `--foreground` keeps it attached for debugging.
+`fpasoterm --list` / `fpasoterm -l` prints one line per running window with its process/session ID, displayed title, and startup time, then exits without opening a window.
+
+`fpasoterm --close <pid|title|all>` / `fpasoterm -q <pid|title|all>` requests a graceful close without opening another window. A numeric value selects a process ID, another value must exactly match the displayed title, and the reserved case-insensitive target `all` closes every running fpasoterm window. No confirmation dialog is shown. If several windows have the same exact title, all matching windows are closed.
+
+Users can install the published npm package directly:
+
+```sh
+npm install -g fpasoterm
+```
+
+For an unpacked checkout, `npm run install:desktop` installs a local `fpasoterm` command into `XDG_BIN_HOME` or `~/.local/bin`.
+
+`npm run update:desktop` overwrites the same command, launcher entry, and hicolor icon files. `npm run uninstall:desktop` removes those installed files without removing the source checkout or npm dependencies. On Windows, `npm run uninstall:desktop` removes only fpasoterm-specific directories from the current user's `Path`; shared npm directories are not removed.
+
+The project icon is `extra/logo/fpasoterm.png`.
+
+When multiple instances are running, the titlebar window menu exposes
+`Tile (^T)`, and `Ctrl+Shift+T` invokes the same grid arrangement. Windows and
+X11 support native placement. Wayland compositors may reject application-
+controlled positions; the diagnostic log records the requested and actual
+positions in that case.
+
+Running instances refresh their cache markers periodically. Tile layout and
+title suffix allocation ignore markers that are no longer refreshed. Tile uses
+stable grids such as 2x1 for two windows, 2x2 for four, 4x2 for eight, 3x3 for
+nine, and 5x2 for ten. Later same-title windows use the next number after the
+highest live suffix.
+
+On macOS and Windows, the application executable directory is prepended to the
+child shell `PATH`. On macOS, launching `fpasoterm` from inside fpasoterm
+detaches the new GUI process so the current shell prompt is released.
+
+The application window uses that PNG as its runtime icon. Linux desktop entries still refer to `Icon=fpasoterm` so installers can place the image in the target icon theme. Size-specific hicolor PNGs are generated under `extra/linux/icons/hicolor/`.
+
+The package license is MIT and the repository must expose `bin.fpasoterm` from `package.json` for global installation.
+
+When the shell-backed PTY exits, fpasoterm closes the owning application window. This makes `exit` behave like closing a normal terminal window.
+
+## Configuration and Plugins
+
+User configuration is read from `~/.config/fpasoterm/User/config.toml`, or from `$XDG_CONFIG_HOME/fpasoterm/User/config.toml` when `XDG_CONFIG_HOME` is set.
+`fpasoterm --config <path>` uses another TOML file for one launch. `--width`, `--height`, and `--size` override the configured window size for one launch. `--shell <command>` selects another shell for one launch. `--cwd <path>` (`-o`) starts the PTY in an existing local directory and resolves a relative path from the calling shell. `--command <command>` sends a command to the shell after launch. `--reset-window-state` deletes the saved window size. `--reset-config` (`-R`) renames the selected `config.toml` to a timestamped backup, restores all platform defaults, deletes the saved window state so the default 1000x680 size takes effect, and exits.
+`--show-config` prints the resolved settings and plugin load status. `--enable-plugin` and `--disable-plugin` select one or more local plugin selectors and edit `plugins.enabled`; selectors may omit the `plugins/` prefix and `.js` or `.ts` suffix when unambiguous.
+
+On launch, fpasoterm writes or refreshes `config.toml.example` with the default settings. fpasoterm does not overwrite an existing user config. When `window.rememberBounds` is enabled, the last window size is saved locally to `~/.config/fpasoterm/User/window-state.json` and restored on the next launch. Saved size overrides explicit `window.width` and `window.height` values in `config.toml`; one-shot CLI overrides are applied last.
+
+Supported config sections:
+
+- `window`: initial window size, minimum window size, background color, theme source, frame/titlebar visibility, and whether to remember the last size locally.
+- `terminal`: xterm.js terminal options such as `fontFamily`, `fontSize`, `scrollback`, and `theme`.
+- `plugins.enabled`: relative plugin paths under the config directory.
+
+Plugins must be placed under `~/.config/fpasoterm/User/plugins/`. `.js` and `.ts` plugins are supported. TypeScript plugins are transpiled to `~/.config/fpasoterm/User/cache/plugins/` at launch and then loaded into the renderer. New convenience behavior should normally be implemented as a plugin rather than added to the core application.
+
+Renderer plugins access `window.fpasotermPluginApi`, which exposes the terminal, fit addon, resolved config, and a diagnostics logger.
+
+The full default configuration is documented in `docs/config.en.md`. See `examples/config/` for sample configs. The runtime plugin API is documented in `docs/plugins.en.md`; reviewed installable plugins and their ports workflow are maintained in [fpasoterm-plugins](https://github.com/oyoguhito/fpasoterm-plugins).
+
+Known platform limitations are tracked in `docs/known-issues.en.md`.
+
+## Diagnostics
+
+Set `FPASOTERM_DEBUG_KEYS=1` to log key and composition events.
+
+Diagnostics are written to:
+
+```text
+~/.config/fpasoterm/User/logs/fpasoterm-debug.log
+```
+
+The diagnostics and log panel textareas use the same `Ctrl+Shift+C` copy path as the terminal selection.
+
+## Non-goals
+
+- fpasoterm does not manage IBus engines.
+- fpasoterm does not implement split panes; use screen, tmux, byobu, or herdr.
+- fpasoterm does not emulate OS-level Japanese input switching.
+- fpasoterm does not implement terminal shell behavior itself; that is delegated to the user's shell through portable-pty.
+- fpasoterm does not reproduce terminal multiplexer features such as pane/session lifecycle, layout management, command orchestration, or multiplexer-specific configuration.
+- fpasoterm does not reproduce TUI editor features such as buffers, editing commands, language tooling, or editor-specific configuration; it maintains compatibility with Vim, Emacs, Fresh, Helix, and similar tools.
+- fpasoterm does not add general convenience workflows to the core when they can be implemented as a local plugin.

package/docs/spec.ja.md

@@ -0,0 +1,99 @@
+# fpasoterm 仕様
+
+## 目的
+
+fpasoterm は、ChromeOS Linux での日本語入力を重視したデスクトップ Terminal アプリです。将来的に他 OS へ展開しやすい構成を採用します。screen / tmux / byobu / herdr などの terminal multiplexer と併用する前提で、画面分割はアプリ側で行いません。複数 window は titlebar の操作で並べられます。session/pane管理、shell command、job control、multiplexer設定に加え、Vim、Emacs、Fresh、Helix などの TUI editor が提供する編集機能は意図して再実装しません。これらの tool を問題なく利用できる互換性の維持・改善を優先します。
+
+## 構成
+
+- Tauri がアプリケーションウィンドウと platform webview の入力メソッド経路を担当します。
+- xterm.js が renderer process で Terminal UI を描画します。
+- portable-pty が Rust backend で shell 付き PTY を作成します。
+- renderer と backend の通信は Tauri command / event に限定します。
+- terminal clipboard integration は選択した terminal text の copy、multiplexer からの OSC 52 copy request、paste shortcut の backend OS clipboard fallback 経由送信を処理します。
+- terminal output logging は fpasoterm が受け取る PTY stream から一般的な terminal control sequence を除去して記録します。自動生成 log 名には titlebar title と timestamp を含めます。fpasoterm は split-pane を認識しないため、pane 単位の log は tmux、screen、byobu、herdr などの multiplexer 側に委ねます。
+
+## ChromeOS Linux の入力方針
+
+fpasoterm は `かな` / `英数` などの日本語キーボードキーを横取りしません。IME の切替と composition は platform webview と OS に任せます。
+
+terminal copy は、terminal text を選択して `Ctrl+Shift+C` を押すと、その選択範囲を WebView clipboard event/API と backend clipboard 経路の両方で OS clipboard へ書き込みます。hamburger の window menu には `Log Start (^S)` / `Log Stop (^S)`、`Log Show (^P)`、`Broadcast (^B)`、`Kill (^K)`、`Copy (^C)`、`Paste (^V)` を表示します。Unixでは、`Kill (^K)` または `Ctrl+Shift+K` が前景 PTY process group に `SIGKILL` を送ります。Windowsではterminal shellの子孫processを深い順に強制終了します。いずれも実行中commandを終了し、interactive shell とその window は残します。shell promptで実行対象がない場合は、shellを終了しないためerrorを表示します。その場合の終了はclose buttonを使用します。通常の terminal input である `Ctrl+C` とは別の強制終了操作です。`Ctrl+Shift+B` は改行を正規化して Enter を追加した text を選択した local PTY だけに送信し、全local windowを選択した場合だけtrustedなsync channelも明示選択できます。Kitty APC graphics は上限付きの image storage で描画します。`Ctrl+Shift+L` は log 操作に focus した状態でこの menu を開き、`Ctrl+Shift+S` と `Ctrl+Shift+P` は logging と log 表示を直接実行します。右クリックは terminal selection がある場合は copy、selection がない場合は paste として動作します。terminal paste は、user gesture中のWebView clipboard APIを先に読み、空または利用不可の場合だけbackend clipboardを使ってPTYへ送ります。herdr、tmux、screen などが OSC 52 clipboard sequence を出す設定の場合、fpasoterm はその payload を OS clipboard に書き込みます。`Ctrl+Shift+M` で window menu を開き、menu 内の `Help (^H)` または `Ctrl+Shift+H` でアプリの全 shortcut 一覧を表示します。
+
+terminal log panel が開いている間、keyboard focus は panel 内に留まります。`Tab` と `Shift+Tab` で log selector、検索欄、操作 button、close button、log text area を循環できます。focus された control は高 contrast の outline で表示します。`Search` button は表示中の log から次の一致文字列を選択してその位置へ scroll し、現在の一致番号を表示します。`N` と `j` は次の一致、`P` と `k` は前の一致へ移動します。矢印キーは通常の text area scroll 用に残します。
+
+npm binary 名は `fpasoterm` です。Linux では `--disable-dmabuf` により、WebKitGTK の描画診断用に `WEBKIT_DISABLE_DMABUF_RENDERER=1` を設定できます。
+既定では launcher はコンソールから切り離して起動します。debug 時は `--foreground` で接続したままにできます。
+`fpasoterm --list` / `fpasoterm -l` は起動中のwindowごとにprocess/session ID、表示title、起動時刻を1行で出力し、新しいwindowを開かずに終了します。
+
+`fpasoterm --close <pid|title|all>` / `fpasoterm -q <pid|title|all>`は、新しいwindowを開かずに通常終了を要求します。数値はprocess ID、それ以外は表示titleとの完全一致で選択し、大文字小文字を区別しない予約targetの`all`は起動中の全fpasoterm windowを閉じます。確認dialogは表示しません。同じ表示titleのwindowが複数ある場合は、一致した全windowを閉じます。
+
+npm registry から直接インストールできます。
+
+```sh
+npm install -g fpasoterm
+```
+
+展開済み checkout では、`npm run install:desktop` により `XDG_BIN_HOME` または `~/.local/bin` にローカル `fpasoterm` コマンドをインストールします。
+
+`npm run update:desktop` は同じ command、launcher entry、hicolor icon files を上書きします。`npm run uninstall:desktop` は source checkout や npm dependencies を削除せず、インストール済みファイルだけを削除します。Windows では current user の `Path` から fpasoterm 関連 directory だけを削除し、共有 npm directory は削除しません。
+
+プロジェクトアイコンは `extra/logo/fpasoterm.png` です。
+
+複数の fpasoterm を起動している場合、titlebar の window menu にある
+`Tile (^T)`、または `Ctrl+Shift+T` で格子状に配置できます。Windows と
+X11 では native placement を使用します。Wayland compositor が位置変更を
+拒否した場合は、diagnostics に要求位置と実際の位置を記録します。
+
+起動中instanceはcache markerを定期更新します。Tileのwindow件数とtitle suffix採番では、更新が停止したmarkerを除外します。Tileは2 windowを2x1、4 windowを2x2、8 windowを4x2、9 windowを3x3、10 windowを5x2の安定したgridへ配置します。同じbase titleの追加windowは、現在起動中の最大suffixの次の番号を使います。
+
+macOSとWindowsではapplication executable directoryをchild shellの`PATH`先頭へ追加します。macOSのfpasoterm内で`fpasoterm`を実行した場合は、新しいGUI processを切り離して現在のshell promptを解放します。
+
+アプリケーションウィンドウはこの PNG を runtime icon として使います。Linux desktop entry は `Icon=fpasoterm` を参照するため、installer はこの画像を対象環境の icon theme へ配置します。サイズ別 hicolor PNG は `extra/linux/icons/hicolor/` に生成します。
+
+license は MIT です。global install で `fpasoterm` コマンドを作るため、`package.json` の `bin.fpasoterm` を公開します。
+
+shell 付き PTY が終了した場合、fpasoterm は対応するアプリケーションウィンドウを閉じます。これにより shell で `exit` を実行すると通常の Terminal ウィンドウと同じように終了します。
+
+## 設定とプラグイン
+
+ユーザー設定は `~/.config/fpasoterm/User/config.toml` から読み込みます。`XDG_CONFIG_HOME` がある場合は `$XDG_CONFIG_HOME/fpasoterm/User/config.toml` を使います。
+`fpasoterm --config <path>` で一度だけ別の TOML file を使えます。`--width`、`--height`、`--size` は一度だけ window size を上書きします。`--shell <command>` は一度だけ別の shell を使います。`--cwd <path>` (`-o`) は既存のlocal directoryからPTYを開始し、relative pathは呼び出したshellのcurrent directoryから解決します。`--command <command>` は起動後に shell へ command を送ります。`--reset-window-state` は保存済み window size を削除します。`--reset-config` (`-R`) は選択した `config.toml` をtimestamp付きbackup名へrenameし、OSごとの全デフォルト値へ戻し、保存済みwindow stateも削除してデフォルトの1000x680を反映して終了します。
+`--show-config` は解決済み設定と plugin 読み込み状況を表示します。`--enable-plugin` と `--disable-plugin` は一つ以上のlocal plugin selectorを選択し、`plugins.enabled` を編集します。selectorは曖昧でない場合、`plugins/` prefixと`.js`/`.ts` suffixを省略できます。
+
+起動時に fpasoterm は既定値を `config.toml.example` として書き出し、古い場合は更新します。既存のユーザー設定は上書きしません。`window.rememberBounds` が有効な場合、最後の window size は `~/.config/fpasoterm/User/window-state.json` に保存され、次回起動時に復元されます。保存済み size は `config.toml` に明示した `window.width`、`window.height` より優先され、CLI の一時指定は最後に適用されます。
+
+対応する設定 section:
+
+- `window`: 初期ウィンドウサイズ、最小ウィンドウサイズ、背景色、theme source、frame/titlebar 表示、最後の size を local に記憶するかどうか。
+- `terminal`: `fontFamily`、`fontSize`、`scrollback`、`theme` などの xterm.js terminal options。
+- `plugins.enabled`: config directory からの相対 plugin path。
+
+プラグインは `~/.config/fpasoterm/User/plugins/` 配下に置きます。`.js` と `.ts` に対応します。TypeScript plugin は起動時に `~/.config/fpasoterm/User/cache/plugins/` へ変換してから renderer に読み込みます。追加すると便利な挙動は、原則として本体ではなく plugin として実装します。
+
+renderer plugin は `window.fpasotermPluginApi` から terminal、fit addon、解決済み config、diagnostics logger を利用できます。
+
+全デフォルト設定は `docs/config.ja.md` に記載しています。設定sampleは `examples/config/` を参照してください。plugin runtime APIは `docs/plugins.ja.md` に記載し、review済みinstall可能pluginとports workflowは [fpasoterm-plugins](https://github.com/oyoguhito/fpasoterm-plugins) で管理します。
+
+現時点の platform 制約は `docs/known-issues.ja.md` に記録します。
+
+## 診断
+
+`FPASOTERM_DEBUG_KEYS=1` を設定すると、key event と composition event を記録します。
+
+診断ログは以下へ保存されます。
+
+```text
+~/.config/fpasoterm/User/logs/fpasoterm-debug.log
+```
+
+diagnostics / log panel の textarea も terminal selection と同じ `Ctrl+Shift+C` copy 経路を使います。
+
+## 非目標
+
+- fpasoterm は IBus engine を管理しません。
+- fpasoterm は画面分割を実装しません。screen、tmux、byobu、herdr などを使用してください。
+- fpasoterm は OS レベルの日本語入力切替を独自実装しません。
+- fpasoterm は shell の挙動を独自実装しません。shell との接続は portable-pty に任せます。
+- fpasoterm はpane/session lifecycle、layout管理、command orchestration、multiplexer固有設定などのterminal multiplexer機能を再実装しません。
+- fpasoterm はbuffer、編集command、language tooling、editor固有設定などのTUI editor機能を再実装しません。Vim、Emacs、Fresh、Helix などとの互換性を維持します。
+- fpasoterm は local plugin として実装できる一般的な便利機能を、本体へ追加しません。

package/docs/sshfs.en.md

@@ -0,0 +1,28 @@
+# SSHFS Mounts
+
+FpasoTerm can mount a remote directory through the locally installed `sshfs` command. It does not implement an SSH server or copy files itself.
+
+Open **Sync > SSHFS Mounts**, enter host, user, SSH port, absolute remote path, and a mount name. The manager opens as a modal in the active FpasoTerm window on every supported platform. On Linux and macOS, the local path is `User/mounts/<name>` below the active FpasoTerm configuration directory. On Windows, FpasoTerm assigns an available drive letter such as `Z:`. Use the resulting path from the terminal or another local application.
+
+With an empty identity and password field, SSHFS uses normal SSH authentication, including `~/.ssh/config`, available default keys, and ssh-agent. An optional identity-file path is passed only to this SSHFS command. An optional password is supplied through standard input using `-o password_stdin`; it is cleared from the UI after the attempt and is never stored in config, logs, or sync files.
+
+Install prerequisites before use: Linux usually provides `sshfs` through its package manager; macOS requires macFUSE and SSHFS; Windows requires SSHFS-Win and WinFsp. Password mode depends on the installed SSHFS implementation supporting `password_stdin`.
+
+On macOS, FpasoTerm starts SSHFS in foreground mode so macFUSE keeps its mount channel when the application launches SSHFS without a Terminal. If an SSHFS error mentions `FD_CLOEXEC`, update the installed SSHFS package: this is a known macFUSE lazy-mount compatibility issue fixed upstream, not a credential or remote-path error.
+
+On Windows, FpasoTerm uses SSHFS-Win's supported disk network-drive interface and assigns an unused drive letter. It does not invoke the bundled Cygwin `sshfs.exe` directly. SSHFS-Win displays the normal Windows credential dialog, owned by the active FpasoTerm window, using the same flow as Explorer and `net use`; use that dialog or Windows Credential Manager for authentication. The optional identity-file field is not accepted on Windows because SSHFS-Win mapped drives do not support that per-mount option; configure a supported SSHFS-Win key setup instead. The manager's initial status line still reports the exact SSHFS-Win installation path it found. Verify an installation in PowerShell:
+
+For the remote root, enter `/`. FpasoTerm maps this to the SSHFS-Win root UNC form `\\sshfs.r\\user@host!port` without a trailing path separator. For a subdirectory, enter an absolute path such as `/home/user/project`.
+
+```powershell
+Test-Path "$env:ProgramFiles\SSHFS-Win\bin\sshfs.exe"
+& "$env:ProgramFiles\SSHFS-Win\bin\sshfs.exe" --version
+```
+
+For a non-standard installation, set `FPASOTERM_SSHFS_PATH` to the full `sshfs.exe` path and restart FpasoTerm. SSHFS-Win documents its normal `bin` installation directory in its [official README](https://github.com/winfsp/sshfs-win).
+
+FpasoTerm stores non-secret mount descriptions in `User/mounts/sshfs-mounts.json`, so reopening the manager can restore the fields and unmount a mount created earlier. On Windows it also stores the assigned drive letter. Passwords are not written there. Active managed mounts appear as `SSHFS (n)` in the terminal titlebar. Closing a terminal window asks for confirmation before leaving mounts active. Unmount through the same manager using the mount name. On Linux and macOS FpasoTerm only unmounts paths below its own `User/mounts` directory; on Windows it only unmounts the recorded drive letter.
+
+The manager keeps a record when a mount attempt fails or when an external command already removed the filesystem. Such entries are marked `(not mounted)`. Select one and use **Forget Saved** to remove only the inactive record; FpasoTerm refuses this action while the filesystem is still mounted.
+
+SSHFS-Win can occasionally leave a network drive mapped after a normal unmount. FpasoTerm first uses the normal Windows disconnect API and verifies the result. If the drive remains mapped, it shows a Windows confirmation dialog before ending `sshfs.exe` and retrying the disconnect. This forced recovery can disconnect other SSHFS-Win mounts available to the same Windows user; cancel it when another SSHFS-Win mount must remain active. A mount record is kept until the drive is verified as removed.