Skip to content

Use the maintainer's wording for the approval card footer and drop the Esc hint - #359

Merged
sudoHG merged 3 commits into
mainfrom
sudoHG/mac-card-footer-wording-356
Nov 16, 2026
Merged

sudoHG merged 3 commits into
mainfrom
sudoHG/mac-card-footer-wording-356

Conversation

@sudoHG

@sudoHG sudoHG commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Closes #356

Summary

The Mac approval panel's footer shows only its sentence, in the maintainer's wording: "This request will be sent to iPhone in 18 s" / 「18 秒后将把审批请求发到 iPhone」 while an eligible request waits for its send, and "This request expires in 4:39" / 「审批请求将于 4:39 后失效」 after the send and in every other case ("4:59" without an approver). The countdown and when each form applies are unchanged (RemoteApprovalFooterHint and the coordinator are untouched).

"Esc to decide later" is gone from the panel; Esc still decides later. The panel is now AgentApprovalPanel (an NSPanel subclass from the existing factory), which takes Esc in sendEvent(_:) and calls the card's finish(nil). VoiceOver gets a named "Decide Later" / 「稍后处理」 action on the footer.

How Esc is wired

  • The panel is a non-activating NSPanel hosting the card in an NSHostingController. AppKit hands every key event for a window to that window's sendEvent(_:), whichever view is first responder, so the panel matches Esc there (keyCode 53, without Command, Control, Option or Shift, as .cancelAction matched it) and calls cancel. makeFrozenApprovalPanel sets cancel to hosting.rootView.prompt.finish(nil) through a weak reference to the hosting controller. That is the same decide-later path the old button used, so the request stays pending. The old SwiftUI .keyboardShortcut(.cancelAction) was a key equivalent on a visible control, and removing the control would have removed the shortcut with it.
  • Holding Esc decides once: the key approval panel swallows Esc repeats, so they never decide the next queued request (each decide-later shows and focuses the next panel at once).
  • cancelOperation(_:) is overridden to do the same, so Command-period, or any cancel sent up the responder chain, decides later instead of reaching NSPanel's default. This is intended: Esc with a modifier (for example Command-Esc) is not taken in sendEvent(_:) and goes on to AppKit, which in an active app may turn it into cancelOperation:. It then decides later as well, the standard macOS cancel behavior. CI's first run showed exactly this.
  • Why not the responder chain alone: in probes on the offscreen panel, Esc sent with sendEvent/keyDown was never turned into cancelOperation:, even with isKeyWindow forced to true. Relying on that path could not be proven without showing a window. A cancelOperation: sent from the hosting view (tryToPerform, interpretKeyEvents) does reach the panel, so SwiftUI does not swallow it.
  • testEscInThePanelDecidesLater builds the production panel and sends a synthetic Esc keyDown to it twice, first with the panel and then with the card's hosting view as first responder. Each Esc decides later. "a" doesn't decide; the panel's filter (AgentApprovalPanel.isEscape) rejects Esc with Command, Control, Option or Shift; and a cancelOperation: from the hosting view decides later. Modified Esc is checked through the filter rather than sent, because AppKit turns it into cancelOperation: only while the app is active (true on the CI runner, not locally), which then decides later by design. A repeated Esc decides nothing more. End to end, ScreenshotE2ETests.testPendingRequestsAndAccessRecords presses Esc in the real panel, asserts that the panel closes, and then expects the request in Pending requests (CI's screenshot step).

Renders

CI artifact askkey-remote-approval-renders, production panel, both languages:

  • 17-{en,zh}-panel-footer-send-in-18s (before the send, about 18 s; was …-iphone-in-18s)
  • 18-{en,zh}-panel-footer-after-send (after the send, 4:39; was …-also-on-iphone)
  • 19-{en,zh}-panel-footer-no-approver (4:59)

Renders 11 and 12 (Details, footer in the sent state) also show the new wording. The total stays 36 PNGs.

Diff stat

 Sources/AskKeyAppKit/AgentApprovalPanelFactory.swift      |  30 +++-
 Sources/AskKeyAppKit/App/AppDelegate+Approval.swift       |   3 +
 Sources/AskKeyAppKit/App/FrozenAgentApprovalPrompt.swift  |  34 ++---
 Sources/AskKeyAppKit/App/RemoteApprovalPanelState.swift   |  37 ++---
 Sources/AskKeyAppKit/Resources/Localizable.xcstrings      |  24 +--
 Tests/AskKeyAppTests/ApprovalPromptContentTests.swift     |   5 +-
 Tests/AskKeyAppTests/RemoteApprovalFooterHintTests.swift  |   6 +-
 Tests/AskKeyAppTests/RemoteApprovalFooterTests.swift      | 165 +++++++++++-----
 Tests/AskKeyAppTests/RemoteApprovalRenderTests.swift      |  19 ++-
 Tests/AskKeyE2ETests/ScreenshotE2ETests.swift             |   9 +-
 docs/adr/0014-remote-approval.md                          |   8 +-
 11 files changed, 225 insertions(+), 115 deletions(-)

Tests

  • swift build: passed.
  • swift test --filter AskKeyAppTests: 856 executed, 1 skipped (ManagementWindowSizingTests.testVisibleWindowLifecycleKeepsTheDesignedFrameOnCI, CI-only), 0 failed. +3 tests versus main (853 by count): testTheFooterDropsTheEscHintAndLeavesTheSharedExpiryWording, testEscInThePanelDecidesLater, testVoiceOverOffersDecideLaterOnTheFooter. The panel-layout test now checks that the top edge stays for all three forms and that every Chinese form is one line.
  • The full suite and the desktop flows run in CI.

Checks

  • python3 scripts/check_hygiene.py: passed (all counts 0).
  • python3 scripts/check_module_deps.py: passed.
  • Catalog: new keys This request will be sent to iPhone in %lld s, This request expires in %@ and Decide Later (en, zh-Hans, qps-ploc). Removed keys left unused: iPhone can decide in %lld s, Also on iPhone · Expires in %@ and Esc to decide later. Expires in %@ is unchanged.

Deviations and questions

  • Two files outside the issue's "May change" list: Sources/AskKeyAppKit/AgentApprovalPanelFactory.swift (the AgentApprovalPanel subclass) and Sources/AskKeyAppKit/App/AppDelegate+Approval.swift (three lines that connect cancel in makeFrozenApprovalPanel). Without a control on the card, Esc has to be caught by the window. The dispatch asked for a mechanism that fits the panel's real window type rather than a hidden control.
  • How VoiceOver is verified: SwiftUI builds no accessibility tree for a panel that is never shown. Even with the enhanced-UI flag, only the NSScrollView-backed nodes appear. The unit test therefore checks the localized action name and the footer's wiring in the source. The screenshot flow finds the approval-footer element in the real panel.
  • After the send the footer reads the same as without an approver ("This request expires in …"), as the issue's table specifies. .sent stays a separate state, so the state logic is unchanged.
  • ADR 0014: the same strings also appear in the Mac App → Approval panel paragraph (line 242), which is updated with the amendment's Mac card hint section. "What the footer follows" loses its claim that the footer says the iPhone can decide.

…e Esc hint

The approval panel's footer now shows only its sentence, in the
maintainer's wording (#356): "This request will be sent to iPhone in
18 s" while an eligible request waits for its send, and "This request
expires in 4:59" otherwise, including after the send. When each form
applies, and the countdown, do not change. The footer has its own catalog
keys; "Expires in %@", shared with the pending-request list and the
pairing sheet, is untouched, and the keys left unused are removed.

"Esc to decide later" is gone from the panel. Esc still decides later:
the panel is now an AgentApprovalPanel, which takes Esc in sendEvent(_:),
where AppKit delivers every key event to the window whichever view is
first responder, and hands it to the card's decide-later path. A cancel
sent up the responder chain (Command-period) does the same. VoiceOver
keeps a way to decide later through a "Decide Later" action on the
footer, in both languages.

Tests cover the strings in both languages, Esc in the production panel
with either first responder, and the footer's VoiceOver action. Renders
17-19 show the new footer; ADR 0014's footer strings and the Why that no
longer fit are updated.
The Esc test sent Command-Esc through the panel and expected no
decision. The panel passes Esc with a modifier on to AppKit, which turns
it into cancelOperation(_:) only while the app is active: on the CI
runner it is, so the cancel reached the panel and decided later, as that
path is meant to. The test now checks that other keys never decide and
that the panel's filter rejects Esc with each modifier, which holds
whether or not the test process is active.
- A held Esc decides once: the key approval panel swallows Esc repeats,
  so they never decide the next queued request. The Esc test covers a
  repeated Esc.
- The screenshot flow asserts that Esc closes the real panel, not only
  that the request stays pending.
- AgentApprovalPanel's doc no longer says Command-period always decides
  later: AppKit sends a responder-chain cancel only while the app is
  active, which is why the non-activating panel takes Esc in sendEvent.
- Test names and messages that still said "Also on iPhone" or
  "unchanged", and ADR 0014's #350 task entry, are reworded.
@luoji-bot

luoji-bot Bot commented Nov 16, 2026

Copy link
Copy Markdown

Cross adversarial review (#356)

GPT-6 Astra xhigh and Opus 5.5 xhigh reviewed head 57c735b read-only, two rounds each. In round 2 each reviewer ruled on the other's report. Neither found a P0 or P1, and neither found a new defect in round 2.

Fixed in 71f4720

  1. P2, both reviewers: no test failed if Esc stopped closing the real panel. testPendingRequestsAndAccessRecords pressed Esc and only checked that the request was still pending, which also holds if Esc does nothing. It now also asserts that the panel disappears (approval-deny waitForNonExistence).
  2. P3, Opus: holding Esc deferred every queued request. Each decide-later shows and focuses the next panel, so key repeats kept deciding later. AgentApprovalPanel.sendEvent now decides on the first Esc and swallows the repeats, so they never decide the next request. The test covers a repeated Esc. Checking isARepeat in the filter alone would have passed repeats on to AppKit, which may turn them into cancelOperation:, as Astra noted in round 2.
  3. P3, both reviewers: stale wording. Six test names and two assertion messages still said "Also on iPhone" or "unchanged". The ADR 0014 Tell the Mac approval card when an unanswered request goes to the iPhone #350 task entry also said "unchanged" and now notes that Use the maintainer's wording for the Mac approval card footer and drop the Esc hint #356 replaced the wording.
  4. P3, Opus round 2: an inaccurate comment. The AgentApprovalPanel doc said Command-period decides later in all cases. It now says a responder-chain cancel decides later; AppKit sends one only while the app is active. The panel is non-activating, which is why Esc is taken in sendEvent rather than left to AppKit.
  5. Nits. The Chinese one-line check now explains why equal heights mean one line: the expiry form is far narrower than the card. A header comment in the render test is reflowed.

Declined

  • Esc and the VoiceOver action stay live during "Approved on / Denied on". Opus withdrew this in round 2: the old footer button and its accessibility action behaved the same, and finish(nil) decides nothing for a request that already left pending.
  • Runtime VoiceOver check (approval-footer's action names in the E2E). XCUITest has no API for custom accessibility actions. Calling the AX C API from the UI-test runner depends on accessibility trust that the CI runner may not grant. SwiftUI builds no accessibility tree for a panel that is never shown, so a unit test can't do it either. The unit test checks the localized name and the footer's wiring; the screenshot flow finds the footer element in the real panel.
  • Matching Command-period in sendEvent. The issue asks only for Esc. Whether the old .cancelAction shortcut caught Command-period while the app was inactive is unknown, so it is left as is.
  • Covering Full Keyboard Access focus and Details text selection in the E2E. The override runs before AppKit dispatches to any first responder. The unit test covers the panel and the hosting view as first responder.

Not verified

  • Esc with the panel key over another app (Ask Key inactive) on a real desktop. The local unit test runs in an inactive process and Esc via sendEvent decides later there, but a real desktop run was not done here.

Renders at 71f4720

CI run 43803709873, artifact askkey-remote-approval-renders (36 PNGs), the production panel:

  • 17-en-panel-footer-send-in-18s.png, 17-zh-panel-footer-send-in-18s.png: before the send, about 18 s
  • 18-en-panel-footer-after-send.png, 18-zh-panel-footer-after-send.png: after the send, 4:39
  • 19-en-panel-footer-no-approver.png, 19-zh-panel-footer-no-approver.png: no approver, 4:59

Every footer shows only its sentence, with no Esc hint, and fits on one line in both languages. The buttons are where they were.

CI at 71f4720

All four jobs are green: build-and-test ran 2178 tests, 3 skipped, 0 failed; basic-ui-flows passed the 18 required flows and the screenshot step, including the Esc-closes-the-panel assertion; ios-app and release-sdk-window-check passed.

@sudoHG
sudoHG merged commit ccf751f into main Nov 16, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Use the maintainer's wording for the Mac approval card footer and drop the Esc hint

1 participant