Preserve performable keybindings for clipboard image paste

[onevtail]

What

• Prevent AppKit menu dispatch from intercepting Ghostty performable keybindings.
• Add regression coverage for image-only clipboard contents and menu-routing flag/state boundaries.
• Document clipboard image passthrough behavior.

Why

Ghostty marks the default macOS paste binding as performable. When the clipboard contains only an image, Ghostty cannot perform its text paste action and should pass the original key event through to the terminal program.

Prowl attempted the matching AppKit menu command first. The menu consumed the shortcut even though the clipboard action could not produce text, preventing terminal-based agents from handling the image themselves.

How tested

• GhosttySurfaceViewTests: 30 tests passed
• make check
• make build-app

Fixes #679

onevtail - an assistant to @onevcat

[Copilot]

Pull request overview

This pull request adjusts Prowl’s Ghostty key-equivalent routing so AppKit menu dispatch no longer intercepts Ghostty bindings marked as PERFORMABLE, preserving the ability for terminal programs (including agent CLIs) to receive paste key events when Ghostty can’t complete a text paste (e.g., image-only clipboard).

Changes:

• Update GhosttySurfaceView.shouldAttemptMenu(for:) to skip AppKit menu attempts for PERFORMABLE bindings.
• Add regression tests covering menu-routing boundaries and image-only clipboard string extraction behavior.
• Document the clipboard image passthrough behavior in the terminal component docs.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
supacodeTests/GhosttySurfaceViewTests.swift	Adds regression tests for shouldAttemptMenu(for:) behavior and image-only clipboard string handling.
supacode/Infrastructure/Ghostty/GhosttySurfaceView+Keyboard.swift	Updates menu-routing decision logic to avoid intercepting Ghostty PERFORMABLE bindings.
docs/components/terminal.md	Documents how image-only clipboard contents are left to the terminal program for supported agents.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[onevclaw]

Our exact-head validation is still incomplete because the clean build had not finished when the investigation ended. The visible CI has passed, but we do not yet have enough evidence from this review to approve or request changes.

onevclaw - an assistant to @onevcat

[onevpaw]

Cross-review complete: I found no P0-P2 issue in this head, and the required checks passed.
This is a technical approval only; final merge remains with @onevcat.

onevpaw - an assistant to @onevcat

[onevcat]

Closing this PR after manual validation.

For an image-only macOS clipboard, bypassing AppKit does reach Ghostty, but Ghostty declines its text paste and the original ⌘V reaches Codex as a literal v; no image is attached. The detailed investigation and upstream references are recorded on #679.