484b66c8ac
* Fix terminal keys (arrows, Ctrl+N/P) swallowed after opening browser After a browser panel is shown, SwiftUI's internal focus system activates and its _NSHostingView starts consuming arrow keys and other non-Command key events via performKeyEquivalent, preventing them from reaching the terminal's keyDown handler. Fix: In the NSWindow performKeyEquivalent swizzle, when GhosttyNSView is the first responder and the event has no Command modifier, route directly to the terminal's performKeyEquivalent — bypassing SwiftUI's view hierarchy walk entirely. Also clear stale browserAddressBarFocusedPanelId when a terminal surface has focus, preventing Cmd+N from being eaten by omnibar selection logic after focus transitions away from a browser. Adds DEBUG-only keyboard event ring buffer (KeyDebugLog) that dumps to /tmp/cmux-key-debug.log for diagnosing future key routing issues. * Fix split focus and Cmd+Shift+N swallowed after opening browser Split focus: capture the source terminal's hostedView before bonsplit mutates focusedPaneId, so focusPanel moves focus FROM the old pane instead of from the new pane to itself. Also retry ensureFocus when the new terminal's view has no window yet (matching the existing retry pattern for isVisibleInUI). Cmd+Shift+N: after WKWebView has been in the responder chain, SwiftUI's internal focus system can intercept Command-key events in the content view hierarchy (returning true) without firing the CommandGroup action closure. Fix by dispatching Command-key events directly to NSApp.mainMenu when the terminal is first responder, bypassing the broken SwiftUI path. Also add Cmd+Shift+N to handleCustomShortcut so it's customizable and doesn't depend on SwiftUI menu dispatch at all. * Unified debug event log: merge key/mouse/focus into /tmp/cmux-debug.log - Delete KeyDebugLog, MouseDebugLog, klog(), mlog() from AppDelegate - Replace all klog/mlog calls with dlog() (provided by bonsplit) - Remove debugLogCallback wiring from Workspace - Add focus change logging: focus.panel, focus.firstResponder, split.created, focus.moveFocus - Add import Bonsplit where needed for dlog access - Fix stale drag state on cancelled tab drags (bonsplit submodule) * Fix split focus stolen by re-entrant becomeFirstResponder during reparenting During programmatic splits (Cmd+D / Cmd+Shift+D), SwiftUI reparents the old terminal view, which fires becomeFirstResponder → onFocus → focusPanel for the OLD panel, stealing focus from the newly created pane. Add programmaticFocusTargetPanelId guard to suppress re-entrant focusPanel calls for non-target panels during split creation. Also document the unified debug event log in CLAUDE.md. * Clear stale title/favicon when browser navigation fails When a page fails to load (e.g. connection refused), the tab was still showing the previous page's title and favicon. Now didFailProvisionalNavigation resets pageTitle to the failed URL and clears faviconPNGData. * Fix Cmd+N swallowed by browser omnibar and improve split focus suppression - Only Ctrl+N/P trigger omnibar navigation, not Cmd+N/P (Cmd+N should always create new workspace regardless of address bar focus) - Move split focus suppression from workspace-level guard to source: suppress becomeFirstResponder side-effects (onFocus + ghostty_surface_set_focus) directly on the old GhosttyNSView during reparenting, preventing both model-level and libghostty-level focus divergence - Remove programmaticFocusTargetPanelId from Workspace.focusPanel * Fix omnibar hang, WebView white flash, drag-over-browser, and idle CPU spin - Omnibar: first click selects all without entering NSTextView tracking loop; subsequent clicks have 3s synthetic mouseUp safety net to prevent hang - WebView: set underPageBackgroundColor to match window so new browsers don't flash white before content loads - Drag/drop: register custom UTType (com.splittabbar.tabtransfer) in Info.plist so WKWebView doesn't intercept tab drags; override registerForDraggedTypes on CmuxWebView as belt-and-suspenders - CPU: fix infinite makeFirstResponder loop in controlTextDidEndEditing by checking both the text field and its field editor (the actual first responder)
174 lines
5.8 KiB
Markdown
174 lines
5.8 KiB
Markdown
# cmux agent notes
|
|
|
|
## Initial setup
|
|
|
|
Run the setup script to initialize submodules and build GhosttyKit:
|
|
|
|
```bash
|
|
./scripts/setup.sh
|
|
```
|
|
|
|
## Local dev
|
|
|
|
After making code changes, always run the reload script with a tag to launch the Debug app:
|
|
|
|
```bash
|
|
./scripts/reload.sh --tag fix-zsh-autosuggestions
|
|
```
|
|
|
|
After making code changes, always run the build:
|
|
|
|
```bash
|
|
xcodebuild -project GhosttyTabs.xcodeproj -scheme cmux -configuration Debug -destination 'platform=macOS' build
|
|
```
|
|
|
|
When rebuilding GhosttyKit.xcframework, always use Release optimizations:
|
|
|
|
```bash
|
|
cd ghostty && zig build -Demit-xcframework=true -Doptimize=ReleaseFast
|
|
```
|
|
|
|
When rebuilding cmuxd for release/bundling, always use ReleaseFast:
|
|
|
|
```bash
|
|
cd cmuxd && zig build -Doptimize=ReleaseFast
|
|
```
|
|
|
|
`reload` = kill and launch the Debug app only (tag required):
|
|
|
|
```bash
|
|
./scripts/reload.sh --tag <tag>
|
|
```
|
|
|
|
`reloadp` = kill and launch the Release app:
|
|
|
|
```bash
|
|
./scripts/reloadp.sh
|
|
```
|
|
|
|
`reloads` = kill and launch the Release app as "cmux STAGING" (isolated from production cmux):
|
|
|
|
```bash
|
|
./scripts/reloads.sh
|
|
```
|
|
|
|
`reload2` = reload both Debug and Release (tag required for Debug reload):
|
|
|
|
```bash
|
|
./scripts/reload2.sh --tag <tag>
|
|
```
|
|
|
|
For parallel/isolated builds (e.g., testing a feature alongside the main app), use `--tag` with a short descriptive name:
|
|
|
|
```bash
|
|
./scripts/reload.sh --tag fix-blur-effect
|
|
```
|
|
|
|
This creates an isolated app with its own name, bundle ID, socket, and derived data path so it runs side-by-side with the main app. Important: use a non-`/tmp` derived data path if you need xcframework resolution (the script handles this automatically).
|
|
|
|
Before launching a new tagged run, clean up any older tags you started in this session (quit old tagged app + remove its `/tmp` socket/derived data).
|
|
|
|
## Debug event log
|
|
|
|
All debug events (keys, mouse, focus, splits, tabs) go to a single unified log in DEBUG builds:
|
|
|
|
```bash
|
|
tail -f /tmp/cmux-debug.log
|
|
```
|
|
|
|
- Implementation: `vendor/bonsplit/Sources/Bonsplit/Public/DebugEventLog.swift`
|
|
- Free function `dlog("message")` — logs with timestamp and appends to file in real time
|
|
- Entire file is `#if DEBUG`; all call sites must be wrapped in `#if DEBUG` / `#endif`
|
|
- 500-entry ring buffer; `DebugEventLog.shared.dump()` writes full buffer to file
|
|
- Key events logged in `AppDelegate.swift` (monitor, performKeyEquivalent)
|
|
- Mouse/UI events logged inline in views (ContentView, BrowserPanelView, etc.)
|
|
- Focus events: `focus.panel`, `focus.bonsplit`, `focus.firstResponder`, `focus.moveFocus`
|
|
- Bonsplit events: `tab.select`, `tab.close`, `tab.dragStart`, `tab.drop`, `pane.focus`, `pane.drop`, `divider.dragStart`
|
|
|
|
## Pitfalls
|
|
|
|
- Do not add an app-level display link or manual `ghostty_surface_draw` loop; rely on Ghostty wakeups/renderer to avoid typing lag.
|
|
|
|
## E2E mac UI tests
|
|
|
|
Run UI tests on the UTM macOS VM (never on the host machine). Always run e2e UI tests via `ssh cmux-vm`:
|
|
|
|
```bash
|
|
ssh cmux-vm 'cd /Users/cmux/GhosttyTabs && xcodebuild -project GhosttyTabs.xcodeproj -scheme cmux -configuration Debug -destination "platform=macOS" -only-testing:GhosttyTabsUITests/UpdatePillUITests test'
|
|
```
|
|
|
|
## Basic tests
|
|
|
|
Run basic automated tests on the UTM macOS VM (never on the host machine):
|
|
|
|
```bash
|
|
ssh cmux-vm 'cd /Users/cmux/GhosttyTabs && xcodebuild -project GhosttyTabs.xcodeproj -scheme cmux -configuration Debug -destination "platform=macOS" build && pkill -x "cmux DEV" || true && APP=$(find /Users/cmux/Library/Developer/Xcode/DerivedData -path "*/Build/Products/Debug/cmux DEV.app" -print -quit) && open "$APP" && for i in {1..20}; do [ -S /tmp/cmux.sock ] && break; sleep 0.5; done && python3 tests/test_update_timing.py && python3 tests/test_signals_auto.py && python3 tests/test_ctrl_socket.py && python3 tests/test_notifications.py'
|
|
```
|
|
|
|
## Ghostty submodule workflow
|
|
|
|
Ghostty changes must be committed in the `ghostty` submodule and pushed to the `manaflow-ai/ghostty` fork.
|
|
Keep `docs/ghostty-fork.md` up to date with any fork changes and conflict notes.
|
|
|
|
```bash
|
|
cd ghostty
|
|
git remote -v # origin = upstream, manaflow = fork
|
|
git checkout -b <branch>
|
|
git add <files>
|
|
git commit -m "..."
|
|
git push manaflow <branch>
|
|
```
|
|
|
|
To keep the fork up to date with upstream:
|
|
|
|
```bash
|
|
cd ghostty
|
|
git fetch origin
|
|
git checkout main
|
|
git merge origin/main
|
|
git push manaflow main
|
|
```
|
|
|
|
Then update the parent repo with the new submodule SHA:
|
|
|
|
```bash
|
|
cd ..
|
|
git add ghostty
|
|
git commit -m "Update ghostty submodule"
|
|
```
|
|
|
|
## Release
|
|
|
|
Use the `/release` command to prepare a new release. This will:
|
|
1. Determine the new version (bumps minor by default)
|
|
2. Gather commits since the last tag and update the changelog
|
|
3. Update `CHANGELOG.md` and `docs-site/content/docs/changelog.mdx`
|
|
4. Run `./scripts/bump-version.sh` to update both versions
|
|
5. Commit, tag, and push
|
|
|
|
Version bumping:
|
|
|
|
```bash
|
|
./scripts/bump-version.sh # bump minor (1.15.0 → 1.16.0)
|
|
./scripts/bump-version.sh patch # bump patch (1.15.0 → 1.15.1)
|
|
./scripts/bump-version.sh major # bump major (1.15.0 → 2.0.0)
|
|
./scripts/bump-version.sh 2.0.0 # set specific version
|
|
```
|
|
|
|
This updates both `MARKETING_VERSION` and `CURRENT_PROJECT_VERSION` (build number). The build number is auto-incremented and is required for Sparkle auto-update to work.
|
|
|
|
Manual release steps (if not using the command):
|
|
|
|
```bash
|
|
git tag vX.Y.Z
|
|
git push origin vX.Y.Z
|
|
gh run watch --repo manaflow-ai/cmux
|
|
```
|
|
|
|
Notes:
|
|
- Requires GitHub secrets: `APPLE_CERTIFICATE_BASE64`, `APPLE_CERTIFICATE_PASSWORD`,
|
|
`APPLE_SIGNING_IDENTITY`, `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID`.
|
|
- The release asset is `cmux-macos.dmg` attached to the tag.
|
|
- README download button points to `releases/latest/download/cmux-macos.dmg`.
|
|
- Versioning: bump the minor version for updates unless explicitly asked otherwise.
|
|
- Changelog: always update both `CHANGELOG.md` and the docs-site version.
|