projmux 0.7.5 → 0.7.6

package/README-ko.md

@@ -70,7 +70,9 @@ projmux shell
 `Alt-1`부터 `Alt-5`까지는 zero-config 보장 기본값이고, `Alt-7`은 추가로
 편집 가능한 built-in 기본값입니다. 전체 key map은
 [Terminal Keybindings](docs/keybindings.md)를 참고하세요. 키가 동작하지 않으면
-tmux 밖에서 `projmux setup`을 실행한 뒤, 지원 터미널에서는
+Darwin 배포본의 `projmux shell`에서는 macOS 접근성 권한을 한 번 승인하면
+물리 키 어댑터가 자동으로 동작합니다. 그 밖의 경로에서는 tmux 밖에서
+`projmux setup`을 실행한 뒤, 지원 터미널에서는
 `projmux init [terminal] --apply`를 사용하세요.
 
 ## 일상 사용

package/README.md

@@ -79,7 +79,9 @@ Inside the app:
 The `Alt-1` through `Alt-5` launch keys are the guaranteed zero-config
 defaults. `Alt-7` is an additional editable built-in default. Add aliases in
 Settings > Keybindings or `~/.config/projmux/keymap.toml`. If a key does not
-fire, run `projmux setup` outside tmux, then use `projmux init [terminal]
+fire, the Darwin release uses a native physical-key adapter automatically
+inside `projmux shell` after one-time macOS Accessibility approval. On other
+paths, run `projmux setup` outside tmux, then use `projmux init [terminal]
 --apply` for supported terminal delivery fallbacks.
 
 ## Day-To-Day Use

package/docs/agent-workflow.md

@@ -39,6 +39,7 @@
 - `make test` also covers AI semantic badge renderer aggregation for window-list, sidebar rows, switch window tabs, popup pane summaries, and pane-border topic badges using prompt-required > response-complete > in-progress priority while preserving blank no-state lanes, response-complete live badge consume on attention clear without idling action-required/progress badges, plus Settings > Appearance AI badge style selection for dot/emoji/off pane-border, Alt-1 sidebar window/preview tabs, and tmux window-status compatibility with dot as the persisted/config fallback.
 - `make test` also covers AI semantic badge Phase 3 theme-role hardening: `@projmux_ai_badge_kind` storage values and aggregate priority stay unchanged, `minimal` remains a read-time alias for the `off` badge style, progress/success/action-required badge roles stay distinct, permission/input status badges do not use critical red, and critical notify queue severity does not drive live AI status badge colors or desktop notification urgency.
 - `make test` also covers keybinding surface tier catalog rules, action-centered `keymap.toml` `keys = [...]` multi-alias parsing/writing, quoted internal `Surface:Action` tables, legacy popup action ID aliases, canonical popup toggle names, AI split popup-vs-direct action labels, generated tmux config multi-alias rendering, global/direct conflict detection, surface-scoped native picker command conflict detection, Settings Keybindings list/search/detail surface-aware picker-local labels, compact action-list state copy, flat Keys list/action detail rows, key detail remove/test rows, Add key default press-key flow with Advanced typed entry, collapsed Troubleshooting entry copy, Settings delivery diagnostics that split logical key/raw bytes/tmux received key while distinguishing missing, ambiguous, adapter-needed, and delivered states, safe direct key pool and risky/reserved diagnostic-only copy, Projmux-owned Ghostty/Windows Terminal advanced delivery copy, raw escape/CSI-u/xterm modified/UserKey/UserSequence rejection from primary keymap storage, Labs compatibility redirect to the Keybindings root, capture/add-key flows, unsafe raw capture, reset behavior, stale guide docs guards, and welcome/runtime footer copy that avoids hardcoded launch-key guides.
+- Darwin native-key focused coverage includes portable physical chord parsing for Alt/Option, Control, Control-Option, Shift, letters/digits/navigation/function keys, shared `keymap.toml` custom-action loading (including `M-a`), focused tmux client discovery, canonical `send-keys -K -c` dispatch through the existing root key table, native Settings Add key capture winning over terminal text encoding, and an explicit Linux/Windows/no-CGO shell startup no-op boundary.
 - `make test` covers the default picker key ownership across catalog, generated tmux config, terminal adapters, setup probes, and native popup close hints: `Alt-4` opens AI Resume as a guaranteed launch default, while `Alt-7` opens the AI split picker as its editable default.
 - `make test` also covers welcome revisit policy: legacy welcome state remains readable without suppressing shell entry, Enter continues without storing release skip, `s` stores an update skip for the current latest tag when an update is available, source installs show disabled Upgrade guidance, stale update cache refresh is best-effort, Settings > About > Welcome opens a Settings-native viewer without pending state, and shell prompt display does not schedule a redundant attach popup.
 - `make test` also covers transport-dependent app tmux defaults for pane/window navigation (`M-Left`/`M-Right`/`M-Up`/`M-Down` and `M-S-Left`/`M-S-Right`) while keeping visible default chords, allowing additive safe plain aliases that do not store or remove the transport defaults, and no UserKey/CSI-u generated fallback.

package/docs/keybindings.md

@@ -13,10 +13,13 @@ supported fallback guidance.
 The recommended path when a key does not fire:
 
 1. Try the key inside `projmux shell`.
-2. Run `projmux setup` outside tmux to see which bytes reach the process.
-3. For supported terminals, preview `projmux init [terminal]`; add `--apply`
+2. On macOS, approve the one-time Accessibility prompt from the native
+   `projmux shell` key adapter, then retry the physical key.
+3. Run `projmux setup` outside tmux to see which bytes reach the process.
+4. For supported terminals outside the native macOS app socket, preview
+   `projmux init [terminal]`; add `--apply`
    only after reviewing the merge.
-4. For unsupported terminals, configure plain Meta bytes or add a custom key in
+5. For unsupported terminals, configure plain Meta bytes or add a custom key in
    Settings > Keybindings.
 
 Settings saves safe tmux plain chords for actions and automatically applies the
@@ -56,6 +59,37 @@ separate from `last-pane` and from the existing-session popup.
 The tmux prefix remains the upstream default `Ctrl-b`. Inside a running
 session, `Ctrl-b ?` lists the live tmux bindings.
 
+### Native macOS delivery
+
+Darwin release binaries start a small native key adapter automatically with
+`projmux shell`. It observes physical keys only while a client on that projmux
+tmux socket reports itself focused. Supported `Alt`/Option and Control chords
+from the same merged action catalog are sent back through tmux's client key
+table. For example, a custom `M-a` remains the ordinary cross-platform
+`keymap.toml` value; on macOS the adapter recognizes physical Option-A and
+injects canonical `M-a`, while Linux and Windows keep their existing terminal
+delivery path.
+
+This adapter is terminal-independent, so Ghostty and iTerm2 do not need
+separate projmux mappings for the app socket. It does not rewrite terminal
+configuration and it does not translate Option-produced symbols such as `¡`.
+The first launch requires macOS Accessibility permission because consuming a
+physical chord before the terminal converts it requires a CGEvent event tap.
+The broker waits for the one-time approval and enables the event tap
+automatically; the tmux session does not need to be restarted.
+
+The portable key vocabulary stays shared across operating systems:
+`M-` (Alt/Option), `C-`, `S-`, letters, top-row digits, arrows/navigation,
+and function keys. Command/Super is intentionally not part of this portable
+tier. Picker-local unmodified commands continue through the picker input path;
+the native adapter owns action-level no-prefix bindings only.
+
+Settings > Keybindings > Add key races the native modified-key capture against
+the existing controlling-TTY capture. On Darwin this lets Press a key store a
+new physical Option, Control, Control-Option, or Shift-modified chord before
+the terminal turns it into text; ordinary keys still use the portable TTY
+path. Other operating systems keep the existing TTY capture unchanged.
+
 ## Discoverable Actions
 
 Settings > Keybindings lists the full action catalogue. In particular, sidebar
@@ -71,12 +105,13 @@ Troubleshooting row with Test key delivery and Advanced... entry points. Key
 rows open key detail for Remove key and Test key. Add key opens Press a key by
 default; Enter key name, the safe direct key pool, risky/reserved key copy, and
 raw diagnostics live under Advanced. Advanced delivery is still owned by the
-selected Projmux action: supported Ghostty and Windows Terminal mappings are
-previewed/applied through `projmux init`, not by storing raw sequences in the
-primary keymap. Options covers unbinding the action and reset/use-default
-flows. Diagnostic/probe/init workflows are not first-class Settings tabs; use
-`projmux setup` and `projmux init` from the terminal when key delivery needs
-remediation.
+selected Projmux action. The native macOS app-socket adapter reads the same
+safe chords directly; supported Ghostty and Windows Terminal mappings for
+other paths are previewed/applied through `projmux init`, not by storing raw
+sequences in the primary keymap. Options covers unbinding the action and
+reset/use-default flows. Diagnostic/probe/init workflows are not first-class
+Settings tabs; use `projmux setup` and, where the native adapter does not
+apply, `projmux init` from the terminal when key delivery needs remediation.
 
 Optional direct keys can be added for actions such as:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projmux",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "description": "tmux project session manager",
   "license": "MIT",
   "homepage": "https://github.com/crevissepartners/projmux#readme",
@@ -28,9 +28,9 @@
     "package:npm:pack": "scripts/package-npm.sh --pack"
   },
   "optionalDependencies": {
-    "@projmux/linux-x64": "0.7.5",
-    "@projmux/linux-arm64": "0.7.5",
-    "@projmux/darwin-x64": "0.7.5",
-    "@projmux/darwin-arm64": "0.7.5"
+    "@projmux/linux-x64": "0.7.6",
+    "@projmux/linux-arm64": "0.7.6",
+    "@projmux/darwin-x64": "0.7.6",
+    "@projmux/darwin-arm64": "0.7.6"
   }
 }