adds quick question UI for mac catalyst target

2026-08-21 17:28:08 -07:00
parent eb2b0d3ca0
commit 5f9fc82b86
20 changed files with 2015 additions and 2 deletions
@@ -0,0 +1,76 @@
+# Sybil for iOS and Mac Catalyst
+
+Run `just run` for the iPhone simulator, or `just run-mac` for Mac Catalyst.
+`just build-mac` builds without launching the Mac app. Both regenerate the Xcode
+project from `project.yml`. The Mac recipes use ad-hoc signing for local development;
+release/archive signing settings are unchanged.
+
+## Quick Question on macOS
+
+While the Catalyst app is running, **Option+Space** toggles a floating Quick
+Question panel, including over other applications. The prompt is focused as soon
+as it opens, with any existing prompt selected so typing replaces it. The same
+select-on-open behavior applies to Quick Question on iPhone and iPad.
+**Return** submits; **Shift+Return** inserts a new line. **Escape**, a
+second **Option+Space**, the close button, or clicking outside dismisses it.
+Hiding the panel preserves the draft and answer and lets an in-flight answer finish.
+**Open in Chat** saves the question and answer in the regular workspace.
+
+The regular Mac chat/search composer uses the same Return/Shift+Return rules.
+Holding Return does not repeatedly submit. The iOS software keyboard is unchanged.
+
+Closing the last Mac window leaves Sybil running, so Option+Space still works.
+Use **Sybil → Quit Sybil** or **Command+Q** to quit the application. The Catalyst
+build opts out of automatic termination, and the native shortcut service holds a
+matching automatic-termination activity until it stops. No hidden keep-alive
+window or sleep-preventing activity is used. Mac scene support also allows the
+workspace to reopen after its last window is closed.
+
+When Catalyst is backgrounded, opening Quick Question first requests app
+activation and waits for UIKit to enter the foreground before creating or ordering
+the native panel. Presentation is deferred out of the hotkey event callback.
+Pressing Option+Space again cancels a pending presentation. Dismissing a panel
+that required activation returns focus to the previous app; explicitly opening
+the workspace keeps focus in Sybil.
+
+On Mac, **Command+N** starts a new chat in the focused workspace, or opens a new
+workspace window when none are open. **Command+Shift+N** always opens a new window,
+including while signed out. **Command+Option+N** starts a new search; iOS retains
+its existing Command+Shift+N search shortcut.
+
+The shortcut is also shown under **File → Quick Question**. If another application
+already owns Option+Space, the panel reports that the shortcut is unavailable;
+the menu item can still be clicked. No Accessibility or Input Monitoring grant is
+needed for the registered hotkey.
+
+The native AppKit panel and Carbon hotkey live in `Apps/SybilMacQuickQuestion`,
+a macOS bundle embedded only for the Mac Catalyst destination. Catalyst loads it
+through the Foundation-only `SybilMacQuickQuestionBridge` contract. Requests,
+provider/model preferences, streaming, and conversion to chat remain in the
+existing `SybilViewModel`; there is no separate backend or API contract. The panel
+uses AppKit controls rather than trying to load the macOS SwiftUI runtime into a
+Catalyst process.
+
+The iPhone/iPad app keeps its existing Quick Question sheet and Home Screen quick
+action, and does not build or embed the macOS helper.
+
+## Verification
+
+- `just test`: existing Swift package tests on the iPhone simulator.
+- From `Packages/Sybil`, run `xcodebuild test -scheme Sybil -destination 'platform=macOS,variant=Mac Catalyst' -parallel-testing-enabled NO` for package tests including the Catalyst panel controller.
+- For a manual Mac check, open the panel from another app, type immediately,
+  submit, hide/reopen during streaming, and verify Escape/outside-click dismissal
+  returns input to the previous app. Check a second display and a full-screen Space
+  when available.
+- Close every Mac window, invoke Option+Space, and verify the saved question and
+  answer remain available. Reopen the workspace from the panel, then explicitly
+  quit with Command+Q. Rebuild and relaunch after changing lifecycle plist keys.
+- In both Mac and iOS Quick Question, reopen an existing prompt and type to replace
+  it. In the Mac workspace, verify Return submits and Shift+Return adds a newline.
+- Check Command+N both with a workspace open and after closing every workspace.
+  Command+Shift+N must open another window even when one already exists, and
+  Command+Option+N must start a search without opening a window.
+- With all workspace windows closed, switch to another app and repeatedly open
+  and dismiss Quick Question, including two quick Option+Space presses while it
+  is opening. Check that no late panel appears after cancellation and that no
+  `UINSAppLifecycleStateRunningNoOpenWindows` assertion occurs.