Skip to content
Swift

Say what connecting does before anyone connects.

Andy Gao86f7fa5a7bcc
diff --git a/DESIGN-SYSTEM.md b/DESIGN-SYSTEM.md
index f917548..44edd8c 100644
--- a/DESIGN-SYSTEM.md
+++ b/DESIGN-SYSTEM.md
@@ -35,7 +35,7 @@ Never show or describe tapping the back of the case, holding the open case uprig
| Surface | Purpose | Size |
|---|---|---|
-| Setup assistant | First run: Allow → Connect → Calibrate → Tap. Permission comes first because the mouse is out of reach once the case is in hand: from then on each finished step leads to the next by itself, and the dots start on their own. Tap is the last step: it starts listening by itself, fills three dots as the person taps the front of the case, and can be skipped; once learned, its primary is Finish, with the fn ⌃ footer. Settings reaches the same step with Teach Tap…. One step per screen, a step indicator on top, a primary button bottom-right (Return). Connect walks through Connect → open the lid → Lid Closed (Return) → turn upright → "You’re connected", with the matching `CaseStepView`. Setup always connects the closed case; the dots wait for the Calibrate step. | 560 × 620 window |
+| Setup assistant | First run: Allow → Connect → Calibrate → Tap. Permission comes first because the mouse is out of reach once the case is in hand: from then on each finished step leads to the next by itself, and the dots start on their own. Tap is the last step: it starts listening by itself, fills three dots as the person taps the front of the case, and can be skipped; once learned, its primary is Finish, with the fn ⌃ footer. Settings reaches the same step with Teach Tap…. One step per screen, a step indicator on top, a primary button bottom-right (Return). Connect walks through Connect → open the lid → Lid Closed (Return) → turn upright → "You’re connected", with the matching `CaseStepView`. Before the first press, Connect says what a session does to the AirPods and the case, and a problem shows above that note instead of replacing it. Setup always connects the closed case; the dots wait for the Calibrate step. | 560 × 620 window |
| Calibration overlay | Full-screen dark overlay. Three dots: center, right edge, top edge. Each captures when the person holds still on it. Esc cancels. With saved edges it is one dot ("AirPointer · Recentering", no step row); if the case is held differently from last time, it carries on to the two edges. | Full screen of the controlled display |
| Main window ("Remote") | Two pages, **Pointer** and **Settings**, and no section tabs: the toolbar is only the gear. Settings opens with a "‹ Pointer" back button; esc and ⌘1 also go back. Pages scroll; a notice bar sits above them. | 440 × 700, min 400 × 620, max width 560 |
| Menu-bar popover | Live aim pad, Recenter, Pause, speed, then menu rows: Open AirPointer, Calibrate…, Disconnect (only while the closed case is connected), Settings…, Quit. | 320 wide |
diff --git a/HomeChecks.swift b/HomeChecks.swift
index 84d3dc3..665bf85 100644
--- a/HomeChecks.swift
+++ b/HomeChecks.swift
@@ -201,7 +201,11 @@ func runHomeChecks()throws {
try require(SetupAssistant.following(0,from:allowed,to:allowed)==nil && SetupAssistant.following(1,from:linked,to:linked)==nil && SetupAssistant.following(2,from:aimed,to:aimed)==nil && SetupAssistant.following(3,from:linked,to:aimed)==nil,"Coming back to a finished step shouldn’t move on by itself")
var finished=0,listening=0,stoppedListening=0,choosing=0
assistant.onFinish={finished+=1};assistant.onLearnTap={listening+=1};assistant.onStopLearningTap={stoppedListening+=1};assistant.onChooseAirPods={choosing+=1}
- assistant.go(to:1);assistant.update(SetupState(link:.idle,problem:ClosedCaseAirPods.Choice.several.failure,accessibilityTrusted:true))
+ func setupSays(_ words:String)->Bool{setupViews().contains{($0 as? NSTextField)?.stringValue.contains(words)==true}}
+ assistant.go(to:1);assistant.update(SetupState(link:.idle,accessibilityTrusted:true))
+ try require(setupSays("diagnostic data") && setupSays("during a call"),"Setup should say what connecting does before anyone connects")
+ assistant.update(SetupState(link:.idle,problem:ClosedCaseAirPods.Choice.several.failure,accessibilityTrusted:true))
+ try require(setupSays("diagnostic data") && setupSays("Choose which to use"),"A problem shouldn’t hide what connecting does")
let choose=setupViews().compactMap{$0 as? RemoteButton}.first{$0.style == .primary}
try require(choose?.title=="Choose AirPods…","Several pairs should offer a choice right in setup")
choose?.performClick(nil)
@@ -305,6 +309,7 @@ func runHomeChecks()throws {
try windowSnapshot("accessibility-guide",AccessibilityGuide.previewWindow(),.aqua)
try windowSnapshot("accessibility-guide-dark",AccessibilityGuide.previewWindow(),.darkAqua)
setup.go(to:1);try windowSnapshot("setup-connect",setup.window,.aqua)
+ setup.update(SetupState(link:.idle,problem:ClosedCaseAirPods.helperFailure(30,stopping:false)));try windowSnapshot("setup-connect-problem",setup.window,.aqua)
setup.update(SetupState(link:.closeLid));try windowSnapshot("setup-close-lid",setup.window,.darkAqua)
setup.update(SetupState(link:.turnUpright));try windowSnapshot("setup-turn",setup.window,.aqua)
setup.update(SetupState(link:.holdStill,holdProgress:0.62));try windowSnapshot("setup-hold-still",setup.window,.aqua)
diff --git a/README.md b/README.md
index e50e1a5..e006b81 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,14 @@ uses private Apple protocols, so a macOS or AirPods update can stop it working.
| macOS 14 and 15 | Allowed, not tested |
| Xcode | Required to build |
+Normal connect and disconnect have run many times on that Mac and pair. These
+cases have not been tested on purpose:
+
+- Force quit during a session
+- Sleep and wake during a session
+- Bluetooth lost during a session
+- Calls and audio during and after a session
+
## Build and run
```sh
diff --git a/SetupAssistant.swift b/SetupAssistant.swift
index e252d71..14ace74 100644
--- a/SetupAssistant.swift
+++ b/SetupAssistant.swift
@@ -35,6 +35,7 @@ final class SetupAssistant:NSObject,NSWindowDelegate {
("Show it where your screen is","Point at three dots — center, right edge, top edge. Hold still on each and it captures automatically. Keep the grip you’ll use."),
("Teach it your tap","Tap the front of the case three times, with a short pause between taps. Hold it the way you’ll point with it."),
]
+ private static let connectEffects="Your Mac can’t use your AirPods for audio while connected, so don’t connect during a call. Ending a session uses up diagnostic data on the case and changes some AirPods settings. These changes may last."
private var state=SetupState()
private var everConnected=false
private var helpDue=false
@@ -221,9 +222,11 @@ final class SetupAssistant:NSObject,NSWindowDelegate {
copy=linkCopy(s.link)
switch s.link {
case .idle:
- caseArt.step = .closed;main=("Connect",.connect);noteText=s.problem
+ caseArt.step = .closed;main=("Connect",.connect);var problem=s.problem
// Setup has no Settings to send them to, so the choice comes from here.
- if s.problem==ClosedCaseAirPods.Choice.several.failure{main=("Choose AirPods…",.chooseAirPods);noteText="More than one pair of AirPods Pro is paired with this Mac. Choose which to use."}
+ if s.problem==ClosedCaseAirPods.Choice.several.failure{main=("Choose AirPods…",.chooseAirPods);problem="More than one pair of AirPods Pro is paired with this Mac. Choose which to use."}
+ // A problem doesn't replace the effects: the person hasn't connected yet.
+ noteText=[problem,Self.connectEffects].compactMap{$0}.joined(separator:"\n\n")
case .openLid:caseArt.step = .opening;chipText="Waiting for the lid";main=("Connecting…",.none)
case .connecting:
caseArt.step = .open;chipText="Looking for your AirPods…";main=("Connecting…",.none)